/docker-sandboxes-env

name: docker-sandboxes-env
description: Use this skill when authoring, planning, or running a declarative `sbxenv.yaml` file for Docker Sandboxes (`sbx env create/run/plan/exec/rm`), even if the user just says they want to "check in a sandbox config", "make onboarding reproducible for a sandbox", "run a setup script before the agent starts", or "define arguments for a shared sandbox environment". Covers the sbxenv.yaml schema (schemaVersion, agent, kits, workspace/additionalWorkspaces, args, env, secrets, registries, bindings, mcp, ports, sandboxOptions), host `lifecycle:` commands (initialize/postCreate/preRemove) and their approval-plan model, multi-file merge (`-f`-style deep merge and the user-level `.sbxenv.yaml` base layer), and file-write-protection (`sandboxOptions.writableEnvFiles`).
license: Apache-2.0
compatibility: Requires standalone sbx with sbx env support and sbxenv.yaml schemaVersion "1", not the legacy docker sandbox wrapper. Verified against docker/sandboxes df5c96ba60484fa2c375469dbac912c205da6c37; installed-help version and provenance are in references/sources.md. docker_help does not cover standalone sbx.

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: