Part 2 of 6

Docker Installation & Core Deployment

Install Docker, clone the Agent Zero repository, configure your environment, and launch the web interface for the first time.

12 minutes

Docker + Python

With your VPS secured and ready, it's time to install Docker and deploy Agent Zero. By the end of this guide, you'll have the Agent Zero web interface running and accessible, with a basic understanding of the framework's structure.

Install Docker

Agent Zero runs inside Docker containers for isolation and consistency. We'll install Docker Engine directly from Docker's official repository to get the latest stable version.

Add Docker's GPG Key and Repository

Terminal

# Install prerequisites
sudo apt install ca-certificates curl gnupg -y

# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add the repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Install Docker Engine

Terminal

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

Configure Docker for Non-Root Access

Add your user to the docker group:

Terminal

sudo usermod -aG docker $USER

Log out and back in for the group change to take effect:

Terminal

exit
ssh -p 2222 agentzero@your-server-ip

Verify Docker Installation

Terminal

docker --version
docker compose version
docker run hello-world

Clean up the test container:

Terminal

docker rm $(docker ps -aq --filter ancestor=hello-world)
docker rmi hello-world

Install Python Dependencies

Agent Zero requires Python 3.10 or newer. Ubuntu 24.04 includes Python 3.12 by default, but we need to install pip and venv:

Terminal

sudo apt install python3-pip python3-venv python3-full -y

Verify the installation:

Terminal

python3 --version

Clone Agent Zero

Create a directory for Agent Zero and clone the repository:

Terminal

cd ~
git clone https://github.com/frdel/agent-zero.git
cd agent-zero

Check the current version:

Terminal

git describe --tags --always

Directory Structure

Understanding Agent Zero's layout helps when customizing behavior or troubleshooting:

File Structure

agent-zero/
├── docker/                  # Docker configuration files
│   ├── Dockerfile
│   └── compose.yml
├── prompts/                 # Agent behavior definitions
│   └── default/
│       ├── agent.system.md  # Main system prompt
│       ├── agent.tools.md   # Tool instructions
│       └── ...
├── python/
│   ├── tools/               # Built-in tool implementations
│   ├── helpers/             # Utility functions
│   └── api/                 # API server code
├── knowledge/               # Custom knowledge base storage
├── memory/                  # Persistent agent memory
├── work_dir/                # Agent's working directory
├── run_ui.py                # Web UI launcher
├── run_cli.py               # CLI launcher
├── example.env              # Environment template
└── requirements.txt         # Python dependencies

prompts/default/ — Edit these files to change how agents think, communicate, and use tools.

memory/ — Where agents store learned information between sessions. Back this up to preserve agent knowledge.

knowledge/ — Import documents here to give agents access to custom information.

work_dir/ — The agent's scratch space for creating files, running scripts, and storing outputs.

Environment Configuration

Agent Zero uses environment variables for configuration. Copy the example file:

Terminal

cp example.env .env
nano .env

API Keys (Choose Your LLM Provider)

For this guide, we'll start with OpenAI since it requires no additional setup:

.env

# OpenAI Configuration
API_KEY_OPENAI=sk-your-openai-api-key-here
CHAT_MODEL_OPENAI=gpt-4o
UTILITY_MODEL_OPENAI=gpt-4o-mini
EMBEDDING_MODEL_OPENAI=text-embedding-3-small

Default Provider Selection

.env

# Set default models
CHAT_MODEL_DEFAULT=gpt-4o
UTILITY_MODEL_DEFAULT=gpt-4o-mini
EMBEDDING_MODEL_DEFAULT=text-embedding-3-small

Web UI Settings

.env

# Web UI Configuration
WEB_UI_HOST=0.0.0.0
WEB_UI_PORT=5000

Setting WEB_UI_HOST=0.0.0.0 allows external access. Use 127.0.0.1 for SSH tunnel only.

Docker Settings

.env

# Docker execution environment
CODE_EXEC_DOCKER_ENABLED=true
CODE_EXEC_DOCKER_NAME=agent-zero-exe
CODE_EXEC_DOCKER_IMAGE=frdel/agent-zero-exe:latest
CODE_EXEC_DOCKER_PORTS=80:80,443:443

Set Up Python Virtual Environment

Terminal

python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Open the Firewall Port

Terminal

sudo ufw allow 5000/tcp comment 'Agent Zero Web UI'
sudo ufw reload

Launch Agent Zero

With configuration complete, start the web interface:

Terminal

python run_ui.py

You should see output similar to:

Output

Initializing Agent Zero...
Loading configuration from .env
Starting web server on 0.0.0.0:5000
Agent Zero UI is ready!
Open http://your-server-ip:5000 in your browser

First Conversation

Test with a simple prompt:

Chat Input

Create a Python script that prints the current date and time, then run it.

Watch Agent Zero write the code, execute it in the Docker container, and return the output—all autonomously.

Understanding the Interface

Chat Panel — The main conversation area showing messages, tool usage, and code execution.

Agent Indicator — Shows which agent is active. Agent 0 is primary; subordinates appear for subtasks.

Settings — Access model selection, temperature, and behavior toggles.

Terminal — Real-time view of commands executing in the Docker container.

CLI Mode

For terminal-based interaction or automation:

Terminal

python run_cli.py

Exit CLI mode with Ctrl+C or by typing exit.

Running as a Background Service

Option 1: Screen Session

Terminal

# Install screen if needed
sudo apt install screen -y

# Start a named session
screen -S agentzero

# Activate venv and start
cd ~/agent-zero
source venv/bin/activate
python run_ui.py

# Detach with Ctrl+A, then D
# Reattach later with: screen -r agentzero

Option 2: Systemd Service

Create a service file:

Terminal

sudo nano /etc/systemd/system/agent-zero.service

/etc/systemd/system/agent-zero.service

[Unit]
Description=Agent Zero AI Framework
After=network.target docker.service
Requires=docker.service

[Service]
Type=simple
User=agentzero
WorkingDirectory=/home/agentzero/agent-zero
Environment="PATH=/home/agentzero/agent-zero/venv/bin:/usr/local/bin:/usr/bin:/bin"
ExecStart=/home/agentzero/agent-zero/venv/bin/python run_ui.py
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start the service:

Terminal

sudo systemctl daemon-reload
sudo systemctl enable agent-zero
sudo systemctl start agent-zero

Check status and logs:

Terminal

sudo systemctl status agent-zero
journalctl -u agent-zero -f

Troubleshooting

"Connection refused" when accessing web UI

Terminal

sudo ss -tlnp | grep 5000
sudo ufw status | grep 5000

"API key not found" or authentication errors

Terminal

grep API_KEY .env

Ensure there are no extra spaces or quotes around the key.

Docker permission denied

Terminal

groups $USER

If docker isn't listed, re-run usermod and log out/in.

Python module not found errors

Terminal

which python
# Should show: /home/agentzero/agent-zero/venv/bin/python
source ~/agent-zero/venv/bin/activate

What's Next?

Agent Zero is now running with cloud-based LLM inference. In Part 3: LLM Provider Configuration, we'll explore:

Configuring alternative cloud providers (Anthropic, Groq, Google)
Installing Ollama for local LLM inference
Choosing the right models for different tasks
Hybrid configurations that balance cost and capability

Local LLM hosting is particularly compelling for privacy-focused deployments and eliminating per-token API costs—exactly the kind of self-hosting advantage that makes VPS deployment worthwhile.

Part 1: Introduction Part 3: LLM Configuration