@mseep/open-computer-use 1.0.0

package/docs/openwebui-filter.md

@@ -0,0 +1,134 @@
+# Open WebUI Computer Use Filter
+
+## Purpose
+
+The Computer Use Filter (`openwebui/functions/computer_link_filter.py`) is the only integration point between Open WebUI and the Computer Use Server. Its `inlet()` fetches the server-baked system prompt over HTTP and injects it into the conversation when the `ai_computer_use` tool is active. Its `outlet()` decorates assistant messages that contain sandbox file URLs with a markdown preview link and an archive-download link. On patched Open WebUI builds (see Path B below) the preview link is auto-promoted to an inline artifact by the `fix_preview_url_detection` frontend patch; on stock builds it stays a one-click link — either way, the user reaches the preview SPA without a rebuild.
+
+The filter is the single source of truth for the client-side URL shape; the server owns prompt content and preview rendering. Read the file itself for the authoritative Valve defaults and behaviour.
+
+> **Heads up on prompt duplication.** The six-tier MCP-native surface (see `docs/system-prompt.md`) also writes the system prompt to `/home/assistant/README.md` and returns it on `InitializeResult.instructions`. In Open WebUI through LiteLLM, `InitializeResult.instructions` is **not** forwarded to the LLM (LiteLLM is a tool-call proxy and drops it), so the real duplication in this deployment is: filter `inlet()` injects the prompt once; the model optionally calls `view /home/assistant/README.md` if it follows the recovery-nudge in the `bash_tool` / `view` tool descriptions — that adds a second ~3–5K token copy. Worst case is two copies, not three. The nudge is kept to help pathological clients that strip the system prompt — alternatives discussed in `docs/system-prompt.md`.
+
+## Installation
+
+- Open WebUI → **Admin Panel** → **Functions** → **New Function**.
+- Paste the entire contents of `openwebui/functions/computer_link_filter.py` into the editor.
+- Save, then toggle the function on for the target model(s).
+- Optionally override any Valve from the function's settings panel. Defaults are chosen so a fresh deployment works end-to-end as soon as the Computer Use Server is reachable at `http://localhost:8081`.
+- Upstream reference: [Open WebUI Functions documentation](https://docs.openwebui.com/features/plugin/functions/).
+
+## Preview panel isn't showing — two ways to fix it
+
+![File preview panel when working](screenshots/02-file-preview.png)
+
+When the AI generates a file, the preview panel shown above should open on the right. If nothing opens, here's why — and two ways to fix it.
+
+### How the preview gets rendered
+
+The filter's `outlet()` appends a markdown link `[🖥️ Open preview]({PUBLIC_BASE_URL}/preview/{chat_id})` to every assistant message that references a sandbox file. The URL comes from the server's `PUBLIC_BASE_URL` env var — delivered to the filter via the `X-Public-Base-URL` response header on `/system-prompt` and cached alongside the prompt, so the filter never needs its own copy of the public URL.
+
+On *stock* Open WebUI the link stays a link: user clicks it, preview opens in a new tab. On *patched* Open WebUI (our `docker-compose.webui.yml` build) the `fix_preview_url_detection` patch sees `/preview/{chat_id}` in the message text and pushes a synthetic `<iframe>` artifact into the chat's `htmlGroups`. A second patch, `fix_artifacts_auto_show`, then auto-opens the side panel. No click required.
+
+> **v4.1.0 note:** earlier versions also embedded a raw fenced ```html `<iframe>` block straight into the message. That turned out to be a foot-gun — the frontend patch's guard (`!htmlGroups.some(o=>o.html)`) skipped detection when the block was present, and stock Open WebUI rendered it as a visible code fence. v4.1.0 relies solely on the markdown link plus the patch.
+
+### Path A — Stock Open WebUI (zero setup)
+
+Do nothing — the filter already emits the markdown link. The user clicks `🖥️ Open preview` and the preview SPA opens in a new tab. Set `PREVIEW_MODE=off` in Valves if you don't want the link at all. See [Valves reference](#valves-reference).
+
+### Path B — Apply our patches to Open WebUI (auto-opening side panel)
+
+If you want the preview to pop open automatically inside the artifact panel like in the screenshot above, use our patched Open WebUI build:
+
+- **Easiest:** use `docker-compose.webui.yml` from the repo root. It builds Open WebUI with `fix_artifacts_auto_show` and `fix_preview_url_detection` pre-applied.
+- **Custom image:** if you maintain your own Open WebUI image, copy the two patch scripts (`openwebui/patches/fix_artifacts_auto_show.py` and `openwebui/patches/fix_preview_url_detection.py`) and run them against `/app/build/_app/immutable/chunks/*.js` at build time — see [`openwebui/Dockerfile`](../openwebui/Dockerfile) for the exact `RUN python3 /tmp/patches/...` invocations. Both patches are idempotent and tested against Open WebUI 0.9.2 (this build's strict target).
+
+### Also check: `PUBLIC_BASE_URL` must be reachable from the user's browser
+
+The iframe/button `src` comes from the server's `PUBLIC_BASE_URL` env var. It must be a hostname the user's browser can resolve — not Docker DNS. Set it in `.env` (`PUBLIC_BASE_URL=https://cu.example.com` for prod, `http://localhost:8081` for local dev). Connection-refused symptoms after that? See [Troubleshooting → connection refused](#preview-shows-connection-refused-or-a-blank-frame).
+
+<a id="two-file_server_url-settings--they-must-match"></a>
+### Two URL-roles — public (server env) and internal (filter+tool Valve)
+
+**v4.0.0:** the "two `FILE_SERVER_URL`" problem is gone. There is now **one public URL**, owned by the server. The filter doesn't carry it any more — it's delivered in the `X-Public-Base-URL` response header on `/system-prompt` and cached alongside the prompt. Operator only has one knob for the public URL now.
+
+| Role | Where | Default | Notes |
+|------|-------|---------|-------|
+| **Public URL** — baked into /system-prompt, returned to filter in header, model writes it in links | `computer-use-server` env `PUBLIC_BASE_URL` (set in `.env`) | `http://computer-use-server:8081` (internal Docker DNS — *the browser cannot resolve it*; override to a browser-reachable URL such as `http://localhost:8081` for local dev, `https://cu.example.com` in prod) | Single source of truth. The filter reads it from the response header; no filter Valve for it. `fix_preview_url_detection` is host-agnostic — the iframe src is reconstructed at runtime from the matched URL's own origin, so no build-arg is needed. |
+| **Internal URL** — server→server fetch from inside the open-webui container | Filter Valve `ORCHESTRATOR_URL` and Tool Valve `ORCHESTRATOR_URL` (both seeded by `init.sh`) | `http://computer-use-server:8081` (Docker service DNS) | Only reachable inside the compose network. Browsers never see it. `init.sh` seeds both Valves from the `ORCHESTRATOR_URL` env on the open-webui container. |
+
+**Custom project/network layouts.** The stock `docker-compose.yml` pins `container_name: computer-use-server`, so `docker compose -p myproject up` by itself does not rename the container — the internal hostname stays `computer-use-server`. If you remove/change that pin, set `ORCHESTRATOR_URL` on the open-webui container to the new hostname and `init.sh` will seed both Valves correctly.
+
+For the full embedding checklist see [README.md → Required setup when embedding Open WebUI](../README.md#required-setup-when-embedding-open-webui-into-your-own-stack).
+
+## Valves reference
+
+| Name | Type | Default | Purpose |
+|------|------|---------|---------|
+| `ORCHESTRATOR_URL` | str | `"http://computer-use-server:8081"` | **Internal** URL of the Computer Use server. Used for server→server fetch of `/system-prompt` from inside the open-webui container. Never appears in browser-facing URLs — the public URL comes from the server's `PUBLIC_BASE_URL` env var via the `X-Public-Base-URL` response header. Trailing slash tolerated. Non-http(s) schemes are rejected. |
+| `INJECT_SYSTEM_PROMPT` | bool | `True` | If `False`, `inlet()` skips system-prompt injection entirely — useful when another filter owns the prompt. |
+| `PREVIEW_MODE` | Literal `"button" \| "off"` | `"button"` | Whether to emit the markdown preview link. `button` = emit `[🖥️ Open preview]({base}/preview/{chat_id})` (the `fix_preview_url_detection` frontend patch promotes it to an inline artifact on patched builds; stock Open WebUI leaves it as a plain clickable link). `off` = no preview link. |
+| `ARCHIVE_BUTTON` | Literal `"on" \| "off"` | `"on"` | Append `[{ARCHIVE_BUTTON_TEXT}]({base}/files/{chat_id}/archive)` to assistant messages that contain files for the current chat. |
+| `PREVIEW_BUTTON_TEXT` | str | `"🖥️ Open preview"` | Label for the preview-button markdown link (used when `PREVIEW_MODE` is `button`). |
+| `ARCHIVE_BUTTON_TEXT` | str | `"📦 Download all files as archive"` | Label for the archive-download link (used when `ARCHIVE_BUTTON` is `on`). |
+
+## Preview UX: which `PREVIEW_MODE` fits you?
+
+- **`PREVIEW_MODE="button"`** (default). Every assistant message containing a sandbox file URL (or a `<details type="tool_calls">` block referencing a browser tool) is decorated with a markdown link `[🖥️ Open preview]({base}/preview/{chat_id})`. On stock Open WebUI the user clicks it to open the preview SPA in a new tab. On patched builds (`fix_preview_url_detection` + `fix_artifacts_auto_show`, shipped by `docker-compose.webui.yml`) the same URL is detected in text and auto-opened as an inline artifact — no click.
+- **`PREVIEW_MODE="off"`**. No preview link. Combine with `ARCHIVE_BUTTON="off"` to make `outlet()` a no-op.
+
+If you're upgrading from v4.0.0 / v3.x and saved `"artifact"` or `"both"` in your Valves, Pydantic validation will now reject the saved value — re-seed Valves after upgrade (`rm /app/backend/data/.computer-use-initialized` + restart).
+
+## Archive button
+
+`ARCHIVE_BUTTON="on"` (default) preserves the v3.0.x behaviour: when an assistant message contains at least one file URL under `{PUBLIC_BASE_URL}/files/{chat_id}/…`, `outlet()` appends a markdown link to the archive endpoint `/files/{chat_id}/archive`. The endpoint streams a zip of every file the sandbox has written for the chat. The append is idempotent (substring check against the fully-rendered URL) — safe to re-run `outlet()` on the same body as many times as the framework chooses.
+
+## System prompt injection
+
+`INJECT_SYSTEM_PROMPT` (default `True`) controls the `inlet()` path. When the `ai_computer_use` tool is active and `chat_id` is present, the filter HTTP-fetches the baked prompt from `{ORCHESTRATOR_URL}/system-prompt` and injects it into the system message, with a 5-minute LRU cache and a stale-cache fallback on transport failure. The response's `X-Public-Base-URL` header is cached alongside the prompt so `outlet()` can build correct browser-facing links without its own Valve. Non-http(s) schemes on `ORCHESTRATOR_URL` are rejected to avoid `file://` / `ftp://` information-disclosure paths. See `docs/system-prompt.md` for the server-side contract, including how `user_email` drives the `<available_skills>` block.
+
+## Troubleshooting
+
+### Preview shows "connection refused" or a blank frame
+
+- Check that `PUBLIC_BASE_URL` (server `.env`) is reachable *from the user's browser* — the filter has no Valve for the public URL any more; everything flows from the server env.
+- Confirm the Computer Use Server is running: `docker compose ps` should list the `computer-use-server` container as healthy.
+- Copy the `src=` value out of the iframe and `curl` it directly — the SPA HTML should come back with HTTP 200.
+
+### Preview link or archive button never appears
+
+- The assistant message must contain at least one URL matching `{PUBLIC_BASE_URL}/files/{chat_id}/…` (or a `<details type="tool_calls">` block referencing a browser tool — covers pure-navigation sessions). No trigger, no decoration.
+- `chat_id` must reach `outlet()` via `__metadata__`. Restart Open WebUI after toggling Valves if the model didn't re-init.
+- `PREVIEW_MODE` must be `"button"` OR `ARCHIVE_BUTTON` must be `"on"`. When both are `"off"`, `outlet()` returns the body unchanged.
+
+### Preview opens in a new tab instead of inside the artifact panel
+
+You are running stock Open WebUI — the markdown link stays a link. Either live with the click (fine on mobile/minimal deploys) or apply Path B (`fix_preview_url_detection` + `fix_artifacts_auto_show`) to get the inline artifact panel.
+
+### Filter cannot reach `computer-use-server` (cross-stack DNS)
+
+**Symptom:** Preview iframe never auto-opens even on the patched build, system-prompt injection silently falls back to stale cache, or OWUI container logs show DNS errors / connection-refused on `http://computer-use-server:8081`. Manually editing the `ORCHESTRATOR_URL` Valve to a host IP (e.g. `http://192.168.x.x:8081`) makes the symptom disappear.
+
+**Why:** `docker-compose.yml` and `docker-compose.webui.yml` reach each other through the **default Docker Compose network**, which only works when both stacks share a project name. Compose derives the project name from the parent directory (`open-computer-use`). If the two stacks end up with different project names — different parent directory, `-p custom-name` flag, `COMPOSE_PROJECT_NAME` env, `docker compose --project-directory`, or running them from separate clones — they get separate networks and `computer-use-server` no longer resolves from inside the OWUI container.
+
+**Fixes (pick one):**
+
+- **Restore the shared project name.** Keep both compose files in the same `open-computer-use/` directory and start them without `-p`. Verify with `docker network inspect open-computer-use_default` — both `computer-use-server` and `open-webui` should appear in the `Containers` section.
+- **Override the env before bringing OWUI up:** add `ORCHESTRATOR_URL=http://host.docker.internal:8081` to `.env`. On Linux, also append `extra_hosts: ["host.docker.internal:host-gateway"]` to the `open-webui` service in `docker-compose.webui.yml` (Docker Desktop / macOS / Windows resolve this automatically). Then re-seed the Valves so the new env reaches the persistent OWUI database: `docker exec <owui> rm /app/backend/data/.computer-use-initialized && docker restart <owui>`.
+- **Hard-set the Valve** via OWUI admin → Functions → Computer Use Filter → Valves → `ORCHESTRATOR_URL` to a host IP or hostname the OWUI container can reach. Quickest one-off fix, but it persists in the OWUI database and survives `.env` changes — easy to forget on the next deploy.
+
+The same root cause also breaks the matching `ORCHESTRATOR_URL` Valve on the **Tool** (`computer_use_tools.py`) and the env var read by the `fix_large_tool_results` patch — fix once at the env layer and all three pick it up via `init.sh`.
+
+### "Non-http scheme" error in logs
+
+Caused by setting `ORCHESTRATOR_URL` to a `file://`, `ftp://`, or similarly non-http(s) URL. The filter rejects it and serves the stale cache if available, otherwise skips injection. Fix by pointing the Valve at an `http://` or `https://` endpoint.
+
+## Version history
+
+- **v4.1.0** — Breaking: removed `PREVIEW_MODE="artifact"` and `PREVIEW_MODE="both"`. `outlet()` no longer emits a fenced ```html `<iframe>` block; only the markdown preview link remains. The extra html block was redundant *and* actively harmful — the `fix_preview_url_detection` frontend patch guards on `!htmlGroups.some(o=>o.html)`, so when outlet pre-emitted an html block the patch skipped detection and the iframe rendered as a raw code fence in chat (issue #43 symptom). `"button"` is the new default; matches internal prod v3.8.0 behaviour. Saved `"artifact"` / `"both"` values fail Pydantic validation — re-seed Valves after upgrade.
+- **v4.0.0** — Breaking: removed `FILE_SERVER_URL` and `SYSTEM_PROMPT_URL` Valves, replaced with a single `ORCHESTRATOR_URL` Valve (internal URL). The public URL is now owned by the server (`PUBLIC_BASE_URL` env) and delivered to the filter via the `X-Public-Base-URL` response header on `/system-prompt`. `_fetch_system_prompt()` now returns `(public_url, prompt)`; `outlet()` reads `public_url` from the cache instead of its own Valve. Tool's `FILE_SERVER_URL` Valve was renamed to `ORCHESTRATOR_URL` for consistency. `init.sh` re-seeds the new Valve names.
+- **v3.4.0** — Removed the three legacy v3.2.0 boolean Valves (`ENABLE_PREVIEW_ARTIFACT`, `ENABLE_PREVIEW_BUTTON`, `ENABLE_ARCHIVE_BUTTON`) and their migration bridge. `PREVIEW_MODE` and `ARCHIVE_BUTTON` are the only knobs. Users upgrading straight from v3.2.0 revert to defaults — upgrade via v3.3.0 first if you need to preserve saved preferences.
+- **v3.3.0** — Collapsed three boolean preview/archive Valves (`ENABLE_PREVIEW_ARTIFACT`, `ENABLE_PREVIEW_BUTTON`, `ENABLE_ARCHIVE_BUTTON`) into two Literal Valves (`PREVIEW_MODE`, `ARCHIVE_BUTTON`). Existing v3.2.0 deployments were migrated transparently by a Pydantic `@model_validator(mode="after")`. `outlet()` behaviour and all v3.1.0/v3.2.0 invariants preserved.
+- **v3.2.0** — Added `ENABLE_PREVIEW_ARTIFACT` (default `True`), `ENABLE_PREVIEW_BUTTON` (default `False`), and `PREVIEW_BUTTON_TEXT` Valves. `outlet()` now emits an inline iframe artifact and/or a markdown preview link alongside the archive button. All v3.1.0 invariants preserved.
+- **v3.1.0** — Removed the hardcoded ~460-line system prompt f-string; server became the single source of truth. HTTP fetch + LRU cache + stale-cache fallback. `SYSTEM_PROMPT_URL` Valve added (removed in v4.0.0); non-http(s) schemes rejected.
+- **v3.0.2** — Last hardcoded-prompt revision. See git history for details.
+
+For deeper context, consult the CHANGELOG blocks in the module docstring of `openwebui/functions/computer_link_filter.py` and the per-commit history on `main`.

package/docs/roadmap/implementation-roadmap.md

@@ -0,0 +1,104 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: draft
+last-reviewed: 2026-06-07
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+---
+
+Dependency-ordered build plan for the minimal-shelf implementation — contract-freeze first, a thin end-to-end thread next, then parallel fan-out — for the team implementing `next/v1` in the code repository.
+
+# Implementation roadmap — minimal shelf
+
+The architecture set (`docs/architecture/`) is settled enough to build: six components, eleven inter-component edges (F1–F11), six drafted contracts, and eleven ADRs (ADR-0001 `accepted`, 0002–0011 `proposed` with settled decisions). This roadmap orders the build so a team working in parallel proves integration early and never codes against a moving contract.
+
+Scope: the **minimal shelf** only — one-click solo deployment, `trusted_operator` profile, `runc` runtime, local-volume storage engine, host-local credentials, file-system audit sink. No IdP, no KVM, no SIEM, no external store. Full-shelf features are listed once, at the end, as deferred.
+
+## Components and edges
+
+The six containers and the directed edges between them ([`05-c4-container.md`](../architecture/05-c4-container.md) §4 defines the F-labels). HARD = the target must exist for the source's critical path; SOFT = the source emits without blocking.
+
+| Edge | Source → Target | Crosses | Type |
+|---|---|---|---|
+| F1 | MCP caller → MCP gateway (01) | MCP authz spec | inbound |
+| F5 | MCP gateway (01) → Control API (02) | session create/status, service identity | HARD |
+| F2 | Operator → Control API (02) | operator-only ingress, kill-switch | HARD (privileged) |
+| F6 | Control API (02) → Session sandbox (05) | Session JWT, host dials guest | HARD |
+| F7 | Storage broker (04) → Session sandbox (05) | mount, `filesystem_id` handle | HARD |
+| F8 | Session sandbox (05) → Egress trust-edge (06) | single outbound path | HARD |
+| F9 | Storage broker (04) → Egress trust-edge (06) | broker-signed backend leg (network engine only) | HARD (network engine) |
+| F10 | every container → Audit pipeline (07) | OCSF event | SOFT (async fan-in) |
+| F11 | data-plane client → Storage broker (04) north face | file/artifact API | SOFT (post-v1) |
+
+```mermaid
+flowchart LR
+    CALLER[MCP caller] -->|F1| MCP[MCP gateway 01]
+    MCP -->|F5 HARD| CTRL[Control API 02]
+    OPER[Operator] -->|F2| CTRL
+    CTRL -->|F6 HARD host-dials| VM[Session sandbox 05]
+    BROKER[Storage broker 04] -->|F7 HARD mount| VM
+    VM -->|F8 HARD| EDGE[Egress trust-edge 06]
+    MCP -.->|F10 soft| AUD[Audit pipeline 07]
+    CTRL -.->|F10 soft| AUD
+    BROKER -.->|F10 soft| AUD
+    VM -.->|F10 soft| AUD
+    EDGE -.->|F10 soft| AUD
+```
+
+The graph is acyclic. `F1 → F5 → F6` is the integration spine; every other edge is either deferred or async fan-in.
+
+## Build order
+
+Freeze the spine contracts before any component code; prove the end-to-end thread before thickening any single component (walking skeleton, not horizontal layers). The audit fan-in (F10) is async, so it is stubbed during the skeleton and the real pipeline is built in parallel afterward.
+
+### Phase 0 — Contract freeze (no service code)
+
+Two spine edges are stubs ([#205](https://github.com/Wide-Moat/open-computer-use/issues/205)); freeze them before opening any consumer.
+
+| Task | Edge | Contract | State today |
+|---|---|---|---|
+| Freeze session set-up RPC | F5 (gateway↔Control), F6 lifecycle | session-setup (Protobuf/gRPC) | stub, [#205](https://github.com/Wide-Moat/open-computer-use/issues/205) |
+| Freeze operator REST surface | F2 | operator OpenAPI | stub, [#205](https://github.com/Wide-Moat/open-computer-use/issues/205) |
+| Confirm exec channel | F6 dial | [`exec/exec-channel.schema.json`](../../contracts/exec/exec-channel.schema.json) | drafted — confirm, do not redesign |
+| Confirm audit envelope | F10 | [`audit/audit-fanin.asyncapi.yaml`](../../contracts/audit/audit-fanin.asyncapi.yaml) | drafted — emitters code against it |
+
+### Phase 1 — Tracer slice (single thread, minimal parallelism)
+
+Build the narrowest path that proves the three load-bearing HARD edges (F5, F6, exec contract) end to end: a caller issues one exec and gets a result. The Session sandbox is the core and the most self-contained piece — it builds first, against a thin Control driver that does only what the sandbox needs to come up. Everything else on the slice exists to stand the sandbox up and carry one call. Audit writes to a NULL sink. This is sequential by nature — it is the integration proof the team merges into.
+
+1. **Session sandbox (05)** — the core. Guest agent as PID 1, host-side exec supervisor terminating the dialled channel over the frozen [`exec/exec-channel.schema.json`](../../contracts/exec/exec-channel.schema.json). `runc` + hardened posture (seccomp BPF, Landlock, cap-drop ALL, read-only rootfs; [ADR-0003](../architecture/adr/0003-sandbox-runtime-tier-ladder.md) `trusted_operator` × `runc` cell). One container; the sub-container split ([#174](https://github.com/Wide-Moat/open-computer-use/issues/174)) is deferred.
+2. **Control / operator API (02)** — thin driver only at this phase: the lifecycle controller's two ordered steps — **create** the container (runc orchestration), then **dial** into it (Session JWT bound to `container_name` over the host-opened exec channel; the guest listens, non-host peers dropped at accept). Minimal-shelf auth is a host-rooted local operator credential ([ADR-0004](../architecture/adr/0004-operator-authentication-substrate.md) minimal variant). The session registry, denylist, quota, and kill-switch are not on the slice — they land in Phase 2.
+3. **MCP gateway (01)** — inbound MCP validator ([`mcp/2025-06-18/ocu-constraints.schema.json`](../../contracts/mcp/2025-06-18/ocu-constraints.schema.json)) forwarding session create/status to the Control driver over the frozen F5 RPC. Stateless per request.
+
+### Phase 2 — Parallel fan-out
+
+Each track hangs off the proven spine behind a frozen contract, so the team runs them concurrently.
+
+- **Track A — Control / operator API (02), full surface.** Thicken the Phase-1 driver into the session registry, the denylist (kill-switch authority, NFR-SEC-01), quota counters, and the operator/SOAR ingress (F2/F4). The customer-IdP + PAM-JIT path is full-shelf ([ADR-0004](../architecture/adr/0004-operator-authentication-substrate.md), [#225](https://github.com/Wide-Moat/open-computer-use/issues/225)).
+- **Track B — Audit pipeline (07).** Swap the NULL sink for the real pipeline behind the F10 envelope: host-attested ingest, fsync-then-ack local durable commit, hash-chain writer, daily Merkle head, file-system sink ([ADR-0009](../architecture/adr/0009-audit-pipeline-pluggable-by-contract.md), minimal shelf). The bus, WORM store, SIEM bridge, and transparency log are pluggable seams, off on the minimal shelf.
+- **Track C — Storage broker (04), south face.** The `filesystem_id`-scoped mount (F7) over the built storage contracts ([`mount-config`](../../contracts/storage/mount-config.schema.json), [`file-ops`](../../contracts/storage/file-ops.schema.json)). Local-volume backend engine — no network leg, so no F9 ([ADR-0010](../architecture/adr/0010-storage-backend-pluggable-adapter.md)). Host-local backend credential, admitted only single-tenant `trusted_operator` (NFR-SEC-60). The north face (F11, SPA) is deferred ([ADR-0002](../architecture/adr/0002-session-view-descriptor.md), post-v1).
+- **Track D — Egress trust-edge (06), minimal rung.** Deny-all or transparent pass-through only (NFR-FLEX-15 ladder; [`02-trust-boundaries.md`](../architecture/02-trust-boundaries.md) §7): a deny-by-default forward route with the `x-deny-reason` structured deny and the content-blind egress tripwire (NFR-SEC-57). No CA, no SDS, no credential injection — those are the bump rung and above (full shelf).
+
+## Deferred to the full shelf (not minimal Phase 1–2)
+
+Each is a clean abstraction boundary the minimal shelf builds against, activated later.
+
+| Feature | Anchor | Gate |
+|---|---|---|
+| Customer IdP + PAM-JIT operator auth | [ADR-0004](../architecture/adr/0004-operator-authentication-substrate.md) full variant | [#225](https://github.com/Wide-Moat/open-computer-use/issues/225) |
+| STS-scoped-per-session backend credential | [ADR-0010](../architecture/adr/0010-storage-backend-pluggable-adapter.md), NFR-SEC-25 | full shelf |
+| gVisor / microVM runtime tiers | [ADR-0003](../architecture/adr/0003-sandbox-runtime-tier-ladder.md) | [#161](https://github.com/Wide-Moat/open-computer-use/issues/161) |
+| Egress bump rung + SDS minter + credential injection | [ADR-0005](../architecture/adr/0005-egress-credential-delivery-envoy-sds.md), [ADR-0007](../architecture/adr/0007-egress-auth-mechanism.md) | [#240](https://github.com/Wide-Moat/open-computer-use/issues/240) |
+| Broker north face / live-session views | [ADR-0002](../architecture/adr/0002-session-view-descriptor.md) | [#210](https://github.com/Wide-Moat/open-computer-use/issues/210) |
+| WORM store, SIEM bridge, transparency log | [ADR-0009](../architecture/adr/0009-audit-pipeline-pluggable-by-contract.md) | [#150](https://github.com/Wide-Moat/open-computer-use/issues/150), [#151](https://github.com/Wide-Moat/open-computer-use/issues/151) |
+
+## Test coverage moves with the code
+
+Each component's verification method is named in its owning NFR row ([`manifesto/02-nfrs.md`](../architecture/manifesto/02-nfrs.md) verification column) and in the STRIDE rows it must exercise ([`06-threat-model.md`](../architecture/06-threat-model.md)). Tests ship in the same PR as the code, using the method the NFR names: unit and property tests on parsers and the policy resolver, integration tests on each HARD edge, the exec golden-path E2E on the Phase 1 slice. The CI gates already enforced on every PR (secrets, SAST, SCA, IaC, contract-schema, doc-lint) bound it; the performance baselines are the NFR-PERF rows (session-create p99, exec overhead, egress latency, audit backpressure). A consolidated test-strategy doc lands once the first component's code does, when at least one verification cell is enforced rather than planned.
+
+## Open questions
+
+1. Broker and edge cardinality — one instance per deployment or per sandbox host — picks a topology at build time; the diagram may change, the component specs do not. [#175](https://github.com/Wide-Moat/open-computer-use/issues/175).
+2. Session sandbox sub-container split (exec supervisor vs guest as separate containers). [#174](https://github.com/Wide-Moat/open-computer-use/issues/174).

package/docs/sandbox-contents.svg

@@ -0,0 +1,229 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 820" font-family="Inter, -apple-system, system-ui, sans-serif">
+  <defs>
+    <style>
+      .title { font-size: 20px; font-weight: 700; fill: #1a1a2e; }
+      .subtitle { font-size: 11px; fill: #6b7280; }
+      .cat-label { font-size: 13px; font-weight: 600; fill: #fff; }
+      .item { font-size: 11px; fill: #374151; }
+      .item-bold { font-size: 11px; font-weight: 600; fill: #1f2937; }
+      .version { font-size: 10px; fill: #6b7280; }
+      .section-border { fill: none; stroke: #e5e7eb; stroke-width: 1; rx: 8; }
+    </style>
+    <linearGradient id="header-bg" x1="0" y1="0" x2="900" y2="0">
+      <stop offset="0%" stop-color="#1a1a2e"/>
+      <stop offset="100%" stop-color="#16213e"/>
+    </linearGradient>
+    <linearGradient id="lang-bg" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#3b82f6"/>
+      <stop offset="100%" stop-color="#2563eb"/>
+    </linearGradient>
+    <linearGradient id="tools-bg" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#8b5cf6"/>
+      <stop offset="100%" stop-color="#7c3aed"/>
+    </linearGradient>
+    <linearGradient id="py-bg" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#10b981"/>
+      <stop offset="100%" stop-color="#059669"/>
+    </linearGradient>
+    <linearGradient id="node-bg" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#f59e0b"/>
+      <stop offset="100%" stop-color="#d97706"/>
+    </linearGradient>
+    <linearGradient id="browser-bg" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#ef4444"/>
+      <stop offset="100%" stop-color="#dc2626"/>
+    </linearGradient>
+    <linearGradient id="fs-bg" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#64748b"/>
+      <stop offset="100%" stop-color="#475569"/>
+    </linearGradient>
+  </defs>
+
+  <!-- Background -->
+  <rect width="900" height="820" rx="12" fill="#fafbfc" stroke="#d1d5db" stroke-width="1"/>
+
+  <!-- Header -->
+  <rect width="900" height="60" rx="12" fill="url(#header-bg)"/>
+  <rect y="48" width="900" height="12" fill="url(#header-bg)"/>
+  <text x="24" y="32" class="title" fill="#fff">Sandbox Container</text>
+  <text x="24" y="48" class="subtitle" fill="#94a3b8">Ubuntu 24.04 (Noble) · linux/amd64 · open-computer-use:latest</text>
+  <text x="876" y="36" text-anchor="end" font-size="10" fill="#94a3b8">One container per chat session</text>
+
+  <!-- Row 1: Languages + System Tools -->
+  <!-- Languages -->
+  <rect x="16" y="72" width="430" height="130" class="section-border" fill="#f8fafc"/>
+  <rect x="16" y="72" width="430" height="28" rx="8" fill="url(#lang-bg)"/>
+  <rect x="16" y="92" width="430" height="8" fill="url(#lang-bg)"/>
+  <text x="32" y="91" class="cat-label">Languages &amp; Runtimes</text>
+
+  <text x="32" y="120" class="item-bold">Python 3.12</text>
+  <text x="130" y="120" class="version">pip, venv</text>
+  <text x="32" y="138" class="item-bold">Node.js 22</text>
+  <text x="130" y="138" class="version">npm 10.9</text>
+  <text x="32" y="156" class="item-bold">Java 21</text>
+  <text x="130" y="156" class="version">OpenJDK JRE</text>
+  <text x="32" y="174" class="item-bold">Bun</text>
+  <text x="130" y="174" class="version">latest</text>
+  <text x="32" y="192" class="item-bold">TypeScript 5.9</text>
+  <text x="160" y="192" class="version">tsc, tsx</text>
+
+  <text x="240" y="120" class="item-bold">Bash</text>
+  <text x="300" y="120" class="version">+ tmux, sudo</text>
+  <text x="240" y="138" class="item-bold">Git</text>
+  <text x="300" y="138" class="version">+ glab 1.52</text>
+  <text x="240" y="156" class="item-bold">Claude Code</text>
+  <text x="340" y="156" class="version">CLI</text>
+  <text x="240" y="174" class="item-bold">Playwright CLI</text>
+  <text x="360" y="174" class="version">0.1.1</text>
+
+  <!-- System Tools -->
+  <rect x="454" y="72" width="430" height="130" class="section-border" fill="#f8fafc"/>
+  <rect x="454" y="72" width="430" height="28" rx="8" fill="url(#tools-bg)"/>
+  <rect x="454" y="92" width="430" height="8" fill="url(#tools-bg)"/>
+  <text x="470" y="91" class="cat-label">System Tools</text>
+
+  <text x="470" y="120" class="item-bold">LibreOffice</text>
+  <text x="560" y="120" class="version">Writer, Calc, Impress</text>
+  <text x="470" y="138" class="item-bold">Pandoc</text>
+  <text x="560" y="138" class="version">Document conversion</text>
+  <text x="470" y="156" class="item-bold">FFmpeg</text>
+  <text x="560" y="156" class="version">Audio/video</text>
+  <text x="470" y="174" class="item-bold">ImageMagick</text>
+  <text x="560" y="174" class="version">Image processing</text>
+  <text x="470" y="192" class="item-bold">Graphviz</text>
+  <text x="560" y="192" class="version">Graph diagrams</text>
+
+  <text x="700" y="120" class="item-bold">Tesseract</text>
+  <text x="775" y="120" class="version">OCR (EN+RU)</text>
+  <text x="700" y="138" class="item-bold">Ghostscript</text>
+  <text x="785" y="138" class="version">PDF engine</text>
+  <text x="700" y="156" class="item-bold">qpdf</text>
+  <text x="785" y="156" class="version">PDF tools</text>
+  <text x="700" y="174" class="item-bold">ttyd</text>
+  <text x="785" y="174" class="version">Web terminal</text>
+  <text x="700" y="192" class="item-bold">socat</text>
+  <text x="785" y="192" class="version">CDP tunnel</text>
+
+  <!-- Row 2: Python Packages -->
+  <rect x="16" y="214" width="868" height="155" class="section-border" fill="#f8fafc"/>
+  <rect x="16" y="214" width="868" height="28" rx="8" fill="url(#py-bg)"/>
+  <rect x="16" y="234" width="868" height="8" fill="url(#py-bg)"/>
+  <text x="32" y="233" class="cat-label">Python Packages (110+)</text>
+
+  <!-- Col 1: Documents -->
+  <text x="32" y="262" class="item-bold">Documents</text>
+  <text x="32" y="278" class="item">python-docx, python-pptx</text>
+  <text x="32" y="294" class="item">openpyxl, xlsxwriter</text>
+  <text x="32" y="310" class="item">reportlab, markitdown</text>
+
+  <!-- Col 2: PDF -->
+  <text x="210" y="262" class="item-bold">PDF</text>
+  <text x="210" y="278" class="item">pypdf, pdfplumber</text>
+  <text x="210" y="294" class="item">pikepdf, pdfkit</text>
+  <text x="210" y="310" class="item">pdfminer, pdf2image</text>
+
+  <!-- Col 3: Images -->
+  <text x="380" y="262" class="item-bold">Images &amp; Vision</text>
+  <text x="380" y="278" class="item">Pillow, OpenCV</text>
+  <text x="380" y="294" class="item">scikit-image, Wand</text>
+  <text x="380" y="310" class="item">pytesseract, mediapipe</text>
+
+  <!-- Col 4: Data -->
+  <text x="550" y="262" class="item-bold">Data &amp; ML</text>
+  <text x="550" y="278" class="item">pandas, numpy, scipy</text>
+  <text x="550" y="294" class="item">scikit-learn, matplotlib</text>
+  <text x="550" y="310" class="item">seaborn, jax, onnxruntime</text>
+
+  <!-- Col 5: Web -->
+  <text x="730" y="262" class="item-bold">Web &amp; LLM</text>
+  <text x="730" y="278" class="item">playwright, requests</text>
+  <text x="730" y="294" class="item">beautifulsoup4, openai</text>
+  <text x="730" y="310" class="item">Flask, lxml, markdown</text>
+
+  <!-- Row footer -->
+  <text x="32" y="340" class="item">unoserver · camelot-py · tabula-py · cryptography · PyYAML · psutil · coloredlogs · click · humanfriendly</text>
+  <text x="32" y="356" class="version">Full list: requirements.txt (110 packages)</text>
+
+  <!-- Row 3: Node.js + Browser -->
+  <!-- Node.js -->
+  <rect x="16" y="381" width="430" height="130" class="section-border" fill="#f8fafc"/>
+  <rect x="16" y="381" width="430" height="28" rx="8" fill="url(#node-bg)"/>
+  <rect x="16" y="401" width="430" height="8" fill="url(#node-bg)"/>
+  <text x="32" y="400" class="cat-label">Node.js Packages (20)</text>
+
+  <text x="32" y="428" class="item-bold">Office</text>
+  <text x="100" y="428" class="item">pptxgenjs, docx, pdf-lib</text>
+  <text x="32" y="446" class="item-bold">Frontend</text>
+  <text x="100" y="446" class="item">React 19, TypeScript 5.9</text>
+  <text x="32" y="464" class="item-bold">Images</text>
+  <text x="100" y="464" class="item">sharp (resize, convert, optimize)</text>
+  <text x="32" y="482" class="item-bold">CLI tools</text>
+  <text x="100" y="482" class="item">mmdc (Mermaid), tsx, tsc, markdownlint</text>
+  <text x="32" y="500" class="item-bold">Automation</text>
+  <text x="100" y="500" class="item">playwright 1.57</text>
+
+  <!-- Browser -->
+  <rect x="454" y="381" width="430" height="130" class="section-border" fill="#f8fafc"/>
+  <rect x="454" y="381" width="430" height="28" rx="8" fill="url(#browser-bg)"/>
+  <rect x="454" y="401" width="430" height="8" fill="url(#browser-bg)"/>
+  <text x="470" y="400" class="cat-label">Browser &amp; Services</text>
+
+  <text x="470" y="428" class="item-bold">Chromium</text>
+  <text x="560" y="428" class="item">via Playwright (headless)</text>
+  <text x="470" y="446" class="item-bold">CDP</text>
+  <text x="560" y="446" class="item">:9222 (external) → :9223 (internal)</text>
+  <text x="470" y="464" class="item-bold">ttyd</text>
+  <text x="560" y="464" class="item">WebSocket terminal server</text>
+  <text x="470" y="482" class="item-bold">Claude Code</text>
+  <text x="560" y="482" class="item">Interactive AI sub-agent via TTY</text>
+  <text x="470" y="500" class="item-bold">inotifywait</text>
+  <text x="560" y="500" class="item">Skill usage tracking</text>
+
+  <!-- Row 4: Filesystem -->
+  <rect x="16" y="523" width="868" height="155" class="section-border" fill="#f8fafc"/>
+  <rect x="16" y="523" width="868" height="28" rx="8" fill="url(#fs-bg)"/>
+  <rect x="16" y="543" width="868" height="8" fill="url(#fs-bg)"/>
+  <text x="32" y="542" class="cat-label">Filesystem Layout</text>
+
+  <!-- Working dir -->
+  <text x="32" y="572" class="item-bold">/home/assistant/</text>
+  <text x="180" y="572" class="version">Working directory (Docker volume, persists per chat)</text>
+  <text x="32" y="590" class="item-bold">/home/node_modules/</text>
+  <text x="200" y="590" class="version">Shared npm packages (image layer, not per-container)</text>
+  <text x="32" y="608" class="item-bold">/usr/local/lib/node_modules_global/</text>
+  <text x="280" y="608" class="version">Global CLI tools: mmdc, tsc, tsx, claude</text>
+
+  <!-- Mount points -->
+  <text x="500" y="572" class="item-bold">/mnt/user-data/uploads/</text>
+  <text x="690" y="572" class="version">User files (read-only)</text>
+  <text x="500" y="590" class="item-bold">/mnt/user-data/outputs/</text>
+  <text x="690" y="590" class="version">Output files (served via API)</text>
+  <text x="500" y="608" class="item-bold">/mnt/skills/public/</text>
+  <text x="690" y="608" class="version">Built-in skills (16)</text>
+  <text x="500" y="626" class="item-bold">/mnt/skills/examples/</text>
+  <text x="690" y="626" class="version">Example skills (8)</text>
+  <text x="500" y="644" class="item-bold">/mnt/skills/user/</text>
+  <text x="690" y="644" class="version">User-uploaded skills</text>
+
+  <text x="32" y="626" class="item-bold">/opt/pw-browsers/</text>
+  <text x="200" y="626" class="version">Playwright Chromium cache</text>
+  <text x="32" y="644" class="item-bold">~/.claude/</text>
+  <text x="200" y="644" class="version">Claude Code config, settings, skill symlinks</text>
+  <text x="32" y="662" class="item-bold">~/.mcp.json</text>
+  <text x="200" y="662" class="version">MCP servers for Claude Code (auto-generated)</text>
+
+  <!-- Row 5: Fonts -->
+  <rect x="16" y="685" width="430" height="80" class="section-border" fill="#f8fafc"/>
+  <text x="32" y="708" class="item-bold">Fonts</text>
+  <text x="32" y="726" class="item">Liberation, DejaVu, FreeSans, Noto CJK, Noto Emoji</text>
+  <text x="32" y="744" class="version">Full Unicode coverage: Latin, Cyrillic, CJK, Emoji</text>
+
+  <!-- Ports -->
+  <rect x="454" y="685" width="430" height="80" class="section-border" fill="#f8fafc"/>
+  <text x="470" y="708" class="item-bold">Exposed Ports</text>
+  <text x="470" y="726" class="item">9222 — CDP (browser viewer) · 7681 — ttyd (terminal)</text>
+  <text x="470" y="744" class="version">Accessed via Computer Use Server proxy (not directly)</text>
+
+  <!-- Footer -->
+  <text x="450" y="798" text-anchor="middle" font-size="11" fill="#9ca3af">open-computer-use · github.com/Yambr/open-computer-use</text>
+</svg>