AgentZero Docker Setup

A simple Docker Compose configuration for running AgentZero locally.

Prerequisites

• Docker and Docker Compose installed
• Anthropic API key

Quick Start

1. Clone or download this directory

2. Set your API key

   Option 1: Using .env file (recommended)

   Copy the example file and add your API key:

   cp .env.example .env

   Then edit .env and replace your-api-key-here with your actual Anthropic API key.

   Option 2: Using environment variable

   Export the API key in your shell:

   export ANTHROPIC_API_KEY=your-api-key-here

3. Start the container

   docker compose up -d

4. Access AgentZero

   Open your browser and navigate to: http://localhost:50502

Configuration

Ports

The default port mapping is 50502:80. To change the host port, modify the ports section:

ports:
  - "YOUR_PORT:80"

Volumes

Host Path	Container Path	Description
./agent-zero-data	/a0	AgentZero persistent data (settings, history, etc.)
Custom paths	/srv/*	Additional mounted directories for file access

Adding Custom Directories

To give AgentZero access to additional directories, add more volume mounts:

volumes:
  - ./agent-zero-data:/a0
  - /path/to/your/project:/srv/project-name

Environment Variables

Variable	Required	Description
ANTHROPIC_API_KEY	Yes	Your Anthropic API key for Claude models

Commands

Command	Description
docker compose up -d	Start AgentZero in background
docker compose down	Stop and remove the container
docker compose logs -f	View logs in real-time
docker compose restart	Restart the container
docker compose pull	Update to the latest image

Data Persistence

All AgentZero data is stored in ./agent-zero-data. This includes:

• User settings
• Conversation history
• Custom tools and prompts

To reset AgentZero, stop the container and remove this directory:

docker compose down
rm -rf agent-zero-data

Security Note

Important: Never commit your API key to version control.

This setup uses a .env file which is already included in .gitignore. The docker-compose.yml references the API key via ${ANTHROPIC_API_KEY} environment variable.

For production deployments, consider using Docker secrets or a secrets management system.

Troubleshooting

Container won't start

Check logs for errors:

docker compose logs agent-zero

Port already in use

Change the host port in docker-compose.yml or stop the conflicting service.

Permission issues

Ensure Docker has access to mounted directories on your system.

Resources

• AgentZero GitHub
• AgentZero Documentation
• Docker Hub