docker-sandboxes-kits

Docker Sandboxes：套件（spec.yaml）

概述

套件是一个目录（或 ZIP/OCI/git 制品），其中包含 spec.yaml 以及可选的 files/ 树。sbx 会在 sbx create/sbx run --kit/sbx env 期间，或在 sbx kit add 期间，将套件组合到正在运行或即将创建的沙箱中。 此技能负责 kit-spec v2 的编写、验证和分发——涵盖 spec.yaml 自身语法中的所有内容——而套件声明的运行时含义（凭据注入、网络强制执行）由 docker-sandboxes-network-credentials 负责，套件所组合到的沙箱则由 docker-sandboxes-lifecycle 负责。

何时使用此技能

在以下情况下启用此技能：

• 用户想要为 kind: sandbox（完整 Agent）或 kind: mixin（扩展）套件编写、验证或打包 spec.yaml。
• 用户想要通过 mixin 为现有内置 Agent 添加工具、凭据、网络访问权限或文件。
• 用户想要将套件发布到 OCI 注册表（或从中拉取）、为其签名，或验证签名／来源证明。
• 用户正在调试套件验证错误、参数替换错误，或 sbx kit add 的重建感知要求。

何时不要使用此技能

在以下情况下不要使用此技能：

• 任务是创建、运行或移除套件所组合到的沙箱，且与套件自身内容无关——请使用 docker-sandboxes-lifecycle。
• 任务涉及套件声明的凭据或网络规则在运行时的实际行为（代理注入、允许／拒绝优先级，或当前网络／全局策略已允许的内容），或者涉及与套件无关的密钥／策略——请使用 docker-sandboxes-network-credentials。
• 任务涉及通过自身 kits: 块引用套件的 sbxenv.yaml 文件格式——请使用 docker-sandboxes-env 处理该文件的架构（此技能仍负责被引用套件本身的内容）。

核心指南

kind: sandbox 与 kind: mixin — 选对类型

• 每个沙箱只能组合一个 kind: sandbox 套件（完整 Agent：基础镜像 + 启动配置）。可叠加任意数量的 kind: mixin 套件（工具、凭据、网络、文件）。mixin 不得声明 sandbox: 块、extends: 或 mixins:。
• 每个套件都必须包含 schemaVersion: "2"（当前的纯净语法——不包含旧版兼容层）、kind，以及符合 ^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$ 的 name。解码采用严格模式：任何位置出现无法识别的字段都会导致硬错误（例如拼写错误的 permissions.netwrok:），因此通过验证的套件不会有被静默忽略的拼写错误。

  schemaVersion: "2"
  kind: mixin
  name: extra-egress
  

• 不要在 mixin 中重新定义基础 Agent 的凭据：为同一服务声明新的 apiKey.name 或 proxyManaged 会导致组合失败。shell、docker-agent 和 opencode 已拥有 github。不过，仅用于路由的增补条目（apiKey.inject，不含 name/proxyManaged/oauth，且 required: false）可以扩展基础凭据。OAuth 只能用于 sandbox 套件，不能用于 mixin。参见 references/spec-v2-fields.md。 请在固定版本的源代码中检查内置定义：sandboxlib/agentkits/agents/<agent>/spec.yaml；sbx kit inspect 接受制品引用，不接受内置名称。单独验证 mixin 不会测试组合。

sandbox: 块（仅限沙箱套件）

• 对 kind: sandbox 必填（除非该套件通过 extends: 继承了已提供此项的父级）；对 kind: mixin 禁止。
• image: 是预构建的基础镜像。entrypoint: 是固定的进程前缀（entrypoint[0] 是二进制文件）；command: 是特定模式的参数尾部——可以是裸列表（设置 default，interactive 会回退到该值），也可以是 {default: [...], interactive: [...]}。 若要创建完整的最小套件，请使用 assets/spec-sandbox.yaml，它继承内嵌的 shell 定义，而不是自行臆造镜像或命令。
• sandbox.build:（Dockerfile 构建）已接受，但此版本的运行时不会执行构建——设置了 build: 的套件仍必须设置 image:，否则加载时会因可操作的错误而被拒绝。
• extends:（如下）是获取真实可用镜像的最简单方式，无需自行臆造。 继承内置 Agent（例如 extends: shell）的沙箱套件会继承该 Agent 实际的 sandbox.image，并且可以完全省略 sandbox:——请参阅最小示例资源，它正是这样做的，而不是指定虚构的镜像引用。

出站流量：permissions.network——以及“声明所有出站流量”的规则

• permissions.network.allow/deny 是 v2 中对应 v1 顶层 network: 的配置项。支持的匹配形式包括精确主机名、精确主机名+端口、单标签通配符（*.example.com）、多标签通配符（**.example.com）和 CIDR 前缀。运行时匹配器不支持端口范围；请使用多个精确端口。 在域名规则内部或 CIDR 规则内部，拒绝优先。 域名规则的明确判定会先于 CIDR 规则进行：已允许的主机名不会再针对其解析出的 IP 检查 CIDR 拒绝规则。不要仅依赖 CIDR 拒绝规则来阻止已允许的主机名。

  permissions:
    network:
      allow:
        - registry.npmjs.org
      deny:
        - telemetry.example.com
  

