Docker Sandboxes

Kit 让你按照自己的工作方式搭建沙箱。使用自定义基础镜像，添加项目需要的工具，并为智能体提供使用这些工具的说明。你还可以控制沙箱能访问哪些服务、如何进行身份验证，以及沙箱启动时运行什么。

一个 Kit 既可以定义完整的环境，也可以为已有环境补充内容，比如一套工具链或团队共享的配置。把这些选择打包一次，就能跨项目复用，并与团队共享。

如果要把沙箱的配置保存在一个可编辑、可共享的文件里，请使用 沙箱环境文件。它在指定工作区路径、资源和凭据的同时，还会选择 Kit。把工具的依赖放在它所属的 Kit 里，这样这些依赖就能跟着工具在各环境之间迁移。搭建沙箱时的各种选择都用环境文件来管理。

Docker 推荐使用 v3 Kit。本节讲的是 v3。仍受支持的 v2 格式请参见 Kits v2。

什么是 Kit？ ​

Kit 把软件和配置打包进沙箱。一个 YAML 文件（称为描述符）告诉 Docker Sandboxes 这个 Kit 需要什么：网络访问、凭据、安装命令，或者给智能体的说明。你把 Kit 发布为一个容器镜像，其中包含它的文件和描述符。

你通过容器镜像引用来标识一个已发布的 Kit，例如 docker.io/docker/sbx-kit-claude:2.1.267。使用这个 Kit 时，sbx 会准备它的文件并应用它的设置。你既可以用一个 Kit 提供完整环境，也可以组合多个各自贡献不同部分的 Kit。

Kit 能做什么 ​

用 Kit 可以：

  • 打包一个自定义智能体，或者为团队项目配置已有智能体。
  • 包含智能体需要的工具，比如 linter、语言运行时、测试运行器和编译器。
  • 共享 linter 规则、编辑器设置、辅助脚本和参考资料，并为智能体提供使用它们的说明和技能。
  • 通过网络规则和凭据把智能体连接到服务，包括内部 API 和私有包镜像仓库。
  • 在沙箱启动时初始化它并运行配套服务，比如用于预览智能体工作成果的开发服务器。

工作负载和 Mixin ​

Kit 在沙箱中有两种角色：工作负载（workload）提供基础环境和启动命令，Mixin 则往其中添加工具或行为。

类型提供什么怎么用
workload要运行的环境和命令，比如一个智能体或 shell传给 sbx run 或 sbx create
mixin额外的工具、配置或运行时行为用 --kit 添加

例如，下面的命令用一个 Mixin 运行一个工作负载：

console
$ sbx run docker.io/docker/sbx-kit-claude:2.1.267 --kit docker.io/sbx/playwright:1.61.1

Claude Code 工作负载启动智能体，Playwright Mixin 添加浏览器测试工具。

Kit 集合 ​

Kit 集合把多个 Kit 合并成一个可以发布和复用的 Kit。用它把工作负载和你需要的 Mixin 打包在一起，这样你和团队只需一个引用就能运行这个环境。

集合指定要合并哪些 Kit 以及各自的版本。它还可以为合并后的环境添加安装命令、智能体说明、网络访问和其他设置。

如果集合中包含工作负载，用 sbx run 运行发布后的 Kit。如果只包含 Mixin，用 --kit 把它加到工作负载上。

环境文件既可以选择单个 Kit，也可以选择一个已发布的集合。当你想要一个固定组件列表的发布引用时，就选集合。构建集合时会记录这些组件的镜像 digest。

关于如何运行 Kit 和添加 Mixin，请参阅 使用 Kit。要定制并发布自己的组合，请参阅 编写 Kit 集合。

版本兼容性 ​

V3 需要 sbx v0.45 或更高版本。v3 沙箱中的每个 Kit 都必须是 v3：选择一个 v3 工作负载，并且只添加 v3 Mixin。

像 claude 和 codex 这样的内置智能体名对应的是 v3 Kit，可以直接添加 v3 Mixin，例如 sbx run claude --kit ./some-v3-mixin。v1 和 v2 Kit 不能与 v3 Kit 组合。

Kit 的能力可能要求更新的版本或本地沙箱。详情请参阅 Kit 能力支持。V2 仍受支持，也没有被废弃。

选择下一步 ​

  • 使用 Kit：运行已发布的环境，或把工作负载和 Mixin 组合起来。
  • 编写 Kit：搭建智能体环境、打包工具，或把 Kit 合并成集合与团队共享。
  • 浏览 sandbox-kit-spec 仓库，查看权威的 v3 规范、构建前端和示例。

若要保存你在沙箱内配置好的环境，请参阅 把沙箱保存为模板。