diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/sandbox/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/sandbox/index.md index 7108fd98f69..ec8cf9540d5 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/sandbox/index.md +++ b/_vendor/github.com/docker/docker-agent/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/_vendor/github.com/docker/docker-agent/docs/features/cli/index.md b/_vendor/github.com/docker/docker-agent/docs/features/cli/index.md index 23cac6ecfef..b389d587305 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/cli/index.md +++ b/_vendor/github.com/docker/docker-agent/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/_vendor/github.com/docker/docker-agent/docs/features/tui/index.md b/_vendor/github.com/docker/docker-agent/docs/features/tui/index.md index d1f4d899513..fec794902d5 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/tui/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/tui/index.md @@ -57,7 +57,7 @@ settings: Omit `lean` or set it to `false` to keep the full TUI as the default. You can still use `--lean` for a single run, or `--lean=false` to use the full TUI when `settings.lean` is enabled. See [User Settings](../../configuration/user-settings/index.md) for the full precedence rules between flags and user config. -The lean TUI supports **steering**: messages submitted while the agent is running are queued and delivered to the active session. Pending steering messages appear with muted styling at the end of the live stream so you can see what will be sent next. +The lean TUI supports **steering** and **follow-ups** while the agent is running. Press Enter to steer the active turn, or Alt+Enter to queue the message as a separate turn after the current one finishes. Pending messages appear with muted styling at the end of the live stream. The lean TUI supports a focused set of slash commands: `/new`, `/compact`, `/model`, `/effort`, `/clear`, `/help`, `/exit` (alias: `/quit`), plus any agent-defined commands. Type `/model` (or `/model `) to switch the active model inline — the command opens a fuzzy-searchable list of available models. @@ -355,7 +355,9 @@ Customize session titles to make them more meaningful and easier to find. By def | Ctrl+Z | Suspend TUI to background (resume with `fg`) | | Ctrl+X | Clear queued messages | | Escape | Cancel current operation | -| Enter | Send message (or newline with Shift+Enter) | +| Enter | Send message (or steer while the agent is running) | +| Alt+Enter | Queue a follow-up turn while the agent is running | +| Shift+Enter | Insert a newline | | Up/Down | Navigate message history | Press Ctrl+H to view the complete list of all available keyboard shortcuts. diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/headless/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/headless/index.md index 5d1c94013c6..3f902475a8e 100644 --- a/_vendor/github.com/docker/docker-agent/docs/guides/headless/index.md +++ b/_vendor/github.com/docker/docker-agent/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 "..." diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/filesystem/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/filesystem/index.md index 921d2527351..42a5471619f 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/filesystem/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/filesystem/index.md @@ -28,6 +28,15 @@ When a file is not found, error messages include the resolved absolute path to h > [!IMPORTANT] > Agents must use paths appropriate for the host OS. A Windows absolute path like `C:\file.txt` on a Unix system (or vice versa) is rejected with a clear error message. +### Empty directory detection + +When `list_directory` encounters an empty directory or a directory where all entries are hidden by ignore patterns (e.g., only a `.git` folder when `ignore_vcs: true`), it explicitly reports the state: + +- **Empty directory**: "Directory is empty: /path/to/dir" +- **All entries ignored**: "Directory has no visible entries (N hidden by ignore patterns): /path/to/dir" + +This helps agents distinguish between an empty directory and a tool failure, avoiding unnecessary retries with shell commands. + ## Available Tools | Tool | Description | @@ -36,7 +45,7 @@ When a file is not found, error messages include the resolved absolute path to h | `read_multiple_files` | Read several files in one call (more efficient than multiple `read_file`) | | `write_file` | Create or overwrite a file with new content | | `edit_file` | Make line-based edits (find-and-replace) in an existing file | -| `list_directory` | List files and directories at a given path | +| `list_directory` | List files and directories at a given path (explicitly reports empty directories) | | `directory_tree` | Recursive tree view of a directory | | `create_directory` | Create a new directory (creates parent directories as needed) | | `remove_directory` | Remove an empty directory | diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/shell/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/shell/index.md index 297c457ef9a..4649dff3aad 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/shell/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/shell/index.md @@ -15,6 +15,17 @@ The shell tool allows agents to execute arbitrary shell commands synchronously. Commands have a default 30-second timeout and require user confirmation unless `--yolo` is used. For servers, watchers, and other long-running commands, add the [`background_jobs`](../background-jobs/index.md) toolset alongside `shell`. +### Shell interpreter detection + +The shell tool automatically detects and names the resolved shell interpreter (e.g., `bash`, `zsh`, `powershell`, `pwsh`, `cmd`) in its description to the model, along with the operating system (Linux, macOS, Windows). This helps models use the correct shell syntax for the host environment. + +For example: + +- On Linux with bash: "Executes the given shell command with bash on Linux." +- On Windows with PowerShell: "Executes the given shell command with powershell on Windows. Use Windows PowerShell 5.1 syntax: chain commands with ";" (not "&&"), and avoid POSIX commands/flags like "ls -la"." + +This reduces wasted turns where models assume POSIX syntax on Windows or vice versa. + ## Configuration ```yaml diff --git a/_vendor/modules.txt b/_vendor/modules.txt index bf8f1dcb02a..cb31d7d120a 100644 --- a/_vendor/modules.txt +++ b/_vendor/modules.txt @@ -4,4 +4,4 @@ # github.com/docker/cli v29.7.1+incompatible # github.com/docker/compose/v5 v5.4.0 # github.com/docker/model-runner v1.1.36 -# github.com/docker/docker-agent v1.122.0 +# github.com/docker/docker-agent v1.123.0 diff --git a/go.mod b/go.mod index 3a95db34e74..31ce5dfa695 100644 --- a/go.mod +++ b/go.mod @@ -11,7 +11,7 @@ require ( github.com/docker/buildx v0.36.1 github.com/docker/cli v29.7.1+incompatible github.com/docker/compose/v5 v5.4.0 - github.com/docker/docker-agent v1.122.0 + github.com/docker/docker-agent v1.123.0 github.com/docker/model-runner v1.1.36 github.com/moby/buildkit v0.32.2 github.com/moby/moby/api v1.55.0 diff --git a/go.sum b/go.sum index 69f1b492b3d..beb75efa79e 100644 --- a/go.sum +++ b/go.sum @@ -150,6 +150,8 @@ github.com/docker/docker-agent v1.120.0 h1:aogSNNlZWiL/6EYmrXhEtkqIgEcL7wt2bhYIt github.com/docker/docker-agent v1.120.0/go.mod h1:HgHOV3OkqM1Hl0qD7iTCBZSBNWpy5mWN2s8tr2/NdOA= github.com/docker/docker-agent v1.122.0 h1:xOei5d7L1M0stvZNwULnOssOS4CzDRE2Xj7k192rS3Q= github.com/docker/docker-agent v1.122.0/go.mod h1:HgHOV3OkqM1Hl0qD7iTCBZSBNWpy5mWN2s8tr2/NdOA= +github.com/docker/docker-agent v1.123.0 h1:u6U/Bx9Ci8+P6f2XKkSkV2oJPBVR/Nd4cB7QOxYzOdY= +github.com/docker/docker-agent v1.123.0/go.mod h1:HgHOV3OkqM1Hl0qD7iTCBZSBNWpy5mWN2s8tr2/NdOA= github.com/docker/docker-credential-helpers v0.9.3 h1:gAm/VtF9wgqJMoxzT3Gj5p4AqIjCBS4wrsOh9yRqcz8= github.com/docker/docker-credential-helpers v0.9.3/go.mod h1:x+4Gbw9aGmChi3qTLZj8Dfn0TD20M/fuWy0E5+WDeCo= github.com/docker/docker-credential-helpers v0.9.5 h1:EFNN8DHvaiK8zVqFA2DT6BjXE0GzfLOZ38ggPTKePkY=