🔒 AI Sandbox Wrapper

Run OpenCode and other AI coding agents in secure Docker containers.

Protect your SSH keys, API tokens, and system files while using AI tools that need filesystem access.

Last updated: February 25, 2026

📑 Table of Contents

• What's New
• Why Use This?
• Quick Start
• Configuration
  • API Keys
  • Workspaces
  • Port Exposure
  • Server Authentication
  • Network Access
  • Git Access
  • Clipboard
• Directory Structure
• Security Model
• Quick Reference
• Troubleshooting
• Other Tools
• Contributing
• License

✨ What's New

📦 Package moved to @nano-step scope

This project is now published as @nano-step/ai-sandbox-wrapper. The old @kokorolx/ai-sandbox-wrapper package is deprecated and will no longer receive updates.

# Old (deprecated)
npx @kokorolx/ai-sandbox-wrapper setup

# New
npx @nano-step/ai-sandbox-wrapper setup

If you have the old package globally installed, uninstall it:

npm uninstall -g @kokorolx/ai-sandbox-wrapper

v5.4.0: Per-Project OpenCode Database Isolation

OpenCode containers now use isolated SQLite databases per project to prevent corruption from concurrent writes (sst/opencode#14194). Container ai-opencode-<hash> is reused across terminals attached to the same project; second-terminal invocations attach via docker exec.

📖 Migrating from v5.3.x? Read MIGRATION_GUIDE.md — your old session history is preserved but needs one of: migration, fresh start, or opt-out.

# Migrate existing sessions into per-project DBs (recommended)
npx @nano-step/ai-sandbox-wrapper@latest migrate-opencode-db --apply

# Or opt out of isolation entirely (keep legacy global DB)
export OPENCODE_DB_ISOLATION=0

Known limitation: when two terminals run opencode for the same project, quitting the first kills the second too (Docker PID 1 semantics). See TROUBLESHOOTING.md for details and workarounds.

v2.7.0: Git Fetch-Only Mode & Bundled Skills

• Git Fetch-Only: Allow git fetch/pull but block push — perfect for AI agents that should read but not write
• Bundled Skills: RTK token optimizer skills auto-installed for OpenCode users
• SSH Config Fix: Resolved crash during git credential setup

# Fetch-only mode (no push allowed)
opencode --git-fetch

# Or select from interactive menu:
#   4) Fetch only - allow once (no push, this session)
#   5) Fetch only - always for this workspace (no push)

# Manage via CLI
npx @nano-step/ai-sandbox-wrapper git fetch-only ~/projects/myrepo
npx @nano-step/ai-sandbox-wrapper git full ~/projects/myrepo
npx @nano-step/ai-sandbox-wrapper git status

🛡️ Why Use This?

| Without Sandbox | With AI Sandbox | |-----------------|-----------------| | AI reads SSH keys, API tokens | ✅ Only whitelisted folders visible | | Full filesystem access | ✅ Read-only except workspace | | 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)

# Install
npx @nano-step/ai-sandbox-wrapper setup

# Reload shell
source ~/.zshrc

# Run OpenCode
opencode

During setup you will be asked:

1. Image source — pull pre-built from ghcr.io (1-2 min) or build locally (~10-20 min)
   • If you choose registry, setup fetches the available tags and lets you pick one (requires gh auth login)
   • If gh is not authenticated, setup falls back to showing base / full options
2. Tools — select which AI tools to install (opencode, claude, amp, etc.)
3. Workspaces — whitelist your project directories

⚙️ Configuration

API Keys

nano ~/.ai-sandbox/env

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

Workspaces

npx @nano-step/ai-sandbox-wrapper workspace add ~/projects/my-app
# Or: echo '/path/to/project' >> ~/.ai-sandbox/workspaces

Port Exposure

# New --expose flag (recommended)
opencode --expose 3000
opencode -e 3000,5555,5556

# Expose to network
PORT_BIND=all opencode --expose 3000

# Legacy (deprecated)
PORT=3000 opencode

Web Mode Auto-Detection:

opencode web                    # Auto-exposes 4096
opencode web --port 8080        # Auto-exposes 8080
opencode --expose 3000 web      # Exposes both 3000 and 4096

Output:

🌐 Detected web command. Auto-exposing port 4096.
🔌 Port mappings: 4096
🌐 Web UI available at http://localhost:4096

Server Authentication

Control authentication for OpenCode web server:

# 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)

