/docker-sandboxes-lifecycle

name: docker-sandboxes-lifecycle
description: Use this skill when creating, running, reattaching to, listing, stopping, or removing Docker Sandboxes (the standalone `sbx` CLI that runs AI coding agents in isolated microVMs), even if the user just says they want to "run claude in a sandbox", "isolate an agent from my repo", "give an agent its own git clone", or "clean up old sandboxes". Covers `sbx run`/`sbx create` (including the built-in agents claude, codex, cursor, devin, docker-agent, gemini, opencode, shell), workspace bind-mount vs `--clone` isolation, additional read-only workspaces, reattaching by `--name`, `sbx ls`/`stop`/`rm`/`prune`, `sbx exec`, `sbx cp`, and `sbx ports`.
license: Apache-2.0
compatibility: Standalone `sbx` CLI (not the legacy `docker sandbox` plugin wrapper). Source-verified against docker/sandboxes (github.com/docker/sandboxes) @ commit df5c96ba60484fa2c375469dbac912c205da6c37. Cross-checked against an installed sbx v0.42.0-503-g951b7f6d7 (commit 951b7f6d7f6bb260fac15077b607109ffe8ae012, older than the pinned source); one source-only behavior change is called out explicitly below (`sbx prune --filter`). `docker_help` does not cover standalone `sbx` syntax.

Docker Sandboxes: Local Lifecycle & Workspace Isolation

Overview

Docker Sandboxes (`sbx`) runs an AI coding agent inside an isolated microVM with its own filesystem, network, and Docker daemon. This skill owns the local sandbox lifecycle — creating, reattaching to, listing, stopping, and removing sandboxes — and the workspace isolation choice (direct bind mount vs. `--clone`). It does not cover network policy, credentials, `sbxenv.yaml`, or kit authoring — see Related skills.

When to use this skill

Activate this skill when:

• The user wants to start, reattach to, stop, or remove a local `sbx` sandbox.
• The user wants an agent to work on a repository without giving it a

writable bind mount of the host working tree (`--clone`).

• The user wants extra read-only (or write-restricted) workspaces mounted

alongside the primary one.

• The user is copying files between host and sandbox, publishing a sandbox

port, or running an ad-hoc command inside a sandbox (`sbx exec`).

• The user wants to clean up stopped sandboxes (`sbx prune`) or remove a

specific one (`sbx rm`), with the destructive consequences understood.

Do not use this skill when

Do not use this skill when:

• The task is running `docker agent run --sandbox` or managing its

`docker agent sandbox` allowlist — use `docker-agent-run`. If the CLI is unclear, establish whether the user runs Docker Agent or standalone `sbx` before choosing commands.

• The task is about what a sandbox can reach on the network or which

credentials it uses — use `docker-sandboxes-network-credentials`.

• The task is authoring or running a declarative `sbxenv.yaml` file — use

`docker-sandboxes-env`.

• The task is authoring, packaging, signing, or composing a kit `spec.yaml`

— use `docker-sandboxes-kits`.

• The task is about `sbx --cloud` (Docker Cloud Sandboxes) — out of scope for

this skill set, which covers the local daemon only.

Core guidance

Creating vs. running

• Use `sbx run AGENT [PATH...]` to create-if-needed **and** attach in one

step. Use `sbx create AGENT [PATH...]` to create without attaching, then `sbx run --name SANDBOX` to attach later. Pass `--detached`/`-d` to `sbx run` to print the sandbox ID and exit without an interactive session.

  sbx run shell                  # create (if needed) and attach, cwd mounted
  sbx create shell .             # create only, cwd mounted, do not attach
  sbx run --name my-sandbox       # reattach later

• `AGENT` is a built-in name (`claude`, `codex`, `cursor`, `devin`,

`docker-agent`, `gemini`, `opencode`, `shell`) or a sandbox kit reference (local directory, ZIP, git, or OCI). A relative local kit reference MUST be an explicit path (`./my-kit`, a parent-relative `.zip` path) — a bare `my-kit` is read as an agent/sandbox name, never a directory beside the cwd.

• **Omitting the path is not the same for every subcommand.** `sbx run claude`

with no path mounts the **current directory**. `sbx create claude` with no path mounts **nothing at all** — the agent then works only in the container's own filesystem. Always pass a path explicitly with `sbx create` if you intend to give the agent a workspace.

• **Prefer `--name` to reattach; a bare positional name still works but is

deprecated.** `sbx run --name NAME` (agent positional optional, read from the sandbox's own spec) is the recommended form. A bare `sbx run NAME` — a positional that is neither a known agent nor an explicit kit reference — is still **accepted** as a legacy re-attach shorthand, but prints a deprecation warning ("`sbx run NAME` is deprecated; use `sbx run --name NAME` instead") and may be removed in a future release. Always write `--name` explicitly rather than relying on the legacy form.

  sbx run --name existing-sandbox                 # reattach, agent read from spec
  sbx run claude --name existing-sandbox          # reattach, verify expected agent

Workspace isolation: bind mount vs. `--clone`

• **Default (bind mount):** the workspace path is mounted read/write inside

the sandbox at the same path as on the host. The agent can write directly to your working tree.

• **`--clone` (creation-time only):** the agent runs against a private

in-container clone of the host Git repository. The host repo is mounted **read-only**; the agent's commits land in the in-container clone and are reachable from the host via a `sandbox-<name>` git remote — fetch or pull from it to bring commits back.

  sbx create --clone --name demo claude .
  # on the host, later:
  git fetch sandbox-demo

• **`--clone` has real preconditions, checked at creation time**, and fails

loudly if any is unmet:

• an explicit `PATH` must be given (there mus