Fleet API & MCP

Reference for the /api/fleet/* REST endpoints and the fleet-aware MCP tools. See Fleet commands for the concepts (targeting precedence, the long-poll model, consent) behind these — this page is the exact shapes.

Base URL: http://127.0.0.1:42031/api/fleet

Auth

Same model as the rest of the local API: unauthenticated on localhost, bearer token only once Expose on local network is on. See Overview & auth.

REST endpoint summary

Method	Path	Purpose
GET	/api/fleet/machines	List the machine roster (self + any paired peers)
GET	/api/fleet/terminals	List the fleet terminal roster (local + remote terminals)
POST	/api/fleet/execute	Run a command locally or on a paired machine
POST	/api/fleet/screen	Read a live screen snapshot, local or remote
POST	/api/fleet/close	Close a local or remote terminal

Peering not installed

GET /api/fleet/machines never returns 501 — without the peering component it still returns just self. Every other endpoint returns 501 { "error": "peering not installed" } when a request targets a remote machine and peering isn't installed.

---

List machines

GET /api/fleet/machines

Returns the machine roster: always includes self, plus one entry per paired peer when peering is present.

Response

{
  "machines": [
    { "machineId": "self",     "deviceName": "win-dev-box",    "os": "windows", "online": true, "self": true },
    { "machineId": "mac-mini", "deviceName": "mac-mini-studio", "os": "macos",   "online": true, "self": false }
  ]
}

curl http://127.0.0.1:42031/api/fleet/machines

---

List terminals

GET /api/fleet/terminals

Returns the fleet terminal roster — every terminal visible across local and paired machines, each tagged with where it lives.

Response

{
  "terminals": [
    { "id": "term_a1b2", "title": "build", "running": true, "machineId": "self",     "os": "windows", "deviceName": "win-dev-box" },
    { "id": "term_9f2a", "title": "Fleet: win-dev-box", "running": true, "machineId": "mac-mini", "os": "macos", "deviceName": "mac-mini-studio" }
  ]
}

curl http://127.0.0.1:42031/api/fleet/terminals

---

Execute a command

POST /api/fleet/execute

Runs a command locally or on a paired machine, following the targeting precedence terminalId → machineId → targetOS → local. This is a long-poll call — see the execution model.

Body parameters

Field	Type	Required	Notes
command	string	Yes	The command to run.
targetOS	windows | macos | linux	No	Routes to the unique online peer running that OS.
machineId	string	No	Routes to a specific paired machine.
terminalId	string	No	Routes to that exact terminal (local or remote).
timeoutMs	number	No	Clamped to [1000, 3600000]. Default 60000.

Response

{
  "machineId": "mac-mini",
  "terminalId": "term_9f2a",
  "deviceName": "mac-mini-studio",
  "done": false,
  "exitCode": null,
  "screen": "…compiling module 214/300…"
}

Errors

Status	Body	When
501	{ "error": "peering not installed" }	Request targets a remote machine and the peering component isn't installed
409	{ "error": "ambiguous target", "candidates": [...], "machines": [...] }	targetOS matches more than one online peer
404	{ "error": "no match", "machines": [...] }	targetOS matches no online peer

Example

curl -X POST http://127.0.0.1:42031/api/fleet/execute \
  -H "Content-Type: application/json" \
  -d '{ "targetOS": "macos", "command": "bun run build", "timeoutMs": 120000 }'

---

Read a live screen

POST /api/fleet/screen

Returns a live screen snapshot of a local or remote terminal — the preferred way to observe an in-flight Fleet command. See Watching progress.

Body parameters

Field	Type	Required	Notes
terminalId	string	Yes	Terminal to read.
machineId	string	No	Omit for a local terminal.

Response

{
  "machineId": "mac-mini",
  "terminalId": "term_9f2a",
  "title": "Fleet: win-dev-box",
  "running": true,
  "screen": "…compiling module 289/300…"
}

curl -X POST http://127.0.0.1:42031/api/fleet/screen \
  -H "Content-Type: application/json" \
  -d '{ "machineId": "mac-mini", "terminalId": "term_9f2a" }'

---

Close a terminal

POST /api/fleet/close

Closes a local or remote terminal.

Body parameters

Field	Type	Required	Notes
terminalId	string	Yes	Terminal to close.
machineId	string	No	Omit for a local terminal.

Response

{ "machineId": "mac-mini", "terminalId": "term_9f2a", "status": "ok" }

curl -X POST http://127.0.0.1:42031/api/fleet/close \
  -H "Content-Type: application/json" \
  -d '{ "machineId": "mac-mini", "terminalId": "term_9f2a" }'

---

Fleet-aware MCP tools

The built-in MCP server (auto-terminal-mcp, http://127.0.0.1:42032/mcp) exposes Fleet through the same tool set agents already use — two new tools, plus fleet-aware changes to two existing ones. See MCP Tools for the full tool reference and the server's other conventions (the "me" shorthand, transport, auth).

Tool	Change
execute_command	terminalId is now optional; gains optional targetOS, machineId, timeoutMs. Omitting terminalId while supplying targetOS or machineId routes the command across the fleet instead of the existing local path.
list_terminals	Now returns the fleet roster — each entry tagged { id, title, running, machineId, os, deviceName } — instead of only local terminals.
list_machines	New. No required parameters. Returns the machine roster: { machineId, deviceName, os, online, self }[]. Always includes self.
get_terminal_screen	New. Parameters: machineId (optional), terminalId (required). Returns the live screen of a local or peer terminal: { machineId, terminalId, title, running, screen }.

{
  "name": "execute_command",
  "arguments": { "targetOS": "macos", "command": "bun run build", "timeoutMs": 120000 }
}

{ "name": "list_machines", "arguments": {} }

{
  "name": "get_terminal_screen",
  "arguments": { "machineId": "mac-mini", "terminalId": "term_9f2a" }
}

Next steps

• Fleet commands — the concepts and worked example behind these calls.
• MCP Tools — the complete tool reference, including the tools Fleet doesn't change.