🐳 Docker Sandbox — 安全沙箱运行
v1.0.0基于 Docker 创建隔离沙箱 VM，安全运行不可信代码、探索依赖包或隔离智能体负载。支持 Claude、Codex、Copilot、Gemini、Kiro 等主流智能体，可精细控制网络代理与挂载策略，一键启停、快照与模板管理，让开发测试无惧风险。
by 详细分析 ▾
- 理解把项目挂载进容器并暴露 /run/docker.sock 会打破大部分隔离保障——避免挂载敏感主机路径，除非确有需要，否则不要暴露 Docker socket。
- 优先采用默认拒绝的网络策略与显式白名单（SKILL.md 支持）；运行未知代码前先测试规则。
- 验证系统中“docker sandbox”插件的来源与行为（技能除 Docker 文档链接外无主页/源码）。
- 先用小型、非敏感实验确认沙箱实际暴露的内容（文件挂载、socket、网络）。
- 若需更强隔离，请使用独立 VM 或不暴露主机 Docker 守护进程/主机文件的沙箱方案。
- 若对插件或 Docker 配置无把握，勿在含敏感数据或凭据的机器上运行不受信代码。
运行时依赖
版本
首次发布 - Docker Desktop 沙箱 VM 管理，支持安全智能体执行、网络代理控制、工作空间挂载与故障排查指南。
安装命令
点击复制技能文档
# Docker 沙盒 使用 Docker Desktop 的沙盒功能，在隔离的 VM 环境中运行 agent 和命令。每个沙盒都拥有自己的轻量级 VM，具备文件系统隔离、网络代理控制，并通过 virtiofs 挂载工作区。 ## 何时使用 - 在系统范围安装前，探索不受信任的软件包或技能 - 安全地运行来自外部的任意代码 - 在不影响宿主机的前提下，测试破坏性操作 - 隔离需要网络访问控制的agent 工作负载 - 为实验搭建可复现的环境 ## 要求 - Docker Desktop 4.49+ 并安装 docker sandbox 插件 - 验证：docker sandbox version ## 快速开始 ### 为当前项目创建沙盒 ``bash docker sandbox create --name my-sandbox claude . ` 这将创建一个 VM 隔离的沙盒，包含： - 通过 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" ` ### 直接运行 agent `bash # 一步创建并运行 docker sandbox run claude . -- -p "What files are in this project?" # 使用 -- 传递 agent 参数 docker sandbox run my-sandbox -- -p "Analyze this codebase" ` ## 命令参考 ### 生命周期 `bash # 创建沙盒（agent 支持：claude、codex、copilot、gemini、kiro、cagent） docker sandbox create --name # 在沙盒中运行 agent（如不存在则自动创建） docker sandbox run [-- ...] docker sandbox run [-- ...] # 执行命令 docker sandbox exec [options] [args...] -e KEY=VAL # 设置环境变量 -w /path # 设置工作目录 -d # 分离（后台）运行 -i # 交互模式（保持 stdin 打开） -t # 分配伪终端 # 停止但不删除 docker sandbox stop # 删除（销毁 VM） 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 挂载进沙盒。沙盒内部挂载路径保持宿主机路径结构： | 宿主机 OS | 宿主机路径 | 沙盒路径 | |---|---|---| | 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 | agent 的主目录为 /home/agent/，其中包含一个软链接的 workspace/ 目录。 ## 沙盒内部环境 每个沙盒 VM 包含： - 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 钩子： `javascript // /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 ## 使用模式 ### 安全地探索软件包 `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 ` ### 锁定式 agent 执行 `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 # 在限制下运行 agent docker sandbox run secure -- -p "Review this code for security issues" ` ## 故障排查 ### “client version X is too old” 请将 Docker Desktop 升级至 4.49+。沙盒插件需要 engine API v1.44+。 ### 沙盒内 “fetch failed” 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 MSYS_NO_PATHCONV=1 docker sandbox exec my-sandbox ls /home/agent ` ### Docker 更新后沙盒无法启动 `bash docker sandbox reset # 清除所有沙盒状态 ``