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.