Docker Agent: AI Agent Builder for the Docker CLI
/docker-agent
Docker Agent is Docker's own CLI plugin for building and running AI agents from a YAML file, installed via Docker Desktop, Homebrew, or a binary release. Model choice, tools, and instructions live in one config pushable to an OCI registry for a teammate to pull and run unchanged. Reach for it if you already live in the Docker CLI; skip it if you need years of production hardening, since this project is still young.
What is Docker Agent?
Docker Agent runs as a plugin for the docker CLI, invoked with `docker agent`, executing AI agents defined in YAML rather than in code. You set an agent's model, instructions, and toolsets — including MCP servers — inside that file, and the plugin runs it straight from your terminal. It handles a single agent or a delegating team, and a finished config can be pulled from an OCI registry the same way you'd pull a container image.
Key Capabilities
- ✓Multi-agent architecture — a root agent can delegate subtasks to a team of specialized agents automatically, per the README.
- ✓MCP-based tool ecosystem — beyond its built-in tools, any Model Context Protocol server, whether it runs locally, remotely, or as a Docker container, becomes available to an agent.
- ✓Model-provider agnostic — the README names Anthropic, OpenAI, Gemini, xAI, Mistral, AWS Bedrock, and Docker Model Runner as supported model sources.
- ✓YAML-first configuration — an agent's model, instructions, and toolsets live in one file that's easy to version, diff, and review.
- ✓Named reasoning tools — the README lists think, todo, and memory as built-in tools an agent can call on while working through a task.
- ✓Pluggable retrieval — combines BM25 keyword matching, embedding similarity, hybrid search, and reranking for RAG use cases, per the README.
- ✓OCI-based packaging — a working agent config can be pushed to any OCI registry and pulled or run elsewhere with the same command.
Potential Use Cases
- •Wiring an internal assistant that needs a specific mix of tools (say, a DuckDuckGo MCP server plus your own APIs) without writing a custom agent loop in Python.
- •Splitting a complex task across a small team of agents that each own a narrower job and delegate the rest, using the multi-agent setup the README describes.
- •Testing an agent against different model providers — OpenAI vs. Anthropic vs. a local model via Docker Model Runner — by swapping one line in the YAML instead of rewriting integration code.
- •Building a retrieval-augmented agent over your own documents using the built-in BM25, embedding, or hybrid RAG option instead of standing up a separate retrieval service.
- •Packaging a working agent as an OCI artifact so a teammate — or CI — can pull and run the exact same config.
Installation and Setup
Docker Desktop 4.63 and later ships the docker-agent CLI plugin pre-installed, so `docker agent` works out of the box if you're already on a recent Docker Desktop. Without Docker Desktop, `brew install docker-agent` gets you the binary on macOS/Linux via Homebrew — run it directly as `docker-agent`, or symlink it to `~/.docker/cli-plugins/docker-agent` so `docker agent` picks it up as a plugin. The README also points to binary releases on GitHub Releases for a manual install, using that same symlink step. Either path needs at least one model credential set as an environment variable — OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, and so on — unless you're running models locally through Docker Model Runner, in which case no API key is needed. The README links to a separate 'Set Up a Model' page that walks through configuring either option in more detail.
Running AI Agents
The base command is `docker agent run`, which runs the default agent with no arguments. Point it at a file with `docker agent run agent.yaml` to run your own setup, or at an OCI reference like `docker agent run myorg/agent:tag` to pull and run someone else's packaged agent directly. `docker agent new` scaffolds a new agent interactively instead of you writing YAML from a blank file. The README says more worked examples live in the repo's examples/README.md, and the project runs its own contributing workflow through the same CLI — `docker agent run ./golang_developer.yaml` — which is a decent sign the tool holds up outside toy demos.
Strengths
- ✓Installs the way Docker tooling normally does — pre-installed in Docker Desktop 4.63+, or one Homebrew command — no separate agent-framework install step.
- ✓Model choice isn't locked in: the same YAML config can point at OpenAI, Anthropic, Gemini, Bedrock, Mistral, xAI, or a local Docker Model Runner model.
- ✓Tool integration runs through MCP: an existing MCP server anywhere — self-hosted, off in the cloud, or packaged as a Docker image — becomes available to an agent without writing custom tool code.
- ✓Configs are portable artifacts: push one to an OCI registry, and a teammate runs the identical agent with `docker agent run myorg/agent:tag`.
- ✓Apache-2.0 license, so there are no copyleft obligations for downstream use.
Considerations and Limitations
- △The README gives no version history, changelog, or stability statement for the CLI itself — you're trusting a comparatively young project with something that will hold API keys and run arbitrary tool calls.
- △Running any agent needs either a paid model API key or Docker Model Runner set up for local models — there's no zero-config way to try it beyond the default agent's own model choice.
- △RAG, multi-agent delegation, and MCP tool wiring are named in the README, but the actual configuration syntax for each isn't spelled out there — you'd need the linked docs site to configure anything past the basic example.
- △The README states Docker Agent collects anonymous usage data by default, worth knowing if you're running it somewhere telemetry needs to be opt-in.
- △It's a Docker CLI plugin, so Docker itself is a hard dependency — this isn't a standalone binary you can drop into a non-Docker pipeline.
Alternatives to Docker Agent
Frequently Asked Questions
Docker Agent is released under the Apache-2.0 license, as listed on its GitHub repository.
Docker Agent's README lists Anthropic, OpenAI, Gemini, xAI, Mistral, AWS Bedrock, and Docker Model Runner as supported model providers, chosen per agent in the YAML config.
Docker Agent agents are configured in a YAML file that sets a model, a text instruction, and a list of toolsets — including MCP servers — for each agent, then run with `docker agent run agent.yaml`.
Docker Agent can run against local models through Docker Model Runner instead of a cloud API key, according to the README's install instructions.
Docker Agent lets you push an agent's YAML config as a package to any OCI registry, so others can pull and run the identical config with `docker agent run myorg/agent:tag`.
Docker Agent supports multi-agent systems: per the README, a root agent can hand off subtasks to a group of specialized agents that work together automatically.
The problem it solves
Building even a simple AI agent from scratch usually means writing glue code to pick a model client, register tools, and manage delegation between sub-agents — work that's awkward to version, review in a pull request, or hand to a teammate without also handing them the whole codebase. Docker Agent's README frames its own reason for existing around exactly that gap: agents described as YAML instead of code, run as a Docker CLI plugin, and shared as an OCI artifact the same way a container image is.
Who should try it — and who should skip
Try Docker Agent if you already run Docker day to day and want agent configs that live in version control as YAML instead of a bespoke Python script per agent — the multi-agent delegation and OCI-based sharing are the actual differentiators here. Skip it if you need an agent framework with years of production hardening and a large plugin ecosystem to lean on, or if you don't want Docker itself as a dependency; at 3,246 stars this is a comparatively new project, not an established one, going by the README's own scope.
Related repositories
Still deciding about docker-agent?
One click hands the question to an AI along with this page — see what it says about docker-agent.