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.