沙箱环境文件把本地或云沙箱的设置记录在 sbxenv.yaml 文件中。把这个文件分享给项目 协作者，让他们使用相同的智能体、工具、资源和凭据，而不必重新抄写 CLI 标志和设置步骤。
Kits 把软件打包在一起，并声明运行它需要什么。环境文件则选定这些 kits，并配置使用 它们的沙箱，包括它的工作区、资源、凭据和生命周期命令。你可以修改或分享这份配置， 无需重新打包工具。关于 kits 如何提供智能体、工具及其运行时要求，请参阅 Kits。
NOTE
sbx env 仍处于实验阶段。命令接口和文件格式可能会发生变化。
除非另有说明，本页的示例都使用本地沙箱。关于云端配置和生命周期差异，请参阅 使用云环境。
启动一个环境
把环境文件放在你挂载进沙箱的目录之外。这包括主工作区和每一个 additionalWorkspaces 挂载。例如，把它放在项目旁边：
web-app-env/
├── sbxenv.yaml
└── web-app/创建 web-app-env/sbxenv.yaml。这个示例给智能体一个共享的环境变量和 Playwright 浏览器测试工具，同时发布应用的开发端口：
schemaVersion: "1"
name: web-app
agent: claude
workspace: ./web-app
kits:
- docker.io/sbx/playwright:1.61.1
env:
NODE_ENV: test
ports:
- sandbox: 3000
host: 3000在 web-app-env 中运行该环境：
$ sbx env runsbx 会显示环境计划并请求你批准。如果你批准该计划，web-app 目录会成为工作区， 而 sbxenv.yaml 仍留在沙箱之外。如果该环境不存在，sbx 会创建一个名为 web-app 的沙箱，安装 Playwright 和 Chromium，并在宿主机上发布沙箱端口 3000，然后连接到 智能体。之后的运行会连接到已有的沙箱。
保护环境文件
环境文件可以声明在宿主机上运行的生命周期命令、密钥命令和 MCP 命令。请把它们放在可写沙箱挂载 点之外，以免智能体改变后续调用所运行的内容。这同时适用于主工作区和 additionalWorkspaces。
如果你必须把环境文件保留在直接挂载的工作区中，请把它直接放在工作区根目录。 sbx 默认以只读方式挂载该文件，但位于子目录中的文件仍可能通过重命名其父目录来被 替换。
对于你打算让智能体编辑该文件的本地环境，设置 sandboxOptions.writableEnvFiles: true。 计划会报告该文件是可写的。只有在你信任该智能体去修改未来调用会在你的宿主机上执行 的命令时，才使用这个选项。
命令
| 命令 | 说明 |
|---|---|
sbx env plan [PATH...] | 显示应用该环境会做哪些改动，不做改动也不需要批准 |
sbx env run [PATH...] [-- ARG...] | 应用已批准的计划，必要时创建环境，并连接 |
sbx env create [PATH...] | 应用已批准的计划并创建环境，不连接 |
sbx env exec [PATH...] -- COMMAND [ARG...] | 在该环境中运行命令，并在沙箱缺失时以交互方式提示创建 |
sbx env rm [PATH...] | 显示销毁计划，然后移除计划中列出的沙箱和资源 |
要使用某个环境文件，把它的路径传给 sbx env。如果传入一个目录，sbx 会在其中查找 sbxenv.yaml。如果不传路径，sbx 会在你运行命令的目录中查找，并加载你的 用户默认值（如果存在）。
每个 sbx env 子命令都接受 --name。该标志为该命令设置沙箱名称，覆盖文件中的 name 字段或自动生成的名称：
$ sbx env create --name web-app-test
$ sbx env exec --name web-app-test -- npm test
$ sbx env rm --name web-app-test每个命令都使用相同的文件路径。如果设置了 --name，请对每个管理该沙箱的命令使用 同一个名称。
创建环境沙箱
创建沙箱但不连接：
$ sbx env create要创建沙箱并连接到智能体，请改用 sbx env run：
$ sbx env run两个命令都遵循计划批准流程，并运行 initialize生命周期命令。创建沙箱之后，它们会在返回或连接之前运行 postCreate 命令。
要在沙箱中运行命令，请用 sbx env exec。如果沙箱不存在，exec 会在标准输入是 交互式的情况下提示你创建。创建会遵循同样的批准和生命周期流程，然后才运行你的命令。 对于已有沙箱，exec 会跳过生命周期命令。在非交互式标准输入或使用 --no-input 时， 请先用 sbx env create 创建沙箱。请参阅 在自动化中复用环境。
设置用户默认值
创建 ~/.sbxenv.yaml 以在各个项目之间共享设置。例如，这个文件选择 Claude 作为 智能体，并挂载你运行 sbx env 时所在的目录：
schemaVersion: "1"
agent: claude
workspace: ${{ env.projectDir }}把这个文件保存在你的主目录中，然后运行：
$ cd /projects/web-app
$ sbx env run沙箱会把 /projects/web-app 作为工作区挂载。在 /projects/api 中运行同一条命令， 它挂载的则是 /projects/api。两个项目中你都不需要单独的 sbxenv.yaml。
如果项目中有 sbxenv.yaml，sbx 会把它与你的用户默认值合并。项目设置覆盖各个 默认值。列表会合并两个文件的条目，其中匹配的端口、MCP 服务器名称和附加工作区目标 使用项目中的条目。有关详情，请参阅合并规则。 如果你向命令传入文件或目录路径，sbx 会跳过 ~/.sbxenv.yaml。
在 ~/.sbxenv.yaml 中，你可以把 workspace 设为 ${{ env.projectDir }} 或类似 ${{ env.projectDir }}/src 的子目录。该文件不接受其他工作区路径。
用户默认值文件不能设置 name。请在项目环境文件中或用 --name 设置沙箱名称。
引用目录
你可以在环境文件中使用 ${{ env.projectDir }} 和 ${{ env.fileDir }} 来插入绝对 目录路径。它们指向宿主机上的目录。
项目目录
${{ env.projectDir }} 是你项目目录的绝对路径。sbx 根据你运行的命令选择这个 目录：
sbx env run：你运行命令时所在的目录。sbx env run /projects/web-app：/projects/web-app。sbx env run /projects/web-app/custom.yaml：/projects/web-app，即包含该文件的目录。
如果你传入多个路径，第一个路径决定项目目录。该命令加载的每个文件都使用同一个 env.projectDir 值。
在需要指向各自项目文件的共享设置中使用这个引用。例如，workspace: ${{ env.projectDir }}/src 会挂载你所选项目中的 src 目录。
文件目录
${{ env.fileDir }} 是包含你写入该引用的那个环境文件的目录的绝对路径。例如，在 /shared/environment.yaml 中，它的值是 /shared。
当环境文件需要定位与它存放在一起的文件时，使用这个引用。例如，假设你的设置脚本是 /shared/scripts/setup.sh。把下面这个生命周期命令加入 /shared/environment.yaml，以便从 /shared 运行该脚本：
lifecycle:
initialize:
- command: ./scripts/setup.sh
workdir: ${{ env.fileDir }}即使你把该环境文件与另一个目录中的项目一起使用，该命令也会从 /shared 运行。
相对工作区路径本来就使用包含环境文件的目录。例如，/shared/environment.yaml 中的 workspace: ./src 会挂载 /shared/src。
两个目录引用都可以出现在 YAML 的值中，但不能出现在字段名中，也不能用在 args 块 内部。
为环境参数化
当同一个环境文件在不同使用场景下需要不同的值时，在顶层 args 块中声明输入。每个 参数必须恰好设置 default 或 required: true 之一：
schemaVersion: "1"
name: web-app
agent: claude
args:
channel:
default: stable
description: 发布通道
enum:
- stable
- beta
endpoint:
required: true
description: API 端点
cpus:
default: "4"
pattern: "[1-9][0-9]*"
env:
RELEASE_CHANNEL: ${{ env.args.channel }}
API_ENDPOINT: ${{ env.args.endpoint }}
sandboxOptions:
cpus: ${{ env.args.cpus }}在任何可以出现 YAML 值的地方，都可以用 ${{ env.args.NAME }} 引用已声明的参数。 引用不能用在字段名中，也不能用在 args 块内部。未加引号的引用在替换后会被当作 YAML 值解释，因此本例中的 cpus 值会变成整数。给引用加引号可将其保留为字符串。
所有 sbx env 命令都接受可重复的 --env-arg NAME=VALUE 标志。用标志提供的值会 替换环境文件中的默认值：
$ sbx env run --env-arg endpoint=https://api.example.com --env-arg channel=beta用 --env-args-file 从文件中加载值。每个非空、非注释的行都必须采用 NAME=VALUE 的形式：
# production.args
channel=beta
endpoint=https://api.example.com$ sbx env run --env-args-file production.args你可以传入多个参数文件。后面的文件优先于前面的文件，而 --env-arg 标志优先于 所有参数文件。值中可以包含 =，参数文件中的值按字面读取，不会由 shell 展开。
参数引用和两个目录引用是环境文件中仅有的会被展开的变量表达式。${VAR} 之类的 shell 风格表达式不会从宿主机环境中展开。其他美元符号保持字面不变，因此像 $PATH:/opt/bin 这样的值会原样传递。 用 $${{ env.args.NAME }} 可以生成字面文本 ${{ env.args.NAME }}。被替换的值不会被 二次展开。
常见工作流
下面的示例把环境文件字段组合成你可以针对项目改造的配置。
添加 v3 kits
要为内置智能体添加 mixins，请在 kits 中列出这些 mixins，并在 agent 中使用内置 名称。
例如，把下面内容保存为 web-app-env/v3.sbxenv.yaml，以使用 Claude Code workload 搭配 Playwright mixin：
schemaVersion: "1"
name: web-app-v3
agent: claude
workspace: ./web-app
kits:
- docker.io/sbx/playwright:1.61.1在 web-app-env 中运行：
$ sbx env run v3.sbxenv.yamlagent 的值会选中内置的 Claude Code workload。名称 web-app-v3 会创建一个独立的 沙箱。关于其他智能体，请参阅 已发布的 v3 workloads。
设置启动命令
设置 entrypoint 和 cmd 来选择 sbx env run 在沙箱内执行什么。例如，把以下字段 加入你的环境文件，以打印两个参数：
entrypoint: [/usr/bin/printf, '%s\n']
cmd: [default, 'two words']$ sbx env run
default
two words每个字段都是一个字符串列表。sbx 会把 cmd 追加到 entrypoint，并把每一项保留 为一个参数，包括含空格和空字符串的项。参数不会被解释为 shell 表达式。要运行 shell 表达式，请显式使用 shell，例如 entrypoint: [/bin/sh, -c]。
-- 之后的参数会替换本次运行的 cmd，并保留 entrypoint：
$ sbx env run -- 'replacement argument'
replacement argument省略某个字段或把它设为 null，可以继承更早的环境文件中的值；如果没有任何文件设置 它，则继承智能体的默认值。把某个字段设为 [] 可将其清空。组合后的命令仍必须以 非空的可执行文件开头。合并多个文件时，后面的 entrypoint 和 cmd 列表会替换前面的 列表，而不是追加。
这些设置仅适用于 sbx env run。它们不会改变已发布的 kit、它保存的启动器、 sbx env exec 或沙箱的 PID 1。使用 --detach 时，run 只启动沙箱，不执行启动 命令。你不能把 --detach 与 -- 之后的参数组合使用。
合并团队默认值与个人设置
把共享配置放在版本控制中、位于挂载工作区之外的环境目录里。把与具体机器相关的设置 放在不纳入版本控制的文件中。例如，把 base.sbxenv.yaml 提交到 web-app 目录旁边：
schemaVersion: "1"
name: web-app
agent: claude
workspace: ./web-app
env:
NODE_ENV: development
sandboxOptions:
cpus: 4
memory: 8g把 local.sbxenv.yaml 加入 .gitignore，然后用它存放个人设置：
env:
LOG_LEVEL: debug
sandboxOptions:
memory: 12g按合并顺序传入两个文件：
$ sbx env run base.sbxenv.yaml local.sbxenv.yaml在这个示例中，沙箱有 4 个 CPU、12 GB 内存，以及两个环境变量。每个相对工作区路径 都相对于声明它的文件所在目录解析。
合并规则
文件按你传入的顺序合并。后面的标量值会覆盖前面的值，而嵌套映射按键合并。大多数 列表会追加来自每个文件的条目。例外情况如下：
ports、mcp.servers和additionalWorkspaces：匹配的条目使用最后一个条目， 详见覆盖列表条目。kits：来源相同的条目会按键合并它们的参数。后面的参数值优先，其他参数保留。entrypoint和cmd：后面的列表会替换前面的列表。有关继承和清空，请参阅 设置启动命令。
覆盖列表条目
要覆盖某个端口、MCP 服务器或附加工作区，请在文件中的更靠后位置，或在更靠后的文件 中声明一个匹配的条目。最后一个条目会替换整个更早的条目，并保留它在列表中的第一个 位置。不匹配的条目会作为独立条目保留。
例如，在你的个人设置中更改沙箱端口 8080 对应的宿主机端口：
# base.sbxenv.yaml
ports:
- sandbox: 8080
host: 3000# local.sbxenv.yaml
ports:
- sandbox: 8080
host: 4000先加载 base.sbxenv.yaml 时，结果是一个端口条目，把沙箱端口 8080 发布到宿主机 端口 4000。
请在替换项中包含你想保留的每一个字段。省略的字段会使用它们的默认值：本例中省略 host 会选择一个临时宿主机端口。同样地，从替换后的工作区中省略 readOnly 会让 它变为可写。
sbx 使用以下字段来判断条目是否匹配：
| 列表 | 匹配字段 |
|---|---|
ports | 沙箱端口和生效的协议 |
mcp.servers | 完全一致的服务器名称 |
additionalWorkspaces | 容器目标：显式的 target，或在省略 target 时解析出的宿主机路径 |
端口协议名称不区分大小写。省略协议时使用 tcp4，对于 IPv6 的 hostIP 则使用 tcp6。不同的协议（例如 tcp 和 tcp4）仍然是分开的。
在 macOS 上，隐式的工作区目标会在可用时使用已存储的宿主机路径大小写。显式目标仍然 区分大小写。
合并之前，每个源文件都必须包含有效的字段和值。后面的覆盖无法修正前面文件中的 无效值。这同样适用于从 ~/.sbxenv.yaml 加载的用户默认值。
跨多个仓库工作
当智能体需要协调改动或查阅共享的代码和文档时，把相关仓库与主项目一起挂载：
# sbxenv.yaml in the directory above the repositories
schemaVersion: "1"
name: web-platform
agent: codex
workspace: ./web-app
additionalWorkspaces:
- path: ./shared-components
- path: ./architecture-docs
readOnly: true智能体从 web-app 启动，可以修改 shared-components，也可以读取 architecture-docs 但不能更改它。环境文件留在三个工作区之外。相对路径相对于声明它们的环境文件所在 目录解析。即使主工作区使用克隆模式，附加工作区仍会被直接挂载。
在自动化中复用环境
同一个提交到版本库的环境，既可用于交互式开发，也可用于自动化任务。开发者用 run 连接到智能体：
$ sbx env run自动化可以不连接就创建沙箱、在其中运行命令，之后再将其移除：
$ sbx env create --force
$ sbx env exec -- npm test
$ sbx env rm --force对于 create 和 run，--force 只为本次调用批准计划，不会为后续调用记录同意。 请对每次无人值守的 create 或 run 都使用该标志。对于 rm，--force 批准销毁 计划，即使沙箱正在使用中也会将其移除。
secrets 下的命令和 vault 引用在宿主机上解析，因此自动化运行器必须提供相应的 工具和身份验证。密钥值仍然留在环境文件之外。
使用云环境
用 sbx --cloud env 可以从环境文件在 Docker 托管的基础设施上创建沙箱。云沙箱不会 挂载或同步本地项目文件，本地凭据对它们也不可用。你把文件复制进沙箱或在其中克隆 仓库，然后在移除沙箱之前取回你的工作成果。
关于完整示例、受支持的设置和生命周期差异，请参阅 在云端使用环境文件。
审阅环境计划
sbx env create、sbx env run 和 sbx env rm 会显示一个环境在沙箱之外所做的 改动，并在应用之前请求批准。计划包含宿主机命令、凭据、绑定、MCP 注册、目录、 kits、已发布端口、沙箱选项和环境变量。
运行 sbx env plan 可以在不做改动、不批准、也不记录任何内容的情况下查看应用计划：
$ sbx env plan该计划会把环境文件与环境上一次应用的状态以及宿主机上的资源进行对比。它会省略未 变化且已经批准的字面密钥值。密钥引用、宿主机命令、环境变量、端口、路径和绑定域名 仍然可见，方便你审阅。
改动会出现在与环境文件相同的键和嵌套结构下。例如，这个计划把 GOFLAGS 从 -mod=mod 改为 -mod=readonly：
env:
~ GOFLAGS: -mod=mod -> -mod=readonly批准计划之前，请先读懂每个条目旁边的符号：
| 符号 | 应用该条目的效果 |
|---|---|
+ | 添加资源 |
~ | 更改资源 |
- | 销毁资源 |
> | 再次运行宿主机命令 |
! | 停止跟踪某个不再声明的资源，但不删除它 |
交互式批准会按环境记录在 sbx 状态目录下。不含宿主机命令的计划在后续调用中会 静默应用，直到该环境发生变化或某个资源缺失。用 --force 提供的批准仅对本次调用 有效。
批准或跳过宿主机命令
默认情况下，包含生命周期命令、凭据 command 来源或本地 MCP 命令的计划每次调用都 需要批准，即使命令文本没有变化。用 --force 批准一次调用，用 --skip-host-commands 跳过生命周期和 MCP 命令，或开启 env.rememberHostCommands 以在命令发生变化 之前记住批准：
$ sbx settings set env.rememberHostCommands true要在不运行生命周期命令和本地 MCP 命令的情况下运行一个环境，请使用：
$ sbx env run --skip-host-commands该标志还会在请求你批准计划之前禁用此前已批准的 MCP 命令。即使你取消计划或重启 守护进程，它们仍保持禁用。要再次启用它们，请不带该标志运行 sbx env run 并批准 计划。当需要相应密钥时，凭据 command 来源仍会运行。
丢失环境状态后的恢复
如果 sbx env run 报告某个本地沙箱"与此环境声明的一切一致"但"什么也没有做"， 那么该沙箱仍然存在，但 sbx 无法验证它是否属于这个环境。这可能发生在升级或状态 重置丢失该环境的记录之后。
要在不删除并重建该沙箱的情况下继续使用它，请在交互式终端中用同样的环境文件路径 和沙箱名称运行 sbx env run。该命令会询问你是否接管该沙箱。只有当这正是你希望该 环境管理的沙箱时才确认，然后审阅并批准环境计划。之后的运行会识别出该沙箱， sbx env rm 也能移除它。
对于因这个错误而失败的自动化运行，请先以交互方式完成该恢复，再重试自动化。 --force 会批准计划，但不会确认接管。只有 sbx env run 提供接管，而且仅在沙箱与 该环境的声明相匹配时才提供。
更新环境
对于已有沙箱，sbx env run 会把更新后的 env 值应用到新的智能体会话，并重新协调 已声明的 MCP 服务器。对工作区、kit 宿主机挂载、kits、端口、密钥、绑定和 sandboxOptions 的更改，只有在下次创建沙箱时才会生效。请用 sbx env rm 移除该 环境，然后重新创建，以应用这些更改。
对 entrypoint 和 cmd 的更改会在每次 sbx env run 时生效，无需重建沙箱。如果 你还更改了 agent，请在继承该智能体默认值的部分启动覆盖生效之前重建该环境。等价 的智能体名称和别名不需要重建。
移除环境
密钥和镜像仓库凭据是沙箱级作用域的。凭据绑定和远程 MCP 服务器注册则是宿主机全局 的，可以被多个沙箱共享。由该环境声明的本地 MCP 命令属于该环境和该沙箱。
sbx env rm 根据宿主机上的资源构建销毁计划。计划包含所有以该沙箱作用域存储的 凭据，包括环境文件已不再声明的凭据。批准之后，sbx 只移除计划中列出的资源。
除非你传入 --prune-bindings，全局凭据绑定会保留。远程 MCP 注册对其他沙箱仍然 可用。移除一个本地环境会吊销并移除它所注册的 MCP 命令。
创建失败后的清理
密钥的配置、绑定的更新和 MCP 服务器的注册都在沙箱创建之前进行。如果沙箱创建失败， 作用域限定的密钥会保留，绑定和 MCP 注册也可能保留。请用相同的路径运行 sbx env rm 以移除作用域限定的密钥。如果你还想移除已声明的全局绑定，请传入 --prune-bindings。远程 MCP 注册在清理之后仍然保留。如果某个环境 MCP 命令注册 无法移除，请参阅 恢复冲突的 MCP 注册。
文件参考
顶层字段
| 字段 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
schemaVersion | string | 是 | 无 | Schema 版本。受支持的值为 "1" |
name | string | 否 | <agent>-<workspace-basename> | 沙箱名称，可被 --name 覆盖 |
agent | string | 是 | 无 | 内置智能体或某个智能体 kit 的名称 |
entrypoint | 字符串 list | 否 | 智能体默认值 | run 的启动可执行文件和固定参数。请参阅设置启动命令 |
cmd | 字符串 list | 否 | 智能体默认值 | 追加到 entrypoint 的默认参数；-- 之后的参数会替换这个列表 |
args | map | 否 | 无 | 环境参数。请参阅 args |
kits | list | 否 | 无 | 创建时安装的 kits。请参阅 kits |
workspace | string 或 object | 否 | 不挂载宿主机目录 | 主工作区。请参阅 workspace |
additionalWorkspaces | list | 否 | 无 | 额外挂载的目录。请参阅 additionalWorkspaces |
mounts | 字符串 map | 否 | 无 | kit 声明的挂载对应的宿主机目录。请参阅 mounts |
env | 字符串 map | 否 | 无 | 沙箱的环境变量 |
sandboxOptions | object | 否 | 无 | 创建选项。请参阅 sandboxOptions |
secrets | map | 否 | 无 | 服务凭据。请参阅 secrets |
bindings | map | 否 | 无 | 凭据注入批准。请参阅 bindings |
registries | map | 否 | 无 | 镜像仓库拉取凭据。请参阅 registries |
mcp | object | 否 | 无 | MCP 服务器。请参阅 mcp |
ports | list | 否 | 无 | 端口映射。请参阅 ports |
lifecycle | object | 否 | 无 | 宿主机命令。请参阅 lifecycle |
args
args 把参数名映射到它们的声明。名称必须以字母或下划线开头，可以包含字母、 数字、下划线和连字符。每个声明必须恰好设置 default 或 required: true 之一。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
default | string | 无 | 命令未提供该参数时使用的值 |
required | boolean | false | 要求命令提供该参数 |
description | string | 无 | 命令输出中显示的说明 |
enum | 字符串 list | 无 | 该参数可接受的值 |
pattern | string | 无 | 与完整参数值匹配的 Go（RE2）表达式 |
enum 和 pattern 不能同时使用。
kits
kits 接受本地目录、ZIP 压缩包、OCI 镜像仓库引用，以及以 git+https:// 或 git+ssh:// 为前缀的 Git URL。Kits 可以安装工具、配置沙箱，并给智能体提供项目 专属的说明。要为内置智能体添加 mixins，请参阅 添加 v3 kits。
环境文件选定 kits 并配置沙箱的宿主机资源。kit 描述文件定义软件包本身。环境文件的 schemaVersion 与 kit 描述文件中的 schema 版本相互独立。
显式的相对路径相对于声明它们的环境文件所在目录解析。这包括 .、..、以 ./ 或 ../ 开头的路径，以及以 .zip 结尾的相对路径。像 organization/kit 这样的 裸引用仍然是镜像仓库引用。
用对象形式的条目向 kit 传递参数。把 source 设为 kit 引用，并在 args 下把 kit 的参数名映射到对应的值：
kits:
- source: ./kits/tool
args:
version: ${{ env.args.channel }}远程 kit 来源必须符合 kit.allowedSources 设置。 默认允许 Docker Hub。要使用来自 docker/sbx-kits-contrib 的 Git kits，请添加它的 来源：
$ sbx settings set kit.allowedSources '["docker.io/","github.com/docker/"]'该设置会替换完整的允许列表，因此要包含你想保留的任何已有来源。为了获得可复现的 安装，请用 ref URL 参数固定 Git kits 的版本，用不可变的标签或摘要固定 OCI kits。
workspace
以字符串形式指定时，workspace 就是路径。克隆模式请使用对象形式。省略 workspace 可创建一个没有宿主机绑定挂载的沙箱。设置 workspace: . 会挂载包含声明它的那个 环境文件所在的目录。
关于环境文件的放置和写保护，请参阅 保护环境文件。
| 字段 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
path | string | 是 | 无 | 工作区目录。相对路径相对于声明它的文件所在目录解析 |
clone | boolean | 否 | false | 使用私有克隆，等价于 sbx create --clone |
你可以在某次 create 或 run 调用中用 --clone 或 --clone=false 覆盖 workspace.clone。
additionalWorkspaces
每个附加工作区都在主工作区之后挂载。相对路径相对于声明它们的环境文件所在目录解析。
| 字段 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
path | string | 是 | 无 | 要挂载的目录 |
target | string | 否 | 沙箱内的宿主机路径 | 沙箱内的绝对 POSIX 路径 |
readOnly | boolean | 否 | false | 以只读方式挂载该目录 |
例如，把一个共享库目录以只读方式挂载到所选路径：
workspace: .
additionalWorkspaces:
- path: ../shared-libs
target: /workspace/libs
readOnly: true省略 target 会使用沙箱内的宿主机路径。相同的目标限制 适用于 sbx create 和 sbx run。
mounts
mounts 为本地沙箱中 kit 声明的宿主机挂载 选择宿主机目录。把每一个 kit 声明的沙箱路径映射到一个已存在的宿主机目录。相对宿主机 路径相对于声明它们的环境文件解析：
mounts:
/home/agent/history: ./history目标必须与所选 kits 中某一个声明的 host-mount@1 路径相匹配。绑定在创建沙箱时 生效。
sandboxOptions
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
template | string | 无 | 自定义沙箱模板镜像 |
memory | string | 无 | 内存上限，例如 8g 或 512m |
cpus | integer | 0 | CPU 数量。0 表示选择宿主机默认值 |
pullPolicy | string | always | 镜像拉取策略：always、missing 或 never |
profile | string | 无 | 治理配置文件名称 |
skills | string | 守护进程默认值 | 共享智能体技能存储的访问权限：off、readonly 或 readwrite |
display | boolean | false | 为图形应用配置显示套接字 |
fuse | boolean | sandbox.fuse 设置 | 挂载 FUSE 文件系统；仅限本地 |
gpu | boolean | false | 把宿主机 GPU 直通给沙箱 |
usb | 字符串 list | 无 | 要直通给沙箱的 USB 设备选择器 |
writableEnvFiles | boolean | false | 允许沙箱写入共享的环境文件；仅限本地 |
对于本地沙箱，cpus: 0 会分配全部宿主机 CPU，但在 Linux arm64 宿主机上默认值上限 为 16。把 cpus 设为明确的数量可以申请更大的配额，最高不超过可用的宿主机 CPU 数量。直接用 sbx create 或 sbx run 创建沙箱时，用 --cpus 做同样的覆盖。 云端资源上限必须匹配某个云端规格。
skills 控制对共享智能体技能存储的访问权限。 把它设为 off 可省略该挂载，设为 readonly 会以只读方式挂载该存储，设为 readwrite 则允许沙箱修改共享技能。如果省略，则使用守护进程的默认值，即 readonly，除非你的组织覆盖了它。
把 fuse 设为 false 可为该沙箱禁用 FUSE 访问。有关默认值以及更改何时生效，请参阅 sandbox.fuse 设置。
lifecycle
lifecycle 块声明在宿主机上以你的用户权限运行的命令。必须在沙箱之外完成的工作， 例如创建工作区、填充测试数据或归档状态，都适合用生命周期命令来实现。
lifecycle:
initialize:
- name: Prepare workspace
command: test -d web-app || git clone https://github.com/example/web-app
timeout: 5m
postCreate:
- command: ./scripts/seed-fixtures.sh
workdir: web-app
preRemove:
- command: ./scripts/archive-state.sh生命周期阶段在以下时机运行：
| 阶段 | 时机 |
|---|---|
initialize | 在其他创建或运行操作之前。每次 create 和 run 都会运行 |
postCreate | 新沙箱创建之后。对于 run，在连接之前。连接到已有沙箱时不运行 |
preRemove | 在你批准移除之后、sbx 删除资源之前。失败会产生警告，移除继续进行 |
关于 sbx env exec 的生命周期行为，请参阅 创建环境沙箱。
同一个阶段内的命令按顺序运行，在第一次失败时停止。请确保 initialize 中的命令可以 安全地重复运行。
preRemove 命令执行完毕后，sbx 会重新生成销毁计划。如果这些命令引入了未包含在 已批准计划中的改动，移除操作会停止。
每个命令都必须有 command，并接受以下字段：
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | string | 命令文本 | 在进度和计划输出中显示的标签 |
command | string | 无 | 传递给用户 shell 的命令 |
workdir | string | 项目目录 | 宿主机工作目录。相对路径相对于第一个文件的目录解析 |
timeout | string | 无 | 最长运行时间，例如 90s 或 5m |
命令继承 sbx 进程的环境，并获得以下变量：
| 变量 | 值 |
|---|---|
SBX_LIFECYCLE_PHASE | 运行该命令的阶段：initialize、postCreate 或 preRemove |
SBX_ENV_FILE | 合并顺序中最后一个环境文件的绝对路径 |
SBX_ENV_FILES | 合并顺序中所有环境文件的绝对路径，在 macOS 和 Linux 上用 : 分隔，在 Windows 上用 ; 分隔 |
SBX_ENV_DIR | 项目目录，用作默认的宿主机工作目录 |
SBX_SANDBOX_NAME | 解析后的沙箱名称，包括任何 --name 覆盖 |
SBX_AGENT | 解析后的智能体名称 |
SBX_WORKSPACE | 宿主机上的主工作区路径。未声明工作区时为空，云环境也为空 |
对于云环境，生命周期命令运行的 sbx 命令会继承云模式和所选端点。例如，生命周期 命令中的 sbx cp 即使不带 --cloud 也会作用于云端。
环境文件的 env 值和解析出的密钥不会传给宿主机命令。
secrets
secrets 把服务名映射到密钥来源。每个条目必须恰好设置 value、ref 或 command 之一。创建环境时，密钥会存储在沙箱作用域上。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
value | string | 无 | 字面密钥值 |
ref | string | 无 | Vault URI，例如 op://Vault/Item/field |
command | string | 无 | 标准输出成为密钥的宿主机 shell 命令 |
snapshot | boolean | false | 在宿主机上一次性解析 ref 或 command，并把结果作为字面量存储 |
refresh | string | 无 | ref 或 command 的解析策略，例如 on-demand 或 55m |
backend | string | 自动 | ref 的解析器：sdk 或 cli |
noVerify | boolean | false | 跳过验证 ref 或 command 在配置期间能否解析 |
WARNING
字面 value 对任何能读取该文件的人都可见。请改用带 ref 的 vault URI，或用 command 在运行时获取该值。
secrets:
anthropic:
ref: op://Private/Anthropic/api-key
refresh: 55m
github:
command: gh auth token密钥命令在宿主机上一个全新的临时目录中执行。相对的辅助工具路径相对于该目录解析。 请把辅助工具及其依赖放在可写沙箱挂载点之外。请使用绝对路径、绝对的宿主机 PATH 条目，或显式切换到辅助工具的私有目录。请参阅 动态密钥来源。
内置的 1Password 和 AWS Secrets Manager 引用同样从临时目录运行，并要求提供商工具 位于宿主机 PATH 的绝对路径目录中。有关提供商配置要求，请参阅 动态密钥来源。
对于云环境，请在 ref 或 command 来源上设置 snapshot: true：
secrets:
github:
command: gh auth token
snapshot: true该命令在计划批准之后于宿主机上运行。解析出的值会作为字面密钥存储，不会刷新。 要轮换它，请重新创建该环境。快照同样适用于本地环境。快照不能设置 refresh 或 noVerify。云端快照对 vault 引用使用 CLI 解析器，不支持 backend: sdk。
bindings
bindings 为每个服务批准凭据注入的域名。该环境会把这些批准合并到用户的全局 credentials.yaml 中。每个服务可以包含一个 apiKey 块、一个 oauth 块，或两者 都有。每个块包含一个 domains 列表：
bindings:
github:
apiKey:
domains:
- api.github.comsbx env rm 默认保留全局绑定。传入 --prune-bindings 会移除环境文件声明的每一个 服务绑定。
WARNING
--prune-bindings 会删除环境文件中声明的每个服务的完整全局绑定条目。这可能影响 共享这些服务绑定的其他沙箱。
registries
registries 把镜像仓库主机名映射到拉取凭据。每个条目都要求有 secret，并接受 可选的 username。两个字段都接受密钥来源，且必须恰好包含 value、ref 或 command 之一。
省略 username 时，sbx 会存储仅含令牌的凭据。GHCR 和 GitLab 等镜像仓库接受 仅含令牌的凭据。
registries:
ghcr.io:
secret:
command: gh auth tokenmcp
mcp.servers 列表把服务器注册到内置的 MCP 网关，并把它们加入沙箱。用 url 注册的远程服务器是宿主机 全局的，在 sbx env rm 之后仍然保留。在本地环境中，用 command 注册的服务器属于 该环境，并且只能为它的沙箱运行。
| 字段 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
name | string | 是 | 无 | 服务器名称 |
url | string | 否 | 无 | 远程服务器 URL、镜像仓库引用或 OCI 引用 |
command | string | 否 | 无 | 本地 stdio 服务器的命令 |
args | 字符串 list | 否 | 无 | 传递给 command 的参数 |
每个服务器必须恰好设置 url 或 command 之一。
批准本地 MCP 命令
command 服务器会在沙箱的 MCP 网关启动时（重启后也一样）以你的权限在宿主机上运行。 环境计划会在注册之前显示解析出的可执行文件和参数。批准会锁定可执行文件的路径，而不 是锁定可执行文件、脚本或它们加载的包的内容。请把这些文件放在可写沙箱挂载点之外。
如果某个 initialize 命令创建了该可执行文件或改变了它解析出的路径，sbx 会在 初始化之后请求你批准解析出的 MCP 命令。拒绝该批准会保留已完成的初始化工作，但不会 注册该命令。--force 会为该次调用同时批准这两个阶段。
从文件中移除某个命令并应用该环境，会吊销它的注册。sbx env rm 会移除该环境的命令 注册。
恢复冲突的 MCP 注册
一个环境无法接管手动注册或由另一个环境注册的命令，即使它们的可执行文件和参数完全 相同。请选择另一个服务器名称，或在应用该文件之前移除冲突的注册。
对于遗留或损坏的注册，请先停止守护进程，再只移除它保存的注册：
$ sbx daemon stop
$ sbx mcp rm --registration-only -- <SERVER_NAME>当同一个名称被多个沙箱拥有的注册共享时，用 --sandbox 选定所属的沙箱：
$ sbx daemon stop
$ sbx mcp rm --registration-only --sandbox <SANDBOX_NAME> -- <SERVER_NAME>这只会移除所选沙箱的注册，包括损坏的沙箱级记录，并保留其他所有者的注册。沙箱选择 要求未限定作用域的记录具有有效且可读的所有权元数据；--sandbox 无法恢复损坏的 未限定作用域的记录。
停止守护进程会中断它的沙箱网关。仅移除注册不会删除已保存的凭据，也不会停止已经在 运行的 MCP 进程。请再次应用该环境，为它的沙箱注册并批准该命令。
ports
ports 在创建环境时发布沙箱端口。由 kit 暴露但未在此列表中列出的端口会获得一个 临时宿主机端口。
| 字段 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
sandbox | integer | 是 | 无 | 沙箱端口，取值 1 到 65535 |
host | integer | 否 | 临时端口 | 宿主机端口，取值 1 到 65535 |
protocol | string | 否 | tcp4，IPv6 hostIP 时为 tcp6 | tcp、tcp4、tcp6、udp、udp4 或 udp6 |
hostIP | string | 否 | 回环地址 | 要绑定的宿主机网络接口 |
设置 protocol: tcp 可同时绑定 IPv4 和 IPv6。不要设置 hostIP，以获得双栈绑定， 因为显式地址只会绑定其自身的 IP 族。
如果某个端口无法发布，沙箱创建会失败，并移除新建的沙箱。