How to Set Up Agent Zero with Docker: A Complete Installation Guide

Run the official agent0ai/agent-zero image with a persistent volume mounted to /a0/usr and port 80 mapped to your host to deploy the full Agent Zero AI framework in minutes.

Agent Zero is an open-source AI agent framework distributed as a single Docker image that bundles the backend, web UI, and optional tools like SearXNG search and voice processing. Setting up Agent Zero with Docker provides an isolated, reproducible environment where all dependencies are pre-installed and user data persists across container restarts.

Understanding the Agent Zero Docker Architecture

The Docker implementation follows a layered approach defined in DockerfileLocal at the repository root.

Base Image and Runtime Layers

The build process starts from agent0ai/agent-zero-base:latest, which provides a minimal Linux system with Python 3 and compiled dependencies. During image construction, the Dockerfile copies the pre-built filesystem from docker/run/fs/ and executes a series of installation scripts: pre_install.sh, install_A0.sh, install_additional.sh, install_A02.sh, and post_install.sh.

Initialization and Service Management

When the container starts, initialize.sh (specified as the CMD in DockerfileLocal) performs three critical tasks:

1. Creates the user data directory at /a0/usr
2. Runs migration scripts for legacy folder structures
3. Launches supervisord to manage background processes

The supervisord configuration starts the Web UI on port 80, an SSH daemon on port 22 for remote code execution, and auxiliary services including SearXNG and the Tunnel API. All services are defined in the initialization scripts located in docker/run/fs/ins/.

Prerequisites and Initial Setup

Before running Agent Zero with Docker, ensure your system meets the following requirements:

• Docker Desktop or docker-ce installed (version 20.10 or later recommended)
• At least 4GB of RAM allocated to Docker
• 10GB of free disk space for the image and persistent data

Install Docker Desktop following the official guides for your operating system, then verify the installation:

docker --version

Running Agent Zero with Docker

The agent0ai/agent-zero image exposes ports 22, 80, and 9000-9009. You can deploy the container using several approaches depending on your persistence and configuration needs.

Quick Start (No Persistence)

For testing or ephemeral instances, run the container without volume mounts:

docker run -p 50001:80 agent0ai/agent-zero

Access the web interface at http://localhost:50001. Note: All data, settings, and uploaded files will be lost when the container stops.

Production Deployment with Persistent Storage

For production use, mount a host directory to /a0/usr to persist settings, memories, projects, and uploaded files across container restarts:

# Create a dedicated data directory

DATA_DIR="/home/$(whoami)/agent-zero-data"
mkdir -p "$DATA_DIR"

# Run with persistence

docker run -d \
  -p 50080:80 \
  -v "${DATA_DIR}:/a0/usr" \
  agent0ai/agent-zero

The -d flag runs the container in detached mode. The Web UI will be available at http://localhost:50080.

Configuration via Environment Variables

Agent Zero supports automated configuration through environment variables prefixed with A0_SET_. These variables populate settings.json on first container start, eliminating manual UI configuration:

docker run -d \
  -p 50080:80 \
  -v "$HOME/agent-zero-data:/a0/usr" \
  -e A0_SET_chat_model_provider=anthropic \
  -e A0_SET_chat_model_name=claude-3-5-sonnet-20241022 \
  -e A0_SET_chat_model_ctx_length=200000 \
  agent0ai/agent-zero

Available configuration keys correspond to settings in the web interface. Refer to the installation documentation for the complete list of configurable parameters.

Using Docker Compose for Agent Zero

The repository includes a docker-compose.yml file in docker/run/ for simplified deployment:

# File: docker/run/docker-compose.yml

services:
  agent-zero:
    image: agent0ai/agent-zero:latest
    container_name: agent-zero
    volumes:
      - ./agent-zero:/a0/usr
    ports:
      - "50080:80"

Deploy using:

docker compose -f docker/run/docker-compose.yml up -d

Important: Only mount /a0/usr for persistence. Do not mount the entire /a0 directory, as this can interfere with application files and break future upgrades.

Key Configuration Files and Scripts

Understanding these source files helps with advanced customization and troubleshooting:

File	Purpose
DockerfileLocal	Defines the runtime image build, exposes ports 22, 80, and 9000-9009, and sets initialize.sh as the entry point
docker/run/fs/ins/*.sh	Installation scripts executed during image build: pre_install.sh, install_A0.sh, install_additional.sh, install_A02.sh, post_install.sh
initialize.py	Called by initialize.sh to boot supervisord and start the Web UI, SSH daemon, SearXNG, and Tunnel API
docker/run/docker-compose.yml	Official Docker Compose configuration for persistent deployments

Summary

Setting up Agent Zero with Docker requires pulling the agent0ai/agent-zero image and running it with a volume mount to /a0/usr for data persistence. The container exposes port 80 for the web interface and supports automated configuration through A0_SET_ prefixed environment variables. For production deployments, use the provided docker-compose.yml from the repository's docker/run/ directory rather than manual docker run commands.

• Pull the image: docker pull agent0ai/agent-zero
• Persist data: Mount host directory to /a0/usr
• Configure automatically: Use A0_SET_* environment variables
• Deploy with Compose: Use docker/run/docker-compose.yml

Frequently Asked Questions

What is the official Docker image for Agent Zero?

The official Docker image is agent0ai/agent-zero, available on Docker Hub. This image bundles the complete Agent Zero framework including the backend, web UI, and optional tools like SearXNG search and voice processing. The image is built from DockerfileLocal in the repository root, which uses agent0ai/agent-zero-base:latest as its foundation.

How do I persist data when running Agent Zero in Docker?

Mount a host directory to the container's /a0/usr path using the -v flag. This directory stores all user data including settings, memories, projects, and uploaded files. For example: -v "$HOME/agent-zero-data:/a0/usr". Never mount the entire /a0 directory, as this can break future upgrades by overwriting application files.

Can I configure Agent Zero settings through environment variables?

Yes, Agent Zero supports automated configuration via environment variables prefixed with A0_SET_. When the container starts for the first time, these variables populate the settings.json file. For example, setting -e A0_SET_chat_model_provider=anthropic configures the chat model provider without manual UI interaction. This feature is handled by the initialization scripts in docker/run/fs/ins/.

Which ports need to be exposed when running Agent Zero?

The official image exposes ports 22 (SSH daemon for remote code execution), 80 (Web UI), and 9000-9009 (auxiliary services including the Tunnel API and SearXNG). In most deployments, you only need to map port 80 to a host port (e.g., -p 50080:80). The SSH and auxiliary ports are optional depending on whether you use remote execution or additional search features.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}