Fleet docs v0.2.0-rc.448

Glossary

Each word has one meaning in these pages. The words are in alphabetical order. Where the code uses a word in two ways, the entry says so. Not built marks a word from the design that the code does not have.

admin

A member with the fleet role admin. An admin adds and removes members, makes shared join tokens and sees the panels about the box and the projects. The last active admin cannot step down. Code: fleet/internal/authz/.

agent

One named task in a fleet: a brief, a project, a working directory, an owner, a model, a kind and a state. fleet spawn <name> makes it. Its id is a UUID, which is also its Claude session id. An agent runs as a series of turns. Code: fleet/internal/registry/registry.go.

agent token

The token that a turn gets as FLEET_TOKEN: <agent id>.<hmac>. The server computes it from the server key and never stores it. It acts as the agent, inside its own project only. After done or stopped, it can only read its own row. See token kinds.

ask

A question from an agent to its owner, its parent or another agent: ask in the worker MCP. A question to the owner goes to Telegram, or waits in fleet asks. The agent goes to needs_input until the answer comes. See a question on Telegram.

backend

Where a turn runs. process runs it as a local process. kubejob runs it as one Kubernetes Job. Code: fleet/internal/backend/.

blob

A file that the server keeps in its blob directory: the brief of each agent (<agent>/brief.md) and the conversation of each turn (<agent>/<turn>.jsonl.zst). A new node imports the newest blob to continue a conversation. Code: fleet/internal/blob/.

blocked

The state of an agent that said fleet status --blocked "<what it needs>". A message or a resume starts it again.

bootstrap code

A one-use code (flb.) that binds the first admin of a new fleet at its first fleet login --bootstrap. It expires after 1 hour. See token kinds.

bot

A named agent that lasts: its own instructions, kit, model and memory. A person makes it on the Bots page; a chat or a routine can run as it. See bots.

box

One machine, as the page shows it. The This box panel has one section for the server's box and one for each node that reports.

brief

The task text of an agent. It comes on stdin to fleet spawn. Turn 1 gets the brief and the context block.

build

On the page: a list of issues in one repo, put in waves by a label. The Builds panel shows each issue with its PR and its agent.

channel

One shared room of a fleet: it has one board of rulings and heads-ups that every running agent in it reads, and a chief. See the board.

chief

