给编码代理一个 Docker 沙箱

编码代理想开 --dangerously-skip-permissions（或各家自己的 YOLO 模式），你又不太想让它直接摸本机。Docker Sandboxes 干的就是这件事：每个代理进一台轻量 microVM，自己的内核、自己的 Docker daemon、自己的网络。装包、起容器、改配置，都关在沙箱里。

sbx CLI 本身免费，个人和商用都能用。只有组织级治理（统一管网络、文件系统、MCP）才要另付订阅。

先分清两套命令

网上还常见这种写法：

docker sandbox run claude ~/my-project

这是当年嵌在 Docker Desktop 里的入口。官方已经弃用，改成独立的 sbx CLI，也不再依赖 Desktop。新装请走 sbx；旧命令能跑的话，尽快迁过去，功能只维护在 sbx 上。

产品页：https://www.docker.com/products/docker-sandboxes/ 文档：https://docs.docker.com/ai/sandboxes/

装 sbx

不需要本机先装 Docker Engine。macOS 要 Sonoma 14+ 和 Apple Silicon；Windows 11 要打开 Windows Hypervisor Platform；Ubuntu 24.04+ 要开着 KVM，用户进 kvm 组。

macOS：

brew trust docker/tap
brew install docker/tap/sbx

Windows：

winget install -h Docker.sbx

Ubuntu（只装 sbx，不装 Engine）：

curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh
sudo apt install docker-sbx

装完登录：

sbx login

会打开浏览器走 Docker OAuth。无浏览器的 CI 场景看文档里的 headless 说明。

跑第一个沙箱

进项目目录：

cd ~/my-project
sbx run --name my-sandbox claude

第一次会让你选全局网络策略，对现有和以后的沙箱都生效，之后用 sbx policy allow/deny/rm 改：

1. Open：不限制出站
2. Balanced：默认拒绝，放行常见开发站点（建议先选这个）
3. Locked Down：全拦，自己一条条放

首次会拉代理镜像，慢一点。之后复用缓存，几秒就能起来。你会被接到沙箱里的代理会话，可以直接给它任务：加功能、装依赖、build、起服务。沙箱里有完整 Linux 和私有 Docker daemon，docker build / docker compose up 都走沙箱内引擎，不碰本机 Docker socket。

换代理就把 claude 换成对应名字。官方开箱支持 Claude Code、Codex、Copilot、Cursor、Docker Agent、Droid、Gemini、Kiro、OpenCode，以及一个没代理的 shell，方便你自己装环境。

Claude Code 如果用的是订阅（Max / Team / Enterprise），进沙箱后 /login 做 OAuth 就行，会话 token 留在宿主机，不会写进 VM。更想用 API key 时：

sbx secret set anthropic

要让代理去 GitHub 提 PR：

sbx secret set github --command 'gh auth token'

密钥走宿主机侧代理注入，默认不会以环境变量或文件的形式出现在沙箱里。

代理实际能碰到什么

另开一个终端：

sbx ls

能看到名字、代理、状态、端口、工作区。工作区是本机唯一默认暴露给代理的部分。

默认是 direct 模式：工作区读写挂进去，代理改的文件立刻出现在你本机工作树。提交前按普通 git diff 看就行。但有几处容易漏：

• .git/hooks 不会出现在 git diff 里，要单独看
• Makefile、package.json scripts、CI 配置、IDE 任务、AI 项目配置，代理都能改
• 改完的代码先审再跑，尤其是会隐式执行的那些文件

不想让代理直接改工作树（比如同一仓库并行跑几个代理），用 clone 模式：

sbx run --clone claude

仓库只读挂进 VM，代理在沙箱里改一份私有 clone。改动要你 fetch / 代理 push 才会回到本机。源码只读副本在 /run/sandbox/source。clone 模式创建时定死，想换只能删了重建。主工作区必须是 Git 仓库，也不能从非主 worktree 里开。删沙箱会丢掉里面的 clone，要留的提交先 fetch 或 push。

沙箱里装的包、拉的镜像、起的容器，都只活在这台 microVM。删沙箱就没了，本机工作树不受影响。

网络别只靠默认

隔离不只是文件系统。出站流量走宿主机上的过滤代理，拦本机 localhost，也能注入认证头，这样沙箱拿不到真实密钥。

看当前规则：

sbx policy ls

放行某个主机：

sbx policy allow network registry.npmjs.org

Locked Down 下，连模型供应商 API 也要自己放。Balanced 会放行常见开发站点。组织开了治理之后，本地 allow 不能再放宽组织策略，只能再收紧。

沙箱默认出不去本机浏览器。开发服务器要映射端口：

sbx run --publish 8080:3000 --name my-sandbox claude

已经在跑的沙箱用：

sbx ports my-sandbox --publish 8080:3000

日常几个命令

sbx run claude ~/my-project     # 同路径再次执行会重连，不会新建
sbx run --name feature claude   # 同一仓库并行多个沙箱，名字分开
sbx create --name bg claude .   # 后台创建，不立刻 attach
sbx exec -it my-sandbox bash    # 进沙箱开 shell
sbx stop my-sandbox             # 停，包和镜像还在
sbx rm my-sandbox               # 删干净
sbx prune --dry-run             # 预览清掉已停止的沙箱
sbx                             # 无参数打开交互面板

sbx rm 如果还有 attach / SSH / SFTP，要加 --force。停着的沙箱可以 sbx prune 一批清掉，正在跑的不会动。

编辑器可以走 SSH 接到沙箱，VS Code 和 Cursor 官方有集成说明：https://docs.docker.com/ai/sandboxes/integrations/

什么时候值得用

适合这几类场景：

• 想开 YOLO / skip-permissions，又不想代理直接拿本机内核和 Docker socket
• 代理要自己 docker build、起临时服务，但你不想把宿主机 Docker 交给它
• 同一仓库并行几个代理，用 --clone 或不同 --name 隔开工作树
• 团队要统一出站、可挂载路径、MCP 白名单（这个要组织治理订阅）

不适合、或者至少先想清楚的：

• 默认 direct 模式并没有「工作区隔离」。代理改的就是你正在看的那份代码
• microVM 不是零成本。大项目第一次拉镜像、装工具会占磁盘；不用的沙箱记得 rm / prune
• 密钥注入只覆盖官方支持的服务和你显式 secret set 的项。自己 export 进沙箱的变量，代理看得到
• Linux 上没 KVM（或嵌套虚拟化没开）根本起不来

和上一篇讲的 Docker cagent 动态 MCP 不是一件事：那边管的是代理按需挂 MCP 服务器，这边管的是代理本身跑在哪。可以叠着用，但先把沙箱边界想清楚。

装法和完整命令表以官方文档为准：https://docs.docker.com/ai/sandboxes/install/ 、https://docs.docker.com/ai/sandboxes/get-started/ 。问题可以开到 https://github.com/docker/sbx-releases/issues 。