Docker Agent

docker-agent · docker/docker-agent · ★ 3.0k · last commit 2026-05-26

Primitive shape 6 total

Commands 6

Summary

Docker Agent — Summary

Docker Agent (docker/docker-agent, 3k stars, Apache-2.0) is a Go-based CLI tool and Docker plugin (docker agent) for creating and running AI agents declaratively via YAML configuration files — no code required. Each YAML defines agents with model, instruction, toolsets (MCP servers, filesystem, shell, todo, fetch, RAG, code sandbox), sub-agents, and permissions; multiple agents form a named team with delegation and parallel execution. The binary ships as a Docker Desktop plugin (pre-installed in Docker Desktop 4.63+) and via Homebrew, making it unique as the only framework in this batch distributed through a mainstream desktop application. The TUI (Bubble Tea / charm.land) provides a rich interactive terminal experience. Docker Agent is model-agnostic (OpenAI, Anthropic, Gemini, AWS Bedrock, Mistral, xAI, Docker Model Runner for local models), supports OCI-based packaging and sharing of agent definitions (docker agent push/pull), and includes a docker agent new interactive generator. The golang_developer.yaml example ships in the repo root and is used to develop the tool itself — extreme dogfooding. Compared to seeds, Docker Agent is most similar to taskmaster-ai (both are CLI tools with YAML-based agent definitions and multi-agent support), but Docker Agent's OCI packaging, Docker-native distribution, and TUI are unique.

Overview

Docker Agent — Overview

Origin

Docker Inc., released 2025. The binary is a docker CLI plugin (docker agent), pre-installed in Docker Desktop 4.63+. The team uses the tool to build the tool: docker agent run ./golang_developer.yaml.

Philosophy

From the README:

"docker-agent lets you create and run intelligent AI agents that collaborate to solve complex problems — no code required."

"Define agents in YAML, give them tools, and let them work."

The YAML-first philosophy aligns with Docker's DNA — just as docker-compose.yaml defines services, agent.yaml defines agents. The tool values declarative configuration, version control, and sharing via registries.

Design pillars

YAML-first: agents are pure data, not code — sharable, diff-able, version-controllable
Docker-native distribution: docker agent push/pull via OCI registries — same workflow as container images
Multi-agent teams: YAML defines named agents with sub-agent relationships
Model-agnostic: any provider via the models: block; mix providers in one YAML
Toolset abstraction: MCP servers, built-in tools (filesystem, shell, todo, fetch), RAG, sandboxes
TUI: Bubble Tea terminal UI for interactive sessions
No-code: the README explicitly says "no code required" — YAML is sufficient

Key quote (from `golang_developer.yaml` instruction)

"The agent avoids asking for clarification unless truly necessary, instead using all available tools to gather needed information. It does not display the code it generates in responses and never writes summary documents, focusing exclusively on code changes."

This is a production-quality agent instruction embedded in a YAML file that ships in the repo — a living example of the framework's intended use.

Dogfooding

The tool is developed using itself:

docker agent run ./golang_developer.yaml

The golang_developer.yaml in the repo root defines a three-agent team (root developer, planner, librarian) used to build docker-agent.

Architecture

Docker Agent — Architecture

Distribution

Type: standalone-repo (Go binary / Docker CLI plugin)
Install methods:
- Docker Desktop 4.63+ (pre-installed)
- brew install docker-agent
- Binary download from GitHub Releases
Required runtime: Go 1.26.3 (to build); any OS to run the pre-built binary
License: Apache-2.0

Binary names

docker agent (as Docker CLI plugin, symlinked to ~/.docker/cli-plugins/docker-agent)
docker-agent (standalone binary)

Go module dependencies (selected from `go.mod`)

Package	Purpose
`charm.land/bubbletea/v2`	TUI framework
`charm.land/lipgloss/v2`	TUI styling
`charm.land/glamour/v2`	Markdown rendering in TUI
`anthropics/anthropic-sdk-go`	Anthropic provider
`aws/aws-sdk-go-v2`	AWS Bedrock
`google/generative-ai-go`	Google Gemini
`openai`	OpenAI
`a2aproject/a2a-go`	A2A protocol
`blevesearch/bleve/v2`	BM25 search (RAG)
`modelcontextprotocol/sdk`	MCP client

