v1.22.52see what's new →

Devices

Register your machines once, then target any of them from any command with --host / --device — or point at a raw user@host, ad-hoc.

The model

A device is a registered machine — a name, a platform, an address, and how to authenticate. Register your fleet once and every command that talks to another machine takes the same flag: --host <name> (or its alias --device <name>). The flag also accepts a raw user@host, so you never have to register a box just to reach it once.

The registry self-populates from your Tailscale tailnet, so on a machine that already has Tailscale up, registering the whole fleet is one command.

Register once

agents devices sync            # ingest the tailnet (checkbox picker in a TTY)
agents devices list            # what's registered — platform, address, reachability
agents devices show mac-mini   # the full profile for one device

See registering devices for manual add, auth modes, and rendering an ssh_config.

Target with a flag

Once a device is registered, one flag reaches it from anywhere. The same flag takes a registered name or an ad-hoc user@host:

agents ssh mac-mini                              # open a shell on it
agents run claude "test" --device mac-mini       # run an agent there
agents run claude "test" --host [email protected]   # ad-hoc, no registration

Offload a run

Push a task onto a beefier machine and let it run there, streaming output back:

agents run --device mac-mini --remote-cwd ~/app "run the full test suite"
agents teams add fix claude "fix the flaky test" --host mac-mini

Full offload reference — --remote-cwd, --no-follow, and the advanced capability-tag pool — is in remote runs.

Let the fleet pick the machine

You rarely want to name a box. Mark what each machine is for, and --device auto picks the least-loaded one that qualifies:

agents devices role yosemite-m1 worker    # agents may run here
agents devices role laptop      personal  # never picked automatically

agents run --device auto "run the full test suite"
agents devices pick                       # just print the machine it would choose

Marking any device worker turns automatic placement into an allowlist — only marked workers are eligible, and a personal box is never chosen. One rule, honoured by run, teams, and ssh auto alike.

agents devices pick prints just the name on stdout, so a script can consume it: box="$(agents devices pick)". When nothing qualifies it fails and names every candidate with the reason it was excluded, rather than quietly falling back to your laptop.

Query across devices

agents sessions fans the same query out over SSH to each machine's own index — no shared store, SSH is the only auth:

agents sessions --active                                  # everything running, everywhere
agents sessions "webhook" --host mac-mini --host studio   # fan out across two machines
agents sessions resume <id> --host mac-mini               # resume a remote session in a tab

See sessions across devices.

Keep state in sync

Two ways to keep session history consistent across the fleet:

agents sessions sync   # CRDT union over R2 — merges transcripts, no conflicts
agents drive push      # rsync your sessions to a machine you control (beta)

Secrets across devices

Move credential bundles between machines without ever putting a plaintext value on the wire:

agents secrets push                              # encrypt + upload account-wide
agents secrets export stripe-prod --host mac-mini # land it as a native bundle on that box

See secrets across devices.

Advanced: agent-host pools

Beyond the device registry, agents hosts is an optional offload pool with capability tags — enroll machines by capability, then dispatch to any healthy host that matches (--host <cap> --any). Reach for it only when you want load-balanced fan-out across a pool rather than targeting one named machine. See remote runs.

Related