R.2
docker-agent commands
Every command of docker-agent 1.149.0 in the four groups of its root help, every global flag, and every serve subcommand with its default listen address.
The root help of docker-agent 1.149.0 lists 19 commands in four groups: Core, Diagnose, Advanced, and Additional. With subcommands, the vendored tree holds 47 pages. The binary is the Homebrew build. The Desktop plugin docker agent runs the same commands with a space in the name (conflict C48). The docs page features/cli is the only other reference, because /reference/cli/docker/agent/ does not exist (conflict C68).
Global flags
Every command accepts these flags.
| Flag | Default | Meaning |
|---|---|---|
--cache-dir | ~/Library/Caches/cagent on macOS | Override the cache directory |
--config-dir | ~/.config/cagent | Override the config directory. The docs add that DOCKER_AGENT_CONFIG_DIR and the legacy CAGENT_CONFIG_DIR set the same path |
--data-dir | ~/.cagent, or DOCKER_AGENT_DATA_DIR | Override the data directory, which holds session.db, worktrees, and plans |
-d, --debug | off | Enable debug logging |
--log-file | ~/.cagent/cagent.debug.log | Path of the debug log, used only with --debug |
-o, --otel | off | Enable OpenTelemetry tracing |
-h, --help | none | Print the help of the command |
Core commands
| Command | Purpose | Flags that matter | Needs | Section |
|---|---|---|---|---|
getting-started | Learn docker agent with a hands-on interactive tour | none. The tree has no page for it (conflict C75). The docs describe a two minute skippable tour, also reachable as docker agent tour | an interactive terminal | §5.1 |
run [<agent-file>|<registry-ref>] [message]... | Run an agent from a file, a registry reference, an alias, or the built-in default | see the table below | a model with a credential, Docker Model Runner, or --fake | §5.1 |
setup | Set up a model through one of four paths: a built-in provider, Docker Model Runner, a custom OpenAI-compatible endpoint, or the Claude Code harness | none | a terminal. The provider path writes ~/.config/cagent/.env | §5.1 |
share push <agent-file> <registry-ref> | Push an agent file to an OCI registry, in clear, with an optional signature or MAC in the annotations | --key (PEM, OpenSSH, or a 16 byte secret, or DOCKER_AGENT_ENCRYPT_KEY), --encrypt | registry access | §6.4 |
share pull <registry-ref> | Pull an agent file and, with a key, verify or decrypt it | --key, --force | registry access | §6.4 |
The flags of run
The run page lists 54 flags. This table groups the ones the manual uses, with their defaults.
| Group | Flags |
|---|---|
| Agent and input | -a, --agent (the team's first agent), --agent-picker [refs], --prompt-file (repeatable), --attach <image>, - reads the message from stdin |
| Output | --exec (no TUI), --last (only the final answer, needs --exec), --json (NDJSON events), --hide-tool-calls, --hide-tool-results, --on-event <type>=<cmd> |
| Approval | --safety strict|balanced|restricted|autonomous, --yolo (same as --safety autonomous, conflict C59) |
| Model | --model [agent=]provider/model (repeatable), --models-gateway, --dry-run |
| Session | --session <id or -1>, -s, --session-db (default <data-dir>/session.db), --session-read-only, --working-dir |
| Record and replay | --record [path] (a cassette plus a TUI e2e test), --fake <path>, --fake-stream [15] ms between chunks |
| Sandbox | --sandbox, --sbx (default true, and --sbx=false forces the removed docker sandbox plugin, conflict C60), --template (default docker/docker-agent-sbx-templates:latest), --sandbox-kit, --kit (repeatable), --kit-arg, --no-kit, --cloud (implies --sandbox), --sandbox-ttl (default 1h0m0s) |
| Hooks | --hook-pre-tool-use, --hook-post-tool-use, --hook-session-start, --hook-session-end, --hook-on-user-input, --hook-stop, all repeatable |
| Config | --flavor (repeatable, applied in order), --env-from-file, --code-mode-tools, --mcp-oauth-redirect-uri, --remote <addr> |
| Worktree | -w, --worktree [name] (default auto), --worktree-base <ref>, --worktree-pr <number or URL> (needs the GitHub CLI) |
| TUI | --lean, --sidebar (default true), --theme, --app-name, --disable-commands |
Diagnose commands
| Command | Purpose | Flags that matter | Needs | Section |
|---|---|---|---|---|
doctor [agent-file] | Report which providers have credentials, whether Docker Model Runner answers, and which model auto picks, and exit non-zero on an issue | --json, --env-from-file, --models-gateway | nothing. It runs docker model status --json to check the runner | §5.1 |
models [list|ls] | List the models --model accepts, from the gateway /v1/models first, then from the providers with credentials | -a, --all, -p, --provider, --format table|json, --models-gateway | nothing | §5.1 |
toolsets | List the 27 built-in toolset types | --format table|json | nothing | §5.3 and R.5 |
Advanced commands
| Command | Purpose | Flags that matter | Needs | Section |
|---|---|---|---|---|
alias add <alias-name> <agent-path> | Save a name for an agent file or registry reference with run options | --yolo, --safety (wins over --yolo), --model, --hide-tool-results, --sandbox | nothing | §5.1 |
alias list|ls, alias remove|rm <alias-name> | List or remove aliases | --json | nothing | §5.1 |
board | Open a Kanban TUI where each card runs an agent in a tmux session on its own git worktree | none | tmux, git, and projects in ~/.config/cagent/config.yaml | none |
debug auth | Print the Docker token in use and where it came from | --json | nothing | R.6 |
debug config <agent-file> [flavor...] | Print the canonical form of an agent file with the flavors applied | the debug group flags | nothing | §5.2 |
debug oauth list|login|remove | List stored OAuth tokens, log in to a remote MCP server, or remove a token | --json (list) | a browser for login | §5.3 |
debug skills <agent-file> | Show the skills an agent discovers | --json | nothing | §4.5 |
debug title <agent-file> <question> | Generate a session title from a question | --model | a model | §5.6 |
debug tool <agent-file> <tool-name> [parameters-json] | Call one tool directly, with real side effects and no model turn | -a, --agent, --json, --no-hook | whatever the tool needs | §5.3 |
debug toolsets <agent-file> | List the tools and parameter schemas of an agent | --json | nothing | §5.3 |
eval <agent-file> [<eval-dir>] | Replay saved sessions in containers and score them | -c, --concurrency (default 10), --judge-model (default openai/gpt-5.6-terra), --judge-type llm|evaluator (default llm), --agent-image (default the pinned docker/docker-agent:<version>), --base-image, --container-runtime (default docker), -e, --env, --keep-containers, --only, --output (default <eval-dir>/results), --repeat (default 1), --baseline, --regression-tolerance (conflict C65) | a container runtime and a judge model | §5.6 |
new [description] | Write a new agent file from a description | --model (anthropic, openai, google, dmr, or a custom provider, conflict C66), --max-iterations (default 20 for DMR, unlimited elsewhere) | a model | §5.1 |
plans create|delete|export|get|list|status|update | Edit the shared plans of the plan toolset from the host, with an optimistic lock | --file (- is stdin), --title, --author, --status, --expected-version (exit code 3 on conflict), --force, --output, --json | nothing | sub_agents, transfer_task, and background_agents |
sandbox allow <host>... | Add hosts to the persistent allowlist of every later --sandbox run | none | nothing | §1.2 |
sandbox deny|remove|rm <host>, sandbox list|ls | Remove a host, or list the allowlist | none | nothing | §1.2 |
serve a2a|acp|api|chat|mcp | Start an agent as a server | see the table below | a model | §6.1 to §6.3 |
sessions diff <session-a> <session-b> | Report the first tool call where two recorded sessions differ | --json, --fail-on-divergence, -s, --session-db | nothing | §5.6 |
The debug group shares one flag set: --code-mode-tools, --env-from-file, --flavor, the six --hook-* flags, --mcp-oauth-redirect-uri, --models-gateway, and --working-dir. The same flags appear on eval, new, and every serve subcommand.
The serve subcommands
| Subcommand | Transport | Default listen address | Session database | Auth and safety flags | Section |
|---|---|---|---|---|---|
serve a2a <agent-file> | HTTP, the Agent-to-Agent protocol | 127.0.0.1:8082 | <data-dir>/session.db | --auth-token, --insecure-no-auth, --cors-origin, --safety, -a (the team's first agent, conflict C64) | §6.3 |
serve acp <agent-file> | stdio, the Agent Client Protocol | none | <data-dir>/session.db | none | §6.2 |
serve api <agent-file>|<agents-dir> | HTTP, sessions and SSE | 127.0.0.1:8080 | session.db in the current directory (conflict C63) | --auth-token (empty disables auth), --max-request-size (default 1048576), --session-workingdir-root, --pull-interval (0 disables), --fake, --record | §6.1 |
serve chat <agent-file> | HTTP, /v1/chat/completions and /v1/models | 127.0.0.1:8083 | no flag | --api-key, --api-key-env, --insecure-no-auth, --cors-origin, --safety, --conversations-max, --conversation-ttl (default 30m0s), --request-timeout (default 5m0s), --max-idle-runtimes (default 4), --max-request-size, -a (all agents if not set) | §6.1 |
serve mcp <agent-file> | stdio by default, streaming HTTP with --http | 127.0.0.1:8081 with --http | no flag | --auth-token, --insecure-no-auth, and --safety only with --http, --attach [latest] to expose a running TUI, --tool-name, --mcp-keepalive (stdio only), -a (all agents if not set) | §6.2 |
The help text names the four safety modes on serve a2a, serve chat, and serve mcp --http, and states no default for them. The default inside each server is therefore not documented in the help.
Additional commands
| Command | Purpose | Flags that matter | Needs | Section |
|---|---|---|---|---|
completion | Generate the autocompletion script for a shell | its page is not in the vendored tree | nothing | none |
help | Help about any command | its page is not in the vendored tree | nothing | none |
version | Print the version and the commit hash | none | nothing | §1.1 |
On the capture machine docker-agent version printed v1.149.0 and Commit: Homebrew (our source record).
Docker Sandboxes (sbx) and Docker Agent (docker-agent) sbx 0.47.0, docker-agent 1.149.0 · bf4169c · 2026-10-07 · Edition 2026.10