docker-sandboxes-lifecycle

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 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:
```
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:
```
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.
```
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=.
```
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.
```
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).
```
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).