Network Access

# Join Docker networks (for databases, APIs, MetaMCP)
opencode -n mynetwork
opencode -n network1,network2

Git Access

Git credentials are not shared by default. When you run a tool, you'll be prompted:

🔐 Git Access Control
  1) Yes, allow once
  2) Yes, always allow for this workspace
  3) No, keep Git disabled (secure default)
  4) Fetch only - allow once (no push, this session)
  5) Fetch only - always for this workspace (no push)

Fetch-only mode allows git fetch, git pull, git clone but blocks git push. Uses git's pushInsteadOf config — no network restrictions needed.

# Force fetch-only via flag
opencode --git-fetch

# Manage via CLI
npx @nano-step/ai-sandbox-wrapper git fetch-only ~/projects/myrepo
npx @nano-step/ai-sandbox-wrapper git full ~/projects/myrepo

Nano-brain Auto-Repair

When running nano-brain inside the sandbox, ai-run performs a targeted preflight and automatic retry for common native-module failures (for example tree-sitter binding issues).

It also suppresses known non-fatal tree-sitter symbol-graph warnings when the command succeeds, so normal query output stays clean. To see suppressed diagnostics, run with debug mode (AI_RUN_DEBUG=1).

This behavior applies to both:

• direct mode (ai-run npx nano-brain ...)
• interactive shell mode (ai-run, then run npx nano-brain ... inside the container shell)

# Auto-repair enabled by default
ai-run npx nano-brain status

# Disable per-command
ai-run npx nano-brain status --no-nano-brain-auto-repair

# Disable via environment variable
AI_RUN_DISABLE_NANO_BRAIN_AUTO_REPAIR=1 ai-run npx nano-brain status

# Show suppressed non-fatal warning details
AI_RUN_DEBUG=1 ai-run npx nano-brain query "hello"

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:

printf "\033]52;c;$(printf "test" | base64)\a"
# Press Cmd+V / Ctrl+V - if you see "test", it works

📖 Full details: 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:

