Repository navigation
07 Protocols
Generated from
docs/at 03a5594. Edit the source in the repository, not this page.
- The M7 additions: the 24 MCP tools (the fifteen Claude Code parity tools), background jobs, the
Refoutput paging, and the admin-only credential methods (section 7.14). - Which SSH users and channels exist, and who may open what.
- The exact bytes of a message: the 4-byte length prefix, the JSON envelope, and a hex example.
- Every method with a real request and response: operator methods, admin methods on the local socket, and the two enrol methods.
- The error codes, the limits (with constant names and values), and the formats of join tokens and registration codes, field by field.
- What flows between central and a runner (
heartbeat@mirafleet,exec@mirafleet,workspace@mirafleet) and the rules for changing the protocol. - The M3 additions: the six workspace operator methods and the admin workspace methods with real JSON, the body frame (a second length-prefixed frame carrying file or stdin bytes), the new heartbeat fields, limits and errors.
- The M5 additions: the MCP layer on top (JSON-RPC over stdin and stdout: the nine tools,
their arguments, the result and error shapes, the caps and the chunking), plus the three small
wire changes underneath:
runners.listgainsactionsandactions_omitted,workspace.closegainsstate, and the heartbeat gainsactions(section 7.13). - The M4 additions: two new admin methods (
gui.reset_admin,fleet.set_confirm), the filters ofaudit.list(section 7.6), and the one place where mirafleet speaks HTTP instead of SSH: the admin GUI's routes table (section 7.14). - The M6 additions: the protocol level and the version-skew rule (central accepts N and N-1, upgrade central first), the exact refusal texts, and what is wired and what is not (section 7.15).
Unfamiliar terms (SSH channel, global request, framing, envelope) are in the
glossary. The code is internal/api (framing, envelope, DTOs, limits),
internal/transport (names shared by central and runner), internal/tokens (token formats),
internal/central (server side) and internal/apiclient (client side).
All examples use the running example: central at central.example.com:2222, fleets dev and
prod, runners build-1 (in dev) and db-1 (in prod), operators durga and kalyan, and
aarvee, the admin who uses the local admin socket. Tokens and codes are obviously fake (the secret
and host-key-hash placeholders are exactly 43 characters long, like the real ones). Timestamps
are made up. Everything here is implemented and released (v0.6.1), except where
a paragraph says "planned". Workspace ids are 32 lowercase hex characters; the examples use
3f9a6c1e5b7d4820a1c3e5f708192a4b.
mirafleet invents no network protocol of its own. Everything rides on SSH (implemented
in-process with golang.org/x/crypto/ssh). SSH gives us encryption, server authentication
(the host key) and client authentication (public keys). On top of one SSH connection, you can open many
independent channels (think: lightweight sub-connections, each with a type name). Peers can
also send global requests (one-off messages on the connection itself, not tied to any
channel, optionally answered). Opening a channel can also carry extra data: a small blob of
bytes sent inside the channel-open message itself, before any channel traffic.
mirafleet uses three kinds of things on top of SSH:
| Mechanism | Used for | Message format |
|---|---|---|
Channel api@mirafleet, join@mirafleet, register@mirafleet (peer to central) |
Operator API, enrolment | 4-byte length prefix + JSON, one request, one response (section 7.3) |
Global request heartbeat@mirafleet (runner to central) |
"I am alive, here is what I am" | SSH request payload: JSON, answered with ok/not ok |
Channel exec@mirafleet (central to runner, over the runner's own connection) |
Run one action | Open data: JSON; reply: one JSON document then EOF (section 7.10) |
Channel workspace@mirafleet (central to runner, same connection) |
One workspace operation: create, exec, read, write, destroy, list | Open data: JSON; optional raw body; reply: one length-prefixed JSON frame, then raw bytes for a read (section 7.10) |
Names are defined once, in internal/transport/transport.go, so central and runner cannot
disagree.
There is one exception to "SSH carries everything": the admin GUI (M4). It is an HTTPS listener
inside the central process (default 0.0.0.0:8443, section 7.14) for a human administrator's
browser. It is not a way in for operators or runners, and it carries no protocol of its own:
every request is turned into a call of the same service methods that the admin socket uses.
The SSH user name selects the role. The key is looked up only in that role's table
(chapter 5). Authentication is public key only,
ssh-ed25519 only, with at most 3 tries (MaxAuthTries). Any other user name is refused.
| SSH user | Key must be | May open (peer to central) | May send | Central may open toward it |
|---|---|---|---|---|
runner |
an enrolled, non-revoked runner key | nothing: every channel is rejected |
heartbeat@mirafleet global requests |
exec@mirafleet (actions runners), workspace@mirafleet (workspace runners) |
operator |
an active operator key |
api@mirafleet, at most 8 at once
|
nothing honoured (global requests are discarded) | nothing |
enroll |
any Ed25519 key | exactly one of join@mirafleet or register@mirafleet, then the connection closes |
nothing honoured | nothing |
| (anything else) | n/a | n/a | n/a | n/a (authentication fails) |
Notes you will need when debugging:
- A channel type that is not in the role's allow-list is rejected with SSH reason
UnknownChannelType("channel type not allowed"). An allowed channel over the cap is rejected withResourceShortage("too many concurrent channels"). A runner's channels all getUnknownChannelType. - On an
enrollconnection only the first channel counts. A second one getsProhibited. If the first has a disallowed type, the connection is closed. - An
enrollconnection lives at mostConfig.EnrollDeadline(30 s) from accept, and is rate limited (10/min per source, 60/min overall) after the handshake. This is why anyone who can reach the port can complete a handshake asenroll: they can then do nothing except present a token or code. - The runner never listens. A runner started with
-actionshandles onlyexec@mirafleet; one started with-workspacehandles onlyworkspace@mirafleet. The SSH library rejects every other channel type toward the runner, and a runner refuses the channel type it has no config for (Prohibited). - There is no
file@mirafleetchannel. File reads and writes go overworkspace@mirafleet(same handler, same trust, half the plumbing). - The admin socket is a unix socket, not SSH. It speaks the same framing and envelope as
api@mirafleet(section 7.5).
A frame is one message on a channel. A reader of raw JSON would have to parse it to find where it ends, so it could not check the size before parsing (and a hostile sender could keep sending). So every message is wrapped in a length prefix: the size comes first.
Look at: every message is 4 length bytes followed by exactly that many JSON bytes.
- The operator builds the JSON request: 33 bytes. Hex above, letters below each byte.
- It puts the payload length first, as 4 bytes, big-endian: 33 = 0x00000021.
- Header and payload go out in one Write on the channel.
- Central reads 4 bytes, checks the length against its limit BEFORE allocating, reads that many.
- Central runs the method and builds the JSON response (a small example: 28 bytes).
- The response is framed the same way: 28 = 0x0000001C. The operator reads it back.
-
write_fileandexecwith stdin add a body frame right behind the request: a 4-byte length, then raw bytes (here 5 bytes,hello), at most 1 MiB. Not JSON. - Central reads the body frame only after policy, ownership and confirm pass, within 30 s.
- The client opens a channel of type
api@mirafleet(or the enrol types). - The client writes 4 bytes: the payload length
Nas an unsigned big-endian integer. - The client writes the N bytes of JSON. (Header and payload leave in one write.)
- Central reads the 4 bytes, checks
Nagainst the limit first, and only then allocates and reads N bytes. A hostile prefix of 4 GiB costs nothing. - Central writes one response frame of the same shape and closes the channel.
byte 0 byte 1 byte 2 byte 3 bytes 4 .. 4+N-1
+-----------+-----------+-----------+-----------+---------------------------+
| N >> 24 | N >> 16 | N >> 8 | N & 0xff | N bytes of UTF-8 JSON |
+-----------+-----------+-----------+-----------+---------------------------+
most significant byte first ("big-endian", also called network byte order)
Rules (internal/api/frame.go, ReadFrame / WriteFrame):
| Situation | Result |
|---|---|
N == 0 |
ErrEmptyFrame: the peer gets bad_request "empty request". Empty frames are also refused when writing. |
N over the limit (request: 64 KiB) |
ErrFrameTooLarge, nothing more is read; the peer gets too_large. |
| Stream ends before the 4 header bytes are complete, or before N payload bytes |
io.ErrUnexpectedEOF; the peer gets bad_request "truncated request". |
| Clean end of stream before any byte |
io.EOF: the peer simply closed; no reply is written. |
Response bigger than MaxResponseBytes
|
Replaced by a too_large error response so the caller still gets an answer. |
The numbers below are the same as in the picture. Durga's client sends hello. The JSON is:
{"v":1,"id":"1","method":"hello"}
Count the characters: that is 33 bytes (all ASCII, one byte per character). 33 is 0x21, so the
length prefix is 00 00 00 21. The whole frame is 4 + 33 = 37 bytes, shown here as hex
(left) and as text (right, . for unprintable bytes):
offset hex text
0000 00 00 00 21 7B 22 76 22 3A 31 2C 22 69 64 22 3A ...!{"v":1,"id":
0010 22 31 22 2C 22 6D 65 74 68 6F 64 22 3A 22 68 65 "1","method":"he
0020 6C 6C 6F 22 7D llo"}
Central's reply here is {"v":1,"id":"1","result":{}}. That is 28 bytes, 0x1C, so the
frame starts 00 00 00 1C and is 32 bytes long:
offset hex text
0000 00 00 00 1C 7B 22 76 22 3A 31 2C 22 69 64 22 3A ....{"v":1,"id":
0010 22 31 22 2C 22 72 65 73 75 6C 74 22 3A 7B 7D 7D "1","result":{}}
(A real hello reply carries the operator name and versions; it is shown in section 7.5. This one
is kept tiny so you can count it.) Notice that the id is echoed back; the client checks it
matches (apiclient.callOn).
Why a length prefix and not one JSON object per line (NDJSON)? It lets a receiver reject a big message by looking at 4 bytes, and the payload may contain any bytes including raw newlines. (Newline-delimited JSON was considered and rejected for this reason.)
Files and stdin are bytes, not JSON. Base64 inside JSON would force a bigger request limit on every method (or tiny 48 KiB chunks), so M3 added a second kind of frame, the body frame, sent on the same channel right behind the request frame. The picture above shows it in steps 7 and 8.
request frame body frame (only some methods)
+----------+------------------------+ +----------+---------------------------+
| 4 bytes | N bytes of JSON (<=64K)| then | 4 bytes | M raw bytes (<= 1 MiB) |
| N | {"method":"workspace. | | M | not JSON, any bytes at all|
+----------+ write_file", ...} | +----------+---------------------------+
Same 4-byte big-endian length, same "check before you allocate". The differences:
Request frame (ReadFrame) |
Body frame (ReadBodyTimeout) |
|
|---|---|---|
| Limit |
api.MaxRequestBytes 64 KiB |
api.MaxFileChunk 1 MiB |
| Zero length | refused (ErrEmptyFrame) |
valid: an empty file or empty stdin |
| Content | one JSON envelope | raw bytes |
| Deadline |
api.RequestTimeout 10 s |
api.BodyTimeout 30 s, armed when central asks for it |
| Writer | api.WriteFrame |
api.WriteBody |
Which methods carry bodies:
-
workspace.write_file: a request body of exactlylengthbytes whose SHA-256 must equalsha256(a mismatch isbad_request, audited, and nothing reaches the runner). -
workspace.execwith"stdin": true: a request body (the stdin bytes, at most 1 MiB). -
workspace.read_file: the response has a body. The JSON result frame comes first (lengthsays how many bytes follow), then one body frame.
The client writes the body frame immediately after the request: SSH's channel window (2 MiB) is
bigger than the biggest body, so that write never blocks. Central, however, reads it late on
purpose: the handlers wrap the body in a lazy reader (lazyStdin, lazyFileBody in
internal/central/workspace_handlers.go) and the service only touches it after policy, ownership,
workspace state, input checks and confirm have passed. Why: if central read the body first, any
authenticated but unauthorised caller could make it buffer 1 MiB per channel, 8 channels per
connection, before being refused. With the late read, a refused caller costs a 64 KiB frame.
A slow sender is cut off after 30 s (timeout; the channel is closed), a body over the stated
size is too_large, a short one is bad_request "truncated body".
Byte example, the body of a write_file of the five bytes hello:
offset hex text
0000 00 00 00 05 68 65 6C 6C 6F ....hello
Every request and response is a JSON object with the same outer shape, the envelope
(api.Request, api.Response).
Request
{"v": 1, "id": "a1b2c3d4e5f60718", "method": "runners.list", "params": {"fleet": "prod"}}| Field | Type | Rules |
|---|---|---|
v |
integer | Protocol version. Must be 1 today. Checked first. |
id |
string | 1 to 128 bytes. Chosen by the client (the Go client uses 16 hex chars from 8 random bytes). Echoed in the reply. |
method |
string | Non-empty. Names in sections 7.5 to 7.7. |
params |
object | Optional. Missing, empty or null means "no params". |
The server decodes with DisallowUnknownFields: any field not listed above, in the envelope or
in the params of a method, is bad_request. Trailing data after the JSON object (including a stray
}) is also bad_request. Strict parsing is cheap protection against typos and smuggling.
Response: exactly one of result and error
{"v": 1, "id": "a1b2c3d4e5f60718", "result": { ... }}
{"v": 1, "id": "a1b2c3d4e5f60718", "error": {"code": "not_found", "message": "not found"}}Response.Marshal refuses to build a message with both or neither. When the request was too broken
to read an id, PeekID tries to recover one for the reply; otherwise id is empty.
One request per channel. The client opens a channel, sends one request, reads one response, closes. Cancel is closing the channel. Concurrency is opening more channels (up to 8 per connection). We rejected a multiplexed JSON-RPC stream on one channel because it needs request-ids, ordering rules and flow control, all of which SSH channels already provide.
A half-close (the client finishes writing but keeps reading) is not a cancel: the request still runs and the reply is still written. Closing the channel or dropping the connection is.
Reachable by operators on api@mirafleet, and by the admin on the admin socket (except hello).
Every call goes through the service: policy (the operator must be active now, so every
operator method passes that current-status check), validation, audit. The method table and the
policy are two independent gates; admin-only calls add a direct check of the caller's kind as a
third.
Identify yourself and learn the protocol versions. Like every operator method it passes the
policy's current-status check; hello just does one extra lookup in its handler
(handleHello in internal/central/dispatch.go): it re-reads the operator row and answers
forbidden if that operator is no longer active.
Request:
{"v":1,"id":"a1b2c3d4e5f60718","method":"hello","params":{"client":"mcp"}}Response:
{"v":1,"id":"a1b2c3d4e5f60718","result":{"operator":"durga","versions":[1],"server":"mirafleet"}}client is an optional hint of at most 32 printable ASCII characters. It is logged, not
trusted (a longer or non-printable hint is silently dropped).
No params. Returns every fleet with its count of non-revoked runners.
{"v":1,"id":"b7e4","method":"fleets.list"}
{"v":1,"id":"b7e4","result":{"fleets":[
{"name":"dev","mode":"actions","confirm":false,"runners":1},
{"name":"prod","mode":"actions","confirm":true,"runners":1}]}}(Responses are one line on the wire; line breaks added here.) confirm: true means a guarded fleet.
Params: fleet (required). Lists non-revoked runners of that fleet, merged with live state:
online is true only for a registered session that heartbeated recently; last_seen is the later
of the stored time and the live heartbeat. labels come from the join token.
{"v":1,"id":"c1d2","method":"runners.list","params":{"fleet":"prod"}}
{"v":1,"id":"c1d2","result":{"runners":[
{"name":"db-1","status":"active","online":true,"labels":{"role":"db"},
"last_seen":"2026-11-13T09:41:07.512Z"}]}}last_seen is an RFC 3339 UTC timestamp and is omitted if the runner was never seen.
Action discovery (M5). An actions-mode runner now tells central which actions it offers, and
runners.list passes that on, so an agent can see that db-1 has tail-logs and which values its
parameters accept instead of guessing names:
{"v":1,"id":"c1d3","result":{"runners":[
{"name":"db-1","status":"active","online":true,"labels":{"role":"db"},
"last_seen":"2026-11-13T09:41:07.512Z",
"actions":[{"name":"tail-logs","params":[{"name":"lines","pattern":"^[0-9]{1,4}$","default":"200"}]}]}]}}Each action has a name and params; each param has name, pattern (the regular expression the
runner's guard will apply) and default (absent when the parameter is required). This is
informational only: the runner's actions.yaml stays the security boundary, and the guard
still checks every value (chapter 5). A made-up list on the wire would change
what the agent tries, never what the runner runs.
Size is bounded twice. A runner may advertise at most 128 actions (transport.MaxHeartbeatActions)
and at most 16 KiB of encoded actions (transport.MaxActionsBytes). Central adds the actions of
the runners in one reply only until 512 KiB (maxListActionsBytes in internal/central/dispatch.go)
are used; every later runner is listed without actions and with "actions_omitted":true, so
a fleet with many busy runners can never push runners.list over api.MaxResponseBytes. M2 and M3
runners send no actions, and then both fields are absent.
Run a named action on one runner.
| Param | Type | Rules |
|---|---|---|
fleet, runner
|
string | Must form a valid fleet/runner reference. |
action |
string | 1 to 64 bytes. Checked by the runner's actions.yaml, not by central. |
params |
object of strings | At most 32 entries, key 1 to 64 bytes, value up to 4096 bytes. |
timeout_s |
integer |
0 = default (120 s); negative is bad_request; capped at 600 s. |
confirm |
string | On a guarded fleet, must equal the fleet name. |
Central checks, in order: policy, input limits, fleet exists and is in actions mode, confirm,
runner is active; then writes the audit start row; then asks the runner.
Request:
{"v":1,"id":"d3f9","method":"action.run","params":{
"fleet":"prod","runner":"db-1","action":"tail-logs",
"params":{"lines":"200"},"timeout_s":30,"confirm":"prod"}}Success:
{"v":1,"id":"d3f9","result":{"exit_code":0,"stdout":"Nov 13 09:41:03 db-1 gitlab-runner[812]: ...\n",
"stderr":"","duration_ms":41,"request_id":"9f1c0a5be2d84c7790a1b3c4d5e6e07a"}}truncated: true appears when output hit the 1 MiB cap. A command that ran and failed is still
a success response with a non-zero exit_code: the protocol worked, the action did not.
Failures (all with the same envelope):
| Situation | Response error
|
|---|---|
Guarded fleet, confirm missing |
{"code":"bad_request","message":"fleet requires confirm to equal the fleet name"} |
| Runner's guard refused (unknown action, bad param) | {"code":"bad_request","message":"refused by runner: refused: parameter \"lines\" does not match its pattern"} |
Runner is pending or disabled
|
{"code":"conflict","message":"runner is pending"} |
Fleet is not in actions mode |
{"code":"conflict","message":"fleet is not in actions mode"} |
| Runner offline, or something broke talking to it | {"code":"unavailable","message":"runner unavailable"} |
| Runner revoked mid-run | {"code":"unavailable","message":"runner revoked"} |
| Audit table not writable | {"code":"unavailable","message":"audit unavailable"} |
Ran past timeout_s
|
{"code":"timeout","message":"action timed out"} |
| Operator revoked, or channel closed mid-run |
{"code":"unavailable","message":"request cancelled"} (usually unseen: the connection is gone) |
If the runner itself reports that the action timed out (the action's own timeout in
actions.yaml), the response is a normal result with exit_code: -1, and the audit outcome is timeout.
Six more operator methods drive workspaces. They exist only on api@mirafleet (the admin socket
does not serve them: aarvee manages workspaces with the admin methods in section 7.6; the admin never
runs commands in them). All six go through the same policy check as every other method, plus a
direct check that the caller is an operator. They only work on a fleet in workspace mode;
action.run on such a fleet, and workspace.* on an actions fleet, answer conflict.
Ownership is the main rule: every call that names a workspace loads the row and requires that
the caller is its owner. Anyone else, and any unknown or malformed id, gets the same
not_found. kalyan cannot even learn that durga's workspace exists.
The running example: durga's agent works in fleet dev, session s1 (see the
M3 flow diagrams: workspace-open.svg and workspace-exec.svg).
| Param | Type | Rules |
|---|---|---|
fleet |
string | A valid fleet name, in workspace mode. |
session |
string | 1 to 128 characters of A-Za-z0-9._:-. Chosen by the client; it is the stickiness key. |
image |
string | Optional. Must match the fleet's image allowlist; default is the fleet's default_image. |
labels |
object of strings | Optional. Must be a subset of the runner's trusted token labels. At most 16; names starting with mirafleet. are reserved. |
confirm |
string | On a guarded fleet, must equal the fleet name. |
{"v":1,"id":"w1","method":"workspace.open","params":{"fleet":"dev","session":"s1","labels":{"zone":"a"}}}
{"v":1,"id":"w1","result":{"workspace":{"id":"3f9a6c1e5b7d4820a1c3e5f708192a4b","fleet":"dev",
"runner":"build-1","session":"s1",
"image":"docker.io/library/golang@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"state":"open","created":"2026-11-13T09:41:07.512Z","last_used":"2026-11-13T09:41:07.512Z",
"expires":"2026-11-20T09:41:07.512Z"},"reused":false}}Open is idempotent per (operator, fleet, session): a second open with the same session
returns the same workspace with "reused":true and creates nothing (a unique partial index in
the database guarantees one live workspace per triple). Two situations are errors instead:
the session's runner is offline (unavailable, "the runner holding this session's workspace is
offline": the files live on that runner, so a fresh workspace elsewhere would silently lose
them), and the first open is still being created (conflict, "workspace is still opening").
Placement is described in chapter 4; the result of a successful open is an open
row, expires is created plus the fleet's max_ttl.
Failures: bad_request (invalid session, image not allowed by the fleet, missing confirm, label
errors, "refused by runner: ..." when the runner's own workspace.yaml says no), conflict
(fleet not in workspace mode, per-operator cap reached: "workspace limit reached (8)"),
unavailable ("no runner can take this workspace right now", "runner busy"), timeout
(creation, including an image pull, took more than 5 minutes).
| Param | Type | Rules |
|---|---|---|
workspace |
string | An id you own, in state open (else conflict, "workspace is closing"). |
argv |
array of strings | 1 to 256 elements, 32 KiB in total, no NUL, argv[0] set. No shell string: to use a shell, send ["/bin/sh","-c","..."]. |
cwd |
string | Optional. Relative to /workspace or absolute under it. Cleaned; a .. that escapes is refused. |
env |
object | Optional. At most 32 variables, names ^[A-Z_][A-Z0-9_]{0,63}$, values up to 4 KiB. Must pass the runner's env_allow and never match the hard denylist: names that look like credentials (ANTHROPIC_API_KEY, *_TOKEN, *_PASSWORD, AWS_*, ...), proxy settings, and variables that change what code a process loads (LD_*, NODE_OPTIONS, PYTHONPATH, GIT_CONFIG_*, ...). The list grows over time, so this guide does not copy it; the source of truth is workspace.EnvDenied in internal/workspace/validate.go. |
timeout_s |
integer |
0 = the fleet's exec_default_s (120); capped at the fleet's exec_max_s (default 1800, ceiling 86400) and again by the runner's limits.exec_max. |
stdin |
boolean |
true means a body frame (at most 1 MiB) follows the request. |
confirm |
string | Guarded fleets: the fleet name. |
{"v":1,"id":"w2","method":"workspace.exec","params":{"workspace":"3f9a6c1e5b7d4820a1c3e5f708192a4b",
"argv":["go","test","./..."],"cwd":"src","env":{"CI":"1"},"timeout_s":300}}
{"v":1,"id":"w2","result":{"exit_code":0,"stdout":"ok \texample.com/app\t0.412s\n","stderr":"",
"duration_ms":1873,"request_id":"c0ffee11d00d4b2a9a3e5f6071829304"}}As with action.run, a command that ran and failed is still a success response with a non-zero
exit_code. truncated: true means the output hit the budget: the runner keeps a head and a
tail of each stream and trims them so the JSON-encoded stdout plus stderr fit in 1 MiB
(api.MaxResultBytes); invalid UTF-8 is replaced, so binary output can never turn into
too_large. timed_out: true means the runner killed the command at its deadline (the audit
outcome is timeout). There is no streaming: the reply is one frame when the command ends.
An env value that is on the denylist is refused naming the variable, never its value:
{"v":1,"id":"w3","method":"workspace.exec","params":{"workspace":"3f9a6c1e5b7d4820a1c3e5f708192a4b",
"argv":["env"],"env":{"ANTHROPIC_API_KEY":"x"}}}
{"v":1,"id":"w3","error":{"code":"bad_request","message":"env ANTHROPIC_API_KEY is denied"}}The shape is the point: bad_request, the variable name, never the value. A name that is merely
not on the runner's env_allow list is refused by the runner instead (refused by runner: env X is not allowed).
Params: workspace, path (a file under /workspace, not the root itself), offset (default 0),
limit (bytes, default and maximum 1 MiB). The result is followed by one body frame holding
length bytes.
{"v":1,"id":"w4","method":"workspace.read_file","params":{"workspace":"3f9a6c1e5b7d4820a1c3e5f708192a4b",
"path":"src/main.go","offset":0,"limit":65536}}
{"v":1,"id":"w4","result":{"size":1342,"offset":0,"length":1342,"mode":420,"eof":true}}
<body frame: 00 00 05 3E, then 1342 bytes>mode is the permission bits as a number (420 is octal 0644). For a file bigger than one chunk,
call again with offset set to what you have so far until eof is true. read_file works on
regular files only: a directory, a FIFO or a symlink that points out of /workspace is refused.
| Param | Type | Rules |
|---|---|---|
workspace, path
|
string | As above. |
offset |
integer | Where to write, default 0. |
truncate |
boolean |
true replaces the file (written to a temp file, then renamed). |
mode |
integer | Permission bits for a new file, 0 means 0644; only 0777 bits are allowed (no setuid). |
length |
integer | 0 to 1 MiB: exactly the size of the body frame. |
sha256 |
string | 64 lowercase hex characters: the SHA-256 of the body. |
confirm |
string | Guarded fleets: the fleet name. |
{"v":1,"id":"w5","method":"workspace.write_file","params":{"workspace":"3f9a6c1e5b7d4820a1c3e5f708192a4b",
"path":"notes.txt","truncate":true,"mode":420,"length":5,
"sha256":"2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"}}
<body frame: 00 00 00 05 68 65 6C 6C 6F>
{"v":1,"id":"w5","result":{"size":5}}Why the hash: the body frame already arrives intact over SSH, but the hash lets the audit row say
exactly which bytes were written without storing them, and catches a client bug (wrong body for
the request) before anything reaches the runner. A file bigger than the chunk limit is written in
pieces: the first with truncate:true, the next ones with offset set. The runner also enforces
its own limits.max_file (set in workspace.yaml, see chapter 10) and refuses a write when the workspace is
over its disk quota (too_large/quota surfaces as bad_request, "refused by runner: ...").
{"v":1,"id":"w6","method":"workspace.close","params":{"workspace":"3f9a6c1e5b7d4820a1c3e5f708192a4b"}}
{"v":1,"id":"w6","result":{}}The row goes open to closing, the runner destroys the container and its directory, the row
becomes closed. If the runner is offline (or the destroy fails), the call still succeeds, but
the row stays closing (it keeps its slot) until the reaper or the reconcile pass finishes the
job, and the result says so with a state field (M5):
{"v":1,"id":"w6","result":{"state":"closing"}}state is absent ({}) when the workspace is closed, and "closing" when it is not yet. Before
M5 both cases looked the same, so a caller could believe a slot was free when it was not. The code
is api.WorkspaceCloseResult and internal/central/workspace_handlers.go. Closing an already
finished workspace is a no-op.
Params: fleet (optional). Returns your own live workspaces (opening, open, closing),
never anyone else's. This call is audited too (one row), unlike fleets.list and runners.list.
{"v":1,"id":"w7","method":"workspace.list","params":{"fleet":"dev"}}
{"v":1,"id":"w7","result":{"workspaces":[{"id":"3f9a6c1e5b7d4820a1c3e5f708192a4b","fleet":"dev",
"runner":"build-1","session":"s1","image":"docker.io/library/golang@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"state":"open","created":"2026-11-13T09:41:07.512Z","last_used":"2026-11-13T09:44:50.101Z",
"expires":"2026-11-20T09:41:07.512Z"}]}}M3 added fields without a version bump (section 7.12): fleets.list shows
"workspace":{"default_image":...,"images":[...],"network":"egress"} on workspace fleets, and
runners.list shows "slots", "free_slots" and "executor" on workspace runners:
{"v":1,"id":"c3","result":{"runners":[{"name":"build-1","status":"active","online":true,
"labels":{"zone":"a"},"last_seen":"2026-11-13T09:44:52.512Z","slots":4,"free_slots":3,"executor":"containerd"}]}}free_slots is slots minus the live workspaces the store knows about.
An admin method on the operator channel:
{"v":1,"id":"e5a1","method":"runner.lifecycle","params":{"fleet":"prod","runner":"db-1","op":"revoke"}}
{"v":1,"id":"e5a1","error":{"code":"forbidden","message":"forbidden"}}A made-up method gives bad_request "unknown method". A future protocol version:
{"v":2,"id":"f0f0","method":"hello"}
{"v":1,"id":"f0f0","error":{"code":"unsupported_version",
"message":"unsupported protocol version 2; supported: [1]","supported":[1]}}The admin socket is <data>/admin.sock (default /var/lib/mirafleet/central/admin.sock), mode
0600. Each connection carries one request frame and one response frame, same framing and same
limits. The peer's uid must equal central's, checked before anything is read. The caller is
principal admin (name uid:<n>), audit source cli. The mirafleet central ... commands are
clients of this socket (internal/central/adminclient.go).
Served here: the admin methods below, plus fleets.list, runners.list and action.run (so
central exec works). hello and the enrol methods are not served (answer: forbidden).
Admin methods are never served on api@mirafleet. The admin disconnecting (for example Ctrl-C of central exec) cancels the request on Linux; on macOS it does not (central only runs on Linux).
All times are RFC 3339 UTC.
| Method | Params | Result |
|---|---|---|
fleet.create |
name, mode (actions default or workspace), confirm (bool), workspace (config object; required-or-defaulted for workspace mode, rejected otherwise) |
{"fleet":{name,mode,confirm,runners,workspace?}} |
fleet.workspace_set |
fleet, workspace (the complete config: a full replace) |
{"fleet":{...}} |
workspace.admin_list |
fleet (optional) |
{"workspaces":[...]} all operators, with the operator field |
workspace.kill |
id |
{"state":"closed"} or {"state":"closing"}
|
token.create |
fleet, labels, approve, uses (0 = 1), ttl_s (0 = 86400; max 2592000) |
{id, token, expires}, token shown once |
token.list |
fleet (empty = all) |
{"tokens":[{id,fleet,labels,approve,max_uses,uses,expires,revoked}]} |
token.revoke |
id |
{} |
runner.lifecycle |
fleet, runner, op (approve, disable, enable, revoke) |
the runner: {name,status,online,labels,last_seen}
|
operator.code |
none | {code, seconds_left, host_fingerprint} |
operator.rotate_secret |
none | {} |
operator.list |
none |
{"operators":[{name,fingerprint,status,last_seen}]} including revoked |
operator.revoke |
name |
{} |
fleet.set_confirm (M4) |
fleet, confirm (bool) |
{"fleet":{...}}: the guard flag changed; audited as fleet.set_confirm with the old and new value |
gui.reset_admin (M4) |
none |
{"setup_token":"mfs1...."}: ends every GUI session, retires the admin, shown once |
audit.list |
since_id, limit (0 = 100, max 1000), and since M4 optional filters (below) |
{"events":[...]} ascending by id |
Examples (one line on the wire):
{"v":1,"id":"1","method":"fleet.create","params":{"name":"prod","mode":"actions","confirm":true}}
{"v":1,"id":"1","result":{"fleet":{"name":"prod","mode":"actions","confirm":true,"runners":0}}}Workspace fleets (M3). fleet.create with mode: workspace carries the fleet's workspace config.
Omitted fields get documented defaults (executor containerd, pull if-not-present, network
none, 2 CPUs, 4 GiB, 1024 pids, 512 MiB tmpfs, 10 GiB disk, idle TTL 24 h, max TTL 168 h,
exec timeout 2 min, exec max 30 min); the default image is never invented and is required. Units
in the wire config: cpu_milli thousandths of a CPU, *_mb mebibytes, *_s seconds.
{"v":1,"id":"11","method":"fleet.create","params":{"name":"dev","mode":"workspace","workspace":{
"executor":"containerd",
"default_image":"docker.io/library/golang@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"images":["docker.io/library/golang@sha256:*"],"network":"egress",
"egress":["proxy.golang.org:443","*.golang.org:443"]}}}
{"v":1,"id":"11","result":{"fleet":{"name":"dev","mode":"workspace","confirm":false,"runners":0,
"workspace":{"default_image":"docker.io/library/golang@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"images":["docker.io/library/golang@sha256:*"],"network":"egress",
"config":{"executor":"containerd","default_image":"docker.io/library/golang@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"images":["docker.io/library/golang@sha256:*"],"pull":"if-not-present","network":"egress",
"egress":["proxy.golang.org:443","*.golang.org:443"],"cpu_milli":2000,"memory_mb":4096,"pids":1024,
"tmpfs_mb":512,"disk_mb":10240,"idle_ttl_s":86400,"max_ttl_s":604800,"exec_default_s":120,"exec_max_s":1800}}}}}The config object (the full config) appears only on the admin socket; an operator's
fleets.list sees default_image, images and network and nothing more. fleet.workspace_set
is a full replace: the CLI first reads the current config, changes the flags you gave and
sends everything back, so a list such as egress can be cleared (send []) and nothing is
merged on the server. Workspaces that already exist keep the spec they were opened with.
{"v":1,"id":"12","method":"fleet.workspace_set","params":{"fleet":"dev","workspace":{
"executor":"containerd","default_image":"docker.io/library/golang@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"images":["docker.io/library/golang@sha256:*"],"pull":"if-not-present","network":"none",
"cpu_milli":2000,"memory_mb":4096,"pids":1024,"tmpfs_mb":512,"disk_mb":10240,
"idle_ttl_s":43200,"max_ttl_s":604800,"exec_default_s":120,"exec_max_s":1800}}}
{"v":1,"id":"12","result":{"fleet":{"name":"dev","mode":"workspace","confirm":false,"runners":1,
"workspace":{"default_image":"docker.io/library/golang@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"images":["docker.io/library/golang@sha256:*"],"network":"none","config":{"...":"as above"}}}}}("config":{"...":"as above"} abbreviates the same object; the real reply spells it out.)
{"v":1,"id":"13","method":"workspace.admin_list","params":{"fleet":"dev"}}
{"v":1,"id":"13","result":{"workspaces":[{"id":"3f9a6c1e5b7d4820a1c3e5f708192a4b","fleet":"dev",
"runner":"build-1","session":"s1","image":"docker.io/library/golang@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"state":"open","operator":"durga","created":"2026-11-13T09:41:07.512Z",
"last_used":"2026-11-13T09:44:50.101Z","expires":"2026-11-20T09:41:07.512Z"}]}}
{"v":1,"id":"14","method":"workspace.kill","params":{"id":"3f9a6c1e5b7d4820a1c3e5f708192a4b"}}
{"v":1,"id":"14","result":{"state":"closed"}}workspace.kill destroys the workspace on its runner. If the runner is offline the state comes
back closing: the row keeps its slot and the reaper finishes the job when the runner returns.
workspace.admin_list shows live and recent workspaces of every operator, which is how aarvee
finds a session to kill. aarvee can see and kill workspaces but has no method to read or write
inside one.
{"v":1,"id":"2","method":"token.create","params":{"fleet":"prod","labels":{"role":"db"},"approve":false,"uses":1,"ttl_s":86400}}
{"v":1,"id":"2","result":{"id":"0123456789abcdef",
"token":"mfj1.0123456789abcdef.EXAMPLE_SECRET_NOT_REAL_EXAMPLE_SECRET_FAKE.EXAMPLE_HOSTKEY_HASH_NOT_REAL_EXAMPLE_HOSTK",
"expires":"2026-11-14T09:41:07.512Z"}}{"v":1,"id":"3","method":"token.list","params":{"fleet":"prod"}}
{"v":1,"id":"3","result":{"tokens":[{"id":"0123456789abcdef","fleet":"prod","labels":{"role":"db"},
"approve":false,"max_uses":1,"uses":0,"expires":"2026-11-14T09:41:07.512Z","revoked":false}]}}{"v":1,"id":"4","method":"token.revoke","params":{"id":"0123456789abcdef"}}
{"v":1,"id":"4","result":{}}{"v":1,"id":"5","method":"runner.lifecycle","params":{"fleet":"prod","runner":"db-1","op":"approve"}}
{"v":1,"id":"5","result":{"name":"db-1","status":"active","online":false,"labels":{"role":"db"}}}online is always false in this reply: it is the stored row, not the live state. Use runners.list for live state.
{"v":1,"id":"6","method":"operator.code"}
{"v":1,"id":"6","result":{"code":"mfr1.EXAMPLECODEEXAMPLECODEEXAM.EXAMPLE_HOSTKEY_HASH_NOT_REAL_EXAMPLE_HOSTK",
"seconds_left":37,"host_fingerprint":"SHA256:EXAMPLE_FINGERPRINT_NOT_REAL"}}{"v":1,"id":"7","method":"operator.rotate_secret"}
{"v":1,"id":"7","result":{}}{"v":1,"id":"8","method":"operator.list"}
{"v":1,"id":"8","result":{"operators":[
{"name":"durga","fingerprint":"SHA256:EXAMPLE_DURGA_FP","status":"active","last_seen":"2026-11-13T09:40:12.004Z"},
{"name":"kalyan","fingerprint":"SHA256:EXAMPLE_KALYAN_FP","status":"revoked"}]}}{"v":1,"id":"9","method":"operator.revoke","params":{"name":"kalyan"}}
{"v":1,"id":"9","result":{}}{"v":1,"id":"10","method":"audit.list","params":{"since_id":1040,"limit":2}}
{"v":1,"id":"10","result":{"events":[
{"id":1041,"time":"2026-11-13T09:41:07.512Z","source":"api","actor_kind":"operator","actor":"durga",
"remote":"203.0.113.7:51514","fleet":"prod","runner":"db-1","subject":"tail-logs","action":"action.run",
"params":{"lines":"200"},"outcome":"start","request_id":"9f1c0a5be2d84c7790a1b3c4d5e6e07a"},
{"id":1042,"time":"2026-11-13T09:41:07.561Z","source":"api","actor_kind":"operator","actor":"durga",
"remote":"203.0.113.7:51514","fleet":"prod","runner":"db-1","subject":"tail-logs","action":"action.run",
"outcome":"ok","exit_code":0,"duration_ms":41,"request_id":"9f1c0a5be2d84c7790a1b3c4d5e6e07a"}]}}audit.list has an extra, direct check in its handler that the caller's kind is admin. Fields
that are empty or zero are omitted (omitempty), except id, time, source, actor_kind,
actor, action. To export the log, call repeatedly with since_id set to the last id seen.
The exit_code pointer distinguishes "0" from "none".
Filters (M4). api.AuditListParams gained optional, additive fields, all exact matches
except where noted; leave them out and the call behaves as before. They exist because the GUI's
Audit screen filters the log, and the admin socket and the screen share one code path
(service.ListAudit over store.QueryAudit).
| Field | Meaning |
|---|---|
before_id |
only rows with a smaller id (paging backwards) |
fleet, runner, actor, source, outcome, workspace, request_id
|
exact match on that column; source is cli, api, gui, enroll or system
|
action |
exact action name, or a prefix when action_prefix is true (runner. finds every runner action; the % and _ characters are escaped) |
from, to
|
RFC 3339 time range |
mirafleet central audit has a flag for each (-fleet, -runner, -actor, -source,
-outcome, -action, -action-prefix, -workspace, -request-id, -from, -to, -before).
Two new admin methods arrived with the GUI, and neither is served on api@mirafleet (they are in
api.IsAdminMethod, so an agent gets forbidden):
{"v":1,"id":"15","method":"fleet.set_confirm","params":{"fleet":"prod","confirm":true}}
{"v":1,"id":"15","result":{"fleet":{"name":"prod","mode":"actions","confirm":true,"runners":1}}}
{"v":1,"id":"16","method":"gui.reset_admin"}
{"v":1,"id":"16","result":{"setup_token":"mfs1.EXAMPLE_SETUP_TOKEN_NOT_REAL"}}fleet.set_confirm is what mirafleet central fleet set prod -confirm=true sends (and what the
GUI's guard toggle calls through the service). gui.reset_admin is what mirafleet central gui reset-admin sends. The GUI cannot call it: gui.Backend leaves ResetGUIAdmin out on purpose,
and Service.ResetGUIAdmin itself refuses any source but cli, so recovery needs shell access to
the central host and cannot be started from a browser
(chapter 10).
Used by SSH user enroll. Each connection carries one channel with one request and one
response, then closes. The method must match the channel type; mismatches get bad_request
"method does not match channel", and enrol methods on api@mirafleet get forbidden.
Both clients pin central's host key from the credential before sending it (chapter 5).
{"v":1,"id":"j1","method":"enroll.join","params":{
"token":"mfj1.0123456789abcdef.EXAMPLE_SECRET_NOT_REAL_EXAMPLE_SECRET_FAKE.EXAMPLE_HOSTKEY_HASH_NOT_REAL_EXAMPLE_HOSTK",
"name":"build-1"}}
{"v":1,"id":"j1","result":{"fleet":"dev","runner":"build-1","status":"pending"}}status is active if the token was made with -approve. The params struct also has an optional
labels field; it is accepted but ignored: labels come only from the token.
{"v":1,"id":"r1","method":"enroll.register","params":{
"code":"mfr1.EXAMPLECODEEXAMPLECODEEXAM.EXAMPLE_HOSTKEY_HASH_NOT_REAL_EXAMPLE_HOSTK",
"name":"durga"}}
{"v":1,"id":"r1","result":{"operator":"durga","status":"active"}}| Situation | Response |
|---|---|
| Anything wrong with the token or code (malformed, wrong pin, unknown, wrong secret, expired, revoked, used up, no registration secret) |
{"code":"unauthenticated","message":"join refused"} or "registration refused", byte-identical for every cause |
| Name already used by a live runner, key already enrolled, key belongs to the other role, revoked operator key |
{"code":"conflict","message":"conflict"} (only reached with a valid token or code) |
| Bad name |
{"code":"bad_request","message":"invalid runner name"} / "invalid operator name"
|
| Not an Ed25519 key |
bad_request "ssh-ed25519 key required" |
api.Error has code (stable, machine-readable), message (human, fixed text per code so no
internal details leak) and, for unsupported_version only, supported (the versions this build
speaks). service.ToAPIError maps internal errors to these.
| Code | Meaning | When it happens |
|---|---|---|
bad_request |
You sent something invalid. Fix the request. | Malformed or empty or truncated frame; missing/invalid v; bad id (empty or over 128 bytes); empty or unknown method; unknown or trailing JSON fields; invalid params (names, limits, negative timeout_s); store.ErrInvalid; wrong or missing confirm; runner guard refused; method/channel mismatch. |
unauthenticated |
Credential refused. | Only join refused / registration refused. SSH authentication failures never produce this: they end the handshake with an opaque "access denied". |
forbidden |
Understood, not allowed for you. | Policy denial; admin or enrol method on the wrong front end; operator no longer active; audit.list by a non-admin. Always the same message, forbidden. |
not_found |
The thing does not exist. | Unknown fleet or runner; unknown token id on revoke; unknown operator on revoke. |
conflict |
The thing exists, but its state does not allow this. | Duplicate fleet name; runner is pending/disabled/revoked ("runner is X"); lifecycle op not allowed from the current status; fleet not in actions mode; name or key clash on enrol; store.ErrConflict or ErrStale outside enrol. |
unavailable |
Try again later. | Runner offline or unreachable; runner revoked mid-run; audit not writable; request cancelled. |
too_large |
Message too big. | Request frame over 64 KiB; response over 1 MiB + 64 KiB. |
timeout |
Too slow. | Request not fully received within 10 s; action.run exceeded its timeout. |
unsupported_version |
v is not one this server speaks. |
v is a valid integer other than 1; carries supported. |
internal |
Our bug or a store failure. | Message is always internal error; the cause is logged on central only. |
Workspace methods (M3) use the same codes. The cases you will meet:
| Code | Workspace situation |
|---|---|
bad_request |
Invalid session; image not on the fleet allowlist; env name denied or malformed; bad path or cwd (NUL, .. escape, too long); sha256 mismatch or not 64 lowercase hex; body shorter than length; refused by runner: ... (the runner's own workspace.yaml or limits said no: image, env, network mode, cap, quota, max_file); wrong or missing confirm. |
not_found |
Unknown workspace id, malformed id, or a workspace owned by someone else (deliberately identical). |
conflict |
Fleet not in workspace mode (or action.run on a workspace fleet); workspace is not open ("workspace is closing"); "workspace is still opening"; "workspace limit reached (8)" (per-operator cap). |
unavailable |
The session's runner is offline; "no runner can take this workspace right now"; "runner busy"; "runner is disabled" / "runner is pending approval"; "runner has no workspace executor"; "audit unavailable"; "runner unavailable". |
too_large |
Body frame over 1 MiB (or over the stated length). |
timeout |
Body not received within 30 s; open took more than 5 minutes; a file operation or close took more than 60 s; central's own deadline for an exec (the exec timeout plus a 15 s margin) passed with no answer from the runner. A normal deadline hit is not an error: the runner kills the command and the result says timed_out: true. |
Note that timeout after the request is read comes from the service. If the 10 s read timer
fires, central closes the channel, so the error reply may never arrive.
Defined in internal/api/api.go unless another place is named. "Config" fields are in
internal/central/central.go (central.Config; zero means the default constant). This is the
one limits table in the guide; other chapters link here instead of repeating it. Every network
input has a bound that is checked before its cost is paid.
| Constant / field | Value | Why |
|---|---|---|
api.MaxRequestBytes |
64 KiB (65 536) | Requests are small; checked before allocation. |
api.MaxResultBytes |
1 MiB | Mirrors actions.MaxOutput: stdout and stderr combined. |
api.MaxResponseBytes |
1 MiB + 64 KiB | Result plus JSON overhead; bigger becomes too_large. |
api.MaxParams / MaxParamKey / MaxParamValue
|
32 / 64 B / 4 KiB | Bounds the params map. |
| id length | 1 to 128 bytes |
maxIDLen. |
transport.MaxResultBytes |
8 MiB | Most central reads from one exec@ result: 1 MiB output times at most 6 for JSON escaping, plus slack. |
actions.MaxOutput |
1 MiB | Runner caps stdout+stderr combined. |
maxInfoValue |
256 B | Each heartbeat-supplied string stored for a runner. |
store maxInfoBytes
|
16 KiB | Runner info JSON. |
| audit list | default 100, max 1000 | Rows per audit.list. |
api.MaxFileChunk |
1 MiB | One body frame: a file chunk or stdin. Bigger files go in chunks with offset. |
api.MaxArgvElems / MaxArgvBytes
|
256 / 32 KiB |
workspace.exec argv; no NUL. |
api.MaxPathBytes |
4 KiB |
cwd and file path. |
api.MaxEnvVars / MaxEnvValue
|
32 / 4 KiB |
workspace.exec env; names ^[A-Z_][A-Z0-9_]{0,63}$. |
api.MaxSessionLen |
128 | Workspace session, charset A-Za-z0-9._:-. |
transport.MaxWorkspaceRequestBytes |
64 KiB | The workspace@ channel-open data. |
transport.MaxBodyBytes |
1 MiB | Raw body (stdin or file chunk) per workspace@ request. |
transport.MaxWorkspaceResultBytes |
1 MiB + 64 KiB | Largest WorkspaceResult frame; central and runner both use it (not the 8 MiB exec cap). |
transport.MaxSpecLabels / MaxEgressRules
|
16 / 64 | Labels and egress rules in a create spec. |
transport.MaxHeartbeatSlots / MaxHeartbeatImages / MaxHeartbeatImageBytes
|
1024 / 32 / 256 B | Bounds on the workspace heartbeat fields. |
| workspace exec output | 1 MiB JSON-encoded | Head and tail kept; stdout and stderr share the budget (wsOutputBudget, a little under 1 MiB). |
| concurrent execs | 4 per workspace |
maxExecPerWorkspace on the runner; the 5th is ResourceShortage. |
service.DefaultMaxWorkspacesPerOperator |
8 | Live workspaces per operator. |
transport.MaxHeartbeatActions / MaxActionNameBytes / MaxActionPatternBytes / MaxActionsBytes
|
128 / 64 B / 256 B / 16 KiB | Bounds on the M5 heartbeat actions (action discovery). |
maxListActionsBytes (internal/central/dispatch.go) |
512 KiB | Encoded action bytes in one runners.list reply; later runners get actions_omitted. |
opconf.DefaultOutputCap (MinOutputCap, MaxOutputCap) |
30 KiB (settable 4 KiB to 256 KiB) | The MCP layer's cap on command output and file text, section 7.13. |
mcpserver.MaxWriteBytes |
8 MiB | Largest write_file content once decoded (sent to central in 1 MiB chunks). |
maxListEntries (internal/mcpserver) |
200 | Entries in any MCP list result; then truncated: true. |
| Constant / field | Value | Why |
|---|---|---|
api.MaxChannelsPerConn |
8 | Concurrent api@ channels per operator connection. |
runner.Config.MaxExec |
4 | Concurrent actions per runner; the 5th is rejected ResourceShortage. |
Config.MaxHandshakesPerIP (DefaultMaxHandshakesPerIP) |
64 | Handshakes in progress per source IP (IPv6: per /64, the block of addresses one machine normally owns). Exempt if the source already has an authenticated connection. |
Config.MaxHandshakes (DefaultMaxHandshakes) |
512 | Handshakes in progress overall. |
MaxAuthTries |
3 | Key offers per connection. |
Config.EnrollDeadline (DefaultEnrollDeadline) |
30 s | Whole lifetime of an enroll connection. |
Config.EnrollRatePerMin (DefaultEnrollRatePerMin) |
10 per min per source | Permit bucket (a counter that refills over time), burst = rate; checked after the handshake. |
Config.EnrollGlobalRatePerMin (DefaultEnrollGlobalRatePerMin) |
60 per min overall | Permit bucket across all sources; stops address rotation. |
maxBuckets (enroll limiter) |
4096 | Hard cap of the per-source table; idle buckets pruned, then least recently used evicted. |
| Constant / field | Value | Why |
|---|---|---|
api.RequestTimeout |
10 s | Time to deliver a complete request; closes the channel on expiry (SSH channels have no read deadline, so a timer closes them). |
api.WriteTimeout |
10 s | A peer that stops reading cannot pin a handler. On timeout the channel and the owning connection are closed. |
api.ListTimeout |
10 s | Cap for all non-action.run methods. |
api.DefaultActionTimeout |
2 min | When timeout_s is 0. |
api.MaxActionTimeout |
10 min | Cap on timeout_s; clamped in seconds so huge values cannot overflow. |
api.BodyTimeout |
30 s | Time to deliver a body frame once central asks for it; the channel is closed on expiry. |
fleet exec_default_s / exec_max_s
|
120 s / 1800 s | Per-fleet workspace exec timeout; api.HardWorkspaceExecCeiling (24 h) is the absolute cap, and the runner's limits.exec_max (default 1 h) applies again. The shortest wins. |
| exec central margin | +15 s |
execMargin: central waits this long beyond the exec timeout for the runner's reply. |
| workspace open | 5 min | Includes an image pull (DefaultWorkspaceOpenTimeout). |
| workspace file op, close | 60 s |
fileOpTimeout, workspaceCloseTimeout. List on the runner: 10 s. |
| reaper sweep | 60 s |
service.DefaultReaperInterval. |
fleet idle_ttl_s / max_ttl_s
|
24 h / 168 h | Defaults for idle and absolute workspace lifetime. |
| disk sampler (runner) | 60 s | Workspace disk usage; 2x the quota destroys the workspace. |
actions.DefaultTimeout |
60 s | Per-action timeout if actions.yaml gives none. |
runner.Config.HeartbeatEvery |
15 s | Heartbeat interval. |
registry StaleAfter
|
45 s (3 x heartbeat) | No heartbeat for this long = offline, connection closed. Set in cmd/mirafleet/central_linux.go. |
Config.HandshakeTimeout (DefaultHandshakeTimeout) |
10 s | Time to finish the SSH handshake. |
Config.TouchInterval (DefaultTouchInterval) |
5 min | Minimum gap between last_seen_at writes per runner (connect writes are further throttled to one per TouchInterval / 10, 30 s). |
apiclient.HandshakeTimeout |
30 s | Client: connect plus SSH handshake. |
orch.CallTimeout / orch.RunMargin
|
2 min / 30 s | MCP layer: client-side limit for any call not listed next. action.run and workspace.exec get their own timeout_s plus RunMargin; workspace.open gets 5 min + RunMargin; file calls 100 s (orch.CallLimit). |
orch.DefaultKeepalive / orch.GuardedTTL
|
30 s / 30 s | MCP layer: how often an idle connection is pinged, and how long the "which fleets are guarded" answer is cached. |
mcpserver.DefaultProgressInterval |
15 s | Spacing of notifications/progress while a tool call runs. |
| runner dial / backoff | dial 10 s; reconnect backoff 1 s to 60 s, doubling, jittered +-20% |
BackoffMin/BackoffMax; backoff resets only after a connection stayed up and acked heartbeats for HealthyAfter (30 s). |
auth lookup timeout |
5 s | One store lookup during the handshake. |
storeTimeout |
5 s | Best-effort last_seen writes. |
outcomeWriteTimeout |
10 s | Final audit write after an action, even if the caller left. |
| Constant / field | Value | Why |
|---|---|---|
service.MaxTokenUses / DefaultTokenUses
|
1000 / 1 | Join token uses. |
service.MaxTokenTTL / DefaultTokenTTL
|
30 days / 24 h | Join token lifetime. |
| labels | 32 labels, key 64 B, value 256 B |
service token label limits. |
tokens.StepSeconds |
60 | Registration code window. |
This traffic is not the framed JSON above. It uses native SSH features.
An SSH global request with want_reply = true. The payload is a JSON transport.Heartbeat:
{"hostname":"db-1.example.com","os":"linux","arch":"amd64","version":"0.2.0","labels":{"role":"db"}}A workspace runner adds four optional fields (M3). An actions runner omits them, and zero values mean "no workspace executor":
{"hostname":"build-1.example.com","os":"linux","arch":"amd64","version":"0.3.0","labels":{"zone":"a"},
"slots":4,"executor":"containerd","secure_runtime":"","images":["docker.io/library/golang@sha256:*"]}| Field | Meaning | Bound (Heartbeat.Validate) |
|---|---|---|
slots |
How many workspaces this runner accepts at once (concurrent in workspace.yaml) |
0 to 1024 |
executor |
containerd or opensandbox; central places a workspace only on a runner whose executor equals the fleet's |
lowercase name, at most 32 chars |
secure_runtime |
gvisor, kata or empty: whether the runner can serve guarded fleets |
at most 64 chars, [A-Za-z0-9._-/:]
|
images |
The runner's image allowlist patterns, for placement only | at most 32 entries of at most 256 bytes |
An actions runner (M5) adds one more optional field, actions: the list of actions it offers,
each with its parameter names, patterns and defaults, built by actions.Set.Describe() from
actions.yaml. It is the source of the actions in runners.list (section 7.5). Central bounds
it in Heartbeat.Validate: at most 128 actions (transport.MaxHeartbeatActions), names up to 64
bytes, patterns up to 256 bytes, at most 16 KiB encoded (transport.MaxActionsBytes). It is
informational only; the guard on the runner never reads it.
{"hostname":"db-1.example.com","os":"linux","arch":"amd64","version":"0.5.0","labels":{"role":"db"},
"actions":[{"name":"tail-logs","params":[{"name":"lines","pattern":"^[0-9]{1,4}$","default":"200"}]}]}Central does not trust any of these heartbeat fields to be enforced: slots and images are hints for placement and
the runner re-checks everything. A runner that inflates slots only overloads itself, because
central counts live workspaces from its own database and the runner has its own semaphore. An
out-of-range value is a hostile or broken runner: central refuses to register it and drops the
connection. The heartbeat's labels are still ignored for placement: workspace labels are
matched against the trusted token labels stored when the runner joined.
- Sent immediately after connecting and then every 15 s. The runner waits at most 2 x the interval for the reply, then closes the connection and reconnects (with backoff).
- Central registers the runner in its live registry on the first heartbeat (by then the runner
has installed its channel handler). A connection that never heartbeats is closed after
StaleAfter(45 s). - Central replies
truefor a good heartbeat. It repliesfalsefor a payload that is not valid JSON, for any other request type, and for a refusal to register (tombstoned or revoked runner, after which it closes the connection). - Central stores hostname, os, arch and version (clipped) as
runners.info; heartbeatlabelsare not stored. Heartbeats themselves are not written to the database. - A session with no heartbeat for
StaleAfteris reported offline and its connection is closed.
Central opens a channel of type exec@mirafleet on the runner's own connection (the runner
never accepts inbound connections). The request is the SSH channel-open extra data,
a JSON transport.ExecRequest:
{"action":"tail-logs","params":{"lines":"200"}}The runner:
- Rejects a malformed request with
ConnectionFailed("malformed exec request"). - Rejects with
ResourceShortage("runner busy ...") if it already runsMaxExec(4) actions. (Central sees an open-channel failure and reportsunavailable.) - Otherwise accepts, writes its own audit line (
start), asks the actions guard to plan and run. - Writes one JSON document, a
transport.ExecResult, to the channel, thenCloseWrite. There is no length prefix here: end-of-stream marks the end. Central reads at mosttransport.MaxResultBytes+ 1 bytes and fails if more arrives.
{"stdout":"Nov 13 09:41:03 ...\n","stderr":"","exit_code":0,"duration_ms":41}A refusal by the guard (nothing ran):
{"stdout":"","stderr":"","exit_code":-1,"refused":true,"message":"refused: unknown action \"bash\"","duration_ms":0}Optional fields: stdout_truncated, stderr_truncated, timed_out (the runner killed the process at its
deadline; exit_code is -1 and message is "timed out; process killed"). If the encoded result would exceed
8 MiB, the runner sends exit_code: -1 with message: "result too large to send" instead.
Cancellation. The runner watches the channel: when central closes it (the caller gave up, the
operator was revoked, the runner was kicked) or the connection drops, the action's context is
cancelled and the whole process group is killed. The runner also writes its own outcome
audit line (ok, failed, refused, timeout) before telling central.
Two timeouts apply: the action's own timeout in actions.yaml (runner side) and the
action.run timeout (central side, default 2 min, max 10 min). The shorter one wins.
The workspace twin of exec@mirafleet: central opens it on the runner's own connection, one
channel per operation. It is a different channel type on purpose: an exec@ request must only
ever reach the actions guard, and mixing workspace operations into it would blur that boundary.
There is no separate file channel; reads and writes are operations on this one.
The request is the channel-open extra data (at most 64 KiB), a JSON
transport.WorkspaceRequest. Only the fields an operation needs are set:
op |
Fields used |
|---|---|
create |
id, spec, timeout_ms
|
exec |
id, argv, cwd, env, stdin_len, timeout_ms
|
read |
id, path, offset, limit
|
write |
id, path, offset, truncate, mode, length, timeout_ms
|
destroy |
id |
list |
none |
{"op":"create","id":"3f9a6c1e5b7d4820a1c3e5f708192a4b","timeout_ms":300000,"spec":{
"image":"docker.io/library/golang@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"pull":"if-not-present","cpu_milli":2000,"memory_bytes":4294967296,"pids":1024,
"tmpfs_bytes":536870912,"disk_bytes":10737418240,"network_mode":"egress",
"allow":[{"host":"proxy.golang.org","port":443}],"labels":{"zone":"a"},"max_age_ms":604800000}}{"op":"exec","id":"3f9a6c1e5b7d4820a1c3e5f708192a4b","argv":["go","test","./..."],"cwd":"/workspace/src",
"env":{"CI":"1"},"timeout_ms":300000}Central decodes strictly (unknown fields are an error) and validates the shape (known op, sizes, non-negative lengths) before sending. The runner does it again, plus the semantic checks (image allowlist, env allowlist, path confinement, limits against its own caps): central is not trusted.
The bytes on the channel, in order:
- For
writeandexecwithstdin_len > 0: central streams exactlylength(orstdin_len) raw bytes, thenCloseWrite. There is no length prefix here, because the request already said how many. A short or long body is an error (ErrBodyLength). - The runner replies with one length-prefixed JSON frame, a
transport.WorkspaceResult(4-byte big-endian length, at most 1 MiB + 64 KiB, checked before allocating):
{"code":"ok","exec":{"exit_code":0,"stdout":"ok \texample.com/app\t0.412s\n","stderr":"","duration_ms":1873},"duration_ms":1875}Other result shapes: {"code":"ok","file":{"size":1342,"mode":420,"length":1342,"eof":true},"duration_ms":2} for
a read or write, {"code":"ok","list":[{"id":"...","image":"...","state":"running","created_ms":1794562867000,"disk_bytes":4096}],"duration_ms":4}
for list, and {"code":"refused","message":"image not allowed on this runner","duration_ms":0}
for a refusal.
3. For read only: length raw bytes follow the result frame, then CloseWrite.
code is one of ok, bad_request, refused, not_found, busy, too_large, quota,
unavailable, unsupported, timeout, internal. The service maps them to the operator-facing
codes of section 7.8 (refused, too_large, quota and unsupported all become bad_request
"refused by runner: ..."; busy becomes unavailable).
Admission before accept. A runner that is full cannot say "busy" inside the channel after
accepting without wasting the body, so it decides before accepting: no workspace config means
reject with Prohibited (central: runner has no workspace executor); all slots or exec
permits taken means reject with ResourceShortage (central: runner busy; for open, central
then tries the next candidate runner). An unreadable request is rejected ConnectionFailed.
Cancellation works as for exec@: when central closes the channel (the caller gave up, the
operator was revoked) or the connection drops, the runner cancels the executor context and the
in-flight command is killed. The runner audits start and the outcome to its own JSONL log on
every operation, and writes its outcome before answering.
Limits on this channel: at most 4 concurrent execs per workspace, concurrent workspaces
per runner, MaxArgvItems 256, argv 32 KiB, paths 4 KiB, env 32 variables, 1 MiB per body.
mfj1.0123456789abcdef.EXAMPLE_SECRET_NOT_REAL_EXAMPLE_SECRET_FAKE.EXAMPLE_HOSTKEY_HASH_NOT_REAL_EXAMPLE_HOSTK
| | | |
| | | +- 43 chars: central's host key hash
| | +- 43 chars: the secret
| +- 16 lowercase hex chars: the token id
+- format version 1, fixed prefix "mfj1."
| Part | Size | How it is made | How it is checked |
|---|---|---|---|
mfj1. |
5 chars | Constant tokens.JoinPrefix; the 1 is the format version. |
ParseJoinToken requires the prefix. |
id |
16 hex chars | First 8 of 40 random bytes (crypto/rand), hex-encoded. Public: used for lookup, token list, audit. |
Lowercase hex, exactly 16 characters (ParseJoinToken; store.CreateToken re-checks with ^[0-9a-f]{16}$). |
secret |
43 chars | Last 32 of those random bytes, base64url without padding. 32 bytes = 256 bits = 43 characters. | Must decode to exactly 32 bytes and re-encode to the identical string (rejects non-canonical spellings). Central hashes it with SHA-256 and compares with the stored hash in constant time. |
hostkeyhash |
43 chars |
SHA-256(hostKey.Marshal()), base64url without padding. |
The client compares it with the server's key before sending anything (apiclient.PinnedHash). Central also checks the token's hash equals its own (hostHashEqual, constant time), so a token for another central is useless here. |
Total length: 5 + 16 + 1 + 43 + 1 + 43 = 109 characters. Splitting on . must give exactly three
parts after the prefix. The . and _, - characters never clash: base64url uses - and _ but not ..
The base64url hash differs from what ssh-keygen -l prints (SHA256: plus standard base64 with +
and /). apiclient.Fingerprint converts between them when an operator supplies a fingerprint by hand.
Only SHA-256(secret) is stored (join_tokens.secret_hash). The token is printed once.
mfr1.EXAMPLECODEEXAMPLECODEEXAM.EXAMPLE_HOSTKEY_HASH_NOT_REAL_EXAMPLE_HOSTK
| | |
| | +- 43 chars: central's host key hash (same as in join tokens)
| +- 26 chars of base32: the time-step code
+- fixed prefix "mfr1."
| Part | How it is made | How it is checked |
|---|---|---|
mfr1. |
tokens.CodePrefix. |
ParseCode. |
code (26 chars) |
step = floor(unix_seconds / 60). mac = HMAC-SHA256(key = secret, message = "mirafleet-register-v1" || step as 8 bytes big-endian). Then take the RFC 4648 base32 encoding of the 32-byte mac, uppercase, no padding, and keep the first 26 characters (26 x 5 = 130 bits). |
Only characters A to Z and 2 to 7. Central recomputes the code for its current step from the stored 32-byte secret and compares in constant time. The previous and next steps are refused. Verifying has no side effects, so any number of operators can use the same code in the same minute. |
hostkeyhash |
Same as for join tokens. | Same. |
Worked example of the step: at unix time 1795000000, step = 1795000000 / 60 = 29916666 (integer
division). As 8 big-endian bytes that is 00 00 00 00 01 c8 7d fa. Those bytes follow the 21-byte
domain string mirafleet-register-v1 into the HMAC. That step ends at unix time 1795000020 (so
seconds_left at the example instant is 20); from then on step = 29916667 and the whole code
changes completely.
operator.code returns seconds_left = 60 - (unix_seconds mod 60), a value from 1 to 60.
The string "mirafleet-register-v1" is a domain separator: it ensures an HMAC computed for this
purpose could never be mistaken for the same secret used for something else. The 32-byte secret
lives in the settings table (registration_secret). rotate-secret replaces it and all earlier
codes stop verifying.
What the code enforces:
-
Protocol version
vis an integer in every envelope. Todayapi.Version = 1andapi.SupportedVersions = [1]. The server readsvbefore decoding the rest, so a client speaking a future version gets a cleanunsupported_versionplus the list it can use, even if its other fields look different. -
helloreturnsversions, the full list a server speaks, so a client can pick a common one. - Request decoding is strict (unknown fields rejected); response decoding by the Go client is lenient (unknown result fields are ignored). So a newer server can add result fields without breaking older clients, but a newer client must not send new request fields to an older server.
- The response
vmust equal the client's expectation, and theidmust match the request. -
Credential formats are versioned in their prefix (
mfj1.,mfr1.) and in the HMAC domain string (mirafleet-register-v1). A parser accepts exactly its own version and nothing else. -
The database schema has its own version (
PRAGMA user_version), independent of the wire version; a newer database is refused (chapter 6). -
SSH names (
api@mirafleet,exec@mirafleet, ...) are the stable surface between versions of central and runners. A new capability gets a new channel type or method, and old peers reject what they do not know. M3 followed this:workspace@mirafleetis a new channel type, the sixworkspace.*methods are new methods, and nothing aboutexec@oraction.runchanged. -
M3 changed no existing request, and added only result and heartbeat fields:
runners.listgainedslots,free_slots,executor;fleets.listgainedworkspace;Heartbeatgainedslots,executor,secure_runtime,images. An older client ignores them (lenient result decoding). An older central ignores unknown heartbeat fields too, so a runner can be upgraded first; but it has noworkspace@support, so a workspace runner only makes sense behind an M3 central. The one place the framing grew is the body frame, and it is opt-in per method (stdin: true,write_file,read_file), so every M2 method still sees exactly one request frame and one response frame. -
M5 changed no existing request either. It added only result and heartbeat fields
(
runners.listgainedactionsandactions_omitted,workspace.closegainedstate,Heartbeatgainedactions) and no new method and no new channel type. The MCP layer (section 7.13) speaks a different protocol on a different pipe (stdin and stdout of a local process), so it has its own versioning, negotiated by MCP itself. -
The database has a new migration,
0002_workspaces.sql(chapter 6): upgrading central runs it automatically; a downgraded binary refuses the newer database.
Guidance for changing the protocol (derived from the rules above; not enforced by a test):
- Adding a new method or a new result field is compatible: old clients never call or never
read it. Add the DTO in
internal/api, the handler ininternal/central, the method name to the rightIs...Methodswitch, and the policy table. - Adding a new request field to an existing method breaks old servers (they reject unknown
fields). Prefer a new method, or bump
v. - Changing the meaning of a field, a code, or the frame layout is a breaking change: bump
api.Versionto 2, put2inSupportedVersionsnext to1for a transition period, and keep the version check ahead of everything else. - Never let a new method reach
api@mirafleetby accident: updateIsOperatorMethodand the policy table deliberately;TestMethodSetsDisjointandTestEnrollMethodsDisjointininternal/apiassert that the operator, admin and enrol sets are disjoint.
Everything above is how mirafleet programs talk to each other over SSH. The agent (Claude Code,
opencode, ...) does not speak any of it. It speaks MCP, the Model Context Protocol, to a local
process, mirafleet mcp, which translates each tool call into the operator methods of section
7.5. Terms: glossary (MCP tool, stdio server, JSON-RPC, harness). The code is
internal/mcpserver (the protocol and the tool definitions) over internal/orch (which context,
which fleet, the SSH connection); chapter 8 follows
one call through both.
MCP here is JSON-RPC 2.0 over the process's standard input and output: the harness writes one JSON object per line to the server's stdin, and the server writes one per line to stdout. Two rules follow from that and are enforced:
-
stdout carries protocol and nothing else. One stray
fmt.Printlnwould corrupt the stream. Logs go to stderr (Config.Logf), and a test (TestM5NoHooks) parses every stdout line. -
A line that is not JSON-RPC ends the session. The MCP library mirafleet uses (the official
Go SDK, "software development kit",
github.com/modelcontextprotocol/go-sdk; the "SDK" below) closes the connection on a malformed frame,mcpserver.Servereturns the decode error, andmirafleet mcpexits 1 without echoing the input (TestServeMalformedFrameExitsNonZero). A harness that sees this restarts the server.
sequenceDiagram
participant H as Harness (Claude Code)
participant S as mirafleet mcp
participant C as central.example.com:2222
H->>S: initialize (protocolVersion)
S-->>H: capabilities {tools}, instructions
H->>S: notifications/initialized
H->>S: tools/list
S-->>H: nine tools with schemas
H->>S: tools/call exec {command}
S->>C: workspace.exec over SSH (section 7.5)
C-->>S: result
S-->>H: structuredContent + text
H->>S: notifications/cancelled (optional)
Note over H,S: stdin closes: S exits 0
Caption: the harness drives; the server only answers. Arrows to the right of mirafleet mcp are
the SSH protocol of the earlier sections.
What the server implements, in internal/mcpserver/server.go:
-
Capabilities:
toolsonly. No resources, prompts, sampling or roots. The server also sendsinstructions, a short text saying that everything tools return (output, file contents, error text from remote hosts) is data from remote machines, not instructions, and that guarded fleets need the user's explicit agreement beforeconfirmis set (mcpserver.DefaultInstructions). -
Versions.
initializenegotiates up to MCP2025-11-25. A client that asks for2026-07-28is answered2025-11-25; an unknown version gets the same. The tests assert what the SDK actually answers (TestRawInitializeVersions), because the SDK (github.com/modelcontextprotocol/go-sdk, pinned ingo.mod) decides. -
Unknown method: JSON-RPC error
-32601. An unknown tool is refused too (the SDK answers with an error; the test accepts either shape).tools/callforfleet_createorrunner_lifecyclefinds nothing: the tool table is fixed in code and holds no admin tool. -
Cancel.
notifications/cancelledcancels the context of the running handler; the SSH channel to central is closed, which cancels the work on central and the runner. -
Progress. If the request carries a
progressToken, the server sendsnotifications/progressevery 15 s while the call runs and none after the answer. Output is still buffered: you get it all at the end. -
Shutdown. stdin EOF,
SIGTERMorSIGHUP(on Windows: an interrupt) stops the server with exit code 0. It cancels in-flight tool calls and closes the SSH connections (bounded to 5 s). It never closes workspaces; see chapter 4 for idle-on-exit and the reaper. One detail on stdin EOF: for at most 2 s the server first lets the quick calls it has already read (initialize,tools/list,ping) be answered, so a client that pipes its requests and closes stdin still gets those replies. It never waits for atools/call. The worst case after stdin EOF is therefore 2 s + 5 s = 7 s. If the client closes our stdout, the failed write (EPIPE; SIGPIPE does not kill the process) ends the server cleanly with exit code 0.
Tool names are in mcpserver.ToolNames and the schemas are JSON Schema strings in
internal/mcpserver/tools_list.go and tools_ws.go. Every tool has an inputSchema with
additionalProperties: false, an outputSchema, and all four behaviour hints
(readOnlyHint, destructiveHint, idempotentHint, openWorldHint) sent explicitly, because a
harness may choose its approval prompt from them. ? marks an optional argument.
| Tool | Arguments | Calls on central | Hints | Guarded confirm
|
|---|---|---|---|---|
list_fleets |
context? |
fleets.list per context |
read-only, idempotent | no |
list_runners |
fleet?, context?, runner?
|
runners.list |
read-only, idempotent | no |
run_action |
fleet?, context?, runner, action, params? (strings), timeout_s? (0 to 600), confirm?
|
action.run |
destructive | yes |
workspace_list |
fleet?, context?
|
workspace.list (your own only) |
read-only, idempotent | no |
workspace_open |
fleet?, context?, image?, labels?, confirm?
|
workspace.open |
idempotent | yes |
exec |
exactly one of command or argv; cwd?, env?, timeout_s? (0 to 86400), stdin? (at most 1 MiB), workspace?, fleet?, context?, confirm?
|
workspace.exec |
destructive | yes |
read_file |
path, offset?, limit? (1 to 1 MiB), encoding? (text or base64), workspace?, fleet?, context?
|
workspace.read_file |
read-only, idempotent | no |
write_file |
path, content, encoding?, offset?, mode? (0 to 511), workspace?, fleet?, context?, confirm?
|
workspace.write_file, in chunks |
destructive | yes |
workspace_close |
workspace?, fleet?, context?
|
workspace.close |
destructive, idempotent | no |
All nine carry openWorldHint: true (they reach other machines). Things worth knowing:
-
exectakescommandorargv, never both.command: "echo hi"becomes["/bin/sh","-c","echo hi"](the shell is inside the workspace, which is the point of workspaces);argvruns the program directly, with no shell. Neither or both isbad_request. -
workspacedefaults to this session's workspace on the resolved (context, fleet).exec,read_fileandwrite_filewith no workspace open one on the default fleet, only if that fleet is not guarded. On a guarded fleet the error says to callworkspace_openfirst. An unknown fleet fails closed (not_found), because it might be guarded. -
confirmis a pass-through string. The server never fills it from a config file, never remembers it and never defaults it; central checks that it equals the fleet name (chapter 5). When central refuses a guarded call, the server rewrites the message to:fleet `prod` in context `work` (argument) is guarded. Ask the user. Only after the user explicitly agrees, repeat the call with `confirm` set to the fleet name.so the model is told, in words, to stop and ask. It names the context and where it came from (guardedRewriteintools_list.go). -
list_runnerswithrunnerreturns just that runner and tries to keep all of its actions; see "List results and size budgets" below. Runner labels are set by an admin but are shown to the model, so they are sanitised like command output (cleanLabels). -
run_actionchecks names before it calls.runnermust match the name grammar (lowercase letters, digits,.,_,-) andactionmust be printable ASCII without spaces, at most 64 bytes, so odd text never gets as far as central or into an error message. -
workspace_closewith noworkspaceargument closes this session's workspace. After a server restart there is no in-memory binding, so the server asksworkspace.listfor your live workspace with this session id and closes that one (the model does not have to open one just to close it). -
No local files.
write_file.contentis the content itself, never a local path, and nothing reads or uploads a file from the operator's machine. A prompt-injected model asked to "upload~/.ssh" has no tool that can do it (chapter 5).
go-sdk's raw tool registration does no argument validation, so every handler starts with
mcpserver.DecodeArgs. It refuses:
- unknown fields and trailing data (
invalid arguments: unknown field "x"); -
keys that differ in case. Go's
encoding/jsonmatchesConfirmto a field taggedconfirmby default, but the Claude Code hook looks for the exact keyconfirm. Without this rule,{"Confirm": "prod"}would slip past the hook's "ask the user" prompt yet still setconfirmon the server.DecodeArgswalks the raw JSON and rejects any struct key that is not an exact-case match (unknown or mis-cased argument "Confirm") and any duplicate key (TestDecodeArgsExactKeys,TestEveryToolRejectsMiscasedAndDuplicateKeys; the attack is walked through in chapter 5); - a body that is not a JSON object.
Keys of a map argument (env, params, labels) are data and are not case-checked
(TestMapKeysStayData: env names are upper case on purpose). Every failure is a bad_request
with a short message; a key that is echoed back is clipped to 24 characters.
A successful call returns the same JSON object twice:
{"jsonrpc":"2.0","id":4,"result":{
"structuredContent":{"exit_code":0,"stdout":"ok \texample.com/app\t0.412s\n","stderr":"",
"truncated":false,"omitted_bytes":0,"duration":"1.873s","workspace":"3f9a6c1e5b7d4820a1c3e5f708192a4b",
"where":{"context":"work","context_source":"current context","fleet":"dev","fleet_source":"project file"}},
"content":[{"type":"text","text":"{\"exit_code\":0,\"stdout\":\"ok \\texample.com/app\\t0.412s\\n\", ...}"}]}}structuredContent is the typed result (validated against the tool's outputSchema by a client
that cares); the text copy is for harnesses that only show text to the model. A failure is
different on purpose:
{"jsonrpc":"2.0","id":5,"result":{"isError":true,
"content":[{"type":"text","text":"{\"error\":{\"code\":\"not_found\",\"message\":\"no such workspace\"}}"}]}}-
isError: true, text only, nostructuredContent. Otherwise a client that checks results againstoutputSchemawould reject the error for lackingexit_code. (Tool errors are results, not JSON-RPC errors, so the model sees them and can react.) -
codeis an api error code (section 7.8:bad_request,not_found,conflict,unavailable, ...), plus one MCP-layer code,canceled, andinternal. A cancelled context iscanceled; a client-side deadline istimeout. -
Only safe text gets out. An error type that implements
PublicError(*mcpserver.Error,*orch.Error) is shown as its code and message, wherever it sits in the error chain; wrapping text is dropped. Anything else, and any panic in a handler, becomesinternal: internal error, and the real error goes to stderr. So a local path, a key fingerprint or an SSH library message never reaches the model provider. Setup errors say what to do instead:not set up: runmirafleet mcp login ...``.
Every result that resolved a target has a where object:
{"context","context_source","fleet","fleet_source"}. The sources are argument, flag,
project file, current context, only context, context default or workspace id (an
explicit workspace argument names its own fleet). It exists because a repository's
.mirafleet.yaml can steer a call that names no fleet: if you cloned a repository that says
fleet: prod, the model's exec would go there. Showing where lets the human see which of the
user's centrals and fleets a call really used. The same precedence and the guarded-default rule
are in orch.Resolve: tool argument, then flags, then .mirafleet.yaml, then the context's
default_fleet; and a guarded fleet that came from the project file or a context default is
refused (it must be named explicitly).
Command output, action output and text files are untrusted text that goes straight into the
model's context (chapter 5 explains the threat).
orch.CapOutput and orch.Sanitize shape it before it leaves the server:
-
Cap. 30 KiB by default for stdout and stderr together (
output_cap_bytesincontexts.yaml, 4 KiB to 256 KiB). It is counted as the JSON-encoded size, so escaping a quote or<(whichencoding/jsonwrites as\u003c) cannot push the result over the cap. When a stream does not fit, the server keeps the first third and the last two thirds, puts\n[mirafleet: N bytes omitted]\nbetween, cuts on a character boundary, setstruncated: trueandomitted_bytes. A non-empty stderr always keeps at least a third. This sits on top of the runner's own 1 MiB cap. -
Sanitising. Invalid bytes become U+FFFD. ANSI escape sequences (colours, OSC titles,
hyperlinks) and control characters other than newline and tab are removed,
\r\nbecomes\n. Unicode tag characters are dropped and other invisible format characters (bidi overrides, zero-width characters, BOM) are written as visible<U+XXXX>. The point is that nothing can be hidden in the text the model reads: an escape sequence that paints over a line in a terminal, or a right-to-left override that reverses what a command looks like, has no effect.Sanitize(Sanitize(x)) == Sanitize(x)and it runs in linear time (FuzzSanitizeandFuzzCapOutputininternal/orch/output_test.go).
A file can be bigger than the cap, so read_file returns a page: offset, length, size
(of the whole file), eof, and next_offset when there is more. Pass next_offset back as
offset to continue. With no limit, the page is sized so the encoded result fits the output
cap (base64 text is a third longer than the bytes, and ", \, newlines and < take two to six
bytes in JSON, so a raw 30 KiB page could overflow); an explicit limit can go up to 1 MiB (one
body frame, api.MaxFileChunk). sha256 is the hash of the raw bytes of that page.
Two encodings:
-
text(default): UTF-8 only. A file that is not valid UTF-8 is refused with the size and SHA-256 of the page and the advice to use base64, so the model never reads binary garbage. A page that ends in the middle of a character is trimmed back so the next page starts on a character boundary. The content is sanitised as above;sanitized: truesays the returned text differs from the file (usebase64for the exact bytes). -
base64: the exact bytes, encoded.
content is text, or base64 with encoding: base64, up to 8 MiB once decoded
(mcpserver.MaxWriteBytes; larger is too_large). The wire limit is 1 MiB per body frame
(body frames in section 7.3), so the server splits the content into
chunks of at most api.MaxFileChunk and sends one workspace.write_file per chunk, computing
length and sha256 for each chunk itself (the model never has to). With offset 0 the first
chunk has truncate: true, which replaces the file; any later offset writes in place. A 1.5
MiB write is two calls, at offsets 0 and 1 MiB. If chunk two fails, the error says how much was
written (... (1048576 of 1572864 bytes were written)), because the file is now half-new. The
reply carries bytes_written, size (file size now) and sha256 of the full content.
Every list result is capped at 200 entries (maxListEntries) with truncated: true. list_fleets
with no context asks every configured context (four at a time); a context that is down becomes an
entry in errors[] ({"context","code","message"}) rather than failing the whole call. (Naming
a context that fails is a tool error.)
list_runners has the actions from section 7.5. Because those can be long, the encoded result
is kept within the output cap: runners are listed with their actions while the budget lasts, later
ones without actions and with actions_omitted: true, and if even the bare entries do not fit,
truncated: true. Central applies a second, larger budget of its own (512 KiB) and sets the same
actions_omitted flag. Either way the answer is the same: call list_runners again with
runner: "db-1" to get that one runner with its actions.
workspace_open returns {workspace, reused, session_source, where}. reused: true means a live
workspace for the same session already existed. session_source is flag, handoff or process:
where the session id came from (chapter 4). workspace_close returns
{state, workspace, where}: state is "closed", or "closing" when central could not reach the
runner yet and the reaper will finish (the workspace.close state field of section 7.5). After
a close, the server forgets the binding, so the next exec opens a fresh workspace.
Everything above is SSH. The admin GUI is the one HTTP surface. It is for aarvee in a browser,
not for agents: it has no JSON API, and it never carries a request from an operator or a runner.
Pages are server-rendered HTML (html/template); a small vendored library, htmx, swaps
HTML fragments into a page so a table can refresh without a full reload (chapter
2 explains htmx). The handler is the same either way: a plain request gets the
full page, a request with the header HX-Request: true gets just the fragment the route names
(Server.Render in internal/gui/render.go).
The routes are registered by one file per screen in internal/gui (handlers_*.go, listed in
routes.go); the table below is that code. "Admin" means the route sits behind
requireAdmin: no live session, no answer (a redirect to /login, or to /setup while no admin
exists). Passive routes are polled by htmx every 10 s and deliberately do not count as
activity, so an open tab cannot keep a session alive forever (chapter 5).
| Method and path | Needs | What it does |
|---|---|---|
GET /static/... |
nothing | Embedded CSS, JS, fonts; URL has a content hash, cached for a year. |
GET /setup, POST /setup
|
setup token (only while no admin exists; then 404) | First-start form; creates the admin and the first session. |
GET /login, POST /login
|
nothing (rate-limited) | Sign-in form and check. |
POST /logout |
admin | Deletes the session row, clears the cookie. |
GET / |
admin | Overview page. |
GET /overview/live |
admin, passive | Overview fragment (counts, runners waiting for approval, recent and denied audit rows). |
GET /fleets, GET /fleets/new, POST /fleets
|
admin | List, create form, create. |
GET /fleets/{fleet} |
admin | Fleet detail. |
GET /fleets/{fleet}/workspace, POST ...
|
admin | Edit the fleet's workspace config (full replace). |
GET /fleets/{fleet}/guard, POST ...
|
admin | Turn the confirm guard on or off (fleet.set_confirm). |
GET /runners |
admin | Runner list, all fleets. |
GET /runners/live |
admin, passive | The polled runner list fragment. |
GET /runners/{fleet}/{runner} |
admin | Runner detail (labels, slots, advertised actions). |
GET /runners/{fleet}/{runner}/revoke |
admin | Revoke confirmation page: type fleet/runner to continue. |
POST /runners/{fleet}/{runner}/{op} |
admin |
op is approve, disable, enable or revoke; any other value is 404. |
GET /tokens, GET /tokens/new
|
admin | Join tokens and the create form. |
POST /tokens |
admin | Creates a token; renders the token directly (once, no-store), no redirect. |
GET /tokens/{id}/revoke, POST ...
|
admin | Revoke a join token. |
GET /operators |
admin | Operators. |
POST /operators/code |
admin | Shows the registration code (renders directly, audited operator.code). |
GET /operators/rotate, POST ...
|
admin | Rotate the registration secret. |
GET /operators/{name}/revoke, POST ...
|
admin | Revoke an operator. |
GET /workspaces |
admin | Workspaces of every operator. |
GET /workspaces/live |
admin, passive | The polled workspace list fragment. |
GET /workspaces/{id}/kill, POST ...
|
admin | Kill a workspace. |
GET /audit |
admin | Audit log with filters, newest first, keyset paging. |
GET /audit/export?format=csv|jsonl |
admin | Streams the filtered log; an audit.export row is written first. |
GET /account |
admin | Password form, session list, theme. |
POST /account/password |
admin | Change the password (ends the other sessions). |
POST /account/sessions/revoke-others, POST /account/sessions/{id}/revoke
|
admin | End other sessions. |
POST /account/theme |
admin | Light, dark or system. |
Rules that hold for every route, all in internal/gui and each pinned by a test
(chapter 9):
-
Methods. Only GET and POST exist. Every state change is a POST, and every POST is checked
by the CSRF layers of chapter 5. A wrong method on a known path is
405. -
Forms. A POST body must be
application/x-www-form-urlencoded(else415) and at mostMaxFormBytes, 64 KiB (else413). Unknown fields are ignored. -
Post-redirect-get (PRG). A successful POST answers
303to a page (an htmx POST gets200withHX-Redirectinstead), never renders the result, so a reload cannot repeat the change. The two exceptions are the ones that show a secret once (POST /tokens,POST /operators/code). -
Host. The
Hostheader must be on the allowlist, else421before any routing. -
htmx. An expired session on an htmx request gets
200withHX-Redirect: /login(a plain303would be followed by the browser's fetch and swapped into the page as a fragment). -
Headers. Every response carries the security headers (
Content-Security-Policyand friends); HTML and fragments areCache-Control: no-store. -
Errors.
404,405,421and5xxare branded pages that show a request id (also theX-Request-IDheader and the access log line) and never a stack or SQL text.
The GUI's own limits (all in internal/gui unless noted):
| Constant / field | Value | Why |
|---|---|---|
DefaultListen |
0.0.0.0:8443 |
Default bind of -gui-listen; off disables the GUI. |
MaxFormBytes |
64 KiB | Body cap on every POST. |
DefaultMaxInFlight |
32 | Requests being served at once; the 33rd gets 503 with Retry-After. |
http.Server timeouts |
header 5 s, read 15 s, write 60 s, idle 120 s | A slow client cannot hold a connection; MaxHeaderBytes is 16 KiB. |
| route timeout | 15 s default; 60 s for hashing routes (POST /login, /setup, /account/password); audit export 10 min |
RouteTimeout per pattern. |
DefaultHashSem |
2 at once, wait 5 s, then 503
|
Argon2id costs 64 MiB of memory per hash; bounded so a login flood cannot exhaust RAM. |
| login limiter | 5 attempts per minute per client address (IPv6 per /64); 10 failures in a row lock that address 15 min |
loginBurst, lockoutAfter, lockoutFor. |
| global slow-down | more than 100 failures in 10 min: one attempt per 5 s for everyone | Never locks the account: with one admin that would be a free denial of service. |
limiterMaxEntries |
4096 | Hard cap on the limiter table (least recently used evicted). |
service.GUIIdleTimeout / GUIAbsoluteTimeout
|
30 min / 12 h | Session lifetimes. |
service.GUIMaxSessionsPerAdmin |
16 | Oldest session evicted when a 17th is created. |
service.GUISetupTTL |
24 h | Setup token lifetime. |
The protocol defines what happens when a runner is newer or older than central. Real fleets are
never upgraded in one instant: at MIRASTACK LABS aarvee upgrades central at 09:00, raj upgrades
build-1 at 09:10, and db-1 stays on the old version until Friday because it is busy. The protocol therefore defines a protocol
level (see the glossary) and one rule about it. The rule lives in a small, pure
package: internal/protover.
The protocol level is one integer. While mirafleet is at version 0.x it is the release's
minor version: v0.6.0, v0.6.3 and v0.6.0-rc.1 are all level 6. From 1.0 it is the major
version (v1.4.2 is level 1). Patch and pre-release parts never matter, because they never change
the wire format. protover.Current is the level of this build (6); protover.Parse,
Version.Level and LevelOf turn a version string into a level. relgen bump and relgen check
(section 8.12) keep Current equal to the level of
the release tag, so a release cannot ship with a stale number.
Why one integer and not "any change is compatible"? A number is something a program can compare in one line and a human can say in one sentence ("you are on 4, I need 5 or 6"). Why the minor version in 0.x? Under semantic versioning (see the glossary), 0.x makes no compatibility promise, so we treat each minor release as a possible protocol change; after 1.0 only a major release may break compatibility, so the major version is the level.
Central at level N accepts runners and orchestrators at level N and N-1. Anything else is
refused. protover.Accepts(central, peer) is peer >= 1 && (peer == central || peer == central-1). Level 0 means "missing": an old development build that never sent a level. It is
always refused.
| Central | Peer | Result |
|---|---|---|
| 6 | 6 | accepted |
| 6 | 5 | accepted (one behind: upgrade the peer soon) |
| 6 | 4 | refused: the peer is too old |
| 6 | 7 | refused: the peer is newer than central |
| 6 | missing (0) | refused |
The two directions need different advice, so protover.Check(role, name, central, peer) returns
an error whose text names who must upgrade. These are the texts the design pins:
runner `db-1` is protocol 4, central needs 5 or 6: upgrade mirafleet on that runner
central is protocol 6, this runner is 7: upgrade central first
(role is runner or orchestrator; with no name the subject reads "this runner". At level 1
the "needs" part is just 1.)
Upgrade order follows from the rule: central first, then runners, then operators. See what
goes wrong in the other order: if raj upgrades db-1 to level 7 first, central (still 6)
refuses it with "upgrade central first", and db-1 is offline until central catches up. In the
documented order a not-yet-upgraded runner is at N-1 and keeps working.
The level restarts at 1 with v1.0, so a bare comparison could mistake 0.1 for 1.x.
protover.CheckVersions(role, name, centralVersion, peerVersion) first refuses any mix of 0.x and
1.x with protover.MixedMajorMessage ("mixed 0.x and 1.x: upgrade everything to 1.x, central
first") and only then compares levels. A 1.x central therefore does not accept 0.x peers. This is
a deliberate one-time break, to be called out in the 1.0 release notes.
The rule is wired into the handshake. Central compares plain
levels (Config.Proto, default protover.Current); the peer's name is in the message, so the
runner sees "runner db-1 is protocol 4, ..." and "central is protocol 6, runner db-1 is 7:
upgrade central first".
-
Runners: the
heartbeat@mirafleetpayload gains aprotofield (transport.Heartbeat.Proto, additive, so old receivers ignore it). Central checks it on the first heartbeat. On a mismatch it sends arefused@mirafleetglobal request whose payload is the message text (the runner acknowledges it), writes an audit rowrunner.refused_version(sourcerunner, outcomedenied, the message in the row) and closes the connection. The runner logs "central refused this runner: " and backs off to its maximum reconnect interval (60 s by default, with the usual jitter) and stays there, because a fast retry loop against a permanent refusal would hammer central. -
Operators:
hellocarriesprotoin its params and its result. A mismatch is an error with codeunsupported_versionand the message above (the subject reads "orchestratoralice").internal/orchturns it into a tool error with the same message, andmcp loginsays hello right after registering and prints it (the exit status is non-zero; the registration itself stands).
A missing proto counts as level 0 and is refused too. Operator refusals are logged by central
but not audited. The wiring compares levels, so the 0.x/1.x break above is not enforced by it yet;
CheckVersions is for callers that hold both release versions.
Where else does the version show up? The release build stamps the binary (-X main.version=...).
go install ...@v0.6.0 has no such stamp, so cmd/mirafleet/version_buildinfo.go reads the module
version from debug.ReadBuildInfo when the stamp is missing, and mirafleet version prints
v0.6.0 either way. A plain source build prints dev.
M7 lets an agent on the orchestrator's Mac work on a remote VM as if the VM were its laptop. The
design is in ARCHITECTURE.md; this section is the wire-level view. Plain-language story first:
the model (inference) stays on the Mac; every tool call runs on the VM; the secrets
(an SSH key, a GitLab token) live on central and reach the VM's memory, never the model. Terms
(host mode, credential, broker, ssh-agent, background job, Ref) are in the glossary.
Everything below follows the rules of the rest of this chapter: strict v1 envelope, exact-case
keys, size limits, body frames for bytes. The new DTOs are in internal/api/devws.go and
internal/transport/devws.go.
Status: built. The types, the MCP tools and central's dispatch for
workspace.fs,job_*,output_read(internal/central/dispatch.go) and thecredential.*admin methods exist.
tools/list now returns 24 tools: the nine of section 7.13 plus fifteen M7 tools. They are
defined in internal/mcpserver/tools_fs.go (files, transfer) and tools_bash.go (shells and
output); TestM5Done/02_tools pins the full list with its four hints. Every tool carries
openWorldHint: true. ? marks an optional argument. All tools also accept workspace?, fleet?
and context? (omitted: this session's workspace on the default fleet). A tool marked confirm
also takes confirm?, the fleet name on a guarded fleet, exactly as exec does
(chapter 5).
| Tool | Like Claude Code's | Arguments | Hints | confirm |
|---|---|---|---|---|
bash |
Bash |
command, description? (256 bytes), timeout_s? (0 to 600; default 120), run_in_background?
|
destructive | yes |
bash_output |
BashOutput |
shell_id, filter? (RE2, matching lines only) |
none of the four (it moves a read cursor) | no |
kill_shell |
KillShell | shell_id |
destructive, idempotent | no |
job_list |
(none) | no arguments | read-only, idempotent | no |
read_output |
(none) |
ref or shell_id (exactly one), stream?, offset?, limit? (at most 1 MiB), tail_lines?, grep?
|
read-only, idempotent | no |
read |
Read |
path, offset? (first line, 1-based), limit? (lines; default 2000) |
read-only, idempotent | no |
write |
Write |
path, content (at most 1 MiB), mode?
|
destructive | yes |
edit |
Edit |
path, old_string, new_string, replace_all?
|
destructive | yes |
multi_edit |
MultiEdit |
path, edits[] (1 to 64 of old_string, new_string, replace_all?) |
destructive | yes |
grep |
Grep |
pattern, path?, glob?, type?, output_mode?, -i?, -n?, -A?, -B?, -C?, multiline?, head_limit?
|
read-only, idempotent | no |
glob |
Glob |
pattern, path?
|
read-only, idempotent | no |
ls |
LS |
path?, ignore?[]
|
read-only, idempotent | no |
notebook_edit |
NotebookEdit |
path, edit_mode (replace, insert, delete), cell_id?, new_source?, cell_type?
|
destructive | yes |
upload |
(none) |
local, remote?, mode?
|
destructive, idempotent | yes |
download |
(none) |
remote, local?, overwrite?
|
destructive, idempotent | no |
Changed existing tools (all additive):
-
workspace_opengainscredentials?[](up to 32 names): narrow this session to a subset of the credentials the runner holds. It can never widen (section "Credentials on the wire" below). Theworkdirname comes from the project file (.mirafleet.yamlworkdir:), not from a tool argument. -
workspace_closegainsdelete?: also delete the session directory. Without it the directory is kept and reattached on the next open.
What is worth knowing:
-
bashrunsbash -lcin the session's current directory. The directory persists between calls (the result'scwd); environment variables do not (each call is a fresh shell). Over the wire it is an ordinaryworkspace.execwithargv: ["bash","-lc",command]; the runner recognises that shape and takes the host path (section 8.14). -
run_in_background: truereturns ashell_idat once (workspace.job_start).bash_outputreturns only the output since the previous call;read_outputre-reads from the start. At most 8 background shells per session; a shell stops at the fleet'sjob_max(default 12 h, at most 24 h). -
File tools run in the runner process, not through a shell.
workspace.fscarries one op from a fixed enum (read write edit multi_edit notebook_edit grep glob ls stat). Unknown ops arebad_request. A write is followed by one body frame holding the bytes (length and SHA-256 in the request), the same pattern asworkspace.write_filein section 7.3. -
readreturns images as MCP image content (png, jpg, gif, webp, up to 5 MiB) and describes other binary files (size, type, SHA-256) instead of dumping them. Text is numbered; long lines are clipped;.ipynbis rendered as cells with outputs. -
grepusesrgwhen it is on the runner'sPATH, else a Go implementation with the same options (RE2, so no look-around). The result shape is the same either way. Hidden files are searched;.gitis never entered;.gitignore,.ignoreand.rgignoreare honoured. -
uploadanddownloadare the only tools that touch the Mac's disk, and they are confined to the local project directory byos.OpenRoot: symlinks out are refused, so are.git,.claude,.mirafleet.yaml,.env*,*.pem,*.key,id_*,.npmrc,.netrcand similar, at most 64 MiB. Without this, a prompt-injected model could copy~/.ssh/id_ed25519to the VM. The code isinternal/orch/transfer.goand runs on the Mac, never on central. -
Local tools are denied for a remote project. The Claude Code plugin's
PreToolUsehook denies localBash,Read,Write,Edit,MultiEdit,Grep,Glob,LSandNotebookEditwhen.mirafleet.yamlsaysremote: true, with a reason naming the remote tool. The MCP server works without the hook; the hook only stops the model from picking the wrong tool (chapter 11). -
Remote text is neutralised. Every tool result and error passes
neutralizeininternal/mcpserver/server.go, which breaks harness control tags such as<system-reminder>so output from a remote file or command cannot pose as an instruction.fsopsnotices to the model are plain[Warning: ...]text for the same reason.
A foreground bash result has these new fields next to the old stdout/stderr/truncated:
{"exit_code":1,"stdout":"...first and last part...","stderr":"","truncated":true,
"stdout_bytes":5242880,"stderr_bytes":0,"omitted_bytes":5210112,
"ref":"c1f0a77e92b4d3a5","cwd":"/home/dev/work/sessions/cc-abc/app",
"note":"output was cut (5210112 bytes omitted); page the full output with read_output {\"ref\":\"c1f0a77e92b4d3a5\"} ..."}The runner tees the full output of every foreground command to a file named by ref (the last 32
are kept, at most 64 MiB each). The result carries the true sizes, how much was omitted, and the
ref; read_output {ref, offset, limit, tail_lines, grep} pages it. The inline part is bounded
twice: the runner keeps about 32 KiB per stream, and the MCP server applies the 30 KiB cap of section 7.13
(orch.CapOutput). The result says what was cut and how to get it: that is the "never a silent
cut" rule. Without it a failing build whose error is in the middle of 5 MiB of log would look
like a success that printed nothing useful.
read_output replies {content, offset, size, eof, lines, next_offset, omitted_bytes}; pass
next_offset as offset to continue.
New methods on api@mirafleet (all strict, all checked for ownership like the other workspace
methods; the mutating ones need confirm on a guarded fleet):
| Method | Params (besides workspace) |
Result | Tool |
|---|---|---|---|
workspace.fs |
op + the op's fields; confirm?; body frame for write
|
FSResult (kind: text, image, binary, notebook, entries, none); an image adds one body frame |
read write edit multi_edit notebook_edit grep glob ls, and upload/download
|
workspace.job_start |
command, description?, timeout_s?, confirm?
|
{job} |
bash (background) |
workspace.job_status |
job? (empty lists) |
{job} or {jobs}
|
job_list |
workspace.job_tail |
job, filter?
|
{job} with output since the last tail |
bash_output |
workspace.job_cancel |
job |
{job} |
kill_shell |
workspace.output_read |
ref or job, stream?, offset?, limit?, tail_lines?, grep?
|
one page | read_output |
A job result has job (the shell_id), state (running, exited, canceled, lost),
exit_code, started_ms, ended_ms, stdout_bytes, stderr_bytes. lost means the runner
could not find the job's process after a restart.
Other additive changes:
-
workspace.opengainscredentials?andworkdir?(a name, never a path). -
workspace.closegainsdelete?. The adminworkspace.killgains the same flag. -
runners.listshows, per runner, the credentials it holds as{name, kind, hosts, status}with statusok,expiring,expiredorinvalid. An operator never sees fingerprints, expiry dates or values. - The heartbeat gains
features(fs,jobs,creds,events,host),credentials(the same four fields, no value) andbusy(running background jobs; a workspace with one is "in use" and is not reaped as idle). - A host runner is held by one operator at a time:
workspace.openby another operator is refused withconflict, messagebusy: runner build-1 is in use by durga, and placement skips held runners. The hold ends when that operator's last live workspace there is closed, reaped, expired, killed or lost.
Credentials are admin only: they exist on the local admin socket (and in the GUI), never on
api@mirafleet, so a prompt-injected agent cannot call them. IsOperatorMethod is false for all of
them and TestM7Done checks that none is reachable on api@.
| Method | Params | Result |
|---|---|---|
credential.set |
name, kind (ssh-key, https-token, registry), hosts[], user?, auth? (basic, bearer, header), header?, known_hosts[]?, host_binding? (required default, or off), expires?, rotate? (gitlab_self), rotate_project?, length, sha256; the secret as ONE body frame |
{credential, replaced} |
credential.list |
name? |
{credentials[]}: masked info with fingerprint, expires, assignments, delivery per runner |
credential.delete |
name |
{} |
credential.assign / credential.unassign
|
name, fleet, runner? (empty: whole fleet) |
the updated credential |
credential.rotate |
name |
rotate now (only rotate: gitlab_self credentials) |
The value travels in a body frame (like workspace.write_file), never in the JSON params, so
it cannot appear in a logged request or an error message. No result echoes it. Replacing a
credential bumps its version and re-delivers to every assigned runner.
Central to runner, on the existing workspace@mirafleet channel kind, there is one new op,
creds_sync, whose body is {generation, credentials[]} with the secret values (this is the one
place a value leaves central). The runner replaces its whole in-memory set atomically and answers
{generation, count}. The effective set of a runner is its own assignments plus its fleet's
assignments. Central also pushes on connect.
The other new op family is fs, job_start, job_status, job_tail, job_cancel and
output_read, the transport side of the operator methods above.
A new channel kind goes the other way: the runner opens events@mirafleet to central and
writes length-prefixed EventBatch frames (at most 128 events or 64 KiB each). Central accepts
only this channel from a runner. An event is credential.use: session, credential name, host,
status, count, in 60 s windows. Central stores them as audit rows with source runner. If a runner
floods, an events.dropped row records what was dropped.
- A credential name the runner does not hold, in
workspace_open {credentials}, is refused at placement: central only picks a runner that holds every requested credential. A credentials list on a non-host (container) fleet isbad_request. -
workspace_openon a host fleet with a session that is already open elsewhere on the same runner isErrRefusedon the runner ("already open here"); two terminals cannot drive one directory. - File tools, jobs and credentials are for host fleets: M7 does not extend container mode.
On a container fleet they answer
bad_request("only host-mode fleets support this"), notunsupported. - Foreground
bashon a container fleet still works (it isexecwith a shell), but there is norefand no persisted cwd. - A job status
lostmeans the runner could not find the job's process (for example after a VM reboot).
Hosts, ports and tokens in this section are examples; no real secret appears anywhere in the guide.
- Why is the secret of
credential.seta body frame and not a JSON field? - A 5 MiB build log: what does the model get inline, and how does it read the rest?
- Which tools may a prompt-injected model call to read a credential value?
Answers
- Params are logged, audited and echoed in errors; a body frame never is, and no result returns it.
- About 30 KiB (head and tail), the true byte counts,
omitted_bytesand aref; it pages withread_output {ref, offset, tail_lines, grep}. - None:
credential.*are admin methods, not reachable onapi@, and no tool result contains a value.
- Durga's client sends a frame whose 4-byte prefix is
00 10 00 00. What happens, and what has central allocated by then? - Why does an
enrollconnection have a 30 s lifetime and exactly one channel? - What is different about how the runner returns its result on
exec@mirafleetcompared with how central answers onapi@mirafleet? - A registration code is shown with
seconds_left = 2. Kalyan copies it, but it takes kalyan 5 seconds to paste. What does kalyan see, and what should they do? - Which of these requests is accepted by a v1 server: (a)
{"v":1,"id":"x","method":"hello","extra":1}, (b){"v":1,"id":"x","method":"hello"}, (c){"id":"x","method":"hello"}? - kalyan sends
workspace.execfor durga's workspace id, withstdin: trueand a 1 MiB body frame already queued behind the request. What does kalyan get back, and how much did central buffer? - A client writes a 3 MiB file with
workspace.write_file. How, and what does each call carry? - Why does a workspace runner reject a
workspace@channel before accepting it when it is full? - A model calls
execwith{"Confirm":"prod","command":"ls"}. What happens and why does the server care about the capital C? - A tool call fails. Which two things are different about the result compared with a success?
- A 40 MiB log file sits in the workspace. How does the model read all of it, and what does each reply carry?
- durga's agent sends
gui.reset_adminonapi@mirafleet. What happens, and why does the GUI itself not offer the same button? - Why does
POST /runners/dev/build-1/revokeanswer303instead of showing the result, and which two routes break that rule? - Central is at level 6. Which of these peers does it accept: a runner at 7, at 6, at 5, at 4, or a runner that sends no level? What does the refused runner at 7 read, and who upgrades?
- Why is the level the minor version in 0.x, and what happens when a 0.6 runner meets a 1.x central?
Answers
-
0x00100000is 1 048 576 (1 MiB), which is above the 64 KiB request limit.ReadFramereturnsErrFrameTooLargeafter reading only the 4 header bytes; central has allocated nothing for the payload, repliestoo_large, and reads no more. - Anyone can reach the
enrollrole (it accepts any key), so it is kept as cheap and harmless as possible: one credential check, then close. The deadline stops idle connections from holding resources, and the one-channel rule stops a connection from retrying credentials in a loop. (Rate limits apply too.) - The runner writes a single JSON document with no length prefix and ends it with
end-of-stream (
CloseWrite); central reads until EOF with a size cap. Onapi@mirafleetevery message is a length-prefixed frame and there is exactly one request frame and one response frame. - The code is only valid within its own 60 s step, so the step has ended and central answers
unauthenticated: registration refused(the same text as for a wrong code). Kalyan runsmirafleet central operator codeagain and registers promptly. - Only (b). (a) has an unknown field, so it is
bad_request. (c) has nov, so it isbad_request"missing or invalid protocol version". -
not_found, the same answer as for an id that does not exist. Central read only the 64 KiB-bounded request frame: the ownership check runs before the lazy body reader is touched, so the queued body is never read (the channel closes after the reply). - In three calls of at most 1 MiB each,
lengthandsha256set per chunk: the first withtruncate: true, offset: 0, the next withoffset: 1048576and2097152. Each call carries one JSON request frame plus one body frame of exactlylengthbytes. - Once it has accepted, the only way to say "busy" is inside the channel, after the caller has
already streamed up to 1 MiB of body. Rejecting first (
ResourceShortage) costs nothing, and it lets central seerunner busyand try another runner for anopen. -
DecodeArgsrefuses it:bad_request,unknown or mis-cased argument "Confirm", and nothing reaches central.encoding/jsonwould have accepted the capital letter, but the Claude Code hook looks for the exact keyconfirmto show its "ask the user" prompt. A mis-cased key would setconfirmon the server while the hook saw nothing. -
isErroristrue, and there is nostructuredContent: only one text item,{"error":{"code","message"}}. Without the second part, a client that validates results againstoutputSchemawould reject the error for lacking the success fields. - In pages: call
read_filewithpath, readcontentandnext_offset, then call again withoffsetset tonext_offsetuntileofis true. A page is at most the output cap by default (30 KiB) and at most 1 MiB withlimit. Each reply hasoffset,length,size,eof,sha256of the page, andsanitizedif the text was cleaned. (Forty MiB in 1 MiB pages is forty calls; in practice the model shouldexecsomething likegreportailinstead.) - Admin methods in
internal/api.IsAdminMethodare refused onapi@mirafleet, so the agent'sgui.reset_admingetsforbiddenand nothing changes. The GUI has no button for it either, by design:gui.BackendleavesResetGUIAdminout, so a stolen browser session cannot mint a new setup token. Recovery needs a shell on the central host. - After a
303the browser fetches a page with GET, so pressing reload repeats the harmless GET, not the revoke (post-redirect-get). The exceptions arePOST /tokensandPOST /operators/code, which render the secret they show once, withno-store. - It accepts 6 and 5. It refuses 7 ("central is protocol 6, this runner is 7: upgrade central first", so central is upgraded, not the runner), 4 ("... needs 5 or 6: upgrade mirafleet on that runner") and a missing level (level 0, always refused).
- In 0.x semantic versioning promises nothing between minors, so each minor may change the
wire format; from 1.0 only a major may. The level restarts at 1 at v1.0, so
CheckVersionsrefuses any 0.x/1.x mix withMixedMajorMessagebefore comparing numbers. Everything must be upgraded to 1.x, central first.
- 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 03a5594; edit there.