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 today; VPS = BLK-12)
   server.ts → runTurn → engine registry →  oma            (opencode serve, gated, default)
        │     fallback chain: oma → aider → router-direct
        │                                  aider           (LiteLLM, edits via git diff)
        │                                  router-direct   (1 call, WRITE_FILE)  ← actually runs in deploy
        │
        ├─ KEY-INJECTION PROXY  (Invariant 6):  strip inbound auth → inject the real router Bearer
        │      the sandbox gets ONLY the proxy URL + a non-secret token — never a provider 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 (default) / E2B       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 forced · runner 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, parses WRITE_FILE blocks, writes the files; 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. All execution is the managed sandbox; no engine spins up its own. (Host engines are fail-closed off until exec co-location ships.)
• Engine ⊥ model ⊥ memory. The engine is a registry plugin, the model is the router's job, cross-engine continuity is a small summary-handoff.
• Isolated state. Only the Supabase project gsuafvvzsdfkfybgfzjv; RLS is forced 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.