You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/configuration/agents/index.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -32,7 +32,7 @@ agents:
32
32
add_prompt_files: [list] # Optional: include additional prompt files
33
33
add_description_parameter: bool # Optional: add description to tool schema
34
34
redact_secrets: boolean # Optional: scrub detected secrets out of tool args, outgoing chat messages, and tool output
35
-
code_mode_tools: boolean # Optional: enable code mode tool format
35
+
code_mode_tools: boolean # Optional: let the agent write JavaScript to orchestrate tool calls (see Code Mode)
36
36
max_iterations: int # Optional: max tool-calling loops
37
37
max_consecutive_tool_calls: int # Optional: max identical consecutive tool calls
38
38
max_old_tool_call_tokens: int # Optional: token budget for old tool call content (disabled unless positive)
@@ -96,7 +96,7 @@ agents:
96
96
| `add_prompt_files` | array | ✗ | List of file paths whose contents are appended to the system prompt. Useful for including coding standards, guidelines, or additional context. |
97
97
| `add_description_parameter` | boolean | ✗ | When `true`, adds agent descriptions as a parameter in tool schemas. Helps with tool selection in multi-agent scenarios. |
98
98
| `redact_secrets` | boolean | ✗ | When `true`, scrubs detected secrets (API keys, tokens, private keys, etc.) out of tool-call arguments, outgoing chat messages, and tool output before they reach a tool, the model, or downstream consumers. See [Redacting Secrets](#redacting-secrets) below. |
99
-
| `code_mode_tools` | boolean | ✗ | When `true`, formats tool responses in a code-optimized format with structured output schemas. Useful for MCP gateway and programmatic access. |
99
+
| `code_mode_tools` | boolean | ✗ | When `true`, replaces the agent's individual tools with a single tool that runs a JavaScript script calling as many of them as needed in one turn. See [Code Mode](../../features/code-mode/index.md). |
100
100
| `max_iterations` | int | ✗ | Maximum number of tool-calling loops. Default: unlimited (0). Set this to prevent infinite loops. |
101
101
| `max_consecutive_tool_calls` | int | ✗ | Maximum consecutive identical tool calls before the agent is terminated, preventing degenerate loops. Default: `5`. |
102
102
| `max_old_tool_call_tokens` | int | ✗ | Maximum number of tokens to keep from old tool call arguments and results. Older tool calls beyond this budget have their content replaced with a placeholder, saving context space. Tokens are approximated as `len/4`. Truncation is disabled by default; set a positive value to enable it. Set to `-1` to disable truncation (unlimited). |
|`--model <ref>`| Override model(s). Use `provider/model` for all agents, or `agent=provider/model` for specific agents. Comma-separate multiple overrides. |
33
-
|`--session <id>`| Resume a previous session. Supports relative refs (`-1` = last, `-2` = second to last). An explicit ID that does not exist yet is created with that ID, so a supervisor can own the session ID upfront and reuse it across runs. |
33
+
|`--session <id>`| Resume a previous session. Supports relative refs (`-1` = newest by creation time, `-2` = second-newest, … — creation order, not last-used). An explicit ID that does not exist yet is created with that ID, so a supervisor can own the session ID upfront and reuse it across runs. |
34
34
|`-s, --session-db <path>`| Path to the SQLite session database (default: `<data-dir>/session.db`, so `~/.cagent/session.db` unless `--data-dir` is set) |
35
35
|`--session-read-only`| Open the TUI in read-only mode: conversation history is displayed but no new messages can be sent to the LLM. Cannot be used with `--exec`. |
36
36
|`--prompt-file <path>`| Include file contents as additional system context (repeatable) |
37
37
|`--attach <path>`| Attach an image file to the initial message |
38
38
|`--dry-run`| Initialize the agent without executing anything (useful for validating a config) |
39
-
|`--remote <addr>`| Use a remote runtime at the given address instead of running the agent locally|
40
-
|`--listen <addr>`| Expose this run's control plane over HTTP so an external process can drive the running TUI (send follow-ups, stream events, read the title). Accepts `host:port` or `unix://`, `npipe://`, `fd://`. See the [API Server](../api-server/index.md#listen). |
39
+
|`--remote <addr>`| Use a remote runtime at the given address instead of running the agent locally. Mutually exclusive with `--sandbox`, `--worktree`, `--worktree-pr`, `--worktree-base`, `--session`, `--session-db`, `--record`, and `--fake` — a remote runtime owns its own session storage and execution environment, so these local-only concerns don't apply.|
40
+
|`--listen <addr>`| Expose this run's control plane over HTTP so an external process can drive the running TUI (send follow-ups, stream events, read the title). Accepts `host:port` or `unix://`, `npipe://`, `fd://`. Hidden from `docker agent run --help` — like `debug`, it's a stable but advanced/automation-oriented flag rather than a day-to-day one. See the [API Server](../api-server/index.md#listen) guide for the full walkthrough. |
41
41
|`--lean`| Use a simplified, non-alternate-screen TUI. Unlike the default full-screen TUI, this renders inline in the normal terminal buffer — useful in environments where an alternate screen is unwanted (e.g. inside tmux panes, CI with a tty, or log-friendly pipelines). Displays an ASCII art banner on startup. |
42
42
|`--app-name <name>`| Override the application name label shown in the TUI (status bar, window title, "/exit" notifications). |
43
43
|`--sidebar`| Control sidebar visibility. Set to `--sidebar=false` to hide the sidebar and disable the Ctrl+B toggle (default: `true`). |
@@ -177,6 +177,16 @@ $ docker agent new --model openai/gpt-5
177
177
$ docker agent new --model dmr/ai/gemma3-qat:12B --max-iterations 15
178
178
```
179
179
180
+
### `docker agent getting-started`
181
+
182
+
Run a short (about 2 minutes), skippable interactive tour inside the chat UI: sending messages, approving tool calls, the command palette (<kbd>Ctrl</kbd>+<kbd>K</kbd>), slash commands, and how agents are configured. Aliased as `docker agent tour`. Requires an interactive terminal.
183
+
184
+
```bash
185
+
$ docker agent getting-started
186
+
```
187
+
188
+
Replay it anytime with this command, or with the `/getting-started` slash command inside a running TUI session.
189
+
180
190
### `docker agent models`
181
191
182
192
List models available for use with `--model`. By default only shows models for providers you have credentials for. Aliases: `docker agent models list`, `docker agent models ls`.
Entries are unioned with the gateway, the kit-resolved tool install hosts, and any `runtime.network_allowlist` declared by the agent. The launch summary lists every source separately so you can see which holes were punched by which layer.
579
589
590
+
### `docker agent debug`
591
+
592
+
Troubleshooting subcommands for inspecting how an agent config resolves and generating diagnostic output — useful when a config isn't behaving the way you expect. `debug` doesn't appear in `docker agent --help` (it's a diagnostic surface, not a day-to-day command), but every subcommand below is stable and fully supported.
593
+
594
+
```bash
595
+
$ docker agent debug <subcommand> [flags]
596
+
```
597
+
598
+
| Subcommand | Description |
599
+
| ---------- | ----------- |
600
+
|`config <agent-file>`| Print the fully-resolved, canonical form of an agent's configuration (defaults applied, references resolved). |
601
+
|`toolsets <agent-file>`| List every toolset each agent in the config exposes, with each tool's name and description. |
602
+
|`skills <agent-file>`| List the skills discovered for each agent, marking forked skills. |
603
+
|`title <agent-file> <question>`| Generate a session title for `<question>` using the same title-generation path the TUI uses (including any configured `title_model`), without starting a session. See [Session Titles](../sessions/index.md#session-titles). |
604
+
|`auth`| Print parsed Docker Desktop authentication info from the locally stored JWT (subject, issuer, expiry, username/email). Add `--json` for machine-readable output. |
605
+
|`oauth list`| List stored MCP OAuth tokens (resource, scope, expiry, redacted access token). Add `--json` for machine-readable output. |
606
+
|`oauth remove <resource-url>`| Remove a stored MCP OAuth token. |
607
+
|`oauth login <agent-file> <mcp-name>`| Perform an interactive OAuth login for a remote MCP server declared in the config, by its name or URL. See [Remote MCP Servers](../remote-mcp/index.md). |
608
+
609
+
```bash
610
+
# Examples
611
+
$ docker agent debug config agent.yaml
612
+
$ docker agent debug toolsets agent.yaml
613
+
$ docker agent debug skills agent.yaml
614
+
$ docker agent debug title agent.yaml "How do I configure a fallback model?"
> **`debug auth --json` prints the full bearer token**
622
+
>
623
+
> The text output of `debug auth` truncates the token to a short preview, but `--json` includes the complete, unredacted JWT in its `token` field. Never paste `debug auth --json` output into logs, issue trackers, or bug reports — anyone with that token can act as you against Docker Desktop's backend. Use the plain-text output (or redact the `token` field yourself) when sharing diagnostic output.
624
+
625
+
The `config`, `toolsets`, `skills`, and `title` subcommands also accept [runtime configuration flags](#runtime-configuration-flags) (`--working-dir`, `--models-gateway`, …); `title` additionally accepts `--model` to override the model used to resolve the config before generating the title.
626
+
627
+
### `docker agent completion`
628
+
629
+
Generate a shell completion script for `bash`, `zsh`, `fish`, or `powershell`.
Run `docker agent completion <shell> --help` for shell-specific installation instructions.
643
+
644
+
### Self-update
645
+
646
+
When installed from a standalone GitHub release binary, Docker Agent can opt in to updating itself. It's disabled by default; set `DOCKER_AGENT_AUTO_UPDATE` to a truthy value (`1`, `true`, `yes`, `on`) to enable it for a command or a shell session:
647
+
648
+
```bash
649
+
$ DOCKER_AGENT_AUTO_UPDATE=1 docker agent run
650
+
```
651
+
652
+
When enabled, every command checks the latest GitHub release before running. If a newer release exists, an interactive session asks whether to install it; a non-interactive session (CI, piped input) proceeds automatically. On yes, Docker Agent downloads the asset for your OS/architecture, verifies its checksum, replaces the current binary, and re-executes with the same arguments. The whole mechanism is fail-safe: any failure at any step falls back to running the current binary. Self-update never triggers for `version`, `help`, `--help`/`-h` (including per-subcommand help), `completion`, or the Docker CLI plugin metadata handshake.
653
+
654
+
See [Optional Self-Updates](../../getting-started/installation/index.md#optional-self-updates) for the full walkthrough. Docker Desktop and Homebrew installs already manage updates and don't need this.
655
+
580
656
## Global Flags
581
657
582
658
These flags are available on every `docker agent` command:
@@ -616,6 +692,7 @@ These flags are accepted by every command that loads an agent (`run`, `run --exe
616
692
|`--hook-session-end <cmd>`| Add a session-end hook command (repeatable). |
617
693
|`--hook-on-user-input <cmd>`| Add an on-user-input hook command (repeatable). |
618
694
|`--hook-stop <cmd>`| Add a stop hook command, fired when the model finishes responding (repeatable). |
695
+
|`--mcp-oauth-redirect-uri <url>`| Public HTTPS URL to advertise as the OAuth `redirect_uri` for MCP servers running in unmanaged OAuth mode. When set, docker-agent drives PKCE and the code exchange in-process instead of expecting the client to. See [Remote MCP](../remote-mcp/index.md) for details. |
0 commit comments