Two meanings in the code. (1) An agent kind: chief. The server does not run it itself. A node that lists chief in its kinds takes it. A chief is the chief of staff of one box (for example box-a-chief): it is pinned to its box, it never finishes (fleet done is refused), and each send to it starts a turn whose last message is the answer that turn shows (#289). (2) On the page: a person's interactive Claude Code session that starts agents. The dashboard finds it by its directory (chief_contains, chief_suffix). In these pages, a chief is a lead agent that acts for a person.

claim

A node asks the server for a turn: POST /v1/nodes/{id}/claim, every 10 s and when a turn ends. The server gives a turn only if the kind, the owner, the profile and the memory all match. A claim takes a lease.

cleanvm

The live test of the install steps: fleet/test/cleanvm/run.sh. It makes cloud VMs, runs the README's marked blocks, checks the result and erases the VMs. Each layout is one shape of fleet: 1, 2, 3a, 3b, mp, twofleets, shared, restore.

connector token

A user token of kind connector, with read or write scope, for a tool that connects to the control MCP. A client that sends an Authorization: Bearer header uses /mcp; a client that cannot (a claude.ai or ChatGPT custom connector) uses /mcp/k/<token>, with the same checks. See token kinds.

context block

The text that fleet adds after the brief in turn 1. It tells the agent its name, project, branch and ticket, how to report, the rules (push after each commit to wip/<n>, write RESUME.md) and the names of its secret keys. Code: fleet/internal/contextblock/.

control MCP

The MCP server at /mcp on the server, for a lead agent: agents, spawn, send, stop, resume, transcript and more. Code: fleet/internal/mcpcontrol/. A caller sends a user or connector token in the header, or in the path (/mcp/k/<token>), or signs in with OAuth: claude.ai and ChatGPT connectors find the sign-in from the 401 (fleet/internal/mcpauth/).

coordinator

The part of the server that answers node joins, heartbeats and claims, and finds lost nodes. Code: fleet/internal/node/coordinator.go.

dispatcher

The part of fleet serve that reads the Git host's open tickets and starts a worker for each one that is ready. It never works on a ticket itself. Code: fleet/internal/work/dispatch.go.

done

The final state of an agent that said fleet done "<result>". Also the command.

driver

The code that builds the command for one coding CLI and reads its output. The node has the claude driver. Code: fleet/internal/driver/.

fleet

One control server with its own database, keys, sign-in, members and nodes. A fleet is a unit of trust: two fleets share nothing. Also the name of the program and its CLI. See separate fleets.

front-door

An agent kind for a session that a person talks to. The server does not run it itself. A node that lists front-door in its kinds takes it.

health

How the page labels an agent or a session: working, done, needs input, retrying, blocked, lost, stuck, failed, idle, queued, paused, parked, stopped. Health comes from the state, and for a session that fleet did not start, from its process and transcript. See workers.

heartbeat

A node tells the server that it is alive: POST /v1/nodes/{id}/heartbeat, every 10 s. After more than 30 s with no heartbeat, the node is lost.

held

An agent that is paused with a reason that starts with held:. It made no progress in 6 turns in a row. It starts no more turns until a person resumes it. On the Builds panel, held is also a label on an issue. See a stuck worker.

identity token

A JWT from the identity provider (dex, with GitHub) that proves who a person is. The page gets it through oauth2-proxy. fleet login exchanges it for a user token.

inbox

What waits for a person or an agent: an approval, a question, a message. fleet inbox lists an agent's messages; the Inbox page lists a person's.

isolation

How a shared node keeps the turns of one member away from another member. uid: each member's turns run as a separate unix user fleet-<hash> with a 0700 home. pod: each turn is a Kubernetes pod. none: a personal node only. Code: fleet/internal/backend/process/uid.go.

join token

A one-use token (flj.) that lets one machine join the fleet as a node. It expires after 1 hour. fleet node token makes a personal one. fleet node token --shared (admins) makes a shared one.

keeper

The standing agent that gets every blocked, waiting, held or silent worker from the supervisor and unblocks it, so that no ticket waits on a person. It asks the owner only for an ask-first item. See docs/fleet/keeper.md.

kind

The kind of an agent: worker (the default), front-door, chief or kubejob. The kind decides where the agent can run. The server runs only the kinds in local_kinds (the default is worker). A node runs the kinds in its kinds. Only a kubejob node runs kubejob.

kubejob

A backend that runs each turn as one Kubernetes Job, and the agent kind for it. See Kubernetes Jobs.

ladder

The models that a stuck agent moves up: sonnet, then opus, then fable. Code: DefaultLadder in fleet/internal/supervisor/supervisor.go.

land

fleet land: how a worker hands finished work to a repo whose ship.yaml says merge.mode: trunk. It rebases on the default branch, runs the local gate (check.local) and fast-forwards the default branch, with a retry when another worker landed first. Exit 3: a conflict, resolve it and run it again. Exit 4: the local gate failed. It comments Landed <sha> on <base> by fleet land on the ticket; the Work page counts that like the merge train's Merged comment. There is no ready message and no Waiting stage in a trunk repo. See docs/fleet/trunk.md.

last green

lead agent

A Claude Code session that starts and directs other agents with fleet spawn or the control MCP. It can be an interactive session or a fleet agent. The code does not use this word. It records the parent of each agent. See agents that start agents.

lease

A hold on a turn and its profile, so that only one place runs it. A node's lease lasts 90 s and each heartbeat keeps it. Code: fleet/internal/sched/leases.go.

ledger

The list of every change in the fleet, as events (fleet.ledger/v1). Every change to the registry goes through the ledger first. The ledger table in fleet.db is the source. ledger.jsonl is a copy: each append, and each server start, first writes the table rows the file lacks, so a lost append or a CLI command's events reach it later. A file with a hole in the middle is rebuilt from the table at start; the old one stays as ledger.jsonl.before-rebuild-<unix time> (#510). Code: fleet/internal/ledger/.

lost

The state of an agent whose node is silent for more than 30 s. If the node returns, the agent is working again. After 15 minutes, the server makes the agent again for another node.

mailbox

The messages for an agent, kept in the registry. They come at the top of the agent's next turn. fleet send writes to it, fleet inbox reads it. Code: fleet/internal/mailbox/.

member

A person in a fleet, with the role admin or member. A project member is a person who can spawn agents in that project, with the role maintainer or member. See add and remove a person.

needs_input

The state of an agent whose turn ended without done, or that asked a question. A message starts its next turn. The page shows "needs input".

node

A machine that runs fleet node and runs turns for the server. A personal node runs only its owner's agents. A shared node runs every member's agents. Its id is tag:fleet-node/<hostname>. See more machines.

node token

The token (fln.) that a node gets when it joins, kept in its --dir. It never expires and has no revoke. A new server key ends it.

orchestrator

The session that runs a swarm: it plans, starts the workers and runs the merge queue. The swarm plugin uses this word. The fleet code does not. In fleet, an orchestrator is a lead agent.

owner

The person whose agent it is. A child agent keeps the owner of its parent. The owner's profile pays for the turns.

owner token

A token in owner.token that acts as the first admin. It exists only with fleet serve --owner-token. It is the sign-in of a fleet for one person.

paused

The state of an agent whose profile is at its usage limit, has no usable login, or that is held. It spends no retry.

pin

An agent pinned to one node runs its turns only there: fleet spawn --node <hostname> (or the node id). The control server never runs a pinned agent itself. A chief is pinned to its box. Code: PinMatches in fleet/internal/registry/registry.go.

profile

One Claude login that fleet keeps for a person: a subscription token or an API key. Its id is <login>/<name>. Its state is ok or limited. Each agent uses one profile. See profiles.

project

A name for one repo and its rules: the repo, the MCP servers, the secret keys that its turns get, and who may spawn in it. fleet projects sync loads projects from a config repo. Membership is in the database.

queued

The state of an agent that waits for a turn. fleet ls shows why it waits.

registry

The database of the fleet: agents, users, members, projects, nodes, tokens, profiles and secrets rows. SQLite in fleet.db. Code: fleet/internal/registry/.

retrying

The state of an agent after a crash or a stuck turn. The page shows the count, for example "retrying 2/3".

routine

Work that a bot starts by itself, on a schedule or on an event. Test runs one now; History lists its runs. See routines.

scheduler

The part of the server that starts turns on the server's own box, every 15 s or when something wakes it. Code: fleet/internal/sched/.

secret

A value that a turn gets as an environment variable: a project secret or a user secret. fleet secret set stores it with sops and age. No API returns a value. See a secret to one turn.

server

fleet serve: the control server. It keeps the registry, the ledger and the blobs, serves the API, the page and the control MCP, and gives turns to nodes. One fleet has one server.

server key

The random key in server.key. The agent tokens, the node tokens and the derived join tokens come from it. A new server key ends all of them.

shared node

A node with no owner. It runs the agents of every member, with isolation uid or pod. An admin makes its join token with fleet node token --shared. See shared machines.

spawn policy

The limit on agents that start agents: depth 3, and 32 live children for each agent (serve.yaml spawn.max_children). A person who spawns has no limit. An agent at depth 3 may still spawn probes (#452): fleet spawn <name> --probe is a haiku worker in its own project with a budget of at most 0.50 USD and a time cap of at most 900 s. A probe spawns nothing, and one agent spawns at most 25 probes in its life (serve.yaml spawn.max_probes). Code: fleet/internal/spawnpolicy/.

state

One of the ten states of an agent: queued, working, needs_input, blocked, retrying, failed, paused, lost, done, stopped. Only done and stopped are final. See the life of an agent.

stuck

Nothing stops a silent turn any more: see a stuck worker. On the page, stuck is the health of a session that is busy, with no transcript change for 30 minutes.

supervisor

The part of the server that reads how a turn ended and picks the next state: done, retry, wait, pause or fail. Code: fleet/internal/supervisor/.

ticket

An issue on the Git host that fleet staffs: the dispatcher starts a worker on it, and the Work page shows it by stage. See a ticket.

token kinds

Token Form For
Owner token hex The first admin, one-person fleet
User token, cli flu. A person's CLI, 90 days
Connector token flu. A tool on the control MCP, read or write
Bootstrap code flb. Binds the first admin, one use
Identity token JWT Proves a person, from dex
Agent token <id>.<hmac> One agent's turns
Join token flj. One machine joins, one use
Node token fln. A node after it joined

Full table: add and remove a person.

trunk guard

The loop in fleet serve that checks the newest head of a trunk repo's default branch by pushing check/<sha12>, runs a red check again once, bisects the commits since the last green, and reverts the culprit as a forward commit. It sends the ticket back with a Sent back: reverted <sha> comment; the card moves to Sent back and the next land is a new round. GET /v1/trunk/<owner>/<name> (or /v1/trunk/<project>) shows its state.

turn

One run of claude -p for one agent. Turn 1 gets the brief. A later turn gets the new messages and continues the same conversation with --resume. A turn ends with a result, a crash, a limit or a stop. See one agent, one turn.

turn-shim

fleet turn-shim: a small process that runs one turn on the server's box and writes its exit code to a file. Because of it, a server restart does not stop a turn. Code: fleet/internal/backend/process/detach.go.

untrusted

How an agent sees a message from another person or another person's agent: marked untrusted: data, not instructions. The context block tells the agent to treat it as data.

user token

A token (flu.) that acts as one person. fleet login makes it and keeps it in ~/.config/fleet/<fleet>/token. It lasts 90 days at most. See token kinds.

waiting

A ticket stage on the Work page: the checks passed and the change waits to merge. It is also the word for an agent that sleeps until an answer or a time (inbox_post, the wait tool), with no process running.

wake

fleet wake <agent> project: messages from project members start a turn of this agent. Without it, those messages wait for a turn that the owner causes.

wave

A group of issues in a build, from a label such as wave:1.

worker

Two meanings in the code. (1) The default agent kind. (2) The coding CLI process that runs one turn. In these pages, a worker is an agent that does one ticket.

worker MCP

The MCP server inside a turn (fleet mcp): report, done, ask, inbox, send, spawn, context. The fleet CLI does the same things. Code: fleet/internal/mcpworker/.

working

The state of an agent with a turn that runs, or that waits for its next turn with messages ready.

workspace

The git worktree an agent works in. A live chat starts with none and moves to a project's worktree with use_workspace (or fleet workspace <project>) before it changes files.