Docker Agent is Dockerās open source runner for AI agents you describe in a YAML file instead of code. The docs pitch it as āto AI agents what docker run is to containersā: declare a model, instructions and tools, then launch it from the terminal as a Docker CLI plugin. The repository sits at about 4.5k stars under Apache-2.0 and shipped five tagged releases between September 28 and October 9, 2026.
The core loop in one line: docker agent run agent.yaml. This guide is built from the README and docs as of 2026-10-14. I read them; I did not run the tool for this article, so every command is documented, not benchmarked.
1. What Is Docker Agent?
Docker Agent builds and runs AI agents from a declarative config. It ships as a Docker CLI plugin (docker agent), accepts YAML or HCL, and the docs say plainly what it is not: not a code framework, not a hosted SaaS, not a model. It talks to many providers (Anthropic, OpenAI, Google, Mistral, OpenRouter and local models through Docker Model Runner, among others), attaches tools including any MCP server, and packages agents as OCI artifacts you can push to a registry.
~4.5k
Stars
GitHub repo page, Oct 14, 2026
Apache-2.0
License
Open source
v1.150.0
Latest release
Oct 9, 2026
Go
Stack
Docker CLI plugin
Read from the GitHub repo page and the releases feed on 2026-10-14 (the REST API was rate-limited from my network). The repo shows 521 forks; the v1.150.0 page lists three contributors. Stars move daily.
A naming note, because search results mix both names: the project used to be cagent. Dockerās docs say Docker Desktop 4.49 through 4.62 shipped it under that name, and 4.63 and later bundle it as Docker Agent. Traces remain: user config lives under ~/.config/cagent/ and the older CAGENT_* variables are still accepted as aliases.
The docs track main
The GitHub Pages docs say they follow the main branch and may describe features that are not released yet; the stable pages live at docs.docker.com/ai/docker-agent. If a property from the reference does not work on your version, check the release notes before debugging your YAML.
2. How It Works: Four Steps From YAML to a Running Agent
The mental model fits in four steps. Everything here comes from the configuration, tools and multi-agent pages of the docs.
1. Define it in a file
A config needs at least one agent and can add models, rag, mcps, providers, permissions, commands, skills and reusable toolsets, plus metadata for distribution. A top-level version key exists (the docs list schema 16 as current and say older files migrate automatically). Secrets stay out of the file: reference them as ${env.NAME}.
2. Run the loop, with limits
docker agent run opens a terminal UI, --exec runs one-shot tasks and serve api exposes HTTP. The loop calls the model, passes each tool call through a permission gate and repeats. Defaults worth knowing: max_iterations is 0 (unlimited), max_consecutive_tool_calls is 5, and session compaction triggers at 0.9 of the context window.
3. Equip it with toolsets
Built-ins cover filesystem, shell, think, todo, memory, fetch, RAG and more. MCP comes in three flavors: ref: docker:<name> runs a catalog server in a container through the MCP Gateway, command/args starts a local stdio process, and remote.url connects to a streamable HTTP or SSE server.
4. Compose and ship
sub_agents delegate through a transfer_task call; handoffs pass the whole session to a peer. docker agent share push publishes the YAML to any OCI registry, and serve mcp or serve api turns the same file into MCP tools or HTTP endpoints.
3. The YAML, Property by Property
These are the agent properties I would reach for first, with the defaults the reference page states.
modelA provider/model string such as openai/gpt-5-mini, or the key of a named entry under models:. Required unless harness is set.
descriptionOne line about the role. A coordinator uses it to choose whom to delegate to, so write it like API documentation.
instructionThe system prompt, inline or from instruction_file (relative paths only, no absolute paths and no ..).
toolsetsList of tools, each with a type: filesystem, shell, think, mcp and more. use_toolsets merges named groups defined at the top level.
sub_agents / handoffsLocal names or OCI references. sub_agents enables transfer_task; handoffs enables peer switching in the same session.
max_iterationsCaps the tool-calling loop. 0 means unlimited; the docs call 20 to 50 typical for development agents.
fallbackBackup models tried in order: retries (default 2) on 5xx errors and a cooldown (default 1m) after a 429.
hooksLifecycle hooks such as pre_tool_use, tool_guard and session_end, alongside structured_output for schema-constrained replies.
A two-agent team (the docsā debugger example, comments trimmed)
agents:
root:
model: openai/gpt-5-mini
description: Bug investigator
instruction: |
Examine error output, stack traces, and source to determine the root cause of a bug.
Describe the problem and its cause clearly.
Hand the implementation of any fix to the fixer agent.
sub_agents: [fixer]
toolsets:
- type: filesystem
- type: mcp
ref: docker:duckduckgo
fixer:
model: anthropic/claude-sonnet-4-5
description: Fix implementer
instruction: |
Produce fixes for bugs the investigator has diagnosed.
Keep changes small and focused, and add tests that guard against regressions.
toolsets:
- type: filesystem
- type: shellThe model strings are the docsā examples, not recommendations. Swap in whatever models your accounts can use today; a named model under models: lets you define provider, max_tokens and thinking_budget once and reference it by key.
MCP toolsets: the three flavors (separate docs examples, combined)
toolsets:
# 1. Docker MCP catalog, run in a container through the gateway
- type: mcp
ref: docker:github-official
tools: ["list_issues", "create_issue"]
# 2. Local stdio server
- type: mcp
command: python
args: ["-m", "mcp_server"]
env:
API_KEY: ${env.MY_API_KEY}
# 3. Remote server with a bearer token
- type: mcp
remote:
url: "https://mcp.linear.app/mcp"
transport_type: "streamable"
headers:
Authorization: "Bearer ${env.LINEAR_TOKEN}"Delegation caveats from the docs
- ā¢ transfer_task is sequential: the parent waits for the child, and the docs call it always auto-approved. For parallel work use the background_agents toolset.
- ā¢ handoffs are model-driven. The model may skip the handoff call, so use force_handoff when a pipeline must be strict (no self-reference, no cycles).
- ā¢ Tag-based external sub-agents are re-resolved on every run. Pin a @sha256: digest to avoid slow or stalled startups.
4. Quickstart: Verified Against the README on 2026-10-14
Every command below comes from the README or the docs page named in its label. I am listing them, not running installers for you: read what a package does before you install it.
Install (README; winget from docs.docker.com)
# Docker Desktop 4.63+ bundles the plugin docker agent version # Homebrew (macOS / Linux) brew install docker-agent docker-agent version # Windows (docs.docker.com) winget install Docker.Agent
Set a provider key and run your YAML (README)
export OPENAI_API_KEY=sk-... docker agent run agent.yaml
Other ways to run (docs home and quickstart)
docker agent run docker agent run myorg/agent:tag docker agent new docker agent run --exec agent.yaml "Create a Dockerfile for a Node.js app" cat error.log | docker agent run --exec agent.yaml "What's wrong in this log?"
Local model, no API key (Set Up a Model page)
docker model pull ai/qwen3 docker agent doctor docker agent run --model dmr/ai/qwen3
docker agent vs docker-agent
Homebrew installs a docker-agent binary. To call it as docker agent, the README says to symlink it to ~/.docker/cli-plugins/docker-agent, or you can run docker-agent directly. Docker Desktop 4.63+ already includes the plugin. The README also lists ANTHROPIC_API_KEY and GOOGLE_API_KEY as alternatives to OPENAI_API_KEY.
5. Guardrails: Safety Modes, Sandbox, Secrets and Telemetry
An agent with filesystem and shell toolsets can change your machine. The docs give you four safety modes and a sandbox; read them before the first run.
strict
Asks before every call.
balanced
Runs calls the runtime labels safe, asks about the rest.
restricted
Runs safe calls and denies the rest without asking. Meant for unattended runs.
autonomous
Runs everything. This is the legacy --yolo behavior; deny rules and guard hooks still apply.
Guardrails sketch assembled from the docsā separate examples (not a file I ran)
agents:
root:
model: anthropic/claude-sonnet-4-5
instruction: You are a careful repo assistant.
max_iterations: 30
toolsets:
- type: filesystem
- type: shell
permissions:
allow:
- "read_*"
- "shell:cmd=ls*"
ask:
- "shell:cmd=git push*"
deny:
- "shell:cmd=sudo*"
runtime:
safety: balancedPermissions are not a security boundary
The permissions page states they are enforced client-side and help prevent accidents. For isolation it points to --sandbox, which runs the agent in a Docker sandbox VM, mounts only the working directory read-write and defaults egress to deny. Also: a third-party YAML can declare runtime.safety: autonomous, which runs every call without prompting. Read configs before you run them.
Telemetry is on by default
The telemetry page lists command names and arguments, agent names and model types, tool names with success or failure, token counts with estimated cost, and session metadata. It warns that arguments and error text can include prompts, file paths or secrets. Opt out with the environment variable below, set before commands that may touch sensitive data.
Opt out of telemetry and run inside a sandbox (docs)
TELEMETRY_ENABLED=false docker agent run agent.yaml docker agent run --sandbox agent.yaml
MCP binaries can auto-install
If an MCP command is not on your PATH, the MCP page says Docker Agent looks it up in the aqua registry and installs it. Disable that per toolset with version: "false" or globally with DOCKER_AGENT_AUTO_INSTALL=false. Secrets resolve from env vars, Compose secrets, ~/.config/cagent/.env and a few other sources, and redact_secrets is on by default; the docs call redaction defense in depth, not a guarantee.
6. Use Cases That Fit
Four places where a YAML-first runner earns its keep.
Team agents as shareable artifacts
Review a YAML in a pull request, push it to your registry, and let teammates run docker agent run myorg/agent:tag. It is the image workflow you already know, including digest pinning.
One-shot automation in scripts
--exec plus a pipe turns an agent into a Unix tool: feed it a log or a diff and read the answer on stdout. The docsā own example pipes an error log into it.
Agents as tools inside Claude Code or Claude Desktop
serve mcp exposes each agent in a config as a separate MCP tool. The HTTP transport defaults to a restricted safety policy and needs --auth-token on non-loopback addresses.
Evaluate before you trust
docker agent eval replays recorded sessions and scores tool calls, relevance and assertions, with --repeat for pass@k and --baseline to fail CI on regressions. It needs a container runtime.
Distribute, expose, evaluate (docs commands)
docker agent share push ./debugger.yaml myusername/debugger docker agent share pull myusername/debugger docker agent serve mcp ./agent.yaml docker agent serve api agent.yaml --listen 127.0.0.1:8080 docker agent eval agent.yaml
Heads up for serve api: set --auth-token when listening beyond loopback, and --session-workingdir-root for multi-user setups. An attached docker agent run --listen has no built-in authentication, per the docs.
7. When NOT to Use Docker Agent
A YAML runner fits a narrow band of problems. These are the situations where I would look elsewhere, or at least slow down.
A fast-moving surface
Five tags in twelve days (v1.146.0 on Sep 28 to v1.150.0 on Oct 9), docs that track main and a recent rename from cagent. Pin your version and read release notes on every upgrade.
Telemetry is opt-out
Fine on a personal laptop; a policy conversation in regulated environments, because arguments can carry sensitive text and you must enforce TELEMETRY_ENABLED=false yourself.
A small community
About 4.5k stars and three contributors listed on the latest release, with help routed to a Docker Community Slack channel. Expect fewer third-party guides and fewer battle-tested recipes.
YAML has a ceiling
Branching business logic, custom state, typed tool code and unit tests around your own functions push a declarative file past what it is good at. That is where a code-first framework pays off.
ā Use it if...
- ā¢ You already live in Docker: Desktop, Compose, registries
- ā¢ You want agents as reviewable files in git, not modules
- ā¢ You want a planner-plus-coder team without glue code
- ā¢ One artifact should run in a terminal, behind HTTP or as an MCP tool
- ā¢ Your agents are mostly tool-calling loops over files, shell and MCP servers
ā ļø Consider a code-first framework if...
- ā¢ You need custom control flow, durable state or human checkpoints written as code
- ā¢ Your team tests agents with typed interfaces and unit tests in one language
- ā¢ You ship an SLA-backed product and need a mature, stable API
- ā¢ Your policy forbids opt-out telemetry and you cannot enforce the variable
- ā¢ You need a hosted multi-tenant runtime: this is a CLI and a self-run server
Golden rule
Treat a third-party agent YAML like a shell script: read it before you run it. The prompt, the toolsets, the MCP commands and the safety defaults all live in that one file.
Conclusion
Docker Agent makes a clear bet: an agent is a configuration artifact, versioned in git, shared through a registry and executed by a small runtime. If your team already thinks in images and Compose files, the bet is easy to adopt, and the guardrails the docs describe (safety modes, a sandbox, secret redaction on by default) ask the right questions.
Start small: one agent, filesystem toolset with readonly: true, balanced mode, telemetry off. Add a sub-agent only after the single agent behaves, and add evals before anyone depends on it. If you need agents like this wired into a real stack with guardrails, that is the kind of gap I close in project rescues.
