Installation

Prerequisites

An API key for at least one AI provider (OpenAI, Anthropic, Google, etc.)
Optional: Docker Desktop — for Docker MCP tools and Docker Model Runner

Install docker-agent

Docker Desktop
Homebrew
Binary release
Build from source

Starting with Docker Desktop 4.63+, docker-agent is pre-installed. No separate installation needed.Open a terminal and verify:

docker agent version

Docker Desktop bundles docker-agent and keeps it up to date automatically. This is the easiest way to get started, especially if you want to use Docker MCP tools or Docker Model Runner for local models.

Install with Homebrew

brew install docker-agent

Verify the installation

docker-agent version

(Optional) Install as a Docker CLI plugin

Symlink the binary into the Docker CLI plugins directory to use docker agent instead of docker-agent:

mkdir -p ~/.docker/cli-plugins
ln -sf "$(which docker-agent)" ~/.docker/cli-plugins/docker-agent
docker agent version

Download a prebuilt binary from GitHub Releases for your platform.

macOS / Linux
Windows

Download the binary

OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m); case "$ARCH" in x86_64) ARCH=amd64;; aarch64) ARCH=arm64;; esac
curl -L "https://github.com/docker/docker-agent/releases/latest/download/docker-agent-${OS}-${ARCH}" -o docker-agent
chmod +x docker-agent

Move to your PATH or Docker CLI plugins

To use as a standalone command:

sudo mv docker-agent /usr/local/bin/
docker-agent version

Or to use as a Docker CLI plugin (docker agent):

mkdir -p ~/.docker/cli-plugins
mv docker-agent ~/.docker/cli-plugins/docker-agent
docker agent version

Download the binary

Download docker-agent-windows-amd64.exe from the GitHub Releases page and rename it to docker-agent.exe.

Add to PATH or Docker CLI plugins

To use as a standalone command, move docker-agent.exe to a directory in your PATH.To use as a Docker CLI plugin (docker agent), move it to %USERPROFILE%\.docker\cli-plugins\:

mkdir -Force "$env:USERPROFILE\.docker\cli-plugins"
Move-Item docker-agent.exe "$env:USERPROFILE\.docker\cli-plugins\docker-agent.exe"
docker agent version

Build from source to get the latest features or to contribute.Prerequisites:

Go 1.26 or higher
Task 3.44 or higher
golangci-lint (for linting)

Clone the repository

git clone https://github.com/docker/docker-agent.git
cd docker-agent

Build the binary

macOS / Linux
Windows

task build

task build-local

On Windows, task build-local builds the binary inside a Docker container using Docker Buildx, which avoids issues with Windows-specific toolchain setup and CGo cross-compilation. The output goes to the ./dist directory.

Run the binary

./bin/docker-agent --help

Set up API keys

docker-agent needs at least one API key for the AI provider you want to use. Set it as an environment variable before running any agents.

export OPENAI_API_KEY="sk-..."        # OpenAI
export ANTHROPIC_API_KEY="sk-ant-..." # Anthropic
export GOOGLE_API_KEY="AI..."         # Google Gemini
export MISTRAL_API_KEY="..."          # Mistral

You only need the key for the provider configured in your agent YAML. If you use Docker Model Runner for local models, no API key is required.

To persist your API key across sessions, add the export line to your shell profile (~/.bashrc, ~/.zshrc, or equivalent).

Verify the installation

# Check the installed version
docker agent version

# Run the default built-in agent
docker agent run

# Try a pre-built agent from the catalog
docker agent run agentcatalog/pirate

Get Started

Core Concepts

Features

Configuration

Built-in Tools

Model Providers

Guides

Community

Prerequisites

Install docker-agent

Set up API keys

Verify the installation

What’s next

Quickstart

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Configuration

Built-in Tools

Model Providers

Guides

Community

​Prerequisites

​Install docker-agent

​Set up API keys

​Verify the installation

​What’s next

Quickstart

Troubleshooting

Build docs developers (and LLMs) love

Prerequisites

Install docker-agent

Set up API keys

Verify the installation

What’s next