# docker/docker-agent: Declarative YAML Agents as a Docker CLI Plugin

> Docker Agent is an Apache-2.0 Go plugin that runs AI agents defined in YAML, with MCP toolsets, multiple model providers and OCI-based sharing. Here is how it installs, what the config actually controls, and where the approach runs out of road.

**docker/docker-agent** — AI Agent Builder and Runtime by Docker Engineering

- Repository: https://github.com/docker/docker-agent
- Website: https://docker.github.io/docker-agent/
- Stars: 3,367 · Forks: 477
- Language: Go
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/docker-docker-agent

## The gap docker-agent fills: agents as versioned config, not code

Most agent frameworks ask you to write a program. Docker Agent asks you to write a file. The README describes the project as a way to "Build, run, and share AI agents with a declarative YAML config" and calls out that no code is required. That framing is the whole product thesis.

The audience follows from it. If you are a platform or infrastructure engineer who already treats Dockerfiles and compose files as reviewable artifacts, an agent declared in YAML fits your existing habits: it diffs, it reviews, it rolls back. If you are a Python developer who wants fine-grained control over the agent loop, this is a layer above you rather than a replacement for your code.

The repository confirms the intent. A top-level agent-schema.json sits next to golang_developer.yaml, which the README says the maintainers use to build the project itself: `docker agent run ./golang_developer.yaml`. Dogfooding a schema-bearing config file is a reasonable signal that the YAML is meant to be the interface, not a convenience wrapper around something else.

## How the YAML, toolsets and model providers fit together

A config declares one or more agents under an `agents:` key. Each entry names a `model` in provider/model form, a `description`, an `instruction` block, and a `toolsets` list. The README example uses `openai/gpt-5-mini` and a single toolset of `type: mcp` with `ref: docker:duckduckgo`.

The `ref` is the interesting part. Toolsets of type `mcp` point at a Model Context Protocol server, and the README states these can be local, remote, or Docker-based. That means tool acquisition is not a build step in your agent config; it is a reference resolved at run time. The same shape appears for models: the README lists OpenAI, Anthropic, Gemini, AWS Bedrock, Mistral, xAI and Docker Model Runner, and go.mod carries the corresponding SDKs (anthropic-sdk-go, aws-sdk-go-v2/service/bedrockruntime, and others), so provider selection is a string swap rather than a code change.

Multi-agent orchestration is declared rather than programmed. The README says teams of specialized agents "delegate tasks automatically", and the examples directory contains files such as agent_switching_commands.yaml and background_agents.yaml that suggest delegation and handoff are configured, not hand-coded. The runtime also ships built-in think, todo and memory tools, plus pluggable RAG with BM25, embeddings, hybrid search and reranking.

Sharing is handled through OCI. The README states you can push agents to any OCI registry and pull and run them anywhere, with `docker agent run myorg/agent:tag` as the invocation. That reuses registry auth and distribution you likely already have.

## Installing docker-agent and running a first agent

There are three install paths in the README. Docker Desktop 4.63 or newer ships the CLI plugin pre-installed, so `docker agent` works with no extra step. Homebrew users can install the standalone binary and either run it directly or symlink it into the Docker CLI plugin directory. Binary releases from GitHub follow the same symlink pattern.

For the Homebrew path, the README gives the install command and names the symlink target:

```bash
brew install docker-agent
```

After that, the README says to symlink the binary to ~/.docker/cli-plugins/docker-agent to use it as `docker agent`, or to run `docker-agent` directly.

Before the first run you need a model. The README shows exporting a provider key, or using Docker Model Runner for local models:

```bash
export OPENAI_API_KEY=sk-...
```

The same pattern applies to ANTHROPIC_API_KEY, GOOGLE_API_KEY and the other providers the README names. The linked Set Up a Model page is where the documentation says the full walkthrough lives.

With a key in the environment, the smallest useful config is the README's own example. Save it as agent.yaml:

```yaml
agents:
  root:
    model: openai/gpt-5-mini
    description: A helpful AI assistant
    instruction: |
      You are a knowledgeable assistant that helps users with various tasks.
      Be helpful, accurate, and concise in your responses.
    toolsets:
      - type: mcp
        ref: docker:duckduckgo
```

Then run it. The README's quick start shows the file-based invocation:

```sh
docker agent run agent.yaml
```

What you should see is an interactive session driven by the TUI the README links under features. If you would rather not write YAML by hand, the README lists `docker agent new` to generate a new agent interactively, and `docker agent run` with no argument to run the default agent.

## Where the declarative model gets in the way

The strongest limitation is version churn. Three releases landed in the three days before the last push on 2026-09-10, and the repository carries a CHANGELOG.md at the top level. A fast release cadence on a tool whose primary interface is a config file means your YAML is coupled to a schema that moves. The agent-schema.json file is the artifact to diff before upgrading, and the README does not document a deprecation policy or a compatibility guarantee for existing configs.

Second, the plugin path is a real dependency. If your Docker Desktop is older than 4.63, or if you run Docker Engine without Desktop, you are on the Homebrew or binary path plus a symlink. That is not hard, but it is a manual step the README describes rather than automates, and it is the kind of thing that breaks silently when a package manager updates the binary location.

Third, telemetry is on by default in the sense that the README states anonymous usage data is collected, with a link to the telemetry page. The README does not describe an opt-out flag in the text available here. If your agents touch internal systems, read that page before the first production run rather than after.

Finally, the tool is the wrong choice when the agent logic is the product. If you need custom control flow inside the reasoning loop, or you are debugging token-by-token behaviour, a declarative layer adds a translation step between you and the model. Go straight to a provider SDK in that case.

## How this differs from LangChain-style agent code

The obvious alternative is a code-first agent framework such as LangChain, where the agent, its tools and its control flow are Python or TypeScript you write and import. The difference is not features; it is where the complexity lives.

In a code-first framework, adding a tool means writing a function, decorating it, and registering it. In docker-agent, adding a tool means adding an entry to `toolsets` that references an MCP server, and the README says that server can be local, remote, or Docker-based. You gain uniformity and lose the ability to do arbitrary things inside a tool. If your tool needs to read from a proprietary queue with custom retry semantics, you are writing an MCP server instead of a function, which is more work up front and more reusable afterwards.

The second difference is distribution. A code-first agent ships as a package or a container you build. A docker-agent config ships as an OCI artifact, per the README's push and pull description, and runs with `docker agent run myorg/agent:tag`. If your organization already has registry governance, that is a shorter path to sharing agents across teams than publishing a library.

The third is language. docker-agent is Go, and the go.mod shows Go 1.27 with a toolchain pin. You are not expected to write Go to use it, but you are expected to accept Go's release and build conventions if you build from source, including the CGO_ENABLED=1 and cross-compilation setup visible in the Dockerfile.

## Licence, telemetry and the cost of keeping up

The repository is Apache-2.0. That permits commercial use, modification and redistribution, and it includes an explicit patent grant. It does not give legal advice, and it does not answer the question of what happens to agent configs and prompts you push to a public OCI registry; that is a policy question for your own registry, not a licence question.

The SECURITY.md file at the top level is the place to look for the project's vulnerability reporting process. The README does not describe a support window or an LTS branch, so plan on tracking releases rather than sitting on one.

Upgrade cost is the practical concern. With three releases in three days, the cadence is high enough that a pinned version plus a changelog review is the only sane posture. The agent-schema.json file gives you a machine-checkable target: validate your configs against it in CI before bumping the binary. That converts an upgrade from a manual smoke test into a failing build. The README does not document rollback behaviour, so keep the previous binary around until the new one has run your configs.

## Conclusion

Adopt docker-agent if your team already runs Docker Desktop 4.63 or newer, wants agent definitions checked into git as YAML, and needs MCP toolsets from local, remote or Docker-based servers. Skip it if you need a stable configuration schema across upgrades, or if you are not willing to pin a version and diff agent-schema.json before every bump. Verify three things first: that your Docker Desktop build actually ships the plugin, that your chosen model provider is reachable from wherever the agent runs, and how the telemetry described in the docs interacts with your data policy.

## FAQ

### What is docker-agent?

It is a Docker CLI plugin, written in Go and licensed Apache-2.0, that lets you build, run and share AI agents from a declarative YAML config. The README describes multi-agent orchestration, MCP toolsets and support for multiple model providers including OpenAI, Anthropic, Gemini, AWS Bedrock, Mistral, xAI and Docker Model Runner.

### How do I install docker-agent?

Docker Desktop 4.63 or newer includes the CLI plugin, so `docker agent` works immediately. Otherwise the README gives two options: `brew install docker-agent`, or download a binary release and symlink it to ~/.docker/cli-plugins/docker-agent.

### What is a Docker agent?

In this project, a Docker agent is an AI agent declared under the `agents:` key of a YAML file, with a model, an instruction block and a list of toolsets. The README's minimal example uses `openai/gpt-5-mini` and one MCP toolset, and is run with `docker agent run agent.yaml`.

### Is Docker still used in 2026?

The README does not address Docker adoption. It does show that docker-agent is distributed as a Docker CLI plugin, with Docker Desktop 4.63 or newer shipping it pre-installed, and that agents can be pushed to any OCI registry.

### What are the 7 types of AI agents?

The README does not list agent types. It describes what docker-agent itself supports: multi-agent architecture where specialized agents delegate tasks automatically, built-in think, todo and memory tools, and MCP toolsets from local, remote or Docker-based servers.

### What is a Docker and why is it used?

The README does not explain Docker itself. It does state that docker-agent is a `docker` CLI plugin run as `docker agent`, and that agents can be pushed to any OCI registry, pulled and run anywhere.

## Sources

- [docker/docker-agent on GitHub](https://github.com/docker/docker-agent)
- [License: Apache-2.0](https://github.com/docker/docker-agent/blob/main/LICENSE)
- [Project website](https://docker.github.io/docker-agent/)
- [README](https://github.com/docker/docker-agent/blob/main/README.md)
- [Releases](https://github.com/docker/docker-agent/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/docker-docker-agent