Documentation

Get Started with Agent Zero

Install, configure, and start using Agent Zero in minutes. Watch the walkthrough or follow the steps below.

Agent Zero - Easy Installation Guide Play video

How to Install Agent Zero

Agent Zero runs in a secure, isolated Docker container, which is the recommended and safest method for deployment. This makes installation simple and consistent across all platforms — Windows, macOS, and Linux.

Quick Install (Recommended)

Run a single command to install everything automatically:

# The fast path to a running agent.
$ curl -fsSL https://bash.agent-zero.ai | bash
# Run this in PowerShell.
> irm https://windows.agent-zero.ai | iex
# Port 80, no mapping boilerplate.
$ docker run -p 80:80 agent0ai/agent-zero

The script handles Docker, configuration, and startup automatically.

Follow the steps in the CLI, set your port and auth credentials. Follow the onboarding, set your API key.

or

Manual Installation (Advanced)

💡 Note: Users should use the Quick Install above. The manual method below is for advanced users who need custom Docker configurations or cannot use the install scripts.

Step 1: Install Docker Desktop

Docker Desktop is free for personal use and required to run Agent Zero.

  1. Download Docker Desktop: Visit docker.com and download Docker Desktop for Windows
    Docker Desktop download page
  2. Run the installer: Double-click the downloaded file and follow the installation wizard with default settings
    Docker installer
  3. Launch Docker Desktop: After installation, start Docker Desktop from your Start menu
    Docker Desktop Windows icon
  4. Verify installation: Wait for Docker Desktop to fully start (you'll see the Docker icon in your system tray)

💡 Note: Docker Desktop on Windows requires WSL 2. The installer will set this up automatically if needed.

  1. Download Docker Desktop: Visit docker.com and download Docker Desktop for Mac (choose your chip: Intel or Apple Silicon)
  2. Install the app: Open the downloaded .dmg file and drag Docker to your Applications folder
    Docker Desktop macOS installation
  3. Launch Docker Desktop: Open Docker from your Applications folder
  4. Configure socket (important!): On first launch, go to Settings → Advanced and ensure "Allow the default Docker socket to be used" is checked
    Docker socket configuration

💡 Note: Make sure to allow Docker file system access when prompted by macOS.

  1. Install Docker CE: Use your package manager or follow the official Docker guide 
    # Ubuntu/Debian
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

# Fedora
sudo dnf install docker-ce docker-ce-cli containerd.io

# Arch
sudo pacman -S docker
  2. Add user to docker group: This allows running Docker without sudo 
    sudo usermod -aG docker $USER
newgrp docker  # Or log out and back in
  3. Start Docker service: 
    sudo systemctl start docker
sudo systemctl enable docker  # Start on boot
  4. Verify installation: 
    docker --version
docker ps  # Should run without errors

Step 2: Pull the Agent Zero Image

The Agent Zero Docker image contains a complete Linux system with all necessary software pre-installed. It's approximately 2GB to download and 4.5GB when extracted.

Option A: Using Docker Desktop (Recommended)

  1. Open Docker Desktop
  2. Click on the search bar at the top
  3. Search for agent0ai/agent-zero
  4. Select the image (should show 10K+ downloads)
  5. Click "Pull" to download the latest version
Docker image search

Option B: Using Command Line

docker pull agent0ai/agent-zero:latest

The download will take a few minutes depending on your internet connection.

Step 3: Run Your Agent Zero Container

Docker images are blueprints; containers are running instances. You can run multiple independent Agent Zero containers from a single image if needed.

Option A: Using Docker Desktop (Recommended)

  1. Go to the "Images" tab in Docker Desktop
  2. Find agent0ai/agent-zero and click the "Run" button
  3. Click "Optional settings" to expand configuration options
    Docker run configuration
  4. Port mapping: In the "Ports" section, enter 0 in the "Host port" field next to port 80
    Tip: Use 0 to let Docker assign a random port, or specify a port like 50080
  5. (Optional) SSH access: Map the SSH port (22) to access the container's terminal
  6. (Optional) Data persistence: Map volumes to preserve data (see Data Persistence section below)
    7. Docker port mapping
  7. Click "Run" to start the container

Option B: Using Command Line

# Basic run (ephemeral - data lost on container deletion)
docker run -d -p 50080:80 --name agent-zero agent0ai/agent-zero

# With data persistence (recommended)
docker run -d -p 50080:80 -v /path/to/local/data:/a0/usr --name agent-zero agent0ai/agent-zero

The container will start in a few seconds. You'll see a green "Running" status in Docker Desktop:

Docker container running

Step 4: Access the Web UI

Once the container is running, access Agent Zero through your web browser:

  • Via Docker Desktop: Click on the port link shown in your container details
    Docker container port link
  • Via Browser: Navigate to http://localhost:<PORT> (e.g., http://localhost:50080)

You should see the Agent Zero interface with a green status indicator:

Agent Zero Web UI

⚠️ Important: Configure Your AI Model

Agent Zero won't work until you configure an AI model provider. Continue to the next section to set this up.

How to Configure and Use Agent Zero

After installation, you need to configure Agent Zero with an AI model provider before you can start chatting. Click the "Settings" button in the web interface to access all configuration options.

Quick Start: Using OpenRouter

OpenRouter is configured as the default provider and requires minimal setup:

  1. Visit openrouter.ai and create an account
  2. Navigate to API Keys and create a new key
  3. Copy your API key
  4. From the 'Models' section of OpenRouter, choose one of the available free models
  5. In Agent Zero, click "Settings" → "External Services"
  6. Paste your key in "OpenRouter"
  7. Write the model names in the 'Chat Model', 'Utility Model' and 'Web Browser Model' fields
  8. Click "Save"

✅ Done! You're ready to start using Agent Zero. Try asking it a question in the chat interface.

Understanding Model Configuration

Agent Zero uses different AI models for different purposes. Each can be configured independently:

Chat Model (Main Brain)

  • Primary model that handles conversations and complex reasoning
  • Configure in: Settings → Agent Settings → Chat Model
  • Recommended: gpt-4.1 for quality and cost efficiency
Chat model settings

Utility Model (Helper Model)

  • Smaller, faster model for internal tasks like memory organization and summarization
  • Can use the same provider as chat model or a cheaper/faster alternative
  • Recommended: gpt-4.1 for quality and cost efficiency

Embedding Model (Memory System)

  • Generates embeddings for Agent Zero's memory and knowledge base
  • Note: Changing this will re-index all memories (can take time)
  • Recommended: Use the default light-weight embedding model

Security: Setting Up Authentication

If you plan to access Agent Zero over the internet or from multiple devices, secure your instance:

  • UI Login & Password: Settings → Authentication → Set username and password for web interface access
  • Root Password: Settings → Authentication → Set password for SSH access to the Docker container

After enabling authentication, you can easily share your Agent Zero instance by opening the External Services panel in the UI, scrolling to the bottom to find the Flare Tunnel section, and clicking Create Tunnel to expose it via a shareable QR code.

Authentication settings

⚠️ Important: Always enable authentication if using Cloudflare Tunnel or exposing your instance to the internet.

Customizing Agent Behavior

Agent Zero's behavior is controlled by prompts and configurations:

See the full Usage Guide for detailed customization options.

Running Local Models with Ollama

For complete privacy, offline operation, and zero API costs, run local language models using Ollama. Note: Local models require significant additional configuration and computing resources.

Step 1: Install Ollama

Download and install Ollama on your host machine (not inside Docker):

  • Windows/macOS: Download installer from ollama.com
  • Linux: curl -fsSL https://ollama.com/install.sh | sh

Step 2: Download Models

Pull the models you want to use. Popular options include: 

# Recommended for chat
ollama pull llama3.2

# Smaller, faster option
ollama pull llama3.2:1b

# Larger, more capable
ollama pull llama3.1:70b

View all available models at the Ollama model library.

Step 3: Configure Agent Zero

  1. In Agent Zero, go to Settings → Agent Settings
  2. For Chat Model (or Utility/Embedding), select "Ollama" as the provider
  3. Enter the model code (e.g., llama3.2)
  4. Set API base URL to http://host.docker.internal:11434
  5. Save your settings
Ollama local models settings

💡 Note: The URL host.docker.internal allows the Docker container to access services on your host machine.

Managing Ollama Models

# List downloaded models
ollama list

# Remove a model
ollama rm llama3.2

# Update a model
ollama pull llama3.2

⚡ Performance Tip

Local models require significant RAM and CPU/GPU resources. For best performance:

  • Use models sized appropriately for your hardware (1B-7B for most users)
  • Consider using a GPU if available
  • Local models may be slower than cloud APIs, especially for complex tasks

Alternative: You can also use LM Studio for local models. Configuration is similar to Ollama.

Updating Agent Zero

Agent Zero is actively developed with regular updates.

Self Update (Recommended)

  1. Open Settings UI → Update tab
  2. Open Self Update
  3. Wait for the update checker to see if you have the latest version or if there's an available update.

You'll also be prompted through the UI when a new A0 version is released. Backups are automatically managed internally.

Updating from Pre-v0.9.8

💡 Note: If upgrading from v0.9.7 or earlier, the architecture has significantly changed. You must use the install script and manually migrate your data.

  1. Backup your existing usr/ directory: Make a copy of your usr/ folder containing your data.
  2. Run the new install script: Use the Quick Install script shown in the Installation section above.
  3. Migrate your data: Copy the contents of your backed-up usr/ directory into the new a0/usr/ directory.

Manual Update (Advanced)

💡 Note: Use this method only if the self-update feature is unavailable or you need to manage containers manually.

  1. Keep your current container running - Don't stop or delete it yet!
  2. Pull the latest image: docker pull agent0ai/agent-zero:latest
  3. Run the NEW container on a different port: docker run -d -p 50081:80 --name agent-zero-new agent0ai/agent-zero
  4. Access your OLD instance: Backup your data (Settings → Backup & Restore → Create Backup)
  5. Access your NEW instance: Restore your data (Settings → Backup & Restore → Restore)
  6. Verify and cleanup: Only delete old container after confirming data is restored

Never delete your old container until you've verified the new one has all your data!

Data Persistence & Backups

By default, Docker containers are ephemeral. When you delete a container, data inside is lost (chats, memories, files, and settings).

Option 1: Built-in Backup & Restore (Recommended)

Agent Zero includes built-in backup functionality:

  1. Click Settings → Backup & Restore
  2. Click "Create Backup" to download all data as a file
  3. Store the backup file safely on your computer
  4. When updating or recreating containers, use "Restore" to import your data

Option 2: Volume Mapping (Advanced)

Most users do not need volume mapping; Backup and Restore is simpler. When you need a volume, map a folder on your machine to the /a0/usr directory inside the container. 

docker run -d -p 50080:80 -v /path/to/local/folder:/a0/usr --name agent-zero agent0ai/agent-zero

⚠️ Volume Mapping Notes

  • Do NOT map the entire /a0 directory when upgrading
  • Prefer a single mapping from a folder on your machine to /a0/usr
  • Always use Backup & Restore before major updates

What Gets Saved

  • /agents - Agent configurations
  • /usr/projects - Projects
  • /memory - Conversation history and memories
  • /knowledge - Knowledge base files
  • /instruments - Custom tools and instruments
  • /prompts - Custom prompt templates
  • /tmp/settings.json - UI settings and configurations
  • .env - Environment variables and API keys

Mobile & Network Access

Access Agent Zero from anywhere on your local network, or expose it to the internet.

Local Network Access

Access Agent Zero from phones, tablets, or other computers on your network:

  1. Find your computer's local IP address:
    • Windows: Run ipconfig and look for IPv4 Address
    • macOS/Linux: Run ifconfig or ip addr
  2. On your mobile device, navigate to http://[YOUR_IP]:[PORT]
  3. Example: http://192.168.1.100:50080

Internet Access

To access Agent Zero from anywhere via the internet, use the built-in tunnel integration in the UI:

  1. In the Agent Zero UI, open Settings → External Services.
  2. Scroll to the bottom and find the Flare Tunnel section.
  3. Click Create Tunnel.
  4. Scan the generated QR code on your phone or share the provided URL to access your Agent Zero instance remotely.

For advanced or custom configurations, you can also use Cloudflare Tunnel directly; see the official Cloudflare Tunnel documentation.

⚠️ Security warning: Always enable authentication (UI login/password) before exposing to the internet!

Need Help?

Running into issues? Reach out to the community!

Community Support

Get help from the community and developers in real-time.