Docker Sandboxes

Kit 集合让你的团队只需运行一个 Kit，其中就包含你选定的工具和版本。你列出要包含的 Kit，添加合并后环境需要的任何设置，然后发布结果。集合还可以运行安装命令、提供智能体说明，并提供诸如使用哪个模型之类的选择。

当你想分享一组 Kit 的组合，并在一处集中管理它的设置时，就用集合。组件可以是你团队发布的 Kit，也可以来自其他发布者。发布集合时，你需要 Docker Buildx 和一个可以推送的镜像仓库命名空间。

选择组件 ​

一个集合可以包含一个工作负载和任意数量的 Mixin。二者共同提供一个完整的沙箱环境。你也可以只做由 Mixin 组成的集合，用来分享用户用 --kit 加到工作负载上的工具和设置。

选择能互相配合的 v3 Kit。例如，你可以把一个智能体工作负载与一个 linter Mixin，以及一个添加你团队配置的 Mixin 组合起来。要打包自己的工具，请参阅 构建工具 Mixin。

在编写集合之前，可以先用 sbx run 和 --kit 试试工作负载与 Mixin 的组合。请参阅 添加 Mixin。 如果一个 Kit 依赖另一个，Docker Sandboxes 会先应用依赖项。调整 --kit 标志或集合中条目的顺序，并不会改变这个顺序。

编写集合描述符 ​

集合描述符使用 kind: set，并在 kits: 下列出它的组件。例如，这个描述符把 Docker 的 Codex 工作负载与一个 Mixin 组合起来：

yaml
# syntax=docker/sandbox-kit:3
schemaVersion: "3"
kind: set
displayName: Codex with tools
version: "1.0.0"

kits:
  - ref: docker.io/docker/sbx-kit-codex:0.155.1
  - ref: <MIXIN_REFERENCE>

把 <MIXIN_REFERENCE> 换成一个已发布 v3 Mixin 的完整镜像引用。换一个工作负载引用即可换用其他智能体或环境。组件自带各自的网络规则和凭据申请，因此集合不必重复声明它们。

集合从 kits: 列表获取软件和文件。它没有 Dockerfile，也没有 dockerfile: 字段或 build: 块。要加入更多软件或静态文件，把它们打包进一个工作负载或 Mixin，发布该 Kit，再把它加进列表。

每个 ref 都必须是已发布的镜像仓库引用。即使从本地源码构建集合，本地路径和 Git URL 也不能作为组件。

为集合添加运行时访问 ​

你可以让合并后的环境访问其组件之外的更多服务。例如，要让智能体从内部镜像仓库下载软件包，就给集合的描述符添加下面这项网络能力：

yaml
capabilities:
  - type: com.docker.sandbox/network-policy@1
    config:
      runtime:
        allow:
          - packages.company.example:443

把示例域名换成你镜像仓库的主机名。只要沙箱的策略允许，这条规则就生效。如果镜像仓库还需要身份验证，请添加凭据申请。请参阅 Kit 声明的服务。

把工具所需的访问权限留在该工具所属的 Kit 里，这样它与其他工作负载一起使用时，访问规则仍然跟随它。合并后环境共享的设置，比如对你团队包镜像仓库的访问，则放在集合上。你也可以在集合上添加安装命令、生成配置文件、提供说明以及定义参数。

构建并发布集合 ​

发布之前，先检查组件之间的文件冲突。

把集合的描述符传给 Docker Buildx 来构建并发布。对于位于 codex-tools/codex-tools.yaml 的描述符：

console
$ docker login
$ docker buildx build ./codex-tools -f ./codex-tools/codex-tools.yaml \
    -t docker.io/<NAMESPACE>/codex-tools:1.0.0 --push

把路径换成你集合的源目录和描述符，把 <NAMESPACE> 换成你可以推送的 Docker Hub 命名空间。

构建会拉取列出的 Kit，检查它们声明的需求，并合并它们各自的文件和设置。如果缺少依赖项、两个 Kit 在 provides 中声明了相同的功能，或者有多个 Kit 是工作负载，构建就会失败。

