# Docker Sandboxes Env

Use this skill when authoring, planning, or running a declarative `sbxenv.yaml` file...

- Repository: https://github.com/docker/skills (609 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add docker/skills --skill docker-sandboxes-env -g -a claude-code -y`
Codex: `npx skills add docker/skills --skill docker-sandboxes-env -g -a codex -y`
Cursor: `npx skills add docker/skills --skill docker-sandboxes-env -g -a cursor -y`
Gemini CLI: `npx skills add docker/skills --skill docker-sandboxes-env -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add docker/skills`

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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 rest: https://github.com/docker/skills/blob/HEAD/skills/docker-sandboxes-env/SKILL.md