docker-agent

docker-agent command [options] [args]docker agent command [options] [args]

docker-agent builds, runs, and shares AI agents from a YAML or HCL config. It is a standalone Go binary and a docker CLI plugin: symlink it to `~/.docker/cli-plugins/docker-agent` and invoke it as docker agent. Docker Desktop 4.63+ ships the plugin. Homebrew formula docker-agent. GitHub Releases provide binaries. Current line is v1.149.0 (Apache-2.0, Docker Engineering).`docker-agent run` without a config uses `docker-agent.yaml`, `docker-agent.yml`, or `docker-agent.hcl` in the current directory when present; otherwise a built-in default agent. Configs name agents, models, and toolsets (files, shell, git, MCP, RAG, and others). Multi-agent teams delegate work. Agents can be pushed to any OCI registry.Needs at least one model: an API key (`OPENAIAPIKEY`, `ANTHROPICAPIKEY`, `GOOGLEAPIKEY`, …), Docker Model Runner for local models, or a custom OpenAI-compatible endpoint. `docker-agent setup` walks through those paths. Session state defaults to `<data-dir>/session.db` (`~/.cagent/session.db` unless --data-dir or DOCKER_AGENT_DATA_DIR). User config lives under `~/.config/cagent/`.The same binary exposes HTTP, MCP, A2A, ACP, and OpenAI-compatible chat servers, a Kanban TUI (board, needs tmux and git), evals, and session diffs.

docker-agent.yaml / .yml / .hcl

Agent file in the working directory used by run when no config argument is given

User settings (theme, board projects, providers). Flavors, hooks, and `.agentsignore` are documented with the config

Provider API keys stored by setup

Default SQLite session store. Override with --data-dir, -s, or DOCKER_AGENT_DATA_DIR

Provider credentials from the environment

Models gateway URL (also --models-gateway)

Set to `1` to skip the interactive setup offer

run [config] [message...]

Interactive TUI. --exec is headless (stdout). -a, --agent name selects an agent. --model ref overrides models (`provider/model`, or `agent=provider/model`, comma-separated). --safety mode is `strict`, `balanced`, `restricted`, or `autonomous` (--yolo is the autonomous alias). --session id resumes (relative refs: `-1` newest). -s, --session-db path. --last (with --exec) prints only the final answer. --json is NDJSON events, or with --last a JSON value. --sandbox / --cloud run in sbx. -w, --worktree [name] isolates a git worktree. --worktree-pr n checks out a GitHub PR (needs gh). --working-dir path. --lean is a non-alternate-screen TUI. --dry-run validates without running

Generate an agent config interactively. --model, --max-iterations

Short interactive tour in the chat UI. Needs a TTY

Interactive model setup: cloud provider, Docker Model Runner, custom endpoint, or Claude Code harness. Offered automatically when a run has no model unless DOCKER_AGENT_NO_SETUP=1

Diagnose credentials, Docker Model Runner, and `auto` model selection. Secrets are never printed. Non-zero when an agent could not run. --json, --env-from-file, --models-gateway

List models you can use with --model. Aliases models list, models ls. -p, --provider, --all, --format json

List built-in toolset types for `toolsets:` in YAML. --format `table`|`json`

HTTP control plane. -l, --listen default `127.0.0.1:8080`

Expose agents as MCP tools (stdio, or --http)

Agent-to-Agent protocol server

Agent Client Protocol over stdio

OpenAI-compatible `/v1/chat/completions` and `/v1/models`

Kanban TUI: each card is an agent in a tmux session on a git worktree. Needs tmux and git

Publish or fetch an agent as an OCI image

Compare two recorded sessions at the first diverging tool-call

Run recorded-session evals. -c concurrency, --only, --repeat, --keep-containers, --container-runtime

ls / list, add, rm. A `default` alias is what bare docker-agent runs

Shared settings for --sandbox runs

Call a tool directly, outside the LLM loop

Print version and commit

A model provider or Docker Model Runner is required. --exec --last declines pending tool approvals; set --safety for unattended runs. --worktree needs a git checkout and cannot combine with --remote or --sandbox. board needs tmux and git. Anonymous usage telemetry is on by default (see the telemetry docs). Paths still use the historical cagent directory names.

Docker Agent is an Apache-2.0 Go project from Docker Engineering. The plugin name is docker-agent; data and config still live under cagent paths. v1.149.0 was released in October 2026.

docker(1), docker-compose(1), claude(1), codex(1), opencode(1), ollama(1), tmux(1), git(1)

Source code · Documentation