Files
skyg-linux-tracker/docs/api.md
T

11 KiB

REST and MCP reference

Full endpoint and MCP client reference. The short version is in the README; 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.json returns 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 /docs renders 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 in sessionStorage and sends it only to GET /api/v1/openapi.json, so the spec itself stays behind auth. With [auth] enabled = false it loads without asking. The page answers with a strict Content-Security-Policy (no external origins), so nothing is fetched from a CDN. Redoc shows REST operations; the MCP tools in x-mcp-tools are 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. --peers describes 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}
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}/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.