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.63, docker-agent is already available. No separate installation needed — just open a terminal and run:
$ docker agent version
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-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
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
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 (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
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 (or GEMINI_API_KEY)
export MISTRAL_API_KEY="..." # Mistral
See Configuration Overview for the full list of supported providers and environment variables.
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