Docker Sandboxes Lifecycle

DockerOfficialPublished by Docker

Skill
Tool integration
Automation and integrations
Apache-2.0
No issues found

From the author

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`.

— the description by Docker

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The Docker Sandboxes (sbx) CLI provides isolated microVM environments for running AI coding agents. This skill covers the complete lifecycle management of these sandboxes, including creation, reattachment, status monitoring, and cleanup. It also addresses workspace isolation strategies, such as choosing between direct bind mounts and secure --clone isolation, as well as managing file transfers and ad-hoc command execution within the sandbox environment.

What it does

Create and run sandboxes using built-in agents or custom kits.
Reattach to existing sandboxes using the --name flag.
Configure workspace isolation using bind mounts or --clone mode.
List, stop, and remove sandboxes to manage system resources.
Execute ad-hoc commands and copy files between the host and the sandbox.
Manage published network ports for running sandboxes.

When to use it

When you need to start or reattach to a local sbx sandbox.
When you want to isolate an agent from your host repository using --clone.
When you need to clean up stopped sandboxes using prune or rm.
When you need to copy files into or out of an active sandbox.
When you need to run specific commands inside a sandbox environment.

Advantages

Provides secure, isolated environments for AI agents.
Supports flexible workspace configurations for different security needs.
Enables persistent agent sessions that can be stopped and resumed.
Includes safety warnings for destructive operations like pruning or removing clones.

Usage examples

“Run a claude agent in a new sandbox with the current directory.”: The agent creates a new sandbox, mounts the current directory, and attaches to the session.
“Reattach to my existing sandbox named dev-env.”: The agent uses the --name flag to reconnect to the specified running or stopped sandbox.
“Clean up all sandboxes that have been stopped for more than a week.”: The agent executes sbx prune --filter until=168h to remove old, stopped sandboxes.
“Copy a config file into my-sandbox.”: The agent uses sbx cp ./config.json my-sandbox:/home/agent/ to transfer the file.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/docker/docker-sandboxes-lifecycle/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip docker-sandboxes-lifecycle.zip -d .agents/skills

Documentation by Docker

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.

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).

Files

ATTRIBUTION.mdAdded by AutoGineer844 B
LICENSELicence file added by AutoGineer11.1 KiB
SKILL.md12.4 KiB
agents/openai.yaml474 B
checks/verification.md4.4 KiB
evals/mount-ls-delete.yaml3.8 KiB
references/sources.md4.5 KiB
skill.yaml1.2 KiB

LICENSE


                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   APPENDIX: How to apply the Apache License to your work.

      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.

   Copyright 2026 Docker, Inc.

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs a command-line tool

The author says: 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.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by

Docker

Publisher

Docker (Official)

Source

docker/skills · skills/docker-sandboxes-lifecycle · commit 9f04a05

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by Docker.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download docker-sandboxes-lifecycle.zip