agent-zero/docs/setup/vps-deployment.md

Agent Zero Installation Guide

Purpose: Step-by-step guide for deploying Agent Zero instances on VPS/dedicated servers
Author: Auto-generated from deployment experience
Last Updated: December 21 2025
Compatibility: Docker-capable Linux servers (AlmaLinux, CentOS, Rocky, Ubuntu, Debian)

---

Table of Contents

1. Prerequisites
2. Docker Installation
3. Agent Zero Container Deployment
4. Apache Reverse Proxy Configuration
5. SSL/TLS Configuration
6. Authentication Setup
7. Domain & DNS Setup
8. Verification & Testing
9. Troubleshooting
10. Maintenance & Updates
11. Quick Reference

---

Prerequisites

Server Requirements

Requirement	Minimum	Recommended
RAM	2 GB	4+ GB
Storage	20 GB	50+ GB
CPU	1 vCPU	2+ vCPU
OS	Linux (64-bit)	AlmaLinux 9, Ubuntu 22.04+
Network	Static IP	Dedicated IP with reverse DNS

Required Access

• Root or sudo access to the server
• SSH access (preferably on non-standard port)
• Domain/subdomain with DNS control
• SSL certificate (Let's Encrypt or commercial)

Software Dependencies

• Docker Engine 24.0+
• Apache 2.4+ with mod_proxy, mod_proxy_http, mod_proxy_wstunnel, mod_ssl, mod_rewrite
• curl, git (optional)

---

Docker Installation

Note

For detailed Docker installation instructions and alternative methods, see the Linux Installation section in the main installation guide.

Method A: Debian/Ubuntu Systems

# Update package index
apt-get update

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

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

# Set up 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" |   tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Start and enable Docker
systemctl enable docker
systemctl start docker

Method B: AlmaLinux/Rocky/CentOS/RHEL Systems

# Install required packages
dnf -y install dnf-plugins-core

# Add Docker repository (use CentOS repo for AlmaLinux/Rocky)
dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# Install Docker
dnf -y install docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Start and enable Docker
systemctl enable docker
systemctl start docker

Method C: Generic (Convenience Script)

⚠️ Note: May not work on all distributions (e.g., AlmaLinux)

curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
systemctl enable docker
systemctl start docker

Verify Docker Installation

docker --version
docker run hello-world

---

Agent Zero Container Deployment

Step 1: Create Directory Structure

# Choose your installation path
A0_NAME="a0-instance"  # Change this to your instance name
A0_PATH="/opt/${A0_NAME}"

# Create directories
mkdir -p ${A0_PATH}
mkdir -p ${A0_PATH}/work_dir
mkdir -p ${A0_PATH}/memory
mkdir -p ${A0_PATH}/logs

Step 2: Create Environment Configuration

# Create .env file with authentication
cat > ${A0_PATH}/.env << 'EOF'
# Agent Zero Configuration
# Authentication (REQUIRED for web access)
AUTH_LOGIN=your_username_here
AUTH_PASSWORD=your_secure_password_here

# Optional: Additional configuration
# See Agent Zero documentation for all options
EOF

⚠️ CRITICAL: AUTH_LOGIN is the username, not a boolean!

• ✅ Correct: AUTH_LOGIN=admin
• ❌ Wrong: AUTH_LOGIN=true

Step 3: Choose Host Port

Port	Use Case
50080	Standard/recommended for reverse proxy setups
50081, 50082...	Additional instances on same server
80	Direct access (not recommended for production)

Step 4: Pull and Run Container

# Set variables
A0_NAME="a0-instance"
A0_PATH="/opt/${A0_NAME}"
A0_PORT="50080"

# Pull latest image
docker pull agent0ai/agent-zero:latest

# Run container
docker run -d   --name ${A0_NAME}   --restart unless-stopped   -p ${A0_PORT}:80   -v ${A0_PATH}/.env:/a0/.env   -v ${A0_PATH}/usr:/a0/usr   agent0ai/agent-zero:latest

Step 5: Verify Container

# Check container is running
docker ps | grep ${A0_NAME}

# Check logs
docker logs ${A0_NAME}

# Test local access
curl -I http://127.0.0.1:${A0_PORT}/

Expected response: HTTP/1.1 302 FOUND with Location: /login (if auth enabled)

---

Apache Reverse Proxy Configuration

Required Apache Modules

# Debian/Ubuntu
a2enmod proxy proxy_http proxy_wstunnel ssl rewrite headers
systemctl restart apache2

# AlmaLinux/CentOS (usually pre-loaded)
httpd -M | grep -E "proxy|rewrite|ssl"

Configuration for Standard Apache (Debian/Ubuntu)

Create /etc/apache2/sites-available/a0-instance.conf:

# Agent Zero Reverse Proxy Configuration
# Instance: a0-instance
# Domain: a0.example.com

# HTTP - Redirect to HTTPS
<VirtualHost *:80>
    ServerName a0.example.com
    ServerAlias www.a0.example.com

    RewriteEngine On
    RewriteCond %{HTTPS} off
    RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
</VirtualHost>

# HTTPS - Proxy to Container
<VirtualHost *:443>
    ServerName a0.example.com
    ServerAlias www.a0.example.com
    ServerAdmin webmaster@example.com

    # SSL Configuration
    SSLEngine on
    SSLCertificateFile /path/to/certificate.crt
    SSLCertificateKeyFile /path/to/private.key
    SSLCertificateChainFile /path/to/chain.crt

    # Proxy Configuration
    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:50080/
    ProxyPassReverse / http://127.0.0.1:50080/

    # WebSocket Support (Required for real-time features)
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule ^/?(.*) ws://127.0.0.1:50080/$1 [P,L]

    # Logging
    ErrorLog ${APACHE_LOG_DIR}/a0-instance.error.log
    CustomLog ${APACHE_LOG_DIR}/a0-instance.access.log combined
</VirtualHost>

Enable and restart:

a2ensite a0-instance.conf
apache2ctl configtest
systemctl reload apache2

Configuration for DirectAdmin Apache (AlmaLinux/CentOS)

Option A: Use httpd-includes.conf (Recommended)

Edit /etc/httpd/conf/extra/httpd-includes.conf:

# Agent Zero Proxy Configuration
# Instance: a0-instance
# Domain: a0.example.com
# Note: Use specific IP, not wildcards, for DirectAdmin compatibility

<VirtualHost YOUR_SERVER_IP:80>
    ServerName a0.example.com
    ServerAlias www.a0.example.com

    RewriteEngine On
    RewriteCond %{HTTPS} off
    RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
</VirtualHost>

<VirtualHost YOUR_SERVER_IP:443>
    ServerName a0.example.com
    ServerAlias www.a0.example.com
    ServerAdmin webmaster@example.com

    SSLEngine on
    # DirectAdmin SSL cert paths (adjust user and domain)
    SSLCertificateFile /usr/local/directadmin/data/users/USERNAME/domains/example.com.cert.combined
    SSLCertificateKeyFile /usr/local/directadmin/data/users/USERNAME/domains/example.com.key

    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:50080/
    ProxyPassReverse / http://127.0.0.1:50080/

    # WebSocket Support
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule ^/?(.*) ws://127.0.0.1:50080/$1 [P,L]

    ErrorLog /var/log/httpd/domains/a0.example.com.error.log
    CustomLog /var/log/httpd/domains/a0.example.com.access.log combined
</VirtualHost>

⚠️ Important for DirectAdmin:

• Use specific IP address (e.g., 192.168.1.100:443), not *:443
• IP-bound vhosts take precedence over DirectAdmin's vhosts
• SSL certs are in /usr/local/directadmin/data/users/USERNAME/domains/

Option B: Standalone conf.d file

If /etc/httpd/conf.d/ is included in your Apache config:

# Check if conf.d is included
grep 'conf.d' /etc/httpd/conf/httpd.conf

# If not, add before directadmin-vhosts.conf include:
sed -i '/Include conf\/extra\/directadmin-vhosts.conf/i Include conf.d/*.conf' /etc/httpd/conf/httpd.conf

# Create config
mkdir -p /etc/httpd/conf.d
cat > /etc/httpd/conf.d/httpd-vhosts-a0.conf << 'EOF'
# Your vhost config here (same as Option A)
EOF

Verify and Restart Apache

# Test configuration
httpd -t          # AlmaLinux/CentOS
apachectl -t      # Alternative
apache2ctl -t     # Debian/Ubuntu

# Restart
systemctl restart httpd   # AlmaLinux/CentOS
systemctl restart apache2 # Debian/Ubuntu

---

SSL/TLS Configuration

Option A: Let's Encrypt with Certbot

# Install Certbot
# Debian/Ubuntu:
apt-get install certbot python3-certbot-apache

# AlmaLinux/CentOS:
dnf install certbot python3-certbot-apache

# Obtain certificate
certbot --apache -d a0.example.com -d www.a0.example.com

# Auto-renewal (usually automatic, but verify)
certbot renew --dry-run

Option B: DirectAdmin Auto-SSL

If using DirectAdmin, SSL is typically managed automatically:

1. Create domain/subdomain in DirectAdmin
2. Enable "SSL" for the domain
3. DirectAdmin will obtain Let's Encrypt certificate
4. Certs stored in /usr/local/directadmin/data/users/USERNAME/domains/

Option C: Manual/Commercial Certificates

Place certificates in secure location:

mkdir -p /etc/ssl/a0
chmod 700 /etc/ssl/a0

# Copy your certificates
cp certificate.crt /etc/ssl/a0/
cp private.key /etc/ssl/a0/
cp chain.crt /etc/ssl/a0/  # if applicable

chmod 600 /etc/ssl/a0/*

---

Authentication Setup

Understanding A0 Authentication Variables

Variable	Purpose	Example
AUTH_LOGIN	The username for login	AUTH_LOGIN=admin
AUTH_PASSWORD	The password for login	AUTH_PASSWORD=SecurePass123!

⚠️ Common Mistake: AUTH_LOGIN is the username, not a boolean to enable auth!

Setting Up Authentication

# Edit .env file
vi /opt/a0-instance/.env

# Add/update these lines:
AUTH_LOGIN=your_username
AUTH_PASSWORD=your_secure_password

# Restart container to apply
docker restart a0-instance

Password Requirements

• Minimum 8 characters recommended
• Special characters are supported (properly escaped)
• Avoid these characters in passwords: ' " \ $ ` (or escape carefully)

Disabling Authentication (Not Recommended)

To disable authentication (local/dev use only):

# Remove or comment out both lines in .env:
# AUTH_LOGIN=
# AUTH_PASSWORD=

docker restart a0-instance

---

Domain & DNS Setup

DNS Configuration

Create an A record pointing to your server:

Type	Name	Value	TTL
A	a0	YOUR_SERVER_IP	300
A	www.a0	YOUR_SERVER_IP	300

DirectAdmin Subdomain Setup

1. Log into DirectAdmin
2. Navigate to: Domain Setup → Select domain → Subdomain Management
3. Create subdomain (e.g., a0)
4. Note: You'll override the DocumentRoot with Apache proxy config

Verify DNS Propagation

# Check DNS resolution
dig a0.example.com +short
nslookup a0.example.com

# Should return your server IP

---

Verification & Testing

Step-by-Step Verification Checklist

# 1. Verify Docker container is running
docker ps | grep a0-instance

# 2. Check container logs for errors
docker logs a0-instance --tail 50

# 3. Test local container access
curl -I http://127.0.0.1:50080/
# Expected: HTTP/1.1 302 FOUND, Location: /login

# 4. Test Apache config
httpd -t   # or apache2ctl -t

# 5. Check Apache is proxying correctly
curl -I http://127.0.0.1:80 -H "Host: a0.example.com"
curl -Ik https://127.0.0.1:443 -H "Host: a0.example.com"

# 6. Test external HTTPS access
curl -I https://a0.example.com/
# Expected: HTTP/2 302 with Location: /login

# 7. Test login page loads
curl -s https://a0.example.com/login | grep -i "<title>"
# Expected: <title>Login - Agent Zero</title>

WebSocket Verification

# Install wscat if needed
npm install -g wscat

# Test WebSocket connection
wscat -c wss://a0.example.com/ws

---

Troubleshooting

Issue: "Invalid Credentials" on Login

Cause: Incorrect .env configuration

Fix:

# Verify .env inside container
docker exec a0-instance cat /a0/.env

# Ensure format is:
# AUTH_LOGIN=username  (NOT AUTH_LOGIN=true)
# AUTH_PASSWORD=password

# Restart after fixing
docker restart a0-instance

Issue: 403 Forbidden

Cause: DirectAdmin vhost overriding custom proxy config

Fix:

# Check vhost order
httpd -S 2>&1 | grep your-domain

# Ensure custom config loads BEFORE directadmin-vhosts.conf
# Use specific IP binding (e.g., 192.168.1.1:443) not wildcards (*:443)

# Restart Apache
systemctl restart httpd

Issue: 502 Bad Gateway

Cause: Container not running or wrong port

Fix:

# Check container status
docker ps -a | grep a0-instance

# If stopped, check logs
docker logs a0-instance

# Restart container
docker start a0-instance

# Verify port binding
netstat -tlnp | grep 50080

Issue: 504 Gateway Timeout

Cause: Container overloaded or unresponsive

Fix:

# Check container resource usage
docker stats a0-instance --no-stream

# Restart container
docker restart a0-instance

# Check for memory issues
free -h

Issue: WebSocket Connection Failed

Cause: Missing WebSocket proxy rules

Fix: Ensure these lines are in your vhost config:

RewriteEngine On
RewriteCond %{HTTP:Upgrade} websocket [NC]
RewriteCond %{HTTP:Connection} upgrade [NC]
RewriteRule ^/?(.*) ws://127.0.0.1:50080/$1 [P,L]

Issue: Container Won't Start

Cause: Port conflict or Docker issue

Fix:

# Check what's using the port
netstat -tlnp | grep 50080

# Remove conflicting container
docker rm -f conflicting-container

# Check Docker daemon
systemctl status docker
journalctl -u docker --since "1 hour ago"

Issue: Changes to .env Not Taking Effect

Cause: Container needs restart to reload env

Fix:

docker restart a0-instance

# Verify env is loaded
docker exec a0-instance cat /a0/.env

---

Maintenance & Updates

Updating Agent Zero

# Pull latest image
docker pull agent0ai/agent-zero:latest

# Stop and remove old container (data persists in volumes)
docker stop a0-instance
docker rm a0-instance

# Recreate with same settings
docker run -d   --name a0-instance   --restart unless-stopped   -p 50080:80   -v /opt/a0-instance/.env:/a0/.env   -v /opt/a0-instance/usr:/a0/usr   -v /opt/agent-zero:latest

Backup Strategy

# Backup all instance data
tar -czvf a0-backup-$(date +%Y%m%d).tar.gz /opt/a0-instance/

# Key items to backup:
# - /opt/a0-instance/.env (configuration)
# - /opt/a0-instance/memory/ (agent memories)
# - /opt/a0-instance/work_dir/ (working files)

Monitoring

# Check container health
docker ps --format "table {{.Names}}	{{.Status}}	{{.Ports}}"

# View recent logs
docker logs --tail 100 -f a0-instance

# Resource usage
docker stats a0-instance

Docker Cleanup

# Remove unused images
docker image prune -f

# Remove all unused Docker resources
docker system prune -f

---

Quick Reference

Essential Commands

# Container Management
docker start a0-instance
docker stop a0-instance
docker restart a0-instance
docker logs a0-instance
docker exec -it a0-instance bash

# Apache Management  
systemctl restart httpd    # RHEL/AlmaLinux
systemctl restart apache2  # Debian/Ubuntu
httpd -t                   # Test config

# Quick Diagnostics
docker ps | grep a0
curl -I https://your-domain.com/login

Standard Paths

Component	Path
Instance Data	/opt/a0-instance/
Environment File	/opt/a0-instance/.env
Memory Storage	/opt/a0-instance/memory/
Work Directory	/opt/a0-instance/work_dir/
Logs	/opt/a0-instance/logs/
Apache Config (Standard)	/etc/apache2/sites-available/
Apache Config (DirectAdmin)	/etc/httpd/conf/extra/httpd-includes.conf
DirectAdmin SSL Certs	/usr/local/directadmin/data/users/USER/domains/

Standard Ports

Port	Purpose
50080	First A0 instance
50081	Second A0 instance
50082	Third A0 instance
80	HTTP (redirect to HTTPS)
443	HTTPS (main access)

.env Template

# Agent Zero Configuration Template
# Copy and customize for each instance

# Authentication (REQUIRED for production)
AUTH_LOGIN=your_username
AUTH_PASSWORD=your_secure_password

# Optional: Additional settings
# Refer to Agent Zero documentation for all options

---

Appendix: Multi-Instance Setup

For running multiple A0 instances on the same server:

# Instance 1: a0-primary on port 50080
mkdir -p /opt/a0-primary
# ... create .env, run container on port 50080

# Instance 2: a0-dev on port 50081  
mkdir -p /opt/a0-dev
# ... create .env, run container on port 50081

# Instance 3: a0-backup on port 50082
mkdir -p /opt/a0-backup
# ... create .env, run container on port 50082

Each instance needs:

• Unique container name
• Unique host port
• Separate data directory
• Separate domain/subdomain
• Separate Apache vhost config

---

This guide comes from successful Agent Zero deployments across DirectAdmin and standard Linux environments.

Contributed by @hurtdidit in the A0 Community.