Docker Agent: Run AI Agents Like Containers with a Single YAML File

Agents as configuration files

The core design decision behind Docker Agent is that an agent is a configuration file, not a program. You describe what the agent should do, which model it should use, and what tools it can reach, all in YAML (or HCL for teams that prefer it). Docker’s framing is that this lowers the barrier enough that building a multi-agent system no longer requires a software engineering background.

That matters more than it might sound. Most agent frameworks today assume you are comfortable with Python classes, async loops, and dependency management. A declarative file changes the audience. Product managers, analysts, and domain experts can read an agent definition and understand exactly what it will do. Reviewing an agent becomes closer to reviewing a Dockerfile than reviewing a service.

OCI registry distribution: agents as pushable, pullable artifacts

The second pillar is distribution. A finished Docker Agent can be pushed to and pulled from any OCI-compatible registry, the same mechanism that moves container images around the world. That single choice inherits an enormous amount of infrastructure for free: versioning, signing, access control, caching, and the registries teams already run.

It also makes agents genuinely shareable. An agent that works well can be published like any other artifact, pulled by a colleague, and run without a manual setup ritual. This is the part of the container analogy that carries the most weight. Containers did not win because isolation was new. They won because a standard artifact format made software portable across machines, teams, and clouds.

Mixing providers per role

Docker Agent does not tie you to a single model vendor. It supports OpenAI, Anthropic, Gemini, AWS Bedrock, Mistral, xAI, and fully local models through Docker Model Runner. Providers can be mixed per role within a single multi-agent team. Docker’s own example is a three-agent setup where a coordinator and a writer both run on Claude while the researcher runs on GPT-5.

That flexibility is a meaningful hedge. Model capabilities shift quickly, and teams that hard-code a provider into their orchestration layer pay a migration tax every time the landscape moves. Declaring the provider in configuration turns that migration into a one-line change. It also lets teams route sensitive work to local models while sending cheaper, less sensitive tasks to a cloud API.

Multi-agent orchestration and the MCP tool ecosystem

Docker Agent supports multi-agent orchestration directly: teams of specialized agents that delegate work to one another. The tool ecosystem is where the design gets interesting. Agents get built-in tools plus access to any MCP server, run locally, remotely, or inside its own Docker container for isolation.

That last option extends the isolation boundary to tools rather than agents. Running an MCP server in its own container means a misbehaving or compromised tool has a boundary around it. Given how much attention agent safety has attracted lately, from reports of agent collusion incidents in 2026 to broader questions about what autonomous systems do when nobody is watching, isolation stops being a nice-to-have. The MCP ecosystem itself is also maturing quickly, with protocol changes such as the shift toward stateless MCP servers built with the v2 SDK making containerized tool deployment simpler than it was a year ago.

Installation and requirements: Docker Desktop, Homebrew, or binary

Getting started requires three things: Docker installed, a way to run it, and access to at least one language model. As of the time of writing, Docker Desktop 4.63 or newer ships the plugin, so those users can simply run docker agent.

For everyone else, Homebrew offers brew install docker-agent, which installs the binary directly. It runs as docker-agent out of the box, or you can symlink it to ~/.docker/cli-plugins/docker-agent to use the docker agent form. The ~ there is the user’s home directory, so on a typical Linux or macOS machine the symlink lands at /home/yourname/.docker/cli-plugins/docker-agent. The same symlink trick applies to the binary release, which is available from GitHub Releases. The plugin architecture means Docker Agent slots into the CLI you already have rather than adding another standalone tool to your PATH.

Model setup and non-interactive runs

The simplest model setup is a cloud provider’s API key stored as an environment variable. Teams that prefer to keep inference on their own hardware can instead run a model locally through Docker Model Runner, with no cloud key required at all. That option pairs naturally with the isolation story: agents, tools, and models all running on the same machine, with nothing leaving it.

Agents can also be run non-interactively for a single task. That is the detail that makes Docker Agent interesting for automation. A one-shot agent invocation is exactly the shape a CI job or a scheduled script needs, and it is where the declarative approach starts to pay off beyond local experimentation.

Configuration and validation: the smallest real agent

The smallest real Docker Agent is a single agent.yaml file. Docker provides a schema validator built against the schema published in the project’s repository, which checks that a configuration is well-formed before anything runs. In the hands-on walkthrough, a three-agent configuration passed schema validation cleanly.

Clean schema validation sounds mundane, but it is the foundation of reproducibility. If a configuration validates against a published schema, then anyone with the same file and the same registry access should get the same agent behavior. That is the same guarantee a Dockerfile offers, and it is what makes an agent safe to commit, review, and share.

Project traction and Docker’s prior groundwork

Docker Agent is not a sudden pivot. The Go module history on pkg.go.dev shows early tagged releases from March 2026, and as of the time of writing the project has already passed 3,300 GitHub stars with nearly 10,000 commits. That commit count suggests a project built over time rather than a weekend experiment.

It also sits on groundwork Docker laid earlier. A July 2025 announcement extended Docker Compose to support agents and AI models directly, and Docker Model Runner shipped as a way to run models locally without a cloud API key. Docker Agent is the natural next step: the same declarative philosophy, extended from models and services to agents themselves.

What to watch

The significance of Docker Agent is not any single feature. It is the decision to treat agents as distributable artifacts. Once an agent is a file that validates against a schema, pushes to a registry, and pulls onto any machine, it inherits everything the container ecosystem spent a decade building: versioning, provenance, caching, and a mental model every engineer already has.

The open question is long-running, stateful agent workloads. A one-shot invocation maps cleanly onto a pipeline step, but an agent that holds context across hours or days has no obvious equivalent in the artifact model Docker is borrowing from. How the project handles persistence, restarts, and state migration will decide whether declarative agents stay a packaging convenience or become a genuine deployment target.

For more on this, see anthropic push trustworthy agents.

For more on this, see single loops multi agent.

For more on this, see workshop run applied ships.