@mseep/open-computer-use 1.0.0

package/docs/COMPARISON.md

@@ -0,0 +1,128 @@
+# Comparison: Open Computer Use vs open-webui/open-terminal
+
+Both projects are self-hosted and give LLMs a place to run code. They solve the same core problem with two fundamentally different architectural approaches — both for the technical stack and for the AI/user interaction model. This is not a "which is better" document; it's a map of trade-offs to help you pick the right tool for your use case.
+
+> **Note:** We respect the open-terminal team and their work. If you spot any inaccuracies in this comparison, please [open an issue](https://github.com/Wide-Moat/open-computer-use/issues) — we want this to be fair and factual.
+
+Claude.ai and OpenAI Operator are cloud-only, not self-hosted — we drew inspiration from them, but a detailed comparison isn't useful here. See the overview table for a quick reference.
+
+## Overview
+
+| Feature | Open Computer Use | [open-terminal](https://github.com/open-webui/open-terminal) | Claude.ai | OpenAI Operator |
+|---------|-------------------|---------------|-----------|-----------------|
+| **Self-hosted** | Yes | Yes | No | No |
+| **Managed SaaS option** | Yes — [yambr.com](https://yambr.com) (free demo at [chat.yambr.com](https://chat.yambr.com), hosted MCP at `api.yambr.com/mcp/computer_use`) | No | Yes (claude.ai) | Yes (operator) |
+| **Any LLM** | Yes (OpenAI-compatible) | Any (via Open WebUI) | Claude only | GPT only |
+| **Code execution** | Full Linux sandbox | Sandbox / bare metal | Sandbox | No |
+| **Live browser** | CDP streaming (shared, interactive) | No | Screenshot-based | Screenshot-based |
+| **Terminal** | ttyd + tmux (persistent, side panel) | PTY + WebSocket | IDE + terminal | N/A |
+| **Sub-agent** | Claude Code CLI, interactive TTY + MCP | N/A | Built-in | N/A |
+| **Skills system** | 13 built-in (auto-injected) + custom | Open WebUI native (text-only) | Custom instructions | N/A |
+| **Document creation** | PPTX, DOCX, XLSX, PDF via skills | No | Via code | N/A |
+| **File preview** | Server-side rendering (DOCX, PDF, PPTX, XLSX, code) | Client-side (via Open WebUI) | IDE | N/A |
+| **Container isolation** | Docker (runc), per chat | Shared container (OS-level users) | Docker (gVisor) | N/A |
+| **MCP server** | Streamable HTTP | FastMCP (stdio + streamable-http) | N/A | N/A |
+| **Image size** | ~11 GB (full stack) | ~2 GB / ~200 MB / ~100 MB | N/A | N/A |
+| **Setup complexity** | Docker Compose + reverse proxy + env config | Single `docker run` or `pip install` | N/A | N/A |
+| **Jupyter notebooks** | No | Yes (per-session kernels via nbclient) | No | No |
+| **Bare metal** | No (Docker required) | Yes (`pip install open-terminal`) | No | No |
+| **Port proxy** | No | Yes (HTTP reverse-proxy to localhost services) | No | No |
+| **Ecosystem** | Multi-client MCP server (Open WebUI, n8n, OpenAI Agents SDK, LiteLLM) | Native Open WebUI integration + enterprise orchestrator ([Terminals](https://github.com/open-webui/terminals)) | N/A | N/A |
+
+---
+
+## Architecture and Isolation
+
+**Open Computer Use** creates a new Docker container for every chat session. If the AI breaks something (installs wrong packages, corrupts files, fills disk), only that chat is affected. Next chat starts fresh. Containers are cleaned up automatically after idle timeout. Resource limits (2 GB RAM, 1 CPU) are enforced per container.
+
+**open-terminal** runs a single container (or bare metal process) shared across sessions. Multi-user mode creates OS-level user accounts with isolated home directories (`chmod 2770` + group membership), file ownership enforcement via `sudo chown`, and path validation to prevent cross-user access. For container-per-user isolation, the separate [Terminals](https://github.com/open-webui/terminals) project manages dedicated open-terminal containers per user.
+
+**Why this matters:** Non-technical users + AI agent executing arbitrary code is the worst case for a shared environment. The user doesn't control what the agent does, and the agent can do anything — install packages, fill disk, corrupt files, spawn processes. Container-per-chat means each session is disposable: if something breaks, only that chat is affected, and the next one starts clean.
+
+**Trade-off:** Each container has a 2 GB RAM limit (configurable via `CONTAINER_MEM_LIMIT`). This is a ceiling, not an allocation — an idle container or one running simple commands uses very little memory. Heavy tasks like Chromium or LibreOffice consume more, up to the limit. open-terminal is lighter but shares kernel, network, and system resources between users. open-terminal's own documentation [notes](https://github.com/open-webui/open-terminal#built-in-multi-user-isolation) that single-container multi-user mode is not designed for production multi-user deployments.
+
+---
+
+## MCP Tools
+
+The two projects take opposite approaches to tool design.
+
+**Open Computer Use** exposes 5 high-level tools:
+
+| Tool | Description |
+|------|-------------|
+| `bash_tool` | Run commands with real-time progress streaming, 15s heartbeats, 30K char output cap, timeout handling |
+| `view` | Read files/directories with line numbers, auto-resize images to base64, detect binary formats |
+| `create_file` | Create files with auto-parent-directory creation |
+| `str_replace` | Edit files via find-and-replace with uniqueness validation |
+| `sub_agent` | Delegate to Claude Code with model selection, session resume, MCP auto-config, cost tracking |
+
+**open-terminal** exposes 15 core MCP tools via FastMCP (+ 4 notebook tools when enabled):
+
+| Category | Tools |
+|----------|-------|
+| Files | list, read, write, display, replace, upload, grep, glob |
+| Processes | execute, list, status, input, kill |
+| Notebooks | create session, execute cell, get session, delete session |
+
+**Trade-off:** Fewer powerful primitives (the AI uses `bash_tool` for search, process management, and anything else) vs. fine-grained operations that don't require shell knowledge.
+
+---
+
+## Security
+
+| Aspect | Open Computer Use | open-terminal |
+|--------|-------------------|---------------|
+| **Isolation** | Docker containers (kernel namespaces) | OS user accounts (chmod 2770 + group membership) |
+| **Privilege escalation** | Non-root user with passwordless sudo; `no-new-privileges` flag | Non-root user with passwordless sudo (full image); no sudo in slim/alpine |
+| **Resource limits** | Per-container (2 GB RAM, 1 CPU default) | OS-level only |
+| **Egress firewall** | Configurable (Docker network policies) | Built-in DNS whitelist (dnsmasq + iptables + ipset), CAP_NET_ADMIN dropped after setup |
+| **API key auth** | Bearer token (MCP_API_KEY) | Bearer token, constant-time comparison (hmac.compare_digest) |
+| **Path traversal** | Sanitized chat_id + safe_path validation | resolve_path + is_path_allowed validation |
+| **Skill/upload mounts** | Read-only | N/A |
+
+---
+
+## What Open Computer Use offers that open-terminal doesn't
+
+- **Document creation skills** — 13 built-in skills with scripts and templates for generating professional documents:
+  - **PPTX**: HTML/CSS → PowerPoint via custom `html2pptx` library, or template-based editing with `inventory.py` (extract shapes), `replace.py` (smart text replacement), `thumbnail.py` (visual validation)
+  - **DOCX**: create from scratch with `docx-js`, or edit existing with tracked changes (OOXML redlining via `<w:ins>`/`<w:del>` tags)
+  - **XLSX**: formula-based spreadsheets with `openpyxl`, automatic recalculation via LibreOffice UNO (`recalc.py`), error scanning (#REF!, #DIV/0!)
+  - **PDF**: create with ReportLab (pre-registered Cyrillic/Emoji fonts), extract tables with tabula-py/camelot, fill forms, merge/split
+- **Skill auto-injection** — skills with scripts, templates, and examples are mounted read-only into containers and injected into the system prompt. The AI gets structured instructions, not just text. Per-user custom skills via Settings Wrapper API.
+- **Live shared browser** — Playwright + CDP streaming: AI automates via CDP, user watches and interacts in real-time (clicks, types passwords, scrolls) in the same Chromium instance. Not screenshot-based.
+- **Claude Code sub-agent** — delegate complex multi-step tasks to Claude Code running autonomously inside the container. Supports model selection (sonnet/opus), session resume after timeout, cost/turns tracking, and auto-configured MCP servers.
+- **Server-side file preview** — preview panel renders DOCX (via Mammoth), XLSX (multi-sheet tables), PDF (page-by-page canvas), PPTX (slide navigation), Markdown, images, and code with syntax highlighting. Works from any MCP client, not tied to Open WebUI's UI.
+- **Container-per-chat isolation** — every chat gets a fresh Docker container with its own filesystem, network, and resource limits. Containers auto-cleanup after idle timeout. No cross-session contamination.
+- **Persistent terminal** — ttyd + tmux: terminal sessions survive disconnects, user can switch between chat and terminal freely, or leave the chat interface entirely and work in the container via direct URL.
+- **Pre-installed stack** — ~180 packages: LibreOffice suite, Playwright + Chromium, OCR (Tesseract), computer vision (OpenCV), image processing (ImageMagick, Pillow, sharp), GitLab CLI (glab), fonts (DejaVu, Noto CJK/Emoji for PDF/reports), ML libraries (JAX, ONNX Runtime, MediaPipe). Image size is ~11 GB vs open-terminal's ~2 GB / ~200 MB / ~100 MB.
+- **Vision AI** — `describe-image` skill for multi-modal image analysis (charts, diagrams, screenshots) via Vision API.
+- **Multi-client MCP support** — tested with Open WebUI, n8n, OpenAI Agents SDK, and LiteLLM. open-terminal also supports multiple transports (stdio + streamable-http via FastMCP) but is primarily tested with Open WebUI.
+- **Container resurrection** — if a container is removed (e.g. by cron), saved metadata allows recreating it with the same volumes, environment, and MCP config.
+- **Smart tool output** — bash_tool streams progress with 15s heartbeats, caps output at 30K chars (first/last 15K), handles semantic exit codes (grep returning 1 is "no match", not error).
+
+## What open-terminal offers that we don't
+
+- **Jupyter notebooks** — per-session kernels via nbclient, create and execute notebooks through the API
+- **Bare metal mode** — `pip install open-terminal`, no Docker needed
+- **Port proxy** — HTTP reverse-proxy to localhost services for web development
+- **Lightweight image variants** — slim (~200 MB, Debian) and alpine (~100 MB) for minimal footprint
+- **Document text extraction as API** — dedicated endpoint reads 11 formats as plain text (PDF, DOCX, PPTX, XLSX, XLS, RTF, ODT, ODS, ODP, EPUB, EML)
+- **Process stdin** — send input to running processes (interactive CLI tools)
+- **Session CWD tracking** — per-session working directory for the API, since open-terminal is stateless between requests
+- **Runtime package installation via env vars** — `OPEN_TERMINAL_PACKAGES="cowsay"` installs apt/pip/npm packages at container startup without rebuilding the image
+- **Docker-in-Docker** — Docker CLI + Compose + Buildx pre-installed, mount the socket for full DinD
+- **TOML config files** — configure via `~/.config/open-terminal/config.toml` or `/etc/open-terminal/config.toml`
+- **Log management** — per-process JSONL logs with configurable retention (7 days default) and flush tuning
+- **Simpler setup** — single `docker run` command
+
+---
+
+## When to choose what
+
+**Choose Open Computer Use** for workflows that need browser automation, document creation, or Claude Code sub-agent. Container-per-chat isolation gives each session its own filesystem, network, and resource limits. Works across MCP clients (Open WebUI, n8n, OpenAI Agents SDK, LiteLLM).
+
+**Choose open-terminal** for terminal-first workflows, especially in Open WebUI environments. Native integration with the Open WebUI ecosystem, minimal setup (single `docker run` or `pip install`), Jupyter notebooks, port proxying, and image variants from ~100 MB to ~2 GB. For multi-user deployments, the [Terminals](https://github.com/open-webui/terminals) project provides enterprise-grade container orchestration.
+
+**Use both together:** Open WebUI supports connecting to both simultaneously — choose per task based on what each does best.

package/docs/DOCKER.md

@@ -0,0 +1,469 @@
+# Docker Architecture
+
+Technical documentation for the AI Computer Use Docker environment.
+
+## Architecture Overview
+
+![Sandbox Contents](sandbox-contents.svg)
+
+See also: [architecture.svg](architecture.svg) for the full system diagram.
+
+**Volume Mounts:**
+- `uploads` → `/mnt/user-data/uploads` (read-only)
+- `outputs` → `/mnt/user-data/outputs` (read-write, served via HTTP)
+- `skills` → `/mnt/skills` (read-only)
+- `workspace` → `/home/assistant` (read-write, per-chat Docker volume)
+
+## Dockerfile Structure
+
+### Multi-Stage Build
+
+The Dockerfile uses a multi-stage build approach for optimal layer caching:
+
+1. **base**: Environment variables
+2. **system-packages**: APT packages installation
+3. **python-deps**: Python packages
+4. **node-deps**: Node.js packages
+5. **playwright-setup**: Playwright browsers
+6. **final**: Directory structure and permissions
+
+### Benefits
+- Faster rebuilds (cached layers)
+- Smaller final image (no build artifacts)
+- Better organization
+
+## Components
+
+### Python Environment
+
+**Version**: 3.12.3
+
+**Key Packages** (107 total):
+- Document: python-docx 1.2.0, python-pptx 1.0.2, openpyxl 3.1.5
+- PDF: pypdf 5.9.0, pdfplumber 0.11.7, reportlab 4.4.10
+- Image: Pillow 11.3.0, opencv-python 4.11.0
+- Data: pandas 2.3.3, numpy 2.3.3
+- Web: playwright 1.57.0, requests 2.32.5
+
+### Node.js Environment
+
+**Version**: 22.20.0
+
+**Key Packages** (21 total):
+- React 19.2.0 + react-dom
+- TypeScript 5.9.3
+- pdf-lib 1.17.1
+- mermaid-cli 11.12.0
+- marked 16.4.0
+
+### System Packages
+
+**Total**: 108 APT packages
+
+**Categories**:
+- Build tools: gcc 13, g++ 13, make
+- Java: OpenJDK 21
+- LibreOffice: writer, calc, impress
+- Media: ffmpeg, imagemagick
+- OCR: tesseract-ocr (EN, RU)
+- Fonts: 20+ font packages
+
+## Mount Points
+
+### 1. User Data Uploads (Read-Only)
+
+```
+Host: ./data/uploads
+Container: /mnt/user-data/uploads
+Mode: ro (read-only)
+```
+
+**Purpose**: Input files for processing
+**Usage**: Place files here from host, read from container
+
+### 2. User Data Outputs (Read-Write)
+
+```
+Host: ./data/outputs
+Container: /mnt/user-data/outputs
+Mode: rw (read-write)
+```
+
+**Purpose**: Generated files and results
+**Usage**: Write from container, read from host
+
+### 3. Skills System (Read-Only)
+
+```
+Host: ./skills
+Container: /mnt/skills
+Mode: ro (read-only)
+```
+
+**Purpose**: Skills system files
+**Structure**:
+- /mnt/skills/public/ - Core skills
+- /mnt/skills/examples/ - Example implementations
+
+### 4. Workspace (Ephemeral)
+
+```
+Volume: ai-workspace
+Container: /home/assistant
+Mode: rw (read-write)
+```
+
+**Purpose**: Temporary working directory
+**Lifecycle**: Data cleared when volume is removed
+**Usage**: Temporary files, intermediate processing
+
+## Resource Management
+
+### CPU Limits
+
+```yaml
+limits:
+  cpus: '4.0'        # Maximum 4 cores
+reservations:
+  cpus: '2.0'        # Reserved 2 cores
+```
+
+### Memory Limits
+
+```yaml
+limits:
+  memory: 8G         # Maximum 8GB
+reservations:
+  memory: 4G         # Reserved 4GB
+```
+
+### Disk Usage
+
+- **Base Image**: ~1GB (Ubuntu 24.04)
+- **Python Packages**: ~5GB
+- **Node Packages**: ~500MB
+- **Playwright Browsers**: ~500MB (Chromium only)
+- **System Packages**: ~3GB
+- **Total**: ~15-20GB
+
+## Networking
+
+### Default Configuration
+
+```yaml
+network_mode: bridge
+ports:
+  - "8000:8000"      # HTTP server (optional)
+```
+
+### DNS Configuration
+
+Default: Uses Docker bridge network DNS
+
+Custom DNS (if needed):
+```yaml
+dns:
+  - 8.8.8.8
+  - 8.8.4.4
+```
+
+## Security
+
+### Enabled Features
+
+1. **no-new-privileges**: Prevents privilege escalation
+2. **Read-only mounts**: Skills and uploads are read-only
+3. **Network isolation**: Bridge network mode
+4. **Resource limits**: CPU and memory constraints (configurable, see examples above)
+5. **Standard Docker runtime (runc)**: Containers share the host kernel. For stronger isolation, consider [gVisor (runsc)](https://gvisor.dev/) which intercepts syscalls in userspace — this is what Claude.ai uses. gVisor support is on the roadmap. On Kubernetes, the [Helm chart](kubernetes.md) already supports hypervisor-grade isolation today via [Kata Containers](kata-runtime.md).
+
+### Optional Hardening
+
+```yaml
+# Read-only root filesystem
+read_only: true
+tmpfs:
+  - /tmp:rw,noexec,nosuid
+  - /home/assistant:rw,noexec,nosuid
+
+# Drop all capabilities
+cap_drop:
+  - ALL
+```
+
+## Health Checks
+
+### Docker Compose
+
+```yaml
+healthcheck:
+  test: ["CMD", "python3", "-c", "import sys; sys.exit(0)"]
+  interval: 30s
+  timeout: 10s
+  start_period: 10s
+  retries: 3
+```
+
+### Manual Health Check
+
+```bash
+docker exec ai-computer-use python3 -c "import sys; sys.exit(0)"
+echo $?  # Should output 0
+```
+
+## Environment Variables
+
+### Python
+- `PYTHONUNBUFFERED=1`: Unbuffered output
+- `PIP_BREAK_SYSTEM_PACKAGES=1`: Allow system-wide pip installs
+- `PYTHONDONTWRITEBYTECODE=1`: No .pyc files
+
+### Node.js
+- `NODE_PATH=/usr/local/lib/node_modules_global`
+- `NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt`
+
+### Java
+- `JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64`
+
+### Playwright
+- `PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers`
+
+### SSL/TLS
+- `REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt`
+- `SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt`
+
+## Performance Optimization
+
+### Build Optimization
+
+1. **Layer Caching**: Install packages in order of change frequency
+2. **Multi-stage**: Separate build stages for better caching
+3. **Cleanup**: Remove package caches after installation
+
+### Runtime Optimization
+
+1. **Volume Mounts**: Fast I/O for data directories
+2. **Resource Limits**: Prevent resource exhaustion
+3. **Ephemeral Workspace**: Named volume for fast disk access
+
+## Troubleshooting
+
+### Check Container Status
+
+```bash
+docker-compose ps
+docker stats ai-computer-use
+```
+
+### View Resource Usage
+
+```bash
+docker stats ai-computer-use --no-stream
+```
+
+### Inspect Container
+
+```bash
+docker inspect ai-computer-use
+```
+
+### Access Logs
+
+```bash
+docker-compose logs
+docker-compose logs -f --tail=100
+```
+
+### Execute Commands
+
+```bash
+# One-off command
+docker-compose exec ai-computer-use python3 --version
+
+# Interactive shell
+docker-compose exec ai-computer-use /bin/bash
+```
+
+## Maintenance
+
+### Update Image
+
+```bash
+docker-compose build --no-cache
+docker-compose up -d
+```
+
+### Clean Up
+
+```bash
+# Remove stopped containers
+docker-compose down
+
+# Remove volumes
+docker-compose down -v
+
+# Remove images
+docker rmi ai-computer-use
+```
+
+### Backup Data
+
+```bash
+# Backup outputs
+tar -czf outputs_backup.tar.gz data/outputs/
+
+# Backup skills (if customized)
+tar -czf skills_backup.tar.gz skills/
+```
+
+## Advanced Configuration
+
+### Custom Base Image
+
+Edit Dockerfile:
+```dockerfile
+FROM ubuntu:24.04  # Change to different base
+```
+
+### Additional Packages
+
+Add to `apt-packages.txt`:
+```
+package-name
+another-package
+```
+
+### Python Packages
+
+Add to `requirements.txt`:
+```
+package-name==version
+```
+
+### Node Packages
+
+Add to `package.json`:
+```json
+{
+  "dependencies": {
+    "package-name": "^version"
+  }
+}
+```
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+```yaml
+name: Build Docker Image
+on: [push]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Build image
+        run: docker-compose build
+      - name: Test image
+        run: |
+          docker-compose up -d
+          docker-compose exec -T ai-computer-use python3 --version
+```
+
+## LiteLLM Integration (Optional)
+
+When using Computer Use via LiteLLM proxy, headers are passed through the `extra_headers` mechanism.
+
+### Supported Headers
+
+| Parameter | Direct Header | OpenWebUI Format | Required |
+|----------|------------------|------------------|--------------|
+| Chat ID | `X-Chat-Id` | `X-OpenWebUI-Chat-Id` | Yes |
+| User Email | `X-User-Email` | `X-OpenWebUI-User-Email` | No |
+| User Name | `X-User-Name` | `X-OpenWebUI-User-Name` | No |
+| GitLab Token | `X-Gitlab-Token` | `X-OpenWebUI-Gitlab-Token` | No |
+| GitLab Host | `X-Gitlab-Host` | `X-OpenWebUI-Gitlab-Host` | No |
+| Anthropic API Key | `X-Anthropic-Api-Key` | `X-OpenWebUI-Anthropic-Api-Key` | No |
+| Anthropic Base URL | `X-Anthropic-Base-Url` | `X-OpenWebUI-Anthropic-Base-Url` | No |
+
+### LiteLLM Configuration
+
+Add MCP server to your LiteLLM `config.yaml`:
+
+```yaml
+mcp_servers:
+  docker_ai:
+    url: "http://localhost:8081/mcp"
+    transport: "http"
+    auth_type: "bearer_token"
+    auth_value: "<MCP_API_KEY>"
+    extra_headers:
+      # OpenWebUI headers
+      - "x-openwebui-chat-id"
+      - "x-openwebui-user-email"
+      - "x-openwebui-user-name"
+      - "x-openwebui-gitlab-token"
+      - "x-openwebui-gitlab-host"
+      - "x-openwebui-anthropic-api-key"
+      - "x-openwebui-anthropic-base-url"
+      # Direct headers
+      - "x-chat-id"
+      - "x-user-email"
+      - "x-user-name"
+      - "x-gitlab-token"
+      - "x-gitlab-host"
+      - "x-anthropic-api-key"
+      - "x-anthropic-base-url"
+    allowed_tools:
+      - "bash_tool"
+      - "str_replace"
+      - "create_file"
+      - "view"
+      - "sub_agent"
+```
+
+### How It Works
+
+1. Client (OpenWebUI) adds `X-OpenWebUI-*` headers to requests
+2. LiteLLM forwards them to MCP server (if specified in `extra_headers`)
+3. `mcp_tools.py` reads headers via `set_context_from_headers()`
+4. Priority: direct headers (`X-Chat-Id`) > OpenWebUI headers (`X-OpenWebUI-Chat-Id`)
+
+### Example LiteLLM API Request
+
+```bash
+curl -X POST http://localhost:4000/v1/chat/completions \
+  -H "Authorization: Bearer <API_KEY>" \
+  -H "X-OpenWebUI-Chat-Id: my-chat-123" \
+  -H "X-OpenWebUI-User-Email: user@example.com" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "claude/claude-sonnet-4-5",
+    "messages": [{"role": "user", "content": "Run ls -la"}],
+    "tools": [{"type": "mcp", "server_label": "docker_ai"}]
+  }'
+```
+
+### Direct MCP Server Access
+
+```bash
+# List tools
+curl -s http://localhost:8081/mcp -X POST \
+  -H "Authorization: Bearer <MCP_API_KEY>" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+
+# Execute command
+curl -s http://localhost:8081/mcp -X POST \
+  -H "Authorization: Bearer <MCP_API_KEY>" \
+  -H "X-Chat-Id: test-123" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"bash_tool","arguments":{"command":"echo Hello","description":"test"}}}'
+```
+
+## References
+
+- [Dockerfile Best Practices](https://docs.docker.com/develop/dev-best-practices/)
+- [Docker Compose Documentation](https://docs.docker.com/compose/)
+- [Ubuntu 24.04 Release Notes](https://releases.ubuntu.com/24.04/)

package/docs/DYNAMIC-SKILLS.md

@@ -0,0 +1,77 @@
+# Dynamic Per-User Skill Injection
+
+System that fetches user-enabled skills and injects them into sandbox containers at runtime.
+
+![Dynamic Skills Architecture](dynamic-skills.svg)
+
+## How it works
+
+1. **On chat start**, the server calls `skill_manager.get_user_skills(email)`
+2. **Skill list** is fetched with 3-level fallback: memory cache (60s TTL) → Settings Wrapper API → disk cache → hardcoded defaults
+3. **System prompt** gets `<available_skills>` XML block with skill names, descriptions, and paths
+4. **User-uploaded skills** are downloaded as ZIP, cached locally, and bind-mounted into the container
+
+Without Settings Wrapper, all 13 public skills are always enabled for everyone.
+
+## Skill Categories
+
+| Category | Storage | Mount Point | Source |
+|----------|---------|-------------|--------|
+| `public` | Baked in Docker image | `/mnt/skills/public/{name}/` | `skills/public/` |
+| `example` | Baked in Docker image | `/mnt/skills/examples/{name}/` | `skills/examples/` |
+| `user` | Host cache `/data/skills-cache/` | `/mnt/skills/user/{name}/` | ZIP from Settings Wrapper |
+
+## Core Functions (skill_manager.py)
+
+| Function | Purpose |
+|----------|---------|
+| `get_user_skills(email)` | Fetch enabled skills (async, 3-level fallback) |
+| `get_user_skills_sync(email)` | Sync version (reads cache only, for Docker thread) |
+| `ensure_skill_cached(skill)` | Download + extract user-uploaded ZIP |
+| `build_available_skills_xml(skills)` | `<available_skills>` XML for system prompt |
+| `build_sub_agent_skills_text(skills)` | Skill list for sub-agent prompt |
+| `get_skill_mounts(skills)` | Docker volume mounts dict for user skills |
+
+## API Endpoints
+
+| Endpoint | Purpose |
+|----------|---------|
+| `GET /system-prompt?user_email=X&chat_id=Y` | Dynamic system prompt with user's skills |
+| `GET /skill-mounts?user_email=X` | Docker volume mounts for user skills |
+| `GET /skill-list?user_email=X` | Skills list for sub-agent prompt |
+
+## ZIP Cache
+
+- **Location**: `/data/skills-cache/{skill-name}/`
+- **Manifest**: `.manifest.json` (name → SHA-256 + timestamp)
+- **Atomic extraction**: unzip to temp dir → rename to final path
+- **Stale cache reuse**: if API/download fails but old cache exists, use it
+- **Host path**: Docker daemon needs host paths for bind mounts — configured via `SKILLS_CACHE_HOST_PATH`
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MCP_TOKENS_URL` | _(empty)_ | Settings Wrapper URL |
+| `MCP_TOKENS_API_KEY` | _(empty)_ | Internal API key |
+| `SKILLS_CACHE_DIR` | `/data/skills-cache` | Container-internal cache path |
+| `SKILLS_CACHE_HOST_PATH` | `/tmp/skills-cache` | Host path for Docker mounts |
+
+## Verification
+
+```bash
+# Check system prompt (should list skills)
+curl "http://localhost:8081/system-prompt?user_email=admin@open-computer-use.dev&chat_id=test" | head -50
+
+# Check skill mounts
+curl "http://localhost:8081/skill-mounts?user_email=admin@open-computer-use.dev"
+
+# Check skill list
+curl "http://localhost:8081/skill-list?user_email=admin@open-computer-use.dev"
+```
+
+## Related Docs
+
+- [SKILLS.md](SKILLS.md) — reference for all built-in skills
+- [SKILLS-USER-GUIDE.md](SKILLS-USER-GUIDE.md) — user guide for skills
+- [settings-wrapper/README.md](../settings-wrapper/README.md) — mock skill registry API