Adding Devices

Every managed machine has a config record, an authenticated Yokai agent, and a local daemon tunnel. The Devices route owns the full lifecycle.

Choose a source

Open Devices with 2, press A, and select one of the available sources.

SSH config

Yokai reads ~/.ssh/config through the daemon and normalizes each usable host alias. Hostname, user, port, and identity file are prefilled, including encrypted-key detection.

Use this path when SSH already works from your terminal:

ssh gpu-box-01

Tailscale

Yokai calls the local Tailscale CLI, reports whether the daemon is installed, running, or awaiting login, and lists peers with hostname, DNS name, IPs, OS, online state, and ACL tags.

Peers carrying tag:ai-gpu are highlighted as recommended. The tag is helpful, not mandatory.

For the complete setup—including tag ownership, Admin Console and CLI workflows, least-privilege access, and verification—see Tailscale GPU Nodes.

Manual

Enter a hostname or IP, SSH user, port, and optional key path. This is the right path for a host that does not appear in SSH config or Tailscale.

SSH authentication

Connection resolution supports normal SSH-key and agent workflows. If a configured key is encrypted, Yokai can use the running SSH agent or request the required credential in the setup flow.

The selected user must be able to:

• write the agent binary and service configuration;
• run Docker commands;
• inspect GPU and system state;
• create monitoring containers when monitoring is selected.

Bootstrap sequence

The bootstrap operation streams progress through the daemon:

1. connect over SSH;
2. check the OS, architecture, Docker, GPU runtime, disk, and ports;
3. generate a 64-character agent bearer token when needed;
4. copy the matching Yokai binary;
5. write the agent configuration and systemd unit;
6. start and verify yokai agent on port 7474;
7. open the local SSH tunnel;
8. optionally install Prometheus, Grafana, node_exporter, and dcgm-exporter.

Device operations

Action	Key	Result
Add	A	Open source picker and setup flow
Edit	E	Change connection and display details
Test	T	Test the selected device
Upgrade	U	Replace and restart the selected remote agent
Test all	Shift+T	Run a fleet-wide connectivity check
Upgrade all	Shift+U	Upgrade all configured remote agents
Remove	X	Remove device state and associated service records

CLI workflow

yokai devices add \
  --host 100.64.0.2 \
  --label "GPU box 01" \
  --ssh-user ubuntu \
  --ssh-key ~/.ssh/id_ed25519 \
  --type tailscale

yokai devices bootstrap 100.64.0.2
yokai devices test 100.64.0.2
yokai devices list

Troubleshooting onboarding

• Verify direct SSH first with the same user, port, and key.
• Verify docker info succeeds for that user.
• Verify the NVIDIA container runtime can run nvidia-smi inside a container.
• Check ~/.config/yokai/daemon.log for bootstrap or tunnel errors.
• If the host changed, edit it in Devices and test again before upgrading.

See Troubleshooting for command-level checks.