• permissions.network.allow 在组合配置中会叠加生效，而且授予沙箱出站流量权限的不只有套件自身的允许列表。 沙箱还会继承基础 Agent 自身的允许列表，以及全局或每沙箱网络策略（sbx policy，独立于任何套件）的许可内容——请参阅 docker-sandboxes-network-credentials。从某个套件的 allow 列表中移除某个主机，并不能证明该主机已被阻止——全局策略默认值（balanced 允许常见软件包注册表和 AI 服务；allow-all 允许所有内容）或其他组合套件仍可能允许访问。切勿在未对真实沙箱运行 sbx policy check network --sandbox <name> <host> 检查实际生效判定前，声称某个主机已被阻止。
• 为确保可复现，应明确声明套件所需的出站流量。注入凭据本身不会授予网络访问权限。省略允许项会使可访问性取决于现有的全局/每沙箱策略；这不一定会阻止该主机。请检查实际生效的判定。

credentials — 工具包需要什么，而非用户如何存储凭据

• 每个条目声明一个 service 标识，以及要将解析后的值注入何处（apiKey 和/或 oauth）；它绝不声明用户如何获取或存储凭据——这由用户自己的绑定文件负责，并通过 sbx secret set 接入（参见 docker-sandboxes-network-credentials）。
• apiKey.inject[] 需要 domain，并且需要显式的 header+ format（format 必须恰好包含一个 %s），或使用 scheme: 简写：scheme: bearer 会展开为 Authorization: Bearer %s（不能有 username），scheme: basic 则需要 username，且不能与 format 同时使用。选择一个尚未由任何组合基础 Agent 声明的 service 名称（参见上文重复服务规则）——完整片段请参见 references/spec-v2-fields.md。
• apiKey.proxyManaged: true 会将容器内的环境变量设为字面值 proxy-managed 哨兵，而不是留空；真实值仅由代理在允许列表中的注入域名上替换。
• oauth 需要 tokenEndpoint.host/.path，并且除非 passthrough: true，否则需要非空的 sentinels.accessToken/.refreshToken。 passthrough: true 是一种安全性降级——真实令牌会进入容器，而不是哨兵——仅当工具包自身的设计要求如此时才使用，并在 description 中说明。

setup — 安装（一次）与启动（每次启动）与文件（启动时写入）

区块	命令形式	运行时机
setup.install[].command	字符串，通过 sh -c 执行	Agent 首次启动前同步运行一次。适用于所有工具包，无论是否内置。
setup.startup[].command	list，exec 风格（无 shell）	在容器每次启动时运行（创建、停止后启动、守护进程重启、主机重启）——必须具备幂等性。
setup.files[]	通过 shell exec 写入文件	在容器启动时运行；path 为绝对路径；content 中只允许使用 ${WORKDIR} 占位符。

供 assets/spec-sandbox.yaml 中 shell 工具包使用的可选片段：

setup:
  startup:
    - command: ["sh", "-c", "mkdir -p ~/.my-kit"]
  files:
    - path: /home/agent/.my-kit/config.json
      content: '{"workdir": "${WORKDIR}"}'

• setup.files 与 files/ 目录树（如下）不是同一种机制。 setup.files 条目是在启动时执行的动态写入，并会替换 ${WORKDIR}；files/home/ 和 files/workspace/ 目录树则是一组与 spec.yaml 一同打包、并在容器创建时复制进去的静态文件；具体而言，写入发生在工作区填充之后的，是该目录树中的 files/workspace/ 部分，而不是 setup.files（例如，在 --clone 下于容器内执行 git clone 之后）。不要混淆二者：setup.files 本身不保证在工作区填充之后执行。
• 在组合工具包时，所有三个 setup: 列表都会按 --kit 顺序拼接。
• 默认执行用户：除非另有指定，否则以 root（user: "0"）执行安装；以 Agent 用户（uid 1000）执行启动/入口点。以 root 身份执行的安装步骤若在 /home/agent 下写入文件，必须将其 chown 回 agent:agent，否则之后以 Agent 用户身份在该目录中写入会失败。

volumes — 仅在创建时生效，每个卷都必须设置大小

• 每个条目都需要绝对路径 path:；可选的 type: tmpfs（基于 RAM；省略或设为 "" 时使用默认的基于块设备的卷）、可选的 size:（字节大小字符串）和 mode:（八进制）。
• 卷仅在创建沙箱时生效——sbx kit add（运行时注入）会完全跳过卷变更；需要卷的工具包必须在创建时就存在。
• 始终为块卷设置 size:。 未指定大小的卷会继承 50 GiB 的默认值，并立即占用真实的主机磁盘空间（ext4 inode 表清零）；512 MiB 是实际可行的下限——低于该值时，mke2fs 会切换 inode 密度，节省的空间基本会消失。

args — 为 kit 参数化

