docker · krissetto · Aug 6, 2026 · Aug 6, 2026
@@ -1,23 +1,31 @@
 ---
 title: "Sandbox Mode"
-description: "Run agents in an isolated Docker sandbox VM for enhanced security."
-keywords: docker agent, ai agents, configuration, yaml, sandbox mode
+description: "Run agents in an isolated sandbox VM managed by sbx."
+keywords: docker agent, sbx, ai agents, configuration, yaml, sandbox mode
 weight: 80
 canonical: https://docs.docker.com/ai/docker-agent/configuration/sandbox/
 ---
 
-_Run agents in an isolated Docker sandbox VM for enhanced security._
+_Run agents in an isolated sandbox VM managed by [`sbx`](https://docs.docker.com/ai/sandboxes/)._
 
 ## Overview
 
-Sandbox mode runs the entire agent inside a disposable sandbox VM instead of directly on the host system. All shell, filesystem, and process activity happens inside that VM, so a misbehaving agent cannot touch files outside the mounted working directory or reach long-lived host state.
+Sandbox mode is Docker Agent's integration with
+[`sbx`](https://docs.docker.com/ai/sandboxes/), Docker's sandbox product. `sbx`
+provides the runtime, CLI, and VM; Docker Agent is one of its built-in agents.
+The `--sandbox` flag asks `sbx` to create or reuse a VM and launches Docker
+Agent inside it.
 
-The backend is provided by the [`docker sandbox`](https://docs.docker.com/ai/sandboxes/) CLI plugin (ships with Docker Desktop) or the standalone [`sbx`](https://github.com/docker/sbx) CLI if it is on `PATH`.
+All shell, filesystem, and process activity happens inside that VM, so a
+misbehaving agent cannot touch files outside the mounted working directory or
+reach long-lived host state. Docker Agent does not implement the sandbox or
+start a raw `docker run` container; it orchestrates the installed `sbx` CLI.
 
 > [!NOTE]
 > **Requirements**
 >
-> Sandbox mode requires Docker Desktop with sandbox support (or a working `sbx` CLI). Docker Agent shells out to these tools, it does not start raw `docker run` containers.
+> Install and configure the [`sbx` CLI](https://docs.docker.com/ai/sandboxes/) before
+> using `--sandbox`.
 
 ## Usage
 
@@ -27,24 +35,21 @@ Enable sandbox mode with the `--sandbox` flag on the `docker agent run` command:
 docker agent run --sandbox agent.yaml
 ```
 
-Docker Agent launches a sandbox VM, copies itself into it, mounts the current working directory, and re-runs the agent from inside.
+Docker Agent asks `sbx` to launch or reuse a sandbox VM, mounts the current
+working directory, and runs the agent inside it.
 
 ## Flags
 
 | Flag          | Default                                      | Description                                                                                               |
 | ------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
 | `--sandbox`   | `false`                                      | Enable sandbox mode.                                                                                      |
-| `--template`  | `docker/docker-agent-sbx-templates:latest`   | OCI image used as the sandbox template. Passed to `docker sandbox create -t` / `sbx create -t`. See [Sandbox templates](#sandbox-templates). |
-| `--sbx`       | `true`                                       | Prefer the `sbx` CLI backend when it is available. Set `--sbx=false` to always use `docker sandbox`.      |
+| `--template`  | `docker/docker-agent-sbx-templates:latest`   | OCI image used as the sandbox template. Passed to `sbx create -t`. See [Sandbox templates](#sandbox-templates). |
 | `--no-kit`    | `false`                                      | Disable the [auto-kit](#auto-kit) — do not stage skills or prompt files into the sandbox.                 |
 
 ```bash
 # Use a custom template image
 docker agent run --sandbox --template myorg/custom-agent-template:latest agent.yaml
 
-# Force the docker sandbox backend even if sbx is on PATH
-docker agent run --sandbox --sbx=false agent.yaml
-
 # Run without staging skills / prompt files into the sandbox
 docker agent run --sandbox --no-kit agent.yaml
 ```
@@ -144,7 +149,7 @@ fallback host set.
 A sandbox template is the OCI image the sandbox VM boots from. It determines
 the base OS and the tools available inside the VM, including whether the
 `docker-agent` binary is already there. `--template` (or `-t` on `sbx
-create` / `docker sandbox create`) selects it.
+create`) selects it.
 
 ### The default template
 
@@ -187,9 +192,8 @@ $ sbx create -t docker/docker-agent-sbx-templates:latest
 ```
 
 > [!TIP]
-> The upstream [Docker Sandboxes documentation](https://docs.docker.com/ai/sandboxes/)
-> covers the full `sbx` / `docker sandbox` CLI reference, independent of
-> Docker Agent.
+> The [`sbx` documentation](https://docs.docker.com/ai/sandboxes/) covers the
+> sandbox CLI and runtime independently of Docker Agent.
 
 ### What they contain
 
@@ -223,7 +227,7 @@ docker agent run --sandbox agent.yaml
 
 ## How It Works
 
-1. `--sandbox` tells Docker Agent to prefer the `sbx` CLI (if available and `--sbx` is true), otherwise it falls back to `docker sandbox`.
+1. `--sandbox` tells Docker Agent to invoke the installed `sbx` CLI.
 2. A new sandbox VM is created from the image passed via `--template`.
 3. The current working directory is mounted into the VM; the agent binary is copied in.
 4. The [auto-kit](#auto-kit) is staged on the host and bind-mounted read-only into the VM, so the agent sees its skills and prompt files inside the sandbox.

@@ -48,9 +48,8 @@ $ docker agent run [config] [message...] [flags]
 | `--json`                                | Output results as newline-delimited JSON (use with `--exec`)                                                                              |
 | `--hide-tool-calls`                     | Hide tool calls in the output                                                                                                             |
 | `--hide-tool-results`                   | Hide tool call results in the output                                                                                                      |
-| `--sandbox`                             | Run the agent inside a Docker sandbox (see [Sandbox](../../configuration/sandbox/index.md))                                     |
+| `--sandbox`                             | Run the agent in sandbox mode using `sbx` (see [Sandbox](../../configuration/sandbox/index.md))                                 |
 | `--template <image>`                    | Template image for the sandbox (default: `docker/docker-agent-sbx-templates:latest`)                                                      |
-| `--sbx`                                 | Prefer the `sbx` CLI backend when available (default `true`; set `--sbx=false` to force `docker sandbox`)                                 |
 | `--no-kit`                              | Disable the [auto-kit](../../configuration/sandbox/index.md#auto-kit): do not stage skills or prompt files into the sandbox    |
 | `--agent-picker [refs]`                 | Show a full-screen interactive picker before launching, letting you browse and select an agent. Accepts an optional comma-separated list of agent references to show (defaults to the built-in `default` and `coder` agents plus any agent configs found in `~/.agents`). Arrow keys navigate; `?` toggles the YAML preview panel; `l` (or mouse-click) toggles the **Lean Mode** checkbox to launch in the lean TUI; `b` (or clicking **[ Open Board ]**) opens the Kanban board (`docker agent board`) instead of running an agent; Enter confirms. Not available in `--exec` or non-TTY modes. |
 | `-w, --worktree [name]`                 | Run the agent in a fresh git worktree of the working directory, isolating its changes from your checkout. Optionally name it (`--worktree=my-feature`); otherwise a name is generated. Requires the working directory to be inside a git repository. Every tool (the shell included) runs inside the worktree. Combine with `--working-dir` to branch from another repository, and with `--session` to resume into the same worktree later. Cannot be combined with `--remote` or `--sandbox`. When the session ends, a clean worktree is removed automatically; one with work prompts to keep or remove (never in `--exec`). |

@@ -71,7 +71,7 @@ Two different questions come up here, and it's worth keeping them separate:
 
 ### `--sandbox`: the isolation boundary
 
-For an untrusted or autonomous agent — anything acting without a human watching approvals — **`--sandbox` is the isolation boundary to reach for**, not a cleverer allow-list. It runs the entire agent, shell calls included, inside a Docker sandbox VM: a misbehaving or successfully-prompt-injected agent can't touch anything outside the mounted working directory or reach other host/CI state, regardless of which command it runs. That VM isn't disposable or ephemeral — a sandbox matching the current workspace and mount set is retained and reused across subsequent runs rather than torn down when the session ends (see [How It Works](../../configuration/sandbox/index.md#how-it-works)). See [Sandbox Mode](../../configuration/sandbox/index.md) for the full flag reference, requirements (Docker Desktop or the `sbx` CLI), and how the network allowlist and kit staging work.
+For an untrusted or autonomous agent — anything acting without a human watching approvals — **`--sandbox` is the isolation boundary to reach for**, not a cleverer allow-list. It runs the entire agent, shell calls included, inside a VM managed by [`sbx`](https://docs.docker.com/ai/sandboxes/): a misbehaving or successfully-prompt-injected agent can't touch anything outside the mounted working directory or reach other host/CI state, regardless of which command it runs. That VM isn't disposable or ephemeral — a sandbox matching the current workspace and mount set is retained and reused across subsequent runs rather than torn down when the session ends (see [How It Works](../../configuration/sandbox/index.md#how-it-works)). See [Sandbox Mode](../../configuration/sandbox/index.md) for the full flag reference, `sbx` requirement, network allowlist, and kit staging behavior.
 
 ```bash
 $ docker agent run --sandbox --exec agent.yaml --json "Fix the failing test"
@@ -169,7 +169,7 @@ jobs:
           path: agent-events.ndjson
 ```
 
-This job auto-approves every shell call the review agent makes (`--yolo`) rather than trying to allow-list every `git`/`grep`/`cat` invocation a code review might need — the read surface for "review this diff" is open-ended, and a fixed pattern list is exactly the kind of shell-matching boundary the [previous section](#defense-in-depth-not-a-boundary-permissions-and-shell-command-matching) says not to rely on. If your CI environment can run `--sandbox` (a self-hosted runner with Docker Desktop, or an `sbx`-enabled image — GitHub-hosted `ubuntu-latest` ships neither out of the box), add it and get a real isolation boundary around that `--yolo`:
+This job auto-approves every shell call the review agent makes (`--yolo`) rather than trying to allow-list every `git`/`grep`/`cat` invocation a code review might need — the read surface for "review this diff" is open-ended, and a fixed pattern list is exactly the kind of shell-matching boundary the [previous section](#defense-in-depth-not-a-boundary-permissions-and-shell-command-matching) says not to rely on. If your CI environment has `sbx` installed and configured (GitHub-hosted `ubuntu-latest` does not ship it out of the box), add `--sandbox` and get a real isolation boundary around that `--yolo`:
 
 ```bash
 $ docker-agent run --sandbox --exec --yolo .github/agents/review-agent.yaml --json "..."