Source layout (`pkg/`)

pkg/
  agent/        # Core agent execution loop
  team/         # Multi-agent team management
  team_loader/  # YAML team definition loading
  mcp/          # MCP client integration
  tui/          # Bubble Tea terminal UI
  rag/          # RAG (BM25 + embeddings + hybrid)
  sandbox/      # Code execution sandbox
  tools/        # Built-in tool implementations
  memory/       # Memory management
  skills/       # Skills integration
  session/      # Session management
  history/      # Conversation history
  config/       # User config
  llm/          # LLM provider abstraction
  runtime/      # Execution runtime
  server/       # Agent server

YAML schema (from `agent-schema.json`)

Schema version: 0–9 (currently v9). Defines: agents, models, mcps, rag, metadata, permissions, runtime, providers.

Components

Docker Agent — Components

CLI subcommands

Subcommand	Purpose
`docker agent run [file.yaml]`	Run an agent from YAML config
`docker agent run --agent <name>`	Run a specific agent from a team YAML
`docker agent run agentcatalog/pirate`	Run from agent catalog (OCI registry)
`docker agent new`	Interactive agent generator
`docker agent push`	Push agent YAML to OCI registry
`docker agent pull`	Pull agent from OCI registry

YAML configuration primitives

YAML key	Purpose
`agents.*`	Agent definitions (model, instruction, toolsets, sub_agents)
`models.*`	Named model configurations (provider + model ID)
`mcps.*`	Reusable MCP server definitions
`rag.*`	Reusable RAG source definitions
`metadata`	Author, readme, version
`permissions`	Tool approval configuration
`runtime`	Execution defaults (timeout, max_steps)

Toolset types

Type	Description
`type: mcp`	Any MCP server (local, remote, Docker-based via `ref: docker:<name>`)
`type: filesystem`	File read/write/create/delete
`type: shell`	Run shell commands
`type: todo`	Task list management
`type: fetch`	HTTP fetch
`type: rag`	Retrieval-augmented generation
`type: sandbox`	Code execution sandbox

Built-in thinking/memory tools

From README: "built-in think, todo, and memory tools" — cognitive scaffolding tools available to all agents.

Docker MCP catalog

ref: docker:duckduckgo, ref: docker:context7 — Docker-managed MCP server registry accessible without separate installation.

Lifecycle profiles (from `agent-schema.json`)

Profile	Behavior
`resilient` (default)	Auto-restart on failure with exponential backoff
`strict`	Fail fast if toolset unavailable
`best-effort`	Single attempt, no auto-restart

Prompts

Docker Agent — Prompts

Verbatim: golang_developer.yaml agent instruction (excerpt)

agents:
  root:
    instruction: |
      <golang_developer>
      <core_purpose>
      The agent is an expert Golang developer specializing in the docker agent 
      multi-agent AI system architecture. Its primary role is to help users with 
      code-related tasks by examining, modifying, and validating code changes.

      The agent always uses conversation context and tools to gather information, 
      preferring tools over its own internal knowledge.
      </core_purpose>

      <workflow>
      The agent follows a deliberate approach to code changes. It begins by 
      understanding what the user needs and searching for relevant code files 
      and functions. Once it has a clear picture of the codebase structure, 
      it makes necessary modifications while ensuring changes follow best practices.

      After making changes, the agent validates its work by running linters and tests.
      If issues arise, it returns to modification and continues this loop until all 
      requirements are met.
      </workflow>

      <working_style>
      The agent is thorough in code examination before making changes and always 
      validates changes before considering a task complete.

      The agent avoids asking for clarification unless truly necessary, instead 
      using all available tools to gather needed information. It does not display 
      the code it generates in responses and never writes summary documents.
      </working_style>

      <communication_style>
      The agent avoids filler phrases and excessive affirmations. It never uses 
      phrases like "you are absolutely right" or "that's a great question" and 
      avoids overused words like "comprehensive" or "robust."
      </communication_style>
      </golang_developer>

Technique: XML-tagged structured instruction with <core_purpose>, <workflow>, <working_style>, <communication_style> sections. Explicit anti-sycophancy instruction ("never uses phrases like 'you are absolutely right'"). Tool-preference instruction ("preferring tools over its own internal knowledge"). This is production-grade prompt engineering in a declarative YAML format.

