Docker Sandboxes: Declarative sbxenv.yaml Environments

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.

When to use this 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.

Do not use this skill when

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
```
.

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
```

Naming, workspace, and the

.sbxenv.yaml

user base layer

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.

args:

— parameterizing a shared file

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
```
.

lifecycle:

— host commands and the approval plan

```
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.

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.

Secrets, registries, and bindings scoped to the environment

```
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
```

kits:

additionalWorkspaces:

mcp:

ports:

, and

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.

sandboxOptions.writableEnvFiles

— a deliberate, explicit downgrade

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.

Related skills

For the
```
sbx create
```
/
```
run
```
/
```
rm
```
flag-based workflow this file wraps, use
```
docker-sandboxes-lifecycle
```
.
For what
```
secrets:
```
/
```
registries:
```
/
```
bindings:
```
mean at runtime, and for configuring network policy independent of any environment file, use
```
docker-sandboxes-network-credentials
```
.
For the schema of the kit
```
spec.yaml
```
a
```
kits:
```
entry (or
```
agent:
```
pointing at an agent kit) references, use
```
docker-sandboxes-kits
```
.

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:

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.

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).

docker-sandboxes-env

NPX Install

Tags

SKILL.md Content

Docker Sandboxes: Declarative sbxenv.yaml Environments

Overview

When to use this skill

Do not use this skill when

Core guidance

File resolution and required fields

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

`args:`
— parameterizing a shared file

`lifecycle:`
— host commands and the approval plan

The environment plan: what it is and is not

Secrets, registries, and bindings scoped to the environment

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

`sandboxOptions.writableEnvFiles`
— a deliberate, explicit downgrade

Related skills

References

Assets

Checks

docker-sandboxes-env

NPX Install

Tags

SKILL.md Content

Docker Sandboxes: Declarative sbxenv.yaml Environments

Overview

When to use this skill

Do not use this skill when

Core guidance

File resolution and required fields

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

args: — parameterizing a shared file

lifecycle: — host commands and the approval plan

The environment plan: what it is and is not

Secrets, registries, and bindings scoped to the environment

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

sandboxOptions.writableEnvFiles — a deliberate, explicit downgrade

Related skills

References

Assets

Checks

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

`args:`
— parameterizing a shared file

`lifecycle:`
— host commands and the approval plan

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

`sandboxOptions.writableEnvFiles`
— a deliberate, explicit downgrade