CLI Reference

Complete reference for all Docker Agent command-line commands and flags.

Commands

docker agent run

Launch the interactive TUI with an agent configuration (.yaml, .yml, or .hcl).

$ docker agent run [config] [message...] [flags]

# Examples
$ docker agent run agent.yaml
$ docker agent run agent.yaml "Fix the bug in auth.go"
$ docker agent run agent.yaml -a developer --yolo
$ docker agent run agent.yaml --model anthropic/claude-sonnet-4-5
$ docker agent run agent.yaml --model "dev=openai/gpt-4o,reviewer=anthropic/claude-sonnet-4-5"
$ docker agent run agent.yaml --session -1  # resume last session
$ docker agent run agent.yaml --session -1 --session-read-only  # review last session without sending messages
$ docker agent run agent.yaml --prompt-file ./context.md  # include file as context

# Add hooks from the command line
$ docker agent run agent.yaml --hook-session-start "./scripts/setup-env.sh"
$ docker agent run agent.yaml --hook-pre-tool-use "./scripts/validate.sh" --hook-post-tool-use "./scripts/log.sh"

# Queue multiple messages (processed in sequence)
$ docker agent run agent.yaml "question 1" "question 2" "question 3"

# Customize TUI display
$ docker agent run agent.yaml --app-name "My Project"
$ docker agent run agent.yaml --sidebar=false
$ docker agent run agent.yaml --disable-commands="/cost,/eval,/model"

# Browse and pick an agent interactively
$ docker agent run --agent-picker
$ docker agent run --agent-picker=myorg/coder,myorg/researcher

# Run in an isolated worktree with a generated name (e.g. "focused_turing")
$ docker agent run agent.yaml --worktree
$ docker agent run agent.yaml -w "Refactor the auth package"

# Give the worktree (and its branch) an explicit name
$ docker agent run agent.yaml --worktree=auth-refactor

# Branch the worktree from another ref instead of the current HEAD.
# A remote-tracking ref is fetched first, so the worktree starts from the
# latest remote state.
$ docker agent run agent.yaml --worktree=auth-refactor --worktree-base origin/main

# Resume a worktree run later: the session remembers its worktree, so you
# don't pass --worktree again (which would fail — the worktree already exists).
$ docker agent run agent.yaml --worktree=auth-refactor   # first run, creates it
$ docker agent run agent.yaml --session -1               # resumes into the same worktree

# Check out an existing GitHub pull request to continue it (requires gh)
$ docker agent run agent.yaml --worktree-pr 123
$ docker agent run agent.yaml --worktree-pr https://github.com/owner/repo/pull/123

With --worktree-pr, the PR's head branch is checked out tracking its remote (via the GitHub CLI), so commits made during the run push straight back to the pull request. The worktree is stored under <data-dir>/worktrees/pr-<number>.

When the interactive session ends, the worktree is cleaned up based on its state:

• Clean (no uncommitted changes, untracked files, or new commits): the worktree and its branch are removed automatically.
• Has work (uncommitted changes, untracked files, or new commits): you're prompted to keep or remove it. Keeping preserves the directory and branch so you can return later; removing discards the worktree, its branch, and all that work.
• Non-interactive runs (--exec): the worktree is never cleaned up — it's left in place for inspection.

A worktree is only ever removed if --worktree created it for this run; a pre-existing worktree is never touched.

A kept worktree can be resumed: pass --session (a relative ref like -1, or the session id) and the run reattaches to the same worktree directory and branch automatically. Don't re-pass --worktree on resume — that would try to create a new worktree and fail because it already exists.

docker agent run --exec

Run an agent in non-interactive (headless) mode. No TUI — output goes to stdout.

$ docker agent run --exec [config] [message...] [flags]

# One-shot task
$ docker agent run --exec agent.yaml "Create a Dockerfile for a Python Flask app"

# With auto-approve
$ docker agent run --exec agent.yaml --yolo "Set up CI/CD pipeline"

# Multi-turn conversation
$ docker agent run --exec agent.yaml "question 1" "question 2" "question 3"

docker agent new

Interactively generate a new agent configuration file.

$ docker agent new [flags]

# Examples
$ docker agent new
$ docker agent new --model openai/gpt-5
$ docker agent new --model dmr/ai/gemma3-qat:12B --max-iterations 15

