Distributed fleet execution

August 10, 2026

The usual speedup is not a smarter prompt — it is more machines running the same factory: prepare one box, register the fleet, install and sync harnesses everywhere, then spin up teams with --device / --devices. Command: agents (AGI CLI).

Pairs with teams as graph engineering (DAG / --after) and sessions index (query what already ran). Step-by-step install path also lives in QUICKSTART.md.

1. Prepare one machine

Start on the box you sit at (or any healthy anchor). Install the CLI, run setup, add at least one harness, prove a headless ping.

# Install AGI CLI (command remains "agents")
npm install -g @phnx-labs/agents-cli   # or: curl -fsSL agi-cli.sh | sh
agents --version

agents setup                    # system config, capability hub
agents setup status             # readiness: browser, secrets, fleet, …

agents add claude@latest
agents add codex@latest
agents run claude               # native login on first interactive run
agents run claude "Reply with exactly PONG" --mode plan
agents view                     # installed versions, accounts, usage
agents doctor                   # broader health + drift

Optional: secrets bundles (agents secrets), share (agents share setup), and an interactive host for artifacts you should see on your laptop.

2. Build the fleet

A fleet is your own machines over Tailscale/SSH that can run commands and host agents. Two related registries:

Devices — Tailscale nodes made addressable (agents devices, alias fleet).
Hosts — dispatch targets; every registered device is also a host; optional capability pools for --device auto-style placement.

agents setup fleet              # discover Tailscale + SSH access
agents devices sync             # TTY: checkbox picker of tailnet nodes
agents devices sync --yes       # non-interactive: register non-ignored nodes
agents devices list             # platform, address, reachability, headroom
agents devices list --refresh   # force live probe

# Optional: name the machine that should open browsers/plans for YOU
agents devices set-interactive zion

Manual machines (not on the tailnet): agents devices add studio [email protected]. Ignore phones/tablets you never run agents on: agents devices ignore ipad. Full register reference: docs/devices/register.

3. Connect and verify devices

Auth is SSH (key by default, or password via a secrets bundle). Prove each worker before you pile teams on it.

agents ssh yosemite-s0 hostname
agents ssh yosemite-s0 'agents --version'

# One flag everywhere: --device (alias --host)
agents run claude "Reply with exactly PONG" --mode plan --device yosemite-s0

# Who is online right now?
agents devices list --live
agents sessions --active          # running sessions across the fleet

Common failure: key not authorized on a laptop that sleeps behind a relay. Fix SSH once; unreachable devices are skipped by fan-out, not fatal. Prefer workers for long runs; keep the interactive laptop light.

4. Install and sync agents across the fleet

You can ssh and agents add on each box — or declare a profile and reconcile with agents apply (alias agents fleet apply / devices apply).

# Capture what this machine looks like into agents.yaml → fleet:
agents fleet capture              # names only — never credentials as values
agents fleet capture --dry-run

# Or hand-author fleet: in agents.yaml
# fleet:
#   devices: all
#   defaults:
#     agents: [claude@latest, codex@latest]
#     sync: [user]
#     login: sync

agents apply --plan               # device × dimension matrix; no changes
agents apply -y                   # install CLI/agents, sync config, push logins
agents apply --device yosemite-s0 # scope to one worker

Dimensions: agents-cli binary, harness installs, config scopes (sync: [user]), portable login propagation, optional --provision-secrets. DotAgents repos: agents repos push/pull and agents repos status --devices-all. Full matrix: docs/fleet.md.

5. Spin up distributed teams

Once workers answer agents --version, put the graph on them. Topology (--after) is separate from placement (--device / --devices).

agents teams doctor

# Local smoke first (optional)
agents teams create smoke-test
agents teams add smoke-test claude "Summarize README in 3 bullets" --name reader
agents teams start smoke-test --watch
agents teams disband smoke-test

# Distributed factory team
agents teams create ship \
  --devices yosemite-s0,yosemite-s1 \
  --repo [email protected]:org/app.git \
  --enable-worktrees \
  -d "Ship pricing end-to-end"

agents teams add ship claude "API" --name api --worktree api --device yosemite-s0
agents teams add ship claude "UI"  --name ui  --worktree ui  --device yosemite-s1
agents teams add ship claude "E2E" --name qa  --after api,ui --worktree qa
agents teams start ship --watch

agents teams status ship
agents teams message ship qa "Skip flaky snapshot; land the rest"

Unpinned teammates on a multi-device pool auto-schedule (reachable, not overloaded, agent installed, under cap). Pin with --device when a surface must sit on a specific box. Deep dive: teams as graph engineering · hands-on: parallel work with teams.

6. Observe: sessions, status, live

Distributed work only pays off if you can see it. Sessions fan out over SSH to each machine's own index — no shared memory bus.

agents sessions --active                    # live everywhere
agents sessions --teams                     # team-spawned sessions
agents sessions --all --since 7d --device yosemite-s0 --flat -n 30
agents teams status ship
agents roster                               # alias: sessions --active
agents feed                                 # needs-you inbox
agents devices list --live                  # headroom while teams run

Recall prior work without reopening every terminal: sessions · index + cross-device. Export a week for offline analysis: agents sessions export --since 7d -o week.bundle.

How this is used in practice

Patterns that show up repeatedly in real fleets (and in session archives of factory work):

Anchor + workers — laptop (interactive host) for browsers and review; Yosemite/worker boxes for teams start --watch and long loops.
Apply once, team often — agents apply after adding a machine or a new harness; daily work is create/add/start on the pool.
Worktrees on every edit teammate — parallel surfaces without merge chaos; --after only for real data deps (API before QA).
Sessions as the audit trail — after a long night of teams, sessions --since 1d --device <worker> reconstructs what landed where; export/import for handoff.
Smoke before scale — teams doctor and a two-teammate local team before a 6-node multi-device DAG.

# End-to-end checklist (copy/paste)
agents setup status && agents devices list --live
agents apply --plan && agents apply -y
agents teams doctor
agents teams create feat --devices yosemite-s0,yosemite-s1 --enable-worktrees
# … add teammates with --name / --after / --device / --worktree …
agents teams start feat --watch
agents sessions --active --teams