Skip to main content
This guide walks you through the fastest paths to a working agent. Pick whichever option suits you best.

​
Option A: Run the default agent

The fastest way to try docker-agent — no config file needed: 
docker agent run
This launches a general-purpose assistant with sensible defaults using the interactive TUI. Just start chatting.

​
Option B: Run a pre-built agent from the catalog

Pull and run a ready-made agent from the agent catalog — no YAML required: 
# Run a pirate-themed assistant
docker agent run agentcatalog/pirate

# Run a coding agent
docker agent run agentcatalog/coder

​
Option C: Write your own agent config

1

Create an agent.yaml

Create a file named agent.yaml in your working directory:
agent.yaml
agents:
  root:
    model: openai/gpt-5-mini
    description: A helpful AI assistant
    instruction: |
      You are a knowledgeable assistant that helps users with various tasks.
      Be helpful, accurate, and concise in your responses.
This is the minimal structure every agent config requires:
  • agents.root — the entry-point agent (the name root is the default)
  • model — the AI model in provider/model-name format
  • description — a short summary of what the agent does
  • instruction — the system prompt that shapes the agent’s behavior
2

Add tools (optional)

Give your agent capabilities by adding toolsets. Here is an agent with filesystem access, shell execution, and step-by-step reasoning:
agent.yaml
agents:
  root:
    model: anthropic/claude-sonnet-4-0
    description: A helpful coding assistant
    instruction: |
      You are an expert software developer. Help users write
      clean, efficient code. Explain your reasoning.
    toolsets:
      - type: filesystem
      - type: shell
      - type: think
3

Run the agent

Launch the interactive TUI:
docker agent run agent.yaml
Once the agent is running, try asking it to:
  • “List the files in the current directory”
  • “Create a Python script that fetches weather data”
  • “Explain what the code in main.go does”
Add --yolo to auto-approve all tool calls without being prompted:
docker agent run agent.yaml --yolo

​
Option D: Generate a config interactively

Use docker agent new to scaffold a config file through prompts: 
# Interactive wizard
docker agent new

# Specify a model directly
docker agent new --model openai/gpt-4o
This generates an agent.yaml in the current directory. Run it with: 
docker agent run agent.yaml

​
Non-interactive mode

Use --exec to run an agent without the TUI — useful for scripts and one-shot tasks: 
# Pass a prompt directly
docker agent run --exec agent.yaml "Create a Dockerfile for a Node.js app"

# Pipe input from stdin
cat error.log | docker agent run --exec agent.yaml "What's wrong in this log?"
With --exec, the agent processes the prompt and exits. Combine with --hide-tool-calls for clean output or --json for machine-readable results.

​
Add more capabilities

Extend your agent with persistent memory and web search:
agent.yaml
agents:
  root:
    model: anthropic/claude-sonnet-4-0
    description: Research assistant with memory
    instruction: |
      You are a research assistant. Search the web for information,
      remember important findings, and provide thorough analysis.
    toolsets:
      - type: think
      - type: memory
        path: ./research.db
      - type: mcp
        ref: docker:duckduckgo
The ref: docker:duckduckgo syntax runs the DuckDuckGo MCP server in a Docker container. This is the recommended way to use MCP tools — secure, isolated, and easy to configure. Requires Docker Desktop.
Run it the same way: 
docker agent run agent.yaml

​
What’s next

Understand agents

Learn how agents work and what you can configure.

Multi-agent systems

Build teams of collaborating agents.

Configuration reference

Full reference for all YAML options.

Troubleshooting

Debug tips and common fixes.

Build docs developers (and LLMs) love

Get started for freeTalk to us