Is Docker Agent free to use?

Docker Agent is an open-source tool from Docker, so the CLI itself carries no per-agent fee. Costs come from the model you point it at; a local model through Docker Model Runner avoids API charges entirely.

Do I need to write Python to use Docker Agent?

No. The agent loop, model calls, and tool execution are handled by the tool. You write YAML with a model line, instructions, and tool permissions.

Can Docker Agent run models locally?

Yes. The model line accepts a local model through Docker Model Runner, alongside cloud providers such as OpenAI, Anthropic, Gemini, and Open Router.

Is Docker Agent a replacement for agent frameworks?

It replaces the framework code for common cases: the loop, tool wiring, and serving. For highly custom orchestration logic, a code-based framework may still fit better, and Docker's docs present the tradeoff as configuration versus code.

Docker Agent Explained in 5 Simple Steps

Docker Agent is Docker's open-source command-line tool for building and running AI agents from YAML files instead of framework code. You describe the model, instructions, and tools in a config file, run it with a single command, and the tool handles the agent loop. This guide walks through how it works, how to connect two agents over the A2A protocol, and what a real setup looks like.

What Is Docker Agent?

Docker Agent is an open-source command-line tool from Docker for building and running AI agents, and Docker positions it as being to AI agents what docker run is to containers. You describe an agent in a YAML file with its model, instructions, and allowed tools, then launch it with one command instead of writing framework code.

The tool handles the agent loop for you: it calls the model, runs the tools, feeds results back into the context, and repeats until the job is finished. Docker's own docs include a side-by-side comparison showing the Python code you would normally write for a model-calling-tools loop next to the equivalent Docker Agent configuration, and the YAML version is substantially shorter.

This article is based on Docker's documentation and a hands-on walkthrough published by Better Stack in October 2026. The walkthrough was recorded by Andreas from Better Stack, and all demos described here come from that video.

The three advantages Docker highlights

Docker frames the tool around three advantages, and each one changes how teams work with agents:

Agents become configuration. You can version them, review them in pull requests, and swap the model by changing one line.
Distribution works like containers. Push an agent to a registry and anyone can run it the same way they run an image.
Agents run as services. One command turns an agent into an HTTP API, an MCP server, or an A2A server that other agents can call.

How a Docker Agent Definition Works

A Docker Agent definition is a YAML file with three core parts: the model, a description, and an instruction. The model line can point at OpenAI, Anthropic, Gemini, Open Router, or a local model served through Docker Model Runner, which means the same agent file works against cloud and local inference.

Tools come from two places. Built-in tool sets cover file access and shell commands, and you can attach any MCP server, the Model Context Protocol standard for exposing tools to models. An agent can also declare sub-agents, so one coordinator hands work off to specialists. Because everything is configuration, agents can be versioned, reviewed in pull requests, and swapped to a different model by changing one line.

Permissions are scoped per agent, and that is what makes delegation safe. In Better Stack's debugging demo, the log analyst agent had a read-only file tool locked to a logs folder, while the on-call assistant had no file access at all and only knew the analyst's URL.

Launching Your First Agent From Scratch

Getting a first agent running takes minutes if Docker Desktop is already installed. On Docker Desktop 4.63 or newer, Docker Agent is installed by default according to the 2026 video walkthrough. Otherwise you can install it with Homebrew and symlink it into the Docker CLI plugins folder, after which it runs as docker agent.

The steps from the Better Stack demo are:

Create a YAML file with a model line, a description, and an instruction.
Run docker agent run agent.yaml.
Talk to the agent in the terminal UI it opens.

That is the entire smallest example. The terminal UI lets you converse with the agent directly, and the tool loop behind it is identical to what a served agent uses, so the same file can later run as an API.

Connecting Two Agents Over A2A

The A2A protocol, the Agent2Agent open protocol for agent-to-agent communication, lets independently owned agents talk to each other. Any agent can be served as an HTTP API, an MCP server, or an A2A server with one command, which makes cross-team delegation practical without sharing credentials or file access.

In Better Stack's checkout-outage demo, a log analyst agent was served with docker agent serve a2a, selected with the agent flag, and bound to port 8080. The on-call assistant, running in a second terminal, knew only the analyst's URL. When asked why checkout had been returning 500 errors since around 2 p.m., the question reached the analyst, which read the application logs and deploy history and sent back findings, and the on-call agent turned them into an incident summary.

The pattern maps cleanly onto real organizations. A platform team owns the log analyst and runs it next to the logs. Other teams' agents query it without ever getting access to the logs themselves. The A2A project lives at a2aproject/A2A on GitHub.

Agents distribute like containers because they are configuration. You can push an agent to Docker Hub or any other OCI registry, and anyone can run it with docker agent run plus the image name.

This gives agents the same versioning, review, and distribution workflow that container images already have, and it is one of the three advantages Docker highlights for the tool alongside configuration-as-code and service mode. For teams already running an internal registry, agent sharing needs no new infrastructure; the same pull-through cache and access controls that govern images govern agents too.

What the Battleship Demo Actually Shows

The Battleship demo stress-tests the same pattern: two AI agents playing a full match over A2A, each in its own process, with a third agent as referee. In the game, Claude Haiku 5.5 beat GPT-6 Luna by sinking the last submarine in row H, winning in 34 shots at 50% accuracy. Kimi K3 refereed so that neither player's model judged its own game.

The setup details show how little code the pattern needs. The players listened on ports 8080 and 8081, the board ran on a local server, and every turn a player received its view of the enemy waters, picked a square, and added a line of trash talk. Haiku found the carrier early and worked down the line to sink it; Luna came back hard and by the end both players were down to their last ship. Luna had sunk all but one of Haiku's ships when Haiku closed out the match. Three agents, three processes, three ports, zero framework code: the players and referee were just YAML files connected over A2A.

Better Stack itself notes this was a simple game rather than a benchmark, though both models clearly played better than random. Comparing models this way measures a single game configuration, not general model quality.

Frequently Asked Questions

Is Docker Agent free to use? Docker Agent is an open-source tool from Docker, so the CLI itself carries no per-agent fee. Costs come from the model you point it at; a local model through Docker Model Runner avoids API charges entirely.

Do I need to write Python to use Docker Agent? No. The agent loop, model calls, and tool execution are handled by the tool. You write YAML with a model line, instructions, and tool permissions.

Can Docker Agent run models locally? Yes. The model line accepts a local model through Docker Model Runner, alongside cloud providers such as OpenAI, Anthropic, Gemini, and Open Router.

Is Docker Agent a replacement for agent frameworks? It replaces the framework code for common cases: the loop, tool wiring, and serving. For highly custom orchestration logic, a code-based framework may still fit better, and Docker's docs present the tradeoff as configuration versus code.

Turn Your Own Agent Walkthroughs Into Articles

A working demo and a published explanation are closer together than they look: a YAML file, a terminal, and a clear narration were all Better Stack needed. If you record that kind of content on YouTube, whether it is agent tooling, infrastructure, or a debugging session of your own, Skala Blog turns the video into a written article: paste the YouTube URL, transcribe it, and generate a structured post from what you already said. Anyone publishing this kind of walkthrough, from a solo creator like Gustavo dev doido to a developer-relations team, ends up with the same written artifact from footage that already exists.

Source video