Kit spec 参考

Note

Kits 处于实验阶段。随着功能演进，kit 文件格式、CLI 命令，以及创建、加载和管理 kit 的体验都可能发生变化。请在 docker/sbx-releases 仓库中反馈意见和提交 bug 报告。

本页记录了 kit 的 spec.yaml 中的每个字段。有关 kit 是什么以及如何使用它们的概述， 请参阅 Kits。

有关解析器和测试使用的规范性 v2 语法，请参阅 docker/sbx-kits-contrib 仓库中的 schemaVersion: "2" specification。

一个 kit 目录需要一个必需的 spec.yaml 和一个可选的 files/ 树：

my-kit/
├── spec.yaml       # required
└── files/          # optional — static files to inject
    ├── home/
    └── workspace/

Schema 版本

从 Docker Sandboxes 0.36 版本开始，支持两个 schema 版本。新的 kit 请使用 schemaVersion: "2"。版本 "1" 通过旧路径仍然被接受。

加载器在 schemaVersion 上分叉。一个 v2 spec 仅使用 v2 语法。在 schemaVersion: "2" spec 中的旧 v1 字段会在解码时被拒绝，而不是被折叠进 v2 模型。每个 spec.yaml 保持使用 一种语法。

v2 中变更了什么：

凭据发现也在 v2 中移出了 kit：kit 声明它需要哪些凭据以及如何注入它们，但每个值的来源由用户 通过 凭据绑定 控制。

Note

解析器接受 mixins 和 sandbox.build，但运行时支持尚待实现。设置了 sandbox.build 的 kit 也必须设置 sandbox.image。

顶层字段

schemaVersion: "2"
kind: <mixin | sandbox>
name: <name>
version: <version>
displayName: <name>
description: <text>
sourceURL: <url>
licenses:
  - MIT
locked:
  - sandbox.image
security:
  privileged: false

一个 kit 还声明行为块，例如 agentInstructions、permissions、ports、credentials、 environment、setup 和 volumes。

Kit 种类

kind: mixin

mixin 将能力叠加到已有的 sandbox 上。它不得声明 sandbox: 块、extends: 或 mixins:。 mixin 可以声明 requires: 来固定它所设计的基 agent：

schemaVersion: "2"
kind: mixin
name: github-tools
requires:
  agent: claude

requires.agent 取一个基 agent 名称。它被作为 kit 名称校验，并在组合时强制执行。

kind: sandbox

sandbox kit 定义一个完整的 agent。根 sandbox 必须声明一个 sandbox: 块。使用 extends: 的 sandbox 可以继承父级镜像并省略自己的 sandbox: 块：

schemaVersion: "2"
kind: sandbox
name: claude-safe
extends: claude

extends: 仅限 sandbox。父级必须解析为 sandbox kit。mixins: 也仅限 sandbox 并被解析器 接受，但运行时组合支持尚待实现。

Sandbox 块

sandbox:
  image: <image-ref>
  build:
    context: .
    dockerfile: Dockerfile
    args:
      AGENT_VERSION: "1.0.0"
    target: runtime
    platforms:
      - linux/amd64
  entrypoint: [my-agent, "--flag"]
  command:
    default: ["--task-mode"]
    interactive: []
  resources:
    cpu: 2
    memory: 4g
    gpu: "1"

有效命令在非交互式启动时是 entrypoint 加 command.default，在 TTY 会话中是 entrypoint 加 command.interactive。如果省略 interactive，则回退到 default。

对于使用 extends: 的 kit，sandbox.command 替换完整的继承参数尾，包括父级 sandbox.entrypoint 中二进制之后的标志。它不会追加到该尾部。定义子级需要的每个参数。例如， claude 的一个添加了 --settings 的子级也必须包含 --dangerously-skip-permissions 以保留 该行为。

agent 的容器镜像必须提供：

• UID 为 1000 的非 root agent 用户，具有无需密码的 sudo。
• 由 agent 拥有的 /home/agent/ 家目录。
• 跨 sudo 保留的 HTTP 代理环境变量（HTTP_PROXY、HTTPS_PROXY、NO_PROXY）。
• agent 二进制，要么烘焙进去，要么用 setup.install 安装。

基于 docker/sandbox-templates:shell-docker 构建即可获得这些基础要求。

Agent 指令

agentInstructions:
  filename: CLAUDE.md
  content: |
    Ruff is installed. Run `ruff check` before committing.

对 mixin，引擎将 content 写入 <dir-of-AI-file>/kits-memory/<kit-name>.md，并向基 AI 文件 添加一个 ## Kits 指针小节。这将每个 mixin 的指令保留在单独的文件中。

凭据

kit 声明它需要的凭据，以及代理如何将它们注入出站请求。它不声明主机发现来源。用户通过密钥 存储或首次运行提示提供值，而 凭据绑定 授权其使用。kit 不能 读取任意宿主环境变量或文件。