• 在顶层 args: 下声明（仅限 v2——冻结的 v1 语法没有 args 块），每项必须且只能包含 default 或 required: true 其中之一，还可包含 description／enum／pattern。在 spec.yaml 或 files/ 中的任意位置通过 ${{ kit.args.NAME }} 引用；替换会在解析 spec 之前进行。每个引用都必须 已声明，否则加载会失败——这正是该块能成为 kit 输入可信列表的原因。在字符串字段中使用占位符时， 请将其加上引号（VERSION: "${{ kit.args.version }}"），否则看起来像数字的未加引号值 会被解析为数字，无法解码到字符串字段中。
• 使用 --kit-arg name=value（适用于每个 kit）或 --kit-arg kitname.name=value（仅适用于一个 kit），或使用 --kit-args-file 提供值。 切勿以这种方式传递机密——--kit-arg 的值不会被屏蔽；参见 docker-sandboxes-network-credentials。

extends 和 mixins — 组合，而非运行时注入

• 在此固定版本中，extends: 仅解析内置 Agent 名称 （shell、claude 等）。远程 git／OCI 父项无法解析，即使已固定也不行； 更广泛的格式规范并不保证实现支持。最小资源使用受支持的 extends: shell。
• mixins: 会被接受并给出警告，但此运行时不会应用它。请使用 --kit 或 sbx kit add 进行组合。格式对不可变引用的要求，并不能让尚未实现的远程继承生效。
• 为保证可复现性，优先使用固定到摘要／提交的 CLI kit 引用。 --kit 和 sbx kit add 仍接受可变标签／分支；CLI 解析器不会强制执行此建议。
• requires.agent（仅限 mixin；用于 kind: sandbox 时会被拒绝）用于固定 mixin 所针对的唯一基础 Agent（例如 Claude 专用环境变量）。规范库会检查其格式是否正确； 实际的 Agent 亲和性不匹配由组合使用方强制检查，而不是仅由 sbx kit validate 检查。

验证、打包和分发

命令	用途
sbx kit validate REFERENCE [--kit-arg ...]	本地目录、ZIP 或 git 引用；不接受 OCI。仅检查架构是否符合规范。不会与基础 Agent 组合——无法检测重复服务的凭据冲突，也无法确认任何域在运行时是否可访问。
sbx kit inspect REFERENCE [--kit-arg ...] [--json]	加载并打印组合前解码后的制品，包括 --kit-arg 替换预览。
sbx kit pack DIRECTORY [-o OUTPUT.zip]	将通过验证的目录打包为 ZIP。
sbx kit pull REFERENCE [-o OUTPUT]	从 OCI 注册表拉取 kit 的原始层载荷，但不进行组合。
sbx kit push DIRECTORY REGISTRY/REPO:TAG [--sign]	打包并推送；每次推送都会附加默认未签名的 SLSA 溯源证明。
sbx kit provenance REFERENCE [--certificate-identity ...]	打印 push 附加的证明；除非通过匹配的密钥／身份验证，否则会标记为未签名。
sbx kit sign REFERENCE / sbx kit verify REFERENCE	使用 Sigstore 进行签名／验证（默认无密钥）；优先使用 --identity-token-file，而非 --identity-token。
sbx kit add SANDBOX REFERENCE [--kit-arg ...]	在运行时将仅限 mixin注入现有沙箱（需要带有重建感知功能的标签）；容器不可变设置（security.privileged、volumes:）无法通过此方式生效。

完整标志列表以及上述每条命令的示例，请参见 references/kit-distribution-commands.md。

相关技能

• 关于 kit 被组合到的沙箱（sbx create/run --kit、sbx kit add SANDBOX），请参阅 docker-sandboxes-lifecycle。
• 关于 kit 的 credentials:/permissions.network: 声明在运行时的含义——代理注入、允许/拒绝优先级、纳入全局/每沙箱策略后沙箱实际拥有的有效策略，以及用户存储实际密钥值的位置——请参阅 docker-sandboxes-network-credentials。
• 关于 sbxenv.yaml 文件（其 kits:/agent: 字段通过此架构引用 kit），请参阅 docker-sandboxes-env。

参考资料

• references/sources.md — 上述每条规则的来源（规范包、SPEC-v2.md、帮助信息截取、文档 URL）。
• references/spec-v2-fields.md — 完整的 v2 字段表（通用字段、仅限沙箱的字段、仅限 mixin 的字段、共享区块），便于查阅，无需重新阅读完整规范。
• references/kit-distribution-commands.md — sbx kit validate/inspect/pack/pull/push/provenance/sign/verify/add 的完整标志和示例。

资源

• assets/spec-sandbox.yaml — 一个真实的最简 kind: sandbox kit，通过 extends: shell 继承真正可用的镜像，而非凭空定义镜像。
• assets/spec-mixin.yaml — 一个真实的最简 kind: mixin kit，不包含任何凭据（仅扩展出口流量），可与每个内置 Agent 顺畅组合。

检查

• checks/verification.md — 架构、组合、出口流量和 kit-add 检查（尚未执行的集成运行手册；使用隔离的 --app-name，不发布到注册表，也不签名）。