Verbatim: planner agent instruction

  planner:
    instruction: |
      You are a planning agent responsible for gathering user requirements 
      and creating a development plan.
      Always ask clarifying questions to ensure you fully understand the 
      user's needs before creating the plan.
      Once you have a clear understanding, analyze the existing code and 
      create a detailed development plan in a markdown file. Do not write 
      any code yourself.
      Once the plan is created, you will delegate tasks to the root agent. 
      Make sure to provide the file name of the plan when delegating.

Technique: Role-constrained instruction with an explicit prohibition ("Do not write any code yourself"). The plan-then-delegate pattern is enforced through natural language instruction rather than code.

Uniqueness

Docker Agent — Uniqueness

Differs from seeds

Most similar to taskmaster-ai (both CLI-first multi-agent tools with YAML/JSON configuration), but Docker Agent has three decisive differences: (1) YAML-first with no code required — taskmaster-ai requires MCP setup and a config JSON but ultimately needs code for custom behavior; (2) OCI-based distribution (docker agent push/pull) enables sharing agent definitions the same way Docker images are shared — no other framework in the catalog has this; (3) pre-installed in Docker Desktop 4.63+ means millions of Docker users have it available with zero additional installation. The golang_developer.yaml dogfooding example — where the tool builds itself — is the most complete production agent YAML in the catalog.

Positioning

Docker Agent targets developers who already use Docker and want to add AI agent capabilities to their workflow without learning a new runtime or language. The YAML schema mirrors docker-compose.yaml familiarity. The OCI packaging mirrors container image sharing.

Distinctive features

Docker Desktop integration: pre-installed — zero-friction adoption for Docker Desktop users
OCI packaging: docker agent push/pull — agent definitions as OCI artifacts
Combined model aliases: extramax: { model: sonnet,gpt } enables multi-provider routing in YAML
Self-dogfooding: ./golang_developer.yaml builds docker-agent using docker-agent — production-quality example
Lifecycle profiles (resilient/strict/best-effort): per-toolset fault tolerance configuration
Charm TUI: richest terminal UI in this batch (animated, markdown-rendered, streaming)

Observable failure modes

YAML complexity: the schema has 9 versions with many optional fields — large mental model for simple use cases
No persistence by default: sessions are ephemeral; no built-in cross-run state
Model Runner dependency for local: local model support requires Docker Model Runner (separate service)
OCI overhead: sharing agents via OCI registries requires Docker Hub account or self-hosted registry
No Python SDK: Go binary only; embedding in Python/Node applications requires subprocess invocation

Workflow

Docker Agent — Workflow

Single agent

agents:
  root:
    model: openai/gpt-5-mini
    instruction: "You are a helpful assistant."
    toolsets:
      - type: mcp
        ref: docker:duckduckgo

docker agent run agent.yaml

Phase	Artifact
1. Write agent.yaml	YAML file
2. `docker agent run agent.yaml`	TUI interactive session
3. User sends message	Chat turn
4. Agent uses tools	Tool call results
5. Response in TUI	Chat response

Multi-agent team (from `golang_developer.yaml`)

models:
  sonnet: { provider: anthropic, model: claude-sonnet-4-6 }
  haiku:  { provider: anthropic, model: claude-haiku-4-5 }

agents:
  root:
    model: gpt
    sub_agents: [librarian]
    # ... developer instruction

  planner:
    model: sonnet
    sub_agents: [root]
    # ... planner instruction

  librarian:
    model: haiku
    # ... search instruction

Phase	Artifact
1. Define team YAML with named agents	YAML team definition
2. Run with `--agent planner`	Planner agent takes control
3. Planner gathers requirements	Development plan (markdown file)
4. Planner delegates to root	Coding tasks
5. Root delegates to librarian for docs	Documentation context
6. Root implements + validates	Code changes

Approval gates

permissions block in YAML: tools can be set to auto (no approval), prompt (ask user), or deny.

Non-interactive mode

docker agent run --agent root golang_developer.yaml 'Fix the bug in pkg/fsx/vcs.go'

Pass the task as a positional argument for headless/CI use.

Memory Context

Docker Agent — Memory & Context

Memory architecture

Built-in memory tool (mentioned in README: "built-in think, todo, and memory tools"). The memory/ package in pkg/ handles memory management. Details not in public README.

