Docker Sandbox Lucas

Docker Sandbox

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

使用场景

• 在全局安装前，安全探索不受信任的软件包或技能（skills）
• 安全地运行来自外部来源的任意代码
• 执行破坏性操作（如格式化、删除、重写等），避免影响宿主机
• 隔离需要精细网络访问控制的 agent 工作负载
• 为实验搭建可复现的环境

前置要求

• Docker Desktop 4.49+，且已安装 docker sandbox 插件
• 验证安装：docker sandbox version

快速上手

为当前项目创建 sandbox

docker sandbox create --name my-sandbox claude .

该命令将创建一个基于虚拟机隔离的 sandbox，包含以下特性：

• 当前目录通过 virtiofs 挂载至 sandbox
• 预装 Node.js、git 及标准开发工具
• 配备支持域名白名单控制的网络代理

在 sandbox 内执行命令

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"

直接运行 agent

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

# 在 `--` 后传入 agent 特定参数
docker sandbox run my-sandbox -- -p "分析此代码库"

命令参考

生命周期管理

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

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

# 停止 sandbox（不销毁 VM）
docker sandbox stop# 删除 sandbox（彻底销毁 VM）
docker sandbox rm# 列出所有 sandbox
docker sandbox ls

# 重置全部 sandbox 状态
docker sandbox reset

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

网络控制

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

# 允许特定域名访问
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

# 屏蔽 IP 地址段（CIDR 格式）
docker sandbox network proxy--block-cidr 10.0.0.0/8

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

# 设置默认策略（允许或拒绝全部流量）
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 .

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

工作区挂载

宿主机上的工作区路径通过 virtiofs 挂载进 sandbox，sandbox 内路径结构与宿主机一致：

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

Sandbox 内部环境

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

• 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 环境变量。若 npm 包内部使用 fetch 发起请求，需通过 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

实践模式

安全探索第三方包

# 创建隔离 sandbox
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

严格受限的 Agent 执行

# 默认拒绝全部网络访问，仅开放必要出口
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

# 在严格限制下运行 agent
docker sandbox run secure -- -p "审查此代码是否存在安全问题"

故障排查

“client version X is too old”

请升级 Docker Desktop 至 4.49+。sandbox 插件依赖 Engine API v1.44+。

sandbox 内 “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 升级后 sandbox 无法启动

docker sandbox reset  # 清除全部 sandbox 状态