Fleet docs v0.2.0-rc.448

For operators

You install and run a fleet: the control server, its nodes, sign-in, upgrades and backups.

Task Where
Install one box Quickstart
Add VMs Several VMs
Run turns as Kubernetes Jobs Kubernetes Jobs, a managed cluster
A team with sign-in Make a new fleet, fleet/deploy/examples/signin/
Upgrade Upgrading: the server first, then each node, the same version on all
Back up and restore Back up and restore
How many agents run at once, when a machine is rented Capacity: by machine load (#559)
An agent stays queued, a node is stale Troubleshooting

Configuration

Both files are read strictly. An unknown key is an error.

  • /etc/fleet/serve.yaml (fleet/internal/cli/serveconfig.go): listen, url, no_local_workers, local_kinds, claude_credentials, worker_env, admission, usage_threshold, pace, fleet_name, issuer, client_id, mcp_client_id, admin_github, owner_token, telegram_bot_token_file, dash, claude (the fleet's Claude Code version), and more. An admin can override pace, usage_threshold and the dispatch knobs live on /admin (see Admin); the file then gives only the starting value.
  • node.yaml (fleet/internal/node/config.go): hostname, max_running, kinds, backend (process or kubejob), namespace, image, run_as, dash, claude (the pinned Claude Code version). Isolation on a shared node is the flag --isolation uid, not a key.

Keep each box's config in the repo, under fleet/deploy/examples/<name>/. The release procedure is the fleet-release skill (.claude/skills/fleet-release/SKILL.md).

Claude Code version

Live chat speaks a stdin protocol of Claude Code that is not documented and can change in any release (docs/fleet/research/2026-11-09-claude-code-capabilities.md). The CLI also updates itself. So each node pins one exact version, and the fleet runs one version (#317).

  • Pin on the node. node.yaml: claude: {version: "2.1.321"}. The node runs ~/.local/share/claude/versions/2.1.321 (the native installer's place), or claude.path when set, by its absolute path. It never runs the claude on PATH. Every turn gets DISABLE_UPDATES=1 and DISABLE_AUTOUPDATER=1. If the binary is missing, or reports another version, the node logs it, claims no work, and the page says why.
  • One version per fleet. serve.yaml: claude: {version: "2.1.321", allowed: ["2.1.319"]}. A node of another version takes no live turns. It takes no turns at all unless its version is in allowed. With no claude key the server checks nothing. A node with no pin reports no version and runs no probe, so a fleet with claude.version gives it no turns: pin every node first.
  • The probe. A node that takes live turns runs fleet probe on its binary after it joins, with haiku. It checks stream-json in and out with several messages in one process, the interrupt control request, --permission-prompt-tool stdio (a can_use_tool request comes for a Bash call), the capabilities of initialize and system/init, and that -p is not --bare (a --settings hook fires and the login is read). Until it passes, the node takes no live turns. A pass is cached in <dir>/probe/<sha256>.json, so it runs once per binary. A failure is not cached. The probe signs in with CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY from the node's environment, else the node's --claude-credentials file, read only.
  • See it. fleet ls --nodes (admins) and the Nodes table at /docs/your-fleet show each node's version, the fleet's version, and why a node takes no turns or no live turns.

Upgrade to a new version, for example 2.1.330:

  1. On every node, install it next to the old one: claude install 2.1.330. The pin still runs the old one. Do not delete the old version.
  2. On every node, run fleet probe --version 2.1.330. Each must print probe passed. If one fails, stop here: the protocol changed, and live chat needs a code change first.
  3. Raise the server: claude: {version: "2.1.330", allowed: ["2.1.321"]} in serve.yaml, and restart fleet serve. Nodes on 2.1.321 keep running workers and stop taking live turns.
  4. Change claude.version in each node.yaml to 2.1.330 and restart each node. It takes live turns again after its probe passes (cached from step 2).
  5. When every node runs 2.1.330, remove allowed.

Roll back: lower claude.version in serve.yaml and in each node.yaml to the old version, which is still installed, and restart. Nothing else changes.

When something stops

What stops What happens
The server restarts Turns on the server's box keep running under fleet turn-shim. Node turns are not touched.
A node is silent for more than 30 s It is lost, and its working agents are lost. After 15 minutes they are made again on another node.
The provider deletes or pre-empts a rented server fleet autoscale logs one gone at the provider or pre-empted line (fleet autoscale log), removes its hub peer, and its card leaves the page at once. Its agents are made again on another node as soon as the node is lost, not 15 minutes later (#423).
A rented server's node is silent for 5 minutes and the provider still runs it fleet autoscale deletes the server and logs deleting a lost node with the reason (#423).
A profile has no usable login The profile pauses. Its agents wait and spend no retry.
The server's disk is lost Restore from the backup on a new box.

The full table, with the test for each line: How it fits together.

Security

  • Secrets go to a process on stdin or in a 0600 file, never on a command line.
  • The server keeps the Claude refresh token. A turn gets an access token only.
  • Give each fleet its own GitHub team. Do not reuse a team that opens other services.
  • Do not open port 8790 to the internet. Nodes reach it over a private network.