Tailscale GPU Nodes

Yokai can discover online peers from your tailnet and use their Tailscale DNS name or IP for SSH. Applying tag:ai-gpu makes dedicated compute servers easy to recognize: Yokai sorts them first and displays an AI GPU badge in the Tailscale device picker.

The tag is recommended, not required. An online Tailscale peer can still be imported without it.

Use this tag only on dedicated server nodes. In Tailscale, a device has either a user identity or a tag-based identity, not both. Applying a tag to a user-authenticated device removes the associated user identity. Do not add tag:ai-gpu to a personal laptop, phone, or other end-user device. See Tailscale’s tag identity guidance.

1. Define the tag

Open Access controls in the Tailscale admin console and add tag:ai-gpu to the tagOwners section of your tailnet policy. Replace you@example.com with the operator who is allowed to apply the tag:

{
  "tagOwners": {
    "tag:ai-gpu": ["you@example.com"]
  }
}

Merge this block into your existing policy rather than replacing the whole file. Tag owners may also be Tailscale groups or other tags. Tailnet Owners, Admins, and Network admins can apply defined tags even when they are not listed as tag owners.

For details, see Define a tag and its owners.

2. Apply the tag

Choose either the admin console or CLI workflow.

Admin console

1. Open Machines in the Tailscale admin console.
2. Find the dedicated GPU server.
3. Open the … menu and select Edit tags.
4. Add tag:ai-gpu and save.

The tag must already exist in tagOwners. You must be a tailnet Owner, Admin, or Network admin to apply tags from the admin console. See Apply a tag in the admin console.

CLI

On a new or signed-out GPU server, authenticate it with the tag:

sudo tailscale login --advertise-tags=tag:ai-gpu

If the server is already authenticated, re-authenticate it with the current user and advertise the tag:

sudo tailscale up --advertise-tags=tag:ai-gpu --force-reauth

Re-authentication creates a new node key but preserves the device’s Tailscale IP. Follow the browser authorization prompt if one appears. See Apply a tag with the Tailscale CLI.

3. Grant access

tag:ai-gpu identifies a compute node; it does not grant network or SSH access. Keep access limited to the operators who need it.

The following example allows one operator to reach SSH on tagged GPU servers. Replace the email address with the operator’s Tailscale identity, then merge the grant into your existing policy:

{
  "grants": [
    {
      "src": ["you@example.com"],
      "dst": ["tag:ai-gpu"],
      "ip": ["tcp:22"]
    }
  ]
}

This network grant is enough for Yokai when the server runs normal OpenSSH and the operator already has a working SSH key or agent credential. Yokai reaches the remote agent through an SSH tunnel, so you normally do not need to expose port 7474 across the tailnet.

Tailscale recommends grants for most new access-control rules. Review the grants documentation before adapting this example to a group or broader fleet.

Optional: use Tailscale SSH

Yokai can also connect through Tailscale SSH. Enable it on a supported GPU server:

sudo tailscale set --ssh

Then add an SSH policy rule in addition to the network grant. Replace ubuntu with the exact local account Yokai should use:

{
  "ssh": [
    {
      "action": "check",
      "src": ["you@example.com"],
      "dst": ["tag:ai-gpu"],
      "users": ["ubuntu"]
    }
  ]
}

Tailscale SSH requires both network access and an SSH rule. check asks the operator to periodically re-authenticate. Use explicit local usernames for tagged destinations; a broad non-root selector can grant access to more host accounts than intended.

The Tailscale SSH server is supported on Linux and on the open-source tailscale + tailscaled macOS variant. Yokai does not require Tailscale SSH, so use normal OpenSSH over the tailnet when it is a better fit. See Configure Tailscale SSH.

4. Verify the node in Yokai

First confirm from the operator machine that the GPU server is online and advertises the tag:

tailscale status --json | jq \
  '.Peer[] | select((.Tags // []) | index("tag:ai-gpu")) | {HostName, Online, TailscaleIPs, Tags}'

If jq is not installed, confirm the server’s online state and tag in the Tailscale Machines page instead.

Then open Yokai:

1. press 2 for Devices;
2. press A and choose Tailscale;
3. press R to refresh if the picker was already open;
4. find the server at the top of the list with the AI GPU badge;
5. select it and press Enter to continue setup.

Yokai reads the local output of tailscale status --json. The operator machine must therefore have the Tailscale CLI installed, running, and signed in to the same tailnet.

Before bootstrapping, verify the exact SSH path Yokai will use:

ssh ubuntu@gpu-box

If you enabled Tailscale SSH, you can verify it directly instead:

tailscale ssh ubuntu@gpu-box

Replace ubuntu and gpu-box with the configured local user and the server’s MagicDNS name.

Troubleshooting

The tag is not available in Edit tags

Define tag:ai-gpu in tagOwners and save the tailnet policy first. Confirm that your account is allowed to apply it.

The CLI reports that the tag is invalid or unauthorized

Check spelling and case, then verify that your user, group, or authenticating tag owns tag:ai-gpu. Tailscale normalizes tag names to lowercase.

Yokai does not show the server

• Confirm the server is online in the Tailscale Machines page.
• Run tailscale status on the operator machine and confirm the server appears.
• In Yokai, reopen the Tailscale picker or press R to refresh.
• Confirm both machines are connected to the same tailnet.

The server appears without the AI GPU badge

Confirm the machine has the exact tag:ai-gpu tag in the Tailscale admin console, then refresh the Yokai picker. Other tags are displayed but do not trigger the badge.

The server appears, but SSH fails

The tag is not an access rule. Confirm the operator has network access to tag:ai-gpu on TCP port 22. For normal OpenSSH, also verify the local SSH account and key. For Tailscale SSH, confirm the destination has SSH advertised and that both the network grant and ssh policy permit the connection.

See Adding Devices for the rest of the Yokai bootstrap flow and Network Topology for port and tunnel details.