Docker Agent

docker ai/agents agents/casestudies casestudies

1. What Docker Agent does

Docker Agent is an open-source framework for defining and running AI agents from the terminal.
Each agent has instructions, a model, and selected tools. A coordinator can delegate work to specialists, then combine their results. Configuration is declarative, typically YAML. HCL is also supported.

Several Docker products serve different roles:

Component	Role	Typical interface
Docker Agent	Build and orchestrate custom AI agents and teams	docker agent
Gordon	Docker’s built-in AI assistant	docker ai
Docker Sandboxes	Isolated environments for running agents	sbx; Docker Agent integrates through --sandbox
Docker Model Runner	Run supported models locally	docker model
Docker MCP integration	Connect agents to external tools using Model Context Protocol	An agent’s mcp toolset

These components can be combined. Running Docker Agent by itself does not mean its filesystem and shell operations are isolated in a VM.

2. How agent teams work

Pattern	Context and control	Useful when
sub_agents	A specialist receives a task in a child session and returns a result to its parent	A coordinator must combine specialist findings
handoffs	Another agent becomes active within the same conversation and sees its history	A workflow moves between conversational roles
background_agents	Supports dispatching independent specialist tasks concurrently	Tasks can proceed independently

With delegation, include the relevant evidence and expected output in the task: a child does not automatically receive the parent’s full conversation. Merely listing sub_agents does not make their execution parallel.

Practical assessment: Start with one agent for a narrow task. Introduce specialists when their responsibilities and outputs are clear. Compare the team against that baseline; extra model calls can add latency and cost, and specialization alone does not guarantee better results.

3. Installation and first run

Docker’s documentation says Docker Agent is included in Docker Desktop 4.63+. Desktop versions 4.49–4.62 used the name cagent. Other installation options include Homebrew, Winget, and release binaries.

A standalone installation can run as docker-agent. To use the Docker CLI plugin form, install or link the binary at the documented plugin location, ~/.docker/cli-plugins/docker-agent.

Configure a model provider, inspect the setup, and launch a session:

docker agent setup
docker agent doctor
docker agent run --model openai/gpt-6.1

The model name above is an example used in Docker’s documentation. Choose a model available to your account. The cloud API path requires the appropriate provider credentials; common variables are OPENAI_API_KEY, ANTHROPIC_API_KEY, and GOOGLE_API_KEY.

Store credentials outside agent YAML. Docker Agent supports environment variables, env files, and other secret providers. Its setup-managed env file is stored in plain text with owner-only permissions; exclude any project .env file from Git.

4. Example: a Docker configuration review team

Save the following as docker-review.yaml in the project to inspect. This is an original example using the documented schema and tool filtering. The documentation currently identifies configuration schema version 15.

version: 15
 
agents:
  root:
    model: openai/gpt-5-mini
    description: Coordinates a review of container configuration
    max_iterations: 12
    instruction: |
      Read the project's Dockerfile and Compose configuration.
      Ask container_reviewer to examine them, passing file contents
      and the user's deployment assumptions in the task.
      Return prioritized findings with file evidence and suggested edits.
      Clearly distinguish inspected configuration from executed tests.
    sub_agents: [container_reviewer]
    toolsets:
      - type: filesystem
        tools: [list_directory, read_file, search_files_content]
 
  container_reviewer:
    model: openai/gpt-5-mini
    description: Examines container build and runtime configuration
    max_iterations: 8
    instruction: |
      Examine the supplied files for build failures, unsafe defaults,
      secret exposure, unnecessary image size, and runtime mismatches.
      Report the file, evidence, likely impact, and a concrete improvement.
      State assumptions and uncertainties. Do not invent test results.
    toolsets:
      - type: filesystem
        tools: [read_file]

Run it interactively:

docker agent run --safety strict docker-review.yaml

Example prompt: “Review this project’s Dockerfile and Compose configuration for a small production deployment. Return the five most important findings.”

For a single non-interactive task:

docker agent run --exec --safety restricted docker-review.yaml \
  "Review Dockerfile and report configuration risks with file evidence."

--exec runs without the terminal UI. Restricted mode permits calls classified as safe and denies other unmatched calls; explicit permission rules can change that behavior. Strict mode asks about unmatched tool calls.

The example exposes selected filesystem reads, with no shell or filesystem-write tools. It can inspect configuration but cannot build an image or validate runtime behavior. Iteration limits bound agent loops; they are not a monetary budget.

5. Tools, permissions, and isolation

Toolsets add capabilities such as filesystem access, shell commands, Git inspection, persistent memory, HTTP requests, and retrieval over indexed documents. Use the tools list to expose only the operations a role needs.

For example, this fragment adds a Docker-hosted search MCP server under an agent’s toolsets:

- type: mcp
  ref: docker:duckduckgo

Docker also supports local-process and remote MCP servers. Docker-hosted MCP tools have their own Docker requirements; the quickstart specifies Docker Desktop for this example. An external tool may need additional credentials.

Permissions support allow, ask, and deny rules. A matching deny takes precedence over allow. User-selected safety modes and existing rules affect prompting, so inspect them before running a third-party configuration. autonomous/--yolo broadly enables tool execution except where other controls still apply. These client-side controls are not an isolation boundary.

For VM isolation, install and configure sbx first, then use:

docker agent run --sandbox --safety strict docker-review.yaml

The current sandbox documentation says Docker Agent invokes sbx to create or reuse a sandbox VM and share the working directory. Shell and filesystem tools execute there. The VM can remain after the agent exits for reuse; manage its lifecycle through the sandbox tooling.

Operational recommendation: Use a dedicated project checkout, share only necessary files, review network access, and grant tools according to the task. Shared project files still require care: isolation does not make edits to the shared workspace disposable.

Documentation caveat: The configuration overview still describes sandboxing as container-based, while the dedicated Sandbox Mode page explicitly describes the current sbx VM integration. This note follows the dedicated page. Verify your installed version’s help before applying older cagent or docker sandbox tutorials.

6. Local models

With Docker Model Runner installed and enabled, the documented local path is:

docker model status
docker model pull ai/qwen3
docker agent doctor
docker agent run --model dmr/ai/qwen3

Local inference does not require a cloud model API key or incur that provider’s per-token charges. Hardware capacity and model suitability still matter. To use a local model in the example team, change both agents’ model values.

Privacy implication: Local inference keeps that inference local, but external MCP tools and HTTP integrations can still transmit information. Assess the complete tool path before treating a workflow as offline.

7. Sharing agent definitions

Docker Agent packages agent configurations as OCI artifacts for Docker Hub or another compatible registry. These are shareable agent definitions; publishing one does not itself deploy a running service.

After authenticating and replacing YOUR_DOCKERHUB_USER with your namespace:

docker agent share push ./docker-review.yaml \
  docker.io/YOUR_DOCKERHUB_USER/docker-review:v1
 
docker agent share pull docker.io/YOUR_DOCKERHUB_USER/docker-review:v1
docker agent run docker.io/YOUR_DOCKERHUB_USER/docker-review:v1

Review configuration and referenced resources before publishing. For external sub-agents, digest-pinned references provide a fixed artifact identity; tag references are checked against the registry on each run.

Sources

1. Docker Agent overview and installation
2. Official Docker Agent repository and license
3. Configuration overview and schema version
4. Sandbox Mode: current sbx integration
5. Set Up a Model
6. Tool Configuration
7. Multi-Agent Systems
8. Managing Secrets
9. Permissions and safety modes
10. CLI Reference
11. Tips & Best Practices
12. Quick Start
13. Agent Distribution
14. Troubleshooting