docker-sandboxes-env

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docker Sandboxes: Declarative sbxenv.yaml Environments

Docker Sandboxes: 声明式 sbxenv.yaml 环境

Overview

概述

sbxenv.yaml

(schemaVersion

"1"

, EXPERIMENTAL) declaratively describes one sandbox environment — agent, mixin kits, workspace mounts, environment variables, secrets/registries/bindings to provision, MCP servers, ports, and host-side lifecycle commands — so

sbx env create|run|plan|exec|rm

can stand it up and tear it down reproducibly instead of a long flag invocation. This skill owns that file format end to end. It delegates the sandbox lifecycle semantics it wraps, the credential/network model it provisions into, and the kit schema its

kits:

entries reference, to their own skills.

sbxenv.yaml

（schemaVersion

"1"

，实验性）声明式地描述一个 sandbox 环境——agent、mixin kit、工作区挂载、环境变量、要配置的 secrets/registries/bindings、MCP 服务器、端口，以及宿主侧生命周期命令——使

sbx env create|run|plan|exec|rm

能够以可重现的方式创建和销毁它，而不是使用一长串标志调用。本 skill 全权负责该文件格式。它将所包装的 sandbox 生命周期语义、其配置所依赖的凭据/网络模型，以及

kits:

条目引用的 kit schema，委托给各自的 skill。

When to use this skill

何时使用本 skill

Activate this skill when:

The user wants a checked-in, reproducible definition of a sandbox environment instead of a long
```
sbx create
```
/
```
sbx run
```
command line.
The user wants host-side setup/teardown commands (cloning a repo, seeding fixtures, archiving state) tied to a sandbox's create/attach/remove lifecycle.
The user wants to parameterize a shared environment file with named arguments (
```
args:
```
+
```
--env-arg
```
).
The user is debugging why
```
sbx env create
```
/
```
run
```
is asking for approval, or why a file, kit, or secret it declares was skipped or flagged.

在以下情况激活此 skill：

用户想要一个可入库、可重现的 sandbox 环境定义，而不是一长串
```
sbx create
```
/
```
sbx run
```
命令行。
用户想要将宿主侧设置/清理命令（克隆仓库、填充 fixtures、归档状态）绑定到 sandbox 的 create/attach/remove 生命周期。
用户想要使用命名参数（
```
args:
```
+
```
--env-arg
```
）参数化一个共享环境文件。
用户正在调试为什么
```
sbx env create
```
/
```
run
```
要求审批，或者为什么它声明的文件、kit 或 secret 被跳过或被标记。

Do not use this skill when

不要使用本 skill 的情况

Do not use this skill when:

The task is the underlying
```
sbx create
```
/
```
run
```
/
```
rm
```
flag-based workflow with no
```
sbxenv.yaml
```
file involved — use
```
docker-sandboxes-lifecycle
```
.
The task is choosing network policy or storing a secret/registry credential independent of any environment file — use
```
docker-sandboxes-network-credentials
```
(this skill's
```
secrets:
```
/
```
registries:
```
/
```
bindings:
```
blocks provision into that same store, but do not redefine its rules here).
The task is authoring the kit
```
spec.yaml
```
a
```
kits:
```
entry points at — use
```
docker-sandboxes-kits
```
.

不要使用本 skill，当：

任务是底层基于
```
sbx create
```
/
```
run
```
/
```
rm
```
标志的流程，且不涉及任何
```
sbxenv.yaml
```
文件——请使用
```
docker-sandboxes-lifecycle
```
。
任务是选择网络策略或存储与任何环境文件无关的 secret/registry 凭据——请使用
```
docker-sandboxes-network-credentials
```
（本 skill 的
```
secrets:
```
/
```
registries:
```
/
```
bindings:
```
块会配置到同一存储中，但不会在此重新定义其规则）。
任务是编写
```
kits:
```
条目所指向的 kit
```
spec.yaml
```
——请使用
```
docker-sandboxes-kits
```
。

Core guidance

核心指导

File resolution and required fields

文件解析与必填字段