docker agent getting-started

Run a short (about 2 minutes), skippable interactive tour inside the chat UI: sending messages, approving tool calls, the command palette (Ctrl+K), slash commands, and how agents are configured. Aliased as docker agent tour. Requires an interactive terminal.

$ docker agent getting-started

Replay it anytime with this command, or with the /getting-started slash command inside a running TUI session.

docker agent models

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.

$ docker agent models [flags]

# Examples
$ docker agent models                                 # only providers you can use
$ docker agent models --all                           # every provider the catalog knows about
$ docker agent models --provider openai
$ docker agent models --format json | jq

When a models gateway is configured (--models-gateway, DOCKER_AGENT_MODELS_GATEWAY, or the user config), the command first queries the gateway's /v1/models endpoint. A non-empty response is authoritative for the models routed through the gateway: the listing shows the models the gateway serves (--provider filters within it), alongside any custom providers you have configured, which serve their models from their own endpoints rather than through the gateway. If the gateway cannot be queried or serves no usable model (endpoint not implemented, empty list, invalid response, timeout, missing authentication), the command falls back to the providers you have configured directly — provider API keys, provider aliases, and custom providers — plus the model catalog; a failure of one source never prevents the others from being listed. The Docker Desktop token is only sent (and required) when the gateway targets a trusted Docker URL.

docker agent toolsets

List the built-in toolset types available for use in an agent configuration. Each type can be referenced under toolsets: in an agent YAML file. Use this to discover what's available without leaving the terminal.

$ docker agent toolsets [flags]

# Examples
$ docker agent toolsets                                # human-readable table
$ docker agent toolsets --format json | jq             # machine-readable (type, summary, docs URL)

docker agent setup

Set up a model interactively. Four paths:

• Built-in cloud provider: pick a provider Docker Agent already knows (Anthropic, OpenAI, Google, Groq, Hugging Face, ...) and connect it. Credentials vary by provider: most take an API key or token, stored in the Docker Agent env file ~/.config/cagent/.env, while chatgpt signs in with your ChatGPT account in the browser.
• Local model: check Docker Model Runner and pull a model. No API key needed.
• Custom OpenAI-compatible endpoint: register an endpoint that is not built in (vLLM, LiteLLM, a corporate gateway, ...) with its base URL, API format, and API key variable, saved to your user configuration so its models work everywhere via --model <name>/<model>.
• Claude Code harness: use a Claude subscription through the official claude CLI. The wizard checks that the CLI is installed and logged in, offers to run claude auth login --claudeai (only after you confirm), and writes a ready-to-run claude-code-agent.yaml. See Coding Harnesses.

Ends with the exact command to start chatting. Secret values are never printed, and Docker Agent never reads or copies the Claude CLI's credentials.

The wizard is also offered automatically when an interactive run finds no usable model (decline-able; set DOCKER_AGENT_NO_SETUP=1 to suppress the offer).

$ docker agent setup

docker agent doctor

Diagnose the model and credential setup. Reports which model providers have credentials and where each credential comes from (shell environment, env file, Docker Desktop, …), whether Docker Model Runner is reachable and which models are pulled, and which model the auto selection would pick. Secret values are never printed. Exits with a non-zero status when an issue would prevent an agent from running, which makes it usable in scripts and CI.

$ docker agent doctor [agent-file|registry-ref] [flags]

With an agent file, also lists the environment variables that file requires (model credentials and tool secrets such as GITHUB_PERSONAL_ACCESS_TOKEN), whether each one is set, and from which source. When the file declares a claude-code harness agent, the doctor additionally checks that the official claude CLI is installed and logged in, reporting its version and safe login metadata (auth method, API provider, subscription type — never your email, organization, or tokens); a missing or logged-out CLI is reported as an issue with the claude auth login --claudeai remediation.

# Examples
$ docker agent doctor                        # credential, DMR, and auto-selection state
$ docker agent doctor ./agent.yaml           # also check that file's requirements
$ docker agent doctor --json | jq .issues

docker agent serve api

Start the HTTP API server for programmatic access. The argument can be a single agent file, a registry reference, or a directory — when given a directory, every .yaml/.yml/.hcl file in it is exposed as a separate entry under /api/agents.

$ docker agent serve api <agent-file>|<agents-dir>|<registry-ref> [flags]

