docker-agent is a Docker CLI plugin for building AI agents from YAML
The README of docker-agent, hosted in the docker/docker-agent GitHub repository, presents it as a way to build, run and share AI agents using a declarative YAML config, a rich tool ecosystem and multi-agent orchestration. Its pitch is that you can create and run AI agents that collaborate on complex problems with no code required. It is a Docker CLI plugin, invoked as docker agent.
The basic workflow is to define agents in YAML, give them tools and let them work. The README's example config declares a single root agent with the model openai/gpt-5-mini, a short description ("A helpful AI assistant"), an instruction block telling it to be helpful, accurate and concise, and one toolset of type mcp that points at a Docker-based DuckDuckGo MCP server. The config is run with docker agent run agent.yaml.
The README lists seven headline features. Multi-agent architecture: teams of specialized agents that delegate tasks automatically. A rich tool ecosystem: built-in tools plus any MCP server, whether local, remote or Docker-based. Provider agnosticism: OpenAI, Anthropic, Gemini, AWS Bedrock, Mistral, xAI and Docker Model Runner, "and more". YAML configuration that is declarative, versionable and shareable. Advanced reasoning through built-in think, todo and memory tools. RAG with pluggable retrieval covering BM25, embeddings, hybrid search and reranking. And packaging: agents can be pushed to any OCI registry, then pulled and run anywhere.
There are three ways to install it. Docker Desktop 4.63 or later has the plugin pre-installed, so you just run docker agent. With Homebrew, brew install docker-agent installs the binary, which you can run directly or symlink to ~/.docker/cli-plugins/docker-agent to use it as docker agent. Binary releases can be downloaded from GitHub Releases and symlinked the same way.
To use it you need to set at least one API key (the README shows OPENAI_API_KEY, and mentions ANTHROPIC_API_KEY and GOOGLE_API_KEY as alternatives), or use Docker Model Runner for local models. The README shows four commands: docker agent run runs the default agent, docker agent run myorg/agent:tag runs an agent from an OCI registry, docker agent new generates a new agent interactively, and docker agent run agent.yaml runs your own config. More examples live in the repository's examples/ directory, and the README links to documentation on installation, model setup, a quick start, agents, models, tools, multi-agent setups, the configuration reference, the TUI, the CLI, MCP mode, RAG, model providers and Docker Model Runner.
Two closing notes. The maintainers say they use docker-agent to build docker-agent, running a golang_developer.yaml config for the purpose. And the tool collects anonymous usage data to improve itself, with a pointer to a Telemetry page.
Key facts
- docker-agent is a Docker CLI plugin, run as
docker agent, that builds and runs AI agents from a declarative YAML config with no code required. - It supports teams of specialized agents that delegate tasks, built-in tools plus any MCP server (local, remote or Docker-based), and RAG with BM25, embeddings, hybrid search and reranking.
- The README lists OpenAI, Anthropic, Gemini, AWS Bedrock, Mistral, xAI and Docker Model Runner as providers, "and more"; at least one API key is needed unless you use Docker Model Runner for local models.
- Agents can be pushed to any OCI registry and pulled and run elsewhere, for example with
docker agent run myorg/agent:tag. - Docker Desktop 4.63 or later ships the plugin pre-installed; other routes are Homebrew (
brew install docker-agent) and binary releases from GitHub Releases.
Why it matters
Agent frameworks usually mean writing code. docker-agent instead puts the whole agent definition (model, instructions, tools, sub-agents) into a YAML file that the README calls declarative, versionable and shareable. It also reuses Docker's existing plumbing: OCI registries as the distribution channel for agents, Docker-based MCP servers as tools, and Docker Model Runner for local models. The project's own maintainers say they use it to build itself.
Who it affects
Developers who already work with the Docker CLI and want to assemble agents without writing an orchestration layer. Anyone running Docker Desktop 4.63 or later has the plugin pre-installed. Teams that want to hand agents around as versioned artifacts can use the OCI registry push and pull flow. Because the README lists providers from OpenAI and Anthropic to AWS Bedrock and local models, it is not tied to one model vendor.
How to use it
On Docker Desktop 4.63 or later, run docker agent. Otherwise install with brew install docker-agent or download a binary from GitHub Releases, and symlink it to ~/.docker/cli-plugins/docker-agent if you want the docker agent form. Set at least one API key (for example OPENAI_API_KEY) or use Docker Model Runner for local models. Then try docker agent new to generate an agent interactively, docker agent run agent.yaml to run your own config, or docker agent run myorg/agent:tag to run one from a registry. The examples/ directory in the repository has more configs.
How solid is it
The only material is the project's README, which describes features in the maintainers' own words. It gives no benchmarks, performance figures, user counts or GitHub stars. It gives no release date or version number for docker-agent itself, and it does not name the authors or maintainers. The listed features are claims from the README, not independent measurements.
Risks and caveats
The tool collects anonymous usage data, and the README does not say what that data contains or how to opt out; it only points to a Telemetry page. No pricing or license is stated in the README. The provider list ends with "and more", and the README does not say which other providers are supported. Using cloud models requires your own API key, and the example config sends work to a hosted model (openai/gpt-5-mini) unless you switch to Docker Model Runner.
“Define agents in YAML, give them tools, and let them work.”
— docker-agent README