The file
```
sbx env
```
reads from a directory is exactly
```
sbxenv.yaml
```
— no other name, and a directory-named
```
.sbxenv.yaml
```
at the project level is not read as a project's own file (only the home-directory base layer uses that hidden name; see below).
Every environment file requires
```
schemaVersion: "1"
```
and
```
agent:
```
(a built-in agent name or the manifest name of an agent kit supplied via
```
kits:
```
). Everything else is optional.
```
agent: shell
```
needs no credentials and is the simplest way to validate a file's mechanics.
```
sbx env create|run|plan|exec|rm
```
accept one or more
```
PATH
```
arguments. Each
```
PATH
```
is either a directory (resolved to
```
<PATH>/sbxenv.yaml
```
) or the file itself. Passing more than one deep-merges them in declaration order — docker compose -f
-style semantics: later files override earlier ones, mappings merge key-by-key, sequences concatenate.
bash
```
sbx env create sbxenv.yaml override.yaml
```

```
sbx env
```
从目录读取的文件恰好是
```
sbxenv.yaml
```
——没有其他名称，项目级别的
```
.sbxenv.yaml
```
不会作为项目自身的文件被读取（只有主目录基础层使用该隐藏名称；见下文）。
每个环境文件都需要
```
schemaVersion: "1"
```
和
```
agent:
```
（一个内置 agent 名称，或通过
```
kits:
```
提供的 agent kit 的 manifest 名称）。其他一切均可选。
```
agent: shell
```
不需要任何凭据，是验证文件机制的最简单方式。
```
sbx env create|run|plan|exec|rm
```
接受一个或多个
```
PATH
```
参数。每个
```
PATH
```
要么是目录（解析为
```
<PATH>/sbxenv.yaml
```
），要么是文件本身。传递多个时会按声明顺序进行深层合并——docker compose -f
风格语义：后面的文件覆盖前面的文件，映射按键逐一合并，序列拼接。
bash
```
sbx env create sbxenv.yaml override.yaml
```

Naming, workspace, and the

.sbxenv.yaml

user base layer

命名、工作区与

.sbxenv.yaml

用户基础层

Unless the file sets
```
name:
```
or
```
--name
```
overrides it, the sandbox is named after the mounted directory (or the project directory when nothing is mounted) — so an environment that mounts nothing is still the same sandbox every time it is applied. Two different environment files in the same directory derive the same sandbox name and collide unless each sets its own
```
name:
```
(or you pass a distinct
```
--name
```
per invocation) — always give each environment its own explicit
```
name:
```
when more than one may exist in the same directory.
```
workspace:
```
names the read/write mount, exactly like
```
sbx create
```
's omitted-path behavior: omitting
workspace:
mounts nothing at all. A relative
```
workspace:
```
path resolves against the directory of the file that declares it —
```
workspace: .
```
mounts the directory the file sits in.
```
${{ env.projectDir }}
```
names the project directory (the one holding the first
```
PATH
```
, or cwd when none is named);
```
${{ env.fileDir }}
```
names the declaring file's own directory. Nothing else is expanded — a bare
```
$
```
is literal text, so a value written for the container (
```
PATH: $PATH:/opt/bin
```
) reaches it unchanged.
yaml
```
workspace: .                       # mounts the directory this file sits in
# workspace: ${{ env.projectDir }} # mounts the project directory explicitly
```
Relative kit sources follow the same file-directory anchoring rule as
```
workspace:
```
(see
```
docker-sandboxes-kits
```
for kit reference syntax).
Files within a mounted workspace get default read-only masking, and that protection is complete only when the file sits directly at the mount's own root. A read-only bind at the mount point cannot be renamed by the sandbox — there is nothing above it inside the mount to rename. But an environment file in a subdirectory of a read-write mount is protected only at its current path: the sandbox can rename the containing directory (which it can write to) and then recreate the original path itself, landing a sandbox-controlled file back where the read-only bind no longer applies.
```
sbx env plan
```
calls this gap out explicitly for a file that is not at a mount's root. Do not claim renaming the containing directory creates no gap — for anything but the mount root, it does.
With no
PATH
given, an
```
.sbxenv.yaml
```
in the home directory is merged underneath as a base layer for defaults shared across projects; naming any
```
PATH
```
skips this layer entirely. The base layer may not set
```
name:
```
(which identifies one project) and its
```
workspace:
```
must be rooted at
```
${{ env.projectDir }}
```
— any other value would mount one fixed directory under every project that merges it.

