Skip to main content
skill CX Codex

docker-sandboxes-lifecycle — Claude Code skill for Docker Sandboxes lifecycle

A skill that covers the local Docker Sandboxes lifecycle through the sbx CLI: running agents in isolated microVMs, cloning repos, cleaning up old environments.

Apache-2.0 1,100 installs ★ 646 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add docker/skills --skill docker-sandboxes-lifecycle -a claude-code
Open on GitHub

What docker-sandboxes-lifecycle does

This skill walks through creating, reattaching to, listing, stopping, and removing local Docker Sandboxes. The commands it covers include sbx run, sbx create, sbx ls, sbx stop, sbx rm, sbx prune, plus sbx exec for one-off commands, sbx cp for file transfers, and sbx ports for exposing ports. Built-in agents: claude, codex, cursor, devin, docker-agent, gemini, opencode, shell.

The real decision point here is workspace isolation. By default the workspace path is mounted read/write, so the agent writes straight into your tree. Pass --clone at creation time and the host repo becomes read-only while commits land in an in-container clone; pull them back through the sandbox-<name> git remote. That helps when you do not want the agent touching your actual checkout.

The skill was verified against sbx v0.42.0-503-g951b7f6d7. One trap worth knowing: sbx run claude with no path mounts the current directory, but sbx create claude with no path mounts nothing at all. Same CLI, different behavior. --clone also has strict preconditions: an explicit path, a plain Git repo, no worktree, and a real .git directory. If any is missing, creation fails loudly.

What it helps with

  • Launch an agent inside an isolated microVM with a single command
  • Give an agent its own git clone instead of write access to the repo
  • Mount extra read-only workspaces alongside the main one
  • Reattach to an existing sandbox by name
  • Clear out stopped sandboxes before they pile up

Example prompts for the agent

  • Run claude in a sandbox and mount the current directory
  • Create a sandbox named demo that clones the repo at ~/dev/myproject
  • List all sandboxes and stop the ones I am not using

How to install docker-sandboxes-lifecycle

1Skills CLI (Vercel)

npx skills add docker/skills --skill docker-sandboxes-lifecycle -a claude-code

2Manually: put the files in place

~/.claude/skills/docker-sandboxes-lifecycle/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/docker-sandboxes-lifecycle/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about docker-sandboxes-lifecycle

How do I install docker-sandboxes-lifecycle in Claude Code?

Run npx skills add docker/skills --skill docker-sandboxes-lifecycle -a claude-code. The skill lands in ~/.claude/skills/docker-sandboxes-lifecycle/SKILL.md.

What is the difference between sbx run and sbx create?

sbx run AGENT [PATH...] creates the sandbox if needed and attaches right away. sbx create AGENT [PATH...] only creates it; you attach later with sbx run --name SANDBOX.

What does --clone require?

An explicit path to a workspace inside a regular Git repository. The path must not be a Git worktree, and .git must be a real directory, not a file. If any precondition fails, creation errors out.

Source text

