介绍
# Docker Sandbox
使用 Docker Desktop 的沙箱功能在**隔离的 VM 环境**中运行代理和命令。每个沙箱都拥有自己的轻量级 VM，具备文件系统隔离、网络代理控制和通过 virtiofs 进行的 workspace 挂载。
## 何时使用
- 在全系统安装之前探索**不受信任的包**或技能 - 安全地运行来自外部源的**任意代码** - 测试**破坏性操作**而不危及宿主机 - 隔离需要网络访问控制的**代理工作负载** - 为实验设置**可复现的环境**
## 要求
- 安装了 `docker sandbox` 插件的 Docker Desktop 4.49+ - 验证命令：`docker sandbox version`
## 快速开始
### 为当前项目创建沙箱
```bash docker sandbox create --name my-sandbox claude . ```
这将创建一个 VM 隔离的沙箱，具有以下特性： - 当前目录通过 virtiofs 挂载 - 预装 Node.js、git 和标准开发工具 - 具有允许列表控制功能的网络代理
### 在内部运行命令
```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" ```
### 直接运行代理
```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" ```
## 命令参考
### 生命周期
```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> ```
### 网络控制
沙箱包含一个网络代理，用于控制出站访问。
```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> ```
### 自定义模板
```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 ```
## 工作区挂载
宿主机上的工作区路径通过 virtiofs 挂载到沙箱中。沙箱内部的挂载路径保留了宿主机的路径结构：
| 宿主机 OS | 宿主机路径 | 沙箱路径 | |---|---|---| | 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` |
代理的主目录是 `/home/agent/`，其中包含一个符号链接的 `workspace/` 目录。
## 沙箱内部环境
每个沙箱 VM 包括： - **Node.js** (v20.x LTS) - **Git** (最新版) - **Python** (系统自带) - **curl**、**wget**、标准 Linux 工具集 - **npm** (全局安装目录位于 `/usr/local/share/npm-global/`) - **Docker socket** (位于 `/run/docker.sock` - 支持 Docker-in-Docker)
### 代理配置 (自动设置)
``` 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 ```
**重要提示**：Node.js `fetch` (undici) 默认**不**遵循 `HTTP_PROXY` 环境变量。对于使用 `fetch` 的 npm 包，请创建一个 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 }); }; } ```
运行方式：`node -r /tmp/proxy-fix.js your-script.js`
## 模式
### 安全的包探索
```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 ```
### 持久化开发环境
```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 ```
### 锁定的代理执行
```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" ```
## 故障排除
### "client version X is too old"
将 Docker Desktop 更新到 4.49+。沙箱插件需要 engine API v1.44+。
### 沙箱内出现 "fetch failed"
Node.js `fetch` 不使用代理。请使用上面提到的 proxy-fix.js require hook，或者改用 `curl`： ```bash docker sandbox exec my-sandbox curl -sL https://api.example.com/data ```
### Windows 上的路径转换 (Git Bash / MSYS2)
Git Bash 会将 `/path` 转换为 `C:/Program Files/Git/path`。请在命令前添加前缀： ```bash MSYS_NO_PATHCONV=1 docker sandbox exec my-sandbox ls /home/agent ```
### Docker 更新后沙箱无法启动
```bash docker sandbox reset # Clears all sandbox state ```