Configuration Overview

docker-agent uses YAML or HCL configuration files to define agents, models, tools, and their relationships.

File Structure

A docker-agent config can be written in YAML or HCL. The examples on this page use YAML; see HCL Configuration for the block-based HCL syntax.

A docker-agent config has these main sections:

# 1. Version — configuration schema version (optional but recommended)
version: 8

# 2. Metadata — optional agent metadata for distribution
metadata:
  author: my-org
  description: My helpful agent
  version: "1.0.0"

# 3. Models — define AI models with their parameters
models:
  claude:
    provider: anthropic
    model: claude-sonnet-4-5
    max_tokens: 64000

# 4. Agents — define AI agents with their behavior
agents:
  root:
    model: claude
    description: A helpful assistant
    instruction: You are helpful.
    toolsets:
      - type: think

# 5. RAG — define retrieval-augmented generation sources (optional)
rag:
  docs:
    docs: ["./docs"]
    strategies:
      - type: chunked-embeddings
        embedding_model: openai/text-embedding-3-small

# 6. MCPs — reusable MCP server definitions (optional)
mcps:
  github:
    remote:
      url: https://api.githubcopilot.com/mcp
      transport_type: sse

# 7. Providers — optional reusable provider definitions
providers:
  my_provider:
    provider: anthropic  # or openai (default), google, amazon-bedrock, etc.
    token_key: MY_API_KEY
    max_tokens: 16384

# 8. Permissions — agent-level tool permission rules (optional)
#    For user-wide global permissions, see ~/.config/cagent/config.yaml
permissions:
  allow: ["read_*"]
  deny: ["shell:cmd=sudo*"]

Minimal Config

The simplest possible configuration — a single agent with an inline model:

agents:
  root:
    model: openai/gpt-5-mini
    description: A helpful assistant
    instruction: You are a helpful assistant.

The same config in HCL:

agent "root" {
  model       = "openai/gpt-5-mini"
  description = "A helpful assistant"
  instruction = "You are a helpful assistant."
}

Inline vs Named Models

Models can be referenced inline or defined in the models section:

model: openai/gpt-5-mini

model: my_claude

Config Sections

Advanced Configuration

Environment Variables

API keys and secrets are read from environment variables — never stored in config files. See Managing Secrets for all the ways to provide credentials (env files, Docker Compose secrets, macOS Keychain, pass):

Tool Auto-Installation:

Runtime overrides:

Validation

docker-agent validates your configuration at startup:

• Local sub_agents must reference agents defined in the config (external OCI references like agentcatalog/pirate are pulled from registries automatically)
• Named model references must exist in the models section
• Provider names must be valid (openai, anthropic, google, dmr, etc.)
• Required environment variables (API keys) must be set
• Tool-specific fields are validated (e.g., path is only valid for memory)

JSON Schema

For YAML editor autocompletion and validation, use the Docker Agent JSON Schema. Add this to the top of your YAML file:

# yaml-language-server: $schema=https://raw.githubusercontent.com/docker/docker-agent/main/agent-schema.json

Config Versioning

docker-agent configs are versioned. The current version is 8. Add the version at the top of your config:

version: 8

agents:
  root:
    model: openai/gpt-5-mini
    # ...

When you load an older config, docker-agent automatically migrates it to the latest schema. It’s recommended to include the version to ensure consistent behavior.

Metadata Section

Optional metadata for agent distribution via OCI registries:

metadata:
  author: my-org
  license: Apache-2.0
  description: A helpful coding assistant
  readme: | # Displayed in registries
    This agent helps with coding tasks.
  version: "1.0.0"

See Agent Distribution for publishing agents to registries.

Reusable MCP Servers (mcps:)

The top-level mcps: section defines named MCP server configurations that agents can reference with toolsets: [{type: mcp, ref: <name>}]. This avoids repeating the same command / URL / headers across agents and keeps credentials in one place.

mcps:
  github:
    remote:
      url: https://api.githubcopilot.com/mcp
      transport_type: sse
  playwright:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-playwright"]

agents:
  root:
    model: openai/gpt-5-mini
    toolsets:
      - type: mcp
        ref: github        # reuse the definition above
      - type: mcp
        ref: playwright

An mcps entry accepts every field a regular type: mcp toolset accepts (command/args/env, remote with url/transport_type/headers/oauth, tools filter, instruction, defer, …) — the type: mcp is implicit. See the Tool Config page for all options and the Remote MCP Servers guide for remote setups.

Custom Providers Section

Define reusable provider configurations with shared defaults. Providers can wrap any provider type — not just OpenAI-compatible endpoints:

providers:
  # OpenAI-compatible custom endpoint
  azure:
    api_type: openai_chatcompletions
    base_url: https://my-resource.openai.azure.com/openai/deployments/gpt-4o
    token_key: AZURE_OPENAI_API_KEY

  # Anthropic with shared model defaults
  team_anthropic:
    provider: anthropic
    token_key: TEAM_ANTHROPIC_KEY
    max_tokens: 32768
    thinking_budget: high

models:
  azure_gpt:
    provider: azure
    model: gpt-4o

  claude:
    provider: team_anthropic
    model: claude-sonnet-4-5
    # Inherits max_tokens, thinking_budget from provider

agents:
  root:
    model: claude

See Provider Definitions for more details.