Installation

Get docker-agent running on your system in minutes.

Prerequisites

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

Docker Desktop (Pre-installed)

Starting with Docker Desktop 4.49.0, docker-agent is already available. No separate installation needed — just open a terminal and run:

$ docker agent version

💡 Tip

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

Homebrew (macOS / Linux)

Install docker-agent using Homebrew:

# Install
$ brew install docker/tap/docker-agent

# Verify
$ docker-agent version

You can also install docker-agent as a docker CLI plugin, by copying docker-agent binary in ~/.docker/cli-plugins. You can then run docker agent version.

Download Binary Releases

Download prebuilt binary releases for Windows, macOS, and Linux from the GitHub Releases page.

macOS / Linux

# Download the latest release (adjust URL for your platform)
curl -L https://github.com/docker/docker-agent/releases/latest/download/docker-agent-$(uname -s)-$(uname -m) -o docker-agent
chmod +x docker-agent
sudo mv docker-agent /usr/local/bin/
docker-agent version

# or alternatively, instead of moving to /usr/local/bin:
mkdir -p ~/.docker/cli-plugins
sudo mv docker-agent ~/.docker/cli-plugins
docker agent version

Windows

Download docker-agent-Windows-amd64.exe from the releases page, rename it to docker-agent.exe and add it to your PATH. Alternatively you can move it to ~/.docker/cli-plugins

Build from Source

For the latest features, or to contribute, build from source:

Prerequisites

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

# Clone the repository
git clone https://github.com/docker/docker-agent.git
cd docker-agent

# Build the binary
task build

# The binary is at ./bin/docker-agent
./bin/docker-agent --help

💡 Building on Windows

On Windows, use task build-local instead of task build. This 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.

Set Up API Keys

docker-agent needs API keys for the model providers you want to use. Set them as environment variables:

# Pick one (or more) depending on your provider
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

ℹ️ Note

You only need the key(s) for the provider(s) you configure in your agent YAML. If you use Docker Model Runner (DMR), no API key is needed — models run locally.

Verify Installation

# Check the version
$ docker agent version

# Run the default agent
$ docker agent run

# Or try a built-in example
$ docker agent run agentcatalog/pirate

What’s Next?

⚡

Quick Start

Create and run your first agent in under 5 minutes.

🔧

Troubleshooting

Something not working? Debug mode, common issues, and solutions.

← Previous Introduction Next → Quick Start