Docker Sandboxes Env

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.