Diagnostics: Set CAGENT_PPROF_ADDR=127.0.0.1:6060 (or --pprof-addr, a hidden flag) to start a live Go pprof server at /debug/pprof/. Use a loopback address; a non-loopback binding logs a security warning.

All runtime configuration flags (--working-dir, --env-from-file, --models-gateway, --hook-*, …) are also accepted.

# Examples
$ docker agent serve api agent.yaml
$ docker agent serve api agent.yaml --listen :8080
$ docker agent serve api ./agents/                          # directory of agent YAML/HCL configs
$ docker agent serve api ociReference --pull-interval 10    # auto-refresh

See API Server for the full HTTP API reference.

docker agent serve mcp

Expose agents as MCP tools for use in Claude Desktop, Claude Code, or other MCP clients. Defaults to stdio transport; use --http to start a streaming HTTP server instead.

$ docker agent serve mcp <config> [flags]

All runtime configuration flags are also accepted.

# Examples
$ docker agent serve mcp agent.yaml                                # stdio transport
$ docker agent serve mcp agent.yaml --http --listen 127.0.0.1:9090 # streaming HTTP
$ docker agent serve mcp agent.yaml --working-dir /path/to/project
$ docker agent serve mcp myorg/coder

See MCP Mode for detailed setup.

docker agent serve a2a

Start an A2A (Agent-to-Agent) protocol server.

$ docker agent serve a2a <config> [flags]

All runtime configuration flags are also accepted.

# Examples
$ docker agent serve a2a agent.yaml
$ docker agent serve a2a agent.yaml --listen 127.0.0.1:9000
$ docker agent serve a2a myorg/agent:tag

docker agent serve acp

Start an ACP (Agent Client Protocol) server over stdio. This allows external clients to interact with your agents using the ACP protocol.

$ docker agent serve acp <config> [flags]

All runtime configuration flags are also accepted.

# Examples
$ docker agent serve acp agent.yaml
$ docker agent serve acp ./team.yaml
$ docker agent serve acp myorg/agent:tag

See ACP for details on the Agent Client Protocol.

docker agent serve chat

Start an HTTP server that exposes one or more agents through an OpenAI-compatible Chat Completions API at /v1/chat/completions and /v1/models. This lets any tool that already speaks the OpenAI protocol — for example Open WebUI, curl, the OpenAI Python SDK, or LangChain — drive a Docker Agent agent without any custom integration.

$ docker agent serve chat <config> [flags]

# Examples
$ docker agent serve chat agent.yaml
$ docker agent serve chat ./team.yaml --agent reviewer
$ docker agent serve chat myorg/agent:tag --listen 127.0.0.1:9090
$ docker agent serve chat agent.yaml --api-key-env CHAT_BEARER_TOKEN

# Drive it from any OpenAI-compatible client
$ curl http://127.0.0.1:8083/v1/chat/completions \
    -H 'Content-Type: application/json' \
    -d '{"model": "root", "messages": [{"role": "user", "content": "hello"}]}'

See Chat Server for the full feature reference.

docker agent board

Launch a full-screen Kanban TUI for orchestrating multiple agents at once. Each card runs an agent in its own tmux session on an isolated git worktree; moving a card forward through the pipeline (Dev → Review → Push → Done) delivers the destination column's prompt to that card's agent. Projects and column prompts are stored in the global config file (~/.config/cagent/config.yaml) and can be managed from the TUI.

$ docker agent board

Takes no arguments or flags. Requires tmux and git to be installed.

See Kanban Board for key bindings, configuration, and workflow details.

docker agent share push / docker agent share pull

Share agents via OCI registries.

# Push an agent
$ docker agent share push ./agent.yaml docker.io/username/my-agent:latest

# Pull an agent
$ docker agent share pull docker.io/username/my-agent:latest

# Force pull, overwriting the local copy
$ docker agent share pull docker.io/username/my-agent:latest --force

See Agent Distribution for full registry workflow details.

docker agent eval

Run agent evaluations against a directory of recorded sessions.

$ docker agent eval <agent-file>|<registry-ref> [<eval-dir>|./evals] [flags]

All runtime configuration flags are also accepted.

# Examples
$ docker agent eval agent.yaml                            # use ./evals
$ docker agent eval agent.yaml ./my-evals                 # custom directory
$ docker agent eval agent.yaml -c 8                       # 8 concurrent evaluations
$ docker agent eval agent.yaml --keep-containers          # keep containers for debugging
$ docker agent eval agent.yaml --only "auth*"             # only run matching evals
$ docker agent eval agent.yaml --repeat 5                 # repeat each eval 5 times

See Evaluation for details on creating eval sessions and interpreting results.

docker agent version

Print the version and commit hash for your docker-agent install.

$ docker agent version
docker agent version v1.54.0
Commit: 1737035c

docker agent alias

Manage agent aliases for quick access.

# List aliases
$ docker agent alias ls

# List aliases as JSON
$ docker agent alias list --json

# Add an alias
$ docker agent alias add pirate /path/to/pirate.yaml
$ docker agent alias add other ociReference

# Add an alias with runtime options
$ docker agent alias add yolo-coder myorg/coder --yolo
$ docker agent alias add careful-coder myorg/coder --safety balanced
$ docker agent alias add fast-coder myorg/coder --model openai/gpt-4o-mini
$ docker agent alias add safe-coder myorg/coder --sandbox
$ docker agent alias add turbo myorg/coder --yolo --model anthropic/claude-sonnet-4-5

# Use an alias
$ docker agent run pirate
$ docker agent run yolo-coder

Alias Options: Aliases can include runtime options that apply automatically when used:

• --yolo — Auto-approve tool calls (unless explicitly denied) when running the alias. Legacy alias for --safety autonomous.
• --safety <mode> — Default safety mode (strict, balanced, or autonomous) when running the alias. Wins over the alias's yolo option; both are stored declaratively in the user config (aliases.<name>.safety / aliases.<name>.yolo), so you can also edit them there by hand.
• --model <ref> — Override the model for the alias
• --hide-tool-results — Hide tool call results in the TUI when running the alias
• --sandbox — Always run the alias inside a Docker sandbox

Alias safety options are defaults for new sessions: an explicit --safety/--yolo on the command line wins over them, they win over settings.safety/settings.YOLO and over anything declared in the agent YAML, and they never change the mode of a resumed session.

When listing aliases, options are shown in brackets:

$ docker agent alias ls
Registered aliases (3):

  fast-coder  → myorg/coder [model=openai/gpt-4o-mini]
  turbo       → myorg/coder [yolo, model=anthropic/claude-sonnet-4-5]
  yolo-coder  → myorg/coder [yolo]

Run an alias with: docker agent run <alias>

Pass --json to output aliases as a JSON array instead of the formatted table. Each entry includes the alias name and its options:

$ docker agent alias list --json
[
  {
    "name": "fast-coder",
    "path": "myorg/coder",
    "model": "openai/gpt-4o-mini"
  },
  {
    "name": "turbo",
    "path": "myorg/coder",
    "yolo": true,
    "model": "anthropic/claude-sonnet-4-5"
  },
  {
    "name": "yolo-coder",
    "path": "myorg/coder",
    "yolo": true
  }
]

JSON output is sorted by name and omits false/zero-valued fields. This is useful for scripting and automation.

$ docker agent alias add default /my/default/agent.yaml

docker agent sandbox

Manage settings shared by every --sandbox run — today, the persistent network allowlist that turns a Blocked by network policy 403 into a one-line, durable fix:

# Allow a host on every subsequent --sandbox run.
$ docker agent sandbox allow api.example.com

# Or several at once.
$ docker agent sandbox allow api.example.com registry.npmjs.org:443

# See what's persisted in ~/.config/cagent/config.yaml.
$ docker agent sandbox list

# Drop a host you no longer need.
$ docker agent sandbox deny api.example.com

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.

docker agent plans

Manage the plans agents collaborate on, from the host — without starting a session. Two plan systems are covered:

• Shared plans — the named, versioned documents of the plan toolset. Fully manageable: create, update, set status, export, delete.
• Session plans — the single per-session plan of the "draft, review, execute" workflow. Read-only here (list, get, export); they belong to their session and are changed from within it. A mutation aimed at a session plan fails with an unsupported error explaining what to do instead.

$ docker agent plans <subcommand> [flags]

Plan content passed via --file (a regular file, or stdin with --file -) is capped at 10 MiB — the same limit the plan storage itself enforces — and a directory or non-regular file (device, named pipe) is rejected up front; violations fail with an invalid_argument error.

