Terminal
Terminal/Skill
Explains writing a checked-in sbxenv.yaml that sets up a Docker Sandboxes sandbox for an agent, covering mounts, secrets and host setup commands.
By Docker
Works with
npx skills add docker/skills --skill docker-sandboxes-envsbxenv.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.
Activate this skill when:
sbx create/sbx run command line.args: + --env-arg).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:
sbx create/run/rm flag-based workflow with
no sbxenv.yaml file involved — use docker-sandboxes-lifecycle.docker-sandboxes-network-credentials (this skill's secrets:/
registries:/bindings: blocks provision into that same store, but do not
redefine its rules here).spec.yaml a kits: entry points at — use
docker-sandboxes-kits.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).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.
sbx env create sbxenv.yaml override.yaml
.sbxenv.yaml user base layername: 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.
workspace: . # mounts the directory this file sits in
# workspace: ${{ env.projectDir }} # mounts the project directory explicitly
workspace: (see docker-sandboxes-kits for kit reference syntax).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.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 fileargs:, each with a default (making it
optional, default: "" counts as a real default) or required: true
(mutually exclusive), plus optional description, enum, or pattern.${{ 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 planlifecycle: 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.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
workdir:; bound its runtime with
timeout:).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.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: 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.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.
# 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 downgradesandboxOptions.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.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.sbx create/run/rm flag-based workflow this file wraps, use
docker-sandboxes-lifecycle.secrets:/registries:/bindings: mean at runtime, and for
configuring network policy independent of any environment file, use
docker-sandboxes-network-credentials.spec.yaml a kits: entry (or agent:
pointing at an agent kit) references, use docker-sandboxes-kits.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/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/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).