使用 Docker Sandboxes 运行编码智能体

Docker Sandboxes 会在本地 microVM 中运行 Claude Code、Codex、Copilot 或 Cursor 等编码智能体。该 microVM 拥有独立的内核和独立的 Docker 引擎，与宿主机之间仅共享你的项目目录，并且在本地运行完全免费。

如果你曾在一个下午内确认过上百次 ls 和 npm test 的权限提示，你一定很想打开“跳过权限确认”的开关。你大概也会担心，一旦打开这个开关，智能体可能会对你的笔记本电脑做些什么。

本文将介绍沙箱隔离了哪些内容、从安装到首次会话的完整配置过程、如何取回智能体所做的修改、它与其他方案的对比，以及使用成本。该工具尚处于 1.0 之前的阶段，仍在快速迭代。

为什么在笔记本电脑上开启完全自主模式存在风险

处于完全自主模式的编码智能体会在不询问的情况下执行 shell 命令、安装软件包并编辑文件，而且这一切都以你的用户账户身份进行。这意味着你的主目录、SSH 密钥、云服务凭据和本地服务都在它的可及范围之内。一次错误的 rm -rf 或 git reset --hard 就可能抹掉所有未提交的工作。

权限确认提示是常见的防护手段，但它违背了使用智能体的初衷。长时间运行的任务会在每条命令处停下来，而到了第二十次提示时，大多数人都会不看内容直接确认。更好的解决办法不是更加信任智能体，而是把它放到一个无法造成太大破坏的环境中。关于隔离智能体的更全面论述，可参阅安全地以 YOLO 模式运行编码智能体。本文则聚焦于一个具体的工具。

为什么 Docker Sandboxes 使用 microVM 而非容器

普通的 Docker 容器与宿主机共享内核。任何能够访问 Docker socket 的进程都可以启动一个挂载你文件系统的特权容器。Docker 官方的守护进程攻击面文档明确警告：守护进程以 root 身份运行，只应由受信任的用户控制。智能体常常需要使用 Docker，因此挂载 /var/run/docker.sock 这种显而易见的捷径，等于把整台机器交给了它。

根据 Docker 的隔离层文档，每个沙箱都是一个拥有独立 Linux 内核和独立 Docker Engine 的 microVM。智能体可以在沙箱内运行 docker build 和 docker run，无需 Docker-in-Docker 所要求的特权配置，你的宿主机守护进程也完全不会参与其中。

端到端配置 Docker Sandbox

安装 sbx CLI，登录 Docker，为智能体提供模型凭据，然后在项目目录中运行 sbx run。官方教程指出，宿主机既不需要 Docker Desktop，也不需要 Docker Engine。

根据你的操作系统执行相应的安装命令：

# macOS
brew trust docker/tap && brew install docker/tap/sbx

# Windows
winget install Docker.sbx

# Ubuntu: add Docker's apt repo, install, then grant KVM access
curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh
sudo apt-get install docker-sbx
sudo usermod -aG kvm $USER
newgrp kvm

Linux 需要 KVM 支持，且你的用户必须属于 kvm 用户组。Docker 在 Ubuntu 上对 sbx 进行了测试并提供支持。对于其他发行版，sbx-releases 仓库提供了发布文件，但 Docker 不保证这些发行版能正常运行。各平台的前置条件请查阅安装页面。

接下来，启动一个 Claude Code 会话：

sbx login
sbx secret set anthropic        # skip if you use a Claude subscription
cd ~/my-project
sbx run --name my-project claude

• API 密钥： sbx secret set anthropic 会将密钥保存在宿主机上。沙箱代理会将其注入智能体的 API 请求中，因此智能体永远不会接触到原始密钥。如使用 Codex，请运行 sbx secret set openai。如果你已经在 shell 中导出了密钥，sbx secret import --dry-run 会列出 sbx 能够识别的密钥，而 sbx secret import 会在你逐一确认后保存它们。
• 订阅： 无需配置密钥。使用 Claude 时，在沙箱中启动 Claude Code 后输入 /login 即可。使用 Codex 时，sbx 会先在宿主机上完成 OpenAI 登录，然后才创建沙箱。

首次运行时，sbx 会要求你选择默认网络策略。此后，智能体会以完全自主模式启动，Claude Code 不会再请求权限，你也无需传入任何参数。如需使用其他智能体，只需将 claude 替换为 codex、copilot、cursor 或 gemini。

项目文件夹是智能体在你机器上唯一可以写入的地方，而它可以删除其中的任何内容。请在开始前先提交或推送代码。

如何取回智能体的工作成果？

在默认模式下，Docker Sandbox 中智能体所做的编辑会立即出现在宿主机的工作树中。你可以像平常一样审查这些修改：

git diff

一些较早的指南（包括 Docker 的快速入门示例仓库）中介绍了 --branch 参数，它会让智能体在宿主机侧 .sbx/ 目录下的 worktree 中工作。该参数已在 sbx v0.31.0 中被移除，取而代之的是克隆模式。现在传入该参数会返回错误，并提示你改用 --clone。

