# Docker Agent, software that turns YAML into AI agents

> Docker Agent is an open source Docker software that packages AI agents in YAML and distributes them as OCI containers with MCP and sandbox
> By José Maldonado · Artificial Intelligence · 2026-10-09

Write a configuration file, launch it with a command and watch the machine obey: Docker turned that gesture into the standard way of moving software around the world with its containers. Now it wants to repeat the trick with artificial intelligence agents, and its bet is called Docker Agent, an open source project with more than 3,300 stars on GitHub that defines agents in YAML and treats them as if they were images, according to the [official docker-agent repository](https://github.com/docker/docker-agent).

The proposition is easy to sum up. You describe what your agent should do, which model it works with and which tools it uses. Docker Agent handles the orchestration loop, tool execution, delegation between agents and streaming output. You decide what the agent should do and the runtime works out how to wire it all together underneath.

The timing is right. Agents began the year answering questions and are ending it opening pull requests, running tests and touching real infrastructure. That leap demands serious isolation, because an agent with access to your terminal needs the same limits as a properly configured container. Docker, which has spent a decade packaging processes, arrives at this party with its suit already pressed.

## What is Docker Agent and what does it taste like?

The official presentation sums it up with a neat analogy. Docker Agent aims to be to agents what docker run was to containers, according to its [documentation](https://docker.github.io/docker-agent/). It is not a framework where you write code, nor a hosted service, nor a new model. It is a command-line interface that runs agents declared in YAML or HCL, with an interactive TUI, a headless mode for CI and HTTP servers, OpenAI compatible, MCP and A2A.

The contrast with the competition helps place it. Most frameworks ask you to glue models, tools and flows together with Python or TypeScript. Here everything is declared in configuration and run with a single command. You change models with one line, add tools without touching code and version behavior the way you version your Dockerfiles.

![An example of how Docker Agents work](https://content.observatorioblockchain.com/wp-content/uploads/2026/10/docker-agent.webp)
*An example of how Docker Agents work*

The multi-agent team architecture is its second hallmark. Instead of a generalist that tries everything, you define specialists with specific roles and a coordinator hands out tasks to the most suitable one. Each agent brings its own tools, and hook-based routing decides who responds to each request according to the rules you wrote.

The tool ecosystem draws from two sources. On one hand, it ships built-in utilities for the file system and the shell, with its own memory to recall context. On the other it connects to any MCP server, local, remote or packaged as a Docker container, and adds retrieval with hybrid search and reranking for context.

## Defining your agent with a YAML file

The configuration file is the heart of the invention. In it you declare the model with its instructions in natural language, and which tools and subagents accompany it. The syntax is designed so a developer can read it at a glance, with no surprises or hidden magic between the lines.

Getting started is just as direct. The run command launches the default agent with its TUI, and variants of the same command pull an agent from the registry, generate a new one interactively or run your local file. Those who prefer to automate use exec mode for non-interactive turns, with a flag to print only the final response.

Models are interchangeable at will. Several providers coexist in the same configuration, from the big labs to Docker's local Model Runner. That agnosticism protects your work, because if tomorrow a provider raises prices or lowers quality, you change one line and get on with your day.

Packaging copies the image recipe. You share an agent with push and pull against any OCI registry, with the same authentication you already use for containers. Pushing creates the repository if it does not exist, and pulling leaves it running on any machine with one command. No more repositories plus an installation README.

**[Microsoft finally has native Linux containers on Windows](https://observatorioblockchain.com/en/technology/microsoft-contenedores-linux-nativos-windows/)**

## Bars for the AI parrot

An agent that only talks is a parrot with a silver tongue. An agent that executes commands needs a cage with real bars, and there the containers take center stage again. Docker Agent relies on three layers of isolation depending on the scenario: the local sandbox, the Model Runner and remote CI sandboxes.

On your machine, the natural flow combines WSL2 as the Docker Desktop backend with containers for MCP toolsets. That piece deserves context, because running Linux inside Windows stopped being an experiment years ago. As we explained in our guide on [whether Windows is still a good environment for programming in 2026](https://observatorioblockchain.com/en/technology/sigue-siendo-windows-un-buen-entorno-para-programar-en-2026/), WSL2 brought a real ultralight kernel that today underpins container development on Windows without friction.

The GitHub integration took the leap in the summer of 2026. GitHub's [**Agentic Workflows**](https://github.github.com/gh-aw/) added Docker Sandboxes as a supported runtime, so a coding agent has broad control of its environment, including launching containers, while the environment itself lives isolated in a microVM with network policy and secret injection, as recounted in the [Docker blog on agents in GitHub Actions](https://www.docker.com/blog/running-ai-agents-in-github-actions-with-docker-sandboxes/).

The public demo makes it crystal clear. The agent runs on a GitHub-hosted Ubuntu runner, enters the sandbox, spins up a Java integration suite with PostgreSQL via Testcontainers, finds a deliberately planted bug, fixes it and opens a draft pull request. The full run took 11 minutes and 16 seconds, and the final patch only touched code under the permitted directory.

The architectural trick lies in nested daemons. Each sandbox is a dedicated environment with its own kernel, file system and network, and runs its own private Docker daemon. The agent has root inside the virtual machine without ever touching the host daemon. The only bridge between the two worlds is the shared repository directory.

## What do you gain from all this?

Anyone who has built an agent by hand knows the pain, and no, it is not a joke. The same loop of model, tools and subagents gets rewritten in every project, sharing it requires a repository plus a README, and changing provider means tweaking the SDK. Docker Agent attacks those three fronts with reusable YAML, OCI distribution and interchangeable models.

Governance is the argument that weighs most in enterprises. Docker AI Governance applies organization and team policies over sandbox network, file system and MCP access, and records decisions in audit logs. Those logs identify the source client and the machine, so the same model covers laptops and CI runners without inventing anything new.

Security also improves by default. MCP toolsets run in containers with one click, debug mode allows invoking tools outside the model loop to inspect them, and evaluation with dedicated judges measures stability by repeating runs. None of this eliminates the risk of an autonomous agent, but it keeps it confined and observable.

For teams already living in containers, the learning curve is almost flat. The same registries, the same authentication and the same supply chain visibility that Scout gives images extend to agents. After all, if your organization already trusts OCI to move software, moving agents along the same track reduces the surface of novelty.

Capability

Docker Agent

Classic code framework

Definition

Declarative YAML

Python or TypeScript glued together

Distribution

OCI registry with push and pull

Repo plus installation README

Models

Multi-provider plus Model Runner

Tied to one provider's SDK

Tools

Built-in plus any MCP

Custom connectors per agent

Teams

Multi-agent with delegation

One generalist by default

Execution

TUI, CLI, API, MCP and A2A

Whatever you implement

## How to try it without breaking anything serious?

Installation covers the usual paths. Docker Desktop from version 4.63 ships it preinstalled as a plugin, and there are also standalone binaries, a Homebrew formula and a Winget package. The binary links as a CLI plugin or is used on its own, as the user prefers.

The sensible first step is to pin down the model. You configure at least one provider key or point to the local Model Runner to run open models on your machine. The repository's examples catalog offers ready-made configurations for inspiration, from a toy pirate to serious debuggers.

Start with read-only tasks. Ask the agent to explain a module, draw the dependency map or propose tests without running them. When you trust it, open the door to writing with clear limits, a permitted directory and human review of every change before merging it.

If the experiment grows, take it to CI with sandboxes. Describe the agentic workflow in Markdown with its frontmatter, compile it to Actions and let the agent work confined with minimal permitted network. The pull request is created in a separate safe-output job whose patch only accepts files under the code directory.

**[Is Windows still a good environment for programming in 2026?](https://observatorioblockchain.com/en/technology/sigue-siendo-windows-un-buen-entorno-para-programar-en-2026/)**

## What Docker Agent says about the future of the craft

Docker's move smacks of history repeating itself. First containers turned deployment into a boring, reliable gesture, and a decade later agents are looking for their own boring gesture. Defining in YAML, sharing via registry and running isolated is a solid candidate to become that standard.

It remains to be seen whether the community adopts the format or whether each lab imposes its own. The start is promising, with thousands of stars and a real GitHub integration that already runs confined agents in CI. If the format catches on, asking an agent for something will be as normal as pulling an image.
