Docker 沙箱

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

使用场景

• - 在系统范围内安装不受信任的软件包或技能前进行探索
• 安全地运行来自外部来源的任意代码
• 测试破坏性操作而不危及宿主机
• 隔离需要网络访问控制的代理工作负载
• 为实验搭建可复现的环境

系统要求

• - Docker Desktop 4.49+ 并安装 docker sandbox 插件
• 验证命令：docker sandbox version

快速开始

为当前项目创建沙箱

bash
docker sandbox create --name my-sandbox claude .

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

• - 通过 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

一步完成创建和运行

docker sandbox run claude . -- -p 这个项目中有哪些文件？

在 -- 后传递代理参数

docker sandbox run my-sandbox -- -p 分析此代码库

命令参考

生命周期管理

bash

创建沙箱（支持的代理：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 <沙箱>

网络控制

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

bash

允许特定域名

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 <沙箱>

自定义模板

bash

使用自定义容器镜像作为基础

docker sandbox create --template my-custom-image:latest claude .

将当前沙箱状态保存为可复用模板

docker sandbox save my-sandbox

工作区挂载

宿主机上的工作区路径通过 virtiofs 挂载到沙箱中。沙箱内的挂载路径保留宿主机路径结构：

宿主机操作系统	宿主机路径	沙箱路径
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/ 目录。

沙箱内部环境

每个沙箱虚拟机包含：

• - 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
NODEEXTRACA_CERTS=/usr/local/share/ca-certificates/proxy-ca.crt
SSLCERTFILE=/usr/local/share/ca-certificates/proxy-ca.crt

重要提示：Node.js 的 fetch（undici）默认不遵循 HTTP_PROXY 环境变量。对于使用 fetch 的 npm 包，请创建 require 钩子：

javascript
// /tmp/proxy-fix.js
const proxy = process.env.HTTPSPROXY || process.env.HTTPPROXY;
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

创建隔离沙箱

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

持久化开发环境

bash

一次性创建

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

锁定式代理执行

bash

默认拒绝所有网络，仅允许必要访问

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 审查此代码的安全问题

故障排除

客户端版本 X 太旧

请将 Docker Desktop 更新至 4.49+。沙箱插件需要引擎 API v1.44+。

沙箱内 fetch 失败

Node.js 的 fetch 不使用代理。请使用上述 proxy-fix.js require 钩子，或改用 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 MSYSNOPATHCONV=1 docker sandbox exec my-sandbox ls /home/agent

Docker 更新后沙箱无法启动

bash docker sandbox reset # 清除所有沙箱状态