Fleet docs v0.2.0-rc.448

For users

You are a member of a fleet. You spawn agents, read their reports and answer their questions.

Change When
working to done The turn completes and the agent said fleet done.
working to needs_input The turn ends with no done, or the agent asked a question.
working to blocked The agent said fleet status --blocked.
retrying A crash. The retries come after 30 s, 2 minutes and 8 minutes. Then failed.
paused The profile is at its usage limit or has no usable login. It returns to queued when the limit resets or the login works.
lost The node was silent for more than 30 s.
needs_input or blocked to working A message arrives (fleet send, an answer).
failed or blocked to queued Someone resumes the agent.
stopped fleet stop, from any state that is not final.

States: fleet/internal/registry/states.go. Transitions: fleet/internal/supervisor/supervisor.go and fleet/internal/api/lifecycle.go. Only done and stopped are final.

First steps

  1. Get the fleet's URL and your project name from an admin.
  2. Sign in: fleet login https://fleet.example.com. Open the link and sign in with GitHub.
  3. Add your Claude login: claude setup-token, then fleet profile add main --kind subscription --default (paste the token on stdin).
  4. Link Telegram for questions: fleet notify link.
  5. Spawn: echo "<brief>" | fleet spawn hello --project myproject --workdir ~/demo --model sonnet.

Full steps: Join a fleet.

Every day

