用这份参考查阅一个 v3 Kit 能否在你的 Docker Sandboxes 版本上运行，以及它是否需要本地沙箱。每项能力在 Docker Sandbox Kit Specification 中都有对应的链接，说明其设置和示例。
按能力划分的支持情况
版本号标识首个支持该能力的 sbx 版本，同时受表中限制的约束。部分支持意味着 Docker Sandboxes 只应用该能力的一部分。仅声明意味着 Docker Sandboxes 接受这个条目，但不使用其中的命令。
表中所有能力名都带有 com.docker.sandbox/ 前缀。
| 能力 | 本地沙箱 | 云沙箱 | 限制 |
|---|---|---|---|
agent-context@1 | v0.45.0 | v0.45.0 | 智能体说明在创建沙箱时应用。 |
agent-context@2 | v0.51.0 | 部分支持：v0.51.0 | 云沙箱会在 /home/agent 下写入一份工作负载配置。Mixin 使用该工作负载的配置，不能指定 directory。必需的配置文件不受支持会阻止创建；可选的则会被跳过。 |
agent-interactive-sessions@1 | 不支持 | 不支持 | Docker Sandboxes 不使用这些会话命令。 |
agent-sessions@1 | 仅声明 | 仅声明 | 从 v0.45.0 起接受，但 Docker Sandboxes 不执行其中声明的会话命令。 |
agent-skill@1 | v0.48.0 | 不支持 | 需要指定 agent-skills@1 目标。使用 --skills=off 时，随附的技能仍然可用。 |
agent-skills@1 | v0.45.0 | 不支持 | 本地沙箱会挂载共享技能存储。从 v0.48.0 起，发现路径也会收到随附的技能。 |
credential@1 | v0.45.0 | 部分支持：v0.45.0 | 在云沙箱中，作用域限定为安装阶段的凭据在安装之后仍然可用。 |
git-identity@1 | v0.48.0 | 不支持 | 需要宿主 Git 配置中有 user.name 和 user.email。 |
host-mount@1 | v0.50.0 | 不支持 | 用户可以在创建时选择宿主目录。云沙箱会拒绝必需条目，并跳过可选条目。 |
kit-registry@1 | v0.45.0 | 不支持 | 仅限已批准的 OCI 构建器 Kit。本地和 Git Kit 来源不会获得镜像仓库访问权限。 |
lifecycle@1 | v0.45.0 | v0.45.0 | 本地 startup 钩子与智能体并行运行，而不是阻塞它的启动。 |
long-running@1 | v0.47.0 | 不支持 | 在最后一个会话断开后保持本地沙箱运行。 |
network-policy@1 | v0.45.0 | 部分支持：v0.45.0 | 云沙箱在安装之后仍保留安装阶段的网络访问。 |
network-policy@2 | v0.45.0 | 部分支持：v0.45.0 | 云沙箱会执行主机规则，但不执行 HTTP 方法或路径限制。安装阶段的访问在安装之后仍然保留。 |
port@1 | v0.45.0 | 部分支持：v0.45.0 | 云沙箱只暴露 IPv4 TCP 端口。请参阅端口地址族。 |
privileged@1 | v0.48.0 | 不支持 | 本地运行时接受该能力，它会在沙箱 VM 内以特权模式运行 Docker-in-Docker 容器。 |
resources@1 | 部分支持：v0.45.0 | 部分支持：v0.45.0 | 工作负载的 CPU 和内存默认值会被应用。gpu 字段不用于选择 GPU；云端创建会拒绝必需的 GPU 申请。 |
sbx@1 | v0.45.0 | v0.45.0 | Docker Sandboxes 使用工作负载命令启动智能体。 |
ssh-agent@1 | v0.48.0 | 不支持 | 需要启用 SSH agent 转发，并且有可用的宿主 SSH agent。 |
usb-device@1 | 不支持 | 不支持 | 不支持 Kit 申请 USB 设备访问。 |
volume@1 | v0.45.0 | 部分支持：v0.45.0 | 本地沙箱提供块存储或 tmpfs，并在删除和重新创建后保留块卷。云沙箱在声明的路径上使用普通的沙箱磁盘，tmpfs 申请也是如此。 |
端口地址族
对于 v3 的 port@1 条目，family 用于选择发布端口时使用的地址族：ipv4、ipv6，或两者兼用的 dual。如果没有任何 Kit 指定地址族，该端口默认使用 IPv4，即使显式写了 transport: tcp。当服务同时需要 IPv4 和 IPv6 客户端时，请使用 family: dual。
当多个 Kit 声明同一个端口和传输方式时，没有指定 family 的条目会使用该组合中另一个 Kit 指定的地址族。为同一端口指定冲突地址族的 Kit 不能一起使用。
云沙箱只支持 IPv4 TCP 端口。它们会拒绝必需的 ipv6 和 dual 条目，并跳过可选条目。语法和示例请遵循上表中的 port@1 规范链接。
能力组
Docker Sandboxes 从 sbx v0.48.0 起支持能力组。只有当运行时能提供组内每一项能力时，才会选择这个组。如果某项能力不可用，可选组会被整体跳过，包括它的网络规则、安装命令、生成的文件和智能体说明。必需组中不可用的能力会阻止沙箱创建。
可用性还取决于宿主：Git 身份要求配置好 user.name 和 user.email，SSH agent 访问要求有可用且启用了转发的 agent。语法和组合规则请参阅上游的 能力组定义。
需要创建沙箱的能力
把需要下列设置的 Kit 包含进来，并在创建沙箱时应用它们。sbx kit add 无法把这些设置应用到已有沙箱：
| 能力 | 需要创建沙箱才能生效的设置 |
|---|---|
credential@1 | 凭据路由和身份验证 |
kit-registry@1 | 对 Kit 镜像仓库的访问 |
long-running@1 | 在会话断开后保持沙箱运行 |
port@1 | 已发布的端口 |
resources@1 | CPU 和内存分配 |
volume@1 | 块存储和 tmpfs 挂载 |
lifecycle@1 | 生成的 files 需要创建沙箱。install 和 startup 钩子可以用 sbx kit add 添加。 |
network-policy@1 和 network-policy@2 | 主机级拒绝规则需要创建沙箱。允许规则可以用 sbx kit add 添加，network-policy@2 的 HTTP 方法和路径规则也可以。 |
sbx kit add 会拒绝声明了凭据、已发布端口、资源设置、卷、生命周期生成文件或主机级拒绝规则的 Kit。要使用这些 Kit，请删除沙箱后用包含它们的 Kit 重新创建。删除沙箱前，先保存其中需要保留的工作。
技能发现路径（agent-skills@1）和随附技能（agent-skill@1）可以用 sbx kit add 添加：该命令会替换沙箱容器并应用更新后的技能配置。