名称： docker-sandbox
描述： 创建和管理 Docker 沙盒化虚拟机环境，用于安全执行智能体。适用于运行不受信任的代码、探索软件包或隔离智能体工作负载。支持 Claude、Codex、Copilot、Gemini 和 Kiro 智能体，并提供网络代理控制。
元数据： {"clawdbot":{"emoji":"🐳","requires":{"bins":["docker"]},"primaryEnv":"","homepage":"https://docs.docker.com/desktop/features/sandbox/","os":["linux","darwin","win32"]}}

Docker 沙盒

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

使用场景

• 在系统全局安装前，安全地探索不受信任的软件包或技能
• 安全地运行来自外部的任意代码
• 在不影响主机的情况下测试破坏性操作
• 隔离需要网络访问控制的智能体工作负载
• 为实验设置可复现的环境

前提条件

• 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 [选项] <沙盒> <命令> [参数...]
  -e KEY=VAL          # 设置环境变量
  -w /路径            # 设置工作目录
  -d                  # 后台运行 (分离模式)
  -i                  # 交互模式 (保持标准输入打开)
  -t                  # 分配伪终端

# 停止但不删除沙盒
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

# 阻止 IP 范围
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 .

# 将当前沙盒状态保存为模板以供复用
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

使用模式

安全的软件包探索

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

# 限制网络仅允许访问 npm 注册表
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"

# 检查安装后脚本、网络调用、文件访问
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+ 版本。沙盒插件需要引擎 API v1.44+。

沙盒内出现 "fetch failed"

Node.js 的 fetch 不使用代理。请使用上述的 proxy-fix.js require 钩子，或改用 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  # 清除所有沙盒状态