@mseep/open-computer-use 1.0.0

package/docs/FEATURES.md

@@ -0,0 +1,100 @@
+# Architecture & Features
+
+How Open Computer Use works under the hood. For comparisons with other tools, see [COMPARISON.md](COMPARISON.md).
+
+## Shared Browser
+
+![Shared Browser](shared-browser.svg)
+
+One Chromium instance inside the sandbox container, shared between the AI and the user:
+
+| Actor | Access | What they do |
+|-------|--------|--------------|
+| **AI Agent** | Playwright CDP | Navigates, clicks, fills forms, scrapes data |
+| **User** | CDP streaming (interactive, side panel) | Watches AI in real-time, clicks, types, scrolls — same browser session |
+
+The user can enter sensitive information (passwords, 2FA codes, private data) directly into the browser — the AI never sees the raw credentials, only the resulting page state. Both the AI and the user operate on the same browser — true collaboration, not a screenshot relay.
+
+## File Flow & Preview
+
+![File Flow](file-flow.svg)
+
+### How files work
+
+1. **AI creates files** inside the sandbox container (`/mnt/user-data/outputs/`)
+2. **Computer Use Server** serves files via HTTP (`/files/{chat_id}/filename`)
+3. **Chat shows links** — the AI's response contains clickable HTTP URLs to the files
+4. **Side panel renders preview** — docx, pdf, xlsx, images, code are rendered inline
+5. **User downloads** by clicking the link or using the archive/zip endpoint
+
+### Key design: files stay on the server
+
+Files live on the server, not in the conversation. The chat only contains links. This means:
+
+- **No file size limits** in chat — the server handles arbitrarily large files
+- **Direct access** — open any file URL in a new browser tab
+- **Zip download** — download all outputs as a single archive
+- **No re-upload** — files don't flow back into the client's storage
+
+## Claude Code CLI
+
+The sandbox container has **Claude Code CLI pre-installed**. Users can access it in two ways:
+
+1. **Via sub_agent tool** — the AI delegates complex tasks to Claude Code autonomously
+2. **Via terminal tab** — the user opens the terminal in the side panel and runs Claude Code manually
+
+### When to use the terminal
+
+- Complex refactoring that requires many file edits
+- Debugging with interactive tools (gdb, pdb, node inspect)
+- Git operations (rebase, merge, cherry-pick)
+- Running Claude Code with specific flags or prompts
+- Working with MCP servers that the chat model doesn't support
+- Simply preferring a CLI workflow
+
+### How it works
+
+![Terminal Architecture](terminal-flow.svg)
+
+- **tmux** keeps the session alive — disconnect and reconnect without losing state
+- **Claude Code** has access to all configured MCP servers (auto-generated `~/.mcp.json`)
+- User can **switch between chat and terminal** freely — both modify the same container filesystem
+
+### The escape hatch
+
+Users can leave the chat interface entirely:
+- Open the server URL directly in a browser tab
+- Navigate to `/terminal/{chat_id}/` for a full-screen terminal
+- Work with files, run code, use Claude Code CLI — all independent of the chat interface
+
+## Preview & Artifacts Panel
+
+The side panel in Open WebUI serves three functions:
+
+| Tab | Content | Source |
+|-----|---------|--------|
+| **Files** | Preview of created documents (docx, pdf, xlsx, images, code) | Computer Use Server `/api/outputs/{chat_id}/` |
+| **Browser** | Live CDP stream of Chromium in the sandbox | Computer Use Server `/browser/{chat_id}/` |
+| **Sub-Agent** | Terminal (ttyd) + Claude Code process dashboard | Computer Use Server `/terminal/{chat_id}/` |
+
+### How preview rendering works
+
+1. AI creates a file (e.g. `report.docx`) via `create_file` tool
+2. The filter function detects the file URL in the response
+3. Side panel opens automatically with the preview URL
+4. Server renders preview: LibreOffice converts docx to HTML, pdf is embedded, images are displayed
+5. User sees the result inline without downloading
+
+## File Transfer & Sync
+
+![Data Flow](data-flow.svg)
+
+- **Everything is on the server** — Docker volumes, not local filesystem
+- **Container sees volumes as mounts** — `/mnt/user-data/uploads/` (user uploads, read-only) and `/mnt/user-data/outputs/` (AI outputs, read-write)
+- **Server serves files via HTTP** — no direct filesystem access from the browser
+- **Chat only has links** — lightweight, no file data in the conversation
+- **Volume persists** — survives container restarts, available until cleanup
+
+## Docker Image Size
+
+The sandbox image (`open-computer-use:latest`) is **~11 GB**. It includes a full Ubuntu 24.04 environment with LibreOffice, Playwright + Chromium, Claude Code CLI, Python ML/data science stack, Node.js toolchain, OCR, media processing, and 13 skills. First build takes ~15 minutes.

