docker-sandboxes-env

Docker 沙箱：声明式 sbxenv.yaml 环境

概述

sbxenv.yaml（schemaVersion "1"，实验性）以声明式方式描述一个沙箱环境——包括 Agent、混合工具包、工作区挂载、环境变量、要配置的密钥/注册表/绑定、MCP 服务、端口，以及主机端生命周期命令——这样就可以通过 sbx env create|run|plan|exec|rm 可重复地创建和销毁环境，而无需使用冗长的命令行参数调用。本技能端到端负责该文件格式。它将所封装的沙箱生命周期语义、所配置的凭据/网络模型，以及 kits: 条目引用的工具包架构，委托给各自的技能。

何时使用此技能

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

• 用户希望将沙箱环境定义存入版本库，以便重复使用，而不是使用冗长的 sbx create/sbx run 命令行。
• 用户希望将主机端的设置/清理命令（克隆仓库、填充测试数据、归档状态）与沙箱的创建/连接/移除生命周期关联起来。
• 用户希望通过命名参数（args: + --env-arg）为共享环境文件配置参数。
• 用户在排查 sbx env create/run 为何要求批准，或为何跳过或标记了文件、工具包或密钥。

何时不要使用此技能

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

• 任务涉及底层基于参数的 sbx create/run/rm 工作流，且不涉及 sbxenv.yaml 文件——请使用 docker-sandboxes-lifecycle。
• 任务涉及选择网络策略，或独立于任何环境文件存储密钥/注册表凭据——请使用 docker-sandboxes-network-credentials（此技能的 secrets:/registries:/bindings: 块会配置到同一存储中，但不会在此处重新定义相关规则）。
• 任务涉及编写 kits: 条目所指向的工具包 spec.yaml——请使用 docker-sandboxes-kits。

核心指南

文件解析与必填字段

• sbx env 从目录中读取的文件必须恰好命名为 sbxenv.yaml——不能使用其他名称；项目级的、以目录命名的 .sbxenv.yaml 不会被读取为项目自身的文件（只有主目录基础层使用这个隐藏文件名；见下文）。
• 每个环境文件都必须包含 schemaVersion: "1" 和 agent:（内置 Agent 名称，或通过 kits: 提供的 Agent 工具包的清单名称）。其他字段均为可选项。agent: shell 无需凭据，是验证文件机制最简单的方式。
• sbx env create|run|plan|exec|rm 接受一个或多个 PATH 参数。每个 PATH 可以是一个目录（解析为 <PATH>/sbxenv.yaml），也可以是文件本身。传入多个参数时会按声明顺序进行深度合并——语义与 docker compose -f 相同：后面的文件会覆盖前面的文件，映射按键合并，序列则会串接。

  sbx env create sbxenv.yaml override.yaml
  

命名、工作区和 .sbxenv.yaml 用户基础层

• 除非文件设置了 name: 或被 --name 覆盖，否则沙箱名称取自挂载的目录（如果没有挂载，则取自项目目录）——因此，即使环境没有挂载任何内容，每次应用时仍是同一个沙箱。同一目录中的两个不同环境文件会生成相同的沙箱名称并发生冲突，除非每个文件都设置自己的 name:（或每次调用时传入不同的 --name）——同一目录中可能存在多个环境时，务必为每个环境设置各自明确的 name:。
• workspace: 用于命名读写挂载，其行为与 sbx create 省略路径时完全相同：省略 workspace: 就不会挂载任何内容。相对 workspace: 路径相对于声明它的文件所在目录解析——workspace: . 会挂载文件所在的目录。${{ env.projectDir }} 表示项目目录（即包含第一个 PATH 的目录；如果没有指定，则为当前工作目录）；${{ env.fileDir }} 表示声明该项的文件所在目录。除此之外，不会展开任何内容——单独的 $ 会被视为文本字面量，因此，为容器编写的值（PATH: $PATH:/opt/bin）会原样传递给容器。

  workspace: .                       # mounts the directory this file sits in
  # workspace: ${{ env.projectDir }} # mounts the project directory explicitly
  

