Docker Sandboxes

如果你运行过 sbx run claude 或 sbx run codex，那你已经用过 Kit 了。内置智能体就是打包了环境、工具和运行时设置的 Kit。你自己构建的 Kit，或者从其他发布者那里拿到的 Kit，用法完全一样：给 sbx 一个引用，Docker Sandboxes 就会准备环境并应用该 Kit 的设置。

claude、codex 这类内置智能体引用使用 v3 Kit。V2 对已有的 Kit 仍受支持。

运行 Kit ​

像 claude 和 codex 这样的内置名称会解析到 Docker Hub 上发布在 docker.io/sbx/<NAME>:latest 下的 Kit。例如，codex 解析为 docker.io/sbx/codex:latest。这些引用与下面列出的带版本号的 v3 工作负载不同。

要运行其他 Kit，把智能体名换成该 Kit 的引用即可。例如，运行 Docker 发布的 v3 Codex 工作负载：

console
$ sbx run docker.io/docker/sbx-kit-codex:0.155.1 --name codex-v3-kit

已发布的 v3 工作负载 ​

内置快捷方式可以通过 sbx run 或 sbx create 接受 v3 Mixin。你也可以从下面这些带版本号的工作负载中选择一个，以固定智能体版本。

工作负载的智能体名来自其仓库名的最后一段。例如，docker/sbx-kit-claude 注册为 sbx-kit-claude。更改沙箱的 --name 不会改变智能体名。

内置智能体V3 工作负载 OCI 引用
claudedocker.io/docker/sbx-kit-claude:2.1.267
codexdocker.io/docker/sbx-kit-codex:0.155.1
copilotdocker.io/docker/sbx-kit-copilot:1.0.86
cursordocker.io/docker/sbx-kit-cursor:2026.09.18-9a7762b
devindocker.io/docker/sbx-kit-devin:3000.10.31
docker-agentdocker.io/docker/sbx-kit-docker-agent:1.141.0
droiddocker.io/docker/sbx-kit-droid:0.223.0
kirodocker.io/docker/sbx-kit-kiro:1.0.0
opencodedocker.io/docker/sbx-kit-opencode:1.18.31
shelldocker.io/docker/sbx-kit-shell:1.0.0

对于沙箱环境文件，在 kits 下写出工作负载引用，并把 agent 设为其仓库名，例如 sbx-kit-claude。