除非文件设置了
```
name:
```
或由
```
--name
```
覆盖，sandbox 以挂载的目录命名（如果未挂载任何内容，则以项目目录命名）——因此一个不挂载任何内容的环境每次应用时仍是同一个 sandbox。同一目录中的两个不同环境文件会派生出相同的 sandbox 名称并发生冲突，除非每个文件都设置了自己的
```
name:
```
（或者每次调用传入不同的
```
--name
```
）——当同一目录中可能存在多个环境时，务必为每个环境设置显式的
```
name:
```
。
```
workspace:
```
指定读/写挂载，与
```
sbx create
```
省略路径时的行为完全一致：省略
workspace:
则不挂载任何内容。相对
```
workspace:
```
路径相对于声明它的文件所在目录解析——
```
workspace: .
```
挂载该文件所在的目录。
```
${{ env.projectDir }}
```
表示项目目录（第一个
```
PATH
```
所在的目录，若未命名 PATH 则为当前工作目录）；
```
${{ env.fileDir }}
```
表示声明文件自身的目录。除此之外不做任何展开——单独的
```
$
```
是字面文本，因此为容器写的值（
```
PATH: $PATH:/opt/bin
```
）会原样到达。
yaml
```
workspace: .                       # 挂载此文件所在的目录
# workspace: ${{ env.projectDir }} # 显式挂载项目目录
```
相对 kit 源与
```
workspace:
```
遵循相同的文件目录锚定规则（kit 引用语法见
```
docker-sandboxes-kits
```
）。
挂载工作区内的文件默认获得只读掩码，且只有在文件直接位于挂载自身根目录时，这种保护才是完整的。 挂载点上的只读绑定无法被 sandbox 重命名——挂载内部没有比它更高的层级可供重命名。但是，位于读/写挂载子目录中的环境文件仅在其当前路径受到保护：sandbox 可以重命名包含它的目录（该目录可写），然后自行重新创建原路径，从而让 sandbox 控制的文件回到只读绑定不再适用的位置。
```
sbx env plan
```
会针对不在挂载根目录的文件明确指出这一缺口。不要声称重命名包含目录不会产生缺口——对除挂载根目录以外的任何位置来说，这确实会产生缺口。
当未指定
PATH
时，主目录中的
```
.sbxenv.yaml
```
会作为基础层合并到下方，为跨项目共享默认值；指定任何
```
PATH
```
都会完全跳过该层。基础层不能设置
```
name:
```
（那会标识某个项目），其
```
workspace:
```
必须以
```
${{ env.projectDir }}
```
为根——其他任何值都会在合并它的每个项目下挂载一个固定目录。

args:

— parameterizing a shared file

args:

— 参数化共享文件

Declare named inputs under
```
args:
```
, each with a
```
default
```
(making it optional,
```
default: ""
```
counts as a real default) or
```
required: true
```
(mutually exclusive), plus optional
```
description
```
,
```
enum
```
, or
```
pattern
```
.
Reference one as
```
${{ env.args.NAME }}
```
anywhere a value appears in the file, and supply it with
```
--env-arg NAME=VALUE
```
(repeatable) or
```
--env-args-file PATH
```
.

在
```
args:
```
下声明命名输入，每个输入带有
```
default
```
（使其可选，
```
default: ""
```
也算真正的默认值）或
```
required: true
```
（互斥），以及可选的
```
description
```
、
```
enum
```
或
```
pattern
```
。
在文件中的任意值位置用
```
${{ env.args.NAME }}
```
引用某个输入，并通过
```
--env-arg NAME=VALUE
```
（可重复）或
```
--env-args-file PATH
```
提供。

lifecycle:

— host commands and the approval plan

lifecycle:

— 宿主命令与审批计划