{
  "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.

Bundled Skills (OpenCode)

OpenCode containers auto-install these skills on first run (existing skills are never overwritten):

| Skill | Description | |-------|-------------| | rtk | Command reference for RTK token optimizer (60-90% token savings) | | rtk-setup | Persistent RTK enforcement — updates AGENTS.md and propagates to subagents |

Skills are copied to ~/.config/opencode/skills/ and available immediately.

Pre-built Images from ghcr.io

Setup automatically asks whether to pull a pre-built image or build locally. Pulling is faster (1-2 min vs 10-20 min).

During npx @nano-step/ai-sandbox-wrapper setup:

1. Choose "Use pre-built image from ghcr.io"
2. Setup fetches available tags and shows push dates — pick one (requires gh auth login)
3. If not authenticated with gh, setup shows base / full as fallback options
4. The pulled image is tagged as ai-sandbox:latest and ready to use

# Authenticate gh to see all available tags with push dates
gh auth login
gh auth refresh --scopes read:packages

# Then run setup
npx @nano-step/ai-sandbox-wrapper setup

Tag formats:

• base / full — rolling latest, always up to date
• base-sha-<short> / full-sha-<short> — pinned to a specific commit
• base-v<version> / full-v<version> — pinned to a semver release

Advanced — pull manually without setup:

docker pull ghcr.io/nano-step/ai-opencode:base
docker tag ghcr.io/nano-step/ai-opencode:base ai-sandbox:latest

Image contents — what's inside each variant

Both variants share the same base layer (Node 22, Bun, pnpm, Python 3 + pipx + uv, ripgrep, fd, tmux, vim, gh CLI, TypeScript/Python LSP servers, PDF/OCR tools, build-essential). They differ only in the opt-in INSTALL_* flags layered on top.

| Component | :base (~2.3 GB) | :full (~2.7 GB) | |---|:---:|:---:| | opencode binary (ENTRYPOINT) | ✅ | ✅ | | Coding helpers | | | | spec-kit (specify) | ✅ | ✅ | | ux-ui-promax (uipro) | ✅ | ✅ | | OpenSpec CLI (openspec) | ✅ | ✅ | | RTK (token optimizer) + OpenCode skills rtk, rtk-setup | ✅ | ✅ | | Atlassian CLI (acli) | ✅ | ✅ | | Observability | | | | Datadog Pup CLI + OpenCode skill dd-pup | ✅ | ✅ | | Language toolchains | | | | Go 1.23 + sqlc, goose, golangci-lint | ✅ | ✅ | | Ruby + Rails | ❌ | ❌ | | Browser tools | | | | chrome-devtools-mcp (host CDP mode) | ✅ | ✅ | | @playwright/mcp (host CDP mode) | ✅ | ✅ | | Chromium binary in container | ❌ (host mode) | ❌ (host mode) | | Playwright npm + browsers (standalone) | ❌ | ✅ | | Open Design | | | | od-status / od-health helper scripts | ❌ | ✅ |

Practical guidance:

• :base (default) — pick this for normal OpenCode usage. It has every tool needed for coding, code review, observability work, and MCP browser automation against host Chrome.
• :full — pick this if you also need to run standalone Playwright scripts inside the container (e.g. npx playwright test) or use the Open Design daemon helpers.

Neither variant ships Chromium inside the container — both MCP browser tools (chrome-devtools-mcp, playwright-mcp) connect to host Chrome over CDP. You must configure mcp.chromePath in ~/.ai-sandbox/config.json for browser MCP to work.

The exact preset definitions live in ci/presets/base.env and ci/presets/full.env — these are the source of truth for what each image ships. Adding a new tool to a preset requires editing one of these files (see AGENTS.md "Adding a New Tool > Kind B").

📁 Directory Structure

~/.ai-sandbox/
├── config.json      # Workspaces, git, networks
├── env              # API keys
├── tools/           # Per-tool sandbox homes
│   └── opencode/home/
└── shared/git/      # Shared git credentials

Native configs are bind-mounted:

• ~/.config/opencode ↔ /home/agent/.config/opencode
• ~/.local/share/opencode ↔ /home/agent/.local/share/opencode

Per-project SQLite isolation: OpenCode's database files (opencode.db, opencode.db-wal, opencode.db-shm) are isolated per-project under ~/.ai-sandbox/opencode-dbs/<hash>/ to prevent SQLite WAL corruption from concurrent writes. The <hash> is computed deterministically from the git remote URL (preferred), git toplevel, or absolute path. All other opencode data (sessions, MCP config, skills, logs, storage payloads) remains shared across projects.

🔐 Security Model

┌─────────────────────────────────────────────────┐
│                   HOST SYSTEM                    │
│  ❌ SSH keys, API tokens, browser data          │
│  ❌ Home directory, system files                │
│  ❌ Other projects                               │
└─────────────────────────────────────────────────┘
                        │
                   Docker isolation
                        │
┌─────────────────────────────────────────────────┐
│              AI SANDBOX CONTAINER               │
│  ✅ /workspace (whitelisted folders only)       │
│  ✅ Passed API keys (explicit)                  │
│  ✅ Git config (opt-in per workspace)           │
│  ❌ Everything else                              │
└─────────────────────────────────────────────────┘

📚 Quick Reference

# Run OpenCode
opencode                      # Direct mode
opencode --shell              # Interactive shell
opencode web                  # Web UI mode

# Port exposure
opencode --expose 3000        # Expose port
opencode -e 3000,4000         # Multiple ports

# Network
opencode -n mynetwork         # Join Docker network

# Git fetch-only
opencode --git-fetch            # Fetch only (no push)

# Nano-brain
ai-run npx nano-brain status                      # With auto-repair
AI_RUN_DISABLE_NANO_BRAIN_AUTO_REPAIR=1 ai-run npx nano-brain status

# Management
npx @nano-step/ai-sandbox-wrapper workspace list
npx @nano-step/ai-sandbox-wrapper clean

# OpenCode DB migration (one-time, splits global DB into per-project DBs)
npx @nano-step/ai-sandbox-wrapper migrate-opencode-db          # dry run (preview only)
npx @nano-step/ai-sandbox-wrapper migrate-opencode-db --apply  # perform migration

❓ Troubleshooting

| Issue | Solution | |-------|----------| | command not found: opencode | Run source ~/.zshrc | | 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 | | nano-brain native binding/tree-sitter error | Fatal errors auto-repair and retry once by default; known non-fatal symbol-graph warnings are suppressed unless AI_RUN_DEBUG=1 |

📦 Other Tools

This sandbox also supports Claude, Gemini, Aider, Kilo, Codex, Amp, Qwen, and more.

See TOOLS.md for the full list and tool-specific configuration.

🤝 Contributing

See CONTRIBUTING.md.

📝 License

MIT