---
type: WebPage
title: Docker Agent — Run AI agents from YAML, like containers
description: ""
resource: https://docker.github.io/docker-agent/
tags: []
timestamp: 2026-10-09T10:00:39.737308Z
---

[Skip to content](#page-content)

[![](/docker-agent/assets/docker-mark.svg)
Docker Agent](/docker-agent/)

Search… ⌘K

Run AI agents like containers.

Getting Started
[Introduction](/docker-agent/getting-started/introduction/)
[Installation](/docker-agent/getting-started/installation/)
[Set Up a Model](/docker-agent/getting-started/set-up-a-model/)
[Quick Start](/docker-agent/getting-started/quickstart/)

Core Concepts
[Agents](/docker-agent/concepts/agents/)
[Models](/docker-agent/concepts/models/)
[Tools](/docker-agent/concepts/tools/)
[Multi-Agent](/docker-agent/concepts/multi-agent/)
[Agent Distribution](/docker-agent/concepts/distribution/)

Configuration
[Overview](/docker-agent/configuration/overview/)
[HCL Configuration](/docker-agent/configuration/hcl/)
[Agent Config](/docker-agent/configuration/agents/)
[Model Config](/docker-agent/configuration/models/)
[Tool Config](/docker-agent/configuration/tools/)
[Budget](/docker-agent/configuration/budget/)
[Custom Commands](/docker-agent/configuration/commands/)
[Hooks](/docker-agent/configuration/hooks/)
[Permissions](/docker-agent/configuration/permissions/)
[Ignoring Files](/docker-agent/configuration/agentsignore/)
[Sandbox Mode](/docker-agent/configuration/sandbox/)
[Structured Output](/docker-agent/configuration/structured-output/)
[Flavors](/docker-agent/configuration/flavors/)
[Model Routing](/docker-agent/configuration/routing/)
[User Settings](/docker-agent/configuration/user-settings/)

Built-in Tools

File & Shell

[File](/docker-agent/tools/file/)
[Filesystem](/docker-agent/tools/filesystem/)
[Git](/docker-agent/tools/git/)
[Shell](/docker-agent/tools/shell/)
[Environment](/docker-agent/tools/environment/)
[Date and Time](/docker-agent/tools/datetime/)
[Script](/docker-agent/tools/script/)
[Open URL](/docker-agent/tools/open-url/)
[Fetch](/docker-agent/tools/fetch/)

Agent Coordination

[A2A](/docker-agent/tools/a2a/)
[Handoff](/docker-agent/tools/handoff/)
[Transfer Task](/docker-agent/tools/transfer-task/)
[Background Agents](/docker-agent/tools/background-agents/)
[Background Jobs](/docker-agent/tools/background-jobs/)

Memory & Knowledge

[Memory](/docker-agent/tools/memory/)
[RAG](/docker-agent/tools/rag/)
[MCP Catalog](/docker-agent/tools/mcp-catalog/)
[MCP](/docker-agent/tools/mcp/)

Planning & Reasoning

[Calculator](/docker-agent/tools/calculator/)
[Random](/docker-agent/tools/random/)
[Think](/docker-agent/tools/think/)
[Plan](/docker-agent/tools/plan/)
[Todo](/docker-agent/tools/todo/)
[Tasks](/docker-agent/tools/tasks/)
[Scheduler](/docker-agent/tools/scheduler/)

Interaction

[User Prompt](/docker-agent/tools/user-prompt/)
[Model Picker](/docker-agent/tools/model-picker/)
[Session Context](/docker-agent/tools/session_context/)
[LSP](/docker-agent/tools/lsp/)
[OpenAPI](/docker-agent/tools/openapi/)
[Webhook](/docker-agent/tools/webhook/)
[API](/docker-agent/tools/api/)

Features
[Terminal UI](/docker-agent/features/tui/)
[Snapshots](/docker-agent/features/snapshots/)
[Kanban Board](/docker-agent/features/board/)
[Sessions](/docker-agent/features/sessions/)
[CLI Reference](/docker-agent/features/cli/)
[MCP Mode](/docker-agent/features/mcp-mode/)
[Coding Harnesses](/docker-agent/features/harnesses/)
[A2A Protocol](/docker-agent/features/a2a/)
[ACP](/docker-agent/features/acp/)
[API Server](/docker-agent/features/api-server/)
[Chat Server](/docker-agent/features/chat-server/)
[Evaluation](/docker-agent/features/evaluation/)
[Skills](/docker-agent/features/skills/)
[Code Mode](/docker-agent/features/code-mode/)
[Remote MCP Servers](/docker-agent/features/remote-mcp/)

Model Providers
[Overview](/docker-agent/providers/overview/)
[Anthropic](/docker-agent/providers/anthropic/)
[AWS Bedrock](/docker-agent/providers/bedrock/)
[Baseten](/docker-agent/providers/baseten/)
[Cerebras](/docker-agent/providers/cerebras/)
[Cloudflare AI Gateway](/docker-agent/providers/cloudflare-ai-gateway/)
[Cloudflare Workers AI](/docker-agent/providers/cloudflare-workers-ai/)
[ChatGPT](/docker-agent/providers/chatgpt/)
[DaoXE](/docker-agent/providers/daoxe/)
[DeepSeek](/docker-agent/providers/deepseek/)
[Docker Model Runner](/docker-agent/providers/dmr/)
[Fireworks AI](/docker-agent/providers/fireworks/)
[GitHub Copilot](/docker-agent/providers/github-copilot/)
[Google Gemini](/docker-agent/providers/google/)
[Groq](/docker-agent/providers/groq/)
[Hugging Face](/docker-agent/providers/huggingface/)
[Local Models](/docker-agent/providers/local/)
[MiniMax](/docker-agent/providers/minimax/)
[Mistral](/docker-agent/providers/mistral/)
[Moonshot AI](/docker-agent/providers/moonshot/)
[Nativ](/docker-agent/providers/nativ/)
[Nebius](/docker-agent/providers/nebius/)
[NVIDIA](/docker-agent/providers/nvidia/)
[OpenAI](/docker-agent/providers/openai/)
[OpenCode Go](/docker-agent/providers/opencode-go/)
[OpenCode Zen](/docker-agent/providers/opencode-zen/)
[OpenRouter](/docker-agent/providers/openrouter/)
[OVHcloud](/docker-agent/providers/ovhcloud/)
[Together AI](/docker-agent/providers/together/)
[Vercel AI Gateway](/docker-agent/providers/vercel/)
[xAI (Grok)](/docker-agent/providers/xai/)
[Provider Definitions](/docker-agent/providers/custom/)

Resources

Guides

[Tips & Best Practices](/docker-agent/guides/tips/)
[Thinking / Reasoning](/docker-agent/guides/thinking/)
[Managing Secrets](/docker-agent/guides/secrets/)
[Go SDK](/docker-agent/guides/go-sdk/)
[Managing Context & Compaction](/docker-agent/guides/compaction/)
[Running Agents Headless & in CI](/docker-agent/guides/headless/)

Community

[Contributing](/docker-agent/community/contributing/)
[Troubleshooting](/docker-agent/community/troubleshooting/)
[Telemetry](/docker-agent/community/telemetry/)
[OpenTelemetry Tracing](/docker-agent/community/opentelemetry/)

These docs track the `main` branch and may describe unreleased features.
The stable documentation lives at
[docs.docker.com](https://docs.docker.com/ai/docker-agent/).

# Docker Agent

**Docker Agent is to AI agents what `docker run` is to containers.**
Define an agent in a YAML file, run it with one command, share it through any OCI registry — the same workflow you already use for images.

[Quick Start →](getting-started/quickstart/)
[View on GitHub](https://github.com/docker/docker-agent)

[![
![Docker Agent TUI demo showing an interactive agent session](demo.gif)
](demo-poster.png)](demo.mp4)

What it is

A CLI that runs AI agents defined declaratively in YAML or HCL.

What it isn’t

Not a framework you write code in. Not a hosted SaaS. Not a new model.

Who it’s for

Developers who want agents in their workflow without glue code.

What you get

TUI · CLI · HTTP API · MCP server · A2A · OCI distribution.

## What Is Docker Agent?

Docker Agent is an open-source tool from **Docker** — makers of [Docker Engine](https://www.docker.com/products/container-runtime/), [Docker Desktop](https://www.docker.com/products/docker-desktop/), [Docker Hub](https://hub.docker.com), and [Docker Scout](https://www.docker.com/products/docker-scout/) — that lets you **build, run, and share AI agents using simple configuration files** instead of writing application code.

You describe what your agent does — its model, personality, tools, and teammates — in a YAML file. Docker Agent handles the LLM orchestration loop, tool execution, multi-agent delegation, and streaming output. You focus on *what* the agent should do, not *how* to wire it up.

```
# agent.yaml — this is all you need
agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: A coding assistant
    instruction: |
      You are an expert developer. Help users write clean,
      efficient code. Explain your reasoning step by step.
    toolsets:
      - type: filesystem
      - type: shell
      - type: think
```

```
$ docker agent run agent.yaml
```

That's it. Your agent can now read and write files, run shell commands, and reason through problems — all through an interactive terminal UI.

## Without vs. with Docker Agent

The same coding assistant, written two different ways:

Without Docker Agent

```
# ~30 lines of glue code, every project
import anthropic, json, subprocess
from pathlib import Path

client = anthropic.Anthropic()
MODEL = "claude-sonnet-4-5"
TOOLS = [
  {"name": "read_file", "input_schema": {...}},
  {"name": "write_file", "input_schema": {...}},
  {"name": "run_shell", "input_schema": {...}},
]

def dispatch(name, args):
  if name == "read_file":
      return Path(args["path"]).read_text()
  if name == "write_file":
      Path(args["path"]).write_text(args["content"])
      return "ok"
  if name == "run_shell":
      return subprocess.check_output(args["cmd"], shell=True).decode()

messages = [{"role": "user", "content": input("> ")}]
while True:
  resp = client.messages.create(
    model=MODEL, max_tokens=4096, tools=TOOLS,
    system="You are an expert developer…",
    messages=messages,
  )
  # …parse tool_use blocks, dispatch, append, loop…
  if resp.stop_reason == "end_turn": break
```

With Docker Agent

```
# agent.yaml — 8 lines, no glue code
agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: A coding assistant
    instruction: You are an expert developer.
    toolsets:
      - type: filesystem
      - type: shell
```

```
$ docker agent run agent.yaml
```

## Why Docker Agent?

Most AI agent frameworks ask you to write Python or TypeScript to glue together models, tools, and workflows. Docker Agent takes a different approach: **declare everything in config, run it with a single command.**

× “I rebuilt the same agent loop in three projects.”

✓ Reusable YAML — declare once, run everywhere.

× “Sharing my agent means a repo plus a setup README.”

✓ `docker agent run user/agent` — OCI distribution, like images.

× “I’m locked into one model SDK.”

✓ Swap the `model:` line — OpenAI, Anthropic, Gemini, Bedrock, local.

× “Tools are one-offs glued to one agent.”

✓ Built-in toolsets plus any MCP server from [Docker's MCP catalog](https://hub.docker.com/u/mcp) — reuse them across agents.

### Config, Not Code

Define agents in YAML or HCL. Swap models, add tools, or change behavior without touching application code.

### Built-in Tools + MCP

Comes with tools for filesystem, shell, memory, web fetch, and more. Extend with any of the hundreds of MCP servers in [Docker's MCP catalog](https://hub.docker.com/u/mcp).

### Multi-Agent Teams

Build teams of specialized agents that delegate work to each other. A coordinator routes tasks to the right specialist.

### Any Model

OpenAI, Anthropic, Google Gemini, AWS Bedrock, local models via Docker Model Runner or Ollama — bring your own provider.

### Package & Share Like Images

Push agents to any OCI registry. Pull and run them anywhere with one command — the same workflow you use for containers.

### Run Anywhere

Interactive TUI, headless CLI, HTTP API server, OpenAI-compatible chat endpoint, MCP server, or A2A protocol.

## Use Cases

What people build with Docker Agent today:

### Coding agents

Pair-programmer agents with file system, shell, and LSP tools. Read code, edit it, run tests, iterate.

[CLI reference →](features/cli/)

### Ops & SRE

Triage incidents, search logs, run kubectl, build Dockerfiles. Pipe alerts in via `--exec` for headless runs.

[CLI reference →](features/cli/)

### Data & research

Persistent memory, web fetch, RAG over local docs, structured output for downstream pipelines.

[RAG guide →](tools/rag/)

### Custom workflows

Multi-agent teams, hooks, model routing, A2A and MCP servers — wire agents into your existing stack.

[Multi-agent →](concepts/multi-agent/)

## How It Works

Docker Agent follows a simple loop:

![agent.yaml is run by 'docker agent run', which loops through Model, Tools and Sub-agents, then streams results to the TUI or API.](assets/how-it-works.svg)
![agent.yaml is run by 'docker agent run', which loops through Model, Tools and Sub-agents, then streams results to the TUI or API.](assets/how-it-works-dark.svg)

Your YAML config is the input; the runtime drives a Model ↔ Tools ↔ Sub-agents loop until the task is done; results stream back to the TUI or any API client.

1. **You define an agent** in YAML — its model, instructions, tools, and sub-agents
2. **You run it** with `docker agent run` via TUI, CLI, or API
3. **The agent processes your request** — calling tools, delegating to sub-agents, reasoning step by step
4. **Results stream back** in real time

## A few terms you'll see

Agent
:   An LLM with instructions, tools, and (optionally) sub-agents — the unit you define in YAML.

Tool
:   A function the agent can call, like `read_file` or `shell`. Tools come from built-in toolsets or external MCP servers.

MCP
:   *Model Context Protocol* — an open standard for tool servers. Docker Agent can use any MCP server as a toolset.

A2A
:   *Agent-to-Agent* — an HTTP protocol agents use to talk to each other across machines.

TUI
:   *Terminal User Interface* — the default interactive front end, launched by `docker agent run`.

OCI
:   The same registry format used for Docker images. Docker Agent reuses it to push and pull agents.

### Zero Config

The fastest way to try it — no config file needed:

```
# Run the project config or built-in default agent
$ docker agent run
```

### From the Registry

Run agents straight from any OCI-compatible registry — just like pulling a Docker image:

```
$ docker agent run myorg/agent:tag
```

### Multi-Agent Teams

Build a team where a coordinator delegates tasks to specialists:

```
agents:
  root:
    model: openai/gpt-5
    description: Team coordinator
    instruction: Route tasks to the best specialist.
    sub_agents: [coder, reviewer]

  coder:
    model: anthropic/claude-sonnet-4-5
    description: Writes and modifies code
    instruction: Write clean, tested code.
    toolsets:
      - type: filesystem
      - type: shell

  reviewer:
    model: anthropic/claude-sonnet-4-5
    description: Reviews code for quality
    instruction: Review code for bugs, style, and best practices.
    toolsets:
      - type: filesystem
```

### Non-Interactive Mode

Use `--exec` for scripting and automation:

```
# One-shot task
$ docker agent run --exec agent.yaml "Create a Dockerfile for a Node.js app"

# Pipe input
$ cat error.log | docker agent run --exec agent.yaml "What's wrong in this log?"

# Serve as an API
$ docker agent serve api agent.yaml --listen :8080
```

Prefer HCL?

You can also write agent configs in HCL using labeled blocks and heredocs. See [HCL Configuration](configuration/hcl/).

## Part of the Docker ecosystem

Docker Agent reuses the tooling and conventions you already know:

[**Docker Hub**
Push and pull agents like container images — same registry, same auth.](https://hub.docker.com)
[**Docker Desktop**
Run MCP toolsets in containers via `ref: docker:…` with one click.](https://www.docker.com/products/docker-desktop/)
[**Docker Model Runner**
Run local OSS models on your machine — just point your agent at `dmr/…`.](https://docs.docker.com/desktop/features/model-runner/)
[**Docker Scout**
Same supply-chain visibility you have for images extends to agent images.](https://www.docker.com/products/docker-scout/)

## Explore the Docs

[### Introduction

The full story: what Docker Agent is, why it exists, and how it works.](getting-started/introduction/)
[### Quick Start

Get your first agent running in under 5 minutes.](getting-started/quickstart/)
[### Core Concepts

Agents, models, tools, and multi-agent orchestration explained.](concepts/agents/)
[### Configuration

Full reference for every YAML and HCL option.](configuration/overview/)
[### Model Providers

OpenAI, Anthropic, Gemini, Bedrock, Docker Model Runner, and more.](providers/overview/)
[### Features

TUI, CLI, API server, MCP mode, A2A, RAG, Skills, and distribution.](features/tui/)

![](/docker-agent/assets/docker-mark.svg)

Docker Agent

Run AI agents like containers.

## Product

* [Docker Desktop](https://www.docker.com/products/docker-desktop/)
* [Docker Hub](https://hub.docker.com)
* [Docker Scout](https://www.docker.com/products/docker-scout/)
* [Build Cloud](https://www.docker.com/products/build-cloud/)

## Resources

* [Docker Docs](https://docs.docker.com)
* [GitHub](https://github.com/docker/docker-agent)
* [Blog](https://www.docker.com/blog/)
* [llms.txt](/docker-agent/llms.txt)

## Company

* [About](https://www.docker.com/company/)
* [Status](https://status.docker.com)
* [Terms](https://www.docker.com/legal/docker-terms-service/)
* [Privacy](https://www.docker.com/legal/docker-privacy-policy/)

© 2026 Docker Inc. All rights reserved.
Docker Agent is open source under the [Apache 2.0 license](https://github.com/docker/docker-agent/blob/main/LICENSE).