Docker Sandboxes Env Agent Skill

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.

  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.

  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.

  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.

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