Configuration
Initialization and fleet up #
fleet init writes the native config. fleet up keeps every due Task
reconciling. This page owns their behaviour. The native Fleet TOML
reference owns the config fields.
Prerequisites #
init works offline. To run real sessions, put runtime-mux on PATH,
install tmux, and install and authenticate each harness your Tasks name.
The fleet-only install puts fleet, runtime-mux and
workspace-git on PATH.
Fleet does not install prerequisites or change login state. up asks the
runtime of each configured host for its manifest. When no host answers, up
exits and names the runtime it could not start. When some hosts answer, up
reports each other host and starts. Harness login and readiness failures stay
visible in Task status: inspect fleet status task NAME --json before you
retry.
Fleet starts the codex harness with a launch override that trusts its
workspace. Claude Code can show its trust dialog in a new workspace. Fleet
never answers that dialog: trust the folder once in the session, and the
brief follows. See workspace trust.
Running fleet up #
up runs in the foreground and continuously reconciles every due Task. It
creates no Task of its own: Tasks come from fleet apply, from an interface
such as thurbox, or from a gateway route. Keep up running in a terminal or
your own service supervisor. Ctrl-C (also SIGTERM on Unix) finishes the
bounded sweep, releases the manager lease and retains sessions. Run
fleet up again to reconnect.
fleet up holds an exclusive OS lock on <data dir>/manager.lock for its
whole life. The OS releases the lock when the manager exits, however it
exits. A second fleet up on the same store waits while the lock is held,
whatever lease.json says. It prints the holder once, and it takes over
when the holder exits. The lease keeps its fencing role:
every controller write checks its token. Each new lease takes its token
from the store's resourceVersion counter, so a token never goes back,
even when lease.json is lost.
fleet up tells a supervisor its state through systemd's notify protocol
when NOTIFY_SOCKET is set:
STATUS=waiting for …while another manager holds the lock.READY=1after it takes the lease and finishes its first pass. A unit withType=notifycounts as started only then.STATUS=paused: disk full at <path>while the disk of the data directory has no room. A pause sends noREADY=1: a manager that pauses before its first pass stays not ready until it resumes.STOPPING=1when it stops.
A full disk pauses fleet up. It does not stop it:
- A store write fails with no room left (
ENOSPCorEDQUOT). The sweep stops at that write, so no effect runs without its intent. - The manager keeps
manager.lock, recordsstate: pausedand prints the path that was full. - It tries again after 5 s, then doubles the wait up to 60 s.
- When a write succeeds again, it renews its own lease, with an unchanged
token, even when the lease expired during the pause. It records
state: servingand resumes.
A stop during a pause cannot release the lease. The next manager takes it over, because its holder is gone.
fleet doctor warns when less than 256 MiB is free on the disk of the
data directory.
fleet up exits with code 78 on a refusal that no retry can fix: a config
that does not parse, or a store whose format this build does not read. A
unit stops restarting it with RestartPreventExitStatus=78.
The manager writes its status to <data dir>/manager.json: pid, boot,
version, exe, config, startedAt and state (starting,
serving, paused or stopped). On a full disk the manager overwrites
the record in place, so paused reaches it. The record is status, never authority: a manager
that crashed leaves its last state behind.
The service unit: fleet service #
fleet service writes and drives the one supervisor of fleet up, under
the system's own service manager:
- Linux: a systemd user unit, driven through
systemctl --user. - macOS: a launchd agent, driven through
launchctlin the user'sgui/<uid>domain. - Windows: a Task Scheduler task that starts at the user's logon, driven
through
schtasks.
The commands below name the systemd verbs. The other two supervisors are described after the systemd unit.
| Command | What it does |
|---|---|
fleet service install [--name NAME] [--now] |
Writes ~/.config/systemd/user/NAME.service (fleet by default) for the config, runs daemon-reload and enables the unit. --now also starts it. |
fleet service start, stop, restart |
Runs systemctl --user with that verb on the store's unit. stop keeps the sessions. |
fleet service restart --expect VERSION [--timeout SECONDS] |
Restarts the store's unit with try-restart when it runs, and waits until a manager that started since then serves VERSION. Exits 0 when it serves, and 0 when the unit was not running. Exits 1 when the unit fails first, for example on exit code 78, and 7 when the wait ends. The wait is twice TimeoutStopSec, plus one minute, by default. |
fleet service status |
Prints systemctl --user status of the store's unit, and exits with its code: 0 when the unit is active, 3 when it is not. |
fleet service uninstall |
Stops and disables the store's unit, removes its file and runs daemon-reload. Its drop-ins stay. |
install --now, start and restart queue the job and return. They do not
wait for READY=1: a new fleet up waits while another manager holds the
store's lock. fleet service status shows when the unit is active.
restart --expect reads the manager record (manager.json): its
version, its state and its startedAt. The update of an install
(thurbox-cli update) runs it after it installs a release.
--config names the config, as for every command. The unit sets
FLEET_CONFIG to that config's absolute path. --data-dir is refused:
fleet up reads the data directory from the config. Each verb other than
install acts on the unit of the config's store. --name names another
unit.
The unit that install writes:
[Unit]
Description=Fleet manager (fleet up)
X-Fleet-Store=<data dir>
[Service]
Type=notify
Environment="FLEET_CONFIG=<config>"
Environment="PATH=<fleet's directory>:<PATH at install>"
ExecStart="<fleet's directory>/fleet" --config ${FLEET_CONFIG} up
Restart=on-failure
RestartSec=2s
RestartSteps=6
RestartMaxDelaySec=2min
RestartPreventExitStatus=78
TimeoutStartSec=infinity
TimeoutStopSec=<the manager lease>
KillMode=mixed
[Install]
WantedBy=default.target
<fleet's directory>is<prefix>/lib/thurbox/current/binwhenfleetruns from a release under<prefix>/lib/thurbox/releases/. A restart then runs the current release.X-Fleet-Storenames the store. systemd ignores the key. Fleet reads it to find the unit of a store.installrefuses a second unit for the same store, with exit code 5. Uninstall the first unit, or install it again under its own name.installwith the name of an existing unit replaces the unit file. The unit's drop-ins (NAME.service.d/) stay. Put local changes, such as more directories onPATH, in a drop-in:systemctl --user edit NAME.service.TimeoutStopSecis the lease thatfleet uptakes: twice the longest runtime, forge, gateway or plugin operation, and 30 seconds at least. A stop lets the current sweep finish.KillMode=mixedsignalsfleet up, and then stops every process that is left in the unit's cgroup.runtime-muxstarts the multiplexer's server in a scope of its own (runtime-mux), so the server, and every session on it, stays when the unit stops or restarts.- A tmux server that started before
runtime-muxused a scope is in the unit's cgroup. The first stop or restart of the unit stops that server. Fleet then starts each Task's session again, as after a host reboot.
The launchd agent (macOS) #
install writes ~/Library/LaunchAgents/NAME.plist. The agent's label is
NAME. The property list holds the same command and environment as the
systemd unit, and these keys:
XFleetStorenames the store. launchd ignores the key.RunAtLoad, andKeepAlivewithSuccessfulExitfalse: launchd starts the agent when it loads it, and starts it again after a failure, 10 seconds apart at most (ThrottleInterval).ExitTimeOutis the lease thatfleet uptakes, asTimeoutStopSec.AbandonProcessGroupkeeps the multiplexer's server when the agent stops. Every other process that the manager started also stays.- The manager's output goes to
~/Library/Logs/NAME.log.
| Command | launchctl |
|---|---|
install |
enable gui/<uid>/NAME. --now also loads the agent with bootstrap when launchd has not loaded it. Otherwise launchd loads it at the next login. |
start |
kickstart, or bootstrap when the agent is not loaded |
restart |
kickstart -k, or bootstrap when the agent is not loaded |
stop |
bootout: it stops and unloads the agent |
status |
print. Exit 0 while the agent runs, 3 while it does not |
uninstall |
bootout when the agent is loaded, and removes the property list |
restart --expect |
kickstart -k. The agent fails first when it stops with exit code 78 |
launchd has no RestartPreventExitStatus: it starts a manager that exits
78 again after ThrottleInterval. A loaded agent keeps the property list
it was loaded with. Run fleet service stop and then start to load a
rewritten one.
The Task Scheduler task (Windows) #
install writes the task's XML to
%LOCALAPPDATA%\fleet\service\NAME.xml and registers it as the task
NAME with schtasks /Create /XML. Fleet keeps that file to find the task
of a store. The task:
- names its store in
Documentation(X-Fleet-Store=<data dir>); - starts at the user's logon, as that user, with no extra privilege;
- runs
"<fleet>" --config "<config>" upwith no time limit; - starts again after a failure, one minute apart, at most 999 times;
- ignores a second start while it runs.
| Command | schtasks |
|---|---|
install |
/Create /TN NAME /XML <file> /F. --now also runs /Run |
start |
/Run |
restart |
/End when the task runs, then /Run |
stop |
/End when the task runs |
status |
/Query /V /FO LIST. Exit 0 while the task runs, 3 while it does not |
uninstall |
/End, then /Delete, and removes the XML file |
restart --expect |
/End, then /Run. The task fails first when its last result is 78 |
/Endends the manager at once. It does not wait for the current sweep. The next manager takes over the lease of a manager that is dead.- Fleet reads
StatusandLast Resultfrom the report ofschtasks, which names them in English. - The task runs in a console window of its own.
The supervisor in fleet version #
fleet version --json names the service in manager.supervisor:
{"kind": "systemd", "unit": "fleet.service"}, {"kind": "launchd", "unit": "fleet"} or {"kind": "task-scheduler", "unit": "fleet"}, or
null when no service runs the store. An interface reads the service there
and does not guess it.
The install script (scripts/install.sh) runs fleet init and
fleet service install --now on Linux when a systemd user manager answers.
THURBOX_NO_SERVICE=1 skips that step.
The lease holder is fleet-up-<pid>@<boot id>. On Linux, after a reboot,
a manager takes over at once a lease whose holder names another boot:
neither that manager nor any process it started still runs.
A lease holder records each process group it starts (a runtime, forge,
gateway or plugin call) in <data dir>/children/<pid>@<boot id>/, until
the call returns. When the holder's process is gone on the same boot, for
example after a SIGKILL, the next fleet up or fleet reconcile does
these steps:
- It kills each process group that the dead holder recorded.
- It waits until each group is gone, then removes its record.
- It takes the lease at once.
When a group cannot be stopped, the record stays and the next manager
waits for the lease to expire. The check reads /proc, so every process
that uses one data directory must run in the same PID namespace. A holder that left no record directory,
such as one from an older Fleet, also waits for expiry.
fleet version --json reports the manager lease and the manager record
under manager, and only reads them:
{"manager": {"held": true, "holder": "fleet-up-4242@6780a1c8-c1de-4350-9421-b5ff90278de2", "expiresAt": 1763120000000, "why": null, "state": "serving", "version": "3.4.0", "exe": "/usr/bin/fleet", "config": "/home/me/.config/fleet/config.toml", "supervisor": {"kind": "systemd", "unit": "fleet.service"}}}
heldistruewhile the recorded lease is unexpired and the next manager cannot take it at once: a manager runs.heldisfalsewhen no lease is recorded, the lease expired or was released, its holder names another boot, or its holder is gone on this boot and left a record directory.holderandexpiresAtthen name the last lease, if any.heldisnullwhen the lease cannot be read.whysays why. An unreadable lease never reads asfalse.state,version,exeandconfigcome frommanager.json. They arenullwhen no manager ran. When the record cannot be read, they arenullandwhysays why.cli.versionis the version of thefleetthat answers. When it differs frommanager.version, the manager runs another release than the one installed. Restart the manager through its supervisor.supervisornames the unit that runsfleet upfor the store (the service unit). It isnullwhen no unit names the store, and on a system other than Linux.- The report takes no lease and renews none, takes no lock, and it creates no store. Unknown session observations never trigger a blind replacement. Each sweep reports a Task that is blocked at startup or that needs attention, so no separate status query is needed to see why.
Polling defaults to one bounded sweep per second; up --poll-ms accepts 100
through 10000 ms. Each unfinished Briefed Task costs one bounded inspect
of its session per sweep. The lookup by key, the check for a gone window and
the check for a pause share that answer for 500 ms, until a verb changes the
session's process.
Unchanged Task status is not rewritten. A manual fleet reconcile remains
available for bounded diagnostics while up is stopped.
After a host reboot, fleet up revives the sessions of unfinished Tasks and
resumes their briefs. See
after a host reboot.
This works only when fleet up starts again after the reboot. A service
supervisor must start it at boot, without a login. fleet service install
enables its unit for default.target. Let the user manager run without a
login:
loginctl enable-linger "$USER"
runtime-mux starts the multiplexer's server in a scope of its own, so the
server is not in the unit's cgroup. A unit that you write yourself can use
KillMode=mixed, as the unit that fleet service install writes does.
Without a systemd user manager, runtime-mux starts the server in the
cgroup of fleet up. Then a unit needs KillMode=process to keep the
sessions.
Configuration and customization #
Reference: native Fleet TOML, Task, TaskConfig, EnvProvider, and environment JSON.
Config selection is --config PATH, then FLEET_CONFIG, then exactly one
native per-user path: $XDG_CONFIG_HOME/fleet/config.toml (fallback
~/.config/fleet/config.toml). Fleet never searches the current directory or
its parents. Explicit paths must exist for commands other than init;
init --config PATH creates a separate configuration and a default data
root at <native-data>/fleet/instances/<config-path-hash>/. Relative paths
inside TOML resolve beside that file. With no native data-home variables,
explicit --config uses a fleet-data directory beside the config as its
data root. An explicit store must be separate from the config.
Default init writes a fresh resource store path at
$XDG_DATA_HOME/fleet/store-v1 (fallback ~/.local/share/fleet/store-v1).
The config records absolute paths and a session key prefix derived from the
config's path, so two configs never share a session. It writes
runtimes.mux.callTimeoutMs = 10000, below the built-in default of 15000;
edit it to change the bound. No runtime under [runtimes] passes a model to
its harness: it refuses a Task that sets spec.model. Give the model in the
harness's own configuration instead.
init prints what it set up and what comes next: the config path, the places
sessions run in, the coding agents found on PATH, and the commands to run.
thurbox runs init itself on its first start when no config exists.
The config is yours once written. A repeated init validates it and keeps
it as it is; a malformed config is an error, never replaced. A symlink at the
config's path is refused; a symlinked directory above it is not. Initializers serialize with an OS lock,
so two concurrent init runs write one config.
Migrating a Fleet 2 config: fleet migrate #
Fleet 3 refuses a Fleet 2 config by name. fleet migrate turns the Fleet 2
config and store into Fleet 3's. fleet migrate --dry-run prints the same
report and changes nothing.
- It writes a journal,
config.toml.migrating, beside the config. - It writes the new store beside the 2.x store, as
store-v1.v3. - It writes a copy of the 2.x config,
config.toml.v2. - It renames the 2.x store to
store-v1.v2, and moves the new store into place. - It replaces the config with the new one in one step.
- It removes the journal.
The config path always holds the 2.x config or the new one. It deletes no
2.x file. It removes only its own journal and an unfinished
store-v1.v3.partial. It holds the lock that fleet init takes.
It refuses to run in these cases:
- A Fleet 2 manager holds the store's lease.
- With no journal,
config.toml.v2,store-v1.v2orstore-v1.v3already exists.
A run that stopped part way leaves the journal, and the next run completes from there. A run that finds a Fleet 3 config changes nothing.
A Fleet 2 config with no [data] dir names the data directory itself as its
store, for example ~/.local/share/fleet.
fleet migrate reads a Fleet 2 config only at the config path. If you moved
the 2.x files aside by hand and ran fleet init, it finds a Fleet 3 config
and changes nothing.
The new config is what fleet init writes, with these sections of the 2.x
config:
[forge]and[plugins], as they are.[forge.readyPolicies]gets the three shipped policies when the 2.x config has none.[gateway], when Fleet 3 accepts it. Otherwise the report says to copy it by hand.
The report names each key and table it does not copy, with the reason:
[runtime], [starter] and [workspaces].
The new store holds each Task, TaskConfig and EnvProvider of the 2.x store, with their names and labels, and without their status:
- A Task's
spec.workspacebecomes a list of URLs.{dir}becomes afile://URL. Each repository becomes agit+URL:git+file://on the checkout that[runtime.repositories]maps it to, elsegit+on its URL. A Task that had a session continues the branch that 2.x made, with?branch=. - A host other than
localbecomes the placemux/<host>. The report says to add[runtimes.mux.places.<host>]. spec.modelis removed, and the report says so.spec.dispatchisfalse: no session starts until you set it totrue.- A concluded Task, a Task that was being deleted, and the objects of other kinds are not imported. The report names each one. Its record stays in the 2.x store.
Resource commands #
apply -f - reads JSON from stdin. A file can hold one object, an array of
objects, or an object with items. Config uses versioned TOML; resource
manifests use apiVersion: fleet/v1alpha1. Use fleet --help and each
command's --help for the flags this build actually serves.
A worker writes its answer with fleet result TASK --generation N --outcome shipped --summary TEXT; the generation must match the delivered brief, and
required outputs must match the Task's declared schema. A result is a claim,
not proof of an artifact landing. fleet send TASK TEXT queues a message
for a running or concluded Task's session; the next reconcile delivers it
once, when the session is ready. fleet event publish adds an event to a
Board that every Task can read. fleet event list
reads a Board's events after a cursor, fleet event wait waits for the
next match, and fleet event watch follows the Board.
Tasks can reference a passive TaskConfig for harness, host, model and
environment defaults. EnvProvider resources supply stored string maps and
explicit manager-local JSON files or bounded commands. Explicit Task values
win; launch values are frozen privately before the first effect and reused
across retries and restarts. See execution configuration
for runnable manifests, precedence, security boundaries and snapshot recovery.
Register trusted protocol-1 controller programs under [plugins.<name>] in
the config. Their manifests add schema-validated resource kinds; fleet apply,
get, list, status and delete accept those kinds. Inspect registration
with fleet list plugins --json, and run their controllers with
fleet reconcile or fleet up. The
Plugin controller guide defines the
protocol, admitted operations, effect recovery and environment separation.
Plugins can create Tasks and, by default, steer only Tasks carrying their
creator label. Worker results remain the worker's responsibility. Plugin
programs run as the manager user; controller environment scrubbing is a
purity contract, not a sandbox.
Native Fleet configuration (fleet.toml) #
The native versioned TOML file selects a resource store, runtimes and hosts,
and the forges ChangeRequests are read from. It is separate
from the JSON Task,
TaskConfig,
EnvProvider and
ChangeRequest resources applied into that
store.
fleet apply takes no TOML as input, and --config applies no resources.
There is no [taskConfig], [envProvider] or task-template section in TOML.
The [telemetry] section configures
OpenTelemetry export.
File selection and paths #
Selection order is --config PATH, then FLEET_CONFIG, then one native path:
| Platform | Native configuration path |
|---|---|
| Linux | $XDG_CONFIG_HOME/fleet/config.toml, falling back to ~/.config/fleet/config.toml. |
| Windows | %APPDATA%\fleet\config.toml. |
Fleet does not search the current directory or parents. Explicit config paths
must exist, except fleet init --config PATH, which creates an isolated
instance without replacing an existing config. fleet init creates the
native config; see
initialization/customization
for data roots and per-instance paths.
Relative data.dir, runtime.dir, a fake forge host's
dir and a fake gateway account's dir resolve beside the TOML file. A
runtime executable should be a PATH name or absolute path;
runtimes.<name>.program is passed to process execution without rebasing it
beside TOML.
Provider source paths are always absolute and manager-local, even for remote
Tasks; they never inherit TOML's relative-path rule.
Runtimes and their places #
Where sessions run explains Fleets and places, and the setups they allow.
A runtime is a program that speaks the
runtime protocol. Each one is a
[runtimes.<name>] table. A place is where a runtime runs a process,
written <runtime>/<place>, and a Task names one in spec.host
(ADR-42):
version = 1
[data]
dir = "/home/me/.local/share/fleet/store-v1"
[runtimes.mux]
program = "runtime-mux"
callTimeoutMs = 10000
keyPrefix = "f0123456789abcdef01234567"
This is the runtime part of what fleet init writes: an absolute store
path, a keyPrefix derived from the config's path, and runtime-mux and
nothing else. init also writes the three shipped [forge.readyPolicies],
and the TaskConfig default and the Boards shared
and fleet into the store
(the default TaskConfig).
A runtime with no places table has one place, local, so this config has
one place, mux/local, also named local: this machine.
Fleet never falls back to another runtime. With no multiplexer on the
machine, the first start fails, naming the missing binary, and the Task's
Spawned condition says so. Another runtime is opt-in: add its table.
fleet runtime check -- <program> tells whether a program speaks the
protocol before a config names it.
A runtime declares its places inline, one table each:
[runtimes.mux]
program = "runtime-mux"
default = true
# this machine; spec.host = "local" or "mux/local"
[runtimes.mux.places.local]
# a machine over ssh; spec.host = "mux/devbox"
[runtimes.mux.places.devbox]
kind = "ssh"
destination = "me@devbox"
# a dynamic place: one new VM per key; spec.host = "vm/sandbox"
[runtimes.vm]
program = "runtime-vm"
[runtimes.vm.places.sandbox]
image = "agent-base"
- Fleet passes a place's table to the runtime in each request
(places) and does not
read it. The keys are the runtime's own.
runtime-muxtakeslocalwith no table, and remote places ofkind = "ssh"orkind = "wsl". localis the short form of<runtime>/localon the default runtime: the one withdefault = true, or the only runtime. Fleet refuses a config with several runtimes and no single default at load.- A default runtime whose
placestable has nolocal, such as one of VMs alone, leaveslocalnaming no place. Fleet refuses to apply a Task onlocal, and says why. A Task with nospec.hosttakes its TaskConfig's, elselocal, by the rule the manager launches it by; one whose TaskConfig is not there yet is not checked.fleet doctorwarns, andfleet runtime places --jsonhas"local": nulland alocalWhy. - A runtime or place name is 1 to 253 lowercase letters, digits,
-or.. - A place's table comes only from this file. The runtime trusts it.
- A runtime of protocol version 1 serves only
local, with no config: a Task on another of its places waits, unknown. fleet doctorfails a place its runtime reports not ready, with the runtime's why. It reads readiness by the same rule asfleet runtime places.fleet runtime places --jsonlists every place with what its runtime's manifest says of it:{"places": [{place, runtime, name, alias, platform, dynamic, ready, why}]}.placeis the id,<runtime>/<place>, andaliasis"local"on the placelocalnames.readyisnullwhen the runtime did not answer: its places are unknown, never absent.localis the idlocalnames, ornullwithlocalWhysaying why. With the fake[runtime],placesisnull.fleet runtime hosts --jsonlists the place ids a Task may name,localfirst and then each other place. thurbox's new-session flow reads it.fleet runtime browse <place> [dir] --jsonreads a place's folders through its runtime'sbrowseverb:{"dir", "entries": [{name, repo}]}, each subdirectory ofdirby name,repotrue on the top of a git work tree. Withoutdirit reads the place's home.fleet runtime branches <place> <repo> --jsonreads a repository's branches there throughbranches:{"names", "default"}.<place>islocalor<runtime>/<place>. Both only read, and a place the config does not define, a runtime whose manifest does not offer the verb, and a directory the runtime cannot read are errors that say why (browse and branches).
Remote places on runtime-mux #
A remote place of runtime-mux is a machine over ssh or a WSL distro. The
agent runs there, on that machine's multiplexer:
[runtimes.mux]
program = "runtime-mux"
[runtimes.mux.places.local]
# spec.host = "mux/nixos-hp"
[runtimes.mux.places.nixos-hp]
kind = "ssh"
destination = "nixos-hp"
ssh_opts = ["-o", "ControlMaster=auto", "-o", "ControlPersist=10m"]
path_prepend = ["~/.cargo/bin"]
# spec.host = "mux/ubuntu"; runtime-mux runs on Windows
[runtimes.mux.places.ubuntu]
kind = "wsl"
distro = "Ubuntu-24.04"
| Key | Default | Meaning |
|---|---|---|
kind |
required | ssh or wsl. |
destination |
required for ssh |
The ssh destination, such as me@devbox. ~/.ssh/config applies. |
ssh_opts |
[] |
ssh options before the destination. |
distro |
the place's name | The WSL distro, for wsl. |
multiplexer |
tmux |
The multiplexer on the place: tmux, psmux or rmux. |
platform |
posix, or windows with psmux |
The place's operating system. |
socket |
runtime-mux |
The multiplexer's socket on the place. |
session |
the default | The multiplexer's session name on the place. |
path_prepend |
[] |
Directories put first on the agent's PATH on the place, before its login PATH. Absolute or ~-rooted. |
runtime-muxrefuses any other key, and names it.- The place needs
ssh -o BatchMode=yes <destination> trueto succeed, tmux 3.2 or newer (or psmux), andfleetand the agent on itsPATH. Agit+workspace also needsworkspace-gitandgitthere, and a WSL place needsflock.fleet runtime placesandfleet doctorsay which one is missing, with the command that shows or fixes it. start,inspect,stop,pause,list,input,captureandexecrun on the place. A harness's hook files, such as pi's extension, are copied to the place at each start that names them.- A native-Windows place (
multiplexer = "psmux") runs the same verbs through PowerShell, and Fleet reads its agents' state there with the place's ownfleet.browse,branchesand workspace setup steps needsh, and are refused there by name. - A Task asks the runtime about its own place only. A place that does not answer is reported not ready after 8 s, and never holds up a Task on another place.
- A workspace on a remote place is made on the place by its own
workspace-git, under~/.local/share/runtime-mux/workspaces. Agit+URL names a repository as the place reaches it, and afile://URL a directory on the place. A release removes the worktree there and keeps its work as onlocal. - A WSL place stays running while its multiplexer's server runs:
runtime-muxkeeps onewsl.exewaiter attached to it (runtime-mux's places). fleet attach,fleet shell,fleet runtime browseandfleet runtime branchesread the place, so thurbox's new-session dialog picks a folder and a branch there.
A second Fleet installation on the same runtime needs a distinct
keyPrefix. Store and config must remain separate paths.
Fake runtime #
[runtime], a single table, configures the offline fake runtime for tests
and trials. It excludes [runtimes]: a file with both is refused. See the offline fake-runtime example.
Fields #
| Field | Required/default | Meaning |
|---|---|---|
version |
Required, 1 |
Native config schema; unsupported versions and unknown fields are refused. |
data.dir |
Optional | Resource store. --data-dir overrides it; otherwise Fleet uses its native data directory. |
runtimes.<name>.program |
Required for each runtime | The runtime's executable, a path or a bare name. Fleet looks for a bare name beside its own executable first, then on PATH, so a manager runs its own release's runtime. Fleet runs <program> [args] <verb> through its bounded spawner. |
runtimes.<name>.args |
[] |
Arguments before the verb. |
runtimes.<name>.callTimeoutMs |
15000 |
Bound for each call but workspace, 1 to 300000; the manager lease must outlast the runtime's reported worst case. |
runtimes.<name>.workspaceTimeoutMs |
600000 |
Bound for a workspace call, which can clone a repository. Unknown on timeout concludes nothing: the next pass asks again under the same key. |
runtimes.<name>.keyPrefix |
fleet |
The first part of every key Fleet gives the runtime, <keyPrefix>.<uid>; at most 32 lowercase letters, digits and -. |
runtimes.<name>.default |
false |
The runtime whose local place local names. Required on one runtime when there are several. |
runtimes.<name>.places.<place> |
one place, local |
A place of the runtime: a table Fleet passes to it in each request and does not read. A Task names it as spec.host = "<name>/<place>"; one naming a place no runtime has is unreachable and waits. |
runtime.kind |
Required when configuring [runtime] |
fake; excludes [runtimes]. |
runtime.dir |
Required for fake |
Isolated fake-host persistence, relative to this config file. |
--data-dir is for explicit store operations. fleet up rejects a differing
override because its workers must share the store selected by the persisted
config. Persist data.dir before using up with a different store. All
resource commands in one workflow should use the same --config path.
fleet up reads this file once, when it starts. A change to it applies at
the next start: a running process never switches its store, lease holder,
runtime or key prefix.
Each runtime makes the workspaces of the hosts it serves, from the URLs a Task names (workspaces).
Every session Fleet starts gets FLEET_SIGNAL_FILE, FLEET_HARNESS and
FLEET_HARNESS_DIR, the directory below
(signal contract). On local, the signal file is
under <data dir>/signals. On any other place, it is
~/.local/state/fleet/signals/<key>.jsonl on that place, and Fleet reads
it through the runtime's exec.
The harnesses/ directory beside the config file holds the user's
harness profiles, one *.toml file
each. Every command that loads the config reads them at start, and a file
that does not parse stops the command with its path. fleet signal and
fleet version skip such a file instead. A user profile replaces the
bundled profile of the same name, or adds a harness. A Task whose launch
is frozen (it names a TaskConfig or an env) keeps the profile's
[launch] env as it was when the launch was resolved.
Runtime-specific fields apply only to that runtime. Keep the store and native configuration user-private; they contain literal manifests and private launch snapshots. Windows snapshots inherit the store's ACL, while Unix launch storage enforces owner-only permissions. See privacy and retention.
Offline fake-runtime example #
version = 1
[data]
dir = "data"
[runtime]
kind = "fake"
dir = "fake-host"
This is the executable example config. Fake sessions run no agent, although explicitly configured external EnvProvider commands still execute locally. Do not treat the fake runtime as a sandbox for untrusted helpers.
fleet --config examples/fleet/fleet.toml apply -f examples/fleet/resources.json
fleet --config examples/fleet/fleet.toml list tasks --json
fleet --config examples/fleet/fleet.toml reconcile
For the new resources, save the manifests in their individual references, then use the same explicit config for each operation:
fleet --config fleet.toml apply -f env-provider.json
fleet --config fleet.toml apply -f task-config.json
fleet --config fleet.toml apply -f task.json
fleet --config fleet.toml reconcile
Apply uses JSON resources. File/command provider output uses a third format:
environment JSON maps. Keep source credentials out of
resource manifests. Config schema 1, resource API fleet/v1alpha1 and store
format 1 are separate version contracts; fleet version --json reports
them. A repeated fleet init keeps the user-owned native config, the
TaskConfig default and the Boards shared and fleet when the store holds
them.
The [forge] section #
The forges that ChangeRequests are mirrored from. Without this section a ChangeRequest is refused at apply, and one already stored is reported by the manager and never polled.
[forge]
callTimeoutMs = 15000
closedGraceMs = 604800000 # one week; a ChangeRequest spec may override
settledTtlMs = 2592000000 # thirty days; a ChangeRequest spec may override
relayNotes = true # defaults a Task's spec.forge.relay may override
relayChecks = true
relayBots = false
noCheckGraceMs = 300000 # the checksPassed predicate's wait for a check
draftPolicy = "checks" # omit to never take a draft out of draft
[forge.hosts]
"github.com" = { kind = "github", cli = "gh" }
"gitlab.com" = { kind = "gitlab", cli = "glab" }
"gitlab.example.com" = { kind = "gitlab", cli = "glab" }
"dev.azure.com" = { kind = "azure-devops", cli = "az" }
"bitbucket.org" = { kind = "bitbucket-cloud", cli = "curl" }
[forge.readyPolicies.checks]
checksPassed = true
[forge.readyPolicies.checks-and-bots]
botReviewsAddressed = true
checksPassed = true
[forge.readyPolicies.strict]
botReviewsAddressed = true
checksPassed = true
noUnresolvedThreads = true
| Field | Required/default | Meaning |
|---|---|---|
forge.callTimeoutMs |
15000 |
Bound for each forge CLI call. One observation of a change may make up to six such calls, and the manager lease is raised to outlast the port's reported worst case. |
forge.closedGraceMs |
604800000 |
How long a closed change stays watched before it settles. |
forge.settledTtlMs |
2592000000 |
How long a settled ChangeRequest is retained before its controller deletes it. |
forge.relayNotes, forge.relayChecks |
true |
Whether the Forge controller relays new notes, and passed or failed checks, to a Task's worker. A Task's spec.forge.relay overrides each. |
forge.relayBots |
false |
Whether bot-authored notes are relayed to the worker. A selected policy that waits on bots relays their blockers regardless. |
forge.noCheckGraceMs |
300000 |
How long checksPassed waits, from a head's first observation, for a check to appear before treating that checkless head as passed. |
forge.draftPolicy |
Absent | The ready policy applied to a Task that sets none; it must name a policy below. Absent: a draft is never taken out of draft unless the Task names a policy. |
forge.readyPolicies.<name> |
Three written by fleet init |
A set of the predicates the Forge controller defines (checksPassed, botReviewsAddressed, noUnresolvedThreads, forgeMergeable; workerDone and workerIdle are always on), under a name that is only a key. Any other key is refused at load. |
forge.hosts.<host> |
One per forge host | kind is azure-devops, bitbucket-cloud, github, gitlab or fake; cli is a PATH name or absolute path (az, curl, gh or glab by default); a fake host takes dir, its directory, relative to this file. Configure dev.azure.com once for hosted Azure DevOps Services; its {organization}.visualstudio.com aliases route to that adapter. bitbucket-cloud is accepted only for bitbucket.org; Server/Data Center is a different API. A URL on any other unlisted host is refused at apply. |
Credentials stay with each external client's own configuration. Fleet passes
none to the forge and stores none. Azure DevOps login is resolved separately
for each organization; Fleet never reads or writes a PAT, token, subscription
or CLI default.
Bitbucket Cloud has no official CLI boundary here: Fleet runs bounded HTTPS
GETs through curl --netrc-optional and relies on curl's externally managed
config, netrc or credential helper. Fleet never constructs an Authorization
header, username, password or token. The client must be able to read
/2.0/user, pull requests, comments, pull-request commit statuses and
mergeability checks. Draft observation is supported, but mark-ready fails
closed because Bitbucket's PUT draft=false has no atomic head-and-state
precondition.
fleet init writes the three readyPolicies tables above into
the generated config and no draftPolicy: a Task is marked ready only once
it, or the operator's config, names a policy. The shipped
example config adds a fake host,
forge.example, with draftPolicy = "checks" and the same three policies,
so a declared draft can be taken out of draft offline.
Supported forges #
Fleet has one adapter for each forge in this table. To follow a change, the adapter reads its checks, review threads, notes and merge state. The Forge controller relays news from them to the worker. Mark ready takes a draft out of draft. Fleet does not check a minimum client version.
| Forge | Client | Follow | Mark ready | [forge.hosts] entry |
Self-hosted |
|---|---|---|---|---|---|
| GitHub | gh api graphql |
Yes | Yes | "github.com" = { kind = "github", cli = "gh" } |
Yes: GitHub Enterprise Server, under its own hostname |
| GitLab | glab api |
Yes | Yes | "gitlab.com" = { kind = "gitlab", cli = "glab" } |
Yes: a self-hosted GitLab, under its own hostname |
| Azure DevOps | az devops invoke, REST 7.1 |
Yes | No | "dev.azure.com" = { kind = "azure-devops", cli = "az" } |
No: Azure DevOps Services only. Azure DevOps Server is not supported. |
| Bitbucket Cloud | curl, REST 2.0 |
Yes | No | "bitbucket.org" = { kind = "bitbucket-cloud", cli = "curl" } |
No: bitbucket.org only. Bitbucket Data Center is not supported. |
- Azure DevOps and Bitbucket Cloud have no atomic head-and-state check on the draft update. Fleet refuses mark ready on them.
- GitLab marks a merge request ready when Fleet removes the draft marker from its title. Fleet refuses a draft whose title has no marker.
- On Azure DevOps and Bitbucket Cloud, reviewer votes set only the review decision. Azure DevOps marks no note as a bot's.
The adapter truth tables give each field's mapping.
Fleet ships these four.
[plugins] section #
The Plugin controller registers each plugin here, operator-owned.
[plugins.github-issues]
program = "/usr/local/bin/node"
args = ["/opt/fleet-plugins/github-issues/dist/plugin.js"]
cwd = "/opt/fleet-plugins/github-issues"
callTimeoutMs = 15000
tasks = "own" # or "any"
passEnv = ["GH_TOKEN"]
envFrom = [{ name = "github-issues-env" }]
| Field | Required/default | Meaning |
|---|---|---|
plugins.<name> |
One per plugin | The key is the plugin's name; the manifest's name must equal it. |
program |
yes | Absolute path of the program on the manager, as for an EnvProvider command source: no PATH search, no shell, no rebasing beside TOML. |
args |
[] |
Arguments before the call name the host appends. |
cwd |
yes | Absolute working directory on the manager. |
callTimeoutMs |
15000 |
Bound for each plugin process, 1 to 300000; the tree is killed past it, and the manager lease is raised to outlast the port's reported worst case. |
tasks |
"own" |
Which Tasks the plugin may patch, delete, send to or declare on: own, those carrying its fleet.dev/plugin label, or any. Creating a Task needs no permission beyond this entry. |
passEnv |
[] |
Variables copied from the manager's environment into the plugin's observer calls only. |
envFrom |
[] |
EnvProviders whose merged map reaches the observer calls only, resolved per sweep through the provider machinery TaskConfig uses; a provider's command source runs under the same bounds and lease rule. |
The controller calls, manifest, probes and reconcile, receive none of
these variables. Values never reach the store, a status or argv. Programs run
on the manager with the manager's user; register only programs you intend
Fleet to execute, as for EnvProvider command sources.
The [gateway] section #
The installed binary reads and validates this section, reads each route's
brief with it, and opens its accounts before a manager run;
ConversationController starts Tasks from its routes, and GatewayController
ties, relays, posts, logs and reacts. The
Gateway controller reads its chat
accounts, people and routes from here, as the Forge controller reads
[forge.hosts].
[gateway]
callTimeoutMs = 15000
pollMs = 300000 # history backstop for tied threads
activeMs = 86400000 # ... while the thread had a message this recently
retainMs = 604800000 # seven days: an idle thread's retention, then it retires
beatMs = 60000 # a listener beats at least this often; stale after three
questions = "eng" # the route whose first channel id takes Questions from untied Tasks
logs = { account = "slack-main", channel = "C0456EFGH" } # every Task's Drafts, result and change news
reactions = { queued = "hourglass_flowing_sand", working = "eyes", replied = "white_check_mark" } # the defaults; `reactions = false` turns them off
[gateway.accounts.slack-main]
platform = "slack"
team = "T0123ABCD" # the team, or the enterprise id in an Enterprise org
bot = "U0BOT0001" # Fleet's bot user id, checked against the platform's answer
inbound = "socket-mode" # how the listener receives and authenticates deliveries
cli = "curl"
curlConfig = "/etc/fleet/slack-curl.conf" # operator-owned; holds the bot token header
[gateway.accounts.discord-main]
platform = "discord"
team = "1200000000000000000" # the guild id
bot = "1210000000000000000" # the bot user's snowflake
inbound = "discord-gateway" # the listener holds the Gateway WebSocket
messageContent = false # true only when the application holds MESSAGE_CONTENT
curlConfig = "/etc/fleet/discord-curl.conf" # holds "Authorization: Bot <token>"
[gateway.people.alex]
slack-main = "U0123ABCD" # one platform id per account
discord-main = "1220000000000000000" # a user snowflake, never a username
[gateway.people.sam]
slack-main = "U0456EFGH"
[gateway.routes.eng]
account = "slack-main"
channels = ["C0123ABCD"]
mention = "required" # a new thread needs a mention of Fleet's bot
allow = ["alex", "sam"] # names under [gateway.people]
taskConfig = "conversation" # a TaskConfig resource: harness, host, model, env
brief = "/etc/fleet/briefs/conversation.md"
workspace = { base = "/work/conversations" } # a base: each thread gets /work/conversations/<conversation name>
refusal = "Sorry, I only take requests from people on this channel's list."
[gateway.routes.alerts]
account = "slack-main"
channels = ["C0789IJKL"]
mention = "top-level" # every top-level post starts a Task
allow = ["alex", "sam"]
allowBots = ["B0123ABCD"] # the alerting app whose posts are requests
taskConfig = "conversation"
brief = "/etc/fleet/briefs/triage.md"
workspace = { base = "/work/triage" } # a base: each alert's thread gets its own directory
[gateway.routes.anywhere]
account = "slack-main"
channels = ["*", "dm:*"] # the wildcard: every other channel the bot is in; the DM entry: every DM with the bot
allow = ["alex", "sam"] # mention = "required", the only mention a wildcard route takes; a DM needs none
taskConfig = "conversation"
brief = "/etc/fleet/briefs/conversation.md"
workspace = { base = "/work/anywhere" }
| Field | Required/default | Meaning |
|---|---|---|
gateway.callTimeoutMs |
15000 |
Bound for each adapter call, 1 to 300000; the manager lease is raised to outlast the port's reported worst case. |
gateway.pollMs |
300000 |
How often a Tied Conversation reads its history as a backstop for events a listener missed, where the account has history. A Conversation's spec.pollMs overrides it for that thread. It is also the interval at which a create waiting under WorkspaceBusy, for a thread's directory that another Task holds, is planned again, the cap on the recovery-read backoff, and how often a Listener asks whoami and capabilities. |
gateway.activeMs |
86400000 |
How long after a Tied thread's last message its history backstop keeps polling. |
gateway.retainMs |
604800000 |
How long a thread is kept with no message, counted from the later of its last message and its orphaning. Past it, a thread that is Untied, Orphaned or tied to a Concluded Task retires: Fleet deletes its Task, the thread directory that the manager created, and its Conversation. A thread with a running Task is kept. |
gateway.beatMs |
60000 |
The longest a listener goes between beats. An account's InboundReady turns False when three are missed. |
gateway.questions |
Absent | The route whose first channel id takes a new thread for a Question declared by a Task with no tie and no parent. A Task's gateway.fleet.dev/route label overrides it. Absent and unlabelled: such a Question is not posted. Refused when the route lists no channel id, as a route with only "*" or "dm:*" does. |
gateway.logs |
Absent | The log destination: account, a name under [gateway.accounts], and channel, one channel id on it. Fleet posts every Task's Drafts, result and change news there, as top-level posts. Absent: Fleet posts them nowhere; a tied thread's ready and answered notices are posted either way. Refused when the account is not configured, when the account's adapter cannot read the channel id, or when a route of that account lists the channel. A wildcard route never covers the log channel. |
gateway.reactions |
On: queued = "hourglass_flowing_sand", working = "eyes", replied = "white_check_mark" |
The reactions that mark a person's message: queued while admission holds the request for its Task, working once the Task exists or Fleet relayed the message to it, when queued is removed, and replied once Fleet posted in the thread, when working is removed. Each is a platform emoji name, which each adapter maps as its adapter page says. A name left out keeps its default. false turns reactions off, and true keeps the defaults. Refused when a name is empty or holds whitespace, when two name one emoji, or for another key. |
gateway.accounts.<name> |
One per chat account | platform is slack, discord, or fake with a dir; any other platform is refused when the manager runs; team the platform's workspace identity (Slack: the team or enterprise id, optional; Discord: the guild id, required); bot, Fleet's bot id there, which the adapter's pure event reading uses to tell Fleet's own posts and mentions apart (Discord: a snowflake, as is team); inbound, required, the one way its listener receives deliveries, which fixes how each is authenticated (Slack: socket-mode, an authenticated connection, or events-api, a signed HTTPS delivery; Discord: discord-gateway, an authenticated connection; fake: connection), and an envelope claiming another is refused; messageContent, Discord only, default false, whether the application holds the privileged message content intent, which sets the intents that fleet gateway account prints; cli, default curl, and the platform's credential reference, here curlConfig, required for Slack and Discord, an absolute path Fleet passes to curl -K and never reads. The Slack and Discord adapter pages list each platform's keys and errors. |
gateway.people.<name> |
Optional | A person, with one platform id per account name. Ids only: never a display name, username or email. |
gateway.routes.<name> |
One per set of channels | account; channels, platform channel ids, "*", the wildcard, or "dm:*", the DM entry (see below); mention, required or top-level; allow, people names; allowBots, bot or app ids whose messages count as a person's; taskConfig, the TaskConfig a new conversation Task references; brief, an absolute path the manager reads when it loads the config and copies into each Task it creates; workspace, the Task's workspace: {base}, an absolute base directory, below which each thread's Tasks get ["file://<base>/<conversation name>"], the directory created by the manager with the Task on the TaskConfig's host, recorded on the Conversation, and removed when the thread retires; Fleet never removes a directory it did not create or the base directory; a thread waits only while another Task holds its own directory, and no two routes' base directories may equal or contain each other; or a list of absolute URLs, which each Task gets as it is and its runtime makes for it, so a route's Tasks share nothing (a git+ URL gives each Task its own worktree); refusal, the one polite refusal. A channel id belongs to at most one route. A route lists at least one channel and names at least one person in allow or one bot in allowBots. |
A wildcard route has "*" in channels. It covers every channel of its
account that the account's listener delivers, with these exceptions:
- A channel id that another route of the account lists belongs to that route.
- The
gateway.logschannel belongs to no route.
These rules apply to a wildcard route:
- An account has at most one wildcard route.
- A wildcard route needs
mention = "required". Reason:top-levelmakes every top-level post a request, which suits one alert channel only. allow,allowBotsandrefusalapply as on any route.- A wildcard route can also list channel ids. The first id is the channel where the route opens a thread for a Question.
A DM route has "dm:*", the DM entry, in channels. The DM entry covers
every one-to-one direct message between the bot and a user of the account,
with these exceptions:
- A channel id that a route of the account lists belongs to that route.
- The
gateway.logschannel belongs to no route.
A DM is a one-to-one direct message only when the account's adapter says so. A group DM is not one. A group DM is a channel, and the wildcard covers it under the mention rule.
These rules apply to a DM route:
- An account has at most one DM route.
- In a thread that the DM entry covers, a message that starts the thread
starts a Task without a mention. A message that mentions Fleet also
starts one. The route's
mentionapplies only to its channels. - In such a thread, a top-level message from a person who is not on
allowearns the route's refusal, once per thread. allow,allowBotsandrefusalapply as on any route.- A route can hold both
"*"and"dm:*", and also list channel ids. - A Discord account refuses the DM entry. Reason: the Discord adapter ignores every DM.
The adapter pages say which conversations each platform delivers, and which are DMs.
Credentials stay with the external client: Fleet passes the curl config's path and never constructs an Authorization header. The listener holds the platform's connection token itself. TaskConfig defines no brief or workspace, so a route carries both.
Environment JSON file and command output #
An EnvProvider file source reads a UTF-8 JSON object whose values are strings. Command sources must emit this same format on stdout and exit zero. This is environment data, separate from Fleet's native TOML configuration and JSON resource manifests.
Save this example as agent-env.json in a private manager-local directory:
{
"PROJECT_MODE": "review",
"GREETING": "bonjour = 🌍",
"MULTILINE": "first line\nsecond line"
}
| Rule | Accepted input |
|---|---|
| Shape | One JSON object of string values; empty {} is valid. |
| Names | [A-Za-z_][A-Za-z0-9_]*; no case collisions such as Path and PATH. |
| Values | Strings, including empty strings, Unicode, spaces, = and newlines; never NUL. |
| Source size | At most 64 KiB of file/command bytes. |
| Map/merged size | Total UTF-8 key and value bytes at most 64 KiB. |
Arrays, nested objects, numbers, booleans and null values are refused. The
same key/value rules apply to literal EnvProvider data, TaskConfig env
and Task env. Across maps, later values replace case variants and retain
the winning spelling on every platform. See
the complete precedence.
A file must be a regular file at an absolute path on the manager. There is no lookup beside the TOML config, resource manifest, Task workspace or remote host. Use a native path; Windows backslashes must be escaped inside the provider's JSON manifest. A missing, unreadable, nonregular, malformed or oversized file prevents launch. Source parse errors never echo its content.
External files may contain credentials: restrict their access and exclude them from public repositories. Fleet freezes their resolved values in a private plaintext launch snapshot; protect store backups as well. Editing the file affects future resolutions, not already frozen Tasks. Follow the snapshot recovery rules for an existing execution; there is no background refresh.
OpenTelemetry export #
The [telemetry] section and the standard OTEL_* environment variables
turn on OpenTelemetry export. An OTEL_* variable that is set wins over the
section's value for that variable.
Observability owns the keys, the variables, the
spans, the metrics and the guarantees of the export, for Fleet and every
other program.
The [telemetry] section #
[telemetry]
endpoint = "http://localhost:4318"
headers = { file = "/run/user/1000/otel-headers" } # holds key=value,...; never the secret here
resource = { "service.namespace" = "fleet", "deployment.environment.name" = "local" }
Each fleet command reads the section: fleet up, fleet reconcile, and a
one-shot command that an agent's hook or a shell runs. Fleet gives the
values in force to each runtime-mux call and to each agent that it
starts (coding agents). The keys and
their rules are in Config files.
fleet doctor shows the export in force, and where each value comes from.
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 fleet up # a variable wins over the section