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*"]

# 9. Commands & Skills — reusable, named groups shared across agents (optional)
commands:
  ci:
    deploy: "Deploy the application"
skills:
  base: [local, git]

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:

Variable Expansion in Config Fields

docker-agent uses two different expansion syntaxes depending on the field. They are not interchangeable: using the wrong syntax in a field is currently a silent no-op, so the literal string is passed through. Tracking issue: #2615.

JavaScript template literals — ${env.VAR}

Used wherever the agent prompt or HTTP traffic is templated. Backed by a JS evaluator, so you also get || defaults, ternaries, and tool calls (${tool({...})}).

Applies to:

• agents.<name>.description
• agents.<name>.welcome_message
• agents.<name>.instruction
• agents.<name>.commands.* (string form and instruction: field)
• toolsets[*].instruction
• toolsets[*].headers and toolsets[*].remote.headers (MCP, A2A, OpenAPI, fetch, API)

For api toolsets, api_config.endpoint and api_config.headers are also rendered through the JS expander (the same syntax applies).

agents:
  root:
    description: "Assistant for ${env.USER || 'guest'}"
    commands:
      deploy: "Deploy ${env.PROJECT_NAME || 'app'} to ${env.ENV || 'staging'}"
    toolsets:
      - type: openapi
        url: https://api.example.com
        headers:
          Authorization: "Bearer ${env.INTERNAL_TOKEN}"

Undefined variables expand to the empty string.

Shell-style — $VAR, ${VAR}, ~

Used for filesystem paths. Backed by os.ExpandEnv plus tilde expansion against the current user’s home directory.

Applies to:

• agents.<name>.toolsets[*].working_dir (MCP, LSP)
• agents.<name>.toolsets[*].path (memory, tasks)
• agents.<name>.toolsets[*].env values (MCP, shell, script, LSP) — these go through os.Expand, not the JS evaluator, so ${env.X} is not recognized here.
• The ~ prefix is also accepted in any path-like field documented as such.

agents:
  root:
    toolsets:
      - type: memory
        path: "~/notes/${PROJECT}/memory.db"
      - type: mcp
        command: my-server
        working_dir: "$HOME/work"

The working_dir and path fields additionally accept the ${env.VAR} form as an alias for ${VAR}, so the JS-style syntax works there too. Richer JS expressions (e.g. ${env.VAR || 'default'}) are still not evaluated in path fields. The env values fields remain shell-only.

Quick reference

When in doubt, prefer ${env.X} for prompts and headers, and ${X} (or $X) for paths.

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.

Reusable Commands & Skills (commands: / skills:)

The top-level commands: and skills: sections define named, reusable groups that agents pull in by name through use_commands: / use_skills:. This avoids repeating the same command set or skill configuration across agents. Each group value uses the exact same format as an agent’s own commands / skills field.

Referenced groups are merged into the agent during config loading. An agent’s own inline commands / skills entries take precedence on name conflicts.

commands:
  ci:                       # a named command group
    deploy: "Deploy the application"
    test: "Run the test suite"
skills:
  base: [local, git]        # a named skill group

agents:
  root:
    model: openai/gpt-5-mini
    use_commands: [ci]        # reuse the "ci" command group
    use_skills: [base]        # reuse the "base" skill group
    commands:
      lint: "Run the linter"  # inline command, merged in (wins on conflict)
  reviewer:
    model: openai/gpt-5-mini
    use_commands: [ci]        # same group, reused without duplication

See examples/shared-commands-skills.yaml for a complete example.

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.