To Run
See your agents, state, last report fleet ls, or the page
Send an agent a message (it gets it in its next turn) fleet send <agent> "<text>"
See open questions fleet asks
Stop an agent fleet stop <agent>
Change a live setting (pace, usage threshold, dispatcher) with no restart, or see who changed what /admin (admins only): the Scheduler tab and the Change log
See cost fleet costs --by project --since 2026-11-01
See cost per ticket, every attempt and retry counted (UNKNOWN: turns whose usage was lost; ESTIMATED: lost turns priced at list price from the conversation they saved; CI RUNS: check runs on t/ and the trains that carried it) fleet costs --by ticket
See rented machine cost per ticket (COMPUTE: a Spot or cloud machine's rate times its life, split over the turns on it by time; an own box and the control server count $0) and the overhead last (compute:idle: machine time no turn used; merge-train, chief, chat, other: turns of no ticket). Another currency than USD shows as itself, not converted fleet costs --by ticket --since 2026-11-12
See whether a ticket landed: merge outcome, merged sha and time, first ready, attempts GET /v1/costs?by=ticket (outcome, merged_sha, merged_at, first_ready_at, attempts); the "Merged" comment on the issue also gives the cost so far
Compare cost per accepted ticket by model, driver, machine (spot:<class>, cloud:<class> or fixed) or project: every attempt of every ticket in the group, accepted or not, over the accepted ones; attempts per accepted; median first ready to merged and first turn to merged. A ticket counts once, in the group of the attempt that merged (MIXED: it ran in more than one) fleet costs --group machine --since 2026-11-12 (GET /v1/costs?by=ticket&group=machine, groups)
Let project members wake your agent fleet wake <agent> project
Use a second fleet fleet use <name>, or --fleet <name> for one command

What to know

  • Your agents use only your Claude profile. A colleague's agents never use it.
  • A message from another user reaches your agent marked as untrusted.
  • When an agent says done, fleet does not tell you. Read fleet ls or the page. A question from ask comes to Telegram. See the work sequence.
  • An agent that stays queued shows the reason in fleet ls. See Troubleshooting.

Start a chat

On the chat page (/chat), New chat (or the pencil at the top on a phone, or Ctrl+K) opens an empty chat in the current channel with the cursor in the message box. Type what you want and send. Nothing else is asked: the first message creates the chat and names it.

  • The chat starts in the channel's default repo, or in a neutral home folder when the channel has none. Options under the message box picks the model or the machine; you can leave it closed.
  • The agent works out where the work belongs from what you say. When the project is clear, it moves the chat to that project's git worktree and says in one line which project it picked. The header then shows the project and the branch.
  • When the project is not clear, the agent asks in the chat: a card with the projects as buttons. Tap one, and it goes on there.
  • Agents move a chat with the MCP tool use_workspace or fleet workspace <project> [--branch B] [--also R,R] [--new R,R].
  • When a message is unclear (the goal, the scope or the target), the agent asks one short question first. When it is clear, it acts and says in one line what it did.

Channels

A channel is a topic or an idea. + Channel in the list asks for a name and nothing else.

  • A chat in a channel with no repos talks and plans without one. The first time it needs code or files, it asks in a card: "Where should this live? Name repos, even roughly, or say new". Type it in your own words ("the dpc one and the data repo, and a new one for notes"). The agent matches that against your repos (fleet's projects and your Forgejo repos, by name and description), confirms in one line ("I will use dpcdirectory and publicdata, and create idea-x-notes. OK?") and goes on only after you say yes. A new repo is a private Forgejo repo.
  • The channel remembers those repos; later chats in it start in the first one and are not asked again.
  • The ⋯ by a channel's name opens its settings: name, repos, the repo new chats start in, and a machine. All are optional.
  • Chats run on persistent nodes only, never on elastic servers; the machine lists offer none. The workers a chat starts may still run on elastic servers.
  • Import at the bottom of the list brings in a Claude Code session from one of your machines.

Your Claude home and the fleet layer

Every turn of your agents gets your home: CLAUDE.md, settings.json, mcp.json and the skills/, rules/, agents/ and commands/ folders. It is laid under the fleet layer, which an admin keeps for everyone, and the two are merged:

  • CLAUDE.md: the fleet part first, then yours, each under its own heading.
  • settings.json: your value wins key by key; permissions.allow, deny and ask add up.
  • mcp.json: servers by name; your server of the same name replaces the fleet's.
  • Folders: by file; your file of the same path wins.
fleet home push                    # ~/.claude to your home (never a login or a session)
fleet home pull ~/claude-copy      # your home into a folder
fleet home ls --layer effective    # what your next turn gets, both layers merged
fleet home versions                # every save; * is the one turns get
fleet home use <version>           # roll back
fleet home push --layer fleet DIR  # admins: the fleet layer

push refuses to overwrite a save made since that folder was last pulled or pushed (someone else, or the page, saved in between). Pull into another folder, compare, and push again, or use push --force. A save takes effect at the next turn; a running turn keeps what it started with. Each turn records the version of each layer it got.

MCP servers in your home

A secret never goes into mcp.json. Write ${NAME} in its place and store the value as your own secret (fleet secret set --mine NAME). Every turn of yours gets your secret of each name that the merged mcp.json references, with no project listing it (#594). On the fleet layer, ${NAME} means each user's own secret of that name: one turn never uses another person's key.

fleet home mcp parse '<what the server docs say>'  # a URL, a claude mcp add line, npx/uvx/docker, or Desktop JSON
fleet home mcp probe https://mcp.example.com/mcp    # the auth it needs: none, oauth, bearer, unknown, unreachable
fleet home mcp test '<the same paste>'              # connect with the pasted key and list the tools
fleet home mcp health [--refresh]                   # each server in your merged home, as the server last checked it
fleet home mcp catalog [--more] linear              # the fleet list; --more also searches the MCP Registry (unreviewed)
fleet home mcp needs 'npx -y @playwright/mcp'       # can a node run this stdio server (node, uvx, docker)?
fleet home mcp connect https://mcp.linear.app/mcp LINEAR_TOKEN  # OAuth: open the printed URL and sign in

On the page, the Config tab has the same flow: MCP servers → Manage… shows a card for each server (a status dot from the last check, the tools, an on/off switch for the server and for each tool), Add server takes a paste or a catalog pick, and Advanced is the raw mcp.json. The switches write permissions.deny (mcp__<server> or mcp__<server>__<tool>) in the layer's settings.json; Save shows the diff first.

Connect (OAuth) registers fleet with the server's sign-in, opens it in a new window, and stores the token as your own secret under the name you pick (the entry sends Authorization: Bearer ${NAME}). The refresh data is the secret NAME__OAUTH; no turn gets it. The health check refreshes a token before it expires. When a refresh fails, the card turns amber and you get an inbox alert: press Reconnect. For Connect to work, the fleet URL (--url) must be one your browser reaches, because the sign-in sends your browser back to <fleet URL>/v1/home/mcp/oauth/callback. The callback sits behind the sign-in proxy and is not opened past it, so Connect needs an SSO session: a page signed in only with a fleet token says so, and you sign in through SSO first (#653).

A catalog pick from the MCP Registry is marked unreviewed: fleet has not checked it, so the probe and Test still run. Before you add a stdio server, fleet checks that a node that polls now has what the server needs (node for npx, uvx, docker). If no node has it, fleet refuses.

parse shows the entry it read and moves each key out to ${NAME}. It does not store anything: add the entry to your mcp.json, set the secrets, and fleet home push. probe only proposes: an OAuth server also takes a pasted key, and a 403 with no WWW-Authenticate is often a firewall, so it proposes nothing. A server that answers with no key can still want one for its tools. test calls tools/list and tells you so. A stdio server runs on the worker, so the server cannot test it.

The server checks each user's remote MCP servers every 30 minutes with that user's own secrets. When a server that worked, or that carries your key, starts refusing it or breaks, you get one inbox alert. You do not get one at each check. A server on the fleet layer that you never added a key for shows as "offered, not connected" and sends no alert. The server never connects to a loopback, link-local or cloud metadata address for these checks.

Every Claude Code session in fleet (the session hook)

fleet session report uploads a Claude Code session you run on any machine, so the chat page lists it (with the host it ran on) and any node can revive it. Import always forks: the original is never written. Log in on the machine first (fleet login); the hook holds no token.

Put this in ~/.claude/settings.json (or in your central home, then fleet home push):

{
  "hooks": {
    "SessionEnd": [{"hooks": [{"type": "command", "command": "fleet session report", "timeout": 15}]}],
    "Stop": [{"hooks": [{"type": "command", "command": "fleet session report", "timeout": 10}]}]
  }
}
  • The hook reads the hook JSON on stdin, starts a detached uploader (its own session, so it outlives Claude) and returns at once with exit 0. It never exits 2, so a Stop hook cannot hold the session.
  • The upload is complete at SessionEnd. Stop also queues one, but Claude writes the transcript asynchronously, so a Stop upload can miss the last reply; the SessionEnd one replaces it. An interrupted turn fires no Stop; fleet's node scan (#308) is the backstop for crashed sessions.
  • Uploads are idempotent: the same sha256 uploads nothing. The transcript is streamed and zstd-compressed.
  • Fleet's own turns (FLEET_AGENT_ID set) are skipped: they are stored already. Hooks in the user settings.json do not fire under --setting-sources project.
  • Errors go to ~/.cache/fleet/session-report.log.