已发布的 sbx/* Mixin，例如 sbx/playwright 和 sbx/codex-mixin，可以与这些工作负载组合使用。它们的源码位于 docker/sbx-kits-contrib 的 v3 分支。更多源码示例请参阅 sandbox-kit-spec。

用版本标签选择某个 Kit 版本，用 digest 标识确切内容。latest 标签可能指向需要更新 sbx 版本的 Kit。V3 格式从 v0.45 开始支持，但 Kit 的能力可能要求更高版本或本地沙箱。选择 Kit 前，请查阅Kit 能力支持和发布者提出的要求。

选择 Kit 来源 ​

前面的示例用的是 Docker Hub 上的已发布镜像。你也可以从本地目录或 Git 仓库运行 Kit。用 --kit 添加的 Mixin 支持相同的来源类型：

来源示例引用
已发布的镜像docker.io/my-org/agent-kit:1.0.0
本地目录./my-agent
Git 仓库git+https://github.com/<ORG>/<REPOSITORY>.git#ref=<COMMIT>&dir=my-agent

对于 Git 来源，ref 选择某个修订版本，dir 选择 Kit 的子目录。Git URL 里可能含有 &，在 shell 命令中要加引号：

console
$ sbx run "git+https://github.com/<ORG>/<REPOSITORY>.git#ref=<COMMIT>&dir=my-agent"

创建沙箱时，sbx 会拉取已发布的镜像，并构建本地或 Git 来源。源文件内容未变且 Kit 参数不变时，只要构建结果仍然可用，就会复用缓存结果。

长时间没有引用的未使用的源 Kit 构建镜像，七天后可以被自动清理。被已有沙箱或已保存模板引用的镜像会保留。之后再次使用时，被回收的构建可能需要恢复或重新构建，即使它的源文件和参数没有变化。

默认情况下，远程 Kit 来源仅限于 Docker Hub。要使用 Git 来源或其他镜像仓库，请参阅限制 Kit 来源。对于私有镜像，请参阅镜像仓库凭据。

复用沙箱 ​

沙箱会保留创建时所用的 Kit 配置。要回到上一个示例中的沙箱，指定它的名称：

console
$ sbx run --name codex-v3-kit

你不需要再次指定 Kit 引用。要换用其他工作负载、Mixin 组合或参数值，请用不同的名称创建沙箱，或者重新创建已有的沙箱。要给已有沙箱添加 Mixin，请参阅添加 Mixin。

运行时访问和说明 ​

Kit 可以申请访问它需要的服务。例如，Codex 工作负载需要访问 OpenAI 并完成身份验证。如果你使用 API 密钥，把它存在宿主机上，然后批准该 Kit 使用它的请求。这是两个独立的步骤：存储密钥并不等于授权第三方 Kit 使用它。准备无人值守运行时，请参阅凭据绑定。

查阅 Kit 的文档，确认它会连接哪些服务、需要哪些凭据，以及启动时运行哪些命令。对于由代理管理的凭据，Kit 的凭据绑定会告诉代理该把哪个凭据加到发往该服务的请求上。批准绑定后，代理会把凭据加到出站请求中。凭据的值留在宿主机上，不会暴露在沙箱内部。

网络请求还必须满足你沙箱的网络策略。Kit 的允许规则不能授予超出你组织策略的访问权限。如果连接失败，查看策略日志，确认是哪条规则拦截了它。

Kit 还可以给智能体提供使用其工具的说明。这些说明保存在沙箱内的上下文文件里。随 Kit 打包的文件位于 /usr/share/sandbox/kit/ 下，例如 /usr/share/sandbox/kit/git-signing/git-signing-context.md。Docker Sandboxes 会把 Kit 列表及其上下文文件路径加到智能体的说明文件（如 AGENTS.md 或 CLAUDE.md）中，让智能体在需要时读取每个文件。这样 Kit 的指导信息就与你项目的说明分开存放。

添加 Mixin ​

Mixin 往工作负载里添加工具和配置。创建沙箱时用 --kit 添加 Mixin。

例如，一个内部 CLI Mixin 可以打包你公司的可执行文件，同时带上网络规则和针对其 API 的凭据申请：

console
$ sbx run codex --name codex-tools \
    --kit docker.io/<NAMESPACE>/company-cli:1.0.0

把 Mixin 引用换成你自己组织发布的那个。要构建自己的 Mixin，请参阅构建工具 Mixin。把 Mixin 申请的凭据存在宿主机上，并在提示时批准访问。

Codex 启动时 company-cli 已经可用。Docker Sandboxes 会同时应用工作负载和 Mixin 提供的文件与设置。

组合多个 Mixin ​

重复使用 --kit 可以添加更多 Mixin。你也可以把兼容的 Mixin 加到已发布的工作负载集合上，或者用 --kit 传入一个只含 Mixin 的集合。

避免添加集合中已有的 Kit。如果两个 Kit 提供相同的功能，Docker Sandboxes 可能会拒绝这个组合。

要把你的组合发布成一个引用，请参阅编写 Kit 集合。要在共享的沙箱配置中保持各 Kit 分离，把它们列在沙箱环境文件里。为每个已发布的 Kit 使用独立的镜像仓库名。同一仓库的不同标签对应同一个 Kit 名称，而 Docker Sandboxes 会拒绝组合中出现重名。

更改沙箱的 Mixin ​

对 v3 Kit，你在创建沙箱时选择 Mixin。要换用其他组合，请用不同的名称再创建一个沙箱，并指定工作负载和所有要包含的 Mixin。

sbx kit add 命令无法向已有的 v3 沙箱添加 Mixin。

新沙箱不会继承上一个沙箱的变更或 Kit 卷数据。

组合 Kit ​

有些 Mixin 需要另一个 Kit 提供的工具。例如，脚本调用 gojq 的 Mixin 可以声明这个依赖：

yaml
requires: [gojq]

gojq Mixin 示例声明了它提供的功能：

yaml
provides: ["gojq@0.12.17"]

创建沙箱时把两个 Mixin 都包含进来。无论你的 --kit 标志顺序如何，Docker Sandboxes 都会先应用 gojq Mixin，再应用脚本依赖它的那个 Mixin。如果漏掉 gojq，沙箱创建会失败。

requires 条目告诉 Docker Sandboxes 一个 Kit 需要什么。提供该功能的 Kit 仍由你选择并包含。Docker Sandboxes 不会根据这个条目替你下载 Kit。Kit 还可以要求某项功能的最低版本，或排除不兼容的 Kit。

使用 --kit 时，Docker Sandboxes 在创建沙箱时检查并合并这些 Kit。对于集合，这一步发生在发布者构建集合时。发布的 Kit 会记录所用确切组件的清单，以各自的镜像 digest 标识。

要在自己的 Kit 中声明这些关系，请参阅组合字段。

向 Kit 传递参数 ​

Kit 可以暴露参数，用于 linter 模式这类设置。查阅 Kit 的文档，了解参数名、默认值和可接受的值。用 --kit-arg name=value 设置参数：

console
$ sbx run docker.io/<NAMESPACE>/codex-tools:1.0.0 \
    --name codex-tools-fix --kit-arg lint_mode=fix

这个示例使用了一个暴露 lint_mode 参数的工作负载集合。把镜像引用换成你集合的发布引用。要在自己的集合中暴露参数，请参阅配置组件参数。

参数值是纯文本，可能出现在 shell 历史和沙箱状态中。机密信息请使用存储的凭据。

指定目标 Kit ​

不带 Kit 前缀的参数会应用到每个声明了该参数的已选 Kit。要指定到某一个 Kit，使用 --kit-arg <HANDLE>.<ARGUMENT>=<VALUE>：

console
$ sbx run docker.io/<NAMESPACE>/codex-tools:1.0.0 \
    --name codex-tools-fix --kit-arg codex-tools.lint_mode=fix

句柄用于标识 Kit，来自它的引用：

Kit 来源句柄
已发布的镜像仓库名的最后一段，例如 codex-tools
本地目录目录名
Git 仓库所选子目录名；如果没有选择子目录，则为仓库名

针对单个 Kit 的值会覆盖应用到所有 Kit 的值。

从文件加载参数 ​

用 --kit-args-file <FILE> 可以从可复用的文件加载参数。每行写一条 name=value。你可以在名称前加 Kit 句柄前缀，与 --kit-arg 一样。

用 --kit-arg 传入的值会覆盖文件中的值。

哪些设置可以修改？ ​

对于 Kit 集合，你只能修改作者已暴露出来的参数。其他组件参数在集合发布时就已固定。

镜像构建期间选定的设置，比如工具的版本，需要重新构建镜像才能改变。

Kit 数据和宿主目录 ​

Kit 可以为工具设置、历史记录和其他数据提供存储。由 Kit 决定使用哪些目录，以及它们的内容是持久的、临时的，还是与其他沙箱共享。在依赖 Kit 保留你的工作之前，请先查阅该 Kit 的文档。

为 Kit 的宿主挂载选择目录 ​

有些 Kit 会与宿主机共享一个目录。在本地沙箱中，Docker Sandboxes 默认管理这个目录。它的内容在沙箱删除后依然保留，并在使用相同 Kit 来源和挂载路径的沙箱之间共享。

你也可以选择自己的宿主目录。先查阅 Kit 的文档确定沙箱内的路径，然后用 sbx create 或 sbx run 创建沙箱时传入 --mount HOST:SANDBOX_PATH。例如，如果某个已发布的 Kit 使用 /home/agent/history：

console
$ mkdir -p ./history
$ sbx run docker.io/<NAMESPACE>/my-agent:1.0.0 --name my-agent \
    --mount ./history:/home/agent/history

宿主目录必须存在，且沙箱路径必须与 Kit 声明的宿主挂载完全一致。你无法用这种方式添加其他挂载路径。要挂载更多已声明的路径，就重复使用 --mount。这些选择在沙箱创建时就固定了。用 sbx inspect <SANDBOX> 查看宿主目录。

对于环境文件，请使用 mounts。 宿主目录绑定仅适用于本地沙箱。

重新创建沙箱时保留 Kit 数据 ​

本地沙箱中的持久 Kit 卷在 Kit 更新和沙箱删除后依然保留。要复用其中的数据，请用相同的名称和 Kit 来源重新创建沙箱。你可以更改已发布 Kit 的标签或 digest，前提是该 Kit 仍使用相同的存储路径。不同的沙箱名称或 Kit 来源会得到独立的存储。

这只适用于持久的 Kit 卷。在删除沙箱之前，请先保存容器文件系统中你需要的内容。临时的 Kit 存储会在沙箱停止时被丢弃。

关于更换 Kit 时如何保留存储，请参阅 配置卷。

限制 Kit 来源 ​

kit.allowedSources 控制允许的远程 Kit 来源。默认允许 Docker Hub。要加入 Git 发布者，设置你希望允许的完整前缀列表：

console
$ sbx settings set kit.allowedSources '["docker.io/","github.com/docker/"]'

前缀在路径段边界处匹配。本地来源目录由 kit.allowLocalKits 单独控制，默认值为 true：

console
$ sbx settings set kit.allowLocalKits false

默认值和对应的环境变量，请参阅 Kit 设置参考。

验证 Kit 签名 ​

要针对作者的签名身份验证一个已发布的 Kit：

console
$ sbx kit verify docker.io/<NAMESPACE>/my-kit:1.0.0 \
    --certificate-identity <SIGNER_IDENTITY> \
    --certificate-oidc-issuer <ISSUER_URL>

对于基于密钥的签名，用 --key cosign.pub 代替证书身份和签发者选项。从发布者那里获取预期的身份或公钥。

要要求加载 Kit 时必须有可信签名，先配置可信签名者策略，再打开该要求：

console
$ sbx settings set kit.trustedSigners \
    '[{"identity":"release-bot@example.com","issuer":"https://accounts.google.com"}]'
$ sbx settings set kit.requireSignature true

V3 源目录和 Git 来源不支持源签名流程。需要签名时请使用已签名的 OCI 镜像。

调试 Kit ​

当某个工具缺失或请求失败时，检查运行中的沙箱：

console
$ sbx exec <SANDBOX> -- which <TOOL>
$ sbx exec <SANDBOX> -- cat /home/agent/.config/<TOOL>/settings.json
$ sbx policy log

策略日志会显示出站请求及其匹配的规则。用它来查找被拦截的包镜像仓库或 API 主机。如果添加了一个申请凭据的 Kit 之后下载失败，请让该 Kit 的作者确认凭据注入只针对真正需要的服务主机。

要试用更新过的 v3 Kit，请用不同的名称创建沙箱。复用已有沙箱会保留它记录的 Kit 配置。