Docker Sandbox

Docker Sandbox

使用 Docker Desktop 的 sandbox（沙箱）功能，在隔离的虚拟机环境中运行智能体（agents）和命令。每个沙箱都拥有独立的轻量级虚拟机，具备文件系统隔离、网络代理控制，并通过 virtiofs 挂载工作区（workspace）。

适用场景

• 在全局安装前，安全地探索不受信任的软件包或技能（skills）
• 安全地执行来自外部来源的任意代码
• 测试可能破坏系统的高风险操作，避免影响宿主机
• 隔离需要精细网络访问控制的智能体工作负载
• 为实验搭建可复现的运行环境

前置要求

• Docker Desktop 4.49 及以上版本，并已安装 docker sandbox 插件
• 验证安装：运行 docker sandbox version

快速入门

为当前项目创建沙箱

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"

直接运行智能体

# 创建并运行一步完成
docker sandbox run claude . -- -p "这个项目里有哪些文件？"

# 运行已有沙箱，并在 `--` 后传入智能体专属参数
docker sandbox run my-sandbox -- -p "分析这个代码库"

命令参考

生命周期管理

# 创建沙箱（支持的智能体：claude、codex、copilot、gemini、kiro、cagent）
docker sandbox create --name# 在沙箱中运行智能体（若沙箱不存在则自动创建）
docker sandbox run[--...]
docker sandbox run[--...]

# 执行任意命令
docker sandbox exec [options][args...]
  -e KEY=VAL          # 设置环境变量
  -w /path            # 设置工作目录
  -d                  # 后台运行（detach）
  -i                  # 交互模式（保持 stdin 打开）
  -t                  # 分配伪 TTY

# 停止沙箱（不删除）
docker sandbox stop# 删除沙箱（销毁对应虚拟机）
docker sandbox rm# 列出所有沙箱
docker sandbox ls

# 重置全部沙箱状态
docker sandbox reset

# 将当前沙箱保存为可复用模板
docker sandbox save

网络控制

沙箱内置网络代理，用于精细管控出站网络请求。

# 允许访问特定域名
docker sandbox network proxy--allow-host example.com
docker sandbox network proxy--allow-host api.github.com

# 禁止访问特定域名
docker sandbox network proxy--block-host malicious.com

# 禁止访问指定 CIDR 网段
docker sandbox network proxy--block-cidr 10.0.0.0/8

# 对特定主机绕过代理（直连）
docker sandbox network proxy--bypass-host localhost

# 设置默认策略（`allow` 或 `deny`）
docker sandbox network proxy--policy deny  # 默认拒绝一切，再按需白名单放行
docker sandbox network proxy--policy allow  # 默认允许一切，再按需黑名单拦截

# 查看网络活动日志
docker sandbox network log

自定义模板

# 使用自定义容器镜像作为基础环境
docker sandbox create --template my-custom-image:latest claude .

# 将当前沙箱状态保存为可复用模板
docker sandbox save my-sandbox

工作区挂载（Workspace Mounting）

宿主机上的工作区路径通过 virtiofs 挂载进沙箱，且沙箱内的挂载路径严格保留宿主机原始路径结构：

智能体的主目录为 /home/agent/，其中 workspace/ 是指向挂载工作区的符号链接。

沙箱内部环境

每个沙箱虚拟机预装以下组件：

• 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 注入代理支持：

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

实践模式

安全探索第三方包

# 创建隔离沙箱
docker sandbox create --name pkg-test claude .

# 仅允许访问 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

# 安装并检查可疑包
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"

# 检查 postinstall 脚本、外连行为、敏感文件访问等
docker sandbox network log pkg-test

# 清理资源
docker sandbox rm pkg-test

持久化开发环境

# 一次性创建
docker sandbox create --name dev claude ~/projects/my-app

# 多次复用（跨会话）
docker sandbox exec dev npm test
docker sandbox exec dev npm run build

# 保存为团队共享模板
docker sandbox save dev

严格受限的智能体执行

# 默认禁止所有网络访问，仅开放必要服务
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

# 在限制条件下运行智能体
docker sandbox run secure -- -p "审查此代码是否存在安全问题"

故障排查

“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：

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  # 清除全部沙箱状态