SKILL.md · Apache-2.0
---
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.
  ```bash
  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.
  ```bash
  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.
  ```bash
  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 must be a workspace to clone
    from);
  - that path must be inside a Git repository;
  - it must NOT be a Git worktree (the in-container clone cannot follow a
    worktree's `.git` pointer out to a common dir elsewhere);
  - its `.git` must be a real directory, not a file (a submodule or a
    `--separate-git-dir` setup points `.git` elsewhere, which the read-only
    source mount would not include).
- **`--clone` on `sbx run` when reattaching is a no-op ONLY on a sandbox
  already created in clone mode** — it re-validates nothing new and simply
  keeps running the existing in-container clone. Passing `--clone` while
  reattaching to a sandbox that was created **without** it (a plain
  bind-mounted sandbox) is **not** a silent no-op: it fails with an error
  telling you to recreate the sandbox with `sbx create --clone ...`. Neither
  form can convert an existing sandbox's mode after creation.
- **Removing or pruning a clone-mode sandbox permanently discards every
  commit the agent made that was never fetched back to the host** — the
  in-container clone lives on the sandbox's own filesystem and is deleted
  with it. Before removing a clone-mode sandbox, fetch its work first:
  ```bash
  git fetch sandbox-demo
  ```
  Fetching populates two refspecs: the ordinary `refs/remotes/sandbox-demo/*`
  (deleted along with the remote when the sandbox is removed) and a survivor
  copy at `refs/sandboxes/demo/*` (outside the remote namespace, so it is
  **not** deleted when the remote goes). Recover a branch from the survivor
  copy after removal with:
  ```bash
  git branch <local-name> refs/sandboxes/demo/<branch>
  ```
  `sbx rm`/`sbx prune` print this warning automatically for any clone-mode
  sandbox they are about to remove; read it before confirming, don't
  suppress it with `--force` out of habit.
- Additional workspaces are extra positional paths after the first. Append
  `:ro` to mount one read-only. **`:ro` blocks writes, not reads** — the
  sandbox can still read every file under a `:ro` mount; it is not a way to
  hide sensitive content, only to stop the sandbox from modifying it. A
  read-only argument may name a single file rather than a directory, holding
  just that one path out of reach for writes inside a workspace the sandbox
  can otherwise write.
  ```bash
  sbx run claude . /path/to/docs:ro
  ```
  **Never mount a secrets/credentials file this way** (`:ro` or otherwise) —
  a read-only mount still lets the sandbox (and, through it, the proxy-less
  agent process) read the secret in the clear. Use the credential store
  instead; see `docker-sandboxes-network-credentials`.

### Reattaching, stopping, and removing

- `sbx ls` lists sandboxes with agent, status, published ports, and
  workspace (`--json`, `-q`/`--quiet` for scripting).
- `sbx stop SANDBOX [SANDBOX...]` stops without removing; state is retained
  and the sandbox restarts with `sbx run --name`.
- `sbx rm [SANDBOX...] [--all] [--force]` removes sandboxes, their
  containers, Git worktrees, state, and sandbox-scoped secrets. **This
  cannot be undone**, and for a clone-mode sandbox it discards every
  unfetched commit (see above). Only use `--force` when you have already
  reviewed what will be destroyed and consented — for scripted teardown of
  resources this session itself created and uniquely named, not as a
  default habit.
- `sbx prune [--dry-run] [--filter until=VALUE] [--force]` removes only
  **stopped** sandboxes — a running sandbox is never touched — but this is
  still a destructive, irreversible bulk removal: every matching stopped
  sandbox's state, secrets, and (for clone-mode sandboxes) any unfetched
  commits are gone. Always preview with `--dry-run` first and read the
  clone-commit warning it prints before removing for real; do not pass
  `--force` as a default.
  - **Current source flag is `--filter until=VALUE`**, not `since=`. `VALUE`
    may be an RFC 3339 timestamp, a Unix timestamp, or a Go duration
    relative to now (e.g. `until=168h` keeps anything stopped within the
    last week — i.e. prunes what stopped *before* that point). **This is a
    source-only behavior at the pinned commit that differs from some
    installed builds**: an older installed `sbx` may still advertise
    `--filter since=DURATION` as a legacy alias; prefer `until=` and treat
    `since=` as legacy-only if your installed `--help` output does not show
    `until=`.
  ```bash
  sbx prune --dry-run --filter until=168h
  # after reviewing the dry-run output and any clone-commit warnings:
  sbx prune --filter until=168h
  ```

### Copying files and running ad-hoc commands

- `sbx cp SRC DST` copies between host and sandbox; exactly one side must be
  `SANDBOX:PATH`. Copying between two sandboxes is not supported.
  ```bash
  sbx cp ./config.json my-sandbox:/home/agent/
  sbx cp my-sandbox:/home/agent/output.log ./
  ```
- `sbx exec [flags] SANDBOX COMMAND [ARG...]` runs a command in a sandbox
  (starting it first if stopped); flags mirror `docker exec` (`-it`, `-d`,
  `-u`, `-w`, `-e`, `--env-file`, `--privileged`).
  ```bash
  sbx exec -it my-sandbox bash
  sbx exec -u root my-sandbox apt-get update
  ```
- `sbx ports SANDBOX [--publish SPEC] [--unpublish SPEC]` manages published
  ports after creation; `-p/--publish` on `sbx create`/`sbx run` only takes
  effect when the sandbox is created, not on reattach.

### Sizing and naming

- `--cpus` (0 = auto: all host CPUs) and `--memory`/`-m` (default 50% of
  host memory, clamped 512 MiB–32 GiB) are create-time-only knobs.
- `--name` sets the sandbox name (default `<agent>-<workdir>`); at least two
  characters, starting with a letter or number, letters/numbers/hyphens/
  periods only, at most 63 ASCII characters, ending in a letter or number;
  `default` is reserved.

## Related skills

- For `docker agent run --sandbox` and `docker agent sandbox` commands,
  use `docker-agent-run`.

- For network egress policy and service/registry credentials, use
  `docker-sandboxes-network-credentials`.
- For declarative, checked-in `sbxenv.yaml` environments that wrap this same
  create/run/rm lifecycle, use `docker-sandboxes-env`.
- For authoring or composing the kit `spec.yaml` an `AGENT` reference can
  point to, use `docker-sandboxes-kits`.

## References

- `references/sources.md` — provenance for every rule above (help captures, source paths, docs URLs).

## Assets

- None.

## Checks

- `checks/verification.md` — Verification runbook for sandbox lifecycle commands (unexecuted runbook; run manually with an isolated `--app-name`, never with `--force` except consented cleanup of the runbook's own uniquely-named test sandboxes).

© docker · Apache-2.0 · docker/skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set12

The whole set →
docker-destructive-guardrails The docker-destructive-guardrails skill makes the agent name exactly what will be deleted and get your confirmation before any destructive Docker command runs. CX Codex +1 1,700installs docker-project-foundations The docker-project-foundations skill bootstraps Docker environments from scratch. It generates a baseline set of .dockerignore, Dockerfile, and compose.yaml files. CX Codex +1 1,700installs docker-sandboxes-kits docker-sandboxes-kits teaches your coding agent to author, validate, pack, and sign Docker Sandboxes spec.yaml kits under the v2 schema. Useful when creating agents or mixins. CX Codex +1 1,100installs docker-sandboxes-network-credentials docker-sandboxes-network-credentials is a Claude Code skill for Docker Sandboxes network access and credentials. It activates when an agent needs a host allowed or blocked, a service token, or help diagnosing a denied request. CX Codex +1 1,100installs docker-agent-run Walks through docker agent run: picking a safety mode, isolating the agent in a sandbox, aliases, and failed runs. CX Codex +1 1,100installs docker-agent-config docker-agent-config is a Claude Code skill that creates and edits agent.yaml files for Docker Agent. It supports configuring models, MCP toolsets, and multi-agent teams. CX Codex +1 1,100installs docker-agent-deploy docker-agent-deploy is a Claude Code skill for serving Docker Agent, sharing configs through an OCI registry, and evaluating changes to check for CI regressions. CX Codex +1 1,100installs docker-sandboxes-env docker-sandboxes-env is a Claude Code skill that creates and validates declarative sbxenv.yaml files for Docker Sandboxes. It supports reproducible environment setup and lifecycle commands. CX Codex +1 1,000installs

Project sponsors

Companies that keep this analytics open