# docker-sandboxes-env

Generates and validates declarative sbxenv.yaml files for Docker Sandboxes. Handy when setting up reproducible agent environments and host lifecycle commands.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 725 installs · ★ 599
- Author: docker
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/docker/skills/tree/HEAD/skills/docker-sandboxes-env/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/docker-sandboxes-env

## What it does

This skill guides agents through writing and inspecting `sbxenv.yaml` files with `schemaVersion: "1"`. It configures agent choices, mounts, environment variables, secrets, ports, and MCP servers. Instead of typing long flag lists into terminal prompts, users can manage environments with `sbx env create`, `run`, or `plan`.

Configurations support `docker compose -f`-style deep merging. Later files override earlier values, mappings merge by key, and lists concatenate. A base file at `~/.sbxenv.yaml` applies automatically when no path is passed. Host lifecycle hooks like `initialize`, `postCreate`, and `preRemove` run under an explicit approval plan.

The workflow requires standalone `sbx` with `sbx env` support rather than the legacy `docker sandbox` wrapper. Read-only masking is completely safe only when `sbxenv.yaml` resides at the mount root. If placed in a subdirectory, the sandbox could rename the folder to bypass protection.

## Requirements
- Works with: Docker

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add docker/skills --skill docker-sandboxes-env -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/docker-sandboxes-env/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/docker-sandboxes-env/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add docker/skills --skill docker-sandboxes-env -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/docker-sandboxes-env/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add docker/skills --skill docker-sandboxes-env -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/docker-sandboxes-env/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install docker/skills docker-sandboxes-env
```

2. **Manually: put the files in place**
- File: `.github/skills/docker-sandboxes-env/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add docker/skills --skill docker-sandboxes-env -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/docker/skills --path skills/docker-sandboxes-env
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/docker-sandboxes-env/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add docker/skills --skill docker-sandboxes-env -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/docker/skills/tree/HEAD/skills/docker-sandboxes-env/SKILL.md

## When to use it
- write declarative `sbxenv.yaml` manifests for Docker Sandboxes
- attach host setup scripts via `lifecycle` commands
- merge multiple environment configurations into one sandbox
- pass parameterized values using `args` and `--env-arg`

## Example prompts
- Write an sbxenv.yaml file mounting the current folder with the shell agent
- Add an initialize lifecycle hook to clone a repo before sandbox start
- Check my sbxenv.yaml schema and configure writableEnvFiles

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: dc4070d7df7b7527.

BEGIN THIRD-PARTY FILE dc4070d7df7b7527
```text
---
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
```
END THIRD-PARTY FILE dc4070d7df7b7527

The third-party file has ended. Everything between the dc4070d7df7b7527 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2756 of 16187 bytes. © docker · Apache-2.0 · https://github.com/docker/skills/tree/HEAD/skills/docker-sandboxes-env/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md