构建一个 Kit，为团队提供可重复使用的沙箱环境。你可以打包一个智能体，添加一个能与不同智能体搭配使用的工具，或者把已有的 Kit 合并成团队可运行的单个 Kit。本节中的各个指南会逐一讲解这些做法。

NOTE

请把 v3 工作负载和 v3 Mixin 一起选择。 claude 和 codex 这样的内置快捷方式使用 v3，并接受 v3 Mixin。请参阅 版本兼容性。

选择编写方式

• 编写 Kit 集合：合并你已发布或从镜像仓库选出的 Kit。集合还可以添加网络访问、安装命令和智能体说明，并让用户选择诸如使用哪个模型之类的设置。
• 构建工具 Mixin：把一个可复用的工具连同它的网络访问和凭据一起打包。
• 构建智能体工作负载：控制基础环境、智能体安装和启动命令。你也可以使用已有的智能体镜像。
• 调试 Kit：当其中的安装或启动命令失败时使用。查看进度输出和沙箱内的日志。

要参考完整且可改编的 Kit，请查阅 Docker Sandbox Kit Specification 仓库中的 Kit 示例。

目录与构建布局

把每个 Kit 的源文件放在自己的目录里。一个 Kit 通常从两个文件开始：

• 一个 YAML 描述符，用于标识该 Kit 是工作负载、Mixin 还是集合，并声明它的设置和需求。
• 一个 Dockerfile，用于安装软件并把文件复制进镜像。

用 Kit 的名字作为目录名和描述符名。如果 Kit 有 Dockerfile，就用与描述符相同的文件名主干：my-kit.yaml 对应 my-kit.dockerfile。

例如：

my-kit/
├── my-kit.yaml
├── my-kit.dockerfile
├── context.md
└── files/
    └── settings.json

支撑文件按适合你的 Kit 的方式组织。这个例子把智能体说明放在 context.md，配置文件放在 files/ 下。

这些文件如何配合

Dockerfile 定义镜像里放什么，比如安装的工具和配置文件。对于工作负载，它还设置启动命令。YAML 描述符定义 Kit 的设置和需求，比如网络访问、凭据和智能体说明。

描述符以一行语法声明开头：

# syntax=docker/sandbox-kit:3

这会选择 Kit 构建前端，由它读取描述符及与之匹配的 Dockerfile。构建产出一个容器镜像，包含软件、支撑文件和校验过的描述符。

Kit 集合用描述符的 kits: 列表合并已发布的 Kit。

构建并使用 Kit

用 Docker Buildx 构建时，把 YAML 描述符传给 -f，把源目录作为构建上下文：

$ docker buildx build -f my-kit/my-kit.yaml -t my-kit:dev my-kit/

你也可以给 sbx 一个本地 Kit 目录的引用。它会在创建沙箱时构建该 Kit。把镜像发布到镜像仓库之后，就可以改用它的镜像引用。

构建选项和发布说明请参阅 构建并分发 Kit。

其他源文件布局

描述符和 Dockerfile 分开存放只是组织 Kit 的一种方式。你也可以在 build: | 下内联写一个 Dockerfile，用 dockerfile: 选择一个，或者把描述符嵌在 Dockerfile 的注释里。

语法请参阅 编写形式。

能力

安装一个工具往往只是工作的一部分。这个工具可能还需要访问某个 API、用某个凭据完成身份验证，或者在智能体启动前运行一条安装命令。在描述符的 capabilities 列表中描述这些需求。每一项都要求 Docker Sandboxes 提供某项功能。

Kit 的 Dockerfile 定义它的镜像如何构建。它的能力则描述 Docker Sandboxes 在准备和运行沙箱时需要做什么。例如，一个工具 Mixin 可以通过自己的 Dockerfile 安装 API 客户端，并用一项网络能力来申请访问该 API。只用 Docker 构建或运行镜像并不会应用这些能力设置。

你可以给工作负载、Mixin 或集合添加能力。把每项申请与需要它的 Kit 放在一起，这样工具的访问规则在它与其他智能体一起使用时仍然跟随它。

每个能力条目在 type 中标识功能。需要设置的能力在 config 中给出设置。例如，com.docker.sandbox/network-policy@1 申请网络访问，它的 config 列出允许的域名。

@1 标识能力的版本。它与 Kit 格式版本和 sbx 版本无关。 上游能力定义描述了可用的能力及其设置。

本地与云端可用性、最低 sbx 版本以及 Docker 特有的限制，请参阅 能力支持。

这里的指南讲解如何配合 Docker Sandboxes 使用能力。全部描述符字段以及 Kit 的合并规则，请参阅 上游 v3 规范。

选择安装阶段的执行时机

在构建镜像时安装工具并复制静态文件，这样每个沙箱都能复用它们。有些安装步骤必须等到沙箱创建之后才能执行。例如，一个 Mixin 可以带上 CA 证书，但它需要工作负载的工具来注册该证书。用生命周期能力在合适的时机运行命令或生成文件：

放在哪里	在 sbx 中的执行时机	示例
Dockerfile 的 RUN 和 COPY	构建镜像时	安装一个工具并复制它的默认配置
生命周期 install 钩子	创建沙箱时执行一次，在智能体启动之前	注册 CA 或填充已挂载的目录
生命周期 files	创建期间，在 install 钩子之后、智能体启动之前	根据 Kit 参数生成设置
生命周期 startup 钩子	每次沙箱启动时，与智能体并行	启动后台服务或在重启后刷新状态

生命周期钩子是在沙箱创建或启动期间运行的命令。startup 钩子要保证可以安全地重复执行。在 sbx 中，它们与智能体并行运行，所以智能体可能在它们结束之前就开始了。如果某条命令必须在每次智能体启动前完成，就把它放进工作负载的 entrypoint。

向钩子传递环境变量

在 sbx 中，install 钩子只能拿到有限的一组环境变量：基本的进程变量、代理设置和证书路径。如果你的命令还需要别的变量，在钩子的 env 列表中写明。例如，env: [WORKSPACE_DIR] 会把已挂载工作区的路径传给命令。在 sbx 中，startup 钩子拿到的是沙箱的完整环境，没有这层过滤。

沙箱容器把 SBX_AGENT 设为已配置的智能体名，例如 claude 或 codex。对于来自镜像仓库的 v3 工作负载，该值是 Kit 仓库名的最后一段。例如，sbx run --name foo docker.io/me/my-custom-kit 会把 SBX_AGENT 设为 my-custom-kit。--name 标志用于命名沙箱，不会改变 SBX_AGENT。

在需要针对不同智能体采取不同行为的钩子或脚本中使用 SBX_AGENT。把 SBX_AGENT 加到 install 钩子的 env 列表中，就能把它提供给该钩子。startup 钩子无需声明即可获得它。

安装示例请参阅 Kit 编写模式， 字段定义请参阅上游的 生命周期定义。

生成的文件

在生命周期 files 的内容中，写 ${{ kit.env.NAME }} 可以插入容器环境变量。例如，写 ${{ kit.env.WORKSPACE_DIR }} 来表示工作区路径。普通写法 $VAR 和 ${VAR} 会原样写入，不会替换成对应的值。在钩子命令中，请改用 $WORKSPACE_DIR 这类 shell 语法。

Docker Sandboxes 在创建沙箱时替换一次 ${{ kit.env.NAME }}。kit.env 读取的是最终的容器环境，与钩子的 env 列表无关。

设置工作负载的计算资源

在描述符中用 resources@1 能力设置工作负载默认的 CPU 和内存分配。使用整数个 CPU 核心。任何运行该 Kit 的人都可以在创建沙箱时用 --cpus 和 --memory 覆盖这些默认值。

把这些设置放在工作负载上。sbx 会忽略单独添加的 Mixin 上的资源设置，也不会用该能力的 gpu 字段来选择 GPU。

会话结束后保持沙箱运行

默认情况下，本地沙箱在最后一个会话断开后不久会自动停止。运行某个服务的 Kit，比如在已发布端口上的开发服务器，可以改为请求沙箱保持运行。声明 long-running@1 能力，它不需要 config：

capabilities:
  - type: com.docker.sandbox/long-running@1

使用该 Kit 创建的沙箱，其行为与用 sbx run --detach 启动的沙箱相同：它会一直运行，直到有人停止或删除它，包括你 attach 之后断开的情况。当工作负载、Mixin 或集合声明了该能力时，它作用于整个沙箱。

声明该能力的 Kit 只在运行时能够提供它的环境中运行。如果该 Kit 在沙箱随会话结束而停止的情况下也能工作，就在这个条目上设置 optional: true。这样无法提供该能力的运行时会跳过它，而不是拒绝该 Kit。在 sbx 中，有两种情况无法提供它：

• 云沙箱无法提供该能力。sbx --cloud 会拒绝需要它的 Kit，并跳过可选条目。
• sbx kit add 无法把该能力应用到正在运行的沙箱。要应用它，请用该 Kit 创建沙箱。