@kokorolx/ai-sandbox-wrapper 2.3.0-beta → 2.6.0

package/README.md

@@ -4,9 +4,36 @@
 
 Protect your SSH keys, API tokens, and system files while using AI tools that need filesystem access.
 
-*Last updated: February 6, 2026*
+*Last updated: February 9, 2026*
 
-## ✨ New in v2.3.0-beta: Web Mode & Port Exposure
+---
+
+## 📑 Table of Contents
+
+- [What's New](#-whats-new)
+- [Why Use This?](#️-why-use-this)
+- [Quick Start](#-quick-start)
+- [Configuration](#️-configuration)
+  - [API Keys](#api-keys)
+  - [Workspaces](#workspaces)
+  - [Port Exposure](#port-exposure)
+  - [Server Authentication](#server-authentication)
+  - [Network Access](#network-access)
+  - [Git Access](#git-access)
+  - [Clipboard](#clipboard)
+- [Directory Structure](#-directory-structure)
+- [Security Model](#-security-model)
+- [Quick Reference](#-quick-reference)
+- [Troubleshooting](#-troubleshooting)
+- [Other Tools](#-other-tools)
+- [Contributing](#-contributing)
+- [License](#-license)
+
+---
+
+## ✨ What's New
+
+### v2.3.0-beta: Web Mode & Port Exposure
 
 - **Web Auto-Detection**: `opencode web` automatically exposes port 4096 and injects `--hostname 0.0.0.0`
 - **`--expose` Flag**: New way to expose ports (replaces deprecated `PORT` env var)
@@ -23,6 +50,8 @@ opencode web --port 8080
 opencode --expose 3000,5555 web
 ```
 
+---
+
 ## 🛡️ Why Use This?
 
 | Without Sandbox | With AI Sandbox |
@@ -32,6 +61,8 @@ opencode --expose 3000,5555 web
 | Host environment exposed | ✅ API keys passed explicitly |
 | Runs with your permissions | ✅ Non-root, CAP_DROP=ALL |
 
+---
+
 ## 🚀 Quick Start
 
 **Prerequisites:** Docker Desktop (macOS/Windows) or Docker Engine (Linux)
@@ -49,9 +80,12 @@ opencode
 
 During setup: select **opencode**, choose registry images (faster), whitelist your project directories.
 
+---
+
 ## ⚙️ Configuration
 
 ### API Keys
+
 ```bash
 nano ~/.ai-sandbox/env
 ```
@@ -61,6 +95,7 @@ OPENAI_API_KEY=sk-...
 ```
 
 ### Workspaces
+
 ```bash
 npx @kokorolx/ai-sandbox-wrapper workspace add ~/projects/my-app
 # Or: echo '/path/to/project' >> ~/.ai-sandbox/workspaces
@@ -94,6 +129,30 @@ Output:
 🌐 Web UI available at http://localhost:4096
 ```
 
+### Server Authentication
+
+Control authentication for OpenCode web server:
+
+```bash
+# Set password directly (visible in process list)
+ai-run opencode web --password mysecret
+ai-run opencode web -p mysecret
+
+# Read password from environment variable (more secure)
+MY_PASS=secret ai-run opencode web --password-env MY_PASS
+
+# Explicitly allow unsecured mode (suppresses warning)
+ai-run opencode web --allow-unsecured
+```
+
+**Login credentials:**
+- Username: `opencode` (default, override with `OPENCODE_SERVER_USERNAME` env var)
+- Password: your configured password
+
+**Precedence:** `--password` > `--password-env` > `OPENCODE_SERVER_PASSWORD` env > interactive prompt
+
+Without flags, interactive mode shows a menu; non-interactive mode shows a security warning.
+
 **Port Conflict Detection:**
 ```
 ❌ ERROR: Port 3000 is already in use by node (PID: 12345)
@@ -117,6 +176,65 @@ Git credentials are **not** shared by default. When you run a tool, you'll be pr
   3) No, keep Git disabled (secure default)
 ```
 
+### Clipboard
+
+Clipboard access in containers requires a terminal that supports **OSC52** protocol.
+
+**Supported terminals:** iTerm2, Warp, Kitty, Alacritty, WezTerm, Windows Terminal, Ghostty
+
+**Not supported:** GNOME Terminal, VS Code Terminal, Tilix, Terminator
+
+Test if your terminal supports clipboard:
+```bash
+printf "\033]52;c;$(printf "test" | base64)\a"
+# Press Cmd+V / Ctrl+V - if you see "test", it works
+```
+
+📖 **Full details:** [CLIPBOARD_SUPPORT.md](CLIPBOARD_SUPPORT.md)
+
+### MCP Tools (Browser Automation)
+
+During setup, you can optionally install MCP servers for AI agent browser automation:
+
+| Tool | Maintainer | Features | Size |
+|------|------------|----------|------|
+| **Chrome DevTools MCP** | Google | Performance profiling, Core Web Vitals, detailed console/network inspection | ~400MB |
+| **Playwright MCP** | Microsoft | Multi-browser (Chromium), TypeScript code generation, vision mode | ~300MB |
+
+After installation, configure your MCP client (e.g., OpenCode) to use them:
+
+**`~/.config/opencode/opencode.json`:**
+```json
+{
+  "mcp": {
+    "chrome-devtools": {
+      "type": "local",
+      "command": [
+        "chrome-devtools-mcp",
+        "--headless",
+        "--isolated",
+        "--executablePath", "/opt/chromium",
+        "--chromeArg=--no-sandbox",
+        "--chromeArg=--disable-setuid-sandbox"
+      ]
+    },
+    "playwright": {
+      "type": "local",
+      "command": [
+        "npx", "@playwright/mcp@latest",
+        "--headless",
+        "--browser", "chromium",
+        "--no-sandbox"
+      ]
+    }
+  }
+}
+```
+
+> **Note:** The `--no-sandbox` flags are required when running in Docker containers. This is safe because the container itself provides isolation.
+
+---
+
 ## 📁 Directory Structure
 
 ```
@@ -132,6 +250,8 @@ Native configs are bind-mounted:
 - `~/.config/opencode` ↔ `/home/agent/.config/opencode`
 - `~/.local/share/opencode` ↔ `/home/agent/.local/share/opencode`
 
+---
+
 ## 🔐 Security Model
 
 ```
@@ -153,6 +273,8 @@ Native configs are bind-mounted:
 └─────────────────────────────────────────────────┘
 ```
 
+---
+
 ## 📚 Quick Reference
 
 ```bash
@@ -173,6 +295,8 @@ npx @kokorolx/ai-sandbox-wrapper workspace list
 npx @kokorolx/ai-sandbox-wrapper clean
 ```
 
+---
+
 ## ❓ Troubleshooting
 
 | Issue | Solution |
@@ -181,6 +305,9 @@ npx @kokorolx/ai-sandbox-wrapper clean
 | `Outside whitelisted workspace` | `echo "$(pwd)" >> ~/.ai-sandbox/workspaces` |
 | Port already in use | Stop the process or use different port |
 | Docker not found | Install and start Docker Desktop |
+| Clipboard not working | Use OSC52-compatible terminal. See [CLIPBOARD_SUPPORT.md](CLIPBOARD_SUPPORT.md) |
+
+---
 
 ## 📦 Other Tools
 
@@ -188,10 +315,14 @@ This sandbox also supports **Claude, Gemini, Aider, Kilo, Codex, Amp, Qwen**, an
 
 See [TOOLS.md](TOOLS.md) for the full list and tool-specific configuration.
 
+---
+
 ## 🤝 Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).
 
+---
+
 ## 📝 License
 
 MIT

package/bin/ai-run

@@ -1,14 +1,140 @@
 #!/usr/bin/env bash
 set -e
 
+# Show help if requested
+show_help() {
+  cat << 'EOF'
+Usage: ai-run <tool> [options] [-- tool-args...]
+
+Run AI tools in a secure Docker sandbox.
+
+Options:
+  -s, --shell              Start interactive shell instead of running tool directly
+  -n, --network [name]     Connect to Docker network(s) (comma-separated or interactive)
+  -e, --expose <ports>     Expose container ports (comma-separated, e.g., 3000,5555)
+  -p, --password <value>   Set OpenCode server password (for web/serve mode)
+      --password-env <VAR> Read OpenCode server password from environment variable
+      --allow-unsecured    Allow OpenCode server to run without password (suppresses warning)
+  -h, --help               Show this help message
+      --help-env           Show environment variables reference
+
+OpenCode Server Authentication (web/serve mode only):
+  When running 'opencode web' or 'opencode serve', you can control authentication:
+
+  # Set password directly (visible in process list)
+  ai-run opencode web --password mysecret
+
+  # Read password from environment variable (more secure)
+  MY_PASS=secret ai-run opencode web --password-env MY_PASS
+
+  # Explicitly allow unsecured mode (suppresses warning)
+  ai-run opencode web --allow-unsecured
+
+  Default username: opencode (override with OPENCODE_SERVER_USERNAME env var)
+  Precedence: --password > --password-env > OPENCODE_SERVER_PASSWORD env > interactive prompt
+
+Examples:
+  ai-run claude                           # Run Claude in sandbox
+  ai-run opencode web -e 4096             # Run OpenCode web with port exposed
+  ai-run opencode web -p secret           # Run with password
+  ai-run opencode --shell                 # Start shell, run tool manually
+  ai-run aider -n mynetwork               # Connect to Docker network
+
+Documentation: https://github.com/kokorolx/ai-sandbox-wrapper
+EOF
+  exit 0
+}
+
+show_help_env() {
+  cat << 'EOF'
+Environment Variables Reference
+===============================
+
+Runtime Environment Variables (inline with ai-run):
+---------------------------------------------------
+  AI_IMAGE_SOURCE=registry    Use pre-built images from GitLab registry instead of local
+                              Example: AI_IMAGE_SOURCE=registry ai-run opencode
+
+  AI_RUN_DEBUG=1              Enable debug output (shows Docker command details)
+                              Example: AI_RUN_DEBUG=1 ai-run opencode
+
+  AI_RUN_PLATFORM=linux/amd64 Force specific platform (useful for cross-arch)
+                              Example: AI_RUN_PLATFORM=linux/amd64 ai-run opencode
+
+  PORT_BIND=all               Bind exposed ports to all interfaces (0.0.0.0) instead of localhost
+                              ⚠️  Security risk - use only when needed
+                              Example: PORT_BIND=all ai-run opencode web -e 4096
+
+  PORT=3000,4000              (Deprecated) Expose ports - use --expose flag instead
+                              Example: PORT=3000 ai-run opencode
+
+Build Environment Variables (inline with setup.sh or install scripts):
+----------------------------------------------------------------------
+  DOCKER_NO_CACHE=1           Force rebuild without Docker cache
+                              Example: DOCKER_NO_CACHE=1 bash setup.sh
+
+  OPENCODE_VERSION=1.1.52     Install specific OpenCode version instead of latest
+                              Example: OPENCODE_VERSION=1.1.52 bash lib/install-opencode.sh
+
+  INSTALL_CHROME_DEVTOOLS_MCP=1  Install Chrome DevTools MCP in base image
+  INSTALL_PLAYWRIGHT_MCP=1       Install Playwright MCP in base image
+  INSTALL_PLAYWRIGHT=1           Install Playwright browser automation
+  INSTALL_RUBY=1                 Install Ruby 3.3.0 + Rails 8.0.2
+  INSTALL_SPEC_KIT=1             Install spec-kit (specify CLI)
+  INSTALL_UX_UI_PROMAX=1         Install uipro CLI
+  INSTALL_OPENSPEC=1             Install OpenSpec CLI
+
+Container Environment Variables (passed to container via ~/.ai-sandbox/env):
+-----------------------------------------------------------------------------
+  ANTHROPIC_API_KEY           Anthropic API key for Claude
+  OPENAI_API_KEY              OpenAI API key
+  OPENCODE_SERVER_PASSWORD    Password for OpenCode web server
+  OPENCODE_SERVER_USERNAME    Username for OpenCode web server (default: opencode)
+  GITHUB_TOKEN                GitHub token for gh CLI authentication
+  GH_TOKEN                    Alternative GitHub token variable
+
+Configuration Files:
+--------------------
+  ~/.ai-sandbox/config.json   Main configuration (workspaces, git, networks, MCP)
+  ~/.ai-sandbox/env           API keys and secrets (KEY=value format)
+  ~/.ai-sandbox/workspaces    Legacy workspace list (one path per line)
+
+Examples:
+  # Debug mode with registry images
+  AI_RUN_DEBUG=1 AI_IMAGE_SOURCE=registry ai-run opencode
+
+  # Rebuild everything from scratch
+  DOCKER_NO_CACHE=1 bash setup.sh --no-cache
+
+  # Install specific OpenCode version
+  OPENCODE_VERSION=1.1.52 bash lib/install-opencode.sh
+
+  # Expose port to network (not just localhost)
+  PORT_BIND=all ai-run opencode web -e 4096
+EOF
+  exit 0
+}
+
+# Check for help flag before anything else
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  show_help
+fi
+
+if [[ "${1:-}" == "--help-env" ]]; then
+  show_help_env
+fi
+
 TOOL="$1"
-shift
+shift 2>/dev/null || { echo "❌ ERROR: No tool specified. Use 'ai-run --help' for usage."; exit 1; }
 
 # Parse flags
 SHELL_MODE=false
 NETWORK_FLAG=false
 NETWORK_ARG=""
 EXPOSE_ARG=""
+SERVER_PASSWORD=""
+PASSWORD_ENV_VAR=""
+ALLOW_UNSECURED=false
 TOOL_ARGS=()
 
 while [[ $# -gt 0 ]]; do
@@ -33,6 +159,24 @@ while [[ $# -gt 0 ]]; do
         shift
       fi
       ;;
+    --password|-p)
+      shift
+      if [[ $# -gt 0 && ! "$1" =~ ^- ]]; then
+        SERVER_PASSWORD="$1"
+        shift
+      fi
+      ;;
+    --password-env)
+      shift
+      if [[ $# -gt 0 && ! "$1" =~ ^- ]]; then
+        PASSWORD_ENV_VAR="$1"
+        shift
+      fi
+      ;;
+    --allow-unsecured)
+      ALLOW_UNSECURED=true
+      shift
+      ;;
     *)
       TOOL_ARGS+=("$1")
       shift
@@ -1221,6 +1365,381 @@ if [[ -n "$TTY_FLAGS" ]]; then
   CONTAINER_NAME="--name $(generate_container_name)"
 fi
 
+# ============================================================================
+# OPENCODE SERVER PASSWORD HANDLING
+# ============================================================================
+OPENCODE_PASSWORD_ENV=""
+
+# Detect if running opencode web or serve command
+is_opencode_web_mode() {
+  [[ "$TOOL" == "opencode" ]] || return 1
+  for arg in "${TOOL_ARGS[@]}"; do
+    [[ "$arg" == "web" || "$arg" == "serve" ]] && return 0
+  done
+  return 1
+}
+
+# Resolve password from CLI flags, env vars, or interactive prompt
+# Precedence: --password > --password-env > OPENCODE_SERVER_PASSWORD env > interactive/warning
+resolve_opencode_password() {
+  # 1. CLI --password flag (highest priority)
+  if [[ -n "$SERVER_PASSWORD" ]]; then
+    OPENCODE_PASSWORD_ENV="-e OPENCODE_SERVER_PASSWORD=$SERVER_PASSWORD"
+    return 0
+  fi
+
+  # 2. CLI --password-env flag
+  if [[ -n "$PASSWORD_ENV_VAR" ]]; then
+    local env_value="${!PASSWORD_ENV_VAR:-}"
+    if [[ -z "$env_value" ]]; then
+      echo "❌ ERROR: Environment variable '$PASSWORD_ENV_VAR' is not set"
+      exit 1
+    fi
+    OPENCODE_PASSWORD_ENV="-e OPENCODE_SERVER_PASSWORD=$env_value"
+    return 0
+  fi
+
+  # 3. Existing OPENCODE_SERVER_PASSWORD environment variable
+  if [[ -n "${OPENCODE_SERVER_PASSWORD:-}" ]]; then
+    OPENCODE_PASSWORD_ENV="-e OPENCODE_SERVER_PASSWORD=$OPENCODE_SERVER_PASSWORD"
+    return 0
+  fi
+
+  # 4. --allow-unsecured flag: skip prompt/warning, no password
+  if [[ "$ALLOW_UNSECURED" == "true" ]]; then
+    return 0
+  fi
+
+  # 5. Interactive mode: show menu
+  if [[ -t 0 ]]; then
+    echo ""
+    echo "🔐 OpenCode Web Server Security"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "The web server requires a password for security."
+    echo ""
+    echo "  1) Generate random password (recommended)"
+    echo "  2) Enter custom password"
+    echo "  3) No password (⚠️  unsecured - localhost only)"
+    echo ""
+    read -p "Choice [1-3]: " password_choice
+    
+    case "$password_choice" in
+      1)
+        local generated_password=$(openssl rand -base64 24 | tr -d '/+=' | head -c 24)
+        OPENCODE_PASSWORD_ENV="-e OPENCODE_SERVER_PASSWORD=$generated_password"
+        echo ""
+        echo "🔑 Generated password: $generated_password"
+        echo "👤 Username: opencode (default)"
+        echo ""
+        echo "To connect from another terminal:"
+        echo "  OPENCODE_SERVER_PASSWORD='$generated_password' opencode attach http://localhost:4096"
+        ;;
+      2)
+        read -sp "Enter password: " custom_password
+        echo ""
+        if [[ -n "$custom_password" ]]; then
+          OPENCODE_PASSWORD_ENV="-e OPENCODE_SERVER_PASSWORD=$custom_password"
+          echo "✅ Custom password set"
+          echo "👤 Username: opencode (default)"
+          echo ""
+          echo "To connect from another terminal:"
+          echo "  OPENCODE_SERVER_PASSWORD='<your-password>' opencode attach http://localhost:4096"
+        else
+          echo "⚠️  Empty password - server will be unsecured"
+        fi
+        ;;
+      *)
+        echo "⚠️  No password set - server is unsecured"
+        echo "   Only use this for localhost access!"
+        ;;
+    esac
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+  else
+    # 6. Non-interactive: show warning
+    echo ""
+    echo "🔐 OpenCode Web Server Security"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "⚠️  OPENCODE_SERVER_PASSWORD not set - server is unsecured"
+    echo "   Set OPENCODE_SERVER_PASSWORD environment variable for security"
+    echo "   Or use --allow-unsecured to suppress this warning"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+  fi
+}
+
+# Run password resolution if in web/serve mode
+if is_opencode_web_mode; then
+  resolve_opencode_password
+fi
+
+# ============================================================================
+# MCP AUTO-CONFIGURATION FOR OPENCODE
+# ============================================================================
+
+# Check if MCP tool is installed (from config.json, set during setup.sh)
+is_mcp_installed() {
+  local mcp_tool="$1"
+  if has_jq && [[ -f "$AI_SANDBOX_CONFIG" ]]; then
+    jq -e --arg tool "$mcp_tool" '.mcp.installed | index($tool) != null' "$AI_SANDBOX_CONFIG" &>/dev/null
+  else
+    return 1
+  fi
+}
+
+# Check if MCP is already configured in OpenCode config
+is_mcp_configured() {
+  local mcp_name="$1"
+  local config_file="$HOME/.config/opencode/opencode.json"
+  
+  if [[ ! -f "$config_file" ]]; then
+    return 1
+  fi
+  
+  if has_jq; then
+    jq -e --arg name "$mcp_name" '.mcp[$name] // empty' "$config_file" &>/dev/null
+  else
+    grep -q "\"$mcp_name\"" "$config_file" 2>/dev/null
+  fi
+}
+
+# Add MCP configuration to OpenCode config
+add_mcp_config() {
+  local mcp_name="$1"
+  local mcp_command="$2"
+  local force="${3:-false}"
+  local config_file="$HOME/.config/opencode/opencode.json"
+  
+  # Check if already configured and warn user
+  if [[ "$force" != "true" ]] && is_mcp_configured "$mcp_name"; then
+    echo ""
+    echo "  ⚠️  WARNING: '$mcp_name' is already configured!"
+    echo "     Reconfiguring will overwrite your existing settings."
+    echo "     Any custom credentials or options will be lost."
+    read -p "     Are you sure you want to overwrite? [y/N]: " overwrite_choice
+    if [[ ! "$overwrite_choice" =~ ^[Yy]$ ]]; then
+      echo "     ⏭️  Kept existing configuration"
+      return 1
+    fi
+  fi
+  
+  mkdir -p "$(dirname "$config_file")"
+  
+  if [[ ! -f "$config_file" ]]; then
+    # Create new config with MCP
+    echo "{\"mcp\": {\"$mcp_name\": {\"type\": \"local\", \"command\": $mcp_command}}}" > "$config_file"
+  elif has_jq; then
+    # Add MCP to existing config
+    jq --arg name "$mcp_name" --argjson cmd "$mcp_command" \
+      '.mcp = (.mcp // {}) | .mcp[$name] = {"type": "local", "command": $cmd}' \
+      "$config_file" > "$config_file.tmp" && mv "$config_file.tmp" "$config_file"
+  else
+    echo "⚠️  jq not found. Please manually add MCP configuration to $config_file"
+    return 1
+  fi
+  chmod 600 "$config_file"
+}
+
+# Mark MCP as skipped for this workspace (don't ask again)
+mark_mcp_skipped() {
+  local skip_file="$SANDBOX_DIR/.mcp-skip-$WORKSPACE_MD5"
+  date -Iseconds > "$skip_file" 2>/dev/null || date > "$skip_file"
+}
+
+# Check if MCP prompt was skipped for this workspace
+is_mcp_skipped() {
+  local skip_file="$SANDBOX_DIR/.mcp-skip-$WORKSPACE_MD5"
+  [[ -f "$skip_file" ]]
+}
+
+# Configure MCP tools for OpenCode
+configure_opencode_mcp() {
+  # Only run for opencode tool in interactive mode
+  [[ "$TOOL" != "opencode" ]] && return 0
+  [[ ! -t 0 ]] && return 0
+  
+  local config_file="$HOME/.config/opencode/opencode.json"
+  
+  # Generate workspace hash for skip tracking
+  WORKSPACE_MD5=$(echo "$CURRENT_DIR" | md5sum | cut -c1-8)
+  
+  # Check if already skipped for this workspace
+  if is_mcp_skipped; then
+    return 0
+  fi
+  
+  # Detect installed MCP tools (from config.json, set during setup.sh)
+  local chrome_installed=false
+  local playwright_installed=false
+  local chrome_configured=false
+  local playwright_configured=false
+  
+  if is_mcp_installed "chrome-devtools"; then
+    chrome_installed=true
+    is_mcp_configured "chrome-devtools" && chrome_configured=true
+  fi
+  
+  if is_mcp_installed "playwright"; then
+    playwright_installed=true
+    is_mcp_configured "playwright" && playwright_configured=true
+  fi
+  
+  # If no MCP tools installed in image, return
+  if [[ "$chrome_installed" == "false" && "$playwright_installed" == "false" ]]; then
+    return 0
+  fi
+  
+  # If all installed tools are already configured, return silently
+  local all_configured=true
+  [[ "$chrome_installed" == "true" && "$chrome_configured" == "false" ]] && all_configured=false
+  [[ "$playwright_installed" == "true" && "$playwright_configured" == "false" ]] && all_configured=false
+  
+  if [[ "$all_configured" == "true" ]]; then
+    return 0
+  fi
+  
+  # Build lists of configured and unconfigured tools
+  local unconfigured=()
+  local configured=()
+  [[ "$chrome_installed" == "true" && "$chrome_configured" == "false" ]] && unconfigured+=("chrome-devtools")
+  [[ "$chrome_installed" == "true" && "$chrome_configured" == "true" ]] && configured+=("chrome-devtools")
+  [[ "$playwright_installed" == "true" && "$playwright_configured" == "false" ]] && unconfigured+=("playwright")
+  [[ "$playwright_installed" == "true" && "$playwright_configured" == "true" ]] && configured+=("playwright")
+  
+  # Show prompt
+  echo ""
+  echo "🔌 MCP Tools Detected"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  
+  # Show already configured tools
+  if [[ ${#configured[@]} -gt 0 ]]; then
+    echo "Already configured:"
+    for tool in "${configured[@]}"; do
+      case "$tool" in
+        chrome-devtools)
+          echo "  ✓ Chrome DevTools MCP"
+          ;;
+        playwright)
+          echo "  ✓ Playwright MCP"
+          ;;
+      esac
+    done
+    echo ""
+  fi
+  
+  # Show unconfigured tools
+  if [[ ${#unconfigured[@]} -gt 0 ]]; then
+    echo "Not yet configured:"
+    for tool in "${unconfigured[@]}"; do
+      case "$tool" in
+        chrome-devtools)
+          echo "  • Chrome DevTools MCP - browser automation + performance profiling"
+          ;;
+        playwright)
+          echo "  • Playwright MCP - multi-browser automation"
+          ;;
+      esac
+    done
+    echo ""
+  fi
+  
+  echo "Configure MCP tools in OpenCode?"
+  echo "  1) Yes, configure all detected tools"
+  echo "  2) Yes, let me choose which ones"
+  echo "  3) No, skip (I'll configure manually)"
+  echo "  4) No, don't ask again for this workspace"
+  echo ""
+  read -p "Choice [1-4]: " mcp_choice
+  
+  local configured_any=false
+  
+  case "$mcp_choice" in
+    1)
+      # Configure all (both unconfigured and offer to reconfigure configured ones)
+      local all_tools=()
+      [[ "$chrome_installed" == "true" ]] && all_tools+=("chrome-devtools")
+      [[ "$playwright_installed" == "true" ]] && all_tools+=("playwright")
+      
+      for tool in "${all_tools[@]}"; do
+        case "$tool" in
+          chrome-devtools)
+            if add_mcp_config "chrome-devtools" '["chrome-devtools-mcp", "--headless", "--isolated", "--executablePath", "/opt/chromium"]'; then
+              echo "  ✓ Configured Chrome DevTools MCP"
+              configured_any=true
+            fi
+            ;;
+          playwright)
+            if add_mcp_config "playwright" '["npx", "@playwright/mcp@latest", "--headless", "--browser", "chromium"]'; then
+              echo "  ✓ Configured Playwright MCP"
+              configured_any=true
+            fi
+            ;;
+        esac
+      done
+      ;;
+    2)
+      # Let user choose from all installed tools
+      local all_tools=()
+      [[ "$chrome_installed" == "true" ]] && all_tools+=("chrome-devtools")
+      [[ "$playwright_installed" == "true" ]] && all_tools+=("playwright")
+      
+      for tool in "${all_tools[@]}"; do
+        local tool_desc=""
+        local status_hint=""
+        case "$tool" in
+          chrome-devtools)
+            tool_desc="Chrome DevTools MCP (browser automation + DevTools)"
+            is_mcp_configured "chrome-devtools" && status_hint=" [already configured]"
+            ;;
+          playwright)
+            tool_desc="Playwright MCP (multi-browser automation)"
+            is_mcp_configured "playwright" && status_hint=" [already configured]"
+            ;;
+        esac
+        read -p "  Configure $tool_desc$status_hint? [y/N]: " tool_choice
+        if [[ "$tool_choice" =~ ^[Yy]$ ]]; then
+          case "$tool" in
+            chrome-devtools)
+              if add_mcp_config "chrome-devtools" '["chrome-devtools-mcp", "--headless", "--isolated", "--executablePath", "/opt/chromium"]'; then
+                echo "    ✓ Configured"
+                configured_any=true
+              fi
+              ;;
+            playwright)
+              if add_mcp_config "playwright" '["npx", "@playwright/mcp@latest", "--headless", "--browser", "chromium"]'; then
+                echo "    ✓ Configured"
+                configured_any=true
+              fi
+              ;;
+          esac
+        else
+          echo "    ⏭️  Skipped"
+        fi
+      done
+      ;;
+    4)
+      mark_mcp_skipped
+      echo "ℹ️  Won't ask again for this workspace"
+      ;;
+    *)
+      echo "ℹ️  Skipped."
+      ;;
+  esac
+  
+  # Show config file path for easy editing
+  echo ""
+  if [[ "$configured_any" == "true" ]]; then
+    echo "✅ MCP configuration saved!"
+  fi
+  echo "📄 Config file: $config_file"
+  echo "   Edit this file to customize MCP settings or add credentials."
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo ""
+}
+
+# Run MCP configuration check for opencode
+configure_opencode_mcp
+
 # ============================================================================
 # WEB COMMAND DETECTION AND PORT EXPOSURE
 # ============================================================================
@@ -1473,6 +1992,7 @@ docker run $CONTAINER_NAME --rm $TTY_FLAGS \
   $DISPLAY_FLAGS \
   $HOST_ACCESS_ARGS \
   $PORT_MAPPINGS \
+  $OPENCODE_PASSWORD_ENV \
   -v "$HOME_DIR":/home/agent \
   -w "$CURRENT_DIR" \
   --env-file "$ENV_FILE" \

package/dockerfiles/base/Dockerfile

@@ -2,9 +2,9 @@ FROM node:22-bookworm-slim
 
 ARG AGENT_UID=1001
 
-# Install common dependencies
-# Note: python3-venv is needed for many tools, unzip for some installers
-RUN apt-get update && apt-get install -y --no-install-recommends     git     curl     ssh     ca-certificates     jq     python3     python3-pip     python3-venv     python3-dev     python3-setuptools     build-essential     libopenblas-dev     pipx     unzip     xclip     wl-clipboard     && curl -LsSf https://astral.sh/uv/install.sh | UV_INSTALL_DIR=/usr/local/bin sh     && rm -rf /var/lib/apt/lists/*     && pipx ensurepath
+RUN apt-get update && apt-get install -y --no-install-recommends     git     curl     ssh     ca-certificates     jq     python3     python3-pip     python3-venv     python3-dev     python3-setuptools     build-essential     libopenblas-dev     pipx     unzip     xclip     wl-clipboard     ripgrep     && curl -LsSf https://astral.sh/uv/install.sh | UV_INSTALL_DIR=/usr/local/bin sh     && rm -rf /var/lib/apt/lists/*     && pipx ensurepath
+
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg     && chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg     && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null     && apt-get update     && apt-get install -y gh     && rm -rf /var/lib/apt/lists/*
 
 # Install pnpm globally using npm (not bun, for stability)
 RUN npm install -g pnpm
@@ -34,14 +34,80 @@ RUN mkdir -p /usr/local/lib/openspec && \
     ln -sf /usr/local/lib/openspec/node_modules/.bin/openspec /usr/local/bin/openspec && \
     chmod -R 755 /usr/local/lib/openspec && \
     chmod +x /usr/local/bin/openspec
+# Install Playwright system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libglib2.0-0 \
+    libnspr4 \
+    libnss3 \
+    libdbus-1-3 \
+    libatk1.0-0 \
+    libatk-bridge2.0-0 \
+    libcups2 \
+    libxcb1 \
+    libxkbcommon0 \
+    libatspi2.0-0 \
+    libx11-6 \
+    libxcomposite1 \
+    libxdamage1 \
+    libxext6 \
+    libxfixes3 \
+    libxrandr2 \
+    libgbm1 \
+    libcairo2 \
+    libpango-1.0-0 \
+    libasound2 \
+    && rm -rf /var/lib/apt/lists/*
+# Install Playwright and browsers via npm
+RUN npm install -g playwright && npx playwright install
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libglib2.0-0 \
+    libnspr4 \
+    libnss3 \
+    libdbus-1-3 \
+    libatk1.0-0 \
+    libatk-bridge2.0-0 \
+    libcups2 \
+    libxcb1 \
+    libxkbcommon0 \
+    libatspi2.0-0 \
+    libx11-6 \
+    libxcomposite1 \
+    libxdamage1 \
+    libxext6 \
+    libxfixes3 \
+    libxrandr2 \
+    libgbm1 \
+    libdrm2 \
+    libcairo2 \
+    libpango-1.0-0 \
+    libasound2 \
+    fonts-liberation \
+    libappindicator3-1 \
+    libu2f-udev \
+    libvulkan1 \
+    libxshmfence1 \
+    xdg-utils \
+    wget \
+    && rm -rf /var/lib/apt/lists/*
+ENV PLAYWRIGHT_BROWSERS_PATH=/opt/playwright-browsers
+RUN mkdir -p /opt/playwright-browsers && \
+    npm install -g @playwright/mcp@latest && \
+    npx playwright-core install --no-shell chromium && \
+    npx playwright-core install-deps chromium && \
+    chmod -R 777 /opt/playwright-browsers && \
+    ln -sf $(ls -d /opt/playwright-browsers/chromium-*/chrome-linux/chrome | head -1) /opt/chromium
+ENV CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS=1
+RUN npm install -g chrome-devtools-mcp@latest && \
+    touch /opt/.mcp-chrome-devtools-installed
+RUN touch /opt/.mcp-playwright-installed
 
 # Create workspace
 WORKDIR /workspace
 
-# Non-root user for security
 # Non-root user for security (match host UID)
 RUN useradd -m -u ${AGENT_UID} -d /home/agent agent && \
     mkdir -p /home/agent/.cache /home/agent/.npm /home/agent/.opencode /home/agent/.config && \
-    chown -R agent:agent /home/agent/.cache /home/agent/.npm /home/agent/.opencode /home/agent/.config /workspace
+    chown -R agent:agent /home/agent/.cache /home/agent/.npm /home/agent/.opencode /home/agent/.config /workspace && \
+    ([ -d /opt/playwright-browsers ] && chown -R agent:agent /opt/playwright-browsers || true)
 USER agent
 ENV HOME=/home/agent

package/dockerfiles/opencode/Dockerfile

@@ -1,7 +1,6 @@
 FROM ai-base:latest
 
 USER root
-# Install OpenCode using official native installer
 RUN curl -fsSL https://opencode.ai/install | bash && \
     mv /home/agent/.opencode/bin/opencode /usr/local/bin/opencode && \
     rm -rf /home/agent/.opencode

package/lib/install-base.sh

@@ -104,13 +104,72 @@ RUN gem install rails -v 8.0.2 && gem install bundler && rbenv rehash
 '
 fi
 
+# MCP Tools for AI agent browser automation
+# Both tools share Playwright's Chromium (native ARM64/x86_64, avoids Puppeteer arch issues)
+MCP_BROWSER_INSTALLED=false
+
+if [[ "${INSTALL_CHROME_DEVTOOLS_MCP:-0}" -eq 1 ]] || [[ "${INSTALL_PLAYWRIGHT_MCP:-0}" -eq 1 ]]; then
+  MCP_BROWSER_INSTALLED=true
+  echo "📦 Installing shared Chromium browser for MCP tools"
+  ADDITIONAL_TOOLS_INSTALL+='RUN apt-get update && apt-get install -y --no-install-recommends \
+    libglib2.0-0 \
+    libnspr4 \
+    libnss3 \
+    libdbus-1-3 \
+    libatk1.0-0 \
+    libatk-bridge2.0-0 \
+    libcups2 \
+    libxcb1 \
+    libxkbcommon0 \
+    libatspi2.0-0 \
+    libx11-6 \
+    libxcomposite1 \
+    libxdamage1 \
+    libxext6 \
+    libxfixes3 \
+    libxrandr2 \
+    libgbm1 \
+    libdrm2 \
+    libcairo2 \
+    libpango-1.0-0 \
+    libasound2 \
+    fonts-liberation \
+    libappindicator3-1 \
+    libu2f-udev \
+    libvulkan1 \
+    libxshmfence1 \
+    xdg-utils \
+    wget \
+    && rm -rf /var/lib/apt/lists/*
+ENV PLAYWRIGHT_BROWSERS_PATH=/opt/playwright-browsers
+RUN mkdir -p /opt/playwright-browsers && \
+    npm install -g @playwright/mcp@latest && \
+    npx playwright-core install --no-shell chromium && \
+    npx playwright-core install-deps chromium && \
+    chmod -R 777 /opt/playwright-browsers && \
+    ln -sf $(ls -d /opt/playwright-browsers/chromium-*/chrome-linux/chrome | head -1) /opt/chromium
+'
+fi
+
+if [[ "${INSTALL_CHROME_DEVTOOLS_MCP:-0}" -eq 1 ]]; then
+  echo "📦 Chrome DevTools MCP will be installed in base image"
+  ADDITIONAL_TOOLS_INSTALL+='ENV CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS=1
+RUN npm install -g chrome-devtools-mcp@latest && \
+    touch /opt/.mcp-chrome-devtools-installed
+'
+fi
+
+if [[ "${INSTALL_PLAYWRIGHT_MCP:-0}" -eq 1 ]]; then
+  echo "📦 Playwright MCP will be installed in base image"
+  ADDITIONAL_TOOLS_INSTALL+='RUN touch /opt/.mcp-playwright-installed
+'
+fi
+
 cat > "dockerfiles/base/Dockerfile" <<EOF
 FROM node:22-bookworm-slim
 
 ARG AGENT_UID=1001
 
-# Install common dependencies
-# Note: python3-venv is needed for many tools, unzip for some installers
 RUN apt-get update && apt-get install -y --no-install-recommends \
     git \
     curl \
@@ -128,10 +187,18 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     unzip \
     xclip \
     wl-clipboard \
+    ripgrep \
     && curl -LsSf https://astral.sh/uv/install.sh | UV_INSTALL_DIR=/usr/local/bin sh \
     && rm -rf /var/lib/apt/lists/* \
     && pipx ensurepath
 
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
+    && chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
+    && echo "deb [arch=\$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
+    && apt-get update \
+    && apt-get install -y gh \
+    && rm -rf /var/lib/apt/lists/*
+
 # Install pnpm globally using npm (not bun, for stability)
 RUN npm install -g pnpm
 
@@ -146,11 +213,11 @@ ${ADDITIONAL_TOOLS_INSTALL}
 # Create workspace
 WORKDIR /workspace
 
-# Non-root user for security
 # Non-root user for security (match host UID)
 RUN useradd -m -u \${AGENT_UID} -d /home/agent agent && \\
     mkdir -p /home/agent/.cache /home/agent/.npm /home/agent/.opencode /home/agent/.config && \\
-    chown -R agent:agent /home/agent/.cache /home/agent/.npm /home/agent/.opencode /home/agent/.config /workspace
+    chown -R agent:agent /home/agent/.cache /home/agent/.npm /home/agent/.opencode /home/agent/.config /workspace && \\
+    ([ -d /opt/playwright-browsers ] && chown -R agent:agent /opt/playwright-browsers || true)
 USER agent
 ENV HOME=/home/agent
 EOF

package/lib/install-opencode.sh

@@ -1,22 +1,36 @@
 #!/usr/bin/env bash
 set -e
 
-# OpenCode installer: Open-source AI coding tool (Native Go Binary)
 TOOL="opencode"
+OPENCODE_VERSION="${OPENCODE_VERSION:-}"
 
-echo "Installing $TOOL (OpenCode AI - Native Go Binary)..."
+if [[ -n "$OPENCODE_VERSION" ]]; then
+  echo "Installing $TOOL v$OPENCODE_VERSION (OpenCode AI - Native Go Binary)..."
+else
+  echo "Installing $TOOL (OpenCode AI - Native Go Binary, latest)..."
+fi
 
-# Create directories
 mkdir -p "dockerfiles/$TOOL"
 mkdir -p "$HOME/.ai-sandbox/tools/$TOOL/home/.cache"
 mkdir -p "$HOME/.ai-sandbox/tools/$TOOL/home"
 
-# Create Dockerfile using official native installer (Go binary)
-cat <<'EOF' > "dockerfiles/$TOOL/Dockerfile"
+if [[ -n "$OPENCODE_VERSION" ]]; then
+  cat > "dockerfiles/$TOOL/Dockerfile" <<EOF
+FROM ai-base:latest
+
+USER root
+RUN curl -fsSL https://opencode.ai/install | bash -s -- --version $OPENCODE_VERSION && \\
+    mv /home/agent/.opencode/bin/opencode /usr/local/bin/opencode && \\
+    rm -rf /home/agent/.opencode
+
+USER agent
+ENTRYPOINT ["opencode"]
+EOF
+else
+  cat <<'EOF' > "dockerfiles/$TOOL/Dockerfile"
 FROM ai-base:latest
 
 USER root
-# Install OpenCode using official native installer
 RUN curl -fsSL https://opencode.ai/install | bash && \
     mv /home/agent/.opencode/bin/opencode /usr/local/bin/opencode && \
     rm -rf /home/agent/.opencode
@@ -24,6 +38,7 @@ RUN curl -fsSL https://opencode.ai/install | bash && \
 USER agent
 ENTRYPOINT ["opencode"]
 EOF
+fi
 
 # Build image
 echo "Building Docker image for $TOOL (native binary)..."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kokorolx/ai-sandbox-wrapper",
-  "version": "2.3.0-beta",
+  "version": "2.6.0",
   "description": "Docker-based security sandbox for AI coding agents. Isolate Claude, Gemini, Aider, and other AI tools from your host system.",
   "keywords": [
     "ai",

package/setup.sh

@@ -321,8 +321,21 @@ if [[ ${#CONTAINERIZED_TOOLS[@]} -gt 0 ]]; then
     echo "Language runtimes selected: ${LANGUAGE_RUNTIMES[*]}"
   fi
 
-  # Combine both categories for processing
-  ADDITIONAL_TOOLS=("${AI_ENHANCEMENT_TOOLS[@]}" "${LANGUAGE_RUNTIMES[@]}")
+  echo ""
+
+  # Category 3: MCP Tools (Browser automation for AI agents)
+  MCP_OPTIONS="chrome-devtools-mcp,playwright-mcp"
+  MCP_DESCS="Google Chrome DevTools MCP - performance profiling + debugging (~400MB),Microsoft Playwright MCP - multi-browser automation (~300MB)"
+
+  multi_select "Select MCP Tools for AI Agent Browser Automation" "$MCP_OPTIONS" "$MCP_DESCS"
+  MCP_TOOLS=("${SELECTED_ITEMS[@]}")
+
+  if [[ ${#MCP_TOOLS[@]} -gt 0 ]]; then
+    echo "MCP tools selected: ${MCP_TOOLS[*]}"
+  fi
+
+  # Combine all categories for processing
+  ADDITIONAL_TOOLS=("${AI_ENHANCEMENT_TOOLS[@]}" "${LANGUAGE_RUNTIMES[@]}" "${MCP_TOOLS[@]}")
 else
   ADDITIONAL_TOOLS=()
   echo "ℹ️  No containerized AI tools selected. Skipping additional tools."
@@ -361,6 +374,8 @@ if [[ $NEEDS_BASE_IMAGE -eq 1 ]]; then
   INSTALL_OPENSPEC=0
   INSTALL_PLAYWRIGHT=0
   INSTALL_RUBY=0
+  INSTALL_CHROME_DEVTOOLS_MCP=0
+  INSTALL_PLAYWRIGHT_MCP=0
 
   for addon in "${ADDITIONAL_TOOLS[@]}"; do
     case "$addon" in
@@ -379,11 +394,32 @@ if [[ $NEEDS_BASE_IMAGE -eq 1 ]]; then
       ruby)
         INSTALL_RUBY=1
         ;;
+      chrome-devtools-mcp)
+        INSTALL_CHROME_DEVTOOLS_MCP=1
+        ;;
+      playwright-mcp)
+        INSTALL_PLAYWRIGHT_MCP=1
+        ;;
     esac
   done
 
-  export INSTALL_SPEC_KIT INSTALL_UX_UI_PROMAX INSTALL_OPENSPEC INSTALL_PLAYWRIGHT INSTALL_RUBY
+  export INSTALL_SPEC_KIT INSTALL_UX_UI_PROMAX INSTALL_OPENSPEC INSTALL_PLAYWRIGHT INSTALL_RUBY INSTALL_CHROME_DEVTOOLS_MCP INSTALL_PLAYWRIGHT_MCP
   bash "$SCRIPT_DIR/lib/install-base.sh"
+  
+  # Save MCP selections to ~/.ai-sandbox/config.json for ai-run auto-configuration
+  SANDBOX_CONFIG="$HOME/.ai-sandbox/config.json"
+  mkdir -p "$HOME/.ai-sandbox"
+  if command -v jq &>/dev/null; then
+    if [[ ! -f "$SANDBOX_CONFIG" ]]; then
+      echo '{"version":2,"workspaces":[],"git":{"allowedWorkspaces":[],"keySelections":{}},"networks":{"global":[],"workspaces":{}},"mcp":{"installed":[]}}' > "$SANDBOX_CONFIG"
+    fi
+    MCP_INSTALLED='[]'
+    [[ "$INSTALL_CHROME_DEVTOOLS_MCP" -eq 1 ]] && MCP_INSTALLED=$(echo "$MCP_INSTALLED" | jq '. + ["chrome-devtools"]')
+    [[ "$INSTALL_PLAYWRIGHT_MCP" -eq 1 ]] && MCP_INSTALLED=$(echo "$MCP_INSTALLED" | jq '. + ["playwright"]')
+    jq --argjson mcp "$MCP_INSTALLED" '.mcp.installed = $mcp' "$SANDBOX_CONFIG" > "$SANDBOX_CONFIG.tmp" && mv "$SANDBOX_CONFIG.tmp" "$SANDBOX_CONFIG"
+    chmod 600 "$SANDBOX_CONFIG"
+    echo "✅ MCP tool selections saved to config"
+  fi
 fi
 
 # Install selected tools
@@ -483,6 +519,12 @@ if [[ ${#ADDITIONAL_TOOLS[@]} -gt 0 ]]; then
       openspec)
         echo "  openspec - OpenSpec CLI for spec-driven development"
         ;;
+      chrome-devtools-mcp)
+        echo "  chrome-devtools-mcp - Google Chrome DevTools MCP server"
+        ;;
+      playwright-mcp)
+        echo "  @playwright/mcp - Microsoft Playwright MCP server"
+        ;;
     esac
   done
 fi