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 overridepace,usage_thresholdand 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(processorkubejob),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), orclaude.pathwhen set, by its absolute path. It never runs theclaudeonPATH. Every turn getsDISABLE_UPDATES=1andDISABLE_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 inallowed. With noclaudekey the server checks nothing. A node with no pin reports no version and runs no probe, so a fleet withclaude.versiongives it no turns: pin every node first. - The probe. A node that takes live turns runs
fleet probeon its binary after it joins, with haiku. It checks stream-json in and out with several messages in one process, theinterruptcontrol request,--permission-prompt-tool stdio(acan_use_toolrequest comes for a Bash call), the capabilities ofinitializeandsystem/init, and that-pis not--bare(a--settingshook 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 withCLAUDE_CODE_OAUTH_TOKENorANTHROPIC_API_KEYfrom the node's environment, else the node's--claude-credentialsfile, read only. - See it.
fleet ls --nodes(admins) and the Nodes table at/docs/your-fleetshow 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:
- 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. - On every node, run
fleet probe --version 2.1.330. Each must printprobe passed. If one fails, stop here: the protocol changed, and live chat needs a code change first. - Raise the server:
claude: {version: "2.1.330", allowed: ["2.1.321"]}inserve.yaml, and restartfleet serve. Nodes on 2.1.321 keep running workers and stop taking live turns. - Change
claude.versionin eachnode.yamlto2.1.330and restart each node. It takes live turns again after its probe passes (cached from step 2). - 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.