Docker 沙盒

在隔离的虚拟机环境中运行代理和命令

使用 Docker Desktop 的沙盒功能。每个沙盒都拥有自己轻量级的虚拟机，具备文件系统隔离、网络代理控制以及通过 virtiofs 挂载工作区的功能。

• 使用场景在系统全局安装之前探索
• 不受信任的软件包或技能安全地
• 运行来自外部源的任意代码
• 在不危及主机的情况下测试破坏性操作
• 隔离需要网络访问控制的代理工作负载

为实验

• 设置Docker 沙箱插件
• 验证：Docker 沙箱版本

快速开始

为当前项目创建一个沙箱

docker sandbox create --name my-sandbox claude .

这将创建一个具备虚拟机隔离的沙箱，包含：

• 通过 virtiofs 挂载的当前目录
• 预装的 Node.js、git 和标准开发工具
• 带有允许列表控制的网络代理

在沙箱内部运行命令

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"

直接运行代理程序

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

命令参考

生命周期

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

网络控制

沙箱包含一个用于控制出站访问的网络代理。

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

自定义模板

# 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 挂载到沙箱中。沙箱内的挂载路径保留了主机路径结构：

代理的主目录是/home/agent/其中有一个符号链接的workspace/目录。

沙箱内部环境

每个沙箱虚拟机包含：

• Node.js(v20.x LTS)
• Git(最新版本)
• Python(系统自带)
• curl以及wget标准的 Linux 工具
• npm（全局安装目录位于/usr/local/share/npm-global/）
• Docker 套接字（位于/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 钩子：

// /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

模式

安全的包探索

# 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

持久化开发环境

# 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

锁定代理执行

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

故障排除

"客户端版本 X 过旧"

将 Docker Desktop 更新到 4.49+ 版本。沙盒插件需要引擎 API v1.44+。

沙盒内出现 "获取失败"

Node.jsfetch不使用代理。请使用上述的 proxy-fix.js 引入钩子，或者改用curl命令：

docker sandbox exec my-sandbox curl -sL https://api.example.com/data

Windows 上的路径转换问题 (Git Bash / MSYS2)

Git Bash 会将/path转换为C:/Program Files/Git/path。请在命令前添加：

MSYS_NO_PATHCONV=1 docker sandbox exec my-sandbox ls /home/agent

Docker 更新后沙盒无法启动

docker sandbox reset  # Clears all sandbox state