• 相对工具包源路径遵循与 workspace: 相同的文件目录锚定规则（工具包引用语法请参阅 docker-sandboxes-kits）。
• 已挂载工作区中的文件默认会受到只读遮蔽保护，但只有文件直接位于挂载点自身根目录时，这项保护才是完整的。 沙箱无法重命名挂载点上的只读绑定——挂载点内没有更上层的目录可供重命名。但是，若环境文件位于读写挂载的子目录中，则它只在当前路径受到保护：沙箱可以重命名其所在目录（沙箱有权写入该目录），然后自行重新创建原路径，让沙箱控制的文件回到只读绑定不再生效的位置。对于不在挂载点根目录的文件，sbx env plan 会明确指出这一缺口。不要声称重命名所在目录不会造成保护缺口——除挂载点根目录外，都会造成缺口。
• 如果未指定 PATH，则会将主目录中的 .sbxenv.yaml 作为基础层合并，用于提供跨项目共享的默认值；指定任何 PATH 都会完全跳过此层。基础层不得设置 name:（它用于标识单个项目），且其 workspace: 必须以 ${{ env.projectDir }} 为根——任何其他值都会在每个合并该配置的项目下挂载同一个固定目录。

args: — 为共享文件配置参数

• 在 args: 下声明具名输入项，每项都必须设置 default（使其成为可选项，default: "" 也算有效默认值）或 required: true（两者不能同时设置），并可选设置 description、enum 或 pattern。
• 在文件中任何出现值的位置，都可以通过 ${{ env.args.NAME }} 引用某项；使用 --env-arg NAME=VALUE（可重复指定）或 --env-args-file PATH 传入该项。

lifecycle: — 主机命令和审批计划

• lifecycle: 声明在主机上、沙盒外、以你自己的权限运行的 shell 命令——而不是在容器内运行。每次调用按以下顺序运行三个阶段：
  • initialize — 每次 create 和 run 都会运行，包括仅连接到现有沙盒的情况。它是唯一一个可以生成环境运行所需内容（克隆的工作区、生成的文件）的阶段，因此必须具备幂等性——每次重新连接时都会再次运行。
  • postCreate — 沙盒创建后运行一次，在交互式连接接管终端之前运行。
  • preRemove — 在 sbx env rm 删除沙盒之前运行，此时 sbx env exec 仍可访问沙盒。preRemove 失败仅会发出警告——失败本身不会阻止删除。钩子运行后，删除操作会重新检查已批准的销毁计划和沙盒身份。若存在未包含在该审批中的新凭据或绑定变更，或同名沙盒已被替换，则会在删除前停止操作。重试前请检查新的销毁计划。
  • sbx env exec 完全不会运行生命周期命令，并且要求沙盒已存在——它不会创建沙盒。请先运行 sbx env create/sbx env run。

  lifecycle:
    initialize:
      - command: test -d app || git clone https://github.com/acme/app
    postCreate:
      - command: ./scripts/seed-fixtures.sh
    preRemove:
      - command: ./scripts/archive-state.sh
  

• 默认情况下，每条命令都通过 shell 在项目目录中运行（可通过 workdir: 按命令覆盖；使用 timeout: 限制其运行时间）。
• 只要文件声明了任何生命周期命令，每次调用处理到该文件时都会询问，无论本次调用是否有任何变更——批准一条命令也意味着信任它调用的所有内容，包括回答后内容可能发生变化的脚本，因此默认会重复询问，而不会记住之前的回答。唯一例外：sbx settings set env.rememberHostCommands true 会让系统仅在命令实际发生变化时再次询问。绝不要将不可信文件或不可信工具包中的生命周期命令视为已预先批准，也绝不要为尚未审查命令的文件启用 rememberHostCommands。完全不声明主机命令，且配置与上次批准的内容相比没有变化的环境，会静默应用，不会弹出提示。使用 --skip-host-commands 可在单次调用中不运行任何已声明的命令。

环境计划：它是什么，以及不是什么

• sbx env plan [PATH...] 会打印应用该文件将设置的所有内容——主机命令、凭据/绑定、MCP 注册、目录、已发布的端口、沙盒本身及其变量——并与上次应用/批准的内容进行比较。它不会更改任何内容。
• sbx env create/sbx env run 会显示相同的计划，并要求在执行任何操作前获得批准（--auto-approve/-y 可在非交互式场景下跳过提示——对于尚未审查的文件或工具包，绝不要默认使用 -y）。在计划中显示并记录到状态中的唯一字段是密钥的字面量 value:，它会以 sha256: 摘要形式记录，而不会以明文记录；ref:/command: 密钥会显示凭据的来源，而不是解析后的值。

按环境限定的密钥、注册表和绑定

