@mseep/open-computer-use 1.0.0

package/docs/shared-browser.svg

@@ -0,0 +1,102 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 920 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); }
+      .arrow { stroke-width: 1.8; fill: none; marker-end: url(#ah2); }
+      .arrow-label { font-size: 9px; fill: #6b7280; }
+      .note { font-size: 9.5px; fill: #64748b; }
+      .highlight { font-size: 10px; font-weight: 600; }
+    </style>
+    <marker id="ah2" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L8,3 L0,6" fill="#94a3b8"/>
+    </marker>
+    <marker id="ah2-green" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L8,3 L0,6" fill="#22c55e"/>
+    </marker>
+    <marker id="ah2-blue" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L8,3 L0,6" fill="#3b82f6"/>
+    </marker>
+    <marker id="ah2-red" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L8,3 L0,6" fill="#ef4444"/>
+    </marker>
+  </defs>
+
+  <rect width="920" height="520" rx="12" fill="#fafbfc"/>
+  <text x="460" y="28" text-anchor="middle" font-size="15" font-weight="700" fill="#1e293b">Shared Browser &amp; Interactive Access</text>
+
+  <!-- Sandbox Container (big box) -->
+  <rect x="350" y="50" width="530" height="200" class="box" fill="#0f766e" stroke="#0d9488"/>
+  <text x="615" y="73" text-anchor="middle" class="label">Sandbox Container</text>
+
+  <!-- Chromium inside sandbox -->
+  <rect x="380" y="90" width="180" height="70" rx="8" fill="rgba(255,255,255,0.15)" stroke="rgba(255,255,255,0.3)"/>
+  <text x="470" y="113" text-anchor="middle" font-size="11" font-weight="600" fill="#fff">Chromium Browser</text>
+  <text x="470" y="128" text-anchor="middle" font-size="9" fill="rgba(255,255,255,0.7)">CDP :9222</text>
+  <text x="470" y="142" text-anchor="middle" font-size="9" fill="rgba(255,255,255,0.7)">Single instance, shared state</text>
+
+  <!-- ttyd inside sandbox -->
+  <rect x="580" y="90" width="140" height="70" rx="8" fill="rgba(255,255,255,0.15)" stroke="rgba(255,255,255,0.3)"/>
+  <text x="650" y="113" text-anchor="middle" font-size="11" font-weight="600" fill="#fff">Terminal (ttyd)</text>
+  <text x="650" y="128" text-anchor="middle" font-size="9" fill="rgba(255,255,255,0.7)">:7681 + tmux</text>
+  <text x="650" y="142" text-anchor="middle" font-size="9" fill="rgba(255,255,255,0.7)">Claude Code CLI</text>
+
+  <!-- Claude Code in sandbox -->
+  <rect x="740" y="90" width="120" height="70" rx="8" fill="rgba(255,255,255,0.15)" stroke="rgba(255,255,255,0.3)"/>
+  <text x="800" y="113" text-anchor="middle" font-size="11" font-weight="600" fill="#fff">Claude Code</text>
+  <text x="800" y="128" text-anchor="middle" font-size="9" fill="rgba(255,255,255,0.7)">Autonomous agent</text>
+  <text x="800" y="142" text-anchor="middle" font-size="9" fill="rgba(255,255,255,0.7)">Full sandbox access</text>
+
+  <!-- Filesystem -->
+  <rect x="380" y="175" width="480" height="55" rx="6" fill="rgba(255,255,255,0.1)" stroke="rgba(255,255,255,0.2)"/>
+  <text x="620" y="195" text-anchor="middle" font-size="10" font-weight="500" fill="rgba(255,255,255,0.9)">Shared Filesystem: /home/assistant/</text>
+  <text x="620" y="210" text-anchor="middle" font-size="8.5" fill="rgba(255,255,255,0.65)">AI, User (via terminal), and Claude Code all see the same files</text>
+
+  <!-- Three actors -->
+  <!-- AI Agent -->
+  <rect x="40" y="60" width="170" height="80" class="box" fill="#1e40af" stroke="#1e3a8a"/>
+  <text x="125" y="83" text-anchor="middle" class="label">AI Agent (LLM)</text>
+  <text x="125" y="100" text-anchor="middle" font-size="9" fill="rgba(255,255,255,0.85)">Playwright automation</text>
+  <text x="125" y="114" text-anchor="middle" font-size="9" fill="rgba(255,255,255,0.85)">bash_tool, create_file</text>
+
+  <!-- User via Chat -->
+  <rect x="40" y="170" width="170" height="80" class="box" fill="#6366f1" stroke="#4f46e5"/>
+  <text x="125" y="193" text-anchor="middle" class="label">User (Chat)</text>
+  <text x="125" y="210" text-anchor="middle" font-size="9" fill="rgba(255,255,255,0.85)">Watches browser live</text>
+  <text x="125" y="224" text-anchor="middle" font-size="9" fill="rgba(255,255,255,0.85)">Sees AI actions in real-time</text>
+
+  <!-- User via Terminal -->
+  <rect x="40" y="280" width="170" height="80" class="box" fill="#b45309" stroke="#a16207"/>
+  <text x="125" y="303" text-anchor="middle" class="label">User (Terminal)</text>
+  <text x="125" y="320" text-anchor="middle" font-size="9" fill="rgba(255,255,255,0.85)">Direct CLI access</text>
+  <text x="125" y="334" text-anchor="middle" font-size="9" fill="rgba(255,255,255,0.85)">Claude Code, manual work</text>
+
+  <!-- Arrows from actors to sandbox -->
+  <path d="M210,100 L375,115" class="arrow" stroke="#3b82f6" marker-end="url(#ah2-blue)"/>
+  <text x="290" y="97" class="arrow-label">Playwright CDP</text>
+
+  <path d="M210,210 L375,130" class="arrow" stroke="#22c55e" marker-end="url(#ah2-green)"/>
+  <text x="270" y="178" class="arrow-label">CDP viewer (interactive)</text>
+
+  <path d="M210,310 L575,125" class="arrow" stroke="#ef4444" marker-end="url(#ah2-red)"/>
+  <text x="370" y="280" class="arrow-label">WebSocket TTY (read-write)</text>
+
+  <!-- Key insight boxes -->
+  <rect x="40" y="390" width="410" height="115" rx="8" fill="#fef3c7" stroke="#f59e0b"/>
+  <text x="60" y="413" class="highlight" fill="#92400e">Shared Browser = One Chromium, Three Users</text>
+  <text x="60" y="432" class="note" fill="#78350f">1. AI navigates via Playwright (automated)</text>
+  <text x="60" y="449" class="note" fill="#78350f">2. User watches live via CDP stream in side panel</text>
+  <text x="60" y="466" class="note" fill="#78350f">3. User can type in the browser directly (e.g. login credentials)</text>
+  <text x="60" y="483" class="note" fill="#78350f">4. AI sees user's input — true collaboration on one browser</text>
+
+  <rect x="470" y="390" width="410" height="115" rx="8" fill="#dbeafe" stroke="#3b82f6"/>
+  <text x="490" y="413" class="highlight" fill="#1e3a8a">Claude Code CLI = Power User Escape Hatch</text>
+  <text x="490" y="432" class="note" fill="#1e40af">1. When chat capabilities are not enough — open terminal</text>
+  <text x="490" y="449" class="note" fill="#1e40af">2. Full Claude Code CLI with all MCP servers</text>
+  <text x="490" y="466" class="note" fill="#1e40af">3. User can also work manually: git, vim, code</text>
+  <text x="490" y="483" class="note" fill="#1e40af">4. Leave OpenWebUI entirely — work in container directly</text>
+
+  <!-- Title annotations -->
+  <text x="460" y="375" text-anchor="middle" font-size="11" font-weight="600" fill="#475569">vs. Open Terminal: native file browser | vs. Claude.ai: screenshot-based browser</text>
+</svg>

package/docs/system-prompt.md

@@ -0,0 +1,113 @@
+# System Prompt Delivery — Six MCP-Native Tiers
+
+The Computer Use Server delivers the same per-session system prompt through **six different channels**, so clients with varying MCP support all get it. Every tier renders from the same source (`computer-use-server/system_prompt.py::render_system_prompt`) with a shared 60-second in-process cache, so fan-out cost is one render per `(chat_id, user_email)` per minute.
+
+**Redundancy is by design.** A client might strip `InitializeResult.instructions` and never call `resources/list` — but it will always call `tools/list`, and the tool descriptions nudge the model toward `/home/assistant/README.md` inside the sandbox. That file is always present.
+
+**Why not `@mcp.prompt("system")`?** MCP `prompts/*` is user-controlled (slash-commands the user explicitly picks) and `PromptMessage.role` is restricted to `{user, assistant}` — naming a prompt `"system"` both clashes with the spec's role model and duplicates `InitializeResult.instructions`, which is the canonical field for "how the server wants itself used." We chose the canonical path.
+
+## The Tiers
+
+| # | Surface | Where it lives | Who uses it |
+|---|---|---|---|
+| 1 | Tool descriptions | `tools/list` — `bash_tool` + `view` docstrings mention README.md | Every MCP client (tools are mandatory) |
+| 2 | `/home/assistant/README.md` | Rendered into the sandbox on container creation via `put_archive` | Any model that runs the `view` tool |
+| 3 | Static `instructions=` hint | FastMCP constructor, one-line pointer to README + `resources/list` | Claude Desktop, MCP Inspector; Agents SDK exposes via `server.server_initialize_result` |
+| 4 | Dynamic `InitializeResult.instructions` | Per-request ContextVar, swapped onto `mcp._mcp_server` as a `@property` | Same clients as #3, with chat-specific content |
+| 5 | `resources/list` + `resources/read` | Uploaded files surfaced as `FunctionResource` per chat, URI `file://uploads/{chat_id}/{rel_path}` | Agents SDK, Inspector, Claude Desktop |
+| 6 | `GET /system-prompt` HTTP | Backward-compat endpoint with header > query priority | Open WebUI filter; external integrations (n8n) |
+
+## Tier 1 — Tool description nudges
+
+Docstrings of `bash_tool` and `view` tools (in `computer-use-server/mcp_tools.py`) end with:
+
+> If you've lost track of your environment (chat_id, file URLs, available skills), re-read /home/assistant/README.md.
+
+Deliberately **not** "read this first" — the system prompt itself (Tiers 3/4) already identifies as "contents of /home/assistant/README.md", so if the client surfaced it the model already has the content. This line is a **recovery hint**, not a forcing function.
+
+## Tier 2 — README.md in the sandbox
+
+When `docker_manager._create_container` spins up a chat's workspace container, it calls `render_system_prompt_sync(chat_id, user_email)` and writes the result to `/home/assistant/README.md` (or `/root/README.md` for the test image) via `container.put_archive`. The file survives across container removals because it lives in the chat's persistent workspace volume (`chat-{chat_id}-workspace`).
+
+Does **not** enumerate uploaded files — those are Tier 5's responsibility and are refreshed on every upload. README is static-per-container and changes only when `user_email` changes (which doesn't happen mid-chat).
+
+## Tier 3 — Static `instructions=`
+
+FastMCP's constructor kwarg. A one-liner pointing at Tiers 2 and 5 (README + uploaded-file resources) so a client that renders only `InitializeResult.instructions` still learns where the per-session content lives.
+
+## Tier 4 — Dynamic `InitializeResult.instructions`
+
+The same `instructions` field, but **per-request**. Relies on three facts pinned in the SDK source (`.venv/lib/python3.13/site-packages/mcp/server/...`):
+
+1. `streamable_http_manager._handle_stateless_request:196` calls `self.app.create_initialization_options()` inside a per-request task spun up for each HTTP hit — and we run `stateless_http=True` (`mcp_tools.py:276`).
+2. `lowlevel/server.py:188` reads `self.instructions` at that moment to populate `InitializationOptions`.
+3. `session.py:183` echoes it into `InitializeResult.instructions`.
+
+Mechanism:
+- `MCPContextMiddleware` (runs before every MCP request) pre-renders the prompt via `render_system_prompt(...)` and stores it in `current_instructions: ContextVar[str]`.
+- `_DynamicInstructionsServer` subclasses `mcp.server.lowlevel.Server` with `@property def instructions` returning the ContextVar value (falling back to the static `_STATIC_INSTRUCTIONS` string when unset).
+- After `FastMCP(...)` constructs the lowlevel server, we **swap the class** on the existing instance: `mcp._mcp_server.__class__ = _DynamicInstructionsServer`. No reconstruction needed.
+
+**Stateful mode would break this** (a long-lived session caches `init_options` at construction). Do NOT flip `stateless_http=False` without re-reading the SDK source above.
+
+**Private-API caveat.** We touch `mcp._mcp_server` and `_resource_manager._resources`. Pin `mcp` narrowly in `computer-use-server/requirements.txt` — an SDK minor bump requires re-verifying these attribute shapes.
+
+## Tier 5 — Uploaded files as MCP resources
+
+`resources/list` returns a `FunctionResource` per uploaded file with URI `file://uploads/{chat_id}/{url-encoded rel_path}`. `resources/read` fetches the content — text for `text/*` and a short MIME allowlist, base64 blob otherwise.
+
+Why `chat_id` embedded in the URI: Agents SDK and Inspector don't re-send `X-Chat-Id` on per-resource calls, so URIs must be self-contained.
+
+Why URL-encoding: FastMCP's `ResourceTemplate.matches` (verified at `.venv/.../templates.py:88`) uses `[^/]+` per template param — it blocks nested paths. Flattening via `urllib.parse.quote` sidesteps the limitation cleanly without forking the SDK.
+
+Dynamic registration: `sync_chat_resources(chat_id)` clears previously-registered entries for that chat, re-adds from the current filesystem state, under an `asyncio.Lock` to avoid "dict changed size during iteration" when a concurrent `resources/list` runs during an upload. Called from:
+- `docker_manager._create_container` — initial sync when the container spins up.
+- `app.py:upload_file` — after `POST /api/uploads/{chat_id}/{filename}` saves a new file.
+
+Upload itself stays on HTTP — **MCP has no upload primitive.** Community consensus is out-of-band HTTP alongside the MCP server.
+
+## Tier 6 — HTTP `/system-prompt`
+
+Kept for the Open WebUI filter (`openwebui/functions/computer_link_filter.py:224–363`) which fetches the prompt server-side and injects it into the LLM's system message. The endpoint reads:
+
+```
+X-Chat-Id | X-OpenWebUI-Chat-Id   > ?chat_id=           > "default"
+X-User-Email | X-OpenWebUI-User-Email > ?user_email=   > None
+```
+
+Header-priority rule consistent with the rest of the server (MCP middleware reads the same headers and aliases). Response header `X-Public-Base-URL` is still emitted so the filter's `outlet()` can build browser-facing archive/preview URLs from the server-owned `PUBLIC_BASE_URL`.
+
+## Render cache
+
+`render_system_prompt(chat_id, user_email)` is cache-backed with a 60-second TTL (`_RENDER_TTL_SECONDS` in `system_prompt.py`). Matches `skill_manager`'s own memory-cache TTL. Middleware runs the render on **every** MCP request to pre-fill the ContextVar for Tier 4, so the cache is load-bearing — without it, every `tools/call` would re-hit the skills provider. The second request for the same `(chat_id, user_email)` is a dict lookup.
+
+Invalidation: `invalidate_render_cache()` (no arg → clear all; `chat_id` arg → clear that chat). Used in tests; also callable when skills change upstream.
+
+## Duplication analysis (honest per-scenario breakdown)
+
+**Open WebUI via LiteLLM (main scenario):**
+- Filter `inlet()` fetches Tier 6 and puts the prompt into `body["messages"]` as a system message → model sees it **once**.
+- Tier 4 `InitializeResult.instructions` is returned on MCP `initialize` — but LiteLLM is a tool-call proxy, it does NOT ingest `instructions` and forward it to the LLM. Tier 4 simply doesn't reach the model here.
+- Tier 2 README.md sits in the container but the model only reads it if it actively calls `view`.
+- The **only** real duplication source in this scenario is the recovery-nudge in `bash_tool`/`view` docstrings (Tier 1): "If you've lost track of your environment, re-read /home/assistant/README.md." A model following that hint adds a **second copy** of the same ~3–5K tokens.
+- **Total: up to 2 copies** (filter inject + optional nudged `view`).
+
+**Agents SDK / MCP Inspector / Claude Desktop (MCP-native scenario):**
+- No Open WebUI filter.
+- Integrator surfaces Tier 4 via `server.server_initialize_result.instructions` (Agents SDK), or Claude Desktop auto-applies it → model sees prompt **once**.
+- Same story: if the Tier 1 nudge is honored, `view /home/assistant/README.md` adds a **second copy**.
+- **Total: up to 2 copies**.
+
+**Why keep the nudge.** Without it, a client that strips the system prompt leaves the model in a sandbox with zero context. The Tier 1 recovery hint is the only fallback that works in that pathological case — its token cost is paid only when the model actually needs it (context thins out, hint gets re-attended).
+
+Follow-up options if duplication proves costly in practice:
+- Weaken the nudge to "If your system prompt does not already describe this sandbox, read /home/assistant/README.md" — model self-selects.
+- Drop the nudge entirely and rely on Tier 4 + filter inject; README stays as a file-only fallback.
+- Teach the Open WebUI filter to skip its inject when the MCP tool is attached — only makes sense after Tier 4 reliably reaches the model through LiteLLM (today it does not).
+
+## See also
+
+- `docs/MCP.md` — protocol-level MCP server documentation.
+- `docs/openwebui-filter.md` — how the filter consumes Tier 6.
+- `computer-use-server/system_prompt.py` — the render function + cache.
+- `tests/orchestrator/test_{render_cache,dynamic_instructions,mcp_resources,tool_descriptions,readme_in_container,system_prompt_endpoint}.py` — pinning tests for every tier.

package/docs/terminal-flow.svg

@@ -0,0 +1,69 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 820 200" 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(#ah3); }
+      .arrow-label { font-size: 9px; fill: #6b7280; font-weight: 500; }
+    </style>
+    <marker id="ah3" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L8,3 L0,6" fill="#94a3b8"/>
+    </marker>
+  </defs>
+
+  <rect width="820" height="200" rx="12" fill="#fafbfc"/>
+  <text x="410" y="24" text-anchor="middle" font-size="13" font-weight="700" fill="#1e293b">Terminal Connection Flow</text>
+
+  <!-- User Browser -->
+  <rect x="20" y="55" width="150" height="90" class="box" fill="#6366f1" stroke="#4f46e5"/>
+  <text x="95" y="82" text-anchor="middle" class="label">User's Browser</text>
+  <text x="95" y="100" text-anchor="middle" class="sublabel">xterm.js terminal</text>
+  <text x="95" y="114" text-anchor="middle" class="sublabel">in side panel</text>
+
+  <!-- Arrow 1 -->
+  <path d="M170,100 L245,100" class="arrow"/>
+  <text x="207" y="92" text-anchor="middle" class="arrow-label">WebSocket</text>
+
+  <!-- Computer Use Server -->
+  <rect x="245" y="55" width="180" height="90" class="box" fill="#1e40af" stroke="#1e3a8a"/>
+  <text x="335" y="78" text-anchor="middle" class="label">Computer Use Server</text>
+  <text x="335" y="96" text-anchor="middle" class="sublabel">:8081</text>
+  <text x="335" y="110" text-anchor="middle" class="sublabel">WebSocket proxy</text>
+  <text x="335" y="124" text-anchor="middle" class="sublabel">/terminal/{chat_id}/ws</text>
+
+  <!-- Arrow 2 -->
+  <path d="M425,100 L500,100" class="arrow"/>
+  <text x="462" y="92" text-anchor="middle" class="arrow-label">WebSocket</text>
+
+  <!-- Container -->
+  <rect x="500" y="40" width="300" height="120" class="box" fill="#0f766e" stroke="#0d9488"/>
+  <text x="650" y="63" text-anchor="middle" class="label">Sandbox Container</text>
+
+  <!-- ttyd -->
+  <rect x="520" y="78" width="80" height="55" rx="6" fill="rgba(255,255,255,0.15)" stroke="rgba(255,255,255,0.3)"/>
+  <text x="560" y="98" text-anchor="middle" font-size="10" font-weight="600" fill="#fff">ttyd</text>
+  <text x="560" y="113" text-anchor="middle" font-size="8" fill="rgba(255,255,255,0.7)">:7681</text>
+  <text x="560" y="125" text-anchor="middle" font-size="8" fill="rgba(255,255,255,0.7)">WS server</text>
+
+  <!-- Arrow ttyd → tmux -->
+  <path d="M600,105 L625,105" class="arrow"/>
+
+  <!-- tmux -->
+  <rect x="625" y="78" width="75" height="55" rx="6" fill="rgba(255,255,255,0.15)" stroke="rgba(255,255,255,0.3)"/>
+  <text x="662" y="98" text-anchor="middle" font-size="10" font-weight="600" fill="#fff">tmux</text>
+  <text x="662" y="113" text-anchor="middle" font-size="8" fill="rgba(255,255,255,0.7)">persistent</text>
+  <text x="662" y="125" text-anchor="middle" font-size="8" fill="rgba(255,255,255,0.7)">session</text>
+
+  <!-- Arrow tmux → bash/claude -->
+  <path d="M700,105 L725,105" class="arrow"/>
+
+  <!-- bash / claude -->
+  <rect x="725" y="78" width="60" height="55" rx="6" fill="rgba(255,255,255,0.15)" stroke="rgba(255,255,255,0.3)"/>
+  <text x="755" y="98" text-anchor="middle" font-size="10" font-weight="600" fill="#fff">bash</text>
+  <text x="755" y="113" text-anchor="middle" font-size="8" fill="rgba(255,255,255,0.7)">Claude</text>
+  <text x="755" y="125" text-anchor="middle" font-size="8" fill="rgba(255,255,255,0.7)">Code CLI</text>
+
+  <!-- Footer notes -->
+  <text x="20" y="185" font-size="9" fill="#64748b">Persistent session: disconnect and reconnect without losing state. Claude Code auto-starts on first login.</text>
+</svg>

package/examples/helm/README.md

@@ -0,0 +1,20 @@
+# Helm examples
+
+Two ready-to-tweak deployment recipes for [`helm/computer-use-server/`](../../helm/computer-use-server/).
+
+| Recipe | Equivalent Compose stack | When to use |
+|---|---|---|
+| [`standalone/`](standalone/) | `docker-compose.yml` | You already run Open WebUI (or some other MCP client) and just want the orchestrator. |
+| [`with-open-webui/`](with-open-webui/) | `docker-compose.yml` + `docker-compose.webui.yml` | You want the whole stack — orchestrator, Open WebUI, Postgres — in one cluster. |
+
+Open WebUI itself is **not** packaged by our chart. Use the upstream chart at <https://github.com/open-webui/helm-charts> instead — `with-open-webui/` shows how to wire the two together.
+
+## Prerequisites
+
+- Kubernetes ≥ 1.27
+- [Kata Containers](https://katacontainers.io/) installed on candidate nodes (the chart runs the inner Docker daemon under Kata) — see [`docs/kata-runtime.md`](../../docs/kata-runtime.md)
+- A StorageClass that supports `ReadWriteOnce`, and one that provisions Block volumes for `/var/lib/docker`
+- An Ingress controller (nginx-ingress, Traefik, etc.)
+- DNS + TLS for the public hostnames
+
+See [`docs/kubernetes.md`](../../docs/kubernetes.md) for the full architecture overview.

package/examples/helm/standalone/values.yaml

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: FSL-1.1-Apache-2.0
+# Copyright (c) 2025 Open Computer Use Contributors
+#
+# Minimum-viable values for computer-use-server.
+#
+# The chart runs the inner Docker daemon under Kata Containers. Before installing:
+#   1. Install kata-deploy and confirm the RuntimeClass exists:
+#        kubectl get runtimeclass kata-qemu
+#   2. Allow privileged pods in the target namespace:
+#        kubectl label ns open-computer-use \
+#          pod-security.kubernetes.io/enforce=privileged --overwrite
+#   3. The cluster default StorageClass must provision Block volumes (the chart
+#      uses a Block-mode PVC for /var/lib/docker). Override
+#      persistence.varLibDocker.persistentVolume.storageClass if it does not.
+# Full runbook: docs/kata-runtime.md.
+#
+# Run:
+#   helm install ocu helm/computer-use-server \
+#     -n open-computer-use --create-namespace \
+#     -f examples/helm/standalone/values.yaml
+#
+# Replace the placeholders (change-me-*, *.example.com) before applying.
+
+secrets:
+  create: true
+  # `openssl rand -hex 32` is a fine source
+  mcpApiKey: "change-me-32-hex-chars"
+
+orchestrator:
+  env:
+    # MUST be the browser-reachable URL of the Ingress below (no trailing slash).
+    # The orchestrator bakes this into preview links it returns to chats.
+    PUBLIC_BASE_URL: "https://orchestrator.example.com"
+
+ingress:
+  enabled: true
+  className: nginx
+  annotations:
+    # uncomment if using cert-manager
+    # cert-manager.io/cluster-issuer: letsencrypt-prod
+  hosts:
+    - host: orchestrator.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+  tls:
+    - hosts:
+        - orchestrator.example.com
+      secretName: orchestrator-tls

package/examples/helm/with-open-webui/README.md

@@ -0,0 +1,99 @@
+# Open WebUI + computer-use-server on Kubernetes
+
+This is the Kubernetes analog of running `docker-compose.yml` + `docker-compose.webui.yml` together. You install two Helm charts side-by-side in the same namespace and wire them through a shared Secret.
+
+```text
+┌──────────────────────── namespace: open-computer-use ──────────────────────────┐
+│                                                                                 │
+│  Users ── Ingress ──► Service: open-webui :3000                                │
+│                              │                                                  │
+│                              │ HTTP (ORCHESTRATOR_URL, MCP_API_KEY)            │
+│                              ▼                                                  │
+│                  Service: ocu-computer-use-server :8081                         │
+│                  (Kata DinD pod, see helm/computer-use-server/README.md)         │
+│                              │                                                  │
+│                              ▼                                                  │
+│                  StatefulSet: postgres  (Bitnami subchart, or BYO)              │
+└─────────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Prerequisites
+
+The same prereqs as `standalone/`: Kata Containers on nodes (see [`docs/kata-runtime.md`](../../../docs/kata-runtime.md)), RWO + Block StorageClass, Ingress controller, DNS + TLS. Plus:
+
+- The upstream Open WebUI Helm repo configured:
+  ```bash
+  helm repo add open-webui https://helm.openwebui.com/
+  helm repo update
+  ```
+
+## Install steps
+
+```bash
+# 0. Create namespace
+kubectl create namespace open-computer-use
+
+# 1. Shared Secret used by both charts. MCP_API_KEY must match in both places.
+kubectl -n open-computer-use create secret generic ocu-shared \
+  --from-literal=MCP_API_KEY=$(openssl rand -hex 32) \
+  --from-literal=POSTGRES_PASSWORD=$(openssl rand -hex 24) \
+  --from-literal=WEBUI_SECRET_KEY=$(openssl rand -hex 32) \
+  --from-literal=ANTHROPIC_AUTH_TOKEN=sk-ant-...  # if using Anthropic
+
+# 2. Install Postgres as a separate release (this chart does NOT bundle it).
+helm repo add bitnami https://charts.bitnami.com/bitnami
+helm repo update
+helm install pg bitnami/postgresql \
+  -n open-computer-use \
+  --set auth.username=openwebui \
+  --set auth.database=openwebui \
+  --set auth.existingSecret=ocu-shared \
+  --set auth.secretKeys.userPasswordKey=POSTGRES_PASSWORD
+
+# 3. Install computer-use-server. Edit values-computer-use.yaml first.
+helm install ocu ../../../helm/computer-use-server \
+  -n open-computer-use \
+  -f values-computer-use.yaml
+
+# 4. Install Open WebUI. Edit values-open-webui.yaml first.
+helm install webui open-webui/open-webui \
+  -n open-computer-use \
+  -f values-open-webui.yaml
+
+# 5. Smoke-test
+helm test ocu -n open-computer-use
+kubectl -n open-computer-use get pods
+```
+
+## How the wiring works
+
+- **`MCP_API_KEY`** lives in the shared `ocu-shared` Secret.
+  - `computer-use-server` reads it via `secrets.existingSecret=ocu-shared` (mounted via `envFrom` onto the orchestrator container).
+  - Open WebUI reads it the same way, then `openwebui/init.sh` (or your manual setup) seeds it into the Tool and Filter Valves on first boot. **The values must match** — that's the whole reason for sharing one Secret.
+
+- **`ORCHESTRATOR_URL`** is the **in-cluster** URL Open WebUI uses to call the MCP endpoint:
+  ```text
+  http://ocu-computer-use-server.open-computer-use.svc.cluster.local:8081
+  ```
+  Set as a plain env var on the Open WebUI container — `values-open-webui.yaml` shows the line. Browsers never see this URL.
+
+- **`PUBLIC_BASE_URL`** is the **browser-facing** URL of the orchestrator. The orchestrator returns it in the `X-Public-Base-URL` header, and the Open WebUI filter uses it to rewrite preview links in chat. It must match the public hostname users actually hit. Set in `values-computer-use.yaml`.
+
+> Note: the `openwebui/init.sh` script from this repo expects to run as the Open WebUI container's entrypoint wrapper. The upstream Open WebUI chart does **not** invoke it. Either build your own image (using `openwebui/Dockerfile` from this repo) and point the upstream chart at it via `image.repository`, or seed the Valves manually through the Admin UI on first boot. Both paths work — the init.sh path is more reproducible.
+
+## Files in this directory
+
+| File | Purpose |
+|---|---|
+| `values-computer-use.yaml` | values for our chart (orchestrator + DinD + cleanup) |
+| `values-open-webui.yaml` | values for upstream Open WebUI chart, pointed at our Service |
+
+## Uninstall
+
+```bash
+helm uninstall webui -n open-computer-use
+helm uninstall ocu   -n open-computer-use
+kubectl -n open-computer-use delete pvc -l app.kubernetes.io/instance=ocu
+kubectl -n open-computer-use delete pvc -l app.kubernetes.io/instance=webui
+kubectl -n open-computer-use delete secret ocu-shared
+```

package/examples/helm/with-open-webui/values-computer-use.yaml

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: FSL-1.1-Apache-2.0
+# Copyright (c) 2025 Open Computer Use Contributors
+#
+# Values for helm/computer-use-server when deployed alongside Open WebUI.
+# See examples/helm/with-open-webui/README.md for install order and Secret setup.
+
+secrets:
+  # GitOps-friendly: chart reads MCP_API_KEY + tokens from the existing Secret.
+  create: false
+  existingSecret: ocu-shared
+
+orchestrator:
+  env:
+    # Must match the host users hit in their browser — same as the Ingress below.
+    PUBLIC_BASE_URL: "https://orchestrator.example.com"
+
+ingress:
+  enabled: true
+  className: nginx
+  annotations:
+    # cert-manager.io/cluster-issuer: letsencrypt-prod
+  hosts:
+    - host: orchestrator.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+  tls:
+    - hosts:
+        - orchestrator.example.com
+      secretName: orchestrator-tls
+
+# Postgres lives in a separate release — see README.md, "Install steps", step 2.

package/examples/helm/with-open-webui/values-open-webui.yaml

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: FSL-1.1-Apache-2.0
+# Copyright (c) 2025 Open Computer Use Contributors
+#
+# Values for the upstream open-webui/open-webui chart, configured to talk to
+# our computer-use-server. Reference: https://github.com/open-webui/helm-charts
+#
+# Adjust to match the upstream chart's actual value paths — this file targets
+# the typical layout (image.repository, extraEnvVars, envFrom, persistence,
+# ingress). Re-check after major chart upgrades.
+
+# Use a custom Open WebUI image built from openwebui/Dockerfile in this repo
+# (it patches Open WebUI and bundles init.sh which seeds the Computer Use
+# Tool + Filter Valves on first boot). Skip this and use stock Open WebUI if
+# you'll configure Valves through the Admin UI by hand.
+image:
+  # Built from openwebui/Dockerfile by .github/workflows/build.yml as "<repo>-webui".
+  repository: ghcr.io/wide-moat/open-computer-use-webui
+  tag: "0.9.2.4"
+  pullPolicy: IfNotPresent
+
+ingress:
+  enabled: true
+  class: nginx
+  host: webui.example.com
+  tls: true
+  existingSecret: webui-tls
+
+persistence:
+  enabled: true
+  size: 10Gi
+
+# Use the bundled Postgres from our chart (ocu-postgresql.*.svc.cluster.local).
+# DATABASE_URL is built from the shared Secret.
+databaseUrl: "postgresql://openwebui:$(POSTGRES_PASSWORD)@pg-postgresql.open-computer-use.svc.cluster.local:5432/openwebui"
+
+# Disable the chart's bundled DBs since we use the one from computer-use-server.
+postgresql:
+  enabled: false
+ollama:
+  enabled: false
+pipelines:
+  enabled: false
+
+# Plain env vars that the openwebui/init.sh script and the patched code read.
+extraEnvVars:
+  - name: ORCHESTRATOR_URL
+    value: "http://ocu-computer-use-server.open-computer-use.svc.cluster.local:8081"
+  - name: BYPASS_EMBEDDING_AND_RETRIEVAL
+    value: "true"
+  - name: RAG_EMBEDDING_MODEL_AUTO_UPDATE
+    value: "false"
+  - name: CHAT_RESPONSE_MAX_TOOL_CALL_RETRIES
+    value: "200"
+  - name: TOOL_RESULT_MAX_CHARS
+    value: "50000"
+  - name: TOOL_RESULT_PREVIEW_CHARS
+    value: "2000"
+  - name: ENABLE_OPENAI_API_SSL_VERIFY
+    value: "true"
+  - name: ADMIN_EMAIL
+    value: "admin@example.com"
+
+# MCP_API_KEY, POSTGRES_PASSWORD, WEBUI_SECRET_KEY, ANTHROPIC_AUTH_TOKEN come
+# from the shared Secret created out-of-band (see README).
+extraEnvFrom:
+  - secretRef:
+      name: ocu-shared

package/helm/computer-use-server/.helmignore

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: BUSL-1.1
+# Copyright (c) 2025 Open Computer Use Contributors
+# Patterns to ignore when packaging the chart.
+.DS_Store
+.git/
+.gitignore
+.bzr/
+.hg/
+.hgignore
+.svn/
+*.swp
+*.tmp
+*.orig
+*.bak
+.idea/
+.vscode/
+*.tgz

package/helm/computer-use-server/Chart.yaml

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: FSL-1.1-Apache-2.0
+# Copyright (c) 2025 Open Computer Use Contributors
+apiVersion: v2
+name: computer-use-server
+description: |
+  Orchestrator for open-computer-use. Spawns disposable workspace
+  containers via an inner Docker daemon (DinD on Kata Containers).
+  Includes an optional cleanup sidecar. Postgres is installed as a separate
+  release when needed; see examples/helm/with-open-webui/.
+type: application
+version: 0.3.0
+appVersion: "0.9.2.4"
+kubeVersion: ">=1.27.0-0"
+home: https://github.com/Wide-Moat/open-computer-use
+sources:
+  - https://github.com/Wide-Moat/open-computer-use
+keywords:
+  - computer-use
+  - mcp
+  - open-webui
+  - sandbox
+  - dind
+  - kata-containers
+maintainers:
+  - name: Open Computer Use Contributors
+    url: https://github.com/Wide-Moat/open-computer-use
+annotations:
+  category: AI
+# Note: PostgreSQL is intentionally NOT a chart dependency. The orchestrator
+# itself does not need a database; only Open WebUI does. Install Postgres
+# separately (managed RDS, CloudNativePG, or `helm install pg bitnami/postgresql`)
+# and point Open WebUI at it via DATABASE_URL. See examples/helm/with-open-webui/.