克隆模式可以让智能体远离你的工作树。正如 Git 工作流文档所述，sbx 会在沙箱内创建一个私有的 Git 克隆，智能体在该副本上工作。在你拉取智能体的分支或智能体推送到远程仓库之前，宿主机上不会发生任何变化。克隆模式只能在创建沙箱时选择，因此请在首次运行时就传入 --clone。已有的沙箱无法在之后切换到该模式。

实际使用中的常见问题

应该选择哪种网络策略？

Docker Sandboxes 提供三种本地网络策略：

• Open：允许所有流量。
• Balanced：默认拒绝流量，但允许常用的开发服务。
• Locked Down：阻止所有未被明确允许的流量。

对于大多数前端工作，建议选择 Balanced。它涵盖了软件包仓库、代码托管平台以及 AI 服务商的 API。如果智能体需要访问不在列表中的站点（例如某个文档网站），可以运行 sbx policy check network <domain> 检查其是否被阻止，然后通过 sbx policy allow network <domain> 放行。运行 sbx policy ls 可以查看现有规则，使用 sbx policy rm 可以删除规则。内置的智能体套件也可以为每个沙箱添加各自的放行规则，即使在 Locked Down 策略下也是如此。

状态会被持久保留吗？

会。智能体安装的工具以及对操作系统所做的任何修改都会保留在沙箱中，直到你将其删除。运行 sbx rm my-project 会清除该环境以及作用域限定在该沙箱的所有密钥。你的全局密钥和项目文件夹则不受影响。

如何重新连接？

要重新连接到现有的 Docker Sandbox，运行 sbx run --name my-project 即可。无需重复指定智能体名称，因为它会从现有沙箱中读取。不带任何参数运行 sbx 会打开一个交互式仪表盘。

Docker Sandboxes 与容器、Devcontainer 和远程虚拟机的对比

每种替代方案都至少在以下三方面之一有所欠缺：内核隔离、安全的 Docker 访问，或内置的出站流量策略。

如果你真正需要的是控制智能体可以调用哪些工具，而不是隔离其运行环境，请参阅面向 AI 智能体的 Docker MCP。

Docker Sandboxes 的局限与成本

本地沙箱可免费运行。根据 v0.45.0 版本说明，云端沙箱目前处于实验阶段，需要有效的 Docker Agentic Platform 订阅。模型推理费用需通过你自己的密钥或订阅支付。运行 sbx login 需要一个 Docker 账户。该产品仍处于早期阶段，定价和命令参数都可能发生变化。

• 项目目录完全可写，因此未提交的工作不受保护。
• 智能体推送的任何内容，或发送到已放行域名的任何数据，都会离开沙箱。
• 可通过 --memory 和 --cpus 设置资源。在本地，内存默认为宿主机 RAM 的一半，上限为 32 GiB。文档中所述的 2 个 CPU 和 4 GiB 的默认值适用于云端沙箱。
• SSH 提交签名通过 SSH-agent 转发实现，当宿主机上设置了 SSH_AUTH_SOCK 时默认启用。但你仍需在沙箱内配置 Git，使其使用转发的密钥进行签名。
• Andrew Lock 在 2026 年 4 月反馈，即使是简单的项目，在沙箱中运行也会明显变慢。

总结

Docker Sandboxes 为编码智能体提供了独立的内核、独立的 Docker 引擎以及受策略管控的网络，而它唯一能接触到的只有你的项目文件夹。要开始使用，请先提交你的工作，安装 sbx，选择 Balanced 策略，然后在一个即使丢失也无妨的仓库中运行 sbx run --name my-project claude。如果你希望在审查之前让智能体的修改不进入工作树，可以改用克隆模式。

常见问题

如何访问智能体在 Docker Sandbox 内启动的开发服务器？

使用 sbx ports 发布其端口。运行 sbx ports my-project --publish 3000:8080 会将宿主机的 3000 端口映射到沙箱的 8080 端口，而单独使用 --publish 8080 则会自动选择一个临时的宿主机端口。在完成这一步之前，浏览器无法访问沙箱内的服务。此外，开发服务器必须绑定到 0.0.0.0 而不是 127.0.0.1，因此许多框架需要添加 --host 0.0.0.0 参数。

能否让智能体读取其他目录但无法修改它们？

可以。在主工作区之后添加额外路径，并在每个路径末尾加上 :ro 使其只读，例如 sbx run claude ~/project-a ~/shared-libs:ro ~/docs:ro。智能体会从第一个路径启动。每个工作区在沙箱内的绝对路径与其在宿主机上的路径相同。即使主工作区使用克隆模式，额外的工作区也会直接从宿主机挂载。

如何从克隆模式的沙箱中取出提交？

从 sbx 添加到宿主机仓库中的 Git 远程仓库拉取即可，该远程仓库的名称为 sandbox- 加上沙箱名称。之后就可以像对待任何远程仓库一样进行 diff 或合并。克隆所用的 Git 服务器位于沙箱内部，因此沙箱停止运行时 git fetch 会失败。sbx rm 也会删除该远程仓库，所以请在删除沙箱之前拉取或推送所有需要保留的内容。