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

6.2 KiB

REST and MCP reference

Full endpoint and MCP client reference. The short version is in the README; the design is in ARCHITECTURE.md.

REST

Base: http://127.0.0.1:1984. Errors are {"error":{"code","message"}}.

Route Notes
GET /healthz public, {"status":"ok","version":...}
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
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. .., encoded slashes 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 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, cut off at limits.max_follow_secs or shutdown. Bodies larger than peers.max_response_bytes are 503 peer <name>: oversize.

Every proxied response, including the consolidator's own errors for that peer (400, 404, 500, 503), carries x-slinuxm-peer: <name>.

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). 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.