Repository navigation
10 Operations
Generated from
docs/at cded12f. Edit the source in the repository, not this page.
This chapter is for the person who installs and looks after a mirafleet deployment. It gives a
complete walk-through for MIRASTACK LABS, a reference for every command, the files each machine keeps, how
to write actions.yaml, and a table of error messages with fixes.
- The M7 set-up: a host-mode runner VM, credentials, the secrets key, rotation, the corporate CA, cleanup and a troubleshooting table (section 10.13).
- How to install and run central, a runner and an operator, step by step, with the output you should see.
- Every
mirafleetcommand and flag, and which machine each one runs on. - What files live where, with their permissions, and what each one is for.
- How to write
actions.yamlsafely. - How to read an error message and know what to do about it.
- How to back up, restore and upgrade central, and what to do if its host key is lost.
-
Workspace mode (M3): the
workspace.yamlreference, containerd on a Docker host, the OpenSandbox option with its TLS front, every new command and flag, the on-disk layout, pruning and troubleshooting (section 10.9). -
The orchestrator side (M5): setting up a laptop on Linux, macOS or Windows,
mcp login, contexts, the Claude Code plugin, opencode and other harnesses, and a troubleshooting table for the MCP server (section 10.10). -
The admin GUI (M4): the first-start setup, where the GUI listens by default and how to
restrict it, certificates and fingerprints,
-gui-host, a reverse proxy, recovery withreset-admin, sessions, and a troubleshooting table (section 10.11). - The M6 additions: choosing an install channel, what the Linux package sets up, firewalling the GUI, Compose, verifying checksums, signatures and provenance, upgrade order, the automatic backup, rollback, and install troubleshooting (section 10.12).
Status: M1 to M5 and M7 (host mode) are built; M6 (release,
v0.6.0) is done. Sections 10.2 to 10.11 and 10.13 run the binary by hand, which still works; packages, systemd units, the image and Compose are in section 10.12 and the M6 plan (PLAN.md).mirafleet mcp(no arguments) is the MCP server that Claude Code and other agents talk to;mirafleet mcp login,contextandapiare the human operator tools. Where the guide shows something planned, it says so.Want to see it all work before reading on? Section 9.11 runs central, a runner and an operator in one throwaway container.
MIRASTACK LABS has one central server and two fleets.
| Thing | Name |
|---|---|
| Central |
central.example.com, SSH port 2222
|
| Fleets |
dev, prod
|
| Runners |
build-1 (in dev), db-1 (in prod) |
| Admin | aarvee, who runs mirafleet central ... on the central host and, since M4, can use the admin GUI at https://central.example.com:8443
|
| Operators |
durga, kalyan (people or agents on laptops; registered keys, not Linux accounts) |
Who runs what:
| Machine | OS | Binary role | Network need |
|---|---|---|---|
central.example.com |
Linux | mirafleet central |
accepts TCP 2222 from runners and operators, and TCP 8443 (HTTPS) from the admin's browser; see 10.11 for how to restrict 8443 |
build-1, db-1
|
Linux | mirafleet runner |
outbound only: connect to central:2222; no open port |
| durga's and kalyan's laptops | Linux, macOS, Windows (amd64 and arm64) | mirafleet mcp |
outbound to central:2222 |
Central and runner refuse to start on other operating systems:
mirafleet: mirafleet central is supported on linux only (current: darwin).
Firewall note. Central has built-in limits (connection caps, enrol rate limits, handshake deadlines) but they are a backstop, not DoS protection. If central is reachable from the internet, put a firewall or rate limiter in front of port 2222. Better still, allow only your runner and laptop address ranges. Since M4, central also listens on port 8443 (the admin GUI) on all interfaces by default. Decide on day one who may reach it (section 10.11).
Build it with the container toolchain (see chapter 9):
scripts/dev.sh shell
# inside the container (the target must match the machine you copy it to):
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o dist/mirafleet ./cmd/mirafleet(/dist/ is git-ignored.) Change GOOS/GOARCH for other machines, for example
darwin/arm64 for an Apple-silicon laptop that only needs mirafleet mcp.
Release archives, packages and install.sh are in 10.12.
To use the binary you just built, copy it to /usr/local/bin/mirafleet on every machine, and check:
$ mirafleet version
devOn central.example.com, as the user that will run central (here root, or a dedicated
mirafleet user that owns /var/lib/mirafleet):
$ mirafleet central init -listen 0.0.0.0:2222
data dir: /var/lib/mirafleet/central
host key: /var/lib/mirafleet/central/host_ed25519
fingerprint: SHA256:Qm9ndXNFeGFtcGxlRmluZ2VycHJpbnRPbmx5Rm9yRG9jcw
listen: 0.0.0.0:2222
created the registration secret
next: mirafleet central run -data /var/lib/mirafleet/central -listen 0.0.0.0:2222(The fingerprint above is a made-up example.) init is offline and idempotent: it
creates the data directory (mode 0700), generates central's SSH host key once, creates the
database and its tables, and generates the registration secret once. Running it again prints
already initialised; registration secret kept and changes nothing. Note down the fingerprint;
you can compare it later with what operators see. -listen here is only used for the hint line;
init does not open a port.
$ mirafleet central run -listen 0.0.0.0:2222 &
central listening on 0.0.0.0:2222, admin socket /var/lib/mirafleet/central/admin.sockSince M4 the same command also starts the admin GUI on 0.0.0.0:8443 and logs its address,
its certificate fingerprint and a notice about the bind (section 10.11 shows the lines). If you
do not want a GUI at all, add -gui-listen off.
Central logs to stderr; run it under a service manager so it restarts and its log is kept. Only
one central may use a data directory: a second one fails with
another central is already using /var/lib/mirafleet/central (lock ... is held). Stop it with
Ctrl-C or SIGTERM; it shuts down cleanly.
An example systemd unit (illustrative only; the real unit ships with the M6 packages):
[Unit]
Description=mirafleet central
After=network-online.target
[Service]
User=mirafleet
ExecStart=/usr/local/bin/mirafleet central run -data /var/lib/mirafleet/central -listen 0.0.0.0:2222
Restart=on-failure
[Install]
WantedBy=multi-user.targetWho may run the admin commands? Every other mirafleet central ... command talks to
the local admin socket admin.sock in the data directory. Central accepts only connections
from the same Unix user that runs central (it checks the connecting process's user ID before
reading anything), and the data directory is mode 0700. So run admin commands as that same user,
for example sudo -u mirafleet mirafleet central fleet list.
$ mirafleet central fleet create dev
fleet dev created (mode actions, confirm false)
$ mirafleet central fleet create prod -confirm
fleet prod created (mode actions, confirm true)
$ mirafleet central fleet list
FLEET MODE CONFIRM RUNNERS
dev actions false 0
prod actions true 0-confirm makes prod a guarded fleet: every action.run against it must carry
"confirm": "prod" (the fleet name). It stops an agent from running something on prod by
accident, because the caller has to say the name on purpose. The check is enforced on central.
-mode workspace can be created, but workspaces arrive in M3; today only actions fleets can
run actions.
$ mirafleet central token create -fleet dev
mfj1.3f9a1c07b2d84e65.<43 characters>.<43 characters>
token 3f9a1c07b2d84e65 for fleet dev, expires 2026-11-14T10:15:00Z; shown once, store it nowThe token itself goes to stdout (so you can pipe it) and the note goes to stderr. It is
shown exactly once; central keeps only a hash. By default a token is single-use and lives 24
hours. Useful options: -uses 5 (up to 1000 runners), -ttl 2h (up to 30 days),
-approve (runners join already active, skipping step 7), -labels role=build,region=eu.
Treat the token like a password until it is used: anyone holding it can enrol a runner into the fleet. Send it over a channel you trust.
On build-1, as the user that will run the runner (needs write access to its data directory).
The default data directory depends on who you are: root: /var/lib/mirafleet/runner; other
users: $XDG_CONFIG_HOME/mirafleet. The packaged mirafleet-runner.service runs as the
mirafleet user with -data /var/lib/mirafleet/runner, so when you join as that user you must
pass the same -data:
$ echo "$JOIN_TOKEN" | sudo -u mirafleet mirafleet runner join central.example.com:2222 -name build-1 -data /var/lib/mirafleet/runner -token -
joined fleet "dev" as runner "build-1": status pending
an admin must approve this runner on central before it can run actions
next: start it with `mirafleet runner run -data /var/lib/mirafleet/runner` (under systemd; the unit ships with the M6 packages)Notes:
- The token is read from stdin (
-token -), not as an argument to mirafleet itself, because the arguments of a running program are visible to every user on the machine (ps) and are saved in shell history. (echois a shell built-in, so the token never appears in another program's arguments either.) It is not read from the environment for the same reason. - The token contains a hash of central's host key. The runner uses it to check it is really talking to your central before sending anything. There is no "trust on first use" prompt.
- The runner generates its own key pair; the private key never leaves the machine.
- A data directory can join only once. A second try fails with
this data directory has already joined a central (runner.yaml exists); use a fresh -data directory.
Write /etc/mirafleet/actions.yaml (see section 10.5 for the format). A minimal one:
actions:
hello:
run: ["/bin/echo", "hello", "{{name}}"]
params:
name: { pattern: "[a-z]{1,8}" }
disk-usage:
run: ["df", "-h", "{{path}}"]
params:
path: { pattern: "/|/var|/home", default: "/" }Then start the runner:
$ mirafleet runner run -actions /etc/mirafleet/actions.yaml
runner "build-1" (fleet dev) -> central.example.com:2222, actions: disk-usage,helloIt dials out, keeps one SSH connection, heartbeats every 15 seconds and reconnects with exponential backoff (1 s up to 60 s) if the connection drops. The actions file is read once at start: restart the runner after editing it. A bad file stops the runner at start with an error naming the action, so mistakes show up immediately.
Back on central:
$ mirafleet central runner list
RUNNER STATUS ONLINE LAST SEEN LABELS
dev/build-1 pending true 2026-11-13T10:16:02Z -
$ mirafleet central runner approve dev/build-1
dev/build-1: activeA pending runner can connect and heartbeat but central will not send it work. Approving takes
effect on the live connection immediately; the runner does not need a restart. Other
lifecycle commands: disable (stop new work, let running work finish; reversible with
enable) and revoke (permanent: cancels running work, kicks the runner, its key can never
rejoin). Use -approve on token create if you trust the token holder enough to skip this step.
$ mirafleet central exec dev/build-1 hello name=world
hello worldcentral exec is the admin's way to run an action with no operator involved (it is audited with
source cli). Its exit code is the action's exit code. For a guarded fleet, add
-confirm prod.
$ mirafleet central operator code
code: mfr1.<26 characters>.<43 characters>
valid for: 42s
host key: SHA256:Qm9ndXNFeGFtcGxlRmluZ2VycHJpbnRPbmx5Rm9yRG9jcwThe code changes every 60 seconds, so it is only useful for a short time; it is derived from the
registration secret and the clock. Any number of operators may use one code within its window.
aarvee hands it to durga over a channel they trust (a call, a chat to the person). The host key line is
the fingerprint of central's key, so the person can double-check out of band.
On durga's laptop:
$ echo "$REGISTRATION_CODE" | mirafleet mcp login central.example.com:2222 -name durga -code -
registered operator "durga" (active); context "durga" -> central.example.com:2222 is now current
config: /home/durga/.config/mirafleetThis generates durga's key pair (first time only), connects with the host key pinned from the
code, registers their public key under the name durga, saves central's key into known_hosts
and records a context (name plus address) in contexts.yaml. kalyan does the same with
-name kalyan. There is no approval step for operators: a valid code is the approval.
$ mirafleet mcp api fleets.list
{
"fleets": [
{
"name": "dev",
"mode": "actions",
"confirm": false,
"runners": 1
},
{
"name": "prod",
"mode": "actions",
"confirm": true,
"runners": 0
}
]
}
$ mirafleet mcp api runners.list '{"fleet":"dev"}'
{
"runners": [
{
"name": "build-1",
"status": "active",
"online": true,
"last_seen": "2026-11-13T10:17:31Z"
}
]
}
$ mirafleet mcp api action.run '{"fleet":"dev","runner":"build-1","action":"hello","params":{"name":"world"}}'
{
"exit_code": 0,
"stdout": "hello world\n",
"stderr": "",
"duration_ms": 4,
"request_id": "9c1f0e5b7a3d4f2e8b6a1c0d9e8f7a6b"
}Now the guarded prod fleet. Suppose db-1 joined prod the same way as build-1 joined
dev (steps 4 to 7), its actions.yaml has a tail-logs action (see 10.5), and kalyan has
registered like durga. prod was created with -confirm, so every call must carry
"confirm":"prod":
$ mirafleet mcp api action.run '{"fleet":"prod","runner":"db-1","action":"tail-logs","params":{"lines":"200"},"confirm":"prod"}'
{
"exit_code": 0,
"stdout": "Nov 13 10:20:01 db-1 postgres[812]: checkpoint complete\n...",
"stderr": "",
"duration_ms": 6,
"request_id": "9f1c4b7a2d0e8635a1c9b4d7f3e2e07a"
}Without the confirm field the call fails with bad_request before anything runs (section
10.6). Methods available to operators: hello, fleets.list, runners.list, action.run and
the workspace.* methods. Nothing else is possible from a laptop, by design: approving runners,
making tokens and revoking things only work on central. mcp api is the hand-driven way to call
them. Claude Code (and other agents) call the same methods through MCP tools, which is what
section 10.10 sets up.
aarvee looks at what kalyan's tail-logs call left behind:
$ mirafleet central audit -since 1040 -limit 2
ID TIME SOURCE ACTOR ACTION TARGET OUTCOME MESSAGE
1041 2026-11-13T10:20:01Z api operator:kalyan action.run prod/db-1 start
1042 2026-11-13T10:20:01Z api operator:kalyan action.run prod/db-1 ok(The message column is empty for these rows. Both rows carry the same request_id,
9f1c...e07a; the table does not print it, -json does, and the start row also records the
parameters, lines 200. Events come oldest first, so -limit 2 alone shows the first two
ever recorded; use -since ID to page forward: -since 1042 shows only later events, handy
for polling. -json gives machine-readable output.) Each runner also keeps its own
audit.jsonl; see section 10.4.
mirafleet has one binary and four top-level commands: central, runner, mcp, version.
Usage errors print mirafleet: usage error: .... Commands that take a secret read it from stdin
and require the flag value -.
Prints the version string (dev for a source build).
All admin commands accept -data DIR (central's data directory, default
/var/lib/mirafleet/central) and find admin.sock inside it. Flags may come before or after
positional arguments. FLEET/RUNNER is a fleet name, a slash and a runner name. Names must match
^[a-z0-9][a-z0-9._-]{0,62}$ (lowercase letters, digits, ., _, -; at most 63 characters).
| Command | Flags | What it does |
|---|---|---|
central init |
-data DIR, -listen ADDR (default 0.0.0.0:2222) |
Create the data dir, host key, database and registration secret. Offline, idempotent. -listen only appears in the hint. |
central run |
-data DIR, -listen ADDR (default 0.0.0.0:2222), and the GUI flags: -gui-listen ADDR|off (default 0.0.0.0:8443), -gui-cert FILE -gui-key FILE (both or neither), -gui-host NAME,... (repeatable), -advertise HOST:PORT
|
Run central: SSH server, admin socket and (unless -gui-listen off) the admin GUI, until SIGINT/SIGTERM. Takes the data-dir lock. Section 10.11 explains the GUI flags. |
central fleet create NAME |
-mode actions|workspace (default actions), -confirm, and for workspace mode the workspace flags below |
Create a fleet. -confirm makes it guarded. |
central fleet set NAME |
-confirm=BOOL (required) |
Turn a fleet's guard on or off (-confirm=true guards it). Audited as fleet.set_confirm with the old and new value. The GUI's guard toggle does the same. |
central fleet workspace set NAME |
the workspace flags below (at least one) | Change a workspace fleet's config. Reads the current config, applies your flags, sends the whole result (a full replace). Existing workspaces keep the spec they were opened with. |
central fleet list |
-json |
List fleets with mode, confirm and non-revoked runner count; workspace fleets show image, network and (admin only) the full config. |
central workspace list |
-fleet F, -json
|
List workspaces of every operator: id, fleet, runner, operator, session, state, image, last used, expires. |
central workspace kill ID |
Destroy a workspace now. If its runner is offline it prints closing; the reaper will finish. |
|
central token create |
-fleet F (required), -labels k=v,k=v, -approve, -uses N (0 = 1, max 1000), -ttl DURATION (0 = 24h, max 720h, min 1s) |
Create a join token; prints it once on stdout. |
central token list |
-fleet F, -json
|
List tokens (id, fleet, approve, uses/max, expiry, revoked, labels). Never secrets. |
central token revoke ID |
Revoke a token by its 16-hex id. Already-enrolled runners are unaffected. | |
central runner list |
-fleet F, -json
|
List non-revoked runners with status, online flag, last seen and labels. |
central runner approve FLEET/RUNNER |
pending to active. |
|
central runner disable FLEET/RUNNER |
active to disabled: no new work; running work finishes. |
|
central runner enable FLEET/RUNNER |
disabled to active. |
|
central runner revoke FLEET/RUNNER |
Permanent. Cancels running work, closes the connection, refuses reconnects. | |
central operator code |
Show the current registration code, seconds left and central's host-key fingerprint. Audited (the code is not). | |
central operator rotate-secret |
Replace the registration secret; every outstanding code stops working. Existing operators are not affected. | |
central operator list |
-json |
List operators (name, status, key fingerprint, last seen). |
central operator revoke NAME |
Revoke an operator and drop its live connections; in-flight actions are cancelled. | |
central exec FLEET/RUNNER ACTION [k=v...] |
-confirm FLEET |
Run an action as admin and print its stdout/stderr; exits with the action's exit code. Waits up to 600 s. |
central audit |
-since ID, -before ID, -limit N (default 100, max 1000), -json, and filters: -fleet, -runner, -actor, -source (cli, api, gui, enroll, system), -outcome, -action (with -action-prefix to match a prefix such as gui.), -workspace, -request-id, -from, -to (RFC 3339 or YYYY-MM-DD) |
Print audit events with id greater than -since, oldest first, narrowed by the filters. |
central gui reset-admin |
Admin recovery: retires the GUI admin, ends every GUI session, prints a fresh one-time setup token on stdout (valid 24 h, shown once). Works even if no admin exists. Audited as gui.reset_admin. |
Valid runner transitions: pending to active; active to and from disabled; any
non-revoked state to revoked; revoked is final. Anything else answers
conflict: runner is <status>: cannot <op>.
Workspace flags (fleet create with -mode workspace, and fleet workspace set). For
create, omitted flags take the defaults; for set, omitted flags keep their current value.
| Flag | Default | Meaning |
|---|---|---|
-executor containerd|opensandbox |
containerd |
Which backend the fleet's runners use. A runner is only placed work whose fleet executor equals its own. |
-image REF |
required on create | The default image; must match -images. A digest reference (name@sha256:...) is recommended. |
-images REF,REF,... |
the default image | The allowlist: exact references, repo:* or repo@sha256:*. A tag-only pattern is allowed but is only as stable as the registry's tag. |
-pull if-not-present|always|never |
if-not-present |
When the runner may pull. never needs pre-pulled images (and OpenSandbox cannot honour it). |
-network none|egress |
none |
none: no network at all. egress: only through the allow-list proxy. |
-egress HOST[:PORT],... |
none | The proxy allowlist: host[:port], *.domain[:port], or cidr:port (the runner must opt in, see egress_cidr_rules). Port defaults to 443. An empty value clears it. |
-cpus N |
2 | CPUs per workspace (fractions allowed, 0.5). |
-memory SIZE |
4GiB | Memory per workspace, swap equals memory (512MiB, 4GiB). |
-pids N |
1024 | Process limit per workspace. |
-tmpfs SIZE |
512MiB | Size of /tmp. |
-disk SIZE |
10GiB | Soft quota for /workspace. |
-idle-ttl DURATION |
24h | Close a workspace unused for this long. |
-max-ttl DURATION |
168h | Close a workspace after this long, however busy. Must be at least -idle-ttl. |
-exec-timeout DURATION |
2m | Default timeout of one exec (when the caller gives none). |
-exec-max DURATION |
30m | Longest exec any caller may ask for (at most 24h; the runner's limits.exec_max caps it again). |
Durations are whole seconds or more (90s, 2m, 24h). Sizes use MiB, GiB, TiB.
| Command | Flags | What it does |
|---|---|---|
runner join ADDR |
-name NAME (required), -data DIR (default: root /var/lib/mirafleet/runner; other users $XDG_CONFIG_HOME/mirafleet; the packaged service user must pass -data /var/lib/mirafleet/runner), -token - (required, reads stdin) |
Enrol with central. ADDR is host:port, and comes first (flags may follow). Writes key, known_hosts, runner.yaml. |
runner run |
-data DIR (same default), -actions FILE (default /etc/mirafleet/actions.yaml) or -workspace FILE (typically /etc/mirafleet/workspace.yaml) |
Connect and serve until SIGINT/SIGTERM. Exactly one mode: giving both is refused, and workspace mode never falls back to actions. Starting workspace mode loads and checks workspace.yaml and the executor first; any failure stops the runner with a message. |
runner tls-init |
-dir DIR (required; new or empty; created 0700), -days N (default 365, 1 to 3650) |
Mint the per-node PKI for the OpenSandbox option: a CA (its private key is discarded after signing), the TLS front's server certificate (SAN 127.0.0.1, ::1, localhost) and the runner's client certificate; ECDSA P-256, all files 0600. Prints the paths, the expiry and the lines for workspace.yaml (ca_file, pin_sha256, client_cert, client_key). Never overwrites; refuses a symlink. |
runner tls-front |
-dir DIR (required: the tls-init directory), -listen ADDR (default 127.0.0.1:8443, loopback only), -upstream ADDR (default 127.0.0.1:8080, loopback, plain HTTP) |
Run the small TLS 1.3 + mTLS reverse proxy that sits in front of OpenSandbox. Runs until SIGINT/SIGTERM. |
runner workspace list |
-data DIR, -workspace FILE (default /etc/mirafleet/workspace.yaml) |
Local, no central: list this runner's workspaces straight from the executor (id, state, age, disk bytes, image). Works after a runner revoke. |
runner workspace prune |
-data DIR, -workspace FILE, -all, -yes
|
Local: destroy this runner's workspaces, by default only those older than max_age; -all destroys every one. Without -yes it only lists what it would destroy. Stop runner run first when you can. |
| Command | Flags | What it does |
|---|---|---|
mcp login ADDR |
-name NAME (required), -code - (required, reads stdin) |
Generate a key (first time), register with central, pin its host key, save a context. |
mcp api METHOD [JSON] |
-in FILE|- (body for workspace.write_file, or stdin of workspace.exec; - reads stdin), -out FILE (where the body of workspace.read_file goes) |
Call one operator method on the current context and print the JSON result. JSON is the params object. With -in, length and sha256 are filled in for write_file when absent, and stdin: true is set for exec. With -out, the file is written 0600 and atomically. Bodies are at most 1 MiB; bigger files go in chunks with offset. |
mcp or mcp serve
|
-context NAME (use this context), -fleet NAME (default fleet), -session ID (fixed session id), -project-dir DIR (where .mirafleet.yaml is looked up; default the working directory) |
Run the MCP server on stdin and stdout. Normally started by a harness, not by you. On a terminal it prints a hint to stderr and waits. Exits 0 on stdin EOF, SIGTERM or SIGHUP within 5 s; exits 1 on a malformed protocol line. |
mcp context list |
List contexts: * NAME ADDR default_fleet=... (the * marks the current one). Prints names and addresses only. |
|
mcp context use NAME |
Make NAME the current context. | |
mcp context remove NAME |
Forget a context (it does not unpin its known_hosts line or revoke anything on central). |
|
mcp hook claude-code EVENT |
EVENT is session-start, session-end or pre-tool-use
|
Run a Claude Code hook handler. Started by Claude Code from the plugin's hooks.json; reads the hook JSON on stdin; always exits 0. |
Environment variables: MIRAFLEET_CONFIG_DIR overrides the operator config directory (must be
an absolute path). MIRAFLEET_STATE_DIR overrides the state directory, where session handoff
files live (also absolute). The MCP server reads only these two (plus the platform's standard
home, cache and config locations to find the defaults, and its parent process id); it forwards
nothing from its environment into workspaces (section 10.10.7).
Operator API methods (for mcp api):
| Method | Params | Result |
|---|---|---|
hello |
{"client":"..."} (optional hint) |
operator name, supported protocol versions |
fleets.list |
none | fleets with mode, confirm, runner count |
runners.list |
{"fleet":"dev"} |
runners with status, online, labels, last_seen; workspace runners add slots, free_slots, executor; actions runners add actions (names, parameter patterns and defaults), or actions_omitted: true when the reply was too big (chapter 7) |
action.run |
{"fleet","runner","action","params":{},"timeout_s":N,"confirm":"FLEET"} |
exit_code, stdout, stderr, truncated, duration_ms, request_id |
workspace.open |
{"fleet","session","image"?,"labels"?,"confirm"?} |
workspace (id, runner, state, expires...), reused |
workspace.exec |
{"workspace","argv":[...],"cwd"?,"env"?,"timeout_s"?,"stdin"?,"confirm"?} |
exit_code, stdout, stderr, truncated, timed_out, duration_ms, request_id |
workspace.read_file |
{"workspace","path","offset"?,"limit"?} with -out FILE
|
size, offset, length, mode, eof (+ the bytes into the file) |
workspace.write_file |
{"workspace","path","offset"?,"truncate"?,"mode"?,"confirm"?} with -in FILE
|
size |
workspace.close |
{"workspace"} |
{} when closed, {"state":"closing"} when the runner could not be reached yet and the reaper will finish |
workspace.list |
{"fleet"?} |
your own workspaces |
timeout_s: 0 or absent means 120 s; it is capped at 600 s. mirafleet mcp api waits for an
action.run as long as that timeout plus 30 s (other methods: 2 minutes), so a long action only
needs a larger timeout_s. For workspace methods the wait is: workspace.open 5 minutes 30 s
(it may pull an image), workspace.exec its timeout_s plus 30 s (24 h plus 30 s when absent;
the fleet enforces the real default), file calls 100 s. Full parameter rules are in
chapter 7. Limits: request at most 64 KiB, at most 32 params, param keys up to 64 bytes and
values up to 4 KiB, output up to 1 MiB (stdout and stderr together; truncated: true if cut).
| File | Mode | What it is |
|---|---|---|
host_ed25519 |
0600 | central's SSH private host key. Its hash is baked into every token and code. Back this up; losing it means every runner and operator must re-enrol. Central refuses to start if the mode is looser than 0600. |
host_ed25519.pub |
0644 | the matching public key |
mirafleet.db |
0600 | the SQLite database: fleets, runners, tokens, operators, settings (including the registration secret), the audit log and, since M4, the GUI admin (password hash), the setup token's hash and the GUI session hashes |
gui/ (directory) |
0700 | M4: the GUI's own files; created at the first GUI start |
gui/tls.crt, gui/tls.key
|
0644 / 0600 | the self-signed GUI certificate and its key (only when you did not give -gui-cert/-gui-key). Valid 2 years, regenerated when under 30 days remain or when the -gui-host names change |
gui/setup-token |
0600 | the one-time setup token (mfs1....) while no admin exists; central deletes it after setup |
mirafleet.db-wal, mirafleet.db-shm
|
0600 | SQLite's write-ahead log and shared memory; they appear while central runs. Back up with .db together, or stop central first |
central.lock |
0600 | lock file held while central runs, so two centrals cannot share one directory |
admin.sock |
0600 | the local admin socket; removed on clean shutdown (a leftover one is cleaned up on next start) |
| File | Mode | What it is |
|---|---|---|
runner.yaml |
0600 |
central, name and fleet; its presence means "joined" |
runner_ed25519 |
0600 | the runner's private key |
runner_ed25519.pub |
0644 | its public key |
known_hosts |
0600 | central's pinned host key, e.g. central.example.com:2222 ssh-ed25519 AAAA.... The runner connects only to this key |
audit.jsonl |
0600 | the runner's own append-only audit log, one JSON object per line (start and the outcome of every action) |
Outside the data directory: /etc/mirafleet/actions.yaml (default location), the allowlist. It
should be owned by root and not writable by the user the runner runs as, so a compromised
runner process cannot widen its own permissions.
A workspace runner keeps the same files, plus /etc/mirafleet/workspace.yaml (its policy,
section 10.9.2) and the workspace root (default /var/lib/mirafleet/ws, section 10.9.4). In
workspace mode audit.jsonl has the runner's start and outcome lines for every workspace.*
operation (argv clipped, env names only, file paths and byte counts, never content).
| OS | Config directory | State directory (session handoff files) |
|---|---|---|
| Linux |
$XDG_CONFIG_HOME/mirafleet, else ~/.config/mirafleet
|
$XDG_CACHE_HOME/mirafleet, else ~/.cache/mirafleet
|
| macOS | ~/Library/Application Support/mirafleet |
~/Library/Caches/mirafleet |
| Windows | %LocalAppData%\mirafleet |
%LocalAppData%\mirafleet\state |
MIRAFLEET_CONFIG_DIR and MIRAFLEET_STATE_DIR override these (absolute paths only). On Windows
the directory is under LocalAppData on purpose, not Roaming: a roaming profile is copied to a
profile server, and the private key would go with it. A network-share %LocalAppData% (a UNC
path) is refused for the same reason.
| File | Mode | What it is |
|---|---|---|
operator_ed25519 |
0600 | the operator's private key. This is the operator's identity. Anyone who copies it can act as that operator until it is revoked |
operator_ed25519.pub |
0644 | the public key |
known_hosts |
0600 | pinned central host keys, one line per central address |
contexts.yaml |
0600 | named centrals, the current one, optional defaults (below) |
Example contexts.yaml (written by mcp login and mcp context; you may edit it by hand):
current: work
output_cap_bytes: 30720 # optional; 4096 to 262144; default 30720 (30 KiB)
contexts:
- name: work
addr: central.example.com:2222
default_fleet: dev # optional
- name: cloud
addr: cloud.example.net:2222The file is strict: unknown keys are errors, names must be lowercase ([a-z0-9][a-z0-9._-]{0,62}),
a second YAML document is refused, and a jump key (SSH jump hosts) is rejected because jump
hosts are not supported yet. Writes take a lock file so two commands cannot lose each other's edit.
Windows protection. On Unix the key is protected by file mode 0600 in a 0700 directory,
checked on load. Windows has no such mode bits, so mirafleet sets a DACL (discretionary
access control list, the Windows permission list) on the config directory and every private file
when it creates them: inheritance off, the owner is the current user, and the only allow-entries
are the current user, SYSTEM and BUILTIN\Administrators. On every load it checks all of that
again and refuses a key whose owner or list differs ("private key ... is not private to the
current user"). Anything it cannot read or does not recognise is a refusal too (fail closed). See
chapter 5 for why.
Per project: .mirafleet.yaml, in the project directory or any parent up to the first
directory containing .git (never above your home directory):
fleet: dev # default fleet for this project
context: work # optional: which contextOnly those two keys are allowed. No addresses, keys or caps, so cloning a repository can never
point your agent at someone else's central. A call that would use a guarded fleet only because
the project file (or a context's default_fleet) names it is refused with an error: guarded fleets
must be named explicitly in the call, and confirmed.
Session handoff files (in the state directory, sessions/*.json, directory 0700, files 0600):
a few lines naming the harness's session id, written by a hook so a restarted server can reattach
to its workspace. They hold no secret and are pruned after 7 days.
This file is the runner's allowlist. It is the security boundary of actions mode: central and the agent can only request names from this file, and each parameter must match a pattern you wrote. Anything not listed is refused.
actions:
<action-name>:
run: ["<command>", "<arg>", "<arg with {{param}}>"] # required: an argv list
timeout: 30s # optional: default 60s
params: # optional
<param-name>:
pattern: "<regular expression>" # required
default: "<value>" # optional
allow_leading_dash: false # optionalRules, all enforced when the runner starts (a mistake stops the runner with a clear error):
-
runis an argv array, never a shell string. There is nosh -c, no pipes, no&&, no$(...), no globbing. Each array element is one argument, passed straight to the program. -
argv[0]is either an absolute path (/usr/bin/systemctl) or a bare command name (df). A bare name is looked up once at start in a fixed path (/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin), never in the runner's ownPATH. A name with a slash that is not absolute (./foo) is refused.argv[0]may not contain{{...}}. -
Placeholders are
{{name}}(letters, digits, underscore; not starting with a digit), allowed inside any argument after the first, even mid-string (--tag=x{{lines}}y). Every placeholder must have a matching entry inparams; every parameter a caller sends must exist. -
Patterns are Go (RE2) regular expressions. The runner wraps them so they must match the
whole value, no matter how you anchored them:
[a-z]+does not acceptabc; rm -rf /. The wrapper covers the entire alternation:/|/var|/homeis read as\A(?:/|/var|/home)\z, so the|choices cannot be used to match only a piece of the value. Make patterns as narrow as you can ([a-z0-9-]{1,40}, not.*). -
defaultmakes a parameter optional. It must match its own pattern. Without a default, the parameter is required. -
Leading dash: a value starting with
-is refused unlessallow_leading_dash: true, because a value like--deletewould be read by the program as an option (option injection). A default that starts with-also needs the flag. -
timeoutis a Go duration (500ms,30s,5m). It must not be negative; omitted means 60 s. When it expires the whole process group is killed and the result saystimed_out. Remember that the caller has its own limit:action.runwaits up totimeout_s(default 120 s, max 600 s), so an action that needs more than two minutes also needstimeout_sin the call. -
Unknown YAML keys are errors (a typo like
timout:is caught, not ignored). -
The environment is empty: the process gets only
PATH=<fixed path>andLANG=C, runs in/, and its stdout and stderr together are capped at 1 MiB. Anything your command needs (a config path, a credential) must be written in the command itself or in files it reads. -
The process runs as the user running the runner. Run the runner as an unprivileged user
and give it exactly the access it needs (for example one
sudoersrule for one command). Never run a runner as root unless every action in the file really needs it.
actions:
# No parameters: the simplest and safest kind.
uptime:
run: ["uptime"]
# A parameter limited to three exact choices.
disk-usage:
run: ["df", "-h", "{{path}}"]
params:
path: { pattern: "/|/var|/home", default: "/" }
# A bounded number, with a default. This is the tail-logs action from the prod/db-1 example.
tail-logs:
run: ["tail", "-n", "{{lines}}", "/var/log/syslog"]
params:
lines: { pattern: "[0-9]{1,4}", default: "200" }
# A service name from a strict pattern; a longer timeout.
restart-service:
run: ["/usr/bin/sudo", "-n", "/usr/bin/systemctl", "restart", "{{unit}}.service"]
params:
unit: { pattern: "(nginx|postgresql|redis)" }
timeout: 2m
# Dangerous example, kept in its place: never take a free-form path to a destructive command.
# BAD: run: ["rm", "-rf", "{{path}}"] with pattern ".*"Try an action locally before you rely on it (central exec goes through the real runner). To
see what the guard refuses:
$ mirafleet central exec dev/build-1 disk-usage path='/; rm -rf /'
mirafleet: bad_request: refused by runner: refused: parameter "path" does not match its pattern(The exact mirafleet: prefix comes from the CLI's error printer.) Every refusal is audited.
Find your message, read what it means, do the fix. "Central log" means central's stderr. Messages
that start forbidden, unauthenticated, conflict etc. are API error codes followed by a fixed
message; they never contain internal detail, so the real reason for some refusals is only in the
central log. The tables are grouped by where you are when it goes wrong.
| Message you see | What it means | What to do |
|---|---|---|
mirafleet: mirafleet central is supported on linux only (current: darwin) |
You ran central or runner on macOS or Windows. | Use a Linux host. Only mcp runs elsewhere. |
dial unix /var/lib/mirafleet/central/admin.sock: connect: no such file or directory |
Central is not running, or -data points to the wrong directory. |
Start central run; pass the same -data you used there. |
dial unix ...admin.sock: connect: permission denied |
You are not the user that runs central (the directory is 0700). | Run the command as central's user, e.g. sudo -u mirafleet. |
another central is already using /var/lib/mirafleet/central (lock ... is held) |
Another central process has that data directory. | Stop it, or use a different -data. Never delete central.lock by hand while it runs. |
admin socket ... is in use by a running central |
Same cause, found at socket start. | As above. |
load host key (run mirafleet central init first): ...
|
No host key in the data directory. | Run central init with the same -data. |
private key /...: has mode 0644; it must not be accessible to group or others (chmod 600) |
A key file has loose permissions; mirafleet refuses to use it. |
chmod 600 the file (and check who else can read the directory). |
database schema version N is newer than this binary supports (M): refusing to open; upgrade mirafleet |
Database was written by a newer mirafleet. | Run the newer binary; do not downgrade. |
| Message you see | What it means | What to do |
|---|---|---|
-token must be - (the token is read from stdin, never from argv or env) |
You passed the token on the command line. | echo "$TOKEN" | mirafleet runner join ... -token - |
-code must be - (the code is read from stdin, never from argv) |
Same for the registration code. | Pipe it: echo "$CODE" | mirafleet mcp login ... -code -
|
no join token on stdin / no registration code on stdin
|
Stdin was empty. | Check the variable is set; mind that the pipe goes into the right command. |
invalid join token / invalid registration code
|
The string is malformed (truncated, extra spaces, or wrong kind). | Copy it again in full. Tokens start with mfj1., codes with mfr1.. |
unauthenticated: join refused |
One message for many causes (deliberately): token unknown, wrong secret, expired, revoked, used up, or made for a different central. | Check the central log for the true reason. Create a new token with central token create. |
unauthenticated: registration refused |
The code is wrong, was for an earlier 60 s window, was made before rotate-secret, or is for another central. |
Get a fresh central operator code and use it within its window. |
conflict: conflict (on join) |
That runner name already exists in the fleet, or the key is already in use (revoked runner keys can never rejoin; a key can't be both runner and operator). | Choose a different -name, or use a fresh -data directory (new key). |
conflict: conflict (on login) |
The name is held by another operator, or this key already belongs to a runner or a revoked operator. | Choose another name; revoked operators must use a new key (delete the config dir). |
this data directory has already joined a central (runner.yaml exists); use a fresh -data directory |
runner join ran twice. |
Use a new -data, or delete the old directory if you really want to start over. |
host key does not match the pinned key (server presented SHA256:...) |
During join/login: the server's key is not the one in your token/code. Could be the wrong address, a rebuilt central, or an attack. | Do not continue. Verify the address and the fingerprint (central operator code prints it). |
invalid name "Durga" (lowercase letters, digits, . _ -; max 63) |
Name rules. | Use a lowercase name. |
central address "central.example.com": ... missing port in address |
The address needs a port. | central.example.com:2222 |
| Message you see | What it means | What to do |
|---|---|---|
runner is not joined: run mirafleet runner join first
|
runner run found no runner.yaml. |
Run runner join, and use the same -data for both. |
host key for central.example.com:2222 (SHA256:...) not pinned in .../known_hosts |
After join/login: central's key changed (for example init ran on a fresh directory) or the file lacks the line. |
If the change is expected, re-join / re-login. If not, treat as an attack. |
ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey], no supported methods remain |
Central does not accept your key: the runner or operator was revoked, never registered, or central's database was replaced. | Check central runner list / central operator list; re-enrol if needed. |
actions: "x": command "foo" not found in /usr/local/sbin:... (runner start) |
A bare argv[0] is not in the fixed path. |
Use an absolute path or install the command. |
actions: "x": placeholder {{p}} has no param definition |
run uses {{p}} but params lacks p. |
Define the parameter. |
actions: "x": default of "p" does not match its pattern |
Default must match its own pattern. | Fix one of them. |
actions: yaml: unmarshal errors: ... field timout not found ... |
Unknown or misspelled key. | Fix the key name. |
Runner log: disconnected: ...; retrying in 1.2s
|
Connection lost; backoff in progress. | Read the reason after disconnected:; it is usually network, a changed host key or revocation. |
| Message you see | What it means | What to do |
|---|---|---|
no current context: run mirafleet mcp login ADDR -name NAME -code - first
|
mcp api has no context. |
Run mcp login. Check MIRAFLEET_CONFIG_DIR is the same as at login. |
forbidden: forbidden |
The policy said no. As an operator: your operator is revoked, or you called a method you may not (admin methods are never available over api@). |
Check central operator list. Use the CLI on central for admin tasks. |
bad_request: invalid fleet or runner name / invalid fleet name
|
Name does not match the name rules or the field is empty (runners.list needs {"fleet":"..."}). |
Fix the JSON. |
bad_request: invalid params |
The JSON had an unknown field or trailing junk (params are decoded strictly). | Check field names against the table in 10.3. |
bad_request: fleet requires confirm to equal the fleet name |
A guarded fleet needs "confirm":"<fleet name>". |
Add it (or -confirm FLEET for central exec). It is audited as denied. |
conflict: fleet is not in actions mode |
action.run on a workspace fleet. |
Use the workspace.* methods, or call an actions fleet. |
conflict: runner is pending (or disabled) |
The runner is not active. |
central runner approve / enable. |
not_found: not found |
The fleet or runner does not exist, or the runner is revoked. |
central fleet list, central runner list. |
unavailable: runner unavailable |
Central could not reach the runner: it is offline, busy, or the connection broke. |
central runner list (ONLINE column); check the runner's log and network. If busy, wait: a runner runs 4 actions at a time. |
unavailable: runner revoked / unavailable: request cancelled
|
The runner or operator was revoked mid-run, or the caller disconnected. | Expected after a revoke. The audit shows cancelled. |
unavailable: audit unavailable |
Central could not write the "start" audit row, so it refused to run the action (fail closed). | Check the central log, disk space and the database file. |
timeout: action timed out |
The call's timeout_s expired. |
Raise timeout_s (max 600), or fix the action. |
bad_request: refused by runner: refused: unknown action "x" |
The action is not in that runner's actions.yaml. |
Add it and restart the runner, or fix the name. Each runner has its own file. |
bad_request: refused by runner: refused: parameter "p" does not match its pattern |
Value failed the regex (or a required parameter is missing: missing required parameter). |
Send a valid value, or widen the pattern carefully. |
bad_request: refused by runner: refused: parameter "p" must not start with '-' |
Leading-dash guard. | Use allow_leading_dash: true only if the program really needs it. |
result has exit_code: -1 and timed_out: true / stderr mentions the binary |
The action timed out and was killed, or the program could not start (not executable, missing). | Check timeout: and the command path. |
timeout: request not received within 10s |
A client opened a channel and sent nothing. | Usually a broken client; retry. |
too_large: request exceeds 65536 bytes |
Request over 64 KiB. | Send less data. |
Every row here comes from a fail-closed check. None of them is "fixed" by loosening a safety setting: fix the host or the file instead.
| Message you see | What it means | What to do |
|---|---|---|
runner run: -actions and -workspace are mutually exclusive (one runner, one mode) |
You passed both flags. | Pick one. A host that needs both modes needs two runners (two -data directories, two fleets). |
workspace config: yaml: unmarshal errors: ... field concurent not found in type wsconfig.Config |
workspace.yaml has an unknown or misspelled key (it is parsed strictly). |
Fix the key; see 10.9.2. |
workspace config: containerd.root "...": must be owned by root (uid 0), is uid N / mode must be 0700, is 0755
|
The workspace root is not root-owned and 0700. |
chown root:root DIR && chmod 0700 DIR. |
workspace config: containerd.namespace "moby" is refused: it belongs to another runtime (also k8s.io) |
You pointed at Docker's or Kubernetes' namespace. | Use mirafleet (or any other name). Never share a namespace with those. |
workspace config: images: allowlist must not be empty |
No images entries. |
List at least one image pattern. |
workspace config: opensandbox.server "http://...": scheme must be https (plain http is refused) |
Plain HTTP to OpenSandbox is not allowed, even on loopback. | Put the TLS front in front of it (10.9.6) and use https://127.0.0.1:8443. |
workspace config: opensandbox.api_key_file "...": mode must be 0600 or 0400, is 0644 (also client_key, or "must be owned by the runner user") |
A secret file is readable by others or owned by someone else. |
chmod 0600 and chown it to the user that runs the runner. |
workspace config: opensandbox.ca_file: required (pin-only trust is not supported ...) |
A pin alone cannot anchor the TLS chain. | Set ca_file (for a self-signed front, the front's certificate itself); pin_sha256 is an extra check. |
ctrd: userns: required is not supported on this host: kernel 5.15 lacks idmapped overlayfs mounts (need >= 5.19) ... |
Hosts without user namespaces or id-mapped snapshots cannot give each workspace its own uid range. | Use a newer kernel and containerd 2.x. containerd.userns: off runs, but weakens isolation between workspaces (and containers share the host uid uid_base + slot); that is a conscious choice, never a default. |
ctrd: connect to containerd at /run/containerd/containerd.sock: ... or not answering
|
containerd is not running, or the runner user cannot open the socket. | Start containerd; run the runner as root (it needs the socket anyway). On a Docker host see 10.9.3. |
ctrd: secure_runtime: runtime "io.containerd.runsc.v1": shim containerd-shim-runsc-v1 not found on PATH |
You declared gVisor/Kata but its shim is not installed. | Install it or remove secure_runtime. Without it the runner refuses guarded fleets. |
ctrd: apparmor: required but AppArmor is not available on this host |
apparmor: required on a host without AppArmor. |
Use auto (apply when available) or enable AppArmor. |
ctrd: init binary /usr/local/bin/mirafleet must be world readable and executable (mode 0700) |
PID 1 inside the container is not root and must be able to execute the mirafleet binary. |
chmod 0755 the binary. |
warning: N image pattern(s) in workspace.yaml cannot be advertised to central (limit 32 entries of 256 bytes) |
Placement only sees the first 32 patterns. | Harmless for safety (the runner still enforces them all); shorten the list if placement misses. |
Runner starts, central lists it with slots but never gives it work |
Central places only on active, online runners whose executor equals the fleet's, with a free slot, matching trusted token labels, and an image the runner advertises. |
central runner list -json: check status, online, executor, slots; check the fleet's -executor and the token labels. |
| Message you see | What it means | What to do |
|---|---|---|
conflict: fleet is not in workspace mode |
workspace.* on an actions fleet. |
Use action.run, or a workspace fleet. |
bad_request: image is not allowed by the fleet |
The image is not in the fleet's -images. |
Use an allowed image, or fleet workspace set -images .... |
bad_request: refused by runner: image not allowed on this runner |
The fleet allows it but this runner's own images list does not. |
Add the pattern to that runner's workspace.yaml and restart it. The intersection applies. |
bad_request: refused by runner: ... limit above this runner's cap |
The fleet asks for more CPU, memory, pids, tmpfs or disk than limits in the runner's file. |
Lower the fleet's value or raise the runner's cap. |
bad_request: refused by runner: network mode "egress" not allowed on this runner |
The runner's network: does not list egress. |
Add it (deliberately) or use -network none. |
bad_request: refused by runner: egress is not supported with secure runtimes yet |
A guarded fleet (gVisor/Kata) cannot use egress mode on containerd yet. | Use -network none for that fleet. |
unavailable: no runner can take this workspace right now |
No candidate: no online active runner, all slots taken, labels or image not matching, or a guarded fleet with no secure-runtime runner. | See the row above about slots; central workspace list shows who holds them; workspace kill or wait for the reaper. |
unavailable: the runner holding this session's workspace is offline |
A sticky session's files are on a runner that is down. Central never creates a fresh workspace elsewhere. | Bring the runner back. To abandon the files: central workspace kill ID, then open again. |
conflict: workspace limit reached (8) |
The operator already has the maximum live workspaces. | Close some (workspace.close), or an admin kills them. |
conflict: workspace is still opening / workspace is closing
|
Open in progress or already being closed. | Wait, then retry; open a new session if closing. |
not_found: not found on a workspace id |
Wrong id, malformed id, or someone else's workspace (deliberately the same). |
workspace.list shows your own. |
bad_request: env ANTHROPIC_API_KEY is denied |
Secrets must not enter a workspace; the denylist always wins. | Do not pass it. Agents keep their keys on the laptop. |
bad_request: refused by runner: env CI is not allowed |
The name is not in the runner's env_allow. |
Add it to env_allow in workspace.yaml if it is harmless. |
bad_request: sha256 mismatch / body shorter than length
|
The body bytes do not match the request. | Use mcp api -in FILE (it computes both) or fix the client. |
too_large: body exceeds 1048576 bytes |
A body frame over 1 MiB. | Send chunks with offset. |
bad_request: refused by runner: file would exceed this runner's max_file |
offset + length over limits.max_file. |
Raise it, or write a smaller file. |
unavailable: runner busy |
All of the runner's slots or exec permits are taken (4 execs per workspace). | Retry; open already tries 3 runners by itself. |
result exit_code: 127 or 126 and the reason on stderr |
The command was not found or not executable in the image (like a shell would say). | Use an absolute path or an image that has the tool. |
result timed_out: true (the exit code is usually 137) |
The command hit its timeout and was killed. | Raise timeout_s (up to the fleet's -exec-max). Daemonised children survive until the workspace is closed. |
git clone or curl hangs or fails in an egress workspace |
The tool ignores HTTP_PROXY/HTTPS_PROXY (it fails closed, there is no other route), or the host is not on -egress, or it resolves to a private range. |
Allow the host (fleet workspace set -egress ...); for private ranges the runner must set egress_cidr_rules: true and the fleet use a cidr:port rule. |
Workspace stays closing
|
Its runner is offline; the row keeps its slot. | Bring the runner back (reconcile finishes it), or runner workspace prune on that host. Rows of a revoked runner become lost. |
| Containers still exist on a host after its runner was revoked | A revoked runner never reconnects, so nothing can destroy them remotely. | On that host: mirafleet runner workspace prune -all -yes ... (it works without central). |
| Message you see | What it means | What to do |
|---|---|---|
Central log: connection from ... refused before handshake: per-IP handshake limit (or global handshake limit) |
Too many half-open connections from one source (or in total). | Wait; look for a misbehaving client; add a firewall rule. |
Central log: enroll connection from ... refused: rate limit exceeded
|
Too many join/login attempts from one IP (10 per minute) or overall (60 per minute). | Wait a minute. |
Central log: runner "x" silent for >45s; closing connection
|
A registered runner sent no heartbeat for 3 intervals (3 x 15 s); the connection is cut and the runner reconnects. | Check the runner host and network. |
Central log: runner "x" (id N) silent for >45s; closing connection
|
The (id N) form is only for a connection that authenticated but never registered, i.e. never sent a first heartbeat. |
Same: check the runner's version, host and network. |
Central log: join from ... refused: token ... pins another host key
|
A token from a different central was used. | Make the token on the right central. |
Can an agent approve a runner, create tokens or revoke things? No. Those methods exist only
on central's local admin socket. Over api@mirafleet they return forbidden, and a test
(TestM2Done) proves it.
Where is the runner's SSH port? Do I open one? There is none. Runners dial out to central; only central listens. That is why a runner can sit behind NAT or a strict firewall.
What happens if central restarts? Runners lose their connection and reconnect by themselves (backoff 1 s up to 60 s, with random jitter). Operators just reconnect on their next call. In-flight actions are cut off (the runner kills them when the connection drops); whether their outcome row is written depends on central shutting down cleanly. Revoked runners stay revoked, because the status is in the database.
What happens if a runner's host is lost? central runner revoke FLEET/RUNNER. The key can
never be used again; a replacement joins under the same name with a new token (revoked names are
reusable, revoked keys are not).
How do I rotate the operator registration secret? mirafleet central operator rotate-secret.
Every outstanding code dies. Operators that already registered keep working (they authenticate
with their keys, not the code). To remove an operator, central operator revoke NAME.
An operator's laptop was stolen. aarvee runs central operator revoke NAME straight away. It closes the
live connection and cancels any running action. The thief cannot use the key afterwards.
How do I back up central? See section 10.8.
Can I run two centrals for high availability? Not in the open-source edition. One central owns one data directory (that is enforced with a lock), and each node talks to exactly one central. HA is an enterprise topic; the code only leaves seams.
Can I change a fleet's name or move a runner between fleets? Not today. Revoke and re-join with a token from the other fleet.
Why does my action work in my shell but fail through mirafleet? The guard runs it with an
empty environment (only PATH and LANG=C), in /, as the runner's user, with no shell.
Use absolute paths, avoid shell syntax, and check the user's permissions.
How do I see what an agent did? mirafleet central audit. Every action.run has a start
row and an outcome row with the same request_id, plus the operator's name. Parameters appear
in the start row, so never design an action that takes a secret as a parameter.
Is there a GUI? Yes, since M4: a web console for aarvee, served by central on port 8443
(section 10.11). It does nothing the CLI cannot do; both call the same service code, and the GUI's
changes are in the same audit log with source gui. Use the CLI for scripts and the GUI for
looking around and for one-off changes.
- Central's log goes to stderr. Under systemd that is the journal; otherwise redirect it to a file and rotate it with your usual tool. Central never writes its own log file.
-
Central's audit log is the
audittable inmirafleet.db. It is append-only, enforced by database triggers, so there is no built-in way to delete old rows. It grows by two rows peraction.run(start and outcome) plus one per admin action. Plan disk space for it. To keep an external copy, page through it withcentral audit -json -since IDand ship the output to your log store (a SIEM, a tool that collects and searches security logs). -
A runner's audit is
audit.jsonlin its data directory: one JSON line per event, appended forever. The runner does not rotate it; rotate or ship it yourself (copy-and-truncate with your usual log tool). -
Workspace calls write more audit rows:
open,exec,read_file,write_fileandcloseeach write astartand an outcome row, and evenworkspace.listwrites one row (an actionslistwrites none). An agent that runs hundreds of commands in a session writes hundreds of row pairs. Theworkspacecolumn is indexed, socentral audit -jsonpiped throughjq(or your log store) can follow one workspace. Rows for reaper, reconcile and revoke work use sourcesystem.
Back up /var/lib/mirafleet/central as one unit: host_ed25519, mirafleet.db and its -wal
and -shm files. The safest way is to stop central, copy the directory, start central. Copy
the files together; the database alone, without its write-ahead log, can miss recent writes.
Keep the copy private: it holds the registration secret and, with the host key, lets someone
impersonate central.
To restore, stop central, put the directory back with the same owner and modes (the directory
0700, the key 0600), and run central run. Runners and operators reconnect by themselves.
Anything that happened after the backup (new runners, operators, audit rows) is lost, so a
restored central may refuse a runner it never heard of: re-join that runner.
The host key is what every token, code, runner and operator pins. If host_ed25519 is lost and
you run central init on a fresh directory, central gets a new key. Then every runner and
operator fails with host key ... not pinned or host key does not match, on purpose: from
their side this looks exactly like an impostor. The fix is to re-pin: every runner needs a
fresh runner join with a new token (new -data directory), and every operator a new
mcp login with a new code. This is why the host key is the file to back up.
- Read the release notes (on the GitHub release page).
- Stop central and back up the data directory (above).
- Replace the binary and start central. On start, central compares the database's schema
version (SQLite
PRAGMA user_version) with the migrations built into the binary and applies the missing ones in order, each inside one transaction. A database from a newer binary is refused (database schema version N is newer than this binary supports). - There is no downgrade. To go back, restore the backup from step 2 and run the old binary.
- Upgrade runners and operators at your own pace; the wire protocol is versioned
(chapter 7). A runner that rejects a new
actions.yamlfield is an older binary: upgrade it first.
Upgrading from M2 to M3 (migration 0002_workspaces.sql). The first start of an M3 central
runs one extra migration inside one transaction:
- it creates two tables,
fleet_workspace(a workspace fleet's config) andworkspaces(one row per workspace, with the indexes that enforce "one live workspace per operator, fleet and session"), and adds an indexedworkspacecolumn toaudit(old rows get an empty value); - the append-only triggers on
auditstill hold after the change; - existing fleets stay in
actionsmode and keep working untouched; existing runners need no change (an M2 runner sends no workspace fields in its heartbeat, which M3 central accepts); -
PRAGMA user_versionbecomes 2. An M2 binary refuses that database (database schema version 2 is newer than this binary supports), so the backup of step 2 is your only way back.
Then, to use workspaces: upgrade central first, then give the workspace hosts the M3 binary,
containerd and a workspace.yaml (section 10.9), and create a workspace fleet. Do not try to
turn an existing actions fleet into a workspace fleet: a fleet's mode is fixed at creation, and
one runner serves exactly one mode.
Upgrading to M4 (migration 0003_gui.sql). The first start of an M4 central runs one more
migration in one transaction:
- it creates
gui_admins,gui_setupandgui_sessions(the admin account, the pending setup token and the GUI sessions; only hashes of tokens, never a token or a cookie) and two indexes onaudit(actorandrequest_id) so the Audit screen's filters stay fast; - nothing existing changes: fleets, runners, operators and the audit log are untouched, and runners and operators need no new binary;
-
PRAGMA user_versionbecomes 3, and an M3 or M5 binary then refuses the database; - the first start also starts the GUI, so the log shows the setup-token notice and, with the default
bind, the all-interfaces notice (section 10.11). Add
-gui-listen offto the service unit before the upgrade if you do not want a GUI.
A workspace is a private, disposable Linux container on a runner where an agent can run commands and read and write files, without ever touching the host. The agent (and its API keys) stays on the operator's laptop; only commands and file bytes cross (chapter 5 explains the boundary, the diagram below summarises it).
Look at: the dotted box is the container; the runner on its left is trusted and the box is not.
- User namespace: uid 1000 inside is an unused high host uid (
uid_base+ slot x 65536), so container root is not host root. - All capabilities dropped,
no_new_privs, and containerd's default seccomp profile. - Read-only root filesystem. Writable: a size-limited
/tmpand/workspace, the one host directory. - Empty network namespace. In egress mode the only way out is the allow-list proxy on
127.0.0.1:3128. - cgroup limits: CPU, memory with swap equal to memory, pids; a soft disk quota on
/workspace. - What crosses: argv, allow-listed env and file bytes in; exit code, output and file bytes out.
- What cannot: host mounts, devices, the containerd socket, API keys, host networking.
- The LLM API key and the SSH key stay on durga's laptop; the agent never runs in the container.
-
A workspace fleet on central (
fleet create -mode workspace): the image allowlist, limits, network mode and lifetimes, set by aarvee. Durga cannot change them. -
A workspace runner per host:
mirafleet runner run -workspace /etc/mirafleet/workspace.yaml. The runner's file is a second, independent policy. The effective policy is the intersection of fleet and runner: the runner builds the whole container spec itself from a fixed template and takes from central only an image (on both allowlists), numbers within its caps, a network mode it allows and allowlisted env. So even a compromised central cannot obtain a privileged container, a host network or a host mount: the runner has no code path that produces one. -
An executor on that runner:
containerd(the default, driven directly through its Go client) oropensandbox(opt-in). One runner serves one fleet, one mode, one executor.
A workspace runner is root-equivalent. Access to the containerd socket amounts to root on the host. Run workspace runners on dedicated, disposable hosts or VMs (nothing else on the box), keep
workspace.yamlroot-owned, and treat the runner key like a root key. The actions runner is deliberately different (it never needs root), which is why the two modes are never mixed.
Placement and lifetimes, in one paragraph: when an agent opens a workspace, central picks a runner
that is active, online, runs the fleet's executor, has a free slot (the runner's concurrent
minus live workspaces), whose trusted token labels contain the requested labels and whose image
list covers the image; the most free slots wins. The workspace is sticky per (operator, fleet, session). A reaper on central (every 60 s) closes workspaces idle longer than -idle-ttl, older
than -max-ttl, or belonging to a revoked operator or runner. When a runner reconnects, central
compares what the runner has with its database (reconcile) and cleans up orphans.
(Chapter 4 walks through all of it; 10.9.8 is the
operator's view.)
The runner's policy file. Default location /etc/mirafleet/workspace.yaml; the -workspace flag
points elsewhere. It is parsed strictly (an unknown key is an error) and checked when the runner
starts, and any failed check stops the runner; there is no "ignore". Own it as root, readable
by the runner user, not writable by it. There is deliberately no key for privileged containers,
unconfined profiles or host mounts: they cannot be configured.
executor: containerd
concurrent: 4
max_age: 168h
images: ["docker.io/library/golang@sha256:*", "ghcr.io/mirastack/dev@sha256:*"]
limits: {cpus: 4, memory: 8GiB, pids: 2048, tmpfs: 1GiB, disk: 20GiB, max_file: 64MiB, exec_max: 1h}
network: [none, egress]
env_allow: [LANG, LC_ALL, TERM, CI, GOFLAGS, NODE_ENV]
egress_cidr_rules: false
containerd:
address: /run/containerd/containerd.sock
namespace: mirafleet
snapshotter: overlayfs
runtime: io.containerd.runc.v2
secure_runtime: ""
root: /var/lib/mirafleet/ws
userns: required
uid_base: 1000000
apparmor: autoTop-level keys:
| Key | Required | Default | Meaning and rules |
|---|---|---|---|
executor |
yes | none |
containerd or opensandbox. Selects which block below is required; the other block must be absent. |
concurrent |
yes | none | How many workspaces this runner holds at once, 1 to 1024. Sent to central as slots; also the runner's own semaphore. Each slot gets its own user-namespace range. |
max_age |
no |
0 (none) |
At most 365 days. Caps the lifetime a fleet may request (a create asking for a longer -max-ttl is refused: max age above this runner's cap), fills in a missing one, and is the age runner workspace prune uses. The runner does not delete anything by itself: central's reaper does. On OpenSandbox it becomes the sandbox's timeout. |
images |
yes | none | The runner-side image allowlist (a boundary of its own): exact references, repo:* or repo@sha256:*; no other wildcards; at least one, at most 1024. A fleet's image must match here too. Checked on the resolved reference before any pull. The first 32 entries (up to 256 bytes each) are advertised to central for placement. |
limits.cpus |
yes | none | Cap per workspace, > 0, at most 1024. A fleet asking for more is refused. |
limits.memory, limits.tmpfs, limits.disk
|
yes | none | Caps. Sizes: 512MiB, 8GiB, 1TiB, or plain bytes; binary units only. |
limits.pids |
yes | none | Cap on processes per workspace. |
limits.max_file |
yes | none | The largest file write_file may build (offset + length), up to 64 GiB. |
limits.exec_max |
no | 1h |
Hard cap on one exec, at most 24h; applies on top of the fleet's -exec-max. |
network |
yes | none | Which modes this runner allows: none, egress, or both. |
env_allow |
no | none | Variable names an exec may set (at most 256, ^[A-Z_][A-Z0-9_]{0,63}$). A name on the hard denylist (*_API_KEY, *_TOKEN, *_SECRET*, *_PASSWORD, *_KEY, ANTHROPIC_*, OPENAI_*, AWS_*, SSH_AUTH_SOCK, GIT_ASKPASS, GIT_SSH_COMMAND, *PROXY*, LD_*, BASH_ENV, NODE_OPTIONS, ...) is refused at load, even here. |
egress_cidr_rules |
no | false |
Lets a fleet use CIDR or IP-literal egress rules. Default: only host names (the proxy always refuses loopback, link-local and metadata addresses, whatever the rule says). |
containerd: block (required when executor: containerd):
| Key | Default | Meaning and rules |
|---|---|---|
address |
/run/containerd/containerd.sock |
Absolute path of containerd's socket. |
namespace |
required | containerd namespace for everything mirafleet creates. moby (Docker) and k8s.io (Kubernetes) are refused. Use mirafleet. |
snapshotter |
overlayfs |
Must support id remapping when userns: required (containerd 2.x overlayfs does). |
runtime |
io.containerd.runc.v2 |
The OCI runtime shim for normal workspaces. |
secure_runtime |
empty | e.g. io.containerd.runsc.v1 (gVisor) or a Kata shim. Declaring it lets the runner serve guarded fleets (-confirm), which require a secure runtime; its shim must exist on PATH. At most 64 characters. Guarded workspaces cannot use egress mode on containerd yet. |
root |
required | Where workspace directories live; a clean absolute path other than /; must be a directory owned by root with mode 0700 (checked at load). Layout in 10.9.4. |
userns |
required |
required: every slot gets its own user namespace and an id-mapped snapshot; the runner refuses to start on a host that cannot do it (kernel 5.19 or newer, user namespaces enabled, an id-mapping snapshotter). off: no user namespace; the process runs as the unprivileged host uid uid_base + slot (never a real user), so isolation between workspaces rests on those distinct uids alone. A conscious weakening, never a default. |
uid_base |
1000000 |
Start of the host uid/gid ranges: slot N gets uid_base + N x 65536. At least 65536 and clear of real users. |
apparmor |
auto |
auto: apply containerd's default profile when the host supports AppArmor; required: refuse to start without it; off. |
opensandbox: block (required when executor: opensandbox; every key but the three marked is required):
| Key | Default | Meaning and rules |
|---|---|---|
server |
none |
https://127.0.0.1:8443: https only (plain http:// is refused, even on loopback), a loopback host, no path, no credentials. |
front |
builtin |
builtin (mirafleet runner tls-front) or external (your own proxy, 10.9.7). Records which one you run; the runner applies the same rules to both. |
ca_file |
none | Absolute path of the CA that signed the front's certificate. Required: TLS is never trusted by pin alone, and the system CA pool is never used. |
pin_sha256 |
optional | 64 hex characters: SHA-256 of the front certificate's public key (SPKI), checked in addition to the chain. tls-init prints it. |
client_cert, client_key
|
none | The runner's mTLS client certificate and key. The key file must be 0600 or 0400 and owned by the runner's user. |
api_key_file |
none | File holding OpenSandbox's API key; 0600 or 0400, owned by the runner's user. Never read from env or argv, never logged, never put into a sandbox. |
secure_runtime |
empty | Declare gvisor or kata only if your OpenSandbox server really runs sandboxes with it; that is what permits guarded fleets. |
Rules for the TLS connection are fixed in code: TLS 1.3 only, mTLS, no redirects followed, every
URL rebuilt from the configured server (OpenSandbox's own endpoint hosts are ignored).
mirafleet talks to containerd directly through its Go client. It never calls Docker Engine and
never needs the docker CLI on a runner (project rule: containers mean containerd). It needs
containerd 2.x: the client mirafleet is built with is 2.4.2, and userns: required needs
2.x's id-mapped overlayfs snapshots. Check with containerd --version.
A host that already runs Docker Engine also runs containerd. The intended set-up is that the
two share the daemon and containerd namespaces keep them apart: Docker's containers live in the
moby namespace, mirafleet's in mirafleet. workspace.yaml refuses moby and k8s.io
outright, so a typo cannot make mirafleet list, adopt or delete Docker's containers. (That refusal
is enforced and unit-tested; the notes below are documented set-up guidance, not something the
project has tested on every Docker install, so check them on your own host.) Notes:
- Use the system containerd socket (default
/run/containerd/containerd.sock). On some Docker installs Docker manages a private containerd with its own socket under/var/run/docker/; pointaddressat whichever socket you intend to use. - If the containerd on the host is still 1.x, install a separate containerd 2.x with its own
socket and root (a second systemd unit) and set
addressto that socket. Do not upgrade the containerd that Docker depends on just for this. - Several runners on one host may share a containerd namespace: the executor tags every workspace
with an ownership name
<fleet>/<runner>andrunner workspace list|prunesee only their own. A separate namespace per runner is still the tidier choice. -
runc(or yourruntime) and, for guarded fleets, the gVisor or Kata shim must be installed. -
Pull happens in containerd, anonymously: private registries are not supported in M3.
Pre-pull the image (
ctr -n mirafleet images pull ...) and use-pull never, or use public images. The allowlist is checked on the normalised reference before anything is pulled.
The containerd.root directory (default /var/lib/mirafleet/ws, root-owned, 0700, checked on
every start) holds the only host directories a workspace can touch:
/var/lib/mirafleet/ws/ root 0700
├── 3f9a6c1e5b7d4820a1c3e5f708192a4b/ one workspace's /workspace; owned by its mapped uid, 0700
│ └── (the agent's files)
├── .meta/
│ └── 3f9a6c1e5b7d4820a1c3e5f708192a4b/
│ ├── hosts generated /etc/hosts, mounted read-only
│ └── resolv.conf generated /etc/resolv.conf, mounted read-only
└── ...
- The directory name is the workspace id (32 lowercase hex characters, assigned by central; the
runner validates it and uses it as the container id
mf-<id>and the labelmirafleet.workspace)..metacan never be a valid id. - Inside the container
/workspaceis this directory (read-write,nosuid,nodev);/tmpis a size-limited tmpfs; everything else is read-only. Nothing else from the host is mounted except the mirafleet binary itself at/.mirafleet/init(read-only), which is PID 1. - Disk use is a soft quota: measured every 60 s and before writes; over
-diskrefuseswrite_file; at twice the quota the workspace is destroyed. One file can never exceed the quota (RLIMIT_FSIZE). It is not a hard filesystem quota: a command can briefly exceed it. Putcontainerd.rooton its own filesystem if the host has other work. - Image layers live in containerd's own storage (
/var/lib/containerd), not here. - A workspace's files vanish when it is closed (directory removed). There is no backup: workspaces
are disposable by design. Anything worth keeping must be copied out with
read_fileor pushed by the agent (for example to a git remote the egress list allows).
For MIRASTACK LABS: central is running (10.2); aarvee adds a new fleet
(a fleet's mode is fixed at creation, so on the central of the earlier walkthrough, where dev is an
actions fleet, pick another name such as dev2). Everything below the first command runs on the
runner host, as root, on a dedicated machine.
# On central (as aarvee): a workspace fleet. Digest-pinned image, no network, modest limits.
IMG=docker.io/library/golang@sha256:<64 hex digits you verified>
mirafleet central fleet create dev -mode workspace -executor containerd \
-image "$IMG" -images 'docker.io/library/golang@sha256:*' \
-network none -cpus 2 -memory 4GiB -pids 1024 -tmpfs 512MiB -disk 10GiB \
-idle-ttl 24h -max-ttl 168h -exec-timeout 2m -exec-max 30m
TOKEN=$(mirafleet central token create -fleet dev -labels zone=a -approve)# On the runner host (root): policy, root directory, join, run.
mkdir -p /etc/mirafleet /var/lib/mirafleet/ws && chmod 0700 /var/lib/mirafleet/ws
cat > /etc/mirafleet/workspace.yaml <<'EOF'
executor: containerd
concurrent: 4
max_age: 168h
images: ["docker.io/library/golang@sha256:*"]
limits: {cpus: 4, memory: 8GiB, pids: 2048, tmpfs: 1GiB, disk: 20GiB, max_file: 64MiB, exec_max: 1h}
network: [none]
env_allow: [LANG, CI, GOFLAGS]
containerd: {namespace: mirafleet, root: /var/lib/mirafleet/ws}
EOF
chmod 0644 /etc/mirafleet/workspace.yaml
printf '%s\n' "$TOKEN" | mirafleet runner join central.example.com:2222 -name build-1 -data /var/lib/mirafleet/runner -token -
mirafleet runner run -workspace /etc/mirafleet/workspace.yamlrunner run prints a clear error and exits if a check fails (10.6). When it is up,
central runner list -fleet dev -json shows "online": true, "slots": 4,
"executor": "containerd". Then register operators as in steps 9 and 10, and use the methods of
10.3. zone=a is a trusted label: it comes from the join token, and only runners with it match
an agent's labels: {"zone":"a"}; whatever the runner claims about itself in a heartbeat is ignored.
To let a workspace reach the network, change both sides deliberately:
# runner: allow the mode (and, if you need them, CIDR rules); restart the runner
# network: [none, egress]
# central: choose it per fleet, with a host allowlist
mirafleet central fleet workspace set dev -network egress -egress 'proxy.golang.org:443,*.golang.org:443'In egress mode the container still has no network of its own. The runner opens a listener on
127.0.0.1:3128 inside the container's network namespace, feeds it into a small HTTP/CONNECT proxy
on the host side, and every exec gets HTTP_PROXY and HTTPS_PROXY. The proxy does its own DNS,
checks the resolved address (so rebinding games fail), allows only listed host and port
combinations, and refuses loopback, link-local, cloud-metadata and private ranges unless a CIDR rule
inside the runner's egress_cidr_rules: true opt-in lists them. Tools that ignore proxy variables
simply fail: that is the design.
OpenSandbox (Apache-2.0) is an existing
sandbox server. Choose it if you already run it or need its runtimes (gVisor, Kata, Firecracker)
behind the same API. mirafleet keeps what it is for: identity, policy, central audit, instant
revoke and outbound-only runners; OpenSandbox supplies the box. It is opt-in per fleet
(-executor opensandbox), and the runner speaks its REST API with the Go standard library only
(no SDK, nothing of theirs linked). As of this writing the server is 0.1.x, so its API may change.
Why a TLS front. OpenSandbox's lifecycle server and its in-sandbox agent (execd) speak
plain HTTP and have no TLS or mTLS settings. mirafleet's rule is HTTPS only, TLS 1.3, never plain
HTTP, not even on loopback. So a small TLS front must sit next to OpenSandbox, ideally in its own
network namespace, so the plaintext hop never leaves it. (Putting the front inside the runner would
just move the plaintext hop to runner-to-OpenSandbox. That was rejected.)
runner process --TLS 1.3 + mTLS--> front 127.0.0.1:8443 --plain http, same namespace--> OpenSandbox 127.0.0.1:8080
Set-up, in order:
-
Configure OpenSandbox (its own settings, server-wide; the names below follow OpenSandbox's
documentation as of writing and were not verified against a live server, so check them
against the version you run): set
[server].api_key(the server only starts without one after an explicit insecure override: do not use that); bind it to127.0.0.1:8080; use[docker].network_mode = bridge(the defaulthostcannot enforce network policy);[egress].mode = dns+nft(modednsdoes not enforce CIDRs); keepno_new_privileges, a seccomp and AppArmor profile,drop_capabilitiesand apids_limit(OpenSandbox applies these server-wide, not per request, so you must set them); add[secure_runtime]if you want guarded fleets. mirafleet cannot check these; it sends a deny-default network policy with every create, so a server that cannot enforce one fails the create (fail closed). -
Mint the node PKI on the runner host:
It creates
mirafleet runner tls-init -dir /etc/mirafleet/tls
ca.pem,front.pemandfront-key.pem,client.pemandclient-key.pem(ECDSA P-256, all 0600, the directory 0700, valid 365 days by default), discards the CA's private key after signing (rotate by runningtls-initinto a new empty directory and restarting both ends), and prints the exact lines forworkspace.yaml, includingpin_sha256. -
Run the front next to OpenSandbox (same host, preferably its network namespace: same pod,
or
network_mode: service:opensandboxin compose):It accepts only TLS 1.3 and only the runner's client certificate (verified againstmirafleet runner tls-front -dir /etc/mirafleet/tls -listen 127.0.0.1:8443 -upstream 127.0.0.1:8080
ca.pem). Listen and upstream must be loopback IPs and the upstream is plain HTTP. Only/v1/sandboxes(and below) and/sandboxes/{id}/(proxy|port)/44772/...(execd's port, optionally/v1-prefixed) are routed; everything else, and any path with dot segments, doubled slashes or backslashes, is 404 and never reaches OpenSandbox. It streams responses (server-sent events), drops hop-by-hop andX-Forwarded-*headers, and never logs headers, bodies or query strings, so the API key and execd tokens stay out of logs. -
Store OpenSandbox's API key where only the runner can read it:
( umask 077; cat > /etc/mirafleet/opensandbox.key ) # paste the key, then Ctrl-D # the file must be owned by the user that runs the runner
-
Write
workspace.yaml:executor: opensandbox concurrent: 4 max_age: 168h images: ["docker.io/library/golang@sha256:*"] limits: {cpus: 4, memory: 8GiB, pids: 2048, tmpfs: 1GiB, disk: 20GiB, max_file: 64MiB} network: [none, egress] env_allow: [LANG, CI] opensandbox: server: https://127.0.0.1:8443 ca_file: /etc/mirafleet/tls/ca.pem pin_sha256: <printed by tls-init> client_cert: /etc/mirafleet/tls/client.pem client_key: /etc/mirafleet/tls/client-key.pem api_key_file: /etc/mirafleet/opensandbox.key secure_runtime: "" # "gvisor" or "kata" only if the server really uses it
-
mirafleet central fleet create dev -mode workspace -executor opensandbox ...and run the runner with-workspace, as in 10.9.5.
Differences you must know about (OpenSandbox's API, not mirafleet's choice):
-
No stdin:
workspace.execwithstdin: trueis refused as unsupported. -
-pull nevercannot be honoured (refused). - Egress policies carry no ports: an allowed host is open on every port inside the sandbox, so mirafleet refuses rules for ports other than 443 and 80. Treat an allowed host as open on those.
- Read-only rootfs, seccomp, AppArmor and pids are server-wide (step 1), not enforced per workspace by mirafleet.
- Python and Go components of OpenSandbox run on the node outside mirafleet's linked code; their licences are theirs to review (the guide's licence rule covers what mirafleet links).
Instead of tls-front you may run nginx, Caddy, HAProxy, Envoy or a service-mesh sidecar. Set
opensandbox.front: external. The runner applies the same rules to whichever front is used, so
your proxy must provide:
-
httpsonly, TLS 1.3 only, listening on a loopback address; - a server certificate that chains to the runner's
ca_file(and matchespin_sha256if set); - client-certificate authentication required, verified against a CA that signed only the runner's client certificate (mTLS);
- upstream
http://127.0.0.1:8080(OpenSandbox's lifecycle server) and the same route allow-list astls-front, 404 for everything else; no redirects, no response caching, no buffering oftext/event-streamresponses; - the
OPEN-SANDBOX-API-KEYandX-EXECD-ACCESS-TOKENheaders passed through and kept out of access logs.
tls-init can still mint the CA and the runner's client certificate for such a proxy.
-
See what exists. Central:
central workspace list [-fleet F] [-json](all operators; statesopening,open,closing,closed,failed,lost). Runner host:runner workspace list(straight from the executor, no central needed). -
Kill one.
central workspace kill ID. If its runner is offline you getclosing; the reaper will finishand the row keeps its slot until the runner returns. -
Automatic cleanup. The reaper (every 60 s) closes a workspace that is idle past
-idle-ttl(measured from the later of its last use and central's start, so a long outage does not wipe everything on restart), past-max-ttl, or owned by a revoked operator or runner. A workspace with a command running is never idle-reaped. -
Restarting things. Restart the runner: its workspaces survive (they are containers in
containerd) and reconcile keeps them; egress listeners are re-attached when
egressis still allowed. Restart central:openingrows (a create it crashed in) becomefailed, everything else persists and is reconciled when each runner reconnects. -
Reconcile in a nutshell. Container exists but no row, or a finished row: destroyed (orphan).
Row
closing: destroyed, thenclosed. Rowopeningfor too long: destroyed,failed. Rowopenbut the container is missing or stopped:lost(slot freed, audited assystem). -
Revoking. Revoking an operator closes their workspaces (destroyed on the next sweep).
Revoking a runner marks its workspaces
closingand thenlost; the containers stay on that host, because a revoked runner never reconnects. Clean them up locally. -
Prune. On a runner host:
mirafleet runner workspace prune -data DIR -workspace FILElists workspaces older thanmax_ageand does nothing; add-yesto destroy them;-all -yesdestroys every workspace of this runner. It talks to the executor directly, so it works with central gone or the runner revoked. Stoprunner runfirst when you can (a destroy of something already gone is harmless, but two actors are untidy). A workspace with an unknown age is only removed by-all. -
Disk and kernel limits. Watch
containerd.rootand/var/lib/containerd. A fork bomb is stopped bypids, a memory hog is OOM-killed inside its cgroup, a runaway writer by the soft quota. Daemonised children of a command survive its timeout until the workspace is destroyed, bounded by those limits. -
Upgrades. Replace the binary and restart the runner. Existing containers keep working. A
changed
workspace.yamlapplies on restart; a changed fleet config (fleet workspace set) applies to new workspaces only.
- Dedicated host or VM;
workspace.yamlroot-owned;containerd.rootroot-owned, 0700. -
userns: required(the default) works on this host;apparmor: autoorrequired. - Image allowlists use digests (
@sha256:*), on both the fleet and the runner. -
network: [none]unless you need egress; egress hosts listed as narrowly as possible. -
env_allowas short as possible; no secrets in workspaces, ever (the denylist is a backstop). - Guarded fleets (
-confirm) only on runners with asecure_runtime, and without egress on containerd. - You know how to
prune, and where to look:central audit,central workspace list, the runner'saudit.jsonl.
This section is for the person who sits at a laptop and wants an agent (Claude Code, opencode, or any other MCP-capable tool) to work on the fleets. Terms: glossary (harness, MCP tool, context, project default, session handoff). The design is in chapter 3 and chapter 5; the protocol is section 7.13.
Three pieces, all on the laptop:
- The
mirafleetbinary on yourPATH(Linux, macOS or Windows; build it as in Step 0). - A login: a key pair, central's pinned host key and a named context, made once by
mirafleet mcp login. A human does this step. The MCP server never registers a key by itself, so an agent cannot create an identity. - A harness integration: the few lines that tell your agent to start
mirafleet mcp(a plugin for Claude Code, a config snippet for opencode or others).
Nothing is installed on central or the runners for M5: a laptop is just another operator (chapter 4).
Get a fresh code from aarvee (Step 9: mirafleet central operator code; it lives 60 seconds and
any number of operators can use one), then, on durga's laptop:
$ echo "$CODE" | mirafleet mcp login central.example.com:2222 -name durga -code -
registered operator "durga" (active); context "durga" -> central.example.com:2222 is now current
config: /Users/durga/Library/Application Support/mirafleetOn Windows, pipe the code in the same way (for example $code | mirafleet mcp login central.example.com:2222 -name durga -code - in PowerShell). The code is never a command-line
argument: it would be visible in the process list and the shell history. The output's last line
names the config directory; the table in section 10.4 lists the default for each OS. Check:
$ mirafleet mcp context list
* durga central.example.com:2222 default_fleet=-On Windows the first login creates %LocalAppData%\mirafleet with the protected permission list
described in section 10.4. If the key's permissions are wrong later (someone copied the folder,
a backup tool reset the permissions), the server will say it cannot use the key. Do not loosen
anything; run mirafleet mcp login again after deleting the config directory if you need a new
identity (the old one stays registered until aarvee revokes it).
A context is a name plus a central address. One laptop can hold several: mcp login with a
different -name adds one and makes it current.
$ mirafleet mcp context list
* work central.example.com:2222 default_fleet=dev
cloud cloud.example.net:2222 default_fleet=-
$ mirafleet mcp context use cloud
current context: cloud
$ mirafleet mcp context remove cloud
removed context cloudWhich context and fleet a tool call uses, in order: the tool's own context / fleet argument,
then the server's -context / -fleet flags, then the project's .mirafleet.yaml, then (for the
context) the current one or the only one, and (for the fleet) the context's default_fleet.
The result of every tool call says what it picked and why (where, chapter 7).
A guarded fleet is never taken from the last two sources: it must be named in the call and
confirmed by the user.
To give a repository a default, commit a .mirafleet.yaml with fleet: dev (section 10.4). It is
safe to commit: it holds only names.
The plugin is in the repository at integrations/claude-code/. Until M6 ships a marketplace entry,
load it from a checkout:
claude --plugin-dir /path/to/mirafleet/integrations/claude-codeWhat it gives Claude Code:
- the MCP server:
.mcp.jsonrunsmirafleet mcp -project-dir ${CLAUDE_PROJECT_DIR}, so the project file is found from your project, not from wherever Claude Code was started. In/mcpthe server is calledplugin:mirafleet:mirafleet, and its tools aremcp__plugin_mirafleet_mirafleet__<tool>; - the commands
/mirafleet <task>,/openfleet <task>and/claudefleet <task>: one skill text (the aliases are copies) that tells the model how to use the tools. If another plugin already owns the bare name, Claude Code needs the prefix:/mirafleet:mirafleet; - three hooks (small programs Claude Code runs at fixed moments), all of them
mirafleet mcp hook claude-code <event>:session-startwrites the session id so a resumed conversation reattaches to its workspace;session-endcloses that session's workspaces when you/clearor log out (other exits leave them to the idle timer);pre-tool-useadds a visible "ask" prompt whenever a call carriesconfirm.
The hooks are conveniences. Without them the tools still work and central still enforces
confirm; see chapter 11. The plugin ships no
binary: mirafleet must be on the PATH of the process that starts Claude Code.
Any harness that can start a stdio MCP server works with no hooks. The command is always
mirafleet mcp -project-dir DIR; only the file it goes into differs.
For opencode (integrations/opencode/): copy commands/*.md to .opencode/commands/ (or
~/.config/opencode/commands/) for /mirafleet and /openfleet, and add the entry from
opencode.example.json to opencode.json:
{
"mcp": { "servers": { "mirafleet": { "type": "local",
"command": ["mirafleet", "mcp", "-project-dir", "."] } } }
}The shape of this entry follows opencode's documentation as read on 13 Nov 2026; it has not been tried against a real opencode, and an older release may expect another shape (the opencode README lists what to try).
For any other harness (integrations/generic/): a JSON like
{"mcpServers":{"mirafleet":{"command":"mirafleet","args":["mcp","-project-dir","."]}}}, with an
absolute -project-dir if the harness does not start the server in your project. For Claude Code
without the plugin: claude mcp add mirafleet -- mirafleet mcp.
What you give up without the Claude Code hooks (the table is integrations/README.md):
| Without hooks | Claude Code plugin | |
|---|---|---|
| Reattach to the workspace after a restart | only with -session NAME in the command |
automatic (cc:<session id>) |
| Close workspaces at the end | no: the idle timer reaps them (default 24 h per fleet) | on /clear and logout |
| Extra "are you sure" on a guarded call | the harness's own tool-approval prompt | plus the hook's ask
|
| Guarded calls without the user's agreement | refused by central | refused by central |
Each harness session gets its own workspace on a workspace fleet (the first exec, read_file or
write_file opens one on an unguarded default fleet; a guarded fleet needs an explicit
workspace_open). The session id comes from, in order: -session NAME; the handoff file a hook
wrote for this harness process and project; a random per-process id. workspace_open reports which
one it used (session_source: flag, handoff or process). The server never closes a workspace
when it exits, because a restart is exactly when you want it back. The idle timer closes forgotten
ones (fleet idle_ttl_s, section 10.9); workspace_list and workspace_close clean up by hand; an
admin can see everything with central workspace list.
The MCP server reads: its flags; MIRAFLEET_CONFIG_DIR; MIRAFLEET_STATE_DIR; your home
directory and the OS's standard config and cache locations (to find the defaults and to stop the
.mirafleet.yaml search at home); and its parent process id (the handoff key). It forwards
nothing from its environment. The env of a workspace command comes only from the env argument
of the tool call, which must pass the hard denylist and the runner's env_allow
(chapter 7: workspace.EnvDenied is the source of truth). So an
ANTHROPIC_API_KEY in your shell never reaches a workspace, and the tests set decoys to prove it.
Tool results never contain key material, local file paths, environment values or registration
codes, because they go to the model provider.
First, see the server's own messages. They go to stderr with the prefix mirafleet mcp:. Run
mirafleet mcp by hand in a terminal (it prints a hint and waits; Ctrl-C ends it) to check it starts,
and use your harness's MCP log view (in Claude Code, /mcp, and claude --debug) for the rest. The
text the model sees is deliberately short and has no paths; the detail is on stderr. Tool errors
are written below as code: message; on the wire they are {"error":{"code":"...","message":"..."}}
(chapter 7).
| Symptom or message | What it means | What to do |
|---|---|---|
The harness shows the server as failed, or the tools are missing; Claude Code /mcp shows plugin:mirafleet:mirafleet failed |
PATH. The harness started mirafleet and the system could not find it. A harness started from a desktop icon, an IDE or a service does not inherit your shell's PATH. On Windows it must be a real mirafleet.exe, not a .cmd/.bat wrapper. |
which mirafleet (where mirafleet on Windows) in the same kind of environment; put the binary in a system-wide directory, or start the harness from a shell where it resolves. |
Tool error unavailable: not set up: run mirafleet mcp login ...`` |
Not set up. No context, no key, an empty known_hosts, or the config directory cannot be found (no %LocalAppData%, no home). The server still starts and lists its tools. |
mirafleet mcp context list. If empty, log in (10.10.2). If it lists contexts, the harness may run with another user or MIRAFLEET_CONFIG_DIR than your shell: compare. |
unauthenticated: the operator key cannot be used: run mirafleet mcp login ...`` |
The key file is unreadable or its permissions are wrong (mode wider than 0600, or on Windows an owner or permission list that is not private). Detail is on stderr. | Fix who can read the file (chmod 600); on Windows, do not edit the list by hand, re-create the config directory. |
unauthenticated: central rejected the operator key: run mirafleet mcp login ...`` |
Central does not know this key: your operator was revoked, you never registered, or aarvee replaced central's database. | Ask aarvee to check central operator list. A revoked operator needs a new key (delete the config directory and log in again). |
unavailable: central's host key does not match the pinned key; the server may have been rebuilt or intercepted |
Host-key pinning. The key central presented is not the one saved in known_hosts at login. Either central was rebuilt (a new central init creates a new key), or someone is in the middle. No request was sent. mirafleet never trusts a new key automatically. |
Do not just retry. Ask aarvee for central's fingerprint (it is printed by central operator code, "host key") and compare. If the rebuild is expected, log in again with a fresh code: it replaces the pinned line for that address. |
unavailable: cannot reach central (one context) |
A dead context. Wrong address, central down, firewall, or no network. Other contexts still work: list_fleets shows the dead one as an entry in errors[] and the rest as normal. |
mirafleet mcp context list (is the address right?), check central is running and reachable on its port. mirafleet mcp context remove NAME drops a context you no longer use; context use NAME changes the current one. |
bad_request: no context selected: pass context(one of a, b) or runmirafleet mcp context use NAME`` |
Several contexts and none is current, none given by flag or project file. |
mirafleet mcp context use NAME. |
not_found: unknown context "x" (known: ...) |
A flag, the project file or the model named a context you do not have. | Fix .mirafleet.yaml or the -context flag. |
bad_request: the project file .mirafleet.yaml is invalid / the contexts file is invalid
|
Strict parsing: unknown key, bad name, a second YAML document, output_cap_bytes out of range, a jump key. |
Fix the file; mirafleet mcp context list prints the real reason. |
bad_request: fleet "prod" is guarded and was taken from the project file: name it explicitly (and ask the user before confirming) |
The project file or default_fleet points at a guarded fleet. This is refused on purpose. |
Name the fleet in the call, and let the user approve it. Do not default a project to a guarded fleet. |
bad_request: no fleet selected: name one with fleet (see list_fleets)
|
No fleet from the call, flags, project file or context default. | Add fleet: dev to .mirafleet.yaml or name it. |
bad_request: fleet ... is guarded. Ask the user. Only after the user explicitly agrees, repeat the call with confirm set to the fleet name.
|
A guarded fleet. The text is written for the model. | The human decides; the model repeats the call with confirm set to the fleet name after a clear yes. |
bad_request: invalid arguments: unknown or mis-cased argument "Confirm" |
A tool call used a key in the wrong case, a repeated key or an unknown one. | Expected from a confused model; keys are exact (confirm, fleet). |
unavailable: the connection to central was lost; the call may or may not have completed |
The connection died during an exec, write_file, action.run or workspace_close. These are never retried, because they may already have run. |
Look at what happened (workspace_list, the audit log with central audit) before running it again. Lists and reads are retried by themselves. |
unavailable: central is busy: too many concurrent calls; try again |
Central's limit of 8 channels per connection was hit. | Retry; ask the agent not to run many calls at once. |
timeout: the call timed out |
The client-side limit passed (timeout_s plus 30 s; 2 minutes for other calls; 5 minutes 30 s for workspace_open). |
Raise timeout_s or fix the command. |
canceled: request canceled |
The harness cancelled the call (you pressed Esc, for example). The command on the runner is cancelled too; the audit shows cancelled. |
Expected. |
mirafleet: mcp server stopped: ... on stderr, exit code 1 |
A malformed frame. Something wrote a line that is not valid JSON-RPC to the server's stdin. The server closes the session, exits 1 and does not echo the input. Typical causes: a shell wrapper or an alias around mirafleet that prints a banner to stdout, an IDE launcher that mixes output into the pipe, or a test typo. |
Run the exact command from your harness config in a terminal and check it prints nothing on stdout by itself. Use the binary directly in command, not through a script that writes to stdout. The harness will restart it. |
After the plugin loads, every mirafleet tool call is blocked, or the hook log shows mirafleet printing its usage text |
PreToolUse and exec-form args. The plugin's hooks are written in "exec form": a command plus an args list, started without a shell (so they work on Windows). A Claude Code release that does not know args runs the bare mirafleet, which prints its usage and exits with code 2, and for a PreToolUse hook exit code 2 means "block this tool call". The minimum Claude Code version for args is not stated in the documentation we read. |
Update Claude Code. As a stopgap that loses only the convenience hooks, register the server without the plugin: claude mcp add mirafleet -- mirafleet mcp. Central still enforces confirm. |
| Hooks seem silent | They are silent by design except pre-tool-use with confirm. |
Run one by hand: echo '{"session_id":"x","cwd":"."}' | mirafleet mcp hook claude-code session-start should print nothing and exit 0. claude --debug shows hook runs. |
| A resumed conversation did not find its workspace | Reattach needs the hook's handoff to be keyed by the same parent process as the server (assumed for Claude Code, checked by hand in M5 step S17), or -session NAME. |
workspace_list shows your workspaces; use their workspace id explicitly, or set -session. |
| Workspaces left over after you quit | Only /clear and logout close them; other exits leave them to the idle timer. |
workspace_list, workspace_close, or wait (24 h by default). |
-
mirafleet versionworks in the environment that starts your harness (samePATH). -
mirafleet mcp context listshows the contexts you expect; the current one is the one you want. - Guarded fleets are not anyone's default (
.mirafleet.yamlordefault_fleet). - You know which hooks you have (Claude Code plugin) and what you give up without them.
- You can find your workspaces (
workspace_list) and the audit trail (central auditon central).
The admin GUI is a web console that central itself serves to aarvee's browser. It shows what
mirafleet central ... shows and lets aarvee do the same changes, with a confirmation step on every
destructive one. It is not for agents or operators (they have no password and no way to reach it
that matters), and it is not a second implementation: each click calls the same service method
as the matching CLI command and leaves the same audit row, with source gui instead of cli
(chapter 8.11).
| Screen | What aarvee does there | CLI equivalent |
|---|---|---|
| Overview | Counts, runners waiting for approval, recent and denied audit rows; refreshes itself every 10 s |
runner list, audit
|
| Fleets | Create a fleet, edit a workspace fleet's config, turn the confirm guard on or off |
fleet create, fleet workspace set, fleet set
|
| Runners | List, filter, approve, disable, enable, revoke (type fleet/runner to confirm) |
runner list|approve|disable|enable|revoke |
| Join tokens | Create (shown once, with the runner join command to copy), revoke |
token create|list|revoke |
| Operators | Show the registration code, rotate the secret, revoke an operator | operator code|rotate-secret|list|revoke |
| Workspaces | See every operator's workspaces, kill one |
workspace list, workspace kill
|
| Audit | Filter, page, export the log as CSV or JSON lines |
audit with its filters |
| Account | Change the password, see and end sessions, light or dark theme, the certificate fingerprint | (GUI only) |
Use the CLI in scripts and over SSH; use the GUI to look around, to see what an agent did, and for one-off changes. Everything works without JavaScript; the scripts only add copy buttons, the registration-code countdown and live refresh.
Look at: the token travels as a file on the central host, never through the log, and the setup page disappears once it has been used.
- Central starts with no admin: it makes a setup token and stores only its SHA-256 and a 24 h expiry.
- It writes the token to
DATA/gui/setup-token(mode 0600). The log names the file, never the token. - aarvee reads the file, opens
/setup(every page redirects there) and checks the certificate fingerprint. - aarvee sends the token, a username and the password twice, with a CSRF token from a short-lived cookie.
-
CompleteGUISetup, one transaction: compare the hash, check expiry, insert the admin, delete the row. - The token file is deleted and aarvee's first session starts (hash stored, cookie sent).
/setupis now 404.
The first start of central prints something like this (shortened):
GUI setup: no admin account yet. The one-time setup token (valid 24h) is in /var/lib/mirafleet/central/gui/setup-token; open the GUI URL below and paste it.
GUI listening on https://localhost:8443/ https://192.0.2.10:8443/ https://central.example.com:8443/
GUI certificate (self-signed) SHA-256 fingerprint: 3A:7F:...:C1, valid until 2028-11-15
GUI is reachable on all interfaces (0.0.0.0:8443). To restrict it: -gui-listen 127.0.0.1:8443 (then use ssh -L), -gui-listen off, or a firewall rule for port 8443.
Check that your browser's certificate fingerprint matches 3A:7F:...:C1 before you type the setup token or your password.What aarvee does:
- On the central host, as central's user:
cat /var/lib/mirafleet/central/gui/setup-token. Anyone who can read that file can become the admin, which is why the data directory is mode 0700. - Open one of the logged URLs. The browser warns that the certificate is not trusted, because central made it itself. Open the certificate details, compare the SHA-256 fingerprint with the line in the log, and only if they match, continue.
- Paste the token, choose a username (lowercase letters, digits,
.,_,-, as for an operator name) and a password of 12 to 256 characters. There are no composition rules; a long passphrase is best. - aarvee lands on Overview. The token file is gone and
/setupnow answers 404.
Why the fingerprint check matters. On the first visit the browser has nothing to compare the
certificate with. If someone on the network answered at central.example.com:8443 before central
did, aarvee would type the setup token and then a new password into their page. The fingerprint in
central's own log is the one thing they cannot fake. After the first visit, the browser remembers
the certificate (or aarvee imports it), and a change is a visible warning. The safest first visit is
through an SSH tunnel (section 10.11.3, option 1), where the traffic never touches the LAN.
The token expired, or the file is gone. The token lives 24 hours. If it ran out, or someone
deleted the file, restart central: while no admin exists it makes a new token and writes a new
file. Or run mirafleet central gui reset-admin, which prints a new token (section 10.11.7).
The default is -gui-listen 0.0.0.0:8443: all network interfaces, TLS only. That is
deliberate: the usual admin sits at a laptop and the central server is in a rack or a cloud
network, so a loopback-only default would make the GUI unusable until someone changed a flag. The
cost is that anyone who can reach port 8443 sees the login page. What they can do from there:
- see
/loginand try passwords (rate-limited: 5 tries a minute and a 15-minute lockout per address after 10 failures; one global slow-down when a flood is detected); - nothing else. Every other page redirects to
/loginand shows no data, version or runner name. Before the first setup, every page redirects to/setup, and only the setup token opens it.
If your central server is on an untrusted network, tighten it. Pick one:
-
Loopback only, reach it by SSH tunnel. Run
central run -gui-listen 127.0.0.1:8443. From a laptop, aarvee runsssh -L 8443:127.0.0.1:8443 aarvee@central.example.comand openshttps://localhost:8443/. The GUI is then not on the network at all, andlocalhostis always an acceptedHost. -
Off.
-gui-listen offstarts no listener (the log saysGUI is off (-gui-listen off)). Use the CLI only. - A firewall rule for port 8443 that allows only the admin's address range. Do this in addition if the GUI must stay reachable.
-
A specific interface.
-gui-listen 10.0.0.5:8443binds one address (for a management network).-gui-listen :8443binds IPv4 and IPv6 on all interfaces.
The Account screen repeats the bind and the notice, so you can check later what a running central is doing.
By default central makes a self-signed certificate on the first GUI start: ECDSA P-256, two
years, in DATA/gui/tls.crt and tls.key (the key mode 0600, the directory 0700). Its names are
localhost, the host name of the machine (short and full), every -gui-host name and the IP
addresses the machine had when it was made. It is renewed when it has under 30 days left or when
the -gui-host set changes (the browser then warns again: compare the fingerprint again). The
fingerprint is in the log on every start and on the Account screen.
To use your own certificate (from your organisation's CA), give both files:
$ mirafleet central run -gui-cert /etc/ssl/mirafleet/gui.crt -gui-key /etc/ssl/mirafleet/gui.keyThe key file must be owned by central's user and not readable by group or others (mode 0600 or
0400), or central refuses to start. Central reads the files at start only; restart it after a
renewal. TLS 1.3 is the minimum either way; there is no plain-HTTP mode at all, because the
cookies need the Secure flag and a downgrade path is a way to get it wrong.
HSTS (a header that tells the browser "only ever use HTTPS for this name") is sent only with your own certificate. With the self-signed one it would do harm: browsers apply HSTS to a whole host name regardless of port, so it would also hit other services on that host, and an HSTS site with a certificate error has no "proceed anyway" button, which would lock aarvee out.
Central answers only for Host values it knows, and replies 421 Unknown host name to anything
else, before it looks at the path. This stops DNS rebinding: a web page on rebind.evil.example
whose DNS later points to central's address would make aarvee's browser send requests to the GUI
with the attacker's host name in them (chapter 5). The accepted forms:
| Form | Accepted when |
|---|---|
localhost, 127.0.0.1, [::1]
|
always |
an IP address of this machine (192.0.2.10, a bracketed IPv6 address) |
it is an address of an interface that is up (re-read every 60 s, so a DHCP change is picked up; link-local excluded) |
the machine's host name (central-01 and central-01.example.com) |
always |
a name from -gui-host (repeatable or comma-separated) |
exact, case-insensitive match; no wildcards |
a DNS name in your -gui-cert certificate |
exact match |
Any port is accepted (tunnels and proxies change it). 0.0.0.0 is never accepted. A name that
embeds an IP (192-168-1-5.nip.io) is refused unless you list it, because anyone can create such
names. So if aarvee reaches central as central.example.com through DNS, start it with
-gui-host central.example.com; if you forget, you get the 421 page.
Supported only as TLS to TLS: the proxy opens an HTTPS connection to central (it must trust
central's certificate or be given your own) and forwards a Host that is on the allowlist
(-gui-host). Two consequences to know:
- Central ignores
X-Forwarded-Forand similar headers on purpose, because any client could forge them. The address it logs, audits and rate-limits is the TCP peer: the proxy. So behind a proxy all admin logins share one rate-limit bucket, and ten wrong passwords from anyone lock the login for everyone for 15 minutes. If that bothers you, rate-limit at the proxy as well. - Audit rows show the proxy's address as the
remote.
-
Sessions live in the database, so they survive a restart of central. A session ends after 30 minutes without activity or 12 hours after login, whichever comes first, and aarvee can have at most 16 at once (the oldest is dropped). The idle timer counts clicks, not open tabs: the pages that refresh themselves every 10 s do not extend it.
-
Changing the password (Account screen, needs the current one) ends every other session at once; the session that changed it stays. Sign out other sessions does the same without changing the password. Both take effect on the other browser's next request.
-
A lost password or a lost admin. On the central host, as central's user:
$ mirafleet central gui reset-admin mfs1.EXAMPLE_SETUP_TOKEN_NOT_REAL GUI admin reset: all GUI sessions ended. Open the GUI and paste this setup token (valid 24h, shown once).
The token goes to stdout, the note to stderr, so
$(...)captures just the token. Every GUI session ends at once and the setup page reopens; aarvee chooses a username and a password again. The audit log keeps the old admin's history and recordsgui.reset_admin. If you restart central before using the token and no file exists, central makes a new token and writes it togui/setup-token. Recovery needs a shell on the central host on purpose: it can not be started from the GUI or overapi@mirafleet. -
A copied database file does not give an attacker a session. The database holds only a SHA-256 of each session token and an Argon2id hash of the password, and the cookie value is not derivable from either (chapter 5).
-
There is one admin account. Several people means sharing it; audit rows then say
admin, not who. A second account or single sign-on is an enterprise feature that the OSS edition leaves a seam for.
Everything the GUI changes is in the same log as the CLI's, with source gui:
$ mirafleet central audit -source gui -action-prefix -action runner.
$ mirafleet central audit -source gui -action-prefix -action gui.The gui.* actions are gui.setup_token, gui.setup, gui.login, gui.logout,
gui.password_change, gui.session_revoke, gui.reset_admin (source cli) and gui.lockout
(one row per address per lockout). audit.export is written before any export streams. Failed
logins are in central's log (address, clipped username, never the password), not in the audit
table. Changes made through the GUI show the browser's address as remote.
The -advertise HOST:PORT flag sets the SSH address the GUI prints in copy-paste commands (the
runner join line on a new join token, the mcp login line next to the registration code). If you
leave it out the hints say CENTRAL:2222 and you replace it by hand.
| What you see | What it means | What to do |
|---|---|---|
Browser: "Your connection is not private" (NET::ERR_CERT_AUTHORITY_INVALID) at the first visit |
The certificate is self-signed. | Compare the fingerprint in the browser with the one in central's log, then continue. Better: use an SSH tunnel for the first visit, or give central a real certificate (-gui-cert). |
| The same warning appears again later | The certificate was regenerated (under 30 days left, or -gui-host changed), or you are not talking to central. |
Compare the fingerprint with the log's current line. If it differs and you did not change anything, stop and ask why. |
421 Unknown host name |
The address in your browser is not one the GUI answers for. | Use an address from central's start-up log, or restart central with -gui-host YOUR.NAME. Behind a proxy, make the proxy send an allowed Host. |
Too many attempts. Try again in N minutes. (status 429 with Retry-After) |
Your address had 10 failed logins in a row, or too many in a minute; behind a proxy it may be someone else's failures. | Wait. The lockout lasts 15 minutes. It never locks the account itself. |
Busy / 503 on login |
More than two password hashes in flight; the wait ran out. Argon2id is deliberately slow and memory-hungry. | Try again in a moment. Many 503s suggest a flood: look at central's log for lockout lines. |
| Setup page says "Setup is not available with that token" | Wrong, expired or already used token, or you lost a race. | Read gui/setup-token again; if the file is gone, restart central or run gui reset-admin. |
/setup is 404 |
An admin exists. | Sign in at /login. If the password is lost, mirafleet central gui reset-admin. |
Everything redirects to /login, or "you were signed out" |
The session expired (30 min idle, 12 h), you changed the password elsewhere, or the admin was reset. | Sign in again. |
| 403 "You are not allowed to do that" after a form | The CSRF check failed: the page was open too long after a sign-in change, or the request came from another site. | Reload the page and submit again. If it happens on a fresh page, something is rewriting Origin headers (a proxy). |
| 413 or 415 | The form was over 64 KiB or not an ordinary form. | Only scripts do that; use the browser form. |
| Nothing at all on port 8443 |
-gui-listen off, a firewall, a loopback bind (reach it through ssh -L), or central did not start. |
ss -ltn on the central host; read central's log for GUI listening on or GUI is off. |
Central exits at start with gui: -gui-key ... has mode 0644; it must not be accessible to group or others (chmod 600) (or is owned by uid N, not by central's uid) |
The key file's mode or owner is wrong. |
chmod 600 it and make central's user the owner. |
Central exits with listen tcp 0.0.0.0:8443: bind: address already in use
|
Something else uses 8443. | Free it, or choose another port with -gui-listen. |
| A 500 page with a request ID | A bug. The details are only in central's log. | Find the line req=<ID> in the log and report it. |
- You know who can reach port 8443 and you chose that on purpose (default: everyone who can reach the host).
- The first visit is through an SSH tunnel or you compared the fingerprint with central's log.
-
-gui-hostlists the names people type, and the proxy (if any) is TLS to TLS. - The data directory is mode 0700 and backed up as a unit; the backup holds the admin's password hash, so treat it as private.
- You tried
mirafleet central gui reset-adminonce, on a test central, before you needed it.
Until now this chapter ran the binary by hand. M6 adds real install channels. This section explains the choices and the failure modes; the copy-and-paste steps are in QUICKSTART.md, which this section does not repeat. The maintainers' side (how a release is made) is RELEASING.md and chapter 11.9.
MIRASTACK LABS has spare servers and VMs. aarvee installs central on one, raj installs runners on the spare machines, and durga, kalyan and sid install the operator binary on their laptops. Each person uses the channel that fits their machine.
| Channel | For | You get | Notes |
|---|---|---|---|
.deb / .rpm / .apk
|
central and runners on Linux | binary, systemd units, /etc/mirafleet/, example configs |
Starts nothing and enables nothing. .apk has no systemd units. |
| OCI image | central, and actions-mode runners |
docker.io/mirastack/mirafleet, also ghcr.io/mirastacklabs-ai/mirafleet: the same image, same digest |
scratch base: no shell, runs as UID 65532. No container-workspace or host mode inside the image (they need host containerd or a real OS user). |
| Docker Compose | central, a runner, or a one-machine lab | deploy/compose/{central,runner,lab} |
First-class install; image tag pinned to the release. |
| Homebrew | operator laptops (macOS, Linux) | brew install mirastacklabs-ai/tap/mirafleet |
Formula rendered from checksums.txt. |
install.sh / install.ps1
|
operators | binary only | Always checks the SHA-256. See 10.12.5. |
| npm | operators whose harness config runs npx
|
@mirastacklabs/mirafleet |
Binary comes in a platform package; no scripts run. |
| Archive | anyone | binary, licences, quickstart | Check it against checksums.txt yourself. |
| Claude Code plugin | operators | skill, commands, hooks | Marketplace mirastacklabs; needs the binary too. |
Why packages and not only a binary? A package gives a system user, the directories with the right modes, and units that already carry the sandbox settings, so the safe setup is the default one.
- A system user and group
mirafleet(home/var/lib/mirafleet, no login). -
/var/lib/mirafleet/centraland/var/lib/mirafleet/runner, mode 0700 owned bymirafleet;/var/lib/mirafleet/runner-ws, 0700 root, for container workspaces. -
/etc/mirafleet/central.env, mode 0600 root (systemd reads it as root before dropping tomirafleet, so it can hold a secret), and/etc/mirafleet/runner.env. - Three units:
mirafleet-central.service(strict sandbox),mirafleet-runner.service(actions mode, light sandbox, starts only ifrunner.yamlexists, i.e. afterrunner join) andmirafleet-runner-workspace.service(root, container workspaces, aftercontainerd.service). - Example configs in
/usr/share/doc/mirafleet/examples/. There is no liveactions.yaml: the runner refuses to start without one, so you must write yours on purpose.
The package never enables a unit and never deletes /var/lib/mirafleet or the user, not even on
purge. Why? Deleting a database or a user on package removal is exactly the kind of mistake
nobody can undo; wiping a machine is the admin's deliberate act. The maintainer scripts are
idempotent (running them twice changes nothing), so a failed upgrade can be re-run.
Admin commands must run as the unit's user, because the admin socket checks the caller's UID:
sudo -u mirafleet mirafleet central ... (container: docker exec <c> mirafleet central ...).
Port 443 (or any port below 1024). The strict sandbox gives central no capabilities, so it
cannot bind a low port. Add a drop-in with systemctl edit mirafleet-central:
[Service]
AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICEand set MIRAFLEET_LISTEN=0.0.0.0:443 in central.env. You grant exactly one capability instead
of weakening the whole sandbox.
Host-mode runner users (M7). Host mode runs the agent as a real OS user on a VM, one runner
per user. The package creates no such users; raj does it: useradd -m dev,
loginctl enable-linger dev (without linger the user's systemd instance, and so the runner,
stops when dev logs out), then as dev joins the runner and enables the user unit
(systemctl --user enable --now mirafleet-runner). A second runner uses a second user such as qa.
The alternative is the system unit mirafleet-runner@dev. See
QUICKSTART section 4.
Port 2222 must be reachable by runners and operators. The Admin GUI listens on all interfaces
(0.0.0.0:8443, self-signed certificate) by default, so either allow 8443 only from admins'
networks, or put -gui-listen 127.0.0.1:8443 in MIRAFLEET_CENTRAL_ARGS and reach it with
ssh -L 8443:127.0.0.1:8443. The packages never touch the firewall. Compose publishes 8443 on
127.0.0.1 only unless you edit the file. Central needs no outbound access, except HTTPS to
GitLab when host-mode token self-rotation is used (the image has no CA bundle, so that case needs
a CA file mounted read-only). At the first visit compare the browser's certificate fingerprint
with the one in the journal (10.11).
deploy/compose/central/compose.yaml has two services: a one-shot central-init (creates the
host key, database and registration secret; safe to repeat) and central, which waits for it with
depends_on: condition: service_completed_successfully. Data lives in a named volume, so
docker compose down keeps it and docker compose down -v deletes it. A runner joins with a
one-shot docker compose run --rm runner runner join ... -token - (token on stdin, so it is not
in ps). deploy/compose/lab runs central, a runner and an operator on one machine for trying
things out.
With plain docker run the same two steps are two commands: central init, then central run.
Without a shell in the image, read the GUI setup token with docker compose cp or docker cp <container>:/var/lib/mirafleet/central/gui/setup-token -.
There are three different checks, and they prove different things:
| Check | Proves | Does not prove |
|---|---|---|
Checksum (sha256sum -c checksums.txt) |
The file is the one listed: not corrupted, not swapped on a mirror. | Who made checksums.txt. An attacker who replaces the file can replace the list too. |
Signature (cosign on checksums.txt) |
checksums.txt was signed by this repository's release.yml workflow for a tag, via GitHub's OIDC identity. Together with the checksum this ties the file to the official pipeline. |
That the source code is free of bugs or malice. |
Provenance (gh attestation verify FILE --repo mirastacklabs-ai/mirafleet) |
A statement, signed by the workflow, saying which commit and workflow built that exact file. | Same: it says where it came from, not that it is good. |
Keyless signing means there is no long-lived private key to steal: the workflow asks Sigstore
for a short-lived certificate tied to its identity. You verify by checking that identity:
cosign verify-blob --bundle checksums.txt.sigstore.json --certificate-identity-regexp '^https://github\.com/mirastacklabs-ai/mirafleet/\.github/workflows/release\.yml@refs/tags/v' --certificate-oidc-issuer https://token.actions.githubusercontent.com checksums.txt. Images are
verified the same way with cosign verify on both registries; the digests must match.
install.sh always verifies the SHA-256 and refuses if the archive is not listed, on a mismatch,
or if the machine has no SHA-256 tool. It verifies the signature when cosign is present and
requires it with --verify-signature. It uses HTTPS only, extracts only the binary and runs
never runs sudo (for a system-wide install run sudo sh install.sh -b /usr/local/bin yourself). install.ps1 does the same on Windows and changes your PATH only
with -AddToPath.
Quarantine. mirafleet is not code-signed by Apple or Microsoft (no accounts, no fee, and
checksums plus cosign give a stronger story for this audience). A zip downloaded in a browser
carries a "from the internet" flag, so macOS or Windows blocks it. After you checked the checksum,
clear it: macOS xattr -d com.apple.quarantine mirafleet; Windows Unblock-File .\mirafleet.exe.
Homebrew, npm and the two scripts download without a browser and are not affected.
Order: central first, then runners, then operators (7.15). Central accepts runners and operators one level behind, so everything keeps working while you walk through the fleet. For central:
sudo apt install ./mirafleet_0.7.0_linux_amd64.deb # or dnf; Compose: change the image tag, docker compose up -dThe package try-restarts the running system units (mirafleet-central, mirafleet-runner,
mirafleet-runner-workspace and every mirafleet-runner@* instance). It cannot reach a user's own
units: after an upgrade, each user who runs the runner as a user unit restarts it with
systemctl --user restart mirafleet-runner. When central starts with a database that is
older than the binary, it makes an online backup first: VACUUM INTO
<data>/backups/mirafleet-schema<N>-<UTC time>.db (directory 0700, file 0600), then migrates, then
keeps the 3 newest backups. Why before, not after? A migration that fails halfway or loses data
cannot be undone from the damaged database. If the backup itself fails (disk full, wrong
permissions) central does not migrate and does not start, with an error that says why; losing
availability for a minute beats losing the database. A fresh database makes no backup. A database
newer than the binary is refused (database schema version N is newer than this binary supports ...: install a newer mirafleet, or restore a backup), so an accidental downgrade cannot
corrupt it.
Rollback, if the new version misbehaves:
- Stop central.
- Reinstall the previous version.
- Move
mirafleet.db,mirafleet.db-walandmirafleet.db-shmaside (do not delete them yet). - Copy the newest
backups/mirafleet-schema<N>-<time>.dbback asmirafleet.db. - Start central.
Writes made after the upgrade are lost: runners enrolled, tokens made, audit rows written.
The backups hold stored credentials exactly as encrypted as the database, so a restore needs the
same MIRAFLEET_SECRETS_KEY (back that key up apart from the data). The backups directory is
inside the data directory, so it is not an off-machine backup; copy it somewhere else too.
Uninstall keeps the data and the user (10.12.2). Operators: brew uninstall mirafleet, delete
the install-script binary, npm needs nothing installed. Compose: see 10.12.4.
| What you see | Likely cause | Fix |
|---|---|---|
"runner db-1 is protocol 4, central needs 5 or 6: upgrade mirafleet on that runner" (runner journal: central refused this runner: ...; audit action runner.refused_version) |
The runner is too old. It retries only every ~60 s. | Upgrade that runner. |
| "central is protocol 6, runner db-1 is 7: upgrade central first" | Wrong upgrade order. | Upgrade central. |
The same texts with orchestrator instead of runner, as a tool error or from mcp login
|
The orchestrator is too old or too new. | Upgrade it (or central first). |
| Central will not start, error mentions the pre-migration backup | Disk full or backups/ not writable. |
Free space or fix the owner (mirafleet), start again. |
database schema version N is newer than this binary supports |
Old binary on a new database. | Install the newer version, or restore a backup. |
install.sh: checksum mismatch / "not listed" |
Corrupt or tampered download, or wrong version string. | Do not use the file; retry; check the version. |
| Runner unit does not start after install | No runner.yaml yet (no runner join) or no actions.yaml. |
Join, write the config, then start. |
| macOS "cannot be opened because the developer cannot be verified" | Browser-downloaded zip, quarantined. | The xattr one-liner above. |
| Windows "Windows protected your PC" | Same, for .exe. |
Unblock-File, or use install.ps1. |
This is the operator's manual for the M7 feature: a host-mode runner on a plain Linux VM, with credentials (an SSH deploy key, a GitLab token, a registry login) stored on central. The developer's Claude Code runs on a Mac; every tool call and every repository file lives on the VM; the secrets live on central and in the runner's memory, never in front of the agent. Design: docs/M7.md. Terms: glossary.
Caption: one session from open to cleanup; the directory outlives every step except the last. (The numbered list for this picture is in 8.13.)
Facts to hold on to before you start:
-
One runner is one operating-system user on one VM.
mirafleet runnerruns as an ordinary user (saydev), never root, and the agent's commands run as that same user. What the agent can touch is exactly whatdevcan touch, like Claude Code on a laptop. The VM is the boundary: use a VM that holds nothing you would mind the agent reading. -
More runners means another VM or another user on the same VM (
qa), enrolled separately and isolated by ordinary Unix permissions (home directories 0700). -
A runner serves one operator at a time. While
durgahas an open workspace onvm1-dev,kalyan'sworkspace_openthere is refused (conflict: busy: runner NAME is in use by durga) and placement picks another runner. Any registered operator may use any runner otherwise. - Containers are not involved. There is no containerd and no root. M3's container mode is unchanged and still available on other fleets.
- Network control is the VM's firewall. Host mode has no egress allow-list of its own.
Caption: a credential's value moves once, from central to the runner's memory. (Numbered list in 8.13.)
Names follow the running example: central central.example.com:2222, fleet dev, VM vm1, runner
vm1-dev, runner user dev, admin aarvee (who runs central), raj (who owns the spare VM and enrols its runner), operators durga and kalyan. Steps marked root need root on that
machine; the runner itself never does.
1. Central: create the secrets key (once). Central encrypts credentials with a 32-byte key
that it reads from the environment variable MIRAFLEET_SECRETS_KEY.
# on the central host, as root: append the line to the packaged env file (do not overwrite it)
mirafleet central keygen >> /etc/mirafleet/central.env # one line: MIRAFLEET_SECRETS_KEY=...
ls -l /etc/mirafleet/central.env # must stay -rw------- root rootThe package ships that file as 0600 root with a commented #MIRAFLEET_SECRETS_KEY= placeholder,
and mirafleet-central.service loads it with EnvironmentFile=/etc/mirafleet/central.env. Restart
central. (With Compose, write the line to the untracked, gitignored
deploy/compose/central/central.env.local, created with umask 077 or followed by
chmod 600; the tracked central.env there is only a template. With a plain container, pass it
with --env-file.) Back the key up somewhere other than the central host. If the key is lost,
every stored credential is lost (central refuses to start without the right key once credentials
exist, so a lost key never silently corrupts anything). The key is shown once, by keygen, on
standard output; the warning goes to standard error so >> does not capture it.
2. Central: create a host-mode fleet and a join token.
mirafleet central fleet create dev -mode workspace -executor host
TOKEN=$(mirafleet central token create -fleet dev)A host fleet takes no -image, -cpus, -memory, -pids, -tmpfs or -disk: the VM is the
boundary and workspace.yaml rejects limits for the host executor. A guarded host fleet is
allowed; guarding means only the typed fleet-name confirm (chapter 5).
3. The VM: one user, once (root).
useradd -m dev && chmod 700 /home/dev # the runner's own user
loginctl enable-linger dev # so its user services start at boot and survive logout
install -m 0755 mirafleet /usr/bin/mirafleetWhy chmod 700: a home directory that other users can list lets them read the runner's
enrolment key and the session directories.
4. The VM: join as dev. The token is read from stdin, never from the command line.
sudo -iu dev
printf '%s\n' "$TOKEN" | mirafleet runner join central.example.com:2222 -name vm1-dev -token -With no -data, a non-root runner keeps its key and config under $XDG_CONFIG_HOME/mirafleet
(~/.config/mirafleet), created 0700. Root keeps the system default /var/lib/mirafleet/runner
(and will refuse to run host mode anyway).
5. The VM: workspace.yaml.
# ~dev/.config/mirafleet/workspace.yaml
executor: host
concurrent: 8
host:
root: /home/dev/work # session directories live in <root>/sessions/<slug>
cleanup: {delete_after: 720h}
job_max: 12h
corporate_ca_file: /etc/ssl/corp/mirastack-root.pem # only if your GitLab uses a private CA
env_allow: [LANG, LC_ALL, TERM, CI, GOFLAGS, NODE_ENV]6. The VM: run the runner as a service. Two supported ways; the user unit is the first choice
because it needs no root after enable-linger.
A. systemd user unit (as dev; the unit ships in packaging/systemd/user/mirafleet-runner.service):
mkdir -p ~/.config/systemd/user
cp mirafleet-runner.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now mirafleet-runnerB. system unit with User= (root; packaging/systemd/mirafleet-runner@.service):
cp mirafleet-runner@.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now mirafleet-runner@dev # %i = devBoth run mirafleet runner run -workspace <home>/.config/mirafleet/workspace.yaml with
Restart=on-failure and KillMode=process. That last line matters: with the default
KillMode=control-group, stopping or restarting the runner would kill every background build the
agent started. With process, systemd stops only the runner and the job supervisors survive; the
restarted runner re-adopts them.
7. Central: approve the runner.
mirafleet central runner approve dev/vm1-dev
mirafleet central runner list8. Central: store and assign credentials (section 10.13.4 for what to create in GitLab).
mirafleet central credential set gl-deploy -kind ssh-key -hosts gitlab.example.com \
-known-hosts ./gitlab.known_hosts < ./deploy_key
mirafleet central credential set gl-token -kind https-token -hosts gitlab.example.com \
-user oauth2 -auth basic -expires 2027-06-30 < ./token.txt
mirafleet central credential assign gl-deploy -runner dev/vm1-dev
mirafleet central credential assign gl-token -fleet dev
mirafleet central credential listThe secret is always read from standard input, never a flag (a flag would land in shell
history and ps). list shows name, kind, hosts, a fingerprint, the expiry, the assignments and
the delivery status per runner. It never shows a value. There is no command that does.
9. The developer's Mac. The project's .mirafleet.yaml:
fleet: dev
remote: true # the plugin steers Claude to the remote tools
workdir: app # optional: share one directory between sessionsworkdir is a name (^[a-z0-9][a-z0-9._-]{0,62}$), never a path; central refuses it on a
non-host fleet. It resolves to <root>/work/app (0700, symlinks refused), so two Claude sessions
can work in the same checkout. Without it each session gets its own directory
<root>/sessions/<slug>. Then in Claude Code the model runs git clone git@gitlab.example.com:mirastack/app.git
with a plain URL: the credential is injected, so the model must never put a token in a URL.
10. A second runner. For a second user on the same VM: useradd -m qa && chmod 700 /home/qa,
then as qa repeat steps 4 to 6 (runner join ... -name vm1-qa, its own workspace.yaml,
mirafleet-runner@qa or its own user unit) and step 7 and 8 on central. Central sees two runners
and each is assigned credentials separately.
| Key | Meaning | Default |
|---|---|---|
executor |
host |
(required) |
concurrent |
most live workspaces on this runner | required, 1 to the maximum |
host.root |
directory holding sessions/<slug> and work/<name> (0700). ~ is expanded. |
$XDG_DATA_HOME/mirafleet/work |
host.cleanup.delete_after |
delete session directories unused this long (daily sweep). 0 = never. |
720 h (30 days) |
host.job_max |
longest a background shell may run; at most 24 h | 12 h |
host.corporate_ca_file |
absolute path of a PEM bundle the broker trusts, in addition to the system roots, for upstream TLS to credential hosts | none |
env_allow |
runner-environment names passed to commands, in addition to HOME USER LOGNAME PATH LANG
|
none |
limits.max_file, limits.exec_max
|
file size and one-exec cap | 64 MiB, default exec max |
network |
none/egress as before (central's egress list is not enforced by host mode) |
both |
Refused with the host executor: images, limits.cpus/memory/pids/tmpfs/disk, and the
containerd and opensandbox blocks. The file is read at runner start; restart the runner after
an edit. Central takes no egress rules for a host fleet either (fleet create -executor host with
-egress, -image, -images or a resource limit is refused); network is accepted and stored but
nothing in host mode enforces it, so use the VM's firewall.
Where things live for the user dev (all 0700):
| What | Path |
|---|---|
runner key, workspace.yaml
|
~/.config/mirafleet/ |
session records, per-session runtime dir (agent.sock, ca.pem, ssh_config, out/, jobs/, cwd) |
~/.local/state/mirafleet/ |
| session directories |
<host.root>/sessions/<slug>, shared <host.root>/work/<name>
|
runner audit log, including credential.use rows (JSONL, no values) |
audit.jsonl in the runner's -data directory |
HOME for the agent's commands is the user's real home, so tool caches (~/.m2,
~/.cache/go-build) are shared across sessions, as on a laptop.
Give each credential the least power its job needs, because a credential's limits are the limits GitLab gives it; mirafleet adds no path or branch rules.
-
SSH deploy key: create a key pair (
ssh-keygen -t ed25519 -f deploy_key -N ''), add the public key to the project as a deploy key with write access, and give central the private key. Pin the server:ssh-keyscan -t ed25519 gitlab.example.com > gitlab.known_hostsand check the fingerprint against what your GitLab admin publishes;-known-hostsis what stops the agent being talked into signing for a look-alike server. Prefer one deploy key per project. -
Project access token: scope
write_repository(andread_repositoryimplied), role Developer, short expiry. Use-auth basic -user oauth2, or-auth header -header PRIVATE-TOKENfor API calls. -
Registry token: a deploy token or access token with
read_registry/write_registry; kindregistry, with the user name. The broker does the Docker-registry bearer exchange itself. -
-host-binding offonly for OpenSSH older than 8.9 on the VM; it removes the "sign only for a pinned server" check, so use it for that credential only.
-
Replace a value: run
credential setagain with the same name. The version goes up, central pushes the new set to every assigned runner at once, and the next request uses it. No restart. -
Remove access:
credential unassignstops it working on that runner at once;credential deleteremoves it everywhere. -
Expiry warnings start 14 days ahead: status
expiringin the GUI, the runner list, the heartbeat and in tool results that name the credential.expiredstops being useful on its own schedule (GitLab will refuse it). -
Automatic GitLab rotation (opt in):
-rotate gitlab_self -rotate-project mirastack/app -expires DATEon anhttps-token. When fewer than 7 days remain, central calls GitLab'sPOST /projects/:id/access_tokens/self/rotate(the token needs theself_rotatescope), stores the new value in the same transaction as its audit row, and pushes it. That needs central to reach GitLab over HTTPS. If central cannot, rotation is manual; a failed attempt is audited, shows asrotate_errorin the GUI, and the old token keeps working until it expires.mirafleet central credential rotate NAME(or the GUI "Rotate now" button) does it on demand. -
Change the secrets key (
central secrets rekey): stop nothing; with the old key in the environment, pipe the new key line on standard input.mirafleet central keygen > /tmp/newkey.env # keep this file private MIRAFLEET_SECRETS_KEY=<old key> mirafleet central secrets rekey < /tmp/newkey.env # then put the new line in /etc/mirafleet/central.env, restart central, delete /tmp/newkey.env
All credentials are re-encrypted in one transaction; a failure leaves the old key valid. Back up the new key first. Rekey is offline: it takes the data-directory lock, so it fails while central is running. Stop central first, rekey, then start it with the new key.
-
Central cannot start ("wrong key" or "key not set"): the environment variable is missing or does not match the stored key check. Fix the file; do not delete credentials to get past it.
If your GitLab certificate is signed by a private CA, three places need to know it:
-
The VM's system trust store (
update-ca-certificateson Debian/Ubuntu). The broker builds the bundle that tools use from the VM's bundle plus the session CA, so a CA the VM trusts is trusted bygit,curl,pipandnodewithout more work. -
host.corporate_ca_fileinworkspace.yaml: the broker's own upstream connection to GitLab is verified against the system roots plus this file. -
Central (only for automatic rotation):
MIRAFLEET_CORPORATE_CA_FILE=/etc/mirafleet/corp-ca.pemin central's environment.
Java does not read the system bundle: build a truststore with keytool once (the plugin's skill
carries the recipe) and use JAVA_TOOL_OPTIONS.
workspace_close and the idle reaper never delete files. Directories are deleted by:
- the daily sweep, after
delete_after(default 30 days) unused. Tool results warn 3 days before; -
mirafleet runner host prune [-older-than D] [-yes] [-root host.root]as the runner user. Without-yesit only lists what it would delete. Directories in use are skipped; sharedwork/<name>directories are never touched; -
workspace_close {delete: true}(the owner), or on centralmirafleet central workspace kill ID -delete(admin).
One practical consequence: if kalyan uses the runner after durga, durga's directories are still
there and readable by the same Unix user. Prune between operators if that matters to you.
-
Restart the runner (
systemctl --user restart mirafleet-runner): foreground commands in flight end; background jobs and open sessions are re-adopted from their records. If a job's process is gone (VM reboot), it is reportedlost. -
See what the runner holds: the GUI Credentials page (
/credentials) and the runner detail page show names, kinds, hosts and per-runner delivery status. Values are write-only: no page, API or CLI shows one, and the GUI has no file upload (use the CLI to load from a file). -
Audit:
central auditshowscredential.*admin rows (without values), workspace rows, and aggregatedcredential.userows with sourcerunner(per session, credential, host and status in 60-second windows).events.droppedmeans a runner produced more than central accepts. -
A replaced connection: if a second process connects as the same runner, central writes a
runner.replacedaudit row (shown on the GUI audit page; filter by action). See "known gap" below. - Back up the central data directory and the key, separately.
| Symptom | Cause | Fix |
|---|---|---|
| Runner exits at start: "refusing to run as root" or "capabilities" | started as root or with ambient capabilities | run as the ordinary user (User= or a user unit); no AmbientCapabilities=
|
| Runner exits: state dir not private |
~/.local/state/mirafleet or $HOME is group/world-writable |
chmod 700 the directory; fix the home permissions |
workspace_open: conflict: busy: runner NAME is in use by durga
|
another operator has live workspaces there | wait for them to close or be reaped, or use another runner; an admin can workspace kill
|
workspace_open: no runner holds credential gl-token
|
not assigned to a runner of that fleet, or the runner has not synced yet |
credential assign; check delivery status in credential list; the runner must be online |
workspace_open with credentials on a container fleet |
credentials exist only on host fleets | use a host-mode fleet |
| Background job stops when the runner restarts | unit has the default KillMode
|
KillMode=process in the unit (shipped units have it) |
| Runner does not start after reboot (user unit) | linger is off |
loginctl enable-linger dev (as root) |
git clone over SSH: Host key verification failed
|
server key not in the credential's known_hosts
|
re-run credential set with the right -known-hosts
|
git clone over SSH: sign_and_send_pubkey: signing failed
|
host binding on with OpenSSH < 8.9, or the key is not the project's deploy key | update OpenSSH, or -host-binding off for that credential |
git clone over HTTPS: certificate error |
private CA not trusted | section 10.13.6 |
git asks for a username/password |
the host is not in the credential's -hosts, or it is on another port |
-hosts gitlab.example.com:8443 style; hosts must match exactly |
| 401 from a registry | wrong user, or no registry credential for that host |
create a registry kind credential |
Central: wrong key at start |
MIRAFLEET_SECRETS_KEY unset or different |
restore the key from the backup |
credential set says value too large |
secret over the maximum value size | keys and tokens are small; check you piped the right file |
Tool result: output was cut ... read_output
|
the command printed more than the inline budget | page it with read_output {ref} (this is the design, not an error) |
bash timed out |
foreground limit (default 120 s, max 600 s) | use run_in_background and poll with bash_output
|
grep finds nothing in ignored files |
.gitignore is honoured |
search the file directly or use bash with grep -r
|
The runner has its own enrolment key on disk (it must, to reconnect). The agent runs as the same
user, so a determined, prompt-injected agent could read that key, connect to central pretending to
be this runner and ask for the credentials assigned to it. The accepted OSS answer is: do not
assign more than the runner needs, scope every token in GitLab, use a dedicated VM, and watch for
runner.replaced. Everything else in the design (memory-only secrets, non-dumpable runner, agent
and broker) closes the other doors. Root on the VM sees everything. The enterprise answer
(separate users or hardware-held keys) is out of scope.
- A dedicated VM; firewall limits outbound traffic to what the project needs.
- Runner user is not root, home is 0700, linger is on, unit has
KillMode=process. -
/etc/mirafleet/central.envis 0600 and the key is backed up elsewhere. - Every credential is scoped in GitLab to one project with the least rights, has an expiry, and is assigned to the runners that need it (not the whole fleet by habit).
-
known_hostspinned for every SSH key; host binding left on. -
delete_afteris what you want; someone ownsrunner host prune. - You tried a tool-call leak check: in a session,
env,ls ~/.ssh,ssh-add -L,cat /proc/$(pgrep -f 'runner run')/environshow no secret.
- Why
KillMode=processin the runner unit? - durga has a workspace on
vm1-dev; what happens when kalyan opens one there? - You lost
central.env. What is lost, and what does central do at start?
Answers
- Otherwise systemd kills background jobs when the runner restarts.
- It is refused with
conflict: busy: runner NAME is in use by durgaand placement tries other runners. - Every stored credential is unreadable; central refuses to start rather than run without the right key. Restore the key from the backup.
- aarvee runs
mirafleet central fleet listfrom their laptop and getscommand not foundor a socket error. Why can aarvee not administer central from their laptop, and what is the right way? - You edit
/etc/mirafleet/actions.yamlonbuild-1and add an action. durga still getsrefused: unknown action. What did you forget? - A join fails with
unauthenticated: join refused. Name three possible causes, and say why the message does not tell you which one it is. -
central operator codeshowsvalid for: 7s. durga pastes it, but theirmcp logintakes 10 seconds to start. Will it work? Does kalyan need their own code? - Why is a pattern like
.*on a path parameter dangerous even though there is no shell? - A workspace runner refuses to start with
userns: required is not supported on this host. Is settinguserns: offthe fix? What do you give up, and what are the alternatives? - durga's
workspace.openreturnsunavailable: the runner holding this session's workspace is offline. Why does central not simply create a fresh workspace on another runner, and what can aarvee do if the runner is gone for good? - You revoke runner
build-1. Its three workspaces showlost, anddocker ps-style tools still show containers on the host. Why, and what do you run? - A fleet allows image
golang@sha256:*but durga getsrefused by runner: image not allowed on this runner. Where do you look? - Claude Code starts, but
/mcpshowsplugin:mirafleet:mirafleetfailed. What do you check first, and why can the same laptop work from a terminal and fail from a desktop launcher? - durga's agent reports "central's host key does not match the pinned key". aarvee rebuilt central yesterday. What do you do, and why is a plain retry the wrong move?
- A stray line that is not JSON reaches
mirafleet mcpon stdin and the server exits with code 1. Why does it exit instead of skipping the line, and who restarts it? - The new admin GUI is on
0.0.0.0:8443and aarvee wants it reachable only from one laptop. Give two ways, and say why you would still check the certificate fingerprint on the first visit. - aarvee opens the GUI as
https://central.example.com:8443/and gets421 Unknown host name, whilehttps://192.0.2.10:8443/(central's own address) works. What is wrong and why does central care? - aarvee forgot the GUI password. What does aarvee run, where, and what happens to the open browser sessions and to the audit history?
- aarvee upgrades central and the new version cannot start: the log says the pre-migration backup failed. Does the old database survive? What does aarvee check?
- After an upgrade, aarvee rolls back with the newest backup. Name two things that are lost or needed, and one thing to back up apart from the data directory.
- raj upgrades
db-1to a newer release before central. What happens, and what is the right order? - A checksum matches, yet a careful engineer still runs the cosign check. What does the signature add that the checksum cannot?
Answers
- Administration is only possible through the local admin socket on the central host, by the same Unix user that runs central; laptops are operators and can only call the four operator methods. aarvee must log in to the central host (for example over their normal SSH access) and run the command as central's user.
- Restart the runner.
actions.yamlis read once at start (runner run). Also check that the action is in the file of that runner: each runner has its own allowlist. - Any of: the token was already used, expired, revoked, unknown, mistyped, or made by a different central. The message is identical on purpose so that someone probing with guessed tokens cannot learn which ids exist or how close a guess was. The real reason is in central's log.
- No: get a fresh code. The code is checked against the current 60 s window at the moment central receives the request, so by then it has expired. kalyan does not need their own: any number of operators can use one code in its window.
- There is no shell, but the program still interprets the value. With
.*a caller can pass any path (/etc/shadow,../..) or, if the program takes options, a value that changes its behaviour. The guard stops injection into the command line structure; it cannot know what is safe for the program, which is why patterns must be as narrow as the use case allows. - Not as a quick fix.
requiredfails because the kernel (older than 5.19), user-namespace settings or snapshotter cannot give each workspace its own uid range.offruns, but isolation between workspaces then rests on distinct unprivileged host uids alone, so choose it consciously. Better: a newer kernel and containerd 2.x, or a different host. The runner never falls back by itself. - The files live on the offline runner; a fresh workspace elsewhere would silently lose them and
the agent would not know. aarvee can
central workspace kill ID(the row goesclosing, thenclosedorlost), after which durga can open a new workspace, or bring the runner back. - A revoked runner never reconnects, so central cannot ask it to destroy anything and marks the
rows
lost. On that host, as root:mirafleet runner workspace prune -all -yes -data DIR -workspace FILE(it talks to containerd directly). - The runner's own
imageslist inworkspace.yaml: the effective policy is the intersection of the fleet's and the runner's allowlists. Add the pattern there and restart the runner. - The
PATH.which mirafleet(orwhere mirafleet) in the environment that starts Claude Code. A shell has yourPATHfrom its profile files; a desktop launcher, an IDE or a service usually does not, so the same command resolves in one and not in the other. - Compare the fingerprint first: central printed it as the "host key" line of
central operator code. A rebuilt central has a new key, which is the expected cause, but an attacker in the middle looks exactly the same, and mirafleet has no trust-on-first-use, so a retry would fail again by design. When the rebuild is confirmed,mirafleet mcp loginagain with a fresh code replaces the pinned line for that address. - The SDK treats a line that is not valid JSON-RPC as a broken session and closes it; the server returns the decode error and exits 1 without printing the line (a test checks it is never echoed). Skipping bad lines would hide a harness or wrapper that has lost track of the protocol and leave a half-working server behind. The harness that started the server restarts it.
- Bind to loopback with
-gui-listen 127.0.0.1:8443and reach it withssh -L 8443:127.0.0.1:8443 aarvee@central.example.com; or turn it off with-gui-listen off; or leave the bind and add a firewall rule for port 8443. The self-signed certificate gives the browser nothing to check on the first visit, so only the fingerprint in central's log shows that aarvee is talking to central and not to something on the network that answered first. - The name is not on the Host allowlist; IP addresses of the machine are, names are only
accepted when listed. Restart central with
-gui-host central.example.com. Central cares because of DNS rebinding: a web page can make a browser send requests to central's address under the attacker's own host name, and refusing every unknown name stops that. - On the central host, as central's user,
mirafleet central gui reset-admin. It prints a new setup token (valid 24 h). Every GUI session ends at once, the setup page reopens, and aarvee chooses a username and password again. The audit history stays, with agui.reset_adminrow. - Yes: the backup runs before any schema change and a failed backup means no migration, so the
database is untouched. aarvee checks free disk space and that
backups/inside the data directory is owned bymirafleetand writable, then restarts central. - Writes since the upgrade are lost (new runners, tokens, audit rows), and the restore needs the
same
MIRAFLEET_SECRETS_KEYbecause backups hold credentials as encrypted as the database. The key is what to back up apart from the data (and copybackups/off the machine too). - Central (still at the old level) sees a runner one level ahead and refuses it with "central
is protocol N, runner
db-1is N+1: upgrade central first";db-1stays offline until central is upgraded. Order: central, then runners, then operators. - A checksum only says the file matches a list; whoever can replace the file can replace the list.
The signature ties
checksums.txtto this repository's release workflow identity, so the list itself can be trusted.
- mirafleet quickstart
- The mirafleet developer guide
- Glossary
- 1. What is mirafleet?
- 2. Background: the ideas mirafleet builds on
- 3. Architecture
- 4. Flows
- 5. Security
- 6. Data model
- 7. Protocols
- 8. Code tour
- 9. Dev setup and testing
- 10. Operations
- 11. Contributing
- 12. Why mirafleet? A comparison with the alternatives
Generated from docs/ at cded12f; edit there.