# Docker Agent

> Run AI agents from a YAML file. Define them once, share them through any OCI registry, and run them anywhere — by Docker.

These docs track the `main` branch and may describe unreleased features. The stable documentation lives at https://docs.docker.com/ai/docker-agent/, which publishes its own https://docs.docker.com/llms.txt.

## Getting Started
- [Introduction](https://docker.github.io/docker-agent/getting-started/introduction/): Docker Agent is a multi-agent runtime that lets you build, run, and share AI agents with a YAML or HCL config — no glue code required.
- [Installation](https://docker.github.io/docker-agent/getting-started/installation/): Get Docker Agent running on your system in minutes.
- [Set Up a Model](https://docker.github.io/docker-agent/getting-started/set-up-a-model/): Make a model available to Docker Agent: bring a cloud provider API key or run a local model with Docker Model Runner.
- [Quick Start](https://docker.github.io/docker-agent/getting-started/quickstart/): Get up and running with Docker Agent in under 5 minutes. Pick whichever path suits you best.

## Core Concepts
- [Agents](https://docker.github.io/docker-agent/concepts/agents/): Agents are the core building blocks of Docker Agent. Each agent is an AI-powered entity with a model, instructions, tools, and optional sub-agents.
- [Models](https://docker.github.io/docker-agent/concepts/models/): Models are the AI brains behind your agents. Docker Agent supports multiple providers and flexible configuration.
- [Tools](https://docker.github.io/docker-agent/concepts/tools/): Tools give agents the ability to interact with the world — read files, run commands, search the web, query databases, and more.
- [Multi-Agent](https://docker.github.io/docker-agent/concepts/multi-agent/): Build teams of specialized agents that collaborate and delegate tasks to each other.
- [Agent Distribution](https://docker.github.io/docker-agent/concepts/distribution/): Package, share, and run agents via OCI-compatible registries — just like container images.

## Configuration
- [Overview](https://docker.github.io/docker-agent/configuration/overview/): Docker Agent uses YAML or HCL configuration files to define agents, models, tools, and their relationships.
- [HCL Configuration](https://docker.github.io/docker-agent/configuration/hcl/): Write Docker Agent configs in HCL instead of YAML, using labeled blocks, heredocs, and the same underlying schema.
- [Agent Config](https://docker.github.io/docker-agent/configuration/agents/): Complete reference for defining agents in your YAML configuration.
- [Model Config](https://docker.github.io/docker-agent/configuration/models/): Complete reference for defining models with providers, parameters, and reasoning settings.
- [Tool Config](https://docker.github.io/docker-agent/configuration/tools/): Complete reference for configuring built-in tools, MCP tools, and Docker-based tools.
- [Custom Commands](https://docker.github.io/docker-agent/configuration/commands/): Define slash commands that send prompts, open URLs, or switch agents, and reuse them across agents with top-level command groups.
- [Hooks](https://docker.github.io/docker-agent/configuration/hooks/): Run shell commands at various points during agent execution for deterministic control over behavior.
- [Permissions](https://docker.github.io/docker-agent/configuration/permissions/): Control which tools can execute automatically, require confirmation, or are blocked entirely.
- [Ignoring Files](https://docker.github.io/docker-agent/configuration/agentsignore/): Hide files from the agent with a .agentsignore file, using the same syntax as .gitignore.
- [Sandbox Mode](https://docker.github.io/docker-agent/configuration/sandbox/): Run agents in an isolated Docker sandbox VM for enhanced security.
- [Structured Output](https://docker.github.io/docker-agent/configuration/structured-output/): Force the agent to respond with JSON matching a specific schema.
- [Flavors](https://docker.github.io/docker-agent/configuration/flavors/): Ship one agent file with named variants, enabled at run time as YAML patches.
- [Model Routing](https://docker.github.io/docker-agent/configuration/routing/): Route requests to different models based on the content of user messages.
- [User Settings](https://docker.github.io/docker-agent/configuration/user-settings/): Full reference for the global settings block in ~/.config/cagent/config.yaml: theme, layout, YOLO, sound, snapshots, permissions, hooks, keybindings, and how they interact with agent config and CLI flags.

## Built-in Tools
- [Filesystem](https://docker.github.io/docker-agent/tools/filesystem/): Read, write, list, search, and navigate files and directories.
- [Shell](https://docker.github.io/docker-agent/tools/shell/): Execute arbitrary shell commands in the user's environment.
- [Script](https://docker.github.io/docker-agent/tools/script/): Define custom shell scripts as named tools with typed parameters.
- [Open URL](https://docker.github.io/docker-agent/tools/open-url/): Open a fixed URL in the user's default browser.
- [Fetch](https://docker.github.io/docker-agent/tools/fetch/): Read content from HTTP/HTTPS URLs.
- [A2A](https://docker.github.io/docker-agent/tools/a2a/): Connect to remote agents via the Agent-to-Agent protocol.
- [Handoff](https://docker.github.io/docker-agent/tools/handoff/): Hand off the active conversation to another local agent defined in the same config.
- [Transfer Task](https://docker.github.io/docker-agent/tools/transfer-task/): Delegate tasks to sub-agents in multi-agent setups.
- [Background Agents](https://docker.github.io/docker-agent/tools/background-agents/): Dispatch work to sub-agents concurrently and collect results asynchronously.
- [Background Jobs](https://docker.github.io/docker-agent/tools/background-jobs/): Run and manage long-running shell commands.
- [Memory](https://docker.github.io/docker-agent/tools/memory/): Persistent key-value storage backed by SQLite for cross-session recall.
- [RAG](https://docker.github.io/docker-agent/tools/rag/): Give your agents access to document knowledge bases with background indexing, multiple retrieval strategies, and hybrid search.
- [MCP Catalog](https://docker.github.io/docker-agent/tools/mcp-catalog/): Let the agent discover and activate remote MCP servers from the Docker MCP Catalog on demand.
- [MCP](https://docker.github.io/docker-agent/tools/mcp/): Extend agents with external tools via the Model Context Protocol.
- [Think](https://docker.github.io/docker-agent/tools/think/): Step-by-step reasoning scratchpad for planning and decision-making.
- [Plan](https://docker.github.io/docker-agent/tools/plan/): Shared persistent scratchpad for multi-agent collaboration.
- [Session Plan](https://docker.github.io/docker-agent/tools/session_plan/): Per-session plan tracker for the draft, review, execute workflow.
- [Todo](https://docker.github.io/docker-agent/tools/todo/): Task list management for complex multi-step workflows.
- [Tasks](https://docker.github.io/docker-agent/tools/tasks/): Persistent task database with priorities and dependencies, shared across sessions.
- [Scheduler](https://docker.github.io/docker-agent/tools/scheduler/): Schedule instructions to run at a time or on a recurring interval.
- [User Prompt](https://docker.github.io/docker-agent/tools/user-prompt/): Ask the user questions and collect interactive input during agent execution.
- [Model Picker](https://docker.github.io/docker-agent/tools/model-picker/): Let the agent pick between several models per turn.
- [Session Context](https://docker.github.io/docker-agent/tools/session_context/): Reference a previous session as context in the current one.
- [LSP](https://docker.github.io/docker-agent/tools/lsp/): Connect to Language Server Protocol servers for code intelligence.
- [OpenAPI](https://docker.github.io/docker-agent/tools/openapi/): Automatically generate tools from an OpenAPI specification.
- [API](https://docker.github.io/docker-agent/tools/api/): Create custom tools that call HTTP APIs.

## Features
- [Terminal UI](https://docker.github.io/docker-agent/features/tui/): Docker Agent's default interface is a rich, interactive terminal UI with file attachments, themes, session management, and more.
- [Snapshots](https://docker.github.io/docker-agent/features/snapshots/): Shadow-git snapshots capture your workspace at turn boundaries so you can review what an agent changed and undo it without touching your real git history.
- [Kanban Board](https://docker.github.io/docker-agent/features/board/): Orchestrate multiple agents from a Kanban TUI: each card runs an agent in a tmux session on an isolated git worktree.
- [Sessions](https://docker.github.io/docker-agent/features/sessions/): How Docker Agent stores conversations, resumes them across runs, and tracks their token cost.
- [CLI Reference](https://docker.github.io/docker-agent/features/cli/): Complete reference for all Docker Agent command-line commands and flags.
- [MCP Mode](https://docker.github.io/docker-agent/features/mcp-mode/): Expose your Docker Agent agents as MCP tools for use in Claude Desktop, Claude Code, and other MCP-compatible applications.
- [Coding Harnesses](https://docker.github.io/docker-agent/features/harnesses/): Delegate coding tasks to external AI coding CLIs (Claude Code, Codex, opencode) as sub-agents.
- [A2A Protocol](https://docker.github.io/docker-agent/features/a2a/): Expose Docker Agent agents via Google's Agent-to-Agent (A2A) protocol for interoperability with other agent frameworks.
- [ACP](https://docker.github.io/docker-agent/features/acp/): Expose Docker Agent agents via the Agent Client Protocol for integration with ACP-compatible hosts like VS Code, IDEs, and other developer tools.
- [API Server](https://docker.github.io/docker-agent/features/api-server/): Expose your agents via an HTTP API for programmatic access, web frontends, and integrations.
- [Chat Server](https://docker.github.io/docker-agent/features/chat-server/): Expose your agents through an OpenAI-compatible Chat Completions API so any tool that already speaks OpenAI can drive a Docker Agent agent.
- [Evaluation](https://docker.github.io/docker-agent/features/evaluation/): Measure agent quality with automated evaluations — tool call accuracy, response relevance, output size, and more.
- [Skills](https://docker.github.io/docker-agent/features/skills/): Skills provide specialized instructions that agents can load on demand when a task matches a skill's description.
- [Code Mode](https://docker.github.io/docker-agent/features/code-mode/): Let an agent write JavaScript that orchestrates several tool calls in one turn instead of calling tools one at a time.
- [Remote MCP Servers](https://docker.github.io/docker-agent/features/remote-mcp/): Connect Docker Agent to cloud services via remote MCP servers with built-in OAuth authentication.

## Model Providers
- [Overview](https://docker.github.io/docker-agent/providers/overview/): Docker Agent supports multiple AI model providers. Choose the right one for your use case, or use multiple providers in the same configuration.
- [Anthropic](https://docker.github.io/docker-agent/providers/anthropic/): Use Claude Sonnet 4, Claude Sonnet 4.5, and other Anthropic models with Docker Agent.
- [AWS Bedrock](https://docker.github.io/docker-agent/providers/bedrock/): Access Claude, Nova, Llama, and more through AWS infrastructure with enterprise-grade security and compliance.
- [Baseten](https://docker.github.io/docker-agent/providers/baseten/): Use Baseten AI models with Docker Agent.
- [Cerebras](https://docker.github.io/docker-agent/providers/cerebras/): Use Cerebras models with Docker Agent.
- [Cloudflare AI Gateway](https://docker.github.io/docker-agent/providers/cloudflare-ai-gateway/): Use Cloudflare AI Gateway models with Docker Agent.
- [Cloudflare Workers AI](https://docker.github.io/docker-agent/providers/cloudflare-workers-ai/): Use Cloudflare Workers AI models with Docker Agent.
- [ChatGPT](https://docker.github.io/docker-agent/providers/chatgpt/): Use your ChatGPT Plus/Pro/Business subscription with Docker Agent by signing in with your OpenAI account, no API key needed.
- [DeepSeek](https://docker.github.io/docker-agent/providers/deepseek/): Use DeepSeek models with Docker Agent.
- [Docker Model Runner](https://docker.github.io/docker-agent/providers/dmr/): Run AI models locally with Docker — no API keys, no costs, full data privacy.
- [Fireworks AI](https://docker.github.io/docker-agent/providers/fireworks/): Use Fireworks AI models with Docker Agent.
- [GitHub Copilot](https://docker.github.io/docker-agent/providers/github-copilot/): Use GitHub Copilot's hosted models (GPT-4o, Claude, Gemini, and more) with Docker Agent through your GitHub subscription.
- [Google Gemini](https://docker.github.io/docker-agent/providers/google/): Use Gemini 2.5 Flash, Gemini 3 Pro, and other Google models with Docker Agent.
- [Groq](https://docker.github.io/docker-agent/providers/groq/): Use Groq fast-inference models with Docker Agent.
- [Hugging Face](https://docker.github.io/docker-agent/providers/huggingface/): Use Hugging Face Inference Providers with Docker Agent.
- [Local Models](https://docker.github.io/docker-agent/providers/local/): Run Docker Agent with locally hosted models for privacy, offline use, or cost savings.
- [MiniMax](https://docker.github.io/docker-agent/providers/minimax/): Use MiniMax AI models with Docker Agent.
- [Mistral](https://docker.github.io/docker-agent/providers/mistral/): Use Mistral AI models with Docker Agent.
- [Moonshot AI](https://docker.github.io/docker-agent/providers/moonshot/): Use Moonshot AI (Kimi) models with Docker Agent.
- [Nebius](https://docker.github.io/docker-agent/providers/nebius/): Use Nebius AI models with Docker Agent.
- [NVIDIA](https://docker.github.io/docker-agent/providers/nvidia/): Use NVIDIA NIM models with Docker Agent.
- [OpenAI](https://docker.github.io/docker-agent/providers/openai/): Use GPT-5.6, GPT-4o, GPT-5, GPT-5-mini, and other OpenAI models with Docker Agent.
- [OpenCode Go](https://docker.github.io/docker-agent/providers/opencode-go/): Use OpenCode Go models with Docker Agent.
- [OpenCode Zen](https://docker.github.io/docker-agent/providers/opencode-zen/): Use OpenCode Zen models with Docker Agent.
- [OpenRouter](https://docker.github.io/docker-agent/providers/openrouter/): Use OpenRouter models with Docker Agent.
- [OVHcloud](https://docker.github.io/docker-agent/providers/ovhcloud/): Use OVHcloud AI Endpoints models with Docker Agent.
- [Together AI](https://docker.github.io/docker-agent/providers/together/): Use Together AI models with Docker Agent.
- [Vercel AI Gateway](https://docker.github.io/docker-agent/providers/vercel/): Use Vercel AI Gateway models with Docker Agent.
- [xAI (Grok)](https://docker.github.io/docker-agent/providers/xai/): Use xAI's Grok models with Docker Agent.
- [Provider Definitions](https://docker.github.io/docker-agent/providers/custom/): Define reusable provider configurations with shared defaults for any provider type — OpenAI, Anthropic, Google, Bedrock, and more.

## Resources
- [Tips & Best Practices](https://docker.github.io/docker-agent/guides/tips/): Expert guidance for building effective, efficient, and secure agents.
- [Thinking / Reasoning](https://docker.github.io/docker-agent/guides/thinking/): Control how much a model reasons before responding. Works across OpenAI, Anthropic, Google Gemini, AWS Bedrock, and Docker Model Runner.
- [Managing Secrets](https://docker.github.io/docker-agent/guides/secrets/): How to securely provide API keys and credentials to Docker Agent using environment variables, env files, Docker Compose secrets, and 1Password references.
- [Go SDK](https://docker.github.io/docker-agent/guides/go-sdk/): Use Docker Agent as a Go library to embed AI agents in your applications.
- [Managing Context & Compaction](https://docker.github.io/docker-agent/guides/compaction/): How to keep long Docker Agent sessions from filling the model's context window: automatic and on-demand compaction, trimming tool results, and reading the context gauge.
- [Running Agents Headless & in CI](https://docker.github.io/docker-agent/guides/headless/): Run Docker Agent without a TUI: structured JSON output, event hooks, sandboxed CI isolation, and a GitHub Actions example.
- [Contributing](https://docker.github.io/docker-agent/community/contributing/): Docker Agent is open source. Here's how to set up your development environment and contribute.
- [Troubleshooting](https://docker.github.io/docker-agent/community/troubleshooting/): Common issues and how to resolve them when working with Docker Agent.
- [Telemetry](https://docker.github.io/docker-agent/community/telemetry/): Docker Agent collects anonymous usage data to help improve the tool. Telemetry can be disabled at any time.
- [OpenTelemetry Tracing](https://docker.github.io/docker-agent/community/opentelemetry/): Export Docker Agent traces to any OTLP backend, including Langfuse and LangSmith, for debugging agentic workflows.