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

> Easily install Agent Zero with Docker using our official image. Follow this guide to deploy the complete AI framework in minutes and start building intelligent agents.

- Repository: [Agent Zero/agent-zero](https://github.com/agent0ai/agent-zero)
- Tags: how-to-guide
- Published: 2026-02-23

---

**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`](https://github.com/agent0ai/agent-zero/blob/main/pre_install.sh), [`install_A0.sh`](https://github.com/agent0ai/agent-zero/blob/main/install_A0.sh), [`install_additional.sh`](https://github.com/agent0ai/agent-zero/blob/main/install_additional.sh), [`install_A02.sh`](https://github.com/agent0ai/agent-zero/blob/main/install_A02.sh), and [`post_install.sh`](https://github.com/agent0ai/agent-zero/blob/main/post_install.sh).

### Initialization and Service Management

When the container starts, [`initialize.sh`](https://github.com/agent0ai/agent-zero/blob/main/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:

```bash
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:

```bash
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:

```bash

# 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`](https://github.com/agent0ai/agent-zero/blob/main/settings.json) on first container start, eliminating manual UI configuration:

```bash
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`](https://github.com/agent0ai/agent-zero/blob/main/docker-compose.yml) file in `docker/run/` for simplified deployment:

```yaml

# 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:

```bash
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`](https://github.com/agent0ai/agent-zero/blob/main/initialize.sh) as the entry point |
| `docker/run/fs/ins/*.sh` | Installation scripts executed during image build: [`pre_install.sh`](https://github.com/agent0ai/agent-zero/blob/main/pre_install.sh), [`install_A0.sh`](https://github.com/agent0ai/agent-zero/blob/main/install_A0.sh), [`install_additional.sh`](https://github.com/agent0ai/agent-zero/blob/main/install_additional.sh), [`install_A02.sh`](https://github.com/agent0ai/agent-zero/blob/main/install_A02.sh), [`post_install.sh`](https://github.com/agent0ai/agent-zero/blob/main/post_install.sh) |
| [`initialize.py`](https://github.com/agent0ai/agent-zero/blob/main/initialize.py) | Called by [`initialize.sh`](https://github.com/agent0ai/agent-zero/blob/main/initialize.sh) to boot supervisord and start the Web UI, SSH daemon, SearXNG, and Tunnel API |
| [`docker/run/docker-compose.yml`](https://github.com/agent0ai/agent-zero/blob/main/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`](https://github.com/agent0ai/agent-zero/blob/main/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`](https://github.com/agent0ai/agent-zero/blob/main/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`](https://github.com/agent0ai/agent-zero/blob/main/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.