Agent Zero Setup Guide

Agent Zero runs inside Docker — this is what gives it a real Linux environment to work in. You need Docker installed first.

Copy# Option 1: Download Docker Desktop from:
https://docs.docker.com/desktop/install/windows-install/

# Option 2: winget (Windows 11)
winget install Docker.DockerDesktop

Copy# Option 1: Download from:
https://docs.docker.com/desktop/install/mac-install/

# Option 2: Homebrew
brew install --cask docker

Copy# Install Docker
sudo apt update && sudo apt install -y docker.io

# Add your user to docker group (no sudo needed)
sudo usermod -aG docker $USER

# Apply group change (or log out and back in)
newgrp docker

# Verify
docker --version

Pull the official Agent Zero Docker image from Docker Hub. This downloads everything needed (~2 GB).

Copydocker pull alexander-ai/agent-zero

This may take 2–5 minutes depending on your internet speed. You'll see download progress bars.

Start Agent Zero with one command. This launches the container and exposes the web UI on port 50001.

Copydocker run -p 50001:80 alexander-ai/agent-zero

Now open your browser and go to:

Copyhttp://localhost:50001

If port 50001 is already in use on your machine:

Copy# Use a different port (e.g. 50002)
docker run -p 50002:80 alexander-ai/agent-zero
# Then open: http://localhost:50002

Agent Zero needs an API key to talk to an AI model. Pick one of these options — OpenRouter is recommended for beginners (free credits included).

To add your API key in Agent Zero:

1. Open http://localhost:50001 in your browser
2. Click the ⚙️ Settings icon (top right)
3. Go to Models tab
4. Select your provider (e.g. OpenRouter)
5. Paste your API key
6. Choose your model (e.g. openai/gpt-4o on OpenRouter)
7. Click Save

With your API key configured, it's time to give Agent Zero its first task. Start simple:

Copy# Start with something simple
hello

# Check what it can do
what tools do you have access to?

# Test its execution capability
list all files in the home directory

# A real task
create a Python script that prints "Hello from Agent Zero!" and run it

If you run into problems, check the Troubleshooting Guide or chat with our AI assistant.

By default, Agent Zero's memory and files are stored inside the Docker container. If you remove the container, you lose that data. Mount a local directory to persist everything:

Copy# Replace C:\Users\YourName\agent-zero-data with your preferred path
docker run -p 50001:80 -v C:\Users\YourName\agent-zero-data:/a0 alexander-ai/agent-zero

Copy# Creates ~/agent-zero-data and mounts it into the container
mkdir -p ~/agent-zero-data
docker run -p 50001:80 -v ~/agent-zero-data:/a0 alexander-ai/agent-zero