Architecture
fleet is one Go binary. fleet serve is the control server. fleet node runs turns on another
machine. A turn is one run of claude -p for one agent.
| Part | What it does | Code |
|---|---|---|
| Server | Wires every part, serves the API, the page and the control MCP | fleet/internal/server/wire.go, fleet/internal/api/router.go |
| Registry | SQLite: agents, users, members, projects, nodes, tokens, secrets | fleet/internal/registry/sqlite/ |
| Ledger | Every change as an event, in a table and in ledger.jsonl |
fleet/internal/registry/sqlite/apply.go |
| Blobs | Each agent's brief and each turn's conversation (zstd) in a directory | fleet/internal/blob/ |
| Scheduler | Starts turns on the server, every 15 s or when woken | fleet/internal/sched/ |
| Coordinator | Gives turns to nodes when they claim, finds lost nodes | fleet/internal/node/coordinator.go |
| Node | Asks for work, runs turns, sends results back | fleet/internal/node/agent.go |
| Backend | process (a local process, with uid isolation as an alternative) or kubejob (one Job per turn) |
fleet/internal/backend/ |
| Driver | Builds the claude command and reads its output |
fleet/internal/driver/claude/ |
| Vault | Claude logins in an age vault (creds/), project and user secrets as sops files (secrets/values/) |
fleet/internal/creds/, fleet/internal/secrets/ |
| Page | One HTML page that reads /api/state every 15 s |
fleet/internal/web/index.html, fleet/internal/dash/ |
| Control MCP | agents, spawn, send, stop, resume, transcript and more, for a lead agent, at /mcp |
fleet/internal/mcpcontrol/ |
| Worker MCP | report, done, ask, inbox, send, spawn, context inside a turn (fleet mcp) |
fleet/internal/mcpworker/ |
| Telemetry | Server spans to FLEET_OTLP_ENDPOINT. Workers get OTEL_* variables. |
fleet/internal/telemetry/ |
| Notifier | Questions to Telegram, answers back by getUpdates |
fleet/internal/notify/ |
Blobs live in the server's blob directory only; there is no object-store backend. Only the claude
driver is registered.
Layouts
One diagram for each layout:
- One person, one machine
- Several VMs, one fleet
- A team with sign-in
- Shared nodes and per-user isolation
- Kubernetes Jobs
- Several clusters
- Several fleets in one company
- A person's own machine in a team fleet
Sequences
- Sign-in: first admin,
fleet login, the page, a worker's token, a node join. - Work: from a request to a result, and what is pushed and what is polled.
- A question on Telegram.
- A worker crashes, or the server restarts: retries,
fleet turn-shim, a node restart. - A stuck worker: the watchdog, the hold, a turn with no
done, a question. - A Claude account hits its limit: pause, and continue at the reset.
- Add and remove a person: tokens, agents, profiles, nodes, and all token kinds.
- A machine joins, and a machine dies: join, heartbeat, lost, made again elsewhere.
- A secret, from storage to one turn: sops, the env, a pod.
- A release goes out and is reverted.
- Backup and restore.
- A ticket, from issue to deploy: a lead agent, the swarm, CI, the Builds panel.
The design is docs/fleet/spec.md. Where the spec and these pages disagree,
these pages follow the code at the commit that changed them.