docker-sandbox

核心用法

docker-sandbox 是一个纯文档型技能，指导用户利用 Docker Desktop 4.49+ 内置的 docker sandbox 插件创建轻量级 VM 隔离环境。核心工作流包括：通过 docker sandbox create 初始化沙箱（支持 Claude、Codex、Copilot、Gemini、Kiro 等主流 Agent），使用 docker sandbox exec 执行命令，或 docker sandbox run 直接启动 Agent 会话。关键特性是网络代理控制层——用户可通过 --policy deny 实施默认拒绝策略，再精确允许特定域名（如 registry.npmjs.org、、api.openai.com`），实现最小权限网络访问。

显著优点

安全架构领先：VM 级隔离而非容器级，配合 virtiofs 挂载实现性能与隔离的平衡。网络代理支持域名白名单、CIDR 阻断、直连绕过三重控制，满足零信任安全模型。多 Agent 生态兼容：原生支持五大主流 AI Agent，避免厂商锁定。开发体验优化：预装 Node.js LTS、Git、Python 等工具链，工作目录自动挂载保留路径结构，跨平台一致（Windows/macOS/Linux）。可复现环境：支持 docker sandbox save 将配置固化为团队共享模板。

潜在缺点与局限性

版本门槛严苛：强制要求 Docker Desktop 4.49+，旧版本用户无法使用。Node.js 代理兼容性问题：原生 fetch（undici）不识别 HTTP_PROXY 环境变量，需手动注入 require hook，增加使用摩擦。Windows 路径转换陷阱：Git Bash/MSYS2 环境存在路径自动转换问题，需设置 MSYS_NO_PATHCONV=1。资源开销：每个沙箱独立 VM，大量并行实例将显著消耗内存与 CPU。功能依赖官方：作为 Docker Desktop 专属功能，无法迁移至纯 Linux Docker Engine 环境。

适合的目标群体

安全敏感型开发者：需要运行 npm 生态中来源可疑的包、执行 LLM 生成的未审计代码。AI Agent 重度用户：频繁调用 Claude/Codex 等工具处理多项目代码，需防止交叉污染。DevOps/SRE 工程师：构建可复现的 CI 测试环境，验证破坏性变更。安全研究员：分析恶意样本或漏洞利用代码，需网络可控的隔离沙箱。企业合规团队：满足代码审计、供应链安全等合规要求。

使用风险

性能风险：VM 启动延迟（数秒级）不适合高频短命令场景；virtiofs 大文件 IO 可能瓶颈。依赖风险：Docker Desktop 更新可能破坏沙箱状态（需 docker sandbox reset 修复）。配置风险：网络策略误配可能导致 Agent 无法访问必要 API，或过度放行丧失隔离意义。隐性成本：Docker Desktop 商业许可在企业场景可能产生费用。

核心功能与用法

docker-sandbox 是 Docker Desktop 4.49+ 引入的 VM 级隔离特性封装 Skill，专为大语言模型代理（Claude、Codex、Copilot、Gemini、Kiro 等）设计安全执行环境。

核心用法

快速创建与运行：

docker sandbox create --name my-sandbox claude .
docker sandbox run claude . -- -p "分析此代码库"

生命周期管理：

• create/run/exec/stop/rm/ls 完整沙箱生命周期控制
• save 将当前状态保存为可复用模板
• reset 一键重置所有沙箱状态

网络精细管控：

docker sandbox network proxy <sandbox> --policy deny              # 默认拒绝
docker sandbox network proxy <sandbox> --allow-host api.github.com  # 白名单放行
docker sandbox network log <sandbox>                              # 审计网络活动

显著优点

| 优势 | 说明 |

|------|------|

| **VM 级隔离** | 非容器级，而是独立轻量 VM，内核隔离更安全 |

| **virtiofs 高性能挂载** | 工作目录以原生性能映射进沙箱 |

| **代理原生集成** | 自动注入 HTTP_PROXY 环境，支持精细化出网控制 |

| **多代理支持** | 统一封装 Claude/Codex/Copilot/Gemini/Kiro |

| **Docker-in-Docker** | 内置 `/run/docker.sock`，支持嵌套容器操作 |

潜在局限与风险

局限性：

• Node.js fetch 代理不兼容：undici 不读取 HTTP_PROXY，需手动注入 dispatcher（Skill 文档提供修复脚本）
• Windows 路径转换陷阱：Git Bash/MSYS2 会自动转换 /path 为 Windows 路径，需设置 MSYS_NO_PATHCONV=1
• 版本锁定：强制要求 Docker Desktop 4.49+，旧版本完全不可用
• 平台依赖：仅支持 Docker Desktop，Linux 纯引擎用户无法使用

常规风险：

• 过度信任隔离：VM 逃逸虽极难，但 virtiofs 共享目录仍是潜在攻击面
• 网络代理配置错误：默认 --policy allow 可能让恶意代码外联，生产环境建议显式 --policy deny
• 敏感数据残留：工作目录挂载意味着沙箱内可读写宿主机项目文件，敏感配置文件可能被意外暴露

适合人群

• AI 代理开发者：需要安全测试代理生成代码
• 开源贡献者：审查 PR 中不可信依赖或构建脚本
• 安全研究员：逆向分析可疑 npm/pypi 包
• CI/CD 管理员：构建可复现、网络受限的构建环境

最佳实践

# 探索可疑包的标准流程
docker sandbox create --name pkg-review claude .
docker sandbox network proxy pkg-review --policy deny
docker sandbox network proxy pkg-review --allow-host registry.npmjs.org
docker sandbox exec pkg-review npm install -g suspicious-pkg
docker sandbox network log pkg-review  # 检查异常出网
docker sandbox rm pkg-review  # 彻底销毁