Fleet
Fleet is the engine behind thurbox. It runs agent sessions on places and
keeps a record of each one. Its crates are crates/fleet-* in this
repository. The overview says how Fleet fits between
thurbox and the runtimes.
This page explains the model, every resource kind, every controller and how they fit together. Each linked page is a reference for one subject.
Install #
Fleet runs headless, without thurbox. The installers' fleet-only mode
installs fleet, runtime-mux and workspace-git, and nothing else:
curl -fsSL https://raw.githubusercontent.com/Thurbeen/thurbox/main/scripts/install.sh | sh -s -- --fleet-only
On Windows, pass -FleetOnly to the installer through a script block. This
form leaves no THURBOX_FLEET_ONLY variable behind in the session:
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Thurbeen/thurbox/main/scripts/install.ps1))) -FleetOnly
A THURBOX_FLEET_ONLY variable stays set in the session. A later install in
that session then skips thurbox, and the installer warns about it.
Then run fleet init, fleet doctor and fleet up.
configuration.md owns these commands. Nothing updates a
fleet-only install: to update it, run the installer again.
The model #
Fleet is declarative, like Kubernetes:
- You describe what you want as a resource,
apiVersion: fleet/v1alpha1, and write it withfleet apply -f FILE. - Each resource has a
spec, what you want, and astatus, what is. - A controller compares the spec with the status and the outside world. Then it acts to bring the status to the spec. This is a reconcile.
fleet upis the manager. It holds one lease and runs every controller in periodic sweeps.fleet reconcileruns the same sweeps until nothing changes, then exits.- The store keeps each resource as a file under the data directory. Every write is compare-and-swap. The lease also fences each controller write.
{
"apiVersion": "fleet/v1alpha1",
"kind": "Task",
"metadata": {"name": "fix-login"},
"spec": {
"harness": "claude-code",
"host": "local",
"brief": "Fix the login redirect and open a pull request.",
"workspace": ["git+https://github.com/example/app.git#main"],
"dispatch": true
}
}
spec.host names the place the session runs on: <runtime>/<place>, or
local, the default runtime's local place. fleet runtime places lists
the places of every configured runtime.
Resource kinds #
Each kind has one row here and one page. fleet version lists the kinds
that this build serves, from
kinds::BUILT_IN. A kind added
there fails docs_index
until it has its row here.
| Kind | What it is for | Who writes the spec | Who writes the status |
|---|---|---|---|
| Task | One agent session doing one brief on one place. | You, with fleet apply; fleet amend appends to amendments. ConversationController, for a chat thread that starts a Task. CronTaskController, at each scheduled time. |
TaskController, except the fields in Who owns a Task's status. |
| TaskConfig | Execution defaults that Tasks share: harness, place, model, environment, idle pause. | You, with fleet apply. |
Nobody: it has no controller. |
| EnvProvider | Environment values for a launch: stored data, a file or a command. | You, with fleet apply. |
Nobody: it has no controller. |
| ChangeRequest | A mirror of one change on a forge (a pull or merge request), numbered so that a reader diffs it with one integer. | The worker, with fleet declare --change-request URL; or you, with fleet apply. |
ChangeRequestController. |
| Conversation | A mirror of one chat thread, and the Task that the thread is tied to. | The account's listener, with fleet gateway receive; GatewayController, for a thread that Fleet opens; or you, with fleet apply. |
ConversationController. The listener spools deliveries on received. |
| Listener | The inbound health of one chat account. | The manager, one per [gateway.accounts] entry, or fleet gateway receive at a first beat. fleet apply refuses it. |
ListenerController. The listener records beats, refused and beatRevision. |
| Board | A log of events that every Task can read, in one order per board. fleet init makes shared, and fleet, where TaskController publishes fleet.task.*. |
You, with fleet apply; fleet init, for shared and fleet. |
Nobody: the store's append moves head and oldest when it appends events. |
| CronTask | A Task created from a template at each time of a cron schedule, like a Kubernetes CronJob. | You, with fleet apply. |
CronTaskController. |
| Plugin kinds | Kinds that a registered plugin defines and reconciles. Write a plugin shows how. | You, with fleet apply; the plugin, through its plan. |
The plugin, as plugin/<name>, through the manager. |
A Session is not a kind. It is the running agent that a Task owns, from
spawn to release. The Task's status.session names it, and
status.sessionState says what the runtime last proved about it. See
Session. A Workspace is not a kind either: it is the
directories the session works in, which the place's runtime makes from the
Task's spec.workspace. See Workspace.
TaskConfig and EnvProvider are passive. A Task names a TaskConfig in
spec.configRef. Before the first effect, the manager resolves the
TaskConfig and its EnvProviders. It freezes the result in the Task's
status.execution, so a later change to them does not change a Task that
already started.
Controllers #
A controller is a pure function in fleet-controllers. It gets the object, the observations and the time. It returns a plan: the status to write and the effects to run. The manager does every read, write and effect.
| Controller | Watches | Does | Writes |
|---|---|---|---|
| TaskController | A Task; its session through the runtime port; the agent's signals. | Makes the workspace, spawns the session on the place, sends the brief, delivers the inbox, pauses and resumes an idle session, revives a lost one, releases the session on delete. | Task status: phase, session, conditions, intents and receipts, deliveries. |
| ChangeRequestController | A ChangeRequest; the change through the forge port. | Mirrors the change's state, checks, reviews and notes. Deletes the object when its retention ends. | ChangeRequest status. |
| ForgeController | A Task's status.declared, and the ChangeRequests it names. |
Relays new review feedback into the Task's inbox. Takes a draft out of draft when its ready policy holds. | Task status.forge; inbox entries. |
| ConversationController | A Conversation's spool; the thread through the gateway port; its tied Task. | Numbers new messages, creates the Task that a thread starts, posts a refusal or a busy notice. Deletes the object when its retention ends. | Conversation status; a new Task. |
| ListenerController | A Listener's beats and refusals; the account through the gateway port. | Says whether the account's listener is alive. Deletes the object when the account leaves the config. | Listener status. |
| CronTaskController | A CronTask; the Tasks that carry its uid label. | Creates a Task at each scheduled time, unless the CronTask is suspended, the time is past its deadline, or its policy forbids it. Deletes the Concluded Tasks beyond its history limit. | CronTask status; a new Task. |
| GatewayController | A Task tied to a Conversation; its child Tasks. | Relays the thread into the Task's inbox. Posts the worker's declarations, logs and reactions to the thread. | Task status.gateway; inbox entries. |
| Plugin controller | The objects of a plugin kind. | Asks the plugin program what to probe and what to plan. A pure gate admits the plan. | The plugin kind's status, as plugin/<name>. |
TaskController, ForgeController and GatewayController all act on a Task. Each one owns a different part of its status, so no two of them write the same field.
One reconcile #
Three rules apply to every controller:
- Intent before effect. The manager writes the planned status, with
the effect's intent, before it runs the effect. It writes the receipt
after. Each effect has a deterministic key. After a crash, an intent
with no receipt is a question. For an effect that is not safe to
repeat, such as
Spawn, the next pass looks the result up by the key before it acts again. An effect that is safe to repeat, such asCleanWorkspace, runs again after a wait. - Unknown never means absent. Every observation is Known or Unknown. An Unknown answer (a timeout, an unreadable file, a corrupt record) keeps the last status. Only a Known answer can say that a session or a change is gone.
- One owner per status field. The store refuses a status write from a writer that does not own the field.
Who owns a Task's status #
| Field | Writer |
|---|---|
result, declared |
The worker, with fleet result and fleet declare. |
forge |
ForgeController. |
gateway |
GatewayController. |
inbox, answered |
Nobody. fleet send, fleet amend and the Forge and Gateway relays append through a typed store mutation. TaskController removes an entry after it delivers it. |
wakeRequestedAt |
Nobody. fleet attach and fleet shell set it through a typed store mutation: with --wake for a paused Task, and for a lost session. |
pauseRequestedAt |
Nobody. fleet pause sets it through a typed store mutation. |
| Every other field | TaskController. |
The source of this table is
kinds::status_owner.
From fleet apply to a ChangeRequest #
The steps for the Task in The model, with fleet up
running:
- You run
fleet apply -f fix-login.json. The store creates the Task in phasePending, with thefleet.dev/releasefinalizer. - This Task names no
configRefand noenv, so the manager has no launch to freeze. A Task with either gets its launch frozen intostatus.executionbefore the first effect. - TaskController plans
Materialize. The runtime'sworkspacecall makes the workspace on the place. - TaskController plans
Spawn, and the phase isSpawning. The runtime'sstartcall starts the agent. The receipt names the session instatus.session, and the phase isSpawned. - The agent starts in its session.
- The agent's hooks run
fleet signal, which appends to the session's signal file. TaskController reads it, and learns that the agent is ready. - TaskController plans
Brief. The runtime'sinputcall types the brief. The agent's prompt hook proves the delivery, and the phase isBriefed. - The worker opens a pull request and runs
fleet declare fix-login --change-request URL. Fleet creates a ChangeRequest for the URL and appends it tostatus.declared. - ChangeRequestController reads the change through the forge port and writes the ChangeRequest's status.
- ForgeController reads the ChangeRequest. It writes
status.forgeand appends new review feedback to the Task's inbox. - TaskController delivers the inbox entry through the runtime's
inputcall, then removes it from the inbox. - The worker runs
fleet result fix-login --generation 1 --outcome shipped. This writesstatus.result. - TaskController sets the phase to
Concluded. The session stays, and later inbox entries still reach it. - When a ready policy is selected and holds, ForgeController plans
MarkReady. The forge port takes the draft out of draft. No policy is selected by default:fleet initwrites three policies but noforge.draftPolicy. SetdraftPolicy = "checks"under[forge], orspec.forge.draft.policyon the Task. See ready policies for the checks that each policy adds to "the worker is done and idle". - You run
fleet delete task fix-login. The phase isReleasing. - TaskController plans
Releaseonce the agent is at rest, or at most 5 minutes after the delete. The runtime'sstopcall ends the session. - TaskController plans
CleanWorkspace. The runtime'sstopcall withreleaseremoves the workspace, and the receipt saysDeleted. Then the finalizer goes, and the store deletes the Task.
Reference pages #
| Page | Answers |
|---|---|
| architecture.md | The crates, their boundaries and ports, persistence, workspaces, views |
| contracts.md | What each part guarantees, and which tests hold it to that |
| configuration.md | fleet init, fleet up, every fleet.toml field, the environment file |
| integration.md | fleet integration: the hooks Fleet installs for an agent that takes none at launch |
| plugins.md | Write a plugin: a new kind and its controller, step by step, with a working example |
| signal-contract.md | For an agent vendor: how an agent reports its state through fleet signal |
| gateway-adapters.md | The Slack and Discord adapters of the gateway port |
Each controller page has its state machine, with the SVG of the same name beside it, and its interface. architecture.svg shows the crates during execution.