credentials:
  - service: <service-id>
    description: <text> # optional
    required: <true | false> # optional, default false
    provider: <provider> # optional, reserved
    apiKey:
      name: <ENV_VAR>
      proxyManaged: true
      inject:
        - domain: <domain>
          header: <header>
          format: <format>
        - domain: <domain>
          scheme: bearer
        - domain: <domain>
          scheme: basic
          username: <user> # required with scheme: basic
    oauth:
      tokenEndpoint:
        host: <host>
        path: <path>
      sentinels:
        accessToken: <sentinel>
        refreshToken: <sentinel>
      credentialFile:
        path: <path>
        template: |
          {
            "<key>": {
              "accessToken": "{{.AccessToken}}",
              "refreshToken": "{{.RefreshToken}}",
              "expiresAt": {{.ExpiresAt}},
              "scopes": {{.ScopesJSON}}
            }
          }

credentials 是一个列表；每个条目命名一个 service 并配置一个或多个认证机制。

每个服务必须声明 apiKey、oauth，或两者。当两者在运行时都解析时，API 密钥优先，OAuth 作为回退。

apiKey

oauth

对于使用 OAuth 认证的 agent（例如 Claude Code），代理拦截 token 响应，用哨兵值替换真实 token，然后在出站请求时换回真实 token。默认情况下，token 永远不会进入沙箱。设置 passthrough: true 可退出哨兵屏蔽，将真实 token 响应送入沙箱。

网络

网络出口在 permissions.network 下声明。凭据不再携带自己的域名映射——代理只将凭据注入其 apiKey.inject 列出的域名，而沙箱到达的每个域名都必须在此处被允许。

permissions:
  network:
    allow: [<domain>, ...]
    deny: [<domain>, ...]

允许和拒绝模式：

在 v1 中这是 network: 块（allowedDomains / deniedDomains，加上 serviceDomains / serviceAuth）。在 v2 中，这些字段是解码错误。

端口

使用 ports 将沙箱服务暴露给宿主机：

ports:
  - container: 8080
    protocol: tcp
    name: web

宿主机端口在 127.0.0.1 上临时分配。用户可以用 sbx ports --publish <host>:<container> 固定宿主机端口。

环境

environment:
  variables:
    <NAME>: <value>

变量名必须是有效的 shell 标识符（[A-Za-z_][A-Za-z0-9_]*）。

不要设置 DASH_、SBX_ 或 DOCKER_ 变量，并避免覆盖 HOME、USER、SHELL、PATH、 LD_PRELOAD 和 LD_LIBRARY_PATH。运行时保留这些名称并可能覆盖它们。

Setup

setup:
  install:
    - command: <shell-string>
      user: <uid>
      description: <text>
  startup:
    - command: [<argv>, ...]
      user: <uid>
      background: <true | false>
      description: <text>
  files:
    - path: <path>
      content: <text>
      mode: <octal>
      onlyIfMissing: <true | false>
      description: <text>

执行顺序

当创建一个沙箱时，kit 内容按此顺序应用：

1. 网络权限和环境变量。
2. files/home/ 下的静态文件。
3. setup.install 命令，按声明顺序。
4. setup.files 项。
5. setup.startup 命令注册用于每次沙箱启动。
6. files/workspace/ 下的静态文件，在 workspace 就绪后。用 --clone 时，这意味着仓库克隆 之后。

对于堆叠的 kit，每个阶段的项按 --kit 顺序应用。一个 install 命令可以消费来自 files/home/ 的打包文件，但不能消费来自 files/workspace/ 或 setup.files 的文件，因为那些文件落得更晚。

sbx kit add 重建沙箱，而不是就地修改它。它支持仅限于 environment.variables、 setup.install 和 permissions.network.allow 的 mixin kit，它们遵循与沙箱创建相同的顺序。 它拒绝声明静态文件、setup.startup 或 setup.files 的 kit。要使用这些字段，请用 kit 重建 沙箱。

install

在应用 kit 时同步运行，无论是在沙箱创建期间还是通过 sbx kit add。Shell 字符串传给 sh -c。

startup

在每次沙箱启动时运行。字符串数组，不由 shell 解释。

启动命令是非交互式的。它们在 agent 连接之前运行，没有终端连接，因此它们不能提示用户（例如， 交互式 aws login 会挂起或失败）。它们也不门控 agent 的入口点：一旦启动命令被分发，agent 就会启动，无论 background 如何。值 false 在启动分发器内等待它运行下一个命令；它不会延迟 agent 入口点。将启动命令用于非交互式准备——启动守护进程、预热缓存、刷新配置——并将任何需要在 agent 运行前落盘的值用于 setup.files。

启动命令必须是幂等的。它们在每次沙箱启动时运行，并在容器重启时重放，因此一个在第二次调用时 失败或行为异常的命令会破坏重启路径。用存在性检查保护工作，使用 upsert 而非 insert，并优先 选择无论运行多少次都收敛到相同终态的命令。

files

在沙箱启动时写入的文件，带运行时替换。

静态文件

my-kit/files/
├── home/       → /home/agent/
└── workspace/  → primary workspace path

父目录自动创建。现有文件被覆盖。绝对路径和路径遍历序列（../../）被拒绝。

卷

volumes:
  - path: /workspace
    size: 10g
    mode: "0755"
  - path: /tmp/scratch
    type: tmpfs
    size: 512m
    mode: "1777"

卷仅在创建沙箱时应用。sbx kit add 不能将卷附加到运行中的容器。