Concurrency guard: every mutation (update, status, delete) requires exactly one of two mutually exclusive flags — the CLI is headless and never prompts:

• --expected-version <n> — the version you last read (from get or list; must be ≥ 1). When the plan changed in the meantime the command fails with a version conflict, reports the current version, leaves the plan untouched, and exits with code 3 (all other failures exit with 1).
• --force — deliberately write without the optimistic-lock guard (last writer wins).

create takes no guard: it is inherently create-only and conflicts (exit code 3) when the name already exists.

JSON output: every subcommand accepts --json. Success documents go to stdout with a top-level "schema_version": "1" marker and stable service-model keys (plans, plan, export, deleted) whose fields are snake_case (updated_at, session_id, bytes_written; a zero/unknown updated_at is omitted); empty plan lists encode as [], and no prose or ANSI is mixed in. Failures print a single JSON object to stderr:

{"schema_version":"1","error":{"code":"conflict","message":"...","scope":"shared","name":"p","expected_version":1,"current_version":2}}

with code one of conflict (including expected_version and current_version), not_found, invalid_argument, unsupported, corrupt, storage, or error; scope, name, and op are included where the failure carries them. Validation performed before a subcommand runs is covered too: a missing required flag, a violated --expected-version/--force group rule, and wrong positional arguments are reported as the same JSON object (code invalid_argument) whenever --json is present. One residual: flags are parsed left-to-right and parsing stops at the first unknown flag or invalid flag value, so such an error is reported as JSON only when --json appears before it on the command line; errors raised before a plans subcommand is resolved at all (e.g. an unknown subcommand) also remain plain text.

# Examples
$ docker agent plans list
$ docker agent plans list --json | jq '.plans[].name'
$ docker agent plans create release --file ./plan.md --title "Release plan" --status draft
$ cat plan.md | docker agent plans create release --file -
$ docker agent plans get release > plan.md            # content only; metadata on stderr
$ docker agent plans update release --file ./plan.md --expected-version 1
$ docker agent plans status release done --expected-version 2
$ docker agent plans export release --output ./plan.md
$ docker agent plans export release --output ./plan.md --force   # replace an existing file
$ docker agent plans delete release --expected-version 3
$ docker agent plans delete scratch --force
$ docker agent plans get --session <session-id>       # a session's plan
$ docker agent plans export --session <session-id> --output ./session-plan.md

Plans live under the data directory (~/.cagent/plans/ and ~/.cagent/session_plans/ by default), so --data-dir selects which store the commands operate on.

docker agent debug

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.

$ docker agent debug <subcommand> [flags]

# Examples
$ docker agent debug config agent.yaml
$ docker agent debug toolsets agent.yaml
$ docker agent debug skills agent.yaml
$ docker agent debug title agent.yaml "How do I configure a fallback model?"
$ docker agent debug auth --json
$ docker agent debug oauth list
$ docker agent debug oauth login agent.yaml github

The config, toolsets, skills, and title subcommands also accept runtime configuration flags (--working-dir, --models-gateway, …); title additionally accepts --model to override the model used to resolve the config before generating the title.

docker agent completion

Generate a shell completion script for bash, zsh, fish, or powershell.

$ docker agent completion <bash|zsh|fish|powershell>

# Examples
# Bash: load for the current session
$ source <(docker agent completion bash)

# Zsh: install permanently (adjust the path for your $fpath)
$ docker agent completion zsh > "${fpath[1]}/_docker-agent"

Run docker agent completion <shell> --help for shell-specific installation instructions.

Self-update

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:

$ DOCKER_AGENT_AUTO_UPDATE=1 docker agent run

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.

See Optional Self-Updates for the full walkthrough. Docker Desktop and Homebrew installs already manage updates and don't need this.

Global Flags

These flags are available on every docker agent command:

OpenTelemetry environment variables

When --otel is enabled, the standard OTel SDK env vars are honored (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_RESOURCE_ATTRIBUTES, etc.). Two additional Docker Agent-specific variables control GenAI instrumentation:

Runtime Configuration Flags

These flags are accepted by every command that loads an agent (run, run --exec, new, eval, serve api, serve mcp, serve a2a, serve acp, serve chat). They are listed once here to avoid repetition in the per-command tables above.

Agent References

Commands that accept a config support multiple reference types: