Docker Agent

TL;DR Highlight

Define multi-agent setups in YAML and run them with docker agent

Who Should Read

Backend/DevOps developers who want to build agents declaratively without code and share them via OCI registries

Core Mechanics

One YAML file defines an agent
- Under agents you set model, description, instruction and toolsets.
- Run it with docker agent run agent.yaml.
Works as a docker CLI plugin
- It comes pre-installed with Docker Desktop 4.63+.
- You can also install via Homebrew (brew install docker-agent) or GitHub Releases binaries.
Multi-agent and MCP tools
- Teams of specialized agents delegate tasks automatically.
- Built-in tools plus any MCP server (local, remote or Docker-based) are supported.
Provider agnostic
- Supports OpenAI, Anthropic, Gemini, AWS Bedrock, Mistral, xAI, Docker Model Runner and more.
- Start with one API key or a local model via Docker Model Runner.
RAG and reasoning tools built in
- think, todo and memory tools are included.

Community Reactions

Too many agent harnesses, some say
- Commenters compared them to the JS frameworks of yesteryear.
- Another said releasing a harness before a good agent is putting the cart before the horse.
Tried it and found it brittle
- One user said that a few weeks ago it was the brittlest harness they had used.
- They plan to return when it matures.
Lack of sandbox and security info
- Commenters noted Docker's AI story should be about sandboxing, yet it is barely covered.
- One wanted command and credential ACLs to set agent boundaries before launch.
Operational opinions
- One team found a single orchestrator routing by capability easier than many concurrent agents.
- Another warned to read the terms on data retention first.

How to Apply

Run a minimal agent YAML locally
- Today, install with brew install docker-agent and set an API key env var.
- Save the YAML below as agent.yaml and run docker agent run agent.yaml.
Distribute team agents via OCI registry
- Push frequently used agent YAMLs to your internal OCI registry.
- Have teammates pull them with docker agent run.
Make a security and terms checklist before adopting
- Read the sandbox and Telemetry docs and confirm data retention scope.
- Connect write-capable tools only with confirmation.

Try It

copy & run

# Paste into a terminal (based on the README example, needs OPENAI_API_KEY)

brew install docker-agent
export OPENAI_API_KEY=sk-...

cat > agent.yaml <<'EOF'
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
EOF

docker-agent run agent.yaml

# Next: try docker agent new for interactive creation, or docker agent run myorg/agent:tag for a registry agent

Terminology

HarnessThe runtime wrapper around an LLM that handles tool calls, loops and state. Think of it as the drivetrain, not the engine.

MCPA standard protocol for agents to connect to external tools. Like a USB port for AI.

OCI registryThe standard store for pushing and pulling Docker images. Agent configs can be stored there too.

BM25A classic keyword-frequency scoring method for search.

RerankingA step that reorders first-pass search results using a more precise model.