• secrets: 和 registries: 会写入 sbx secret set 使用的同一个凭据存储 ，作用范围为此环境的沙箱级别，因此 sbx env rm 可以准确移除它所创建的内容。每个条目采用与 sbx secret set 相同的 value/ref/command 格式（三者必须且只能使用一个）——关于它们在运行时的含义，以及为什么不应以其他方式将字面密钥值写入 已检入的文件，请参阅 docker-sandboxes-network-credentials。
• bindings: 是按服务设置的凭据绑定，会合并到用户的全局 credentials.yaml 中；与 secrets:/registries: 不同，sbx env rm 默认会保留这些绑定（它们属于用户级别，可能会与其他沙箱/环境共享）——传入 --prune-bindings 也可以将其移除。
• 切勿将字面密钥值直接写入已检入的 sbxenv.yaml。 使用 ref:（1Password/AWS Secrets Manager）或 command: ，这样值就完全不会存储在文件中；如果临时使用了字面 value:，计划和状态都只会显示其摘要，但原始环境文件仍会包含明文密钥。下方标注的 secrets: 片段展示了具体格式；它有意不包含在最小资产中，因为验证该资产完全不需要凭据。

  # OPTIONAL fragment — add only if this environment actually needs a
  # credential; the minimal asset omits this entirely.
  secrets:
    anthropic:
      ref: op://Private/Anthropic/api-key   # never a literal `value:` in a checked-in file
      refresh: 55m
  

kits:、additionalWorkspaces:、mcp:、ports: 和 sandboxOptions:

• kits: 会将混入工具包（以及名称与 agent: 匹配的一个 Agent 工具包，且只能有一个）组合到基础 Agent 上；相对路径源以声明文件自身所在目录为基准，与 workspace: 的规则相同。
• additionalWorkspaces: 会挂载主 workspace: 之外的其他目录（文件不能只声明其中一个而不声明另一个）——这相当于 sbx run 额外的位置工作区参数加上 :ro。
• mcp.servers: 会在主机上注册 MCP 服务，并在创建时将其添加到沙箱固定（静态）的 MCP 集合中；注册信息是主机全局的，且会被 sbx env rm 保留。
• ports: 会为沙箱公开的容器端口固定指定主机端口绑定——相当于 sbx ports --publish——并会在 sbx env rm 删除沙箱时自动拆除。
• 除下文的 writableEnvFiles 外，sandboxOptions: 会映射到其余的 sbx create 标志：template、memory、cpus、 pullPolicy、profile、skills。

有关上述五个区块的准确字段格式、必填键以及各自的 YAML 示例，请参阅 references/env-schema-fields.md。

sandboxOptions.writableEnvFiles——有意且明确的安全降级

• 默认情况下，挂载到工作区中的所有环境文件在各自路径下均为只读，即使挂载的其他部分可写也是如此。这样可以防止 Agent 修改决定下次调用时将在你的计算机上运行哪些主机生命周期命令和密钥解析命令的文件。
• 只有在明确希望 Agent 编辑自身环境文件时，才设置 sandboxOptions.writableEnvFiles: true。这会造成真正的安全降级——此时计划会将该文件报告为可写——因此应像对待其他明确的信任决策一样谨慎，而不是将其作为默认设置。
• 此保护仅在挂载自身的根目录处完整有效。 直接放在读写挂载根目录下的文件无法被触及，即使尝试重命名也不行，因为沙箱无法重命名挂载点本身。位于该挂载子目录中的文件则不同：它在当前路径下是只读的，但沙箱可以重命名存放它的目录（沙箱有权写入该目录），然后在原路径重新创建文件，最终得到由沙箱控制的文件。对于不在挂载根目录下的文件，sbx env plan 会标记此漏洞——请阅读计划输出，不要想当然地认为重命名总是无害的。

相关技能

• 对于此文件封装的基于标志参数的 sbx create/run/rm 工作流，请使用 docker-sandboxes-lifecycle。
• 如需了解 secrets:/registries:/bindings: 在运行时的含义，以及如何独立于任何环境文件配置网络策略，请使用 docker-sandboxes-network-credentials。
• 如需了解 kit spec.yaml 的架构（kits: 条目或指向 agent kit 的 agent: 所引用的架构），请使用 docker-sandboxes-kits。

参考资料

• references/sources.md — 上述每条规则的来源记录（帮助信息截图、源文件路径、文档 URL）。
• references/env-schema-fields.md — kits:、additionalWorkspaces:、mcp:、ports: 和 sandboxOptions: 的确切字段结构及 YAML 示例。

资源文件

• assets/sbxenv.yaml — 一个完整、精简且安全的示例：一个挂载声明文件所在目录的 shell Agent、一个静态环境变量，且完全不包含凭据——无需任何入门认证即可验证并生成计划。

检查

• checks/verification.md — 用于 sbxenv.yaml 命令的验证操作手册（尚未执行；请手动运行，并使用隔离且名称唯一的 --app-name，切勿使用真实密钥值，也不要自动批准不可信的生命周期命令）。