包含工作负载的集合发布为 kind: workload。只含 Mixin 的集合发布为 kind: mixin。你的团队可以像使用其他工作负载或 Mixin 一样使用结果。发布的 Kit 会在 kits: 中记录每个组件的确切镜像 digest。只有源描述符使用 kind: set。

运行集合 ​

运行包含工作负载的已发布集合时，把它的镜像引用传给 sbx run，就像对待单个工作负载一样：

console
$ sbx run <SET_REFERENCE> --name my-project

沙箱中包含该工作负载，以及集合中打包的所有 Mixin。你不需要再用 --kit 单独列出那些 Mixin。

对于只含 Mixin 的集合，用 --kit 把它加到工作负载上：

console
$ sbx run <WORKLOAD_REFERENCE> --kit <SET_REFERENCE> --name my-project

身份验证取决于集合中的 Kit。查阅它们的文档了解所需的凭据，把这些凭据存在宿主机上，并在提示时批准访问。身份验证选项和准备无人值守运行的方式，请参阅 凭据配置。

要控制智能体的基础镜像或启动命令，请参阅 构建智能体工作负载。

配置组件参数 ​

你可以让团队修改某个设置，而不必改变包含哪些 Kit。例如，他们可能需要在使用你选定的 linter 版本时，选择 linter 是检查文件还是修复文件。

集合决定用户可以修改哪些组件参数。你可以在发布集合时固定某个参数的值，也可以把它作为集合上的参数暴露出来，让用户在创建沙箱时选择取值。

在描述符中改动参数定义之后，重新构建并发布集合。

固定参数值 ​

假设你有一个 linter Kit，其中 mode 参数通常由用户在创建沙箱时设置。把它加入集合，并把值固定为 check：

yaml
kits:
  - ref: docker.io/my-org/linter-kit:1.0.0
    args:
      mode: check

这段摘录在你发布集合时把 linter 的 mode 固定为 check。请换成你的 linter 镜像引用和参数名。集合中的其他组件可以有自己的参数值。

让用户选择取值 ​

要让用户在创建沙箱时选择模式，在集合上定义一个参数，并把它的值传给 linter：

yaml
args:
  lint_mode:
    default: check
    enum: [check, fix]

kits:
  - ref: docker.io/my-org/linter-kit:1.0.0
    args:
      mode: ${{ kit.args.lint_mode }}

这个示例假定 linter 定义的 mode 拥有相同的默认值和可选值。集合必须保留这些约束。这样用户运行已发布的集合时就能传入 --kit-arg lint_mode=fix。他们只能修改在集合上定义的参数，不能修改组件上的其他参数。参数规则请参阅 集合合并规则。

修改构建参数 ​

用于构建组件的参数，比如要安装的工具版本，固定在其已发布的镜像中。要修改它，请重新构建并发布该组件，然后更新集合中它的引用。

检查并更新组合 ​

检查文件冲突 ​

分享集合之前，检查它的组件能否配合使用。为每个组件的文件分配各自独立的路径：如果两个组件包含同一个路径，后一个镜像层中的文件会替换先前的文件。构建按 Kit 依赖关系对层排序，因此调整 kits: 的顺序并不能决定哪个文件胜出。检查构建出的镜像，确认没有意料之外的替换。如果你改用 --kit 组合 Kit，Docker Sandboxes 会在创建沙箱时拒绝发生冲突的文件。

检查合并后的设置 ​

集合包含每个组件的网络规则和智能体说明。生命周期钩子按依赖顺序执行，但 startup 钩子与智能体并行运行。智能体可能在这些钩子结束之前就开始了。

必须在沙箱创建期间完成的安装步骤，请用 install 钩子。必须在每次智能体启动前完成的安装步骤，请用工作负载的 entrypoint。

工作负载决定说明文件名。如果你在集合上用 agent-context 能力添加说明，就不要指定文件名。

更新组件 ​

修改组件的引用，重新构建集合，并发布另一个版本。再创建一个沙箱来试用更新后的集合。已有沙箱会保留创建时所用的 Kit 配置。

已发布的集合会保留构建时所用的文件和设置，即使某个组件的标签后来指向了另一个镜像。要在重新构建时使用相同的这些镜像，请在源描述符中每个 ref 旁边加上 digest。

签名和多平台构建请参阅 构建并分发 Kit。