Installation

Get cagent 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, cagent is already available. No separate installation needed — just open a terminal and run:

cagent version

💡 Tip

Docker Desktop bundles cagent 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 cagent using Homebrew:

# Install
$ brew install docker/tap/cagent

# Verify
$ cagent 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/cagent/releases/latest/download/cagent-$(uname -s)-$(uname -m) -o cagent
chmod +x cagent
sudo mv cagent /usr/local/bin/

Windows

Download cagent-Windows-x86_64.exe from the releases page and add it to your PATH.

Build from Source

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

Prerequisites

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

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

# Build the binary
task build

# The binary is at ./bin/cagent
./bin/cagent --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

cagent 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
$ cagent version

# Run the default agent
$ cagent run

# Or try a built-in example
$ cagent 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