BOS-X — Architecture

The system at a glance

 SURFACE  (buildless SPA)        x.dev.bos.pro · Cloudflare Pages, also served by the runner
   built-apps rail │ chat + SSE transcript │ live preview iframe (sandboxed, no same-origin)
        │
        │   POST /api/run (SSE)   +   GET /api/* (apps · messages · models · health)
        ▼
 RUNNER  (one Node/TS service)   x-runner.bos.pro · durable CF tunnel  (laptop + Colima; VPS = BLK-12)
   server.ts → runTurn → engine registry → oma · aider · router-direct
        │     fallback chain: oma → aider → router-direct   (router-direct actually runs in deploy)
        │
        ├─ KEY-INJECTION PROXY  (Invariant 6):  injects the real router key — sandbox gets only a proxy URL + token, never a key
        │
        └─ durable builds:  runner/built-apps/{app_id}/  →  GET /apps/{app_id}/*  (survives sandbox reaping)
             │                            │                              │
             ▼                            ▼                              ▼
   SUPABASE (isolated)          MANAGED SANDBOX               MODEL ROUTER (read-only)
   gsuafvvzsdfkfybgfzjv         Daytona (wired default)       rundev.cloved.ai/v1
   apps · messages ·            build → preview               bos:* aliases · provider failover
   model_runs · engine_sessions egress allowlist + proxy      no /v1/models · no streaming
   RLS on · runner-only writes  URL only (Invariant 6)        (proxy de-streams)
          

Components

Request flow — chat → live app

1. The Surface POSTs {prompt, model, engine_ref?, session_id, app_id?} to /api/run and opens an SSE stream.
2. The runner mints run-<id>, validates the model against a server-side allowlist, mints/reuses app-<id>, and emits meta{app_id}.
3. It provisions a managed sandbox via sandboxedSpec() — which asserts Invariant 6: the sandbox env carries the proxy URL + a token, never a provider key.
4. It persists the user turn to messages, loads any follow-up history + existing files, then runs the engine (fallback oma→aider→router-direct).
5. The engine calls the model through the router and applies its file edits (router-direct parses WRITE_FILE blocks; aider derives them from git diff); every step streams to the Surface as engine_event.
6. On success the files are persisted durably to runner/built-apps/{app_id}/ and the runner emits preview{url = /apps/{app_id}/} — a runner-served URL that survives the sandbox being torn down.
7. The build is recorded in apps, the assistant turn in messages, and every attempt (success/fail) in model_runs; done{status} closes the stream.
8. The Surface loads the preview URL into the sandboxed iframe (no allow-same-origin — generated apps are untrusted).

Invariants & trust boundaries

• Invariant 6 — one egress authority. The runner holds the real model-router key; the sandbox never does. The key-injection proxy is the only hop that adds it.
• One sandbox adapter. Managed engines (oma/aider) run code only in the sandbox and are fail-closed by default (the host-engine co-location guard) until exec is co-located into the sandbox; the live fallback (router-direct) makes one model call and writes the generated files on the trusted runner, which serves the durable preview at /apps/{app_id}/.
• Engine ⊥ model ⊥ memory. The engine is a registry plugin, the model is the router's job, and cross-engine continuity is designed as a small summary-handoff (the store is still a stub).
• Isolated state. Only the Supabase project gsuafvvzsdfkfybgfzjv; RLS is enabled (forced on engine_sessions) and every write is runner-only (service-role, host-checked).
• Untrusted preview. The preview iframe deliberately omits allow-same-origin so a generated app can't read the parent/runner origin.