package/docs/INSTALL.md

@@ -0,0 +1,111 @@
+# Installation Guide
+
+This guide is for **self-hosting**. For the managed version (GitHub/Google sign-in, no Docker), see [CLOUD.md](CLOUD.md) or try [chat.yambr.com](https://chat.yambr.com) directly.
+
+## Prerequisites
+
+- **Docker Engine** 24+ with Docker Compose v2
+- **8 GB RAM** minimum (16 GB recommended)
+- **20 GB disk** (sandbox image is ~5 GB)
+
+## Quick Start
+
+```bash
+git clone https://github.com/Wide-Moat/open-computer-use.git
+cd open-computer-use
+cp .env.example .env
+# Edit .env — see the REQUIRED section at the top of .env.example.
+
+# 1. Pre-flight: catch common misconfigurations before docker starts
+./scripts/check-config.sh
+
+# 2. Build and start Computer Use Server (~15 min first time)
+docker compose up --build
+
+# 3. Start Open WebUI (in another terminal)
+docker compose -f docker-compose.webui.yml up --build
+```
+
+`scripts/check-config.sh` reports `[OK]` / `[WARN]` / `[ERR]` for each setting and exits 1 if anything is likely to break end-to-end (e.g. `PUBLIC_BASE_URL` left at the internal-DNS default, half-configured Vision group). WARNs are fine for local dev.
+
+**Re-seeding Valves after editing `.env`.** The `open-webui` container runs an init script that writes Open WebUI Valves from env **on first start only** — a marker file (`/app/backend/data/.computer-use-initialized`) guards re-runs so your admin UI edits are never clobbered. The only env propagated into Valves is `ORCHESTRATOR_URL` (the internal URL, consumed by both the Computer Use tool and filter). To pick up a new value, delete the marker on `open-webui` and restart it:
+
+```bash
+docker compose -f docker-compose.webui.yml exec open-webui \
+    rm /app/backend/data/.computer-use-initialized
+docker compose -f docker-compose.webui.yml restart open-webui
+```
+
+`PUBLIC_BASE_URL` lives only on the `computer-use-server` container — it is **not** propagated into Open WebUI Valves. If you change it in `.env`, restart the server container instead: `docker compose up -d --force-recreate computer-use-server`.
+
+Open http://localhost:3000 — login with `admin@open-computer-use.dev` / `admin`.
+
+## Configuration
+
+Edit `.env` before starting. Key variables:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `OPENAI_API_KEY` | Yes | LLM API key (any OpenAI-compatible provider) |
+| `OPENAI_API_BASE_URL` | No | Custom API URL (OpenRouter, local vLLM, etc.) |
+| `MCP_API_KEY` | Recommended | Bearer token for MCP endpoint security |
+| `ANTHROPIC_AUTH_TOKEN` | No | For Claude Code sub-agent |
+| `VISION_API_KEY` | No | For describe-image skill |
+| `CHAT_RESPONSE_MAX_TOOL_CALL_RETRIES`, `TOOL_RESULT_MAX_CHARS`, `TOOL_RESULT_PREVIEW_CHARS`, `ORCHESTRATOR_URL` | No | Settings on the **`open-webui` container** (not CU-server). Required for multi-step tasks, large tool results, and preview rendering. Full guide: [README.md → Required setup when embedding Open WebUI](../README.md#required-setup-when-embedding-open-webui-into-your-own-stack). |
+
+See `.env.example` for the full list with defaults.
+
+Routing Claude Code through a custom gateway (LiteLLM / Azure / Bedrock)? See [claude-code-gateway.md](claude-code-gateway.md) for the full recipe.
+
+Want sub-agents to run on OpenAI Codex or OpenCode (with OpenRouter / qwen / DeepSeek / 75+ providers) instead of Claude? Flip `SUBAGENT_CLI=claude|codex|opencode` in `.env` — see [multi-cli.md](multi-cli.md) for the full guide and a worked OpenCode + qwen3-coder + OpenRouter recipe.
+
+## Model Settings
+
+After login, go to your model settings and set:
+
+| Setting | Value | Why |
+|---------|-------|-----|
+| **Function Calling** | `Native` | Required for tools to work |
+| **Stream Chat Response** | `On` | Real-time output |
+
+The init script auto-creates a workspace model with these settings, but verify if using a different model.
+
+## Verification
+
+```bash
+# Server health
+curl http://localhost:8081/health
+# → {"status":"healthy"}
+
+# Open WebUI
+curl -s http://localhost:3000 | head -1
+# → <!DOCTYPE html>
+
+# Run project tests
+./tests/test-no-corporate.sh
+./tests/test-project-structure.sh
+```
+
+## Troubleshooting
+
+### "Model not found" or tool calls fail
+- Check **Function Calling** is set to `Native` in model settings
+- Verify `OPENAI_API_KEY` is correct: `curl -H "Authorization: Bearer $OPENAI_API_KEY" $OPENAI_API_BASE_URL/models`
+
+### Container creation timeout
+- First run downloads the sandbox image (~5 GB). Wait for `docker compose up --build` to finish.
+- Check Docker has enough resources: `docker system info | grep Memory`
+
+### Files not appearing in preview
+- Verify `BASE_DATA_DIR` and `USER_DATA_BASE_PATH` match in docker-compose.yml
+- Check: `curl http://localhost:8081/api/outputs/{chat_id}`
+
+### Connection refused from Open WebUI
+- Verify the Computer Use Server stack is up: `docker compose ps`
+- Verify Open WebUI's `ORCHESTRATOR_URL` points at the service DNS URL `http://computer-use-server:8081`. The two compose stacks share the default Docker network because they share the project name (the parent directory `open-computer-use`), so `computer-use-server` resolves directly — no `host.docker.internal` / `extra_hosts` needed.
+- If you override the Compose project name (`-p myproj`) or set a custom `container_name:` on the server, point `ORCHESTRATOR_URL` at the new internal hostname. Then re-seed Valves (see Re-seeding section above).
+- Quick check from inside the `open-webui` container: `docker compose -f docker-compose.webui.yml exec open-webui curl -sf http://computer-use-server:8081/health`.
+
+## Architecture
+
+See [DOCKER.md](DOCKER.md) for detailed Docker architecture and [MCP.md](MCP.md) for the MCP protocol reference.

package/docs/KNOWN-BUGS.md

@@ -0,0 +1,86 @@
+# Known Bugs
+
+## 1. MCP Server: TypeError 'NoneType' on SSE notifications
+
+**Severity:** Low (doesn't break functionality — tool calls return 200 OK)
+
+**Error:**
+```
+starlette/routing.py, line 74, in app
+    await response(scope, receive, send)
+TypeError: 'NoneType' object is not callable
+```
+
+**When:** Every `POST /mcp` that returns 202 Accepted (SSE notification acknowledgment).
+
+**Root cause:** MCP Python SDK's Streamable HTTP handler returns `None` for fire-and-forget notification responses. Starlette expects an ASGI callable Response object.
+
+**Impact:** Error logged but tool calls work. The 202 response is already sent before the error.
+
+**Likely fix:** Check if `mcp` SDK version has a fix, or patch the route handler to return an empty Response for 202.
+
+---
+
+## 2. File preview auto-show depends on model behavior
+
+**Severity:** Medium (functional but not always automatic)
+
+**How it works:** The `fix_preview_url_detection` patch detects Computer Use Server file URLs in assistant messages and auto-opens an iframe preview in the artifacts panel. The `computer_link_filter` injects the file server URL into the system prompt so the model knows to include file links.
+
+**Issue:** Some models (especially smaller ones) don't consistently include file URLs in their responses even when instructed by the system prompt. When the model just says "file created" without the URL, the preview patch has nothing to detect.
+
+**Workaround:** The filter's outlet always adds "View your file" link and "Download all as archive" button — these work regardless. For auto-preview, use models that reliably follow system prompt instructions (Claude, GPT-4o, larger Qwen models).
+
+---
+
+## 3. PPTX generation may timeout with complex prompts
+
+**Severity:** Low (model-dependent)
+
+**When:** Model makes many sequential tool calls (19+ bash, create_file, view, str_replace) for complex tasks like presentation creation.
+
+**Impact:** Response may appear incomplete if model hits max tool call retries.
+
+**Workaround:** Use simpler prompts or increase `COMMAND_TIMEOUT` in `.env`.
+
+---
+
+## 4. File/preview endpoints have no per-user auth
+
+**Severity:** Medium (known limitation, planned fix)
+
+**Issue:** Endpoints like `/files/{chat_id}/`, `/api/outputs/{chat_id}`, `/browser/{chat_id}/`, `/terminal/{chat_id}/` are accessible to anyone who knows the chat ID UUID. There is no per-user authentication — only `MCP_API_KEY` protects the MCP endpoint itself.
+
+**Impact:** In a multi-user deployment without network isolation, one user could access another user's files if they know the chat ID.
+
+**Current mitigation:** Chat IDs are UUIDs (hard to guess). Tested in production with 1000+ users on Open WebUI — acceptable risk for self-hosted deployments behind a firewall.
+
+**Planned fix:** Per-session signed tokens for all file/preview/terminal endpoints. See Security Roadmap in README.
+
+---
+
+## 5. MCP tools cannot return images to the model (Open WebUI limitation)
+
+**Severity:** Medium (functional limitation)
+
+**Issue:** Open WebUI does not support `image` content type in MCP tool results — only `text` is handled. This means tools cannot return screenshots or images back to the model for analysis.
+
+**Impact:** Tools like Playwright (page screenshots) or bash (generated charts) cannot pass visual output directly to the model. The model never sees the image, so it can't reason about what's on screen.
+
+**Workaround:** The `describe-image` skill works around this by calling a separate vision model (e.g., GPT-4o, Qwen-VL) to describe the image as text, which is then returned to the main model. Playwright and other skills save images to `/mnt/user-data/outputs/` as HTTP links for the user to view in the file preview panel.
+
+**Root cause:** Open WebUI's MCP integration only passes `text` content blocks from tool responses to the model. This is an upstream limitation — see [open-webui/open-webui](https://github.com/open-webui/open-webui) for progress on image tool result support.
+
+---
+
+## 6. Preview breaks after custom `container_name` or non-default compose layouts
+
+**Severity:** Medium (configuration-only, no data loss)
+
+**Status (v4.0.0):** the class of "two settings must match" bugs was fixed by moving public-URL ownership to the server. The filter now reads the public URL from the server's `X-Public-Base-URL` response header — there is only one place to set it.
+
+**How it works:** The Computer Use Server embeds file links into every assistant message using its `PUBLIC_BASE_URL` env var. The Open WebUI filter's `outlet()` uses whatever URL the server returned in the response header — no separate public-URL Valve. The filter's internal `ORCHESTRATOR_URL` Valve is a Docker-only hostname and doesn't leave the container.
+
+**What can still go wrong:** the `PUBLIC_BASE_URL` on the `computer-use-server` container must still be a URL the user's browser can reach. Custom compose project names, removed `container_name:` pins, or missing DNS mean the browser sees links pointing at an unreachable hostname — the preview iframe then 404s / shows a blank frame even though the filter decorates it correctly.
+
+**Workaround:** Set `PUBLIC_BASE_URL` (server `.env`) to your externally reachable URL (`http://your-host.lan:8081`, `https://cu.example.com`, …). The `fix_preview_url_detection` patch is host-agnostic — no build-arg required. See [docs/openwebui-filter.md](openwebui-filter.md#two-url-roles--public-server-env-and-internal-filtertool-valve).

package/docs/MCP.md

@@ -0,0 +1,320 @@
+# MCP Server Integration
+
+The Computer Use Server exposes a standard [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) endpoint that works with any MCP-compatible client.
+
+This server is published in the [MCP Registry](https://github.com/modelcontextprotocol/registry) as `io.github.Wide-Moat/open-computer-use`.
+
+## Hosted endpoint (managed)
+
+Skip the self-host deployment and point any MCP client at the managed endpoint:
+
+```
+POST https://api.yambr.com/mcp/computer_use
+Authorization: Bearer <YAMBR_API_KEY>
+X-Chat-Id: <session-id>
+```
+
+Request a key at [app.yambr.com](https://app.yambr.com) (GitHub or Google sign-in). You bring your own model provider — Yambr doesn't resell inference. Per-client configs (Claude Desktop, OpenAI Agents SDK, n8n, LiteLLM) live on [docs.yambr.com](https://docs.yambr.com); repo-side orientation in [CLOUD.md](CLOUD.md).
+
+The rest of this document covers **self-hosting** the same MCP server.
+
+## Deployment Prerequisite
+
+This is a **self-hosted** MCP server. You must deploy it before connecting:
+
+```bash
+git clone https://github.com/Wide-Moat/open-computer-use.git
+cd open-computer-use
+docker build --platform linux/amd64 -t open-computer-use:latest .
+docker compose up -d
+```
+
+The MCP endpoint will be available at `http://localhost:8081/mcp`.
+
+### Session isolation modes
+
+The server supports three modes controlled by the `SINGLE_USER_MODE` environment variable. This determines how `X-Chat-Id` headers are handled and whether sessions get isolated containers.
+
+| `SINGLE_USER_MODE` | `X-Chat-Id` sent | Behavior |
+|---------------------|-------------------|----------|
+| _(not set)_ | Yes | Normal: isolated container per chat ID |
+| _(not set)_ | No | Lenient: uses shared `default` container + appends a warning to every tool response |
+| `true` | _(any)_ | Single-user: always uses one `default` container, no warnings, header ignored |
+| `false` | Yes | Strict multi-user: isolated container per chat ID |
+| `false` | No | **Error** — `X-Chat-Id` is required, tool call rejected |
+
+**Default behavior (no env var):** the server accepts requests without `X-Chat-Id` but appends a note to every tool response explaining the options. This makes onboarding easy — things work immediately, and the warning guides users toward the right setup.
+
+#### Single-user mode (recommended for Claude Desktop)
+
+If you're the only user, set `SINGLE_USER_MODE=true` in `.env`. All sessions share one persistent container — no headers needed:
+
+```bash
+echo "SINGLE_USER_MODE=true" >> .env
+docker compose restart
+```
+
+#### Strict multi-user mode (recommended for production)
+
+For shared deployments, set `SINGLE_USER_MODE=false`. Every request must include `X-Chat-Id` — requests without it are rejected with an error:
+
+```bash
+echo "SINGLE_USER_MODE=false" >> .env
+docker compose restart
+```
+
+MCP clients (Open WebUI, LiteLLM, n8n) typically pass chat/session IDs automatically via `X-Chat-Id` or `X-OpenWebUI-Chat-Id` headers.
+
+## Endpoint
+
+```
+POST http://localhost:8081/mcp
+```
+
+## Authentication
+
+Set the `MCP_API_KEY` environment variable and pass it as a Bearer token:
+
+```
+Authorization: Bearer <MCP_API_KEY>
+```
+
+Leave `MCP_API_KEY` empty for development (no auth required).
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `bash_tool` | Execute bash commands in isolated Docker container |
+| `view` | View files and directories |
+| `create_file` | Create new files |
+| `str_replace` | Edit files via text replacement |
+| `sub_agent` | Delegate tasks to autonomous Claude Code agent |
+
+## Native MCP primitives beyond tools
+
+Beyond the five tools, the server exposes three more native primitives of the Streamable-HTTP MCP protocol — all scoped by `X-Chat-Id`:
+
+| Primitive | What you get | How |
+|---|---|---|
+| `InitializeResult.instructions` | The per-chat system prompt as a string, delivered in the handshake | Dynamic — re-rendered each stateless request from `X-Chat-Id` / `X-User-Email` headers |
+| `resources/list` + `resources/read` | Chat's uploaded files as `file://uploads/{chat_id}/{url-encoded-rel-path}` | Auto-registered on container create + on every `POST /api/uploads` |
+
+In addition, `/home/assistant/README.md` inside the sandbox carries the same prompt text, so any model that runs the `view` tool can recover its environment even if the client stripped every MCP handshake field. Full map: `docs/system-prompt.md`.
+
+*Note: we intentionally do NOT expose the system prompt via `prompts/get`. The MCP `prompts/*` primitive is user-controlled (slash commands) and `PromptMessage.role` is restricted to `user | assistant` — duplicating `InitializeResult.instructions` there would be off-spec.*
+
+## Required Headers
+
+> **`X-Chat-Id` is mandatory.** Without it, the server returns an error. Every request must include a unique session identifier.
+
+| Header | Description | Required |
+|--------|-------------|----------|
+| `X-Chat-Id` | **Session identifier** — one sandbox container per chat ID | **Yes** |
+| `Authorization` | `Bearer <MCP_API_KEY>` — required if `MCP_API_KEY` is set | Conditional |
+| `X-User-Email` | User email (for per-user skills, token lookup, logging) | No |
+| `X-User-Name` | Display name (URL-encoded) | No |
+| `X-MCP-Servers` | Comma-separated MCP server names for Claude Code sub-agent | No |
+
+## Usage Examples
+
+### Initialize Session
+
+```bash
+curl -sD - -X POST "http://localhost:8081/mcp" \
+  -H "Authorization: Bearer $MCP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "X-Chat-Id: my-session" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0"}}}'
+```
+
+Save the `mcp-session-id` header from the response.
+
+### Call a Tool
+
+```bash
+curl -s -X POST "http://localhost:8081/mcp" \
+  -H "Authorization: Bearer $MCP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Mcp-Session-Id: <SESSION_ID>" \
+  -H "X-Chat-Id: my-session" \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"bash_tool","arguments":{"command":"echo Hello from sandbox","description":"test"}}}'
+```
+
+### List Tools
+
+```bash
+curl -s -X POST "http://localhost:8081/mcp" \
+  -H "Authorization: Bearer $MCP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Mcp-Session-Id: <SESSION_ID>" \
+  -H "X-Chat-Id: my-session" \
+  -d '{"jsonrpc":"2.0","id":3,"method":"tools/list","params":{}}'
+```
+
+## Integration with LLM Frameworks
+
+### LiteLLM
+
+```yaml
+mcp_servers:
+  computer_use:
+    url: "http://computer-use-server:8081/mcp"
+    transport: "http"
+    auth_type: "bearer_token"
+    auth_value: "<MCP_API_KEY>"
+    extra_headers:
+      X-Chat-Id: "{chat_id}"
+      X-User-Email: "{user_email}"
+```
+
+### Claude Desktop (claude_desktop_config.json)
+
+```json
+{
+  "mcpServers": {
+    "computer-use": {
+      "url": "http://localhost:8081/mcp",
+      "transport": "streamable-http",
+      "headers": {
+        "Authorization": "Bearer <MCP_API_KEY>",
+        "X-Chat-Id": "desktop-session"
+      }
+    }
+  }
+}
+```
+
+## MCP Servers for Claude Code Sub-Agent
+
+When the `sub_agent` tool launches Claude Code inside a sandbox container, it can be configured with MCP servers. This allows Claude Code to access external tools (databases, APIs, other MCP servers) during autonomous task execution.
+
+### How it works
+
+1. **Client sends MCP server names** via HTTP header when calling the Computer Use Server
+2. **Computer Use Server** writes `~/.mcp.json` inside the sandbox container
+3. **Claude Code** reads the config and connects to the specified MCP servers
+4. **Authorization** uses `ANTHROPIC_AUTH_TOKEN` from the container environment (no secrets in config)
+
+### Header format
+
+Pass MCP server names as a comma-separated list:
+
+```
+X-MCP-Servers: server1,server2,server3
+```
+
+Or the Open WebUI-style header:
+
+```
+X-OpenWebUI-MCP-Servers: server1,server2,server3
+```
+
+### URL pattern
+
+Server URLs are templated as `{ANTHROPIC_BASE_URL}/mcp/{server_name}` — this follows the LiteLLM MCP proxy pattern where LiteLLM acts as a gateway to multiple MCP servers.
+
+### Example: LiteLLM with multiple MCP servers
+
+If LiteLLM is configured with MCP servers `github`, `jira`, `slack`:
+
+```yaml
+# LiteLLM config
+mcp_servers:
+  github:
+    url: "http://github-mcp:3000/mcp"
+  jira:
+    url: "http://jira-mcp:3001/mcp"
+  slack:
+    url: "http://slack-mcp:3002/mcp"
+```
+
+Passing `X-MCP-Servers: github,jira` will make these servers available to Claude Code inside the sandbox.
+
+### Generated ~/.mcp.json
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "type": "http",
+      "url": "https://llm-api.example.com/mcp/github",
+      "headers": {
+        "x-openwebui-user-email": "user@example.com",
+        "Authorization": "Bearer <ANTHROPIC_AUTH_TOKEN>"
+      }
+    }
+  }
+}
+```
+
+### Security notes
+
+- The server name `docker_ai` / `docker-ai` is blocked to prevent recursive sub-agent loops
+- Authorization tokens are resolved at runtime from container environment, not stored in the config file
+- MCP servers are auto-approved in Claude Code's `settings.local.json` so it doesn't prompt for permission
+
+### Open WebUI integration (planned)
+
+Currently, the Open WebUI tool (`computer_use_tools.py`) does not pass MCP server headers. To use this feature, either:
+
+1. Use a custom MCP client that sets the `X-MCP-Servers` header
+2. Or add MCP server forwarding to the Open WebUI tool (contributions welcome)
+
+## Dynamic Configuration Endpoints
+
+The server provides API endpoints that MCP clients should use to get up-to-date configuration instead of hardcoding values.
+
+### GET /system-prompt
+
+Returns the full system prompt as plain text with current skills and correct file URLs.
+
+```bash
+curl "http://localhost:8081/system-prompt?chat_id=my-session&user_email=user@example.com"
+```
+
+| Parameter | Description | Required |
+|-----------|-------------|----------|
+| `chat_id` | Session ID — server constructs file download URLs from this | Recommended |
+| `user_email` | Returns prompt with user-specific skills | No |
+
+### GET /skill-list
+
+Returns available skills as formatted text for sub-agent delegation.
+
+```bash
+curl "http://localhost:8081/skill-list?user_email=user@example.com"
+```
+
+### GET /mcp-info
+
+Returns MCP endpoint metadata as JSON: available tools, required headers, endpoint URL.
+
+```bash
+curl "http://localhost:8081/mcp-info" -H "Authorization: Bearer $MCP_API_KEY"
+```
+
+**Best practice:** Fetch the system prompt dynamically via `/system-prompt?chat_id={id}` at session start. This ensures the AI model gets correct file URLs and the latest skill set. See [System Prompt Reference](system-prompt.md) for details.
+
+## Browser Viewer (CDP)
+
+Each sandbox container runs Chromium with CDP exposed. Access the live browser:
+
+```
+GET http://localhost:8081/browser/{chat_id}/status
+GET http://localhost:8081/browser/{chat_id}/json
+WebSocket: ws://localhost:8081/browser/{chat_id}/devtools/page/{page_id}
+```
+
+## Terminal Access
+
+Interactive terminal via WebSocket:
+
+```
+GET http://localhost:8081/terminal/{chat_id}/status
+GET http://localhost:8081/terminal/{chat_id}/start-ttyd
+WebSocket: ws://localhost:8081/terminal/{chat_id}/ws
+```

package/docs/SCREENSHOTS.md

@@ -0,0 +1,39 @@
+# Screenshots
+
+Visual guide to Open Computer Use with Open WebUI.
+
+## Live Browser Streaming
+
+![Browser Viewer](screenshots/03-browser-viewer.png)
+
+The AI opened openwebui.com via `playwright-cli` — you see the actual browser in real-time through CDP (Chrome DevTools Protocol) streaming. The chat on the left shows tool calls, the browser panel on the right shows the live page. You can watch the AI navigate, click, and fill forms.
+
+## Claude Code Terminal
+
+![Claude Code Terminal](screenshots/04-sub-agent-terminal.png)
+
+Interactive Claude Code session inside the sandbox container. The AI is logged in and responding to prompts. This is a real TTY connection via WebSocket — you can type commands, interrupt execution, and resume sessions. Claude Code has access to all MCP servers and skills configured for the chat.
+
+## File Preview
+
+![File Preview](screenshots/02-file-preview.png)
+
+The preview panel showing a generated Markdown file with skill descriptions. Files created by the AI appear here automatically — supports Word, Excel, PDF, images, code, and more. Dark theme, tabbed navigation (Files / Browser / Sub-agent).
+
+## Sub-Agent Dashboard
+
+![Sub-Agent Dashboard](screenshots/06-sub-agent-dashboard.png)
+
+Claude Code monitoring panel: see running processes, previous sessions with resume capability, dangerous mode toggle. "Currently running: Claude Code" with a Stop button. Previous sessions show task descriptions with dates and Resume buttons.
+
+## Document Creation
+
+![Create Document](screenshots/01-create-document.png)
+
+AI creating a Word document via tool calls. The model reads the SKILL.md, creates the file, and the preview panel auto-opens showing the document content inline.
+
+## Chat Overview
+
+![Chat Overview](screenshots/05-chat-overview.png)
+
+Model listing its available skills and tools: docx, pdf, pptx, xlsx, bash_tool, create_file, str_replace, view, sub_agent, and more. Shows file handling paths and supported formats.