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
- Get the fleet's URL and your project name from an admin.
- Sign in:
fleet login https://fleet.example.com. Open the link and sign in with GitHub. - Add your Claude login:
claude setup-token, thenfleet profile add main --kind subscription --default(paste the token on stdin). - Link Telegram for questions:
fleet notify link. - 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. Readfleet lsor the page. A question fromaskcomes to Telegram. See the work sequence. - An agent that stays
queuedshows the reason infleet 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_workspaceorfleet 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,denyandaskadd 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
Stophook cannot hold the session. - The upload is complete at
SessionEnd.Stopalso queues one, but Claude writes the transcript asynchronously, so aStopupload can miss the last reply; theSessionEndone replaces it. An interrupted turn fires noStop; 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_IDset) are skipped: they are stored already. Hooks in the usersettings.jsondo not fire under--setting-sources project. - Errors go to
~/.cache/fleet/session-report.log.