OmpOS · Architecture

3 min read

OmpOS implementation record

This page records what was actually implemented and proven on 2026-09-27, run 59a29f4c. The initial architecture is live as published; this record adds the measured result.

What exists today

  • Read-only shell web/ (native HTML/CSS/JS, no new packages): seven real panels — Seats, Chat, Memory, Knowledge, Judge, Skills, Ledger — with per-panel provenance (source + checked time), distinct ok/empty/blocked/error states, keyboard panel switching (digits 1–7), 390 px and 1280 px layouts with no settled horizontal overflow.
  • Backend server.py + ompos/ (Python standard library only), deployed as systemd unit ompos.service:
    • Loopback TCP 127.0.0.1:51980 serves only the shell allowlist and /health; every /api request is refused 401 even with forged Remote-User.
    • Private API on Unix socket runtime/ompos.sock (0660, group www-data); Linux SO_PEERCRED requires peer UID www-data, then exactly one validated Remote-User. Wrong peer, missing, duplicate, or malformed identity → 401.
    • All six mutation flags are false server-side; direct mutating calls return 403 (POST /api/chat returns the exact dependency-blocked 503).
  • Adapters (all read-only, fixed origins, no arbitrary URL APIs): seats (omp collab list --json, view-only --view links with generation checks and host-local scope labeling), knowledge (full admitted fleet census), skills (native metadata catalog with precedence), judge (Laya health + source-attributed capabilities), ledger (fail-closed), memory (fail-closed before any store access).

Verified smoke results (2026-09-27)

  • Fleet census knowledge('Authelia'): tenants 61, admitted 57, exclusions 4, private companions 32; all 57 sources attempted individually; 23 deny anonymous index fetch (HTTP 302 to Authelia) recorded as explicit per-source errors; 630 pages indexed; 66 matches. No silent sampling.
  • Skills: 198 installed, query design → 31 matches, 2 precedence collisions surfaced, 0 errors.
  • Judge: http://127.0.0.1:51961/health → ok, device cpu, loaded typed-decisions, multilingual, english; capabilities carry file:line provenance and are not invoked.
  • Ledger: blocked, records []. The authorized candidate /srv/flow/loco-cockpit-data is not readable by the service (PermissionError); no authoritative current export exists. Historical handoffs are not promoted to a live feed.
  • Memory: blocked before any database access — no authoritative identity→project/bank ACL exists; native recall can create/migrate stores and update counters, so it is not used.
  • Chat: exact blocker rendered — SiteKits’ <omp-chat-bubble> is planned, not implemented (SiteKits stnl setup documentation, component contract section); no composer is fabricated and zero provider children launch.
  • Seats: 6 live hosts rendered from the exhaustive allowlist (instanceId, model, cwd, relayConnected, participants, busy, sessionName, pid, startedAt); view links verified access: view, host-loopback relay origin, generation-checked, never logged.

Transport and identity design

  • Intended production path: Authelia one-factor edge overwrites Remote-User; nginx proxies to the Unix socket; the socket additionally requires the www-data peer UID. No Authelia rule for OmpOS exists yet (default policy bypass), and no exclusive shared-configuration writer window was available during this run, so the public app vhost deliberately returns 503 instead of pretending to be protected. Zero shared Authelia changes were made.
  • Browser panel verification used a loopback diagnostic bridge that forwards real Unix-socket responses under the synthetic principal ompos-verification. That is an integration proof, not an authenticated production route or a real human login.

Operational limits observed

  • Native collab list/link perform best-effort registry housekeeping (published 18.3.2 source, registry.ts:609-768). The service runs with ProtectSystem=strict, ProtectHome=read-only and only runtime/ + catalogs/ writable; the native adapter additionally refuses execution unless the registry mount verifies read-only (ST_RDONLY), so listing cannot prune shared state.
  • One upstream robustness fix was required during smoke: an out-of-range page timestamp in an admitted index could abort the whole knowledge snapshot; it is now contained per record.
  • No provider calls were made. No new packages. Bootstrap rollback: commit 48223ce0.

See gaps for everything that remains blocked and why.