diff --git a/docs/configuration/sandbox/index.md b/docs/configuration/sandbox/index.md index 7108fd98f6..ec8cf9540d 100644 --- a/docs/configuration/sandbox/index.md +++ b/docs/configuration/sandbox/index.md @@ -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. diff --git a/docs/features/cli/index.md b/docs/features/cli/index.md index 23cac6ecfe..b389d58730 100644 --- a/docs/features/cli/index.md +++ b/docs/features/cli/index.md @@ -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 ` | 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`). | diff --git a/docs/guides/headless/index.md b/docs/guides/headless/index.md index 5d1c94013c..3f902475a8 100644 --- a/docs/guides/headless/index.md +++ b/docs/guides/headless/index.md @@ -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 "..."