Container details now carry the image id and the HostConfig resource limits
(CPU cores and shares, memory and swap bytes, pids, device requests) plus sandbox flags
(privileged, read-only rootfs, network mode, restart policy), with null meaning unlimited. A new
GET /api/v1/docker/containers/{name}/stats returns one live sample: CPU percent
of one core, memory working set, processes, block IO and network bytes. Peers
proxy the new route.
Env, labels, command lines and mounts are deliberately excluded from the payload.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
11 KiB
REST and MCP reference
Full endpoint and MCP client reference. Everyday usage is in operations.md; the design is in ARCHITECTURE.md.
Generated reference (OpenAPI)
openapi.json is a committed OpenAPI 3.1 description of everything this binary serves: every REST route with its parameters and response schemas, the error shape, the MCP endpoint (POST, the standalone GET stream and the session DELETE), and an x-mcp-tools extension listing each MCP tool with the description and input JSON Schema the tool router reports (eight tools, or ten with [peers] enabled = true). tests/openapi.rs keeps it true: it fails if a route of the real router is undocumented, if a tool is missing from x-mcp-tools, or if the file is stale.
GET /api/v1/openapi.jsonreturns the document for the running instance, behind the same bearer token as the rest of/api/v1. Peer routes appear only when peers are enabled.GET /docsrenders it with Redoc. The page (/docs) and the Redoc 2.5.4 bundle (/docs/redoc.standalone.js, embedded in the binary) are public, static and hold no host data; the page asks for a bearer token, keeps it insessionStorageand sends it only toGET /api/v1/openapi.json, so the spec itself stays behind auth. With[auth] enabled = falseit loads without asking. The page answers with a strictContent-Security-Policy(no external origins), so nothing is fetched from a CDN. Redoc shows REST operations; the MCP tools inx-mcp-toolsare in the JSON, not in the rendered page.slinuxm openapi [--peers]prints the same document offline: no config file, no token, no server, no port.--peersdescribes a consolidator; without it you get the peer-less instance.- Regenerate after changing a route, a tool, a response type or the crate version:
cargo run -- openapi --peers > docs/openapi.json
REST
Base: http://127.0.0.1:1984. Errors are {"error":{"code","message"}}.
| Route | Notes |
|---|---|
GET /healthz |
public, {"status":"ok","version":...}, version is the build stamp YYYY.MM.DD-<branch>-<sha> |
GET /docs, GET /docs/redoc.standalone.js |
public static Redoc viewer for the OpenAPI document, see Generated reference |
GET /api/v1/systemd/units?state=failed |
state is an active state (failed, active, ...) |
GET /api/v1/systemd/units/{name} |
one unit with details; read-only, so only units systemd has loaded (unloaded or unknown is 404) |
GET /api/v1/systemd/timers |
|
GET /api/v1/journal?unit=&priority=err&lines=100 |
priority by name or number |
GET /api/v1/journal/follow?unit=&priority= |
SSE, event journal |
GET /api/v1/docker/ps |
503 when Docker is unavailable |
GET /api/v1/docker/containers/{name} |
limits and sandbox flags (resources), image_id; never env, labels or commands |
GET /api/v1/docker/containers/{name}/stats |
one live sample: CPU percent, memory, pids, block IO, network |
GET /api/v1/docker/containers/{name}/logs?tail=&since=&follow=0|1 |
JSON, or SSE with events stdout/stderr |
GET /api/v1/peers |
consolidator only; sorted status list; absent when peers are disabled |
GET /api/v1/peers/{peer} |
one peer's status object; unknown name is 404 |
GET /api/v1/peers/{peer}/... |
GET-only pass-through of that peer's documented routes |
GET /api/v1/openapi.json |
this document, OpenAPI 3.1 (see Generated reference) |
TOKEN=slinuxm_...
curl -H "Authorization: Bearer $TOKEN" 'http://127.0.0.1:1984/api/v1/systemd/units?state=failed'
curl -N -H "Authorization: Bearer $TOKEN" 'http://127.0.0.1:1984/api/v1/journal/follow?priority=err'
Peers
Present only when [peers] enabled = true. The same inbound token as the rest of /api/v1 is required. GET /api/v1/peers returns {"peers":[...]} sorted by name, including disabled peers. GET /api/v1/peers/{peer} returns one object, not wrapped:
{
"name": "beta",
"enabled": true,
"url": "http://beta:1984",
"server": {
"up": true,
"since": "2026-10-19T10:00:00Z",
"last_checked": "2026-10-19T10:00:09Z",
"last_error": null,
"latency_ms": 1
},
"api": {
"up": true,
"since": "2026-10-19T10:00:00Z",
"last_checked": "2026-10-19T10:00:05Z",
"last_error": null,
"latency_ms": 7,
"auth": "ok",
"peer_version": "0.1.0"
}
}
server is the TCP check and api is the authenticated ping. auth is ok, rejected or unknown. Before the first check, up is false, auth is unknown and the timestamps are null. An unknown name is 404 {"error":{"code":"not_found","message":"peer <name>: unknown peer"}}.
GET /api/v1/peers/{peer}/{path} forwards a GET to that peer and returns the peer's status and body. The path has to be one of the documented read routes: systemd/units, systemd/units/{name}, systemd/timers, journal, journal/follow, docker/ps, docker/containers/{name}, docker/containers/{name}/stats, docker/containers/{name}/logs. ping and peers/... are not forwarded. systemd/units/{name} accepts exactly what the local route accepts, including escaped names (mnt-data\x2dbackup.mount, sent as %5C) and -.mount. .., encoded slashes, NUL/CRLF, a second encoding layer and any other path are 400 peer <name>: path not allowed. Query keys are the same ones the local route accepts (state, unit, priority, lines, since, all, tail, follow); anything else is 400 peer <name>: unsupported query parameter. The unit value is checked with the same unit-name rule as systemd/units/{name}, so escaped names work as both %5C and a literal backslash (/api/v1/peers/beta/journal?unit=mnt-data%5Cx2dbackup.mount). The caller's Authorization and Cookie are not forwarded; the consolidator sends the peer's own token.
A request that already has x-slinuxm-hop is 400 peer <name>: chained requests are not allowed. Other methods are 405. journal/follow and docker logs with follow=1 are text/event-stream with Cache-Control: no-cache, like the local follow routes, cut off at limits.max_follow_secs or shutdown. Bodies larger than peers.max_response_bytes are 503 peer <name>: oversize. Only 2xx from the peer is passed through; any other status becomes the section 4 error for that peer (a peer 404 is 404 not_found, a peer 401/403 is 503 peer rejected credentials, anything else is 503 http_<code>), so a redirect or the peer's own error body never reaches the caller.
Every proxied response for a configured peer, including the consolidator's own errors (400, 404, 500, 503), carries x-slinuxm-peer: <name>. A request for an unknown or malformed peer name is 404 with no peer header: it did not come from a peer.
A peer failure never becomes 401: a peer refusing the consolidator's token is 503 peer <name>: peer rejected credentials, so the caller does not re-authenticate against the wrong host.
curl -H "Authorization: Bearer $TOKEN" 'http://127.0.0.1:1984/api/v1/peers/beta/systemd/units?state=failed'
MCP
Endpoint: http://127.0.0.1:1984/mcp (Streamable HTTP). POST /mcp carries the JSON-RPC messages; the default session mode also serves GET /mcp (standalone text/event-stream for server-to-client messages) and DELETE /mcp (end the session named by Mcp-Session-Id; 202 on success). Eight tools (list_systemd_units, get_systemd_unit, list_systemd_timers, get_journal_logs, tail_journal, list_containers, get_container, get_container_logs), two prompts (diagnose_unit, container_health_report) two resources (systemd://units/failed, docker://containers) and two resource templates (systemd://unit/{name}, docker://container/{name}, same JSON as get_systemd_unit and get_container; percent-encode unusual characters in the name). Log content is untrusted data and is labelled as such in tool results.
Generic client config (header-capable clients):
{
"mcpServers": {
"linux-tracker": {
"url": "http://127.0.0.1:1984/mcp",
"headers": { "Authorization": "Bearer slinuxm_..." }
}
}
}
Claude Code: claude mcp add --transport http linux-tracker http://127.0.0.1:1984/mcp --header "Authorization: Bearer $TOKEN".
Inspector: npx @modelcontextprotocol/inspector, transport Streamable HTTP, add the bearer header.
Raw handshake with curl:
curl -si -X POST http://127.0.0.1:1984/mcp \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
Origin and Host checks
/mcp validates Origin and Host to defend against DNS rebinding from browsers. Loopback names, server.bind and the configured port are accepted by default. Requests without an Origin header (non-browser clients) pass this check, so the bearer token remains the real gate. If you bind to 0.0.0.0 or serve behind a name, add the names clients use to server.allowed_hosts (for example ["monitor.lan:1984"]) and any browser origins to server.allowed_origins. With auth.enabled = false (loopback only), REST requests are checked against a Host allowlist (loopback names, server.bind and server.allowed_hosts) and get 403 otherwise, to blunt DNS rebinding. There is no Origin check on REST and no token in that mode, so keep auth enabled on any multi-user host. If the host is reachable beyond a trusted network, enable native TLS (see tls.md) or terminate TLS in a reverse proxy.