Conversation history

pkg/history/ stores conversation history per session. pkg/session/ manages session lifecycle.

Context injection

The agent YAML instruction field is the system prompt, injected at session start. The add_date: true and add_environment_info: true fields on agents (visible in golang_developer.yaml) inject the current date and system environment info.

RAG (retrieval-augmented context)

type: rag toolset in agent YAML:

BM25 full-text search (Bleve)
Embedding-based vector search
Hybrid search (BM25 + vector)
Reranking

RAG sources defined in the rag: block of the YAML; reusable across agents.

Cross-session handoff

Unknown. The session model suggests per-run context; no explicit persistent cross-session memory documented.

State files

The pkg/session/ and pkg/history/ modules write session state, but exact file paths are not documented in the README.

Config persistence

pkg/config/ handles user configuration (API keys, preferences) stored in platform-standard config directories.

Orchestration

Docker Agent — Orchestration

Multi-agent

Yes. sub_agents: [list] in agent YAML defines delegation hierarchy.

Orchestration pattern

hierarchical — planner → root → librarian (tree of delegation). Parallel execution available: agents can call multiple sub-agents simultaneously.

Max concurrent agents

Unknown; Go goroutines handle concurrency. No hard cap in YAML schema.

Isolation mechanism

None for agent cognition. MCP servers follow the lifecycle.profile in YAML (resilient / strict / best-effort) for process management.

Code sandbox (type: sandbox) provides isolation for code execution.

Multi-model

Yes. Named model aliases in models: block, referenced by agents:

models:
  sonnet: { provider: anthropic, model: claude-sonnet-4-6 }
  haiku:  { provider: anthropic, model: claude-haiku-4-5 }
  gpt:    { provider: openai, model: gpt-5.5 }
  extramax: { model: sonnet,gpt }  # combined model alias

The extramax: { model: sonnet,gpt } is interesting — a combined model alias that can route between multiple providers.

Execution mode

interactive-loop (TUI interactive) or one-shot (non-interactive with task as argument).

Crash recovery

lifecycle.profile: resilient provides automatic MCP server restart with exponential backoff. No agent-level crash recovery.

Context compaction

Unknown. pkg/history/ may implement compaction; not documented.

Consensus

None.

Prompt chaining

Yes — planner creates a plan file → passes filename to root agent → root executes. Explicit file-mediated handoff.

Streaming

Yes — TUI displays streaming responses as they arrive (Bubble Tea progressive rendering).

Ui Cli Surface

Docker Agent — UI & CLI Surface

CLI binary

docker agent — Docker CLI plugin. docker-agent — standalone binary.

Installation paths:

Docker Desktop 4.63+ (pre-installed, zero setup)
brew install docker-agent
Download from GitHub Releases → symlink to ~/.docker/cli-plugins/docker-agent

Key subcommands:

docker agent run [file.yaml] — run agent
docker agent run --agent <name> file.yaml — run specific agent
docker agent run agentcatalog/<name> — run from catalog
docker agent run --model opus file.yaml — override model
docker agent new — interactive agent generator
docker agent push — push to OCI registry
docker agent pull — pull from OCI registry

TUI (Terminal UI)

Built with charm.land/bubbletea/v2 + charm.land/lipgloss/v2 + charm.land/glamour/v2.

Features:

Animated progress (from README: demo.gif)
Markdown rendering in terminal
Streaming response display
Tool call visualization
Multi-agent conversation display

No local web UI

Docker Agent is TUI-only. No web dashboard.

IDE integration

AGENTS.md at repo root (coding agent instructions)
.devcontainer/ (VS Code Dev Container setup)
.vscode/ settings

MCP mode

Docker Agent can itself serve as an MCP server, exposing its agent capabilities to other MCP clients.

OCI registry integration

Agents can be packaged and shared via any OCI registry (Docker Hub, GitHub Container Registry, etc.) using docker agent push/pull. The agentcatalog/ namespace is a curated registry.

Observability

pkg/telemetry/ module. Docker Desktop provides container-level telemetry.

Related frameworks

same archetype · same primary tool · same memory type

Claude-Flow / Ruflo ★ 55k

A6 Multi-agent orchestrator

