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>
24 KiB
TODO — skyg-linux-tracker
The single place for work tracking. Tick boxes here only. Design lives in ARCHITECTURE.md. Archived workstream design notes and logs are in docs/workstreams/. Plans for the next big thing go in plan/.
Last updated: 2026-10-21
Status
The build is functionally complete and merged to main. REST, MCP, OTel, TLS and the NixOS module are implemented. Verification #1–#4 and #6 passed live on minipc1 (2026-10-19). The WS-H nix gate passed on 2026-10-19. Phase 5 (consolidator, optional peers) and the generated OpenAPI doc are merged, and the binary serves it as a Redoc page at /docs (DEC-16); the Phase 5 record is archived in docs/workstreams/P5-consolidator/. Everything open is in the Backlog.
| Milestone | Gate | Status |
|---|---|---|
| M0 Skeleton | slinuxm serve --print-config works. Clippy and tests are clean. No openssl. |
Done |
| M1 Sources live | All four Phase 1 examples run against a real host | Done (systemd, journal, docker verified live) |
| M2 Surfaces | Verification #3, #4 and #5 pass | Partial: #3 and #4 pass live (minipc1, 2026-10-19, all 8 MCP tools); #5 OTel deferred to I6-5 (collector on minipc1 is down) |
| M3 Release | Verification #1–#6 pass. Unit file and README shipped. | Partial: #1–#4 and #6 pass, unit installed on minipc1; needs #5 (I6-5) |
| M4 NixOS | nix flake check passes including the VM test. :1984 serves and a token is minted with the system-installed CLI. |
✅ 2026-10-19: nix build and nix flake check (incl. VM test, plain + TLS) pass; see WS-H log |
| M5 TLS | HTTPS serves REST and /mcp, SIGHUP reloads certs, no openssl. |
Done |
| M6 Consolidator | Phase 5 exit criteria; peer-less instance unchanged (8 MCP tools); nix flake check incl. the peers VM test |
Met, except two live checks still open: P5-1 minipc1 cross-check needs a user-minted token, P5-2 OTel peer-gauge check via devenv up not yet recorded (both in the Backlog) |
In progress / Review
| Item | Owner | State |
|---|---|---|
| C-8 container limits and live stats | hermenix | PR open: feat/container-details |
- WS-H Gate:
nix buildandnix flake checkpass.lddshows no openssl. A fresh NixOS host serves:1984and a token can be minted from a login shell. - V-1 Build-stamped version
YYYY.MM.DD-<branch>-<sha>in--version,/healthz,/api/v1/ping, MCP server info and OTelservice.version(DEC-17).dev-test lint,cargo test,nix buildand both VM tests (vm,vm peers) pass. - DOC-3 User docs restructured into a guide: slim
README.md, plusdocs/how-it-works.md,docs/install.md(Nix and NixOS first; the systemd unit is an example for manual installs),docs/configuration.md,docs/operations.mdanddocs/development.md. The example unit gainsExecReload(SIGHUP), matching the module. markdownlint and link check pass.
Backlog
Parked, not scheduled. Each has a reason. Nothing here blocks the current work. Tick here when picked up and finished.
| ID | Item | Reason parked |
|---|---|---|
| C7 | (optional) Smoke test against the Podman socket (WS-C) | Nice-to-have; no Podman host in use |
| I6-5 | Verification #5: OTel smoke test end to end (P3) | Waiting on the minipc1 collector fix (X-1); slinuxm itself exports fine |
| B-1 | Live check of docker log-follow SSE (/docker/containers/{name}/logs?follow=1) |
Not exercised in the live runs so far |
| B-2 | Live check of REST, bearer auth and TLS against minipc1 | The MCP-tool run did not cover them |
| X-1 | (external) Investigate failed opentelemetry-collector.service and var-lib-loki.mount on minipc1 |
Outside this repo; blocks I6-5 |
| F-1 | Cap concurrent follow streams | Security review 2026-10-16; not scheduled |
| F-2 | Bound line and message length | Security review 2026-10-16; not scheduled |
| F-3 | Unit hardening extras | Security review 2026-10-16; needs a clean-host test first |
| P5-1 | minipc1 cross-check of the consolidator against a real peer | Needs a read-only token minted by the user on minipc1; agents never mint tokens on real hosts |
| P5-2 | Record the OTel peer-gauge check (devenv up, Verification step 5 with peers) |
Not yet run and recorded; no automated test asserts the exported peer metrics end to end |
| D8 | Fleet aggregation (merged views across peers) | Out of scope for v1 (DEC-14: no aggregation, no chaining); needs a design for partial failure and ordering |
| P5-3 | Scoped tokens (per-peer or read-class scopes) | Any valid inbound token may read peer data (DEC-14); scopes need a token schema change and a policy decision |
| P5-4 | Peer health history | State is in memory only by design; history needs storage or an external TSDB, and the OTel gauges already cover it |
| P5-5 | Runtime peer management (add/remove without editing config) | Peers are declarative so no write path or DB table exists (DEC-14); would need a write path against the read-only rule |
| DOC-1 | Show the MCP tools (x-mcp-tools) in the Redoc page |
Redoc renders REST operations only; needs the tool list generated into a tag description (or a section) in openapi.rs, which changes the spec |
| DOC-2 | Config switch to turn the /docs viewer off |
Static, public and data-free (DEC-16), so not needed yet; adds a config key, README and config.example.toml entries |
| V-2 | Real branch name in Nix builds (stamp says nix) |
A flake does not expose its branch; needs CI to pass it to callPackage or a release-tag convention |
- C7 (nice-to-have) Smoke test against the Podman socket
- I6-5 Verification #5 OTel smoke test against a working collector (see the verification checklist)
- B-1 Docker log-follow SSE live check
- B-2 REST, auth and TLS live check against minipc1
- X-1 (external) Fix or investigate
opentelemetry-collector.service/var-lib-loki.mounton minipc1 - P5-1 minipc1 cross-check: run a consolidator against minipc1 with a read-only token the user mints there (
list_peers,get_peer, one pass-through) - P5-2 OTel peer gauges: run
devenv up, enable[otel]with peers, confirmpeer.up,peer.api.auth_ok,peer.check.duration_seconds,peer.last_change_timestamp_secondsreach the collector, and record the result - D8 Fleet aggregation across peers
- P5-3 Scoped tokens
- P5-4 Peer health history
- P5-5 Runtime peer management
- DOC-1 MCP tools in the Redoc page
- DOC-2 Config switch for the
/docsviewer - V-2 Real branch name in Nix builds instead of the
nixplaceholder - F-1 Cap concurrent follow streams. Each journal follow,
tail_journalcall or docker follow pins aspawn_blockingthread for up tolimits.max_follow_secs. Add a global semaphore shared by REST and MCP (suggested 16) returning 429/503 when full. A client that stops reading may hold the thread past the deadline (untested); add a write timeout or a hardtokio::time::timeoutaround the producer. - F-2 Bound line and message length. Docker
LineSplitterand journalMESSAGEare buffered without limit before the 256 KiB result cap applies. Truncate per line (suggested 64 KiB, with a visible marker) and cap total bytes collected. - F-3 Unit hardening:
ProtectKernelLogs,ProtectHostname,RemoveIPC,LimitNOFILE,TasksMax,MemoryMax, narrowerRestrictAddressFamilies,PrivateUsers(check journal group access). Test under the hardened unit on a clean host before enabling. Document how the service user gets read access to the TLS key.
Completed workstreams
Design notes, owned files and logs for each are archived under docs/workstreams/. Task IDs below are stable references.
| ID | What | Key outcome | Tasks | Completed |
|---|---|---|---|---|
| P0 | Foundation: devenv, Cargo, config, DTOs, source traits + fakes, errors, AppState, stubs |
serve --print-config works; build, clippy, fmt, test clean; cargo tree -i openssl empty |
P0-1..P0-11, Gate | merged to main |
| WS-A | systemd source (zbus) | Units, timers (via *.timer + Timer props), read-only GetUnit status |
A1..A7 | merged to main |
| WS-B | journal source (sd-journal) | Snapshot + follow in spawn_blocking; follow thread exits on receiver drop |
B1..B6 | merged to main |
| WS-C | docker source (bollard) | Lazy socket, bounded concurrent inspect, log streams; missing socket maps to Unavailable |
C1..C6 (C7 in Backlog) | merged to main |
| WS-D | auth + SQLite token DB | sha256 tokens, slinuxm token create, list, revoke, bearer middleware, 401 + WWW-Authenticate |
D1..D7 | merged to main |
| WS-E | REST API | All /api/v1 routes, SSE follow, /healthz, 503 on docker-only failures |
E1..E9 | merged to main |
| WS-F | MCP server | 8 tools, 2 prompts, 2 resources, instructions, Origin/Host validation | F1..F9 | merged to main |
| WS-G | OTel export | Traces, observable-gauge metrics, journal/docker log fan-out with reconcile, flush on shutdown, dev/otelcol.yaml |
G1..G7 | merged to main |
| P3 | Integration and hardening | One axum server, negative tests, hardened unit, README; I6 verified on minipc1 (#1–#4, #6) | I1..I6 (I6-5 in Backlog) | 2026-10-19 |
| WS-I | Native TLS (rustls) | server.tls.*, SIGHUP reload, HTTPS tests, live curl --cacert check |
T1..T8 | merged to main |
| WS-H | NixOS package, module, VM test | H1..H8 merged (PR #1, 34da657); gate passed 2026-10-19 |
H1..H8 | merged; gate passed 2026-10-19 |
| P5 | Consolidator: optional peers (WS-T, A..F) | Declarative peers with TCP and API health checks, /api/v1/peers status and GET pass-through, peer argument and list_peers/get_peer (10 MCP tools with peers, 8 without), four OTel gauges, NixOS module option, SSRF guard, peers VM test; peer-less instance unchanged |
T1..T7, A0..A4, B1..B5, C1..C4, D1..D3, E1..E2, F1..F4 (P5-1, P5-2 in Backlog) | 2026-10-20 |
| WS-G (OpenAPI) | Generated OpenAPI 3.1 doc (stand-alone, after P5) | utoipa paths plus schemars bridge, x-mcp-tools, GET /api/v1/openapi.json, slinuxm openapi [--peers], drift test, docs/openapi.json |
G1..G4 | 2026-10-20 |
| WS-H (final fixes) | Phase 5 final-review fixes | One token loader, one set of peer helpers, IPv4-mapped deny check, IPv6 deny_cidrs, client span kind, flaky test fixes, docs corrections |
review items | 2026-10-20 |
Done (archive)
All ticked. One line per workstream; the full task text is on each card.
- P0 — devenv scripts and libsystemd (P0-1);
Cargo.tomlwithslinuxmbin, rustls-only, LTO+strip (P0-2); API spike (P0-3); figment config withotel.headers,otel.metrics.*,limits.*and validation (P0-4);config.example.toml(P0-5); DTOs with serde/schemars (P0-6); source traits + fakes (P0-7);AppErrormapping (P0-8);AppState(P0-9); stubs andmain.rsdispatch (P0-10); config tests (P0-11); gate. - WS-A — bus connection (A1);
list_units(A2);list_timers(A3);unit_statusviaGetUnit(A4); name validation,NoSuchUnitto NotFound (A5);examples/systemd_dump.rs(A6); mapping tests (A7). - WS-B —
spawn_blockingaccess (B1);query(B2);follow(B3); lossy UTF-8 mapping (B4);examples/journal_tail.rs(B5); follow-exit test (B6). - WS-C — lazy bollard client (C1);
ps(C2);container_status(C3);logsstream (C4);tailcap (C5);examples/docker_ps.rs(C6). - WS-D —
db.rsopen-or-create, WAL (D1); tokens migration (D2); token CRUD (D3); CLI (D4); bearer middleware (D5); protected-router layer,/healthzpublic (D6); tests (D7). - WS-E — router with
{name}syntax (E1); systemd routes (E2); journal snapshot (E3); journal SSE (E4); docker routes (E5);/healthz(E6); JSON errors (E7); handler tests (E8); docker 503 (E9). - WS-F —
TrackerService, 8 tools (F1);tail_journalcap (F2);get_container_logscap (F3);get_infoinstructions (F4); tool descriptions (F5); prompts (F6); resources (F7);mcp::servicewith Origin validation (F8); tests (F9). - WS-G —
telemetry::init(G1); tracing subscriber (G2); snapshot + observable gauges (G3); metric set and allowlists (G4); log export with reconcile (G5); shutdown flush (G6);dev/otelcol.yaml(G7). - P3 — serve wiring and shutdown (I1); negative tests (I2); systemd unit, verified with
systemd-analyze security --offline(1.5 OK) and installed as a system unit on minipc1, 2026-10-19 (I3); README (I4); release build,lddclean (I5); manual Verification #1–#4 and #6 on minipc1, 2026-10-19; #5 deferred as I6-5 (I6). - WS-I —
server.tls.*config (T1); rustls with pinned provider (T2); SIGHUP reload (T3);https://MCP origins (T4); non-loopback-without-TLS warning (T5); self-signed cert tests (T6); README TLS section (T7); live check (T8). - WS-H —
nix/package.nix(H1);flake.nix(H2); module options (H3); service definition (H4); system-wide CLI with root guard (H5); firewall options and eval assertion (H6); README NixOS section (H7); VM test (H8). Gate passed 2026-10-19 (build, flake check, VM test). - P5 — runner
dev/dev-test.nuand peers VM test (WS-T); config, validation, secrets loader,peerCLI (WS-A); registry, health loops, status model, SIGHUP reload, transport with SSRF guard (WS-B); status routes, pass-through,x-slinuxm-peer, error mapping (WS-C);peerargument,list_peers/get_peer, instructions (WS-D); gauges, client spans and propagation (WS-E); NixOS module, promoted VM test,tests/peers.rs, README anddocs/consolidator.md(WS-F). - WS-G (OpenAPI) — REST spec (G1); MCP
x-mcp-tools(G2); route andslinuxm openapi(G3); drift guard anddocs/openapi.json(G4). - WS-H (final fixes) — see the record.
Early decisions (DEC-1..DEC-8) were accepted before work started; all decisions are recorded in ARCHITECTURE.md.