@mseep/open-computer-use 1.0.0

package/docs/cli-config-templates.md

@@ -0,0 +1,240 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# CLI Config Templates
+
+Companion reference for [docs/multi-cli.md](multi-cli.md). Copy-paste config snippets for the gray-area knobs the in-image entrypoint does NOT render by default — Azure routing, approval modes, MCP federation, custom OpenAI-compat gateways behind nginx, opencode personas.
+
+The image entrypoint renders a **minimal viable** config so first-boot works for the common case. Anything beyond minimal goes through one of two operator hooks:
+
+- `OPENCODE_CONFIG_EXTRA` — full JSON contents for `/tmp/opencode.json`. When set, **replaces** the canonical block (no merging — opencode JSON has no merge story).
+- `CODEX_CONFIG_EXTRA` — TOML fragment **appended** to `~/.codex/config.toml` after the canonical block. Append-only because TOML supports independent table sections side-by-side.
+
+Both are env vars (no plaintext secrets on disk; values can be sourced from `.env` and rendered with `{env:VAR}` substitution where the consumer supports it).
+
+If you don't set either: the image renders today's defaults exactly as before. Backwards-compatible.
+
+---
+
+## Codex — Azure OpenAI
+
+Operators on Azure OpenAI use a different `wire_api` and a per-deployment `base_url`. Source: [openai/codex docs — model_providers](https://developers.openai.com/codex).
+
+```bash
+# .env
+SUBAGENT_CLI=codex
+OPENAI_API_KEY="<your-azure-key>"
+# Note: do NOT set OPENAI_BASE_URL — that's for the generic custom gateway.
+# Azure goes through CODEX_CONFIG_EXTRA below so wire_api can be "chat".
+CODEX_CONFIG_EXTRA='
+model_provider = "azure"
+
+[model_providers.azure]
+name = "azure"
+base_url = "https://<resource>.openai.azure.com/openai/deployments/<deployment>"
+env_key = "OPENAI_API_KEY"
+wire_api = "chat"
+query_params = { "api-version" = "2024-08-01-preview" }
+requires_openai_auth = true
+'
+```
+
+Verify after `docker compose up`:
+
+```bash
+docker exec -it computer-use-server cat /home/assistant/.codex/config.toml
+# Expect both the canonical [model_providers.custom] block (empty if no
+# OPENAI_BASE_URL) AND the Azure block appended below.
+```
+
+---
+
+## Codex — Approval & sandbox modes
+
+By default the entrypoint relies on `--full-auto` in the adapter argv (see `cli_adapters/codex.py`). Operators wanting interactive approval, or a tighter sandbox, set the defaults in config so they apply when the operator drives the CLI from the ttyd terminal too:
+
+```bash
+CODEX_CONFIG_EXTRA='
+approval_policy = "on-request"     # never | on-request | unless-trusted
+sandbox_mode    = "workspace-write" # read-only | workspace-write | danger-full-access
+'
+```
+
+The adapter's `--full-auto` continues to override these for sub-agent invocations (intentional — sub-agents must not block on user input).
+
+---
+
+## Codex — Custom OpenAI-compat gateway behind nginx
+
+The simplest case (`OPENAI_BASE_URL=https://gateway.internal/v1`) is rendered by the entrypoint automatically. The advanced case (per-route auth, custom headers) needs `CODEX_CONFIG_EXTRA`:
+
+```bash
+SUBAGENT_CLI=codex
+OPENAI_API_KEY="<gateway-token>"
+CODEX_CONFIG_EXTRA='
+model_provider = "internal-gw"
+
+[model_providers.internal-gw]
+name = "internal-gw"
+base_url = "https://gateway.internal/v1"
+env_key = "OPENAI_API_KEY"
+wire_api = "responses"
+requires_openai_auth = true
+http_headers = { "X-Tenant-ID" = "research-team" }
+'
+```
+
+Auth headers go in `http_headers`, never `env`. Avoid baking secrets into the table — use `env_key` to point at the env var name.
+
+---
+
+## OpenCode — instructions (system-prompt federation)
+
+The entrypoint's canonical config has no `instructions[]`. Operators wanting a shared global system prompt (loaded for every opencode invocation in the container) supply the full JSON:
+
+```bash
+SUBAGENT_CLI=opencode
+OPENROUTER_API_KEY="<key>"
+OPENCODE_CONFIG_EXTRA='{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "openrouter": { "options": { "apiKey": "{env:OPENROUTER_API_KEY}" } }
+  },
+  "model": "openrouter/qwen/qwen-3-coder",
+  "instructions": [
+    "You are a sub-agent inside the Open Computer Use sandbox.",
+    "All work happens under /home/assistant. Never touch /mnt/skills."
+  ]
+}'
+```
+
+Verify:
+
+```bash
+docker exec -it computer-use-server cat /tmp/opencode.json
+# Expect exactly your override — no merging with the canonical block.
+```
+
+---
+
+## OpenCode — MCP federation (sub-agent CLI calls back into host MCP)
+
+Use this when you want the opencode sub-agent to invoke MCP tools on the host orchestrator (e.g. to use `take_screenshot` or browse-spec tools without leaving the sub-agent loop):
+
+```bash
+OPENCODE_CONFIG_EXTRA='{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "openrouter": { "options": { "apiKey": "{env:OPENROUTER_API_KEY}" } }
+  },
+  "model": "openrouter/qwen/qwen-3-coder",
+  "mcp": {
+    "computer-use": {
+      "type": "remote",
+      "url": "http://computer-use-server:8081/mcp",
+      "enabled": true
+    }
+  }
+}'
+```
+
+Caveats:
+
+- The opencode container reaches the orchestrator via the docker-compose service name (`computer-use-server`), NOT `localhost`.
+- The host MCP must accept the same auth scope as the host orchestrator's `MCP_API_KEY`. Set it explicitly in the MCP server config or pass via `headers`.
+
+---
+
+## OpenCode — custom OpenAI-compat provider
+
+Mirror of the Phase 9.1 mock LLM smoke test, useful for pointing opencode at a corporate gateway:
+
+```bash
+OPENCODE_CONFIG_EXTRA='{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "internal-gw": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Internal OpenAI gateway",
+      "options": {
+        "baseURL": "https://gateway.internal/v1",
+        "apiKey": "{env:GATEWAY_TOKEN}"
+      },
+      "models": {
+        "qwen-3-coder": { "name": "Qwen 3 Coder" }
+      }
+    }
+  },
+  "model": "internal-gw/qwen-3-coder"
+}'
+```
+
+Set the matching env var in `.env`:
+
+```bash
+GATEWAY_TOKEN="<your-token>"
+SUBAGENT_CLI=opencode
+```
+
+---
+
+## OpenCode — agent personas
+
+Operators wanting predefined personas (e.g. a "code-reviewer" agent and a "test-writer" agent) define them in config and dispatch via `opencode run --agent <name>`:
+
+```bash
+OPENCODE_CONFIG_EXTRA='{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "openrouter": { "options": { "apiKey": "{env:OPENROUTER_API_KEY}" } }
+  },
+  "model": "openrouter/qwen/qwen-3-coder",
+  "agent": {
+    "code-reviewer": {
+      "model": "openrouter/anthropic/claude-sonnet-4.5",
+      "instructions": ["You review code. You never write code yourself."]
+    },
+    "test-writer": {
+      "model": "openrouter/qwen/qwen-3-coder",
+      "instructions": ["You write tests. Always pytest, never unittest."]
+    }
+  }
+}'
+```
+
+Note: the orchestrator adapter (`cli_adapters/opencode.py`) does NOT pass `--agent` today. To dispatch a specific persona from the host MCP, an adapter change is required (deferred to a future phase).
+
+---
+
+## Verification recipe (any of the above)
+
+```bash
+# 1. Update .env, restart the stack so the entrypoint re-renders.
+docker compose down
+docker compose up -d
+
+# 2. Inspect the rendered config.
+docker exec -it computer-use-server cat /tmp/opencode.json
+docker exec -it computer-use-server cat /home/assistant/.codex/config.toml
+
+# 3. Smoke the CLI inside the sandbox container (one-off).
+docker exec -it computer-use-server bash -lc \
+  'SUBAGENT_CLI=opencode opencode run "Say hello." --format json | tail -5'
+
+# 4. Trigger a real sub-agent call from the host MCP and watch the orchestrator
+#    logs for "[SUB-AGENT]" lines confirming the chosen CLI.
+docker compose logs -f computer-use-server | grep -i sub-agent
+```
+
+If the rendered config contains the snippet you set in `*_CONFIG_EXTRA` and the CLI exits 0 on the smoke step, the override is live.
+
+---
+
+## What this doc does NOT do
+
+- Render configs for you. The entrypoint does that — this doc only documents the override knobs.
+- Cover Claude Code config. `claude` reads `~/.claude.json` automatically; the entrypoint does not write a config for it. Use the standard Claude Code config docs.
+- Replace `docs/multi-cli.md`. Read that first to understand the basic flip; this doc is for the operator who has already shipped the basic case and wants to push further.
+
+For the basic per-CLI flip and `.env.example` block, see [`docs/multi-cli.md`](multi-cli.md).
+For known limitations and follow-up phases, see [`CHANGELOG.md`](../CHANGELOG.md).

package/docs/data-flow.svg

@@ -0,0 +1,72 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 500 520" font-family="Inter, -apple-system, system-ui, sans-serif">
+  <defs>
+    <style>
+      .box { rx: 10; stroke-width: 1.5; }
+      .label { font-size: 12px; font-weight: 600; fill: #fff; }
+      .sublabel { font-size: 9px; fill: rgba(255,255,255,0.75); }
+      .arrow { stroke: #94a3b8; stroke-width: 1.8; fill: none; marker-end: url(#ah4); }
+      .arrow-label { font-size: 9px; fill: #6b7280; font-weight: 500; }
+    </style>
+    <marker id="ah4" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L8,3 L0,6" fill="#94a3b8"/>
+    </marker>
+  </defs>
+
+  <rect width="500" height="520" rx="12" fill="#fafbfc"/>
+  <text x="250" y="24" text-anchor="middle" font-size="13" font-weight="700" fill="#1e293b">Data Flow: Volumes → Server → Chat</text>
+
+  <!-- Docker Volume -->
+  <rect x="50" y="45" width="400" height="120" class="box" fill="#475569" stroke="#334155"/>
+  <text x="250" y="68" text-anchor="middle" class="label">Docker Volume: user-data-{chat_id}</text>
+
+  <!-- uploads -->
+  <rect x="75" y="85" width="100" height="55" rx="6" fill="rgba(255,255,255,0.15)" stroke="rgba(255,255,255,0.3)"/>
+  <text x="125" y="105" text-anchor="middle" font-size="10" font-weight="600" fill="#fff">uploads/</text>
+  <text x="125" y="120" text-anchor="middle" font-size="8" fill="rgba(255,255,255,0.7)">read-only</text>
+  <text x="125" y="132" text-anchor="middle" font-size="8" fill="rgba(255,255,255,0.7)">user files</text>
+
+  <!-- outputs -->
+  <rect x="200" y="85" width="100" height="55" rx="6" fill="rgba(255,255,255,0.15)" stroke="rgba(255,255,255,0.3)"/>
+  <text x="250" y="105" text-anchor="middle" font-size="10" font-weight="600" fill="#fff">outputs/</text>
+  <text x="250" y="120" text-anchor="middle" font-size="8" fill="rgba(255,255,255,0.7)">read-write</text>
+  <text x="250" y="132" text-anchor="middle" font-size="8" fill="rgba(255,255,255,0.7)">AI results</text>
+
+  <!-- .claude -->
+  <rect x="325" y="85" width="100" height="55" rx="6" fill="rgba(255,255,255,0.15)" stroke="rgba(255,255,255,0.3)"/>
+  <text x="375" y="105" text-anchor="middle" font-size="10" font-weight="600" fill="#fff">.claude/</text>
+  <text x="375" y="120" text-anchor="middle" font-size="8" fill="rgba(255,255,255,0.7)">sessions</text>
+  <text x="375" y="132" text-anchor="middle" font-size="8" fill="rgba(255,255,255,0.7)">config</text>
+
+  <!-- Arrow: Volume → Container -->
+  <path d="M250,165 L250,205" class="arrow"/>
+  <text x="290" y="190" class="arrow-label">bind mount</text>
+
+  <!-- Sandbox Container -->
+  <rect x="100" y="205" width="300" height="70" class="box" fill="#0f766e" stroke="#0d9488"/>
+  <text x="250" y="232" text-anchor="middle" class="label">Sandbox Container</text>
+  <text x="250" y="250" text-anchor="middle" class="sublabel">/mnt/user-data/uploads/ (RO) · /mnt/user-data/outputs/ (RW)</text>
+  <text x="250" y="263" text-anchor="middle" class="sublabel">AI writes files here → auto-served via HTTP</text>
+
+  <!-- Arrow: Container → Server -->
+  <path d="M250,275 L250,315" class="arrow"/>
+  <text x="290" y="300" class="arrow-label">HTTP</text>
+
+  <!-- Computer Use Server -->
+  <rect x="100" y="315" width="300" height="70" class="box" fill="#1e40af" stroke="#1e3a8a"/>
+  <text x="250" y="342" text-anchor="middle" class="label">Computer Use Server</text>
+  <text x="250" y="360" text-anchor="middle" class="sublabel">/files/{chat_id}/{filename} · /api/outputs/{chat_id}/</text>
+  <text x="250" y="373" text-anchor="middle" class="sublabel">Preview renderer · Zip download</text>
+
+  <!-- Arrow: Server → Chat -->
+  <path d="M250,385 L250,425" class="arrow"/>
+  <text x="290" y="410" class="arrow-label">links in response</text>
+
+  <!-- Open WebUI -->
+  <rect x="100" y="425" width="300" height="65" class="box" fill="#6366f1" stroke="#4f46e5"/>
+  <text x="250" y="452" text-anchor="middle" class="label">Open WebUI (chat)</text>
+  <text x="250" y="470" text-anchor="middle" class="sublabel">Clickable HTTP URLs · Side panel preview · Zip archive button</text>
+  <text x="250" y="483" text-anchor="middle" class="sublabel">Files do NOT upload back into chat</text>
+
+  <!-- Side note -->
+  <text x="250" y="510" text-anchor="middle" font-size="9" fill="#64748b">Volume persists across container restarts · Cleaned up after idle timeout</text>
+</svg>

package/docs/dynamic-skills.svg

@@ -0,0 +1,77 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 750 420" font-family="Inter, -apple-system, system-ui, sans-serif">
+  <defs>
+    <style>
+      .box { rx: 8; stroke-width: 1.5; }
+      .label { font-size: 12px; font-weight: 600; fill: #fff; }
+      .sublabel { font-size: 9px; fill: rgba(255,255,255,0.75); }
+      .item { font-size: 10px; fill: #374151; }
+      .item-bold { font-size: 10px; font-weight: 600; fill: #1f2937; }
+      .arrow { stroke: #94a3b8; stroke-width: 1.5; fill: none; marker-end: url(#ah); }
+      .arrow-label { font-size: 8.5px; fill: #6b7280; }
+    </style>
+    <marker id="ah" markerWidth="7" markerHeight="5" refX="7" refY="2.5" orient="auto">
+      <path d="M0,0 L7,2.5 L0,5" fill="#94a3b8"/>
+    </marker>
+  </defs>
+
+  <rect width="750" height="420" rx="10" fill="#fafbfc"/>
+
+  <!-- Settings Wrapper (optional) -->
+  <rect x="260" y="15" width="230" height="50" class="box" fill="#8b5cf6" stroke="#7c3aed"/>
+  <text x="375" y="37" text-anchor="middle" class="label">Settings Wrapper</text>
+  <text x="375" y="52" text-anchor="middle" class="sublabel">Optional · per-user skills + PATs</text>
+
+  <!-- Arrows down -->
+  <path d="M320,65 L320,100" class="arrow"/>
+  <text x="270" y="87" class="arrow-label">user-config</text>
+  <path d="M430,65 L430,100" class="arrow"/>
+  <text x="440" y="87" class="arrow-label">skill ZIP</text>
+
+  <!-- Skill Manager -->
+  <rect x="200" y="100" width="350" height="55" class="box" fill="#2563eb" stroke="#1d4ed8"/>
+  <text x="375" y="122" text-anchor="middle" class="label">skill_manager.py</text>
+  <text x="375" y="138" text-anchor="middle" class="sublabel">3-level fallback: memory cache → API → disk cache → defaults</text>
+
+  <!-- Outputs from skill manager -->
+  <!-- Left: XML -->
+  <path d="M250,155 L250,195" class="arrow"/>
+  <rect x="130" y="195" width="240" height="45" class="box" fill="#f1f5f9" stroke="#cbd5e1"/>
+  <text x="250" y="215" text-anchor="middle" class="item-bold">&lt;available_skills&gt; XML</text>
+  <text x="250" y="230" text-anchor="middle" class="item">Injected into system prompt</text>
+
+  <!-- Right: Mounts -->
+  <path d="M500,155 L500,195" class="arrow"/>
+  <rect x="380" y="195" width="240" height="45" class="box" fill="#f1f5f9" stroke="#cbd5e1"/>
+  <text x="500" y="215" text-anchor="middle" class="item-bold">Docker Volume Mounts</text>
+  <text x="500" y="230" text-anchor="middle" class="item">/mnt/skills/user/{name} (read-only)</text>
+
+  <!-- Arrow to container -->
+  <path d="M250,240 L250,280" class="arrow"/>
+  <path d="M500,240 L500,280" class="arrow"/>
+
+  <!-- Container -->
+  <rect x="60" y="280" width="630" height="90" class="box" fill="#0f766e" stroke="#0d9488"/>
+  <text x="375" y="303" text-anchor="middle" class="label">Sandbox Container</text>
+
+  <rect x="80" y="312" width="180" height="35" rx="5" fill="rgba(255,255,255,0.12)" stroke="rgba(255,255,255,0.25)"/>
+  <text x="170" y="328" text-anchor="middle" font-size="9" font-weight="600" fill="#fff">/mnt/skills/public/</text>
+  <text x="170" y="340" text-anchor="middle" font-size="8" fill="rgba(255,255,255,0.7)">13 skills (baked in image)</text>
+
+  <rect x="280" y="312" width="180" height="35" rx="5" fill="rgba(255,255,255,0.12)" stroke="rgba(255,255,255,0.25)"/>
+  <text x="370" y="328" text-anchor="middle" font-size="9" font-weight="600" fill="#fff">/mnt/skills/examples/</text>
+  <text x="370" y="340" text-anchor="middle" font-size="8" fill="rgba(255,255,255,0.7)">14 examples (baked in image)</text>
+
+  <rect x="480" y="312" width="190" height="35" rx="5" fill="rgba(255,255,255,0.15)" stroke="rgba(255,255,255,0.35)"/>
+  <text x="575" y="328" text-anchor="middle" font-size="9" font-weight="600" fill="#fff">/mnt/skills/user/</text>
+  <text x="575" y="340" text-anchor="middle" font-size="8" fill="rgba(255,255,255,0.7)">User skills (bind-mounted)</text>
+
+  <!-- ZIP cache note -->
+  <rect x="530" y="100" width="195" height="55" class="box" fill="#f8fafc" stroke="#e2e8f0"/>
+  <text x="627" y="120" text-anchor="middle" class="item-bold">ZIP Cache</text>
+  <text x="627" y="133" text-anchor="middle" class="item">/data/skills-cache/{name}/</text>
+  <text x="627" y="146" text-anchor="middle" font-size="8.5" fill="#6b7280">SHA-256 manifest · atomic extract</text>
+  <path d="M530,127 L550,127" class="arrow" style="marker-end: none"/>
+
+  <!-- Footer -->
+  <text x="375" y="405" text-anchor="middle" font-size="9" fill="#9ca3af">Without Settings Wrapper: all 13 public skills always enabled for everyone (default behavior)</text>
+</svg>

package/docs/file-flow.svg

@@ -0,0 +1,126 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 920 480" 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-width: 1.8; fill: none; marker-end: url(#ah); }
+      .arrow-label { font-size: 9px; fill: #6b7280; }
+      .note { font-size: 9.5px; fill: #64748b; }
+    </style>
+    <marker id="ah" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L8,3 L0,6" fill="#94a3b8"/>
+    </marker>
+    <marker id="ah-green" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L8,3 L0,6" fill="#22c55e"/>
+    </marker>
+    <marker id="ah-blue" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L8,3 L0,6" fill="#3b82f6"/>
+    </marker>
+    <marker id="ah-amber" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L8,3 L0,6" fill="#f59e0b"/>
+    </marker>
+  </defs>
+
+  <!-- Background -->
+  <rect width="920" height="480" rx="12" fill="#fafbfc"/>
+  <text x="460" y="28" text-anchor="middle" font-size="15" font-weight="700" fill="#1e293b">File Flow &amp; Preview Architecture</text>
+
+  <!-- User / Open WebUI -->
+  <rect x="50" y="55" width="200" height="100" class="box" fill="#6366f1" stroke="#4f46e5"/>
+  <text x="150" y="78" text-anchor="middle" class="label">Open WebUI (Chat)</text>
+  <text x="150" y="96" text-anchor="middle" font-size="9.5" fill="rgba(255,255,255,0.85)">User types prompts</text>
+  <text x="150" y="110" text-anchor="middle" font-size="9.5" fill="rgba(255,255,255,0.85)">Sees links to files</text>
+  <text x="150" y="124" text-anchor="middle" font-size="9.5" fill="rgba(255,255,255,0.7)">Files do NOT upload back</text>
+
+  <!-- Side Panel -->
+  <rect x="50" y="185" width="200" height="90" class="box" fill="#8b5cf6" stroke="#7c3aed"/>
+  <text x="150" y="208" text-anchor="middle" class="label">Side Panel (Artifacts)</text>
+  <text x="150" y="226" text-anchor="middle" font-size="9.5" fill="rgba(255,255,255,0.85)">File preview: docx, pdf, xlsx</text>
+  <text x="150" y="240" text-anchor="middle" font-size="9.5" fill="rgba(255,255,255,0.85)">Browser viewer (CDP stream)</text>
+  <text x="150" y="254" text-anchor="middle" font-size="9.5" fill="rgba(255,255,255,0.85)">Terminal (Claude Code CLI)</text>
+
+  <!-- Computer Use Server -->
+  <rect x="350" y="55" width="220" height="120" class="box" fill="#1e40af" stroke="#1e3a8a"/>
+  <text x="460" y="78" text-anchor="middle" class="label">Computer Use Server</text>
+  <text x="460" y="96" text-anchor="middle" font-size="9.5" fill="rgba(255,255,255,0.85)">File Server (HTTP)</text>
+  <text x="460" y="112" text-anchor="middle" font-size="9.5" fill="rgba(255,255,255,0.85)">Preview renderer</text>
+  <text x="460" y="128" text-anchor="middle" font-size="9.5" fill="rgba(255,255,255,0.85)">CDP &amp; Terminal proxy</text>
+  <text x="460" y="144" text-anchor="middle" font-size="9.5" fill="rgba(255,255,255,0.7)">/api/outputs/{chat_id}/</text>
+
+  <!-- Sandbox Container -->
+  <rect x="350" y="215" width="220" height="110" class="box" fill="#0f766e" stroke="#0d9488"/>
+  <text x="460" y="238" text-anchor="middle" class="label">Sandbox Container</text>
+  <text x="460" y="256" text-anchor="middle" font-size="9.5" fill="rgba(255,255,255,0.85)">/mnt/user-data/outputs/ (RW)</text>
+  <text x="460" y="272" text-anchor="middle" font-size="9.5" fill="rgba(255,255,255,0.85)">/mnt/user-data/uploads/ (RO)</text>
+  <text x="460" y="288" text-anchor="middle" font-size="9.5" fill="rgba(255,255,255,0.85)">/mnt/skills/ (RO)</text>
+  <text x="460" y="304" text-anchor="middle" font-size="9.5" fill="rgba(255,255,255,0.7)">AI writes files here</text>
+
+  <!-- Docker Volume -->
+  <rect x="660" y="215" width="210" height="80" class="box" fill="#475569" stroke="#334155"/>
+  <text x="765" y="240" text-anchor="middle" class="label">Docker Volume</text>
+  <text x="765" y="258" text-anchor="middle" font-size="9.5" fill="rgba(255,255,255,0.85)">user-data-{chat_id}/</text>
+  <text x="765" y="274" text-anchor="middle" font-size="9.5" fill="rgba(255,255,255,0.7)">Persists across container restarts</text>
+
+  <!-- External Access -->
+  <rect x="660" y="55" width="210" height="80" class="box" fill="#b45309" stroke="#a16207"/>
+  <text x="765" y="78" text-anchor="middle" class="label">Direct Access</text>
+  <text x="765" y="96" text-anchor="middle" font-size="9.5" fill="rgba(255,255,255,0.85)">Open link in new tab</text>
+  <text x="765" y="112" text-anchor="middle" font-size="9.5" fill="rgba(255,255,255,0.85)">Download zip archive</text>
+
+  <!-- Arrows -->
+  <!-- Chat -> Server: tool calls -->
+  <path d="M250,90 L345,90" class="arrow" stroke="#3b82f6" marker-end="url(#ah-blue)"/>
+  <text x="297" y="83" text-anchor="middle" class="arrow-label">MCP tool calls</text>
+
+  <!-- Server -> Sandbox: commands -->
+  <path d="M460,175 L460,210" class="arrow" stroke="#3b82f6" marker-end="url(#ah-blue)"/>
+  <text x="515" y="197" class="arrow-label">Docker exec</text>
+
+  <!-- Sandbox -> Server: files via volume -->
+  <path d="M400,215 L400,175" class="arrow" stroke="#22c55e" marker-end="url(#ah-green)"/>
+  <text x="375" y="197" text-anchor="end" class="arrow-label">files</text>
+
+  <!-- Server -> Chat: links in response -->
+  <path d="M350,120 L250,120" class="arrow" stroke="#22c55e" marker-end="url(#ah-green)"/>
+  <text x="300" y="137" text-anchor="middle" class="arrow-label">HTTP links in chat</text>
+
+  <!-- Chat -> Side Panel -->
+  <path d="M150,155 L150,180" class="arrow" stroke="#8b5cf6" marker-end="url(#ah)"/>
+  <text x="200" y="172" class="arrow-label">auto-open</text>
+
+  <!-- Side Panel -> Server: fetch preview -->
+  <path d="M250,230 L345,130" class="arrow" stroke="#f59e0b" marker-end="url(#ah-amber)"/>
+  <text x="260" y="170" class="arrow-label">fetch preview</text>
+
+  <!-- Sandbox -> Volume -->
+  <path d="M570,260 L655,260" class="arrow" stroke="#94a3b8"/>
+  <text x="612" y="252" text-anchor="middle" class="arrow-label">mount</text>
+
+  <!-- Server -> External: direct links -->
+  <path d="M570,90 L655,90" class="arrow" stroke="#f59e0b" marker-end="url(#ah-amber)"/>
+  <text x="612" y="83" text-anchor="middle" class="arrow-label">HTTP URL</text>
+
+  <!-- Legend -->
+  <rect x="50" y="350" width="820" height="110" rx="8" fill="#f8fafc" stroke="#e2e8f0"/>
+  <text x="70" y="375" font-size="11" font-weight="600" fill="#1e293b">Key Differences from Claude.ai / Open Terminal</text>
+
+  <line x1="70" y1="395" x2="90" y2="395" stroke="#22c55e" stroke-width="2"/>
+  <text x="95" y="399" class="note">Files stay on the server — chat only receives HTTP links (no re-upload to WebUI)</text>
+
+  <line x1="70" y1="415" x2="90" y2="415" stroke="#8b5cf6" stroke-width="2"/>
+  <text x="95" y="419" class="note">Side panel renders previews via Computer Use Server — not a native file browser</text>
+
+  <line x1="70" y1="435" x2="90" y2="435" stroke="#f59e0b" stroke-width="2"/>
+  <text x="95" y="439" class="note">User can open any file link in a new browser tab, download as zip, or work directly in the container terminal</text>
+
+  <line x1="480" y1="395" x2="500" y2="395" stroke="#3b82f6" stroke-width="2"/>
+  <text x="505" y="399" class="note">Everything syncs with remote server (Docker volumes), not local filesystem</text>
+
+  <line x1="480" y1="415" x2="500" y2="415" stroke="#0f766e" stroke-width="2"/>
+  <text x="505" y="419" class="note">Container terminal accessible independently — Claude Code CLI or manual work</text>
+
+  <line x1="480" y1="435" x2="500" y2="435" stroke="#b45309" stroke-width="2"/>
+  <text x="505" y="439" class="note">User can leave chat and navigate to server URLs to interact with files directly</text>
+</svg>