```
lifecycle:
```
declares shell commands that run on the host, outside the sandbox, with your own privileges — not inside the container. Three phases, run in this order per invocation:
- initialize
  — runs on every
```
create
```
  and
```
run
```
  , including one that only attaches to an existing sandbox. It is the one phase that can produce what the environment needs to exist (a cloned workspace, a generated file), so it must be idempotent — it reruns on every reattach.
- postCreate
  — runs once, after the sandbox exists, before an interactive attach takes the terminal.
- preRemove
  — runs before
```
sbx env rm
```
  deletes the sandbox, while
```
sbx env exec
```
  can still reach it. A failing
  preRemove
  is only a warning — the failure itself does not block removal. After the hook, removal rechecks the approved destroy plan and sandbox identity. A new credential or changed binding not covered by that approval, or a replacement sandbox under the same name, stops removal before deletion. Review the new destroy plan before retrying.
- ```
sbx env exec
```
  runs no lifecycle commands at all, and requires the sandbox to already exist — it does not create one. Run
```
sbx env create
```
  /
```
sbx env run
```
  first.
yaml
```
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
```
Every command runs through the shell from the project directory by default (override per-command with
```
workdir:
```
; bound its runtime with
```
timeout:
```
).
A file that declares any lifecycle command is asked about on every invocation that reaches it, whether or not this particular invocation changed anything — approving a command also trusts whatever it invokes, including a script whose contents can change after the answer, so the question is repeated rather than remembered by default. The one exception:
```
sbx settings set env.rememberHostCommands true
```
makes it ask again only when the commands actually change. Never treat an untrusted file's or an untrusted kit's lifecycle commands as pre-approved, and never enable
```
rememberHostCommands
```
for a file whose commands you have not reviewed. An environment that declares no host commands at all, and whose config is otherwise unchanged from what was last approved, applies silently with no prompt. Use
```
--skip-host-commands
```
to run none of the declared commands for one invocation.

```
lifecycle:
```
声明在宿主机上、sandbox 之外、使用你自己的权限运行的 shell 命令——而不是在容器内。三个阶段，每次调用按此顺序运行：
- initialize
  — 在每次
```
create
```
  和
```
run
```
  时运行，包括仅附加到已有 sandbox 的情况。它是唯一能产生环境所需内容（克隆的工作区、生成的文件）的阶段，因此它必须是幂等的——每次重新附加都会重新运行。
- postCreate
  — 在 sandbox 创建后、交互式附加占用终端之前运行一次。
- preRemove
  — 在
```
sbx env rm
```
  删除 sandbox 之前运行，此时
```
sbx env exec
```
  仍可访问它。失败的
  preRemove
  只是警告——失败本身不会阻止删除。钩子执行后，删除会重新检查已批准的销毁计划和 sandbox 身份。该审批未覆盖的新凭据或更改后的绑定，或同名替换 sandbox，会在删除前中止删除。重试前请审查新的销毁计划。
- ```
sbx env exec
```
  完全不运行任何生命周期命令，且要求 sandbox 已存在——它不会创建 sandbox。请先运行
```
sbx env create
```
  /
```
sbx env run
```
  。
yaml
```
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
```
使其仅在命令实际变化时再次询问。绝不要将不受信任的文件或不受信任的 kit 的生命周期命令视为已预先批准，也绝不要对未审查过命令的文件启用
```
rememberHostCommands
```
。一个完全不声明宿主命令、且配置与上次批准相比没有变化的环境，会静默应用且不提示。使用
```
--skip-host-commands
```
可在单次调用中不运行任何已声明命令。

The environment plan: what it is and is not

环境计划：它是什么与不是什么

```
sbx env plan [PATH...]
```
prints everything applying the file would set up — host commands, credentials/bindings, MCP registrations, directories, published ports, the sandbox itself, and its variables — compared against what was last applied/approved. It changes nothing.
```
sbx env create
```
/
```
sbx env run
```
show the same plan and require approval before doing any work (
```
--auto-approve
```
/
```
-y
```
skips the prompt for non-interactive use — never default to
-y
for a file or kit you have not reviewed). A secret's literal
```
value:
```
is the one field shown both in the plan and recorded to state as a
```
sha256:
```
digest rather than in the clear; a
```
ref:
```
/
```
command:
```
secret shows where the credential comes from, not its resolved value.

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

Secrets, registries, and bindings scoped to the environment

作用域于环境的 secrets、registries 和 bindings

```
secrets:
```
and
```
registries:
```
provision into the same credential store
```
sbx secret set
```
uses, at this environment's sandbox scope, so
```
sbx env rm
```
can remove exactly what it created. Each entry uses the same
```
value
```
/
```
ref
```
/
```
command
```
shape as
```
sbx secret set
```
(exactly one of the three) — see
```
docker-sandboxes-network-credentials
```
for what those mean at runtime and why a literal secret value should not otherwise appear in a checked-in file.
```
bindings:
```
are per-service credential bindings merged into the user's global
```
credentials.yaml
```
; unlike
```
secrets:
```
/
```
registries:
```
, they are left in place by default by
```
sbx env rm
```
(they are user-wide and may be shared with other sandboxes/environments) — pass
```
--prune-bindings
```
to also remove them.
Never write a literal secret value directly into a checked-in
sbxenv.yaml
. Use
```
ref:
```
(1Password/AWS Secrets Manager) or
```
command:
```
so the value never lives in the file at all; if a literal
```
value:
```
is used transiently, both the plan and state show only its digest, but the original environment file still contains the plaintext secret. See the labeled
```
secrets:
```
fragment below for the shape — it is intentionally not part of the minimal asset, which needs no credentials at all to validate.
yaml
```
# 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
```

```
secrets:
```
和
```
registries:
```
配置到
```
sbx secret set
```
使用的同一凭据存储中，范围为此环境的 sandbox 作用域，因此
```
sbx env rm
```
可以精确移除它创建的内容。每个条目使用与
```
sbx secret set
```
相同的
```
value
```
/
```
ref
```
/
```
command
```
形态（三者恰好一个）——运行时的含义以及为什么字面 secret 值不应出现在入库文件中，请参见
```
docker-sandboxes-network-credentials
```
。
```
bindings:
```
是合并到用户全局
```
credentials.yaml
```
中的按服务凭据绑定；与
```
secrets:
```
/
```
registries:
```
不同，
```
sbx env rm
```
默认会将其保留在原处（它们是用户级的，可能与其他 sandbox/环境共享）——传入
```
--prune-bindings
```
也会一并移除它们。
绝不要将字面 secret 值直接写入入库的
sbxenv.yaml
。使用
```
ref:
```
（1Password/AWS Secrets Manager）或
```
command:
```
，这样值永远不会存在于文件中；如果临时使用字面
```
value:
```
，计划和状态都只显示其摘要，但原始环境文件仍包含明文 secret。参见下面的带标签
```
secrets:
```
片段了解其形态——它有意不包含在最小资产中，因为最小资产不需要任何凭据即可验证。
yaml
```
# 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:

, and

sandboxOptions:

kits:

、

additionalWorkspaces:

、

mcp:

、

ports:

与

sandboxOptions:

```
kits:
```
composes mixin kits (and, exactly once, an agent kit whose name matches
```
agent:
```
) onto the base agent; a relative source anchors to the declaring file's own directory, the same rule as
```
workspace:
```
.
```
additionalWorkspaces:
```
mounts extra directories beyond the primary
```
workspace:
```
(a file cannot declare one without the other) — the
```
sbxenv.yaml
```
equivalent of
```
sbx run
```
's extra positional workspace arguments with
```
:ro
```
.
```
mcp.servers:
```
registers MCP servers on the host and adds them to the sandbox's fixed (static) MCP set at create time; registrations are host-global and left in place by
```
sbx env rm
```
.
```
ports:
```
pins explicit host-port bindings for container ports the sandbox exposes — the equivalent of
```
sbx ports --publish
```
— and is torn down automatically when
```
sbx env rm
```
deletes the sandbox.

sandboxOptions:

(beyond

writableEnvFiles

, below) maps onto the remaining

sbx create

flags:

template

memory

cpus

pullPolicy

profile

skills

See

references/env-schema-fields.md

for the exact field shapes, required keys, and a YAML example for each of the five blocks above.

```
kits:
```
将 mixin kit（并且恰好一次，一个名称与
```
agent:
```
匹配的 agent kit）组合到基础 agent 上；相对源锚定到声明文件自身的目录，与
```
workspace:
```
规则相同。
```
additionalWorkspaces:
```
挂载主要
```
workspace:
```
以外的额外目录（一个文件不能只声明其中一个而不声明另一个）——相当于
```
sbx run
```
的额外位置工作区参数加
```
:ro
```
。
```
mcp.servers:
```
在宿主机上注册 MCP 服务器，并在创建时将它们添加到 sandbox 的固定（静态）MCP 集合中；注册是宿主全局的，
```
sbx env rm
```
会保留它们。
```
ports:
```
为 sandbox 暴露的容器端口固定显式的宿主端口绑定——相当于
```
sbx ports --publish
```
——并在
```
sbx env rm
```
删除 sandbox 时自动拆除。

sandboxOptions:

（除下面的

writableEnvFiles

外）映射到剩余的

sbx create

标志：

template

、

memory

、

cpus

、

pullPolicy

、

profile

、

skills

。

有关以上五个块的精确字段形状、必需键和 YAML 示例，请参阅

references/env-schema-fields.md

。

sandboxOptions.writableEnvFiles

— a deliberate, explicit downgrade

sandboxOptions.writableEnvFiles

— 一种有意且显式的降级

By default, every environment file mounted inside the workspace is read-only at its own path, even though the rest of the mount is writable. This stops an agent editing the very file that decides what host lifecycle commands and secret-resolving commands run on your machine on the next invocation.
Set
```
sandboxOptions.writableEnvFiles: true
```
only where an agent is deliberately meant to edit its own environment file. This is a real security downgrade — the plan then reports the file as writable — so treat it the same as any other explicit trust decision, not a default.
The protection is complete only at a mount's own root. A file placed directly at the root of a read-write mount cannot be reached even by renaming, because the sandbox cannot rename the mount point itself. A file in a subdirectory of that mount is a different case: it is read-only at its current path, but the sandbox can rename the directory holding it (which it can write to) and recreate a file at the original path, ending up with a sandbox-controlled file there.
```
sbx env plan
```
flags this gap for a file that is not directly at a mount's root — read the plan's output rather than assuming renaming is always harmless.

默认情况下，挂载在工作区内的每个环境文件在其自身路径上是只读的，即使挂载的其余部分是可写的。这可以防止 agent 编辑那个决定下次调用时哪些宿主生命周期命令和 secret 解析命令会在你机器上运行的文件。
仅在确实有意让 agent 编辑其自身环境文件时设置
```
sandboxOptions.writableEnvFiles: true
```
。这是一种真正的安全降级——计划随后会将该文件报告为可写——因此要像对待任何其他显式信任决策一样对待它，而不是默认值。
该保护仅在挂载自身根目录处是完整的。 直接放置在读/写挂载根目录的文件，即使通过重命名也无法被触及，因为 sandbox 无法重命名挂载点本身。位于该挂载子目录中的文件则是另一种情况：它在其当前路径上是只读的，但 sandbox 可以重命名包含它的目录（该目录可写），并在原路径重新创建一个文件，最终在那里得到 sandbox 控制的文件。
```
sbx env plan
```
会标记这种缺口，针对不直接位于挂载根目录的文件——请阅读计划输出，而不是假设重命名总是无害的。

Related skills

References

参考资料

```
references/sources.md
```
— provenance for every rule above (help captures, source paths, docs URLs).

references/env-schema-fields.md

— exact field shapes and YAML examples for

kits:

additionalWorkspaces:

mcp:

ports:

, and

sandboxOptions:

```
references/sources.md
```
— 上述每条规则来源（帮助捕获、源路径、文档 URL）。

references/env-schema-fields.md

—

kits:

、

additionalWorkspaces:

、

mcp:

、

ports:

和

sandboxOptions:

的精确字段形状及 YAML 示例。

Assets

资产

```
assets/sbxenv.yaml
```
— a complete, minimal, safe example: a
```
shell
```
agent mounting the declaring file's own directory, one static env var, and no credentials at all — it validates and plans without any onboarding authentication.

```
assets/sbxenv.yaml
```
— 一个完整、最小、安全的示例：一个
```
shell
```
agent 挂载声明文件自身的目录、一个静态环境变量、且完全没有任何凭据——它无需任何 onboarding 认证即可验证和规划。

Checks

检查

```
checks/verification.md
```
— Verification runbook for sbxenv.yaml commands (unexecuted runbook; run manually with an isolated, uniquely-named
```
--app-name
```
, never with real secret values or untrusted lifecycle commands auto-approved).

```
checks/verification.md
```
— sbxenv.yaml 命令的验证手册（未执行的 runbook；请手动使用隔离的、唯一命名的
```
--app-name
```
运行，绝不要使用真实 secret 值，也不要自动批准不受信任的生命周期命令）。

docker-sandboxes-env

Original

Translation

Docker Sandboxes: Declarative sbxenv.yaml Environments

Docker Sandboxes: 声明式 sbxenv.yaml 环境

Overview

概述

When to use this skill

何时使用本 skill

Do not use this skill when

不要使用本 skill 的情况

Core guidance

核心指导

File resolution and required fields

文件解析与必填字段

Naming, workspace, and the
`.sbxenv.yaml`
user base layer

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

`args:`
— parameterizing a shared file

`args:`
— 参数化共享文件

`lifecycle:`
— host commands and the approval plan

`lifecycle:`
— 宿主命令与审批计划

The environment plan: what it is and is not

环境计划：它是什么与不是什么

Secrets, registries, and bindings scoped to the environment

作用域于环境的 secrets、registries 和 bindings

`kits:`
,
`additionalWorkspaces:`
,
`mcp:`
,
`ports:`
, and
`sandboxOptions:`

`kits:`
、
`additionalWorkspaces:`
、
`mcp:`
、
`ports:`
与
`sandboxOptions:`

`sandboxOptions.writableEnvFiles`
— a deliberate, explicit downgrade

`sandboxOptions.writableEnvFiles`
— 一种有意且显式的降级

Related skills

相关 skills

References

参考资料

Assets

资产

Checks

检查

docker-sandboxes-env

Original

Translation

Docker Sandboxes: Declarative sbxenv.yaml Environments

Docker Sandboxes: 声明式 sbxenv.yaml 环境

Overview

概述

When to use this skill

何时使用本 skill

Do not use this skill when

不要使用本 skill 的情况

Core guidance

核心指导

File resolution and required fields

文件解析与必填字段

Naming, workspace, and the .sbxenv.yaml user base layer

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

args: — parameterizing a shared file

args: — 参数化共享文件

lifecycle: — host commands and the approval plan

lifecycle: — 宿主命令与审批计划

The environment plan: what it is and is not

环境计划：它是什么与不是什么

Secrets, registries, and bindings scoped to the environment

作用域于环境的 secrets、registries 和 bindings

kits:, additionalWorkspaces:, mcp:, ports:, and sandboxOptions:

kits:、additionalWorkspaces:、mcp:、ports: 与 sandboxOptions:

sandboxOptions.writableEnvFiles — a deliberate, explicit downgrade

sandboxOptions.writableEnvFiles — 一种有意且显式的降级

Related skills

相关 skills

References

参考资料

Assets

资产

Checks

检查

Naming, workspace, and the
`.sbxenv.yaml`
user base layer

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

`args:`
— parameterizing a shared file

`args:`
— 参数化共享文件

`lifecycle:`
— host commands and the approval plan

`lifecycle:`
— 宿主命令与审批计划

`kits:`
,
`additionalWorkspaces:`
,
`mcp:`
,
`ports:`
, and
`sandboxOptions:`

`kits:`
、
`additionalWorkspaces:`
、
`mcp:`
、
`ports:`
与
`sandboxOptions:`

`sandboxOptions.writableEnvFiles`
— a deliberate, explicit downgrade

`sandboxOptions.writableEnvFiles`
— 一种有意且显式的降级