@mseep/open-computer-use 1.0.0

package/docs/kata-runtime.md

@@ -0,0 +1,267 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# Kata Containers runtime (containerd 2.x)
+
+This guide is the runbook for deploying `computer-use-server` on Kubernetes with
+**[Kata Containers](https://katacontainers.io/)** as the inner Docker-in-Docker
+(DinD) runtime. It covers why Kata, how to install it, how to configure the Helm
+chart, and how to verify and troubleshoot the result.
+
+For the chart reference in general, see [`kubernetes.md`](kubernetes.md) and the
+[chart README](../helm/computer-use-server/README.md).
+
+---
+
+## Why Kata
+
+Kata Containers is the supported DinD runtime for the Helm chart. It runs each
+pod inside a lightweight VM (a *microVM*) with its own guest kernel, works on
+**containerd 2.x** — the runtime that ships with current Kubernetes
+distributions (RKE2 / k3s / kubeadm ≥ 1.34) — and gives **hypervisor-grade
+isolation**. The cost is a slower cold start and a fixed per-pod memory overhead
+(see [Tradeoffs](#tradeoffs)).
+
+---
+
+## Prerequisites
+
+- A Kubernetes cluster on **containerd 2.x**.
+- Nodes that can run a hypervisor: **nested virtualization or bare metal** with
+  `/dev/kvm` available. Check with `ls -l /dev/kvm` on a node.
+- `helm` ≥ 3.14.
+- The target namespace must allow privileged pods (Kata DinD runs privileged —
+  see [why](#step-2--configure-the-helm-chart)). Pod Security Admission `enforce`
+  baseline must be `privileged` for that namespace.
+
+---
+
+## Step 1 — Install kata-deploy
+
+[`kata-deploy`](https://github.com/kata-containers/kata-containers/tree/main/tools/packaging/kata-deploy)
+is the official installer. It runs a DaemonSet that drops the Kata binaries and
+containerd shim onto each node and registers the `RuntimeClass` objects.
+
+```bash
+helm install kata-deploy \
+  oci://ghcr.io/kata-containers/kata-deploy-charts/kata-deploy \
+  --version 3.30.0 \
+  --namespace kube-system \
+  --set env.shims=qemu \
+  --set env.defaultShim=qemu \
+  --set env.createDefaultRuntimeClass=false
+```
+
+- `env.shims=qemu` installs only the QEMU shim — the one this guide uses. Add
+  others (`fc`, `clh`) only if you need them.
+- `createDefaultRuntimeClass=false` keeps `runc` as the cluster default — Kata
+  is opt-in per workload, not cluster-wide.
+
+Verify the RuntimeClass landed:
+
+```bash
+kubectl get runtimeclass kata-qemu
+# NAME        HANDLER
+# kata-qemu   kata-qemu
+```
+
+### Optional — a "heavy" RuntimeClass for large guests
+
+The Computer Use workspace can need a multi-GiB guest. RuntimeClass `overhead`
+is fixed per class, so for large guests create a dedicated class:
+
+```yaml
+apiVersion: node.k8s.io/v1
+kind: RuntimeClass
+metadata:
+  name: kata-qemu-heavy
+handler: kata-qemu
+overhead:
+  podFixed:
+    memory: "350Mi"
+    cpu: "250m"
+scheduling:
+  nodeSelector:
+    katacontainers.io/kata-runtime: "true"
+```
+
+The **guest memory** itself is set per-pod via annotations, not the RuntimeClass.
+Add them under `orchestrator.podAnnotations` (or `podAnnotations`) in the chart:
+
+```yaml
+podAnnotations:
+  io.katacontainers.config.hypervisor.default_memory: "8192"     # MiB
+  io.katacontainers.config.hypervisor.default_maxmemory: "16384"
+  io.katacontainers.config.hypervisor.default_vcpus: "4"
+```
+
+For these annotations to be honored, kata-deploy must allow them — pass
+`--set 'env.allowedHypervisorAnnotations=default_memory default_maxmemory default_vcpus'`
+at install time.
+
+---
+
+## Step 2 — Configure the Helm chart
+
+The chart defaults already target Kata — the keys below are the chart defaults,
+shown here so you understand what each one does. A ready-to-edit values file is
+at [`examples/helm/standalone/values.yaml`](../examples/helm/standalone/values.yaml).
+
+```yaml
+orchestrator:
+  runtimeClassName: kata-qemu          # or kata-qemu-heavy
+
+dind:
+  privileged: true                     # REQUIRED — see below
+  storageDriver: fuse-overlayfs        # overlay2 fails on the Kata guest root
+  kataInit:
+    enabled: true                      # runs the chart-managed guest init wrapper
+
+persistence:
+  varLibDocker:
+    persistentVolume:
+      enabled: true                    # Block PVC — preserves xattrs
+      size: 50Gi
+      storageClass: longhorn           # must provision Block volumes
+```
+
+Why each setting:
+
+- **`dind.privileged: true`** — `dockerd` needs `CAP_NET_ADMIN`/`CAP_NET_RAW` to
+  build its iptables NAT chain. Without it dockerd fails with
+  `iptables: Could not fetch rule set generation id: Permission denied`.
+  **This is safe under Kata** — the capabilities are confined to the microVM and
+  cannot reach the host kernel.
+- **`dind.storageDriver: fuse-overlayfs`** — `overlay2` cannot mount on the Kata
+  virtio-fs guest root
+  ([kata-containers#1888](https://github.com/kata-containers/kata-containers/issues/1888)).
+  `fuse-overlayfs` is a userspace overlay filesystem with full xattr support.
+- **`dind.kataInit.enabled: true`** — runs the chart-managed entrypoint wrapper
+  ([see below](#what-the-katainit-wrapper-does)).
+- **Block PVC for `/var/lib/docker`** — the Kata virtio-fs root drops
+  `security.capability` xattrs (CVE-2021-20263), which breaks binaries that rely
+  on file capabilities (e.g. GStreamer in the workspace image). A **Block-mode**
+  PVC arrives in the guest as a raw `virtio-blk` device; the init wrapper formats
+  it `ext4` and mounts it, and ext4 preserves xattrs.
+
+Install:
+
+```bash
+kubectl create namespace open-computer-use
+kubectl label namespace open-computer-use \
+  pod-security.kubernetes.io/enforce=privileged --overwrite
+
+helm install ocu helm/computer-use-server \
+  -n open-computer-use \
+  -f examples/helm/standalone/values.yaml
+```
+
+---
+
+## What the `kataInit` wrapper does
+
+When `dind.kataInit.enabled: true`, the dind container's entrypoint is a
+chart-managed script (rendered into a ConfigMap, see
+`templates/configmap-dind-init.yaml`). Before `exec`-ing `dockerd` it runs four
+idempotent, self-detecting steps:
+
+1. **Install `fuse-overlayfs`** — `apk add --no-cache fuse-overlayfs` if it is
+   not already present. Add more packages via `dind.kataInit.extraPackages`.
+2. **Create `/dev/fuse`** — the Kata guest kernel has `fuse` compiled in but no
+   device node; `mknod /dev/fuse c 10 229`.
+3. **Format + mount the Block PVC** — if `persistence.varLibDocker.persistentVolume`
+   is enabled, `mkfs.ext4` the raw device once (skipped if already formatted),
+   then mount it at `/var/lib/docker`.
+4. **cgroup-v2 PID-1 evacuation** — the Kata guest's systemd leaves PID 1 in a
+   domain-threaded root cgroup, which blocks nested `runc`
+   (`cannot enter cgroupv2 ... with domain controllers`). The wrapper moves
+   processes into a child cgroup and republishes controllers at the root
+   ([docker-library/docker#308](https://github.com/docker-library/docker/issues/308)).
+
+Every step no-ops cleanly on an environment that does not need it.
+
+### Alternative — a pre-baked custom image
+
+If you prefer not to `apk add` at container start (faster cold start, air-gapped
+clusters), build a custom dind image and point `dind.image` at it:
+
+```dockerfile
+FROM docker:27-dind
+RUN apk add --no-cache fuse-overlayfs
+```
+
+You can still keep `dind.kataInit.enabled: true` — step 1 becomes a no-op while
+steps 2–4 still run. Or disable `kataInit` entirely and bake the init logic into
+your image's own entrypoint.
+
+---
+
+## Step 3 — Verify
+
+```bash
+# RuntimeClass is registered
+kubectl get runtimeclass kata-qemu
+
+# The pod is scheduled with the Kata RuntimeClass
+kubectl -n open-computer-use get pod -l app.kubernetes.io/name=computer-use-server \
+  -o jsonpath='{.items[0].spec.runtimeClassName}'   # => kata-qemu
+
+# dockerd is healthy and using fuse-overlayfs
+POD=$(kubectl -n open-computer-use get pod -l app.kubernetes.io/name=computer-use-server -o name)
+kubectl -n open-computer-use exec "$POD" -c dind -- docker info | grep "Storage Driver"
+#   Storage Driver: fuse-overlayfs
+
+# /dev/fuse exists and /var/lib/docker is the ext4 Block volume
+kubectl -n open-computer-use exec "$POD" -c dind -- sh -c 'ls -l /dev/fuse; mount | grep /var/lib/docker'
+
+# Orchestrator health
+helm test ocu -n open-computer-use
+```
+
+Finally, open a chat and confirm a workspace container spawns and tool calls
+succeed end to end.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `dockerd: iptables: Could not fetch rule set generation id: Permission denied` | dind not privileged | set `dind.privileged: true` |
+| `failed to mount overlay: operation not permitted` | `overlay2` on the Kata virtio-fs root ([kata#1888](https://github.com/kata-containers/kata-containers/issues/1888)) | set `dind.storageDriver: fuse-overlayfs` + `dind.kataInit.enabled: true` |
+| `runc ... cannot enter cgroupv2 ... with domain controllers` | Kata guest PID-1 domain-threaded cgroup | `dind.kataInit.enabled: true` runs the cgroup shim |
+| Workspace binaries fail / missing file capabilities (e.g. GStreamer) | virtio-fs drops `security.capability` xattrs (CVE-2021-20263) | enable `persistence.varLibDocker.persistentVolume` (Block PVC) |
+| Pod stuck `Pending`, `runtimeclass not found` | kata-deploy not installed / DaemonSet not ready on the node | check `kubectl -n kube-system get ds kata-deploy` and `kubectl get runtimeclass` |
+| Pod rejected by Pod Security Admission | namespace `enforce` is not `privileged` | `kubectl label ns <ns> pod-security.kubernetes.io/enforce=privileged --overwrite` |
+| `mknod`/`mkfs` errors in dind logs | wrapper running but device absent | confirm the PVC is `volumeMode: Block` and bound; check `kubectl get pvc` |
+
+---
+
+## Tradeoffs
+
+Kata is the runtime the chart uses. The table puts it next to the
+`runc + privileged` fallback for context — that fallback is functional but
+insecure, fit for local testing only.
+
+| Dimension | Kata-qemu (chart default) | runc + privileged (testing only) |
+|---|---|---|
+| Isolation | hardware VM, **separate** guest kernel | none — host kernel, escape is trivial |
+| containerd 2.x | ✅ works | ✅ works |
+| Cold start | slower (microVM boot, ~1–3 s) | fast |
+| Storage driver | `fuse-overlayfs` (`overlay2` fails) | `overlay2` / `vfs` |
+| Memory overhead | ~150–350 MiB/pod (guest kernel + hypervisor) | none |
+| `privileged` needed | yes — but caps confined to the VM | yes — caps on the **host** |
+| Setup complexity | medium (kata-deploy, init wrapper, Block PVC) | low |
+| Production-safe | yes | **no** |
+
+**Bottom line:** Kata is the recommended runtime — strong isolation and it works
+on modern containerd 2.x. `runc + privileged` works too, but the inner daemon
+shares the host kernel, so it is a local-testing escape hatch only, never
+production.
+
+## See also
+
+- [`kubernetes.md`](kubernetes.md) — Kubernetes deployment overview
+- [chart README](../helm/computer-use-server/README.md) — full values reference
+- [ADR-0011](future-architecture/adr/0011-kata-as-first-class-dind-runtime.md) — the decision record
+- [`examples/helm/standalone/values.yaml`](../examples/helm/standalone/values.yaml) — copy-paste config

package/docs/kubernetes.md

@@ -0,0 +1,86 @@
+# Kubernetes deployment
+
+The Docker Compose stack in `docker-compose.yml` / `docker-compose.webui.yml` ships as a Helm chart in [`helm/computer-use-server/`](../helm/computer-use-server/). This is the recommended way to run open-computer-use on Kubernetes.
+
+## Runtime
+
+The orchestrator runs an inner Docker daemon, which needs a DinD-capable runtime
+on the node. The chart uses **[Kata Containers](https://katacontainers.io/)** —
+it works on modern containerd 2.x clusters (RKE2 / k3s / kubeadm ≥ 1.34) and
+isolates the pod in a microVM. Install `kata-deploy` and follow the
+[Kata runtime guide](kata-runtime.md) before installing the chart.
+
+## Quick start
+
+```bash
+# 1. Install Kata Containers (kata-deploy) on the nodes once — see
+#    docs/kata-runtime.md. Confirm the RuntimeClass exists:
+kubectl get runtimeclass kata-qemu
+
+# 2. Add the chart repo (published from the gh-pages branch on every release tag):
+helm repo add open-computer-use https://wide-moat.github.io/open-computer-use
+helm repo update
+
+# 3. Install:
+helm install ocu open-computer-use/computer-use-server \
+  --namespace open-computer-use --create-namespace \
+  --values examples/helm/standalone/values.yaml
+```
+
+Or, against a git checkout for unreleased changes:
+
+```bash
+helm install ocu helm/computer-use-server \
+  --namespace open-computer-use --create-namespace \
+  --values examples/helm/standalone/values.yaml
+```
+
+The chart README at [`helm/computer-use-server/README.md`](../helm/computer-use-server/README.md) is the authoritative reference. This page is the navigation.
+
+## Examples
+
+- **[`examples/helm/standalone/`](../examples/helm/standalone/)** — minimum-viable config (just the orchestrator). Closest to `docker-compose.yml`.
+- **[`examples/helm/with-open-webui/`](../examples/helm/with-open-webui/)** — orchestrator + Open WebUI via the upstream Open WebUI Helm chart. Closest to `docker-compose.yml` + `docker-compose.webui.yml` together.
+
+## Architecture
+
+The orchestrator pod has three containers:
+
+```text
+┌──────────────────────────── Pod (runtimeClassName: kata-qemu) ──────────────────┐
+│                                                                                 │
+│  ┌─────────────────┐   ┌─────────────────┐   ┌──────────────────────────────┐  │
+│  │  orchestrator   │──►│   inner dockerd │◄──│  cleanup sidecar (cron)      │  │
+│  │  FastAPI :8081  │   │  spawns chat-*  │   │  reaps stale chat-* + data   │  │
+│  └─────────────────┘   └─────────────────┘   └──────────────────────────────┘  │
+│        │ /var/run/docker.sock  ▲       ▲                  ▲                     │
+│        └──────── shared emptyDir (dind-socket) ───────────┘                     │
+│                                                                                 │
+│  Volumes:                                                                       │
+│   - emptyDir  dind-socket    → /var/run on all three containers                │
+│   - Block PVC var-lib-docker → /var/lib/docker on dind ONLY (xattr-safe)       │
+│   - PVC       user-data      → /tmp/computer-use-data (RWO)                    │
+│   - PVC       data           → /data (RWO)                                     │
+│   - PVC       skills-cache   → /data/skills-cache (RWO)                        │
+└─────────────────────────────────────────────────────────────────────────────────┘
+```
+
+**Why DinD instead of native k8s Pods?**
+The existing orchestrator code talks to a Docker socket. Lifting it onto Kubernetes via Kata Containers keeps the app code unchanged. A future `K8sBackend` rewrite (drafted in [`docs/future-architecture/`](future-architecture/)) will spawn native Pods, at which point the inner dockerd disappears — but that's a separate workstream.
+
+**Why is the orchestrator single-replica?**
+It owns the inner Docker daemon and three RWO PVCs. There is no shared state between replicas and no leader-election. The chart hard-pins `replicas: 1` in `values.schema.json`.
+
+## Prerequisites checklist
+
+- Kubernetes ≥ 1.27
+- StorageClass that supports `ReadWriteOnce` and is the cluster default (or pass `persistence.*.storageClass` explicitly), plus one that provisions Block volumes for `/var/lib/docker`
+- Kata Containers installed on candidate nodes + the `kata-qemu` `RuntimeClass` — see [`kata-runtime.md`](kata-runtime.md)
+- Ingress controller (nginx-ingress, Traefik, etc.) if you set `ingress.enabled=true`
+- DNS + TLS cert for the public hostname referenced by `PUBLIC_BASE_URL`
+
+## See also
+
+- [`helm/computer-use-server/README.md`](../helm/computer-use-server/README.md) — chart reference and troubleshooting
+- [`docs/kata-runtime.md`](kata-runtime.md) — Kata Containers runtime guide (install, configure, verify, troubleshoot)
+- [`docs/future-architecture/`](future-architecture/) — draft of the future native-Pod backend (not implemented)

package/docs/multi-cli.md

@@ -0,0 +1,161 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# Multi-CLI Sub-Agent Runtime
+
+> The orchestrator dispatches sub-agent calls to one of three CLIs based on the `SUBAGENT_CLI` environment variable. Default unset = `claude` (byte-identical backwards-compat with v0.9.2.0).
+
+## When to flip the switch
+
+| Goal | `SUBAGENT_CLI` | Why |
+|------|----------------|-----|
+| Default — Anthropic / LiteLLM gateway | `claude` (or unset) | Native Claude Code; cost reporting; max-turns enforced |
+| OpenAI Codex (gpt-5-codex etc.) | `codex` | First-party OpenAI tooling; `--ephemeral` runs; no built-in cost reporting |
+| OpenRouter / qwen / DeepSeek / OSS / Bedrock-via-LiteLLM | `opencode` | 75+ provider router; per-step cost when provider reports it |
+
+## Setup — common steps (apply to all three)
+
+1. Pull the latest `open-computer-use` image (codex + opencode are pre-installed alongside claude).
+2. Set `SUBAGENT_CLI=<value>` in your `.env`.
+3. Set the per-CLI auth env vars (see the per-CLI sections below).
+4. Restart the orchestrator: `docker compose up -d --force-recreate computer-use-server`.
+5. Verify the runtime took effect:
+   ```bash
+   docker compose logs computer-use-server | grep "Sub-agent runtime"
+   # Expected: [MCP] Sub-agent runtime: <value>
+   ```
+6. Spawn a sandbox (any chat or `/health` poke) and verify the CLI is on PATH:
+   ```bash
+   docker exec <sandbox-container> <cli> --version
+   # Expected: a non-zero version string
+   ```
+
+## Switch to Claude (default — no setup needed)
+
+This is the default path. If you previously set `SUBAGENT_CLI=codex` or `=opencode` and want to revert, either delete the line from `.env` or set `SUBAGENT_CLI=claude` explicitly — both resolve identically.
+
+For Anthropic / LiteLLM gateway configuration, see [`docs/claude-code-gateway.md`](./claude-code-gateway.md).
+
+## Switch to Codex
+
+Add to `.env`:
+```bash
+SUBAGENT_CLI=codex
+OPENAI_API_KEY=sk-...
+# Optional gateway (Azure OpenAI, LiteLLM proxy, etc.):
+OPENAI_BASE_URL=https://your-litellm-proxy/v1
+# Optional per-CLI default model:
+CODEX_SUB_AGENT_DEFAULT_MODEL=gpt-5-codex
+```
+
+Restart per common steps. The container's `~/.codex/config.toml` is rendered conditionally:
+- with `OPENAI_BASE_URL` set → contains a `[model_providers.custom]` block pointing at your gateway;
+- without it → empty file (Codex uses defaults).
+
+Verify:
+```bash
+docker exec <sandbox> codex --version    # Expect: codex-cli 0.125.0
+docker exec <sandbox> cat ~/.codex/config.toml
+```
+
+## Switch to OpenCode + qwen3-coder via OpenRouter (worked recipe)
+
+This is the headline recipe — runs sub-agents against a frontier OSS coding model with no Anthropic dependency.
+
+Add to `.env`:
+```bash
+SUBAGENT_CLI=opencode
+OPENROUTER_API_KEY=sk-or-v1-...
+OPENCODE_SUB_AGENT_DEFAULT_MODEL=openrouter/qwen/qwen-3-coder
+```
+
+Restart:
+```bash
+docker compose up -d --force-recreate computer-use-server
+```
+
+Verify the orchestrator picked up the runtime:
+```bash
+docker compose logs computer-use-server | grep "Sub-agent runtime"
+# Expected: [MCP] Sub-agent runtime: opencode
+```
+
+Spawn any sandbox and verify the OpenCode config is rendered without leaking the key:
+```bash
+docker exec <sandbox> cat /tmp/opencode.json
+# Expected: provider.openrouter.options.apiKey is "{env:OPENROUTER_API_KEY}" — NOT a literal sk-or-v1-... value
+# OpenCode 1.14.x schema: top-level key is "provider" (singular), apiKey nested under "options".
+```
+
+The `{env:VAR}` syntax means OpenCode resolves the key at runtime from the container env. The file on disk contains zero plaintext secrets — the sandbox volume can be mounted, copied, or shared without leaking your OpenRouter key.
+
+Trigger a sub-agent call from the chat (or via the MCP `sub_agent` tool). Expected response shape:
+```text
+**Sub-Agent Completed** (success)
+<the qwen3-coder reply>
+**Cost:** unavailable | **Duration:** 12.3s | **Turns:** unavailable
+```
+
+`Cost: unavailable` is **expected** for opencode runs — see the next section.
+
+## What changes when you flip the switch
+
+| Aspect | claude | codex | opencode |
+|--------|--------|-------|----------|
+| Cost reporting | reported as USD | unavailable | depends on provider (some report per-step cost) |
+| `max_turns` enforcement | enforced (CLI flag) | not enforced — `SUB_AGENT_TIMEOUT` is the backstop | not enforced — `SUB_AGENT_TIMEOUT` is the backstop |
+| `resume_session_id` | supported | ignored with stderr warning (`--ephemeral` is stateless) | ignored with stderr warning |
+| Model alias `sonnet` / `opus` / `haiku` | resolves to Claude IDs | hard-fail with actionable error message | resolves to `anthropic/claude-X-X` provider/model |
+| Direct provider/model strings (e.g. `openrouter/qwen/qwen-3-coder`) | pass-through | pass-through | pass-through |
+| `~/.claude/projects/*.jsonl` live log streaming | yes | no | no |
+| Image install | always (pre-installed) | always (pre-installed) | always (pre-installed) |
+
+If you set a Claude alias (`sonnet`/`opus`/`haiku`) while `SUBAGENT_CLI=codex`, the orchestrator hard-fails with a clear error rather than silently 400-ing against OpenAI:
+
+```text
+Model alias 'sonnet' is Claude-only; SUBAGENT_CLI=codex requires a GPT model id
+(e.g. 'gpt-5-codex') or set CODEX_SUB_AGENT_DEFAULT_MODEL.
+```
+
+## Escape hatch — plain bash terminal
+
+`SUBAGENT_CLI` makes the in-browser ttyd terminal auto-launch the chosen CLI. To get a plain bash prompt instead:
+
+```bash
+# Per-session (in a new terminal tab):
+NO_AUTOSTART=1 bash
+
+# OR persistently for this container (next ttyd session):
+touch /tmp/.no_autostart
+```
+
+The hint also appears in the entrypoint banner when you start the container.
+
+## Auth isolation guarantee
+
+The orchestrator injects only the active CLI's auth env vars into the sandbox container. Concretely:
+
+- `SUBAGENT_CLI=claude` → only `ANTHROPIC_AUTH_TOKEN` and `ANTHROPIC_BASE_URL` reach the sandbox; `OPENAI_API_KEY` and `OPENROUTER_API_KEY` are stripped even if set on the host.
+- `SUBAGENT_CLI=codex` → only `OPENAI_*` and `AZURE_OPENAI_*` keys reach the sandbox; `ANTHROPIC_AUTH_TOKEN` and `OPENROUTER_API_KEY` are stripped.
+- `SUBAGENT_CLI=opencode` → only `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` reach the sandbox; `ANTHROPIC_AUTH_TOKEN` (the legacy Claude key) is stripped.
+
+This prevents an operator's leftover `OPENAI_API_KEY` (from a previous Codex experiment) from silently routing OpenCode traffic through OpenAI when they meant OpenRouter.
+
+## Advanced configs
+
+The image entrypoint renders **minimal viable** configs only — what works for the common case. For Azure routing, approval modes, MCP federation, custom OpenAI-compat gateways behind nginx, opencode personas, and operator-supplied overrides via `OPENCODE_CONFIG_EXTRA` / `CODEX_CONFIG_EXTRA` env hooks, see [`docs/cli-config-templates.md`](cli-config-templates.md).
+
+## Troubleshooting
+
+- **Banner shows the wrong CLI** — `SUBAGENT_CLI` is read once at orchestrator boot, not per-request. Restart: `docker compose restart computer-use-server`.
+- **`SUBAGENT_CLI=cline` (typo) → orchestrator refuses to start** — this is intentional. Fix the typo; check `docker compose logs computer-use-server` for the FATAL line listing the three accepted values.
+- **OpenCode falls back to a default provider** — verify `/tmp/opencode.json` exists in the sandbox; if not, the container needs `--force-recreate` to re-render it via the entrypoint heredoc.
+- **Cost reads `$0.0000` for codex/opencode** — this is a bug; the expected display is `cost: unavailable`. File an issue with the result blob attached.
+- **Sub-agent for codex/opencode runs forever** — `max_turns` is Claude-only; the backstop for the other two is `SUB_AGENT_TIMEOUT` (default 3600s). Lower it in `.env` if you need a tighter cap: `SUB_AGENT_TIMEOUT=1800`.
+
+## Prior art
+
+- [OpenAI Codex CLI documentation](https://developers.openai.com/codex/cli/reference) — `codex exec` flags, JSONL event schema
+- [sst/opencode documentation](https://opencode.ai/docs/) — `opencode run`, `{env:VAR}` config substitution, providers list
+- [OpenRouter qwen3-coder model page](https://openrouter.ai/qwen/qwen3-coder)
+- Issue #40 / PR #41 — community discussion that informed Phase 3 (Claude Code gateway compatibility), the foundation this milestone builds on.