@mseep/open-computer-use 1.0.0

package/docs/architecture/manifesto/04-non-goals.md

@@ -0,0 +1,23 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: draft
+last-reviewed: 2026-06-06
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+---
+
+Features v1 defers, each with a clean abstraction boundary so a later milestone adds it without redesign. Audience: anyone proposing a feature for v1; the ADR path to reconsider is in [PROCESS.md](../PROCESS.md).
+
+## Non-goals
+
+**Skill registry.** v1 ships zero default skills. The `SkillProvider` abstraction stays `status: tbd` in the component set; skills load from a registry the customer supplies over a stable contract. v1 does not fix the skill metadata schema, the versioning rules, or the discovery protocol — inventing them now locks customers into a shape we have not proved.
+
+**Hosted models and the agent loop.** OCU does not host, proxy, or select an LLM, and does not run the loop (multi-turn reasoning, reflection, tool-use selection); that lives in the calling client — a sibling component such as Open WebUI, n8n, or LiteLLM, or any MCP caller. OCU is an MCP server plus a sandbox executor: it terminates tool-call requests and executes them in isolation. A sandbox tool that needs an LLM reaches it as one allow-listed egress endpoint under the Egress trust-edge, broker, and audit path ([03-non-negotiables.md](03-non-negotiables.md)), never through an OCU model abstraction.
+
+**Admin web UI.** v1 ships no operator console. Operator functions — session lifecycle, quota, denylist, audit review — run over the CLI (`occ`) and GitOps config. Every UI is new attack surface (CSRF, XSS, broken auth), accessibility burden, and localization cost. The end-user data-plane surface (file upload/download, preview, artifact render, transcript display) is in scope and serves end-user visibility, not operator control ([NFR-SEC-82](02-nfrs.md)). v2 may add a read-only operator console once the CLI is feature-complete and customers ask.
+
+**Durable customer-data store.** OCU is an ephemeral workspace: a session's files live on the broker-mounted scope only while the session runs, and the teardown finalizer scrubs them ([NFR-SEC-65](02-nfrs.md), [NFR-SEC-54](02-nfrs.md)). OCU retains no customer file bytes past the session — long-term retention, residency, and erasure of customer data are the customer's own store, reached over the broker backend leg. The one artifact OCU keeps long-term is the audit record of file activity (who/what/when), on the [NFR-COMP-01](02-nfrs.md) floor — the record, never the bytes. Treating OCU as the system of record for customer data inverts this: the object store is a neighbouring customer-provided capability ([03-non-negotiables.md](03-non-negotiables.md)), not an OCU durable tier.
+
+**SaaS offered by us.** FSL-1.1-Apache-2.0 forbids offering OCU (or a modified version) on a hosted or embedded basis that competes with a paid version ([05-licensing-posture.md](05-licensing-posture.md)). We ship self-hostable software only; the limitation lifts per-release on the two-year Apache-2.0 conversion.

package/docs/architecture/manifesto/05-licensing-posture.md

@@ -0,0 +1,61 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: draft
+last-reviewed: 2026-06-01
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+---
+
+States the licence OCU ships under, the conversion to Apache-2.0, and the gate every dependency passes before it enters the project. Audience: anyone adding a dependency or reasoning about what a fork may do.
+
+## OCU licence: FSL-1.1-Apache-2.0
+
+OCU ships under the [Functional Source License, Version 1.1, Apache 2.0 Future License](../../../LICENSE). The grant lets you use, copy, modify, create derivative works, publish, and redistribute the Software. The one limitation: you may not offer the Software (or a modified version) to third parties on a hosted or embedded basis to compete with a paid version of OCU.
+
+Each release carries its own clock. On the **second anniversary** of the date a given version is made available, that version is additionally licensed under Apache-2.0; from that date the FSL limitation no longer binds it. The conversion is per-release and irrevocable: a release published 2026-06-01 is Apache-2.0 on 2028-06-01 regardless of what later releases do.
+
+The conversion is automatic — no pricing decision and no manual relicensing step. The FSL template carries a license-key anti-tamper clause; OCU ships no license key, so that clause binds nothing here. The change from BUSL-1.1 was a one-time, whole-repo migration ([CHANGELOG](../../../CHANGELOG.md)); releases tagged before it retain BUSL-1.1 terms per the LICENSE published at that tag.
+
+## Dependency licence gate
+
+Every dependency — build, runtime, or dev — passes both gates below before it enters the project. The procedure for proposing one is in [`PROCESS.md`](../PROCESS.md); this section is the allow/reject rule that procedure enforces.
+
+**Licence gate — accept:** Apache-2.0, MIT, BSD-2-Clause, BSD-3-Clause, MPL-2.0, LGPL-2.1 (as a separately-running service), PostgreSQL.
+
+**Licence gate — reject:** AGPL (any version), BSL, BUSL (any version that is not a past version of OCU's own licence), SSPL, CC-NC, and any commercial-only or source-unavailable licence.
+
+**Supply-chain gate.** A dependency must have at least one of: a published SBOM, a reproducible build, signed releases, or cosign-attested artifacts. A sole-maintainer npm/PyPI package with no provenance is rejected on this gate alone, regardless of licence.
+
+When the choice is between a heavier, vendor- or foundation-backed, audited tool and a lighter sole-maintainer one, take the heavier one. OCU targets regulated enterprises; a lightweight-but-undocumented dependency loses the InfoSec review that gates the sale.
+
+## Bundled vs not-bundled
+
+Each accepted dependency is recorded as bundled or not-bundled when an ADR or component spec adopts it.
+
+- **Bundled** — OCU ships the binary, image, or library as part of a release. OCU owns its CVE response, version pinning, vulnerability scanning, and SBOM entry.
+- **Not bundled** — the customer provides it over a standard API (for example an IdP, a secret store, a SIEM, or a customer KMS). OCU documents the integration contract; the customer owns the lifecycle.
+
+The Bill of Materials is the table of accepted dependencies with this flag. It is not pre-populated: a row is added when the ADR or component spec that adopts a dependency lands, so the bundled/not-bundled call is made with the rationale that needs it, not in advance.
+
+| Dependency | Licence | Bundled | Adopted by |
+|---|---|---|---|
+| runc | Apache-2.0 | bundled | [ADR-0003](../adr/0003-sandbox-runtime-tier-ladder.md) |
+| gVisor (`runsc`) | Apache-2.0 (per-file MIT/BSD) | bundled | [ADR-0003](../adr/0003-sandbox-runtime-tier-ladder.md) |
+| Envoy | Apache-2.0 | bundled | [ADR-0005](../adr/0005-egress-credential-delivery-envoy-sds.md), [ADR-0006](../adr/0006-egress-forward-proxy-substrate.md) |
+
+## Rejected dependencies
+
+A rejection is first-class: recorded so it is not re-proposed. Each row names the reject reason and the path OCU takes instead. The adopting ADR re-verifies a row's licence fact against the dependency's own LICENSE before it cites the row.
+
+| Dependency | Reason | Instead |
+|---|---|---|
+| HashiCorp Vault | BUSL — reject as a bundled dependency | OpenBao (MPL-2.0) bundled; Vault permitted only as a customer-provided drop-in |
+| HashiCorp Boundary | BUSL (Community edition) | Customer-provided PAM/access plane; OCU stays a relying party |
+| Teleport | AGPLv3 source + commercial-only Community binaries | Customer-provided access plane; OCU stays a relying party |
+| Infisical (enterprise) | Core is MIT, but SSO/audit features are under a commercial licence | Treat as integrate-only; the audit/SSO features a regulated enterprise requires are behind the commercial gate |
+| MinIO | AGPL community edition | Customer S3-compatible store; Ceph RGW as the reference object store |
+| Zitadel (as primary IdP) | AGPL-3.0 | Keycloak (Apache-2.0) as the reference IdP relying-party target |
+| Redpanda | BSL | NATS JetStream (Apache-2.0) for the event bus |
+| mitmproxy / Squid ssl-bump (as the bump engine) | BSD / GPL-2.0+ — licence is not the blocker; adopting either as the egress bump engine drops the Envoy data plane (allow-list, OCSF audit, `ext_authz`) ADR-0006 placed there | Envoy data plane + a self-hosted SDS minting service for per-SNI leaves ([ADR-0007](../adr/0007-egress-auth-mechanism.md)); mitmproxy (BSD) recorded only as the fallback engine where the Envoy data plane is not needed |

package/docs/architecture/manifesto/06-starter-mode-policy.md

@@ -0,0 +1,49 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: draft
+last-reviewed: 2026-06-02
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+---
+
+When a feature limitation is an acceptable minimal-shelf trade-off versus a silent security gap that must be gated or labelled. Audience: architects reviewing a component spec or feature proposal for the solo / minimal-shelf tier.
+
+## Shelf split
+
+Both tiers ship the same six containers ([05-c4-container.md](../05-c4-container.md) §5); only the substrate and credential management differ.
+
+- **Minimal shelf** — single operator, self-signed per-deployment CA, file-system audit, host-rooted operator credential. The one-click `docker-compose up` path: no external IdP, no cloud credential, no pre-staged key.
+- **Full shelf** — customer IdP-asserted operator identity, customer-PKI-rooted signers, external SIEM sink, dynamic SDS credential minting.
+
+The runtime tier (`runc` / gVisor / microVM) is selected orthogonally by `workload_trust_profile`, not by the shelf (§"Tier versus shelf").
+
+The feature set is the same on both; every v1 GA feature must be demonstrable on the minimal shelf with defaults in place.
+
+## Acceptable limitation
+
+A limitation is acceptable only if it meets all three:
+
+1. **The minimal-shelf default does not block the primary workflow.** A solo developer or a hardening pilot builds agents, runs sessions, calls tools, and reads results with no configuration beyond `docker-compose up`.
+2. **The limitation is discoverable in config and docs.** Enabling an optional feature (external SIEM, credential rotation, DLP, a higher runtime tier) states what the minimal shelf trades away — a config comment or a startup log line, not silence.
+3. **No threat-model invariant erodes without explicit operator choice.** The solo path keeps the core locked in code: the guest holds no long-lived upstream secret ([NFR-SEC-23](02-nfrs.md)), audit events are hash-linked ([NFR-SEC-03](02-nfrs.md)), the kill-switch stays operative on the single-instance shelf ([NFR-SEC-01](02-nfrs.md), [NFR-SEC-55](02-nfrs.md)), and session limits hold — idle ≤15 min ([NFR-SEC-40](02-nfrs.md)), absolute ≤12 h ([NFR-SEC-41](02-nfrs.md)).
+
+## Unacceptable limitation
+
+Gate to full shelf, or label it a security gap, if:
+
+- **A core invariant degrades silently** — e.g. audit not hash-linked on solo (breaks NFR-SEC-03), or the guest reaching an upstream secret by default (breaks NFR-SEC-23).
+- **The primary workflow is blocked with no working alternative** — e.g. no way to authenticate an operator, or sessions that time out with no adjustable window.
+- **It is "not built yet", not an architectural choice** — unfinished work belongs in a backlog, not behind a starter-mode label.
+
+| Verdict | Example |
+|---|---|
+| Acceptable | The Storage broker on the minimal shelf holds a host-rooted backend key instead of per-session scoped credentials ([NFR-SEC-25](02-nfrs.md)); the full shelf brings scoped credentials, the trade is documented, and the sole path to it is the full shelf. |
+| Acceptable | The Egress trust-edge on the minimal shelf auto-generates a per-deployment CA instead of integrating a customer KMS ([ADR-0007](../adr/0007-egress-auth-mechanism.md)); a full-shelf deployer brings their PKI. |
+| Not acceptable | Audit not written on the minimal shelf because no external SIEM is configured. Audit is not optional; with the sink off, events still write to a local hash-chained store (NFR-SEC-03). |
+| Not acceptable | Session idle timeout hard-coded with no adjustable window, breaking the workflow. A knob defaulting conservatively is fine; no knob is not (NFR-SEC-40). |
+
+## Tier versus shelf
+
+The `workload_trust_profile` selects the sandbox runtime tier ([ADR-0003](../adr/0003-sandbox-runtime-tier-ladder.md), [NFR-SEC-38](02-nfrs.md)); the shelf is orthogonal. Both shelves carry every runtime tier where the host supports it, so a solo deployer can pick a hardened tier without leaving the minimal shelf. The shelf split is about how a credential reaches a component and the operational burden (IdP, SIEM), not about the guest isolation boundary.

package/docs/architecture/manifesto/07-governance.md

@@ -0,0 +1,60 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: draft
+last-reviewed: 2026-06-02
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+---
+
+How architectural decisions are recorded, approved, and superseded. Audience: reviewers deciding what merits a decision record, and auditors verifying decision lineage.
+
+## Decision routing
+
+Not every choice is an ADR. The decision tree in [`CLAUDE.md`](../../../CLAUDE.md) §"Architecture content routing" is the canonical router; the threshold for an ADR is step 3 — a load-bearing decision that is hard to reverse, crosses ≥2 components, or closes a debated option. Below that threshold, content lands in its NFR scenario, its component spec, the glossary, or an `## Open questions` entry with a tracking issue. A disagreement about the threshold itself is settled by an ADR that cites the routing rule it changes, not by editing this section.
+
+## ADR lifecycle
+
+An ADR moves through four states, recorded in its `status` front-matter.
+
+| State | Criteria | Next |
+|---|---|---|
+| **proposed** | PR open; options and rationale under review; front-matter complete, compliance- and license-impact populated | merge on consensus or owner decision → accepted |
+| **accepted** | PR merged; the decision is locked and every artifact citing it via `adr:` is production-ready | superseded, deprecated, or stays accepted |
+| **superseded** | a later ADR closes a question this one opened; the two cross-link (`superseded-by:` here, `supersedes:` there); the decision still holds for releases made under it | final |
+| **deprecated** | the decision no longer applies and has no direct successor (rare — a constraint changed and nothing replaces it) | final |
+
+No other states. There is no pre-PR "draft" for ADRs — the tracking issue (PROCESS.md step 1) is where discussion happens before the file exists. There is no "withdrawn": close the PR (the issue stays open for later), or merge with `status: deprecated` to record that the idea was evaluated and set aside.
+
+## Approval
+
+An ADR is approved by consensus or by named decision-maker, not by vote.
+
+- **Consensus** — the `owner` and all CODEOWNERS reviewers approve the PR; options are fairly evaluated and the consequences are acceptable.
+- **Decision-maker** — if good-faith discussion does not converge, the `owner` field names who decides; that approval is recorded in the PR description and the merge commit for the audit trail.
+
+The `owner` front-matter always names the decision-maker. The default for architecture ADRs is `@Wide-Moat/architects`; a specific handle is named when subject-matter authority is required.
+
+## Compliance lineage
+
+Two front-matter fields carry the regulatory audit trail when a decision touches compliance:
+
+- **`compliance-impact`** — the controls the decision touches, in the citation form the canon uses (`DORA-Art.28`, `NYDFS-500.15`, `SOC2-CC6.1`, `EU-AI-Act-Art.15`). Empty when not applicable; an empty field is not a non-compliance mark.
+- **`threat-mitigation-link`** — a pointer to the threat-model section or component spec showing how the decision mitigates a named threat.
+
+These let a compliance owner query the decision log by control and verify coverage. The decision audit trail they reconstruct is what DORA Art. 9 and NYDFS §500.15 require of the change-management record.
+
+## Re-evaluation
+
+An accepted ADR is not edited after merge. It is reconsidered when a constraint changes (a dependency is sunset, a regulatory requirement shifts), or a previously-unavailable alternative emerges, or a stakeholder raises a concern later — in each case a follow-up ADR with `supersedes: NNNN` revisits it and either confirms or overrides. No time-based auto-review; the release-readiness gate ([PROCESS.md](../PROCESS.md)) checks that the decision log is complete and no compliance- or buyer-facing ADR has drifted a major release without a re-evaluation note.
+
+## Citation discipline
+
+Every artifact that depends on an ADR records the link, and a supersession cascades through those links:
+
+- **Component specs** carry an `adr:` front-matter list (e.g. the Egress trust-edge spec cites `[0005, 0006, 0007]`).
+- **NFR rows** in [`02-nfrs.md`](02-nfrs.md) carry a `Source` column pointing to the deciding ADR or MANIFESTO section.
+- **Diagrams** record the driving ADR in the commit that changes them, not in the diagram body.
+
+When a new ADR supersedes an old one, the same PR updates every `adr:` field that cited the old number to cite the new — a cleanup commit, not a fresh decision.

package/docs/architecture/primitives-backlog.md

@@ -0,0 +1,51 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: draft
+last-reviewed: 2026-05-30
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+---
+
+Architectural primitives surfaced during research that Wide-Moat will need. Each entry drains into a concrete NFR (§02), principle (§03), or component spec — or escalates to a tracked GitHub issue. See [PROCESS.md](./PROCESS.md) "Capturing primitives discovered during research".
+
+## Active primitives
+
+- **Evidence-as-code bundle** — compliance artifacts (SBOM, SLSA L3 provenance, DORA RoI rows, EU AI Act Annex III conformity checklist, NYDFS contractual-clause completeness, audit-event schema) generated by CI on every release, not assembled under audit pressure — surfaced in `widemoat-thesis-advisor.md`; lands in §02 (NFR) + §03 (principle) + release-pipeline ADR.
+- **DORA Art. 28 RoI field-level traceability in BoM** — every dependency in `manifesto/05-licensing-posture.md` BoM table carries 7 required RoI fields: name, country, sub-contracting depth, function criticality, exit strategy, audit rights, data-residency. Reject-list captures dependencies that cannot supply these fields — surfaced in `reference_2026_regulator_triad`; lands in §05 (BoM rule).
+- **EU AI Act Annex III conformity checklist in release pipeline** — each GA release tags the Annex III risk categories it is configured for and blocks release if controls (logging, human oversight, accuracy metrics, post-market monitoring hooks) are missing — surfaced in `widemoat-thesis-advisor.md`; lands in release-pipeline ADR + §02 (NFR).
+- **Air-gap installer as CI artifact on every release** — tested in build; no phone-home — surfaced in legacy research; lands in deployment component spec + §03 (non-negotiable).
+- **`SkillProvider` abstraction (TBD)** — v1 ships zero default skills bundled; the contract stays TBD until proved; customers mount their own skill packs — surfaced in `project_widemoat_positioning`; lands in §04 (non-goal: skill registry deferred) + skill-host component spec stub.
+- **FSL `LICENSE-ADDITIONAL-PERMISSIONS.md` instrument** — published at repo root, irrevocable, 7 clauses (affiliates via 50% control test, JVs, outsourced operators, single-tenant managed, internal white-label, Competing Use reaffirmed, Apache-2.0 conversion) — surfaced in `advisor-fsl-internal-use.md`; lands in repo root + §05 (licensing-posture).
+
+## Promotion rules
+
+A primitive leaves this backlog when it appears either as:
+
+- A measurable target in `manifesto/02-nfrs.md` (e.g. "kill switch ≤30s wall-clock SLA, measured by …").
+- A principle + anti-example in `manifesto/03-non-negotiables.md`.
+- A component spec section in `components/<NN>-<name>.md`.
+- A BoM row in `manifesto/05-licensing-posture.md`.
+- A tracked GitHub issue when scope exceeds one line.
+
+When promoted, delete the entry from this file in the same PR that lands the destination artifact. The backlog shrinks monotonically.
+
+## Recently drained (2026-05-24)
+
+Removed because the primitive landed in §02 with a measurable target:
+
+- Kill switch ≤30s → NFR-SEC-01.
+- Per-session replay bundle → NFR-SEC-06.
+- Tamper-evident audit log → NFR-SEC-03.
+- WORM audit retention 7y/10y → NFR-COMP-01.
+- BYOK / HYOK via PKCS#11 + KMIP → NFR-SEC-04 + NFR-FLEX-04.
+- Identity = SPIFFE workload + OIDC + SCIM → NFR-SEC-09 + NFR-FLEX-03.
+- Single forward-proxy egress; the egress-wide-bump rung attaches the upstream credential on a per-deployment CA (ADR-0007) → NFR-SEC-05.
+- Egress allow-list (deny-by-default; any destination type) → NFR-SEC-08.
+
+## Removed as out-of-scope (2026-05-30)
+
+Dropped because the primitive is not OCU's concern, not because it landed:
+
+- `ModelProvider` abstraction → the agent loop and model choice live in the calling client (a Wide-Moat sibling component), not in OCU; an LLM is reached as one allow-listed egress endpoint. OCU hosts, selects, and proxies no model.

package/docs/architecture.svg

@@ -0,0 +1,117 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 520" font-family="Inter, -apple-system, system-ui, sans-serif">
+  <defs>
+    <style>
+      .box { rx: 10; stroke-width: 1.5; }
+      .label { font-size: 13px; font-weight: 600; fill: #fff; }
+      .sublabel { font-size: 10px; fill: rgba(255,255,255,0.8); }
+      .item { font-size: 10.5px; fill: #374151; }
+      .arrow { stroke: #94a3b8; stroke-width: 1.5; fill: none; marker-end: url(#arrowhead); }
+      .arrow-label { font-size: 9px; fill: #6b7280; }
+      .port { font-size: 9px; font-weight: 600; fill: #6b7280; }
+    </style>
+    <marker id="arrowhead" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L8,3 L0,6" fill="#94a3b8"/>
+    </marker>
+  </defs>
+
+  <!-- Background -->
+  <rect width="900" height="520" rx="12" fill="#fafbfc"/>
+
+  <!-- Client Layer -->
+  <rect x="250" y="15" width="400" height="55" class="box" fill="#f1f5f9" stroke="#cbd5e1"/>
+  <text x="450" y="38" text-anchor="middle" font-size="12" font-weight="600" fill="#475569">Any MCP Client</text>
+  <text x="450" y="54" text-anchor="middle" font-size="10" fill="#64748b">Open WebUI  ·  Claude Desktop  ·  LiteLLM  ·  n8n  ·  custom</text>
+
+  <!-- Arrow: Client → Server -->
+  <path d="M450,70 L450,105" class="arrow"/>
+  <text x="460" y="92" class="arrow-label">MCP over HTTP</text>
+
+  <!-- Computer Use Server -->
+  <rect x="160" y="105" width="580" height="155" class="box" fill="#1e40af" stroke="#1e3a8a"/>
+  <text x="450" y="128" text-anchor="middle" class="label">Computer Use Server</text>
+  <text x="450" y="142" text-anchor="middle" class="sublabel">MCP Orchestrator · FastAPI · :8081</text>
+
+  <!-- Server modules -->
+  <rect x="180" y="155" width="120" height="40" rx="6" fill="rgba(255,255,255,0.15)" stroke="rgba(255,255,255,0.3)"/>
+  <text x="240" y="172" text-anchor="middle" font-size="10" font-weight="600" fill="#fff">MCP Tools</text>
+  <text x="240" y="185" text-anchor="middle" font-size="8.5" fill="rgba(255,255,255,0.7)">bash · view · create</text>
+
+  <rect x="315" y="155" width="120" height="40" rx="6" fill="rgba(255,255,255,0.15)" stroke="rgba(255,255,255,0.3)"/>
+  <text x="375" y="172" text-anchor="middle" font-size="10" font-weight="600" fill="#fff">File Server</text>
+  <text x="375" y="185" text-anchor="middle" font-size="8.5" fill="rgba(255,255,255,0.7)">upload · preview · zip</text>
+
+  <rect x="450" y="155" width="120" height="40" rx="6" fill="rgba(255,255,255,0.15)" stroke="rgba(255,255,255,0.3)"/>
+  <text x="510" y="172" text-anchor="middle" font-size="10" font-weight="600" fill="#fff">CDP Proxy</text>
+  <text x="510" y="185" text-anchor="middle" font-size="8.5" fill="rgba(255,255,255,0.7)">browser streaming</text>
+
+  <rect x="585" y="155" width="140" height="40" rx="6" fill="rgba(255,255,255,0.15)" stroke="rgba(255,255,255,0.3)"/>
+  <text x="655" y="172" text-anchor="middle" font-size="10" font-weight="600" fill="#fff">Terminal Proxy</text>
+  <text x="655" y="185" text-anchor="middle" font-size="8.5" fill="rgba(255,255,255,0.7)">ttyd · Claude Code</text>
+
+  <!-- Server bottom row -->
+  <rect x="180" y="205" width="170" height="35" rx="6" fill="rgba(255,255,255,0.1)" stroke="rgba(255,255,255,0.2)"/>
+  <text x="265" y="222" text-anchor="middle" font-size="10" font-weight="500" fill="rgba(255,255,255,0.9)">Skill Manager</text>
+  <text x="265" y="233" text-anchor="middle" font-size="8" fill="rgba(255,255,255,0.6)">13 public + user skills</text>
+
+  <rect x="365" y="205" width="170" height="35" rx="6" fill="rgba(255,255,255,0.1)" stroke="rgba(255,255,255,0.2)"/>
+  <text x="450" y="222" text-anchor="middle" font-size="10" font-weight="500" fill="rgba(255,255,255,0.9)">Docker Manager</text>
+  <text x="450" y="233" text-anchor="middle" font-size="8" fill="rgba(255,255,255,0.6)">create · stop · cleanup</text>
+
+  <rect x="550" y="205" width="175" height="35" rx="6" fill="rgba(255,255,255,0.1)" stroke="rgba(255,255,255,0.2)"/>
+  <text x="637" y="222" text-anchor="middle" font-size="10" font-weight="500" fill="rgba(255,255,255,0.9)">System Prompt Builder</text>
+  <text x="637" y="233" text-anchor="middle" font-size="8" fill="rgba(255,255,255,0.6)">dynamic skills XML</text>
+
+  <!-- Arrow: Server → Container -->
+  <path d="M450,260 L450,295" class="arrow"/>
+  <text x="460" y="282" class="arrow-label">Docker Socket</text>
+
+  <!-- Sandbox Container -->
+  <rect x="60" y="295" width="780" height="200" class="box" fill="#0f766e" stroke="#0d9488"/>
+  <text x="450" y="318" text-anchor="middle" class="label">Sandbox Container (one per chat)</text>
+  <text x="450" y="332" text-anchor="middle" class="sublabel">Ubuntu 24.04 · Python 3.12 · Node.js 22 · Java 21</text>
+
+  <!-- Container features grid -->
+  <!-- Row 1 -->
+  <rect x="80" y="345" width="145" height="55" rx="6" fill="rgba(255,255,255,0.12)" stroke="rgba(255,255,255,0.25)"/>
+  <text x="152" y="365" text-anchor="middle" font-size="10" font-weight="600" fill="#fff">Documents</text>
+  <text x="152" y="378" text-anchor="middle" font-size="8.5" fill="rgba(255,255,255,0.7)">LibreOffice · Pandoc</text>
+  <text x="152" y="390" text-anchor="middle" font-size="8.5" fill="rgba(255,255,255,0.7)">docx · pptx · xlsx · pdf</text>
+
+  <rect x="240" y="345" width="145" height="55" rx="6" fill="rgba(255,255,255,0.12)" stroke="rgba(255,255,255,0.25)"/>
+  <text x="312" y="365" text-anchor="middle" font-size="10" font-weight="600" fill="#fff">Browser</text>
+  <text x="312" y="378" text-anchor="middle" font-size="8.5" fill="rgba(255,255,255,0.7)">Chromium + Playwright</text>
+  <text x="312" y="390" text-anchor="middle" font-size="8.5" fill="rgba(255,255,255,0.7)">CDP :9222 live stream</text>
+
+  <rect x="400" y="345" width="145" height="55" rx="6" fill="rgba(255,255,255,0.12)" stroke="rgba(255,255,255,0.25)"/>
+  <text x="472" y="365" text-anchor="middle" font-size="10" font-weight="600" fill="#fff">Claude Code</text>
+  <text x="472" y="378" text-anchor="middle" font-size="8.5" fill="rgba(255,255,255,0.7)">Sub-agent · TTY · MCP</text>
+  <text x="472" y="390" text-anchor="middle" font-size="8.5" fill="rgba(255,255,255,0.7)">Autonomous execution</text>
+
+  <rect x="560" y="345" width="135" height="55" rx="6" fill="rgba(255,255,255,0.12)" stroke="rgba(255,255,255,0.25)"/>
+  <text x="627" y="365" text-anchor="middle" font-size="10" font-weight="600" fill="#fff">Media</text>
+  <text x="627" y="378" text-anchor="middle" font-size="8.5" fill="rgba(255,255,255,0.7)">FFmpeg · ImageMagick</text>
+  <text x="627" y="390" text-anchor="middle" font-size="8.5" fill="rgba(255,255,255,0.7)">Tesseract OCR</text>
+
+  <rect x="710" y="345" width="115" height="55" rx="6" fill="rgba(255,255,255,0.12)" stroke="rgba(255,255,255,0.25)"/>
+  <text x="767" y="365" text-anchor="middle" font-size="10" font-weight="600" fill="#fff">Dev Tools</text>
+  <text x="767" y="378" text-anchor="middle" font-size="8.5" fill="rgba(255,255,255,0.7)">Git · glab · Bun</text>
+  <text x="767" y="390" text-anchor="middle" font-size="8.5" fill="rgba(255,255,255,0.7)">TypeScript · Mermaid</text>
+
+  <!-- Row 2: Mounts -->
+  <text x="80" y="425" font-size="9" font-weight="600" fill="rgba(255,255,255,0.9)">Mounts:</text>
+  <text x="135" y="425" font-size="9" fill="rgba(255,255,255,0.65)">/mnt/skills (read-only) · /mnt/user-data/uploads (read-only) · /mnt/user-data/outputs (read-write → served via HTTP)</text>
+
+  <!-- Row 3: Features -->
+  <text x="80" y="445" font-size="9" font-weight="600" fill="rgba(255,255,255,0.9)">Limits:</text>
+  <text x="125" y="445" font-size="9" fill="rgba(255,255,255,0.65)">2 GB RAM · 1 CPU · idle timeout auto-shutdown · network access enabled</text>
+
+  <!-- Row 4 -->
+  <text x="80" y="465" font-size="9" font-weight="600" fill="rgba(255,255,255,0.9)">Skills:</text>
+  <text x="122" y="465" font-size="9" fill="rgba(255,255,255,0.65)">docx · pdf · pptx · xlsx · playwright-cli · sub-agent · gitlab-explorer · describe-image · frontend-design · ...</text>
+
+  <text x="80" y="485" font-size="9" font-weight="600" fill="rgba(255,255,255,0.9)">Ports:</text>
+  <text x="120" y="485" font-size="9" fill="rgba(255,255,255,0.65)">9222 (CDP browser) · 7681 (ttyd terminal) — proxied through server, not exposed directly</text>
+
+  <!-- Footer -->
+  <text x="450" y="512" text-anchor="middle" font-size="10" fill="#9ca3af">open-computer-use · github.com/Yambr/open-computer-use</text>
+</svg>

package/docs/claude-code-gateway.md

@@ -0,0 +1,173 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# Claude Code Gateway Configuration
+
+Every sandbox container spawned by Open Computer Use runs the Claude Code CLI
+as a sub-agent (via the `sub_agent` MCP tool). Operators choose where that
+CLI sends its API traffic by setting a handful of host-side environment
+variables before `docker compose up`. Three paths are supported; each is
+additive - set only what your deployment needs.
+
+## Supported paths at a glance
+
+| Path | Operator sets on host | Claude Code inside sandbox |
+|------|------------------------|----------------------------|
+| **A - Zero-config** | Nothing | Shows the native `/login` OAuth flow in the terminal |
+| **B - Public Anthropic** | `ANTHROPIC_AUTH_TOKEN` | Talks to `https://api.anthropic.com` with the supplied token |
+| **C - Custom gateway** | `ANTHROPIC_AUTH_TOKEN` + `ANTHROPIC_BASE_URL` + optional compatibility flags | Talks to the gateway (LiteLLM / Azure / Bedrock) with the gateway-scoped token |
+
+## Path A - Zero-config (stock Claude Code /login)
+
+Leave every `ANTHROPIC_*` and `CLAUDE_CODE_*` variable unset on the host.
+`docker compose up` starts the orchestrator with no auth env vars in its
+`Env`. When the user triggers `sub_agent` from Open WebUI, Claude Code
+launches inside the sandbox and prompts for OAuth login in the ttyd
+terminal - the same experience as running `claude` on a fresh laptop.
+
+Nothing else to configure. This is the default and will keep working even
+if you never touch this file.
+
+## Path B - Public Anthropic with your own key
+
+Add one line to `.env`:
+
+```
+ANTHROPIC_AUTH_TOKEN=sk-EXAMPLE-replace-with-your-anthropic-key
+# ANTHROPIC_BASE_URL defaults to https://api.anthropic.com when unset
+```
+
+Restart the orchestrator (`docker compose up -d computer-use-server`).
+Every sandbox container created after that will receive the token, and
+Claude Code will talk straight to Anthropic's public API with no login
+prompt.
+
+This is the simplest paid path. The token is scoped to your Anthropic
+account; no gateway sits in between. See
+<https://code.claude.com/docs/en/env-vars> for the canonical variable
+reference.
+
+## Path C - Custom gateway (LiteLLM, Azure, Bedrock)
+
+Point Claude Code at a gateway with a worked LiteLLM recipe:
+
+```
+ANTHROPIC_AUTH_TOKEN=sk-EXAMPLE-litellm-master-key
+ANTHROPIC_BASE_URL=https://litellm.internal/anthropic
+CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
+DISABLE_PROMPT_CACHING=1
+ANTHROPIC_DEFAULT_SONNET_MODEL=anthropic/claude-sonnet-4-6
+ANTHROPIC_DEFAULT_OPUS_MODEL=anthropic/claude-opus-4-6
+ANTHROPIC_DEFAULT_HAIKU_MODEL=anthropic/claude-haiku-4-5
+```
+
+What each variable does:
+
+| Variable | Purpose |
+|----------|---------|
+| `ANTHROPIC_AUTH_TOKEN` | Gateway master key (LiteLLM `master_key`, Azure API key, etc.) |
+| `ANTHROPIC_BASE_URL` | Gateway endpoint that speaks the Anthropic HTTP API shape |
+| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Set to `1` when the gateway does not forward Anthropic's beta headers |
+| `DISABLE_PROMPT_CACHING` | Set to `1` when the gateway does not support `cache_control` blocks |
+| `ANTHROPIC_DEFAULT_*_MODEL` | Override the model alias for `sub_agent("sonnet"/"opus"/"haiku")` requests |
+
+The full LiteLLM recipe, including which settings are mandatory for which
+backend, is at <https://code.claude.com/docs/en/llm-gateway>.
+
+### Azure / Bedrock via LiteLLM
+
+Claude Code does not speak Azure OpenAI or AWS Bedrock natively, but it
+speaks the Anthropic API shape - and LiteLLM translates. Stand up a LiteLLM
+proxy, register the Azure or Bedrock deployments there, and point Claude
+Code at LiteLLM. Typical model-ID overrides look like
+`azure/my-sonnet-deployment` or
+`bedrock/anthropic.claude-sonnet-4-20250514-v1:0`; put them in the
+`ANTHROPIC_DEFAULT_*_MODEL` vars above so every `sub_agent` call
+automatically routes to the right deployment.
+
+## Full variable reference
+
+| Variable | Type | Default | Purpose | Example (placeholder) |
+|----------|------|---------|---------|-----------------------|
+| `ANTHROPIC_AUTH_TOKEN` | secret | unset | Bearer token for Anthropic / gateway | `sk-EXAMPLE-gateway-key` |
+| `ANTHROPIC_BASE_URL` | URL | `https://api.anthropic.com` when `ANTHROPIC_AUTH_TOKEN` is set, otherwise unset | Where Claude Code sends requests | `https://litellm.internal/anthropic` |
+| `ANTHROPIC_MODEL` | string | unset | Global default model for Claude Code | `anthropic/claude-sonnet-4-6` |
+| `ANTHROPIC_DEFAULT_SONNET_MODEL` | string | unset | Override for `sub_agent("sonnet")` | `azure/my-sonnet-deployment` |
+| `ANTHROPIC_DEFAULT_OPUS_MODEL` | string | unset | Override for `sub_agent("opus")` | `anthropic/claude-opus-4-6` |
+| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | string | unset | Override for `sub_agent("haiku")` | `anthropic/claude-haiku-4-5` |
+| `CLAUDE_CODE_SUBAGENT_MODEL` | string | unset | Model for Claude Code's internal sub-agents | `anthropic/claude-haiku-4-5` |
+| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | flag | unset | Strip beta headers on outgoing requests | `1` |
+| `DISABLE_PROMPT_CACHING` | flag | unset | Disable `cache_control` globally | `1` |
+| `DISABLE_PROMPT_CACHING_SONNET` | flag | unset | Disable prompt caching for Sonnet only | `1` |
+| `DISABLE_PROMPT_CACHING_OPUS` | flag | unset | Disable prompt caching for Opus only | `1` |
+| `DISABLE_PROMPT_CACHING_HAIKU` | flag | unset | Disable prompt caching for Haiku only | `1` |
+
+All of these are official Claude Code environment variables - see
+<https://code.claude.com/docs/en/env-vars> for the upstream reference.
+Open Computer Use passes them through unchanged when (and only when)
+the operator sets them on the host.
+
+## Verifying your gateway setup
+
+1. Confirm the variables are in your `.env`:
+   ```bash
+   grep -E '^(ANTHROPIC|CLAUDE_CODE|DISABLE_PROMPT_CACHING)' .env
+   ```
+2. Recreate the orchestrator container so it picks up the new env:
+   ```bash
+   docker compose up -d computer-use-server
+   ```
+3. Confirm the orchestrator itself received the vars:
+   ```bash
+   docker inspect computer-use-server --format '{{range .Config.Env}}{{println .}}{{end}}' | grep -E '^(ANTHROPIC|CLAUDE_CODE|DISABLE_PROMPT_CACHING)'
+   ```
+4. Trigger a `sub_agent` call from the Computer Use tool inside Open
+   WebUI (any short task - "list files in /tmp" is enough).
+5. Confirm the sandbox container received the expected subset:
+   ```bash
+   docker exec owui-chat-<chatid> env | grep -E '^(ANTHROPIC|CLAUDE_CODE|DISABLE_PROMPT_CACHING)'
+   ```
+6. On Paths B and C the sub-agent should stream output without showing a
+   `/login` prompt. If it still prompts, go to Troubleshooting.
+
+## Troubleshooting
+
+### "The sub-agent keeps asking me to `/login` even though I set `ANTHROPIC_AUTH_TOKEN`."
+
+Two checks, in order:
+
+1. Confirm the orchestrator container actually received the env variable
+   via step 3 of the verification checklist. If it is missing, make sure
+   `ANTHROPIC_AUTH_TOKEN` is declared under
+   `services.computer-use-server.environment:` in `docker-compose.yml`
+   (it is, on current `main`) and that you recreated the container after
+   editing `.env`. `docker compose up -d` does not pick up `.env` changes
+   on already-running services without `--force-recreate` or `down`/`up`.
+2. Confirm you are on a version with the Phase 3 `context_vars.py` fix
+   (<https://github.com/Wide-Moat/open-computer-use/issues/40>). Earlier
+   versions had a ContextVar default of `"https://api.anthropic.com/"`
+   that short-circuited the `or os.environ["ANTHROPIC_BASE_URL"]` fallback
+   in `docker_manager`. Symptom: the sandbox received
+   `ANTHROPIC_BASE_URL=https://api.anthropic.com/` (with a stray trailing
+   slash) but `ANTHROPIC_AUTH_TOKEN` was not injected.
+
+### "LiteLLM returns 400 about prompt caching."
+
+LiteLLM typically does not forward Anthropic's `cache_control` blocks to
+the upstream model; Claude Code sends them by default. Set
+`DISABLE_PROMPT_CACHING=1` on the host. If you route different model
+families through different upstreams, use the per-family flags
+(`DISABLE_PROMPT_CACHING_SONNET`, `_OPUS`, `_HAIKU`) instead of the
+global one.
+
+### "LiteLLM returns 400 about beta / experimental headers."
+
+Set `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`. This strips the
+`anthropic-beta` header Claude Code adds on newer features that gateways
+may not forward yet.
+
+## Further reading
+
+- Claude Code env var reference - <https://code.claude.com/docs/en/env-vars>
+- LLM gateway / LiteLLM recipe - <https://code.claude.com/docs/en/llm-gateway>
+- Model configuration and aliases - <https://code.claude.com/docs/en/model-config>