docker-sandbox

# Docker Sandbox Run agents and commands in **isolated VM environments** using Docker Desktop's sandbox feature. Each sandbox gets its own lightweight VM with filesystem isolation, network proxy controls, and workspace mounting via virtiofs. ## When to Use - Exploring **untrusted packages** or skills before installing them system-wide - Running **arbitrary code** from external sources safely - Testing **destructive operations** without risking the host - Isolating **agent workloads** that need network access controls - Setting up **reproducible environments** for experiments ## Requirements - Docker Desktop 4.49+ with the `docker sandbox` plugin - Verify: `docker sandbox version` ## Quick Start ### Create a sandbox for the current project ```bash docker sandbox create --name my-sandbox claude . ``` This creates a VM-isolated sandbox with: - The current directory mounted via virtiofs - Node.js, git, and standard dev tools pre-installed - Network proxy with allowlist controls ### Run commands inside ```bash docker sandbox exec my-sandbox node --version docker sandbox exec my-sandbox npm install -g some-package docker sandbox exec -w /path/to/workspace my-sandbox bash -c "ls -la" ``` ### Run an agent directly ```bash # Create and run in one step docker sandbox run claude . -- -p "What files are in this project?" # Run with agent arguments after -- docker sandbox run my-sandbox -- -p "Analyze this codebase" ``` ## Commands Reference ### Lifecycle ```bash # Create a sandbox (agents: claude, codex, copilot, gemini, kiro, cagent) docker sandbox create --name <name> <agent> <workspace-path> # Run an agent in sandbox (creates if needed) docker sandbox run <agent> <workspace> [-- <agent-args>...] docker sandbox run <existing-sandbox> [-- <agent-args>...] # Execute a command docker sandbox exec [options] <sandbox> <command> [args...] -e KEY=VAL # Set environment variable -w /path # Set working directory -d # Detach (background) -i # Interactive (keep stdin open) -t # Allocate pseudo-TTY # Stop without removing docker sandbox stop <sandbox> # Remove (destroys VM) docker sandbox rm <sandbox> # List all sandboxes docker sandbox ls # Reset all sandboxes docker sandbox reset # Save snapshot as reusable template docker sandbox save <sandbox> ``` ### Network Controls The sandbox includes a network proxy for controlling outbound access. ```bash # Allow specific domains docker sandbox network proxy <sandbox> --allow-host example.com docker sandbox network proxy <sandbox> --allow-host api.github.com # Block specific domains docker sandbox network proxy <sandbox> --block-host malicious.com # Block IP ranges docker sandbox network proxy <sandbox> --block-cidr 10.0.0.0/8 # Bypass proxy for specific hosts (direct connection) docker sandbox network proxy <sandbox> --bypass-host localhost # Set default policy (allow or deny all by default) docker sandbox network proxy <sandbox> --policy deny # Block everything, then allowlist docker sandbox network proxy <sandbox> --policy allow # Allow everything, then blocklist # View network activity docker sandbox network log <sandbox> ``` ### Custom Templates ```bash # Use a custom container image as base docker sandbox create --template my-custom-image:latest claude . # Save current sandbox state as template for reuse docker sandbox save my-sandbox ``` ## Workspace Mounting The workspace path on the host is mounted into the sandbox via virtiofs. The mount path inside the sandbox preserves the host path structure: | Host OS | Host Path | Sandbox Path | |---|---|---| | Windows | `H:\Projects\my-app` | `/h/Projects/my-app` | | macOS | `/Users/me/projects/my-app` | `/Users/me/projects/my-app` | | Linux | `/home/me/projects/my-app` | `/home/me/projects/my-app` | The agent's home directory is `/home/agent/` with a symlinked `workspace/` directory. ## Environment Inside the Sandbox Each sandbox VM includes: - **Node.js** (v20.x LTS) - **Git** (latest) - **Python** (system) - **curl**, **wget**, standard Linux utilities - **npm** (global install directory at `/usr/local/share/npm-global/`) - **Docker socket** (at `/run/docker.sock` - Docker-in-Docker capable) ### Proxy Configuration (auto-set) ``` HTTP_PROXY=http://host.docker.internal:3128 HTTPS_PROXY=http://host.docker.internal:3128 NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/proxy-ca.crt SSL_CERT_FILE=/usr/local/share/ca-certificates/proxy-ca.crt ``` **Important**: Node.js `fetch` (undici) does NOT respect `HTTP_PROXY` env vars by default. For npm packages that use `fetch`, create a require hook: ```javascript // /tmp/proxy-fix.js const proxy = process.env.HTTPS_PROXY || process.env.HTTP_PROXY; if (proxy) { const { ProxyAgent } = require('undici'); const agent = new ProxyAgent(proxy); const origFetch = globalThis.fetch; globalThis.fetch = function(url, opts = {}) { return origFetch(url, { ...opts, dispatcher: agent }); }; } ``` Run with: `node -r /tmp/proxy-fix.js your-script.js` ## Patterns ### Safe Package Exploration ```bash # Create isolated sandbox docker sandbox create --name pkg-test claude . # Restrict network to only npm registry docker sandbox network proxy pkg-test --policy deny docker sandbox network proxy pkg-test --allow-host registry.npmjs.org docker sandbox network proxy pkg-test --allow-host api.npmjs.org # Install and inspect the package docker sandbox exec pkg-test npm install -g suspicious-package docker sandbox exec pkg-test bash -c "find /usr/local/share/npm-global/lib/node_modules/suspicious-package -name '*.js' | head -20" # Check for post-install scripts, network calls, file access docker sandbox network log pkg-test # Clean up docker sandbox rm pkg-test ``` ### Persistent Dev Environment ```bash # Create once docker sandbox create --name dev claude ~/projects/my-app # Use across sessions docker sandbox exec dev npm test docker sandbox exec dev npm run build # Save as template for team sharing docker sandbox save dev ``` ### Locked-Down Agent Execution ```bash # Deny-all network, allow only what's needed docker sandbox create --name secure claude . docker sandbox network proxy secure --policy deny docker sandbox network proxy secure --allow-host api.openai.com docker sandbox network proxy secure --allow-host github.com # Run agent with restrictions docker sandbox run secure -- -p "Review this code for security issues" ``` ## Troubleshooting ### "client version X is too old" Update Docker Desktop to 4.49+. The sandbox plugin requires engine API v1.44+. ### "fetch failed" inside sandbox Node.js `fetch` doesn't use the proxy. Use the proxy-fix.js require hook above, or use `curl` instead: ```bash docker sandbox exec my-sandbox curl -sL https://api.example.com/data ``` ### Path conversion on Windows (Git Bash / MSYS2) Git Bash converts `/path` to `C:/Program Files/Git/path`. Prefix commands with: ```bash MSYS_NO_PATHCONV=1 docker sandbox exec my-sandbox ls /home/agent ``` ### Sandbox won't start after Docker update ```bash docker sandbox reset # Clears all sandbox state ```