Docker Sandboxes

本教程使用本地沙箱。有关云端凭据和第一次云端会话，请参阅 云端沙箱入门。

Docker Sandboxes 在隔离的 microVM 沙箱中运行 AI 编程智能体。每个沙箱都有自己的 Docker 守护进程、文件系统和网络 —— 智能体可以构建容器、安装软件包和修改文件， 而不会访问除你主动共享之外的任何宿主机资源。

本页带你走完第一次会话：在沙箱中运行一个智能体，看看沙箱如何隔离它，控制它 在网络上可以访问的目标，最后完成清理。

前置条件 ​

  • 安装 sbx CLI 并登录 Docker
  • 为你要使用的智能体配置一种身份验证方式。大多数智能体都需要为其模型提供商准备 API 密钥。有关各提供商的具体说明，请参阅智能体页面。

为智能体完成身份验证 ​

如果你使用的是带 Claude 订阅（Max、Team 或 Enterprise）的 Claude Code，则无需 任何预先配置 —— 在沙箱内使用 /login 命令通过 OAuth 登录即可。会话令牌保存在你的 宿主机上，绝不会存储在沙箱内部。

如果你更愿意使用 API 密钥，请参阅凭据，了解如何用 sbx secret set 存储密钥。

如需让智能体访问 GitHub 以创建 pull request 或与仓库交互：

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

运行你的第一个沙箱 ​

选择一个项目目录，使用 sbx run 启动一个智能体：

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

在交互式终端中，如果全局网络策略尚未初始化，CLI 会提示你选择一个预设。选择 Balanced 可以允许访问常见的开发服务，同时阻止其他目标，除非你批准它们。如果 已经配置了策略，CLI 会直接使用它，不再提示。

如需在不经过交互式提示的情况下初始化策略，请在 sbx run 之前运行 sbx policy init balanced。有关可用预设以及如何更改现有策略，请参阅 从预设开始。

把 claude 替换成你想使用的智能体 —— 完整列表见智能体。

第一次运行会因为拉取智能体镜像而稍慢一些。之后的运行会复用缓存的镜像，几秒即可 启动。

这会将你接入运行在沙箱内的智能体。给它一个真正的任务 —— 让它添加一个功能、安装 一个依赖，或者构建并运行你的项目。智能体拥有完整的 Linux 环境和自己的 Docker 守护进程，因此它可以在工作过程中自行安装软件包、构建镜像和启动容器。

看看智能体能触及什么 ​

在另一个终端中列出你的沙箱：

console
$ sbx ls
SANDBOX      AGENT    STATUS      PORTS   WORKSPACE      CREATED
my-sandbox   claude   ● running           ~/my-project   2m

每一行显示沙箱的名称、智能体、状态、已发布端口、工作区 和创建时长。工作区就是共享进沙箱的宿主机目录，也是你的机器上智能体唯一能看到 的部分。

当你在项目目录中运行 sbx run 而没有传入工作区路径时，当前目录会以读写方式 挂载。智能体和你宿主机看到的是同一批文件。智能体对你的项目所做的修改会随着它 的写入实时出现在你的工作树中，你在提交前可以像查看普通的 Git diff 那样审查它们。

其余一切都运行在 microVM 内部，与你的宿主机隔离：

  • 智能体拥有自己的文件系统、Docker 守护进程和网络。
  • 它安装的软件包、拉取的镜像、启动的容器都留在沙箱内部。你的宿主机系统不受影响， 删除沙箱时它们会被一并丢弃。

如果你希望智能体完全不接触你的工作树 —— 例如在同一个仓库上同时运行多个智能体 时 —— 请使用克隆模式，它会为智能体提供一份私有克隆。

控制智能体可以访问的目标 ​

隔离不只是文件系统层面的。你还可以控制沙箱在网络上能够访问的目标，并且随时可以 查看或调整当前生效的策略。

查看当前生效的规则：

console
$ sbx policy ls

允许访问特定主机：

console
$ sbx policy allow network registry.npmjs.org

使用 Balanced 时，常见的开发服务默认是允许的。使用 Locked Down 时，目标 需要你或 Kit 提供允许规则才会放行。内置智能体 Kit 可以为其模型提供商添加规则。 完整的规则集合以及自定义方法请参阅本地策略。

清理 ​

智能体退出后沙箱依然保留，因此你可以把沙箱停掉，之后再从断点继续：

console
$ sbx stop my-sandbox

已安装的软件包、Docker 镜像和配置变更在重启后都会保留。当某个沙箱不再需要时， 将其删除以回收磁盘空间：

console
$ sbx rm my-sandbox

删除沙箱会删除其中的全部内容 —— 已安装的软件包、Docker 镜像，以及你使用过克隆 模式时在沙箱内创建的 Git 克隆。你宿主机工作树中的文件不受影响。

接下来做什么 ​

你已经运行过智能体，看过沙箱如何隔离它，也控制了它的网络访问。接下来可以从几个 方向继续。

不带任何参数运行 sbx 即可打开交互式仪表板：它可以实时查看每个沙箱，并让你在 同一个地方接入智能体、打开 shell 和管理网络规则。

交互式仪表板，显示沙箱状态、资源使用情况和网络治理控件。

然后可以继续探索：

  • 使用指南 —— 基本命令、重新连接、工作区和端口发布。
  • 工作流模式 —— Git 策略、本地服务、CI 和需要认证的工具。
  • 沙箱环境文件 —— 用 sbxenv.yaml 声明并共享 可复用的本地沙箱配置。
  • 使用 Kit 定制 —— 把智能体、它的工具和它的网络规则打包成一份可复用 的定义，用单个标志即可启动。
  • 智能体 —— 受支持智能体的完整列表以及各自的配置方式。
  • 沙箱治理 —— 在团队范围内集中管理网络、文件系统和 MCP 策略。