Eliminates single-agent context limits and sequential bottlenecks by orchestrating fault-tolerant swarms of specialized AI agents…

Hermes Agent (NousResearch) ★ 168k

A6 Multi-agent orchestrator

Self-improving personal AI agent with closed learning loop, 7 terminal backends, and messaging gateway — not tied to any AI…

OpenCode ★ 165k

A6 Multi-agent orchestrator

Terminal-first AI coding agent with multi-model routing, native desktop app, and a typed .opencode/ configuration system for…

OpenHands ★ 75k

A6 Multi-agent orchestrator

Open-source AI software development platform (open-source Devin alternative) with Docker sandbox isolation, 77.6% SWE-bench…

DeerFlow ★ 70k

A6 Multi-agent orchestrator

Long-horizon superagent that researches, codes, and creates by orchestrating parallel sub-agents with isolated contexts in Docker…

oh-my-openagent (omo) ★ 60k

A6 Multi-agent orchestrator

Multi-provider AI agent orchestration for OpenCode: escape vendor lock-in by routing Sisyphus (Claude/Kimi/GLM) and Hephaestus…

Distribution

Type: standalone-repo
License: Apache-2.0
Install: one-liner

Surfaces

CLI binary: docker-agent
CLI subcmds: 6
Local UI: terminal-tui
Tech stack: charm.land/bubbletea/v2 + lipgloss + glamour

Components

Commands: 6
Skills: 0
Subagents: 0
Hooks: 0
MCP servers: 0
MCP tools: 0
Scripts: 2
Templates: 10

Workflow

Phases: 5
Approval gates: 1
Spec format: yaml
Spec storage: flat-files
Delta or full: whole-file

Orchestration

Multi-agent: Yes
Pattern: hierarchical
Isolation: process
Consensus: none
Prompt chaining: Yes

Multi-model

Multi-model: Yes
BYOK: Yes
Modal: text+vision

Execution

Mode: interactive-loop
Crash recovery: No
Session handoff: No
Streaming: Yes

Memory

Type: file-based
Persistence: session
Search: hybrid

Quality

TDD: No
TDD mechanism: none
Self-review: none

Git / Observability

Auto commit: No
Auto PR: No
Auto merge: No
Worktree/feat: No
Replay: No

Tools

Primary: any
Targets: 7
Portability: high

Signals

Stars: 3.0k
Last commit: 2026-05-26
Maintainer: active
Quality score: 2.5/10

Summary

Docker Agent — Summary

Overview

Docker Agent — Overview

Origin

Philosophy

Design pillars

Key quote (from golang_developer.yaml instruction)

Dogfooding

Architecture

Docker Agent — Architecture

Distribution

Binary names

Go module dependencies (selected from go.mod)

Source layout (pkg/)

YAML schema (from agent-schema.json)

Components

Docker Agent — Components

CLI subcommands

YAML configuration primitives

Toolset types

Built-in thinking/memory tools

Docker MCP catalog

Lifecycle profiles (from agent-schema.json)

Prompts

Docker Agent — Prompts

Verbatim: golang_developer.yaml agent instruction (excerpt)

Verbatim: planner agent instruction

Uniqueness

Docker Agent — Uniqueness

Differs from seeds

Positioning

Distinctive features

Observable failure modes

Workflow

Docker Agent — Workflow

Single agent

Multi-agent team (from golang_developer.yaml)

Approval gates

Non-interactive mode

Memory Context

Docker Agent — Memory & Context

Memory architecture

Conversation history

Context injection

RAG (retrieval-augmented context)

Cross-session handoff

State files

Config persistence

Orchestration

Docker Agent — Orchestration

Multi-agent

Orchestration pattern

Max concurrent agents

Isolation mechanism

Multi-model

Execution mode

Crash recovery

Context compaction

Consensus

Prompt chaining

Streaming

Ui Cli Surface

Docker Agent — UI & CLI Surface

CLI binary

TUI (Terminal UI)

No local web UI

IDE integration

MCP mode

OCI registry integration

Observability

Related frameworks

Key quote (from `golang_developer.yaml` instruction)

Go module dependencies (selected from `go.mod`)

Source layout (`pkg/`)

YAML schema (from `agent-schema.json`)

Lifecycle profiles (from `agent-schema.json`)

Multi-agent team (from `golang_developer.yaml`)