Docker Agent: Build and Share AI Agents in YAML

What Docker Agent is

Docker Agent is an open-source tool from Docker for building, running and sharing AI agents from a declarative configuration file instead of glue code. You describe each agent in YAML (the docs also mention HCL): which model it uses, what its instructions are, which tools it may call and which other agents it can hand work to. Docker Agent then runs the agent loop, executes the tool calls and routes work between agents. The README sums up the pitch as defining agents in YAML, giving them tools, and letting them work.

It ships as a docker CLI plugin, so once installed the entry point is docker agent. The project is aimed at developers and platform teams who want agent setups that can be versioned in Git, reviewed like any other config, and distributed the same way container images are. The introduction page says the Docker team built it after years of building agents with various frameworks and repeatedly running into the same questions about how to make agents shareable and reproducible.

How Docker Agent works

A configuration file declares one or more agents under an agents key. The root agent is the one you talk to. Each agent has a model reference in provider/model form, a description, an instruction prompt and a list of toolsets. When the agent decides it needs to act, it emits a tool call; the runtime executes it and returns the result, and the agent continues from there. By default, tools with side effects such as shell commands and file writes ask the user for confirmation before they run, and the --yolo flag auto-approves everything.

Tools come from two places. Built-in toolsets cover the filesystem, shell, todo lists, memory, RAG, task transfer and background agents, enabled by adding their type to an agent. Everything else arrives through the Model Context Protocol: the docs describe Docker MCP servers run in containers via Docker's MCP Gateway (the recommended route), local stdio MCP servers, and remote MCP servers over streamable HTTP or SSE.

Multi-agent setups use two patterns that the docs explain side by side. With delegation (sub_agents), a parent agent calls the built-in transfer_task tool, the child works in its own sub-session with a clean task description, and the result flows back to the parent. With handoffs (handoffs), the whole conversation passes to a peer agent in the same session and the previous agent drops out of the loop, which suits pipelines and conversational routing. A third option, background_agents, is meant for independent tasks that can run at the same time. The docs note that transfer_task is always auto-approved so delegation does not stall on confirmations.

Key features

• Declarative agents: agents, models and tools live in a config file that can be versioned and shared.
• Multi-agent teams: hierarchical delegation, peer-to-peer handoffs and background agents can be combined in one config.
• Provider-agnostic models: the README lists OpenAI, Anthropic, Gemini, AWS Bedrock, Mistral, xAI and Docker Model Runner for local models, with more providers documented.
• MCP tool ecosystem: any MCP server, local, remote or containerized, can be attached as a toolset.
• Reasoning helpers: built-in think, todo and memory tools give agents scratch space and persistent notes.
• RAG: the rag toolset indexes documents in the background and supports embeddings, BM25 keyword search, hybrid search with result fusion, and reranking.
• OCI distribution: agents can be pushed to Docker Hub, GitHub Container Registry or any OCI registry and pulled and run elsewhere, optionally signed or encrypted with a key.
• Several front ends: an interactive terminal UI, a headless CLI, an HTTP API server with SSE streaming, an MCP server mode and an A2A server.
• Sandbox mode: the --sandbox flag runs the agent inside a Docker Sandboxes VM with the working directory mounted.

Getting started with Docker Agent

Docker Desktop 4.63 and later ships the plugin pre-installed. Otherwise the README offers Homebrew or binary releases from GitHub; for the binary, symlink it into ~/.docker/cli-plugins/docker-agent to use the docker agent form.

brew install docker-agent

You then need at least one model provider key, or Docker Model Runner for local models:

export OPENAI_API_KEY=sk-...        # or ANTHROPIC_API_KEY, GOOGLE_API_KEY, etc.

A minimal agent from the README uses a small OpenAI model and a DuckDuckGo search tool served over MCP:

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

Run it, or try the other quick-start entry points:

docker agent run agent.yaml
docker agent run
docker agent run myorg/agent:tag
docker agent new

docker agent new generates a new agent interactively, and running without arguments starts the default agent. Publishing an agent to a registry looks like this:

docker agent share push ./agent.yaml docker.io/username/my-agent:latest
docker agent share pull docker.io/username/my-agent:latest

To expose an agent to other tools, docker agent serve mcp ./agent.yaml makes it available to MCP clients such as Claude Desktop, Claude Code or Cursor over stdio, and docker agent serve api agent.yaml starts the HTTP API.

Use cases

• Team coding assistants: a coordinator agent that delegates to a developer agent with filesystem and shell access and a reviewer agent that checks the result, the example team the multi-agent docs walk through.
• Shared internal agents: push a vetted agent config to a private registry so everyone runs the same prompt, tools and model, and update it by pushing a new tag.
• Custom tools inside existing assistants: wrap a domain-specific agent with MCP mode and call it from Claude Code, Claude Desktop or Cursor.
• Back ends for web apps and CI: the API server exposes agents and sessions over HTTP with streamed runtime events, and can refresh an agent from a registry on an interval.
• Documentation question answering: point the RAG toolset at a folder of docs and let an agent search it before answering.
• Isolated experiments: run agents that need shell access inside a sandbox VM rather than directly on a laptop.

How Docker Agent compares

Most agent frameworks are libraries: you write Python or TypeScript code that wires models, tools and control flow together. Docker Agent takes the opposite stance and keeps agents as data in a config file, closer to how Compose describes services. That trade-off favors reproducibility, review and distribution over arbitrary custom logic; when you need code, the docs point to a Go SDK guide and to MCP servers for new tools. Its distinctive pieces relative to code-first frameworks are OCI packaging, the MCP-first tool model with containerized MCP servers, and the multiple serving modes (MCP, HTTP API, A2A) built into the same binary. Teams already invested in a code-first framework may find little reason to switch for a single agent, while teams that want many small, shareable agents may find the config-and-registry model a better fit.

Things to know before adopting Docker Agent

• Telemetry is on by default: the telemetry page says usage data is collected unless you set TELEMETRY_ENABLED=false. Command events include positional arguments, which for run and exec can contain prompts and file paths, and error events include error text, so the docs warn not to assume telemetry is free of secrets.
• Tool approvals: side-effecting tools prompt for confirmation by default; --yolo removes that safety net, and transfer_task is always auto-approved.
• Network exposure: the MCP HTTP transport listens on 127.0.0.1:8081 by default, and non-loopback MCP or A2A listeners require an --auth-token unless you explicitly pass --insecure-no-auth.
• A2A is early: the A2A page labels support as functional but evolving, with limited integration for tool calls, artifacts and memory.
• Model costs and keys: cloud providers need API keys and bill per token; Docker Model Runner is the documented path for local models.
• Sandbox prerequisites: --sandbox requires Docker Sandboxes to be installed and configured; files on the mounted working directory remain readable and writable by the agent.
• Signed agents: when signing with share push --key, the YAML itself is still pushed in clear, and passphrase-protected keys are not supported.

Project activity

As of October 2026 the docker/docker-agent repository has about 4,400 stars. It was created on September 1, 2025, is written in Go and is licensed under Apache-2.0, and its most recent push was on the day of writing. The contributing guide notes that the team uses Docker Agent to build Docker Agent. Full documentation is at docker.github.io/docker-agent, and the project has a channel in the Docker Community Slack.