| 1 | # Agent Zero Installation Guide |
| 2 | |
| 3 | > **Purpose:** Step-by-step guide for deploying Agent Zero instances on VPS/dedicated servers |
| 4 | > **Author:** Auto-generated from deployment experience |
| 5 | > **Last Updated:** December 21 2025 |
| 6 | > **Compatibility:** Docker-capable Linux servers (AlmaLinux, CentOS, Rocky, Ubuntu, Debian) |
| 7 | |
| 8 | --- |
| 9 | |
| 10 | ## Table of Contents |
| 11 | |
| 12 | 1. [Prerequisites](#prerequisites) |
| 13 | 2. [Docker Installation](#docker-installation) |
| 14 | 3. [Agent Zero Container Deployment](#agent-zero-container-deployment) |
| 15 | 4. [Apache Reverse Proxy Configuration](#apache-reverse-proxy-configuration) |
| 16 | 5. [SSL/TLS Configuration](#ssltls-configuration) |
| 17 | 6. [Authentication Setup](#authentication-setup) |
| 18 | 7. [Domain & DNS Setup](#domain-dns-setup) |
| 19 | 8. [Verification & Testing](#verification-testing) |
| 20 | 9. [Troubleshooting](#troubleshooting) |
| 21 | 10. [Maintenance & Updates](#maintenance-updates) |
| 22 | 11. [Quick Reference](#quick-reference) |
| 23 | |
| 24 | --- |
| 25 | |
| 26 | ## Prerequisites |
| 27 | |
| 28 | ### Server Requirements |
| 29 | |
| 30 | | Requirement | Minimum | Recommended | |
| 31 | |-------------|---------|-------------| |
| 32 | | **RAM** | 2 GB | 4+ GB | |
| 33 | | **Storage** | 20 GB | 50+ GB | |
| 34 | | **CPU** | 1 vCPU | 2+ vCPU | |
| 35 | | **OS** | Linux (64-bit) | AlmaLinux 9, Ubuntu 22.04+ | |
| 36 | | **Network** | Static IP | Dedicated IP with reverse DNS | |
| 37 | |
| 38 | ### Required Access |
| 39 | |
| 40 | - Root or sudo access to the server |
| 41 | - SSH access (preferably on non-standard port) |
| 42 | - Domain/subdomain with DNS control |
| 43 | - SSL certificate (Let's Encrypt or commercial) |
| 44 | |
| 45 | ### Software Dependencies |
| 46 | |
| 47 | - Docker Engine 24.0+ |
| 48 | - Apache 2.4+ with mod_proxy, mod_proxy_http, mod_proxy_wstunnel, mod_ssl, mod_rewrite |
| 49 | - curl, git (optional) |
| 50 | |
| 51 | --- |
| 52 | |
| 53 | ## Docker Installation |
| 54 | |
| 55 | > [!NOTE] |
| 56 | > For detailed Docker installation instructions and alternative methods, see the [Linux Installation section](installation.md#linux-installation) in the main installation guide. |
| 57 | |
| 58 | ### Method A: Debian/Ubuntu Systems |
| 59 | |
| 60 | ```bash |
| 61 | # Update package index |
| 62 | apt-get update |
| 63 | |
| 64 | # Install prerequisites |
| 65 | apt-get install -y ca-certificates curl gnupg |
| 66 | |
| 67 | # Add Docker's official GPG key |
| 68 | install -m 0755 -d /etc/apt/keyrings |
| 69 | curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg |
| 70 | chmod a+r /etc/apt/keyrings/docker.gpg |
| 71 | |
| 72 | # Set up repository |
| 73 | 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 |
| 74 | |
| 75 | # Install Docker |
| 76 | apt-get update |
| 77 | apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin |
| 78 | |
| 79 | # Start and enable Docker |
| 80 | systemctl enable docker |
| 81 | systemctl start docker |
| 82 | ``` |
| 83 | |
| 84 | ### Method B: AlmaLinux/Rocky/CentOS/RHEL Systems |
| 85 | |
| 86 | ```bash |
| 87 | # Install required packages |
| 88 | dnf -y install dnf-plugins-core |
| 89 | |
| 90 | # Add Docker repository (use CentOS repo for AlmaLinux/Rocky) |
| 91 | dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo |
| 92 | |
| 93 | # Install Docker |
| 94 | dnf -y install docker-ce docker-ce-cli containerd.io docker-compose-plugin |
| 95 | |
| 96 | # Start and enable Docker |
| 97 | systemctl enable docker |
| 98 | systemctl start docker |
| 99 | ``` |
| 100 | |
| 101 | ### Method C: Generic (Convenience Script) |
| 102 | |
| 103 | > ⚠️ **Note:** May not work on all distributions (e.g., AlmaLinux) |
| 104 | |
| 105 | ```bash |
| 106 | curl -fsSL https://get.docker.com -o get-docker.sh |
| 107 | sh get-docker.sh |
| 108 | systemctl enable docker |
| 109 | systemctl start docker |
| 110 | ``` |
| 111 | |
| 112 | ### Verify Docker Installation |
| 113 | |
| 114 | ```bash |
| 115 | docker --version |
| 116 | docker run hello-world |
| 117 | ``` |
| 118 | |
| 119 | --- |
| 120 | |
| 121 | ## Agent Zero Container Deployment |
| 122 | |
| 123 | ### Step 1: Create Directory Structure |
| 124 | |
| 125 | ```bash |
| 126 | # Choose your installation path |
| 127 | A0_NAME="a0-instance" # Change this to your instance name |
| 128 | A0_PATH="/opt/${A0_NAME}" |
| 129 | |
| 130 | # Create directories |
| 131 | mkdir -p ${A0_PATH} |
| 132 | mkdir -p ${A0_PATH}/work_dir |
| 133 | mkdir -p ${A0_PATH}/memory |
| 134 | mkdir -p ${A0_PATH}/logs |
| 135 | ``` |
| 136 | |
| 137 | ### Step 2: Create Environment Configuration |
| 138 | |
| 139 | ```bash |
| 140 | # Create .env file with authentication |
| 141 | cat > ${A0_PATH}/.env << 'EOF' |
| 142 | # Agent Zero Configuration |
| 143 | # Authentication (REQUIRED for web access) |
| 144 | AUTH_LOGIN=your_username_here |
| 145 | AUTH_PASSWORD=your_secure_password_here |
| 146 | |
| 147 | # Optional: Additional configuration |
| 148 | # See Agent Zero documentation for all options |
| 149 | EOF |
| 150 | ``` |
| 151 | |
| 152 | > ⚠️ **CRITICAL:** `AUTH_LOGIN` is the **username**, not a boolean! |
| 153 | > - ✅ Correct: `AUTH_LOGIN=admin` |
| 154 | > - ❌ Wrong: `AUTH_LOGIN=true` |
| 155 | |
| 156 | ### Step 3: Choose Host Port |
| 157 | |
| 158 | | Port | Use Case | |
| 159 | |------|----------| |
| 160 | | `50080` | Standard/recommended for reverse proxy setups | |
| 161 | | `50081`, `50082`... | Additional instances on same server | |
| 162 | | `80` | Direct access (not recommended for production) | |
| 163 | |
| 164 | ### Step 4: Pull and Run Container |
| 165 | |
| 166 | ```bash |
| 167 | # Set variables |
| 168 | A0_NAME="a0-instance" |
| 169 | A0_PATH="/opt/${A0_NAME}" |
| 170 | A0_PORT="50080" |
| 171 | |
| 172 | # Pull latest image |
| 173 | docker pull agent0ai/agent-zero:latest |
| 174 | |
| 175 | # Run container |
| 176 | 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 |
| 177 | ``` |
| 178 | |
| 179 | ### Step 5: Verify Container |
| 180 | |
| 181 | ```bash |
| 182 | # Check container is running |
| 183 | docker ps | grep ${A0_NAME} |
| 184 | |
| 185 | # Check logs |
| 186 | docker logs ${A0_NAME} |
| 187 | |
| 188 | # Test local access |
| 189 | curl -I http://127.0.0.1:${A0_PORT}/ |
| 190 | ``` |
| 191 | |
| 192 | Expected response: `HTTP/1.1 302 FOUND` with `Location: /login` (if auth enabled) |
| 193 | |
| 194 | --- |
| 195 | |
| 196 | ## Apache Reverse Proxy Configuration |
| 197 | |
| 198 | ### Required Apache Modules |
| 199 | |
| 200 | ```bash |
| 201 | # Debian/Ubuntu |
| 202 | a2enmod proxy proxy_http proxy_wstunnel ssl rewrite headers |
| 203 | systemctl restart apache2 |
| 204 | |
| 205 | # AlmaLinux/CentOS (usually pre-loaded) |
| 206 | httpd -M | grep -E "proxy|rewrite|ssl" |
| 207 | ``` |
| 208 | |
| 209 | ### Configuration for Standard Apache (Debian/Ubuntu) |
| 210 | |
| 211 | Create `/etc/apache2/sites-available/a0-instance.conf`: |
| 212 | |
| 213 | ```apache |
| 214 | # Agent Zero Reverse Proxy Configuration |
| 215 | # Instance: a0-instance |
| 216 | # Domain: a0.example.com |
| 217 | |
| 218 | # HTTP - Redirect to HTTPS |
| 219 | <VirtualHost *:80> |
| 220 | ServerName a0.example.com |
| 221 | ServerAlias www.a0.example.com |
| 222 | |
| 223 | RewriteEngine On |
| 224 | RewriteCond %{HTTPS} off |
| 225 | RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301] |
| 226 | </VirtualHost> |
| 227 | |
| 228 | # HTTPS - Proxy to Container |
| 229 | <VirtualHost *:443> |
| 230 | ServerName a0.example.com |
| 231 | ServerAlias www.a0.example.com |
| 232 | ServerAdmin webmaster@example.com |
| 233 | |
| 234 | # SSL Configuration |
| 235 | SSLEngine on |
| 236 | SSLCertificateFile /path/to/certificate.crt |
| 237 | SSLCertificateKeyFile /path/to/private.key |
| 238 | SSLCertificateChainFile /path/to/chain.crt |
| 239 | |
| 240 | # Proxy Configuration |
| 241 | ProxyPreserveHost On |
| 242 | ProxyPass / http://127.0.0.1:50080/ |
| 243 | ProxyPassReverse / http://127.0.0.1:50080/ |
| 244 | |
| 245 | # WebSocket Support (Required for real-time features) |
| 246 | RewriteEngine On |
| 247 | RewriteCond %{HTTP:Upgrade} websocket [NC] |
| 248 | RewriteCond %{HTTP:Connection} upgrade [NC] |
| 249 | RewriteRule ^/?(.*) ws://127.0.0.1:50080/$1 [P,L] |
| 250 | |
| 251 | # Logging |
| 252 | ErrorLog ${APACHE_LOG_DIR}/a0-instance.error.log |
| 253 | CustomLog ${APACHE_LOG_DIR}/a0-instance.access.log combined |
| 254 | </VirtualHost> |
| 255 | ``` |
| 256 | |
| 257 | Enable and restart: |
| 258 | |
| 259 | ```bash |
| 260 | a2ensite a0-instance.conf |
| 261 | apache2ctl configtest |
| 262 | systemctl reload apache2 |
| 263 | ``` |
| 264 | |
| 265 | ### Configuration for DirectAdmin Apache (AlmaLinux/CentOS) |
| 266 | |
| 267 | #### Option A: Use httpd-includes.conf (Recommended) |
| 268 | |
| 269 | Edit `/etc/httpd/conf/extra/httpd-includes.conf`: |
| 270 | |
| 271 | ```apache |
| 272 | # Agent Zero Proxy Configuration |
| 273 | # Instance: a0-instance |
| 274 | # Domain: a0.example.com |
| 275 | # Note: Use specific IP, not wildcards, for DirectAdmin compatibility |
| 276 | |
| 277 | <VirtualHost YOUR_SERVER_IP:80> |
| 278 | ServerName a0.example.com |
| 279 | ServerAlias www.a0.example.com |
| 280 | |
| 281 | RewriteEngine On |
| 282 | RewriteCond %{HTTPS} off |
| 283 | RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301] |
| 284 | </VirtualHost> |
| 285 | |
| 286 | <VirtualHost YOUR_SERVER_IP:443> |
| 287 | ServerName a0.example.com |
| 288 | ServerAlias www.a0.example.com |
| 289 | ServerAdmin webmaster@example.com |
| 290 | |
| 291 | SSLEngine on |
| 292 | # DirectAdmin SSL cert paths (adjust user and domain) |
| 293 | SSLCertificateFile /usr/local/directadmin/data/users/USERNAME/domains/example.com.cert.combined |
| 294 | SSLCertificateKeyFile /usr/local/directadmin/data/users/USERNAME/domains/example.com.key |
| 295 | |
| 296 | ProxyPreserveHost On |
| 297 | ProxyPass / http://127.0.0.1:50080/ |
| 298 | ProxyPassReverse / http://127.0.0.1:50080/ |
| 299 | |
| 300 | # WebSocket Support |
| 301 | RewriteEngine On |
| 302 | RewriteCond %{HTTP:Upgrade} websocket [NC] |
| 303 | RewriteCond %{HTTP:Connection} upgrade [NC] |
| 304 | RewriteRule ^/?(.*) ws://127.0.0.1:50080/$1 [P,L] |
| 305 | |
| 306 | ErrorLog /var/log/httpd/domains/a0.example.com.error.log |
| 307 | CustomLog /var/log/httpd/domains/a0.example.com.access.log combined |
| 308 | </VirtualHost> |
| 309 | ``` |
| 310 | |
| 311 | > ⚠️ **Important for DirectAdmin:** |
| 312 | > - Use **specific IP address** (e.g., `192.168.1.100:443`), not `*:443` |
| 313 | > - IP-bound vhosts take precedence over DirectAdmin's vhosts |
| 314 | > - SSL certs are in `/usr/local/directadmin/data/users/USERNAME/domains/` |
| 315 | |
| 316 | #### Option B: Standalone conf.d file |
| 317 | |
| 318 | If `/etc/httpd/conf.d/` is included in your Apache config: |
| 319 | |
| 320 | ```bash |
| 321 | # Check if conf.d is included |
| 322 | grep 'conf.d' /etc/httpd/conf/httpd.conf |
| 323 | |
| 324 | # If not, add before directadmin-vhosts.conf include: |
| 325 | sed -i '/Include conf\/extra\/directadmin-vhosts.conf/i Include conf.d/*.conf' /etc/httpd/conf/httpd.conf |
| 326 | |
| 327 | # Create config |
| 328 | mkdir -p /etc/httpd/conf.d |
| 329 | cat > /etc/httpd/conf.d/httpd-vhosts-a0.conf << 'EOF' |
| 330 | # Your vhost config here (same as Option A) |
| 331 | EOF |
| 332 | ``` |
| 333 | |
| 334 | ### Verify and Restart Apache |
| 335 | |
| 336 | ```bash |
| 337 | # Test configuration |
| 338 | httpd -t # AlmaLinux/CentOS |
| 339 | apachectl -t # Alternative |
| 340 | apache2ctl -t # Debian/Ubuntu |
| 341 | |
| 342 | # Restart |
| 343 | systemctl restart httpd # AlmaLinux/CentOS |
| 344 | systemctl restart apache2 # Debian/Ubuntu |
| 345 | ``` |
| 346 | |
| 347 | --- |
| 348 | |
| 349 | ## SSL/TLS Configuration |
| 350 | |
| 351 | ### Option A: Let's Encrypt with Certbot |
| 352 | |
| 353 | ```bash |
| 354 | # Install Certbot |
| 355 | # Debian/Ubuntu: |
| 356 | apt-get install certbot python3-certbot-apache |
| 357 | |
| 358 | # AlmaLinux/CentOS: |
| 359 | dnf install certbot python3-certbot-apache |
| 360 | |
| 361 | # Obtain certificate |
| 362 | certbot --apache -d a0.example.com -d www.a0.example.com |
| 363 | |
| 364 | # Auto-renewal (usually automatic, but verify) |
| 365 | certbot renew --dry-run |
| 366 | ``` |
| 367 | |
| 368 | ### Option B: DirectAdmin Auto-SSL |
| 369 | |
| 370 | If using DirectAdmin, SSL is typically managed automatically: |
| 371 | |
| 372 | 1. Create domain/subdomain in DirectAdmin |
| 373 | 2. Enable "SSL" for the domain |
| 374 | 3. DirectAdmin will obtain Let's Encrypt certificate |
| 375 | 4. Certs stored in `/usr/local/directadmin/data/users/USERNAME/domains/` |
| 376 | |
| 377 | ### Option C: Manual/Commercial Certificates |
| 378 | |
| 379 | Place certificates in secure location: |
| 380 | |
| 381 | ```bash |
| 382 | mkdir -p /etc/ssl/a0 |
| 383 | chmod 700 /etc/ssl/a0 |
| 384 | |
| 385 | # Copy your certificates |
| 386 | cp certificate.crt /etc/ssl/a0/ |
| 387 | cp private.key /etc/ssl/a0/ |
| 388 | cp chain.crt /etc/ssl/a0/ # if applicable |
| 389 | |
| 390 | chmod 600 /etc/ssl/a0/* |
| 391 | ``` |
| 392 | |
| 393 | --- |
| 394 | |
| 395 | ## Authentication Setup |
| 396 | |
| 397 | ### Understanding A0 Authentication Variables |
| 398 | |
| 399 | | Variable | Purpose | Example | |
| 400 | |----------|---------|--------| |
| 401 | | `AUTH_LOGIN` | The **username** for login | `AUTH_LOGIN=admin` | |
| 402 | | `AUTH_PASSWORD` | The **password** for login | `AUTH_PASSWORD=SecurePass123!` | |
| 403 | |
| 404 | > ⚠️ **Common Mistake:** `AUTH_LOGIN` is the username, **not** a boolean to enable auth! |
| 405 | |
| 406 | ### Setting Up Authentication |
| 407 | |
| 408 | ```bash |
| 409 | # Edit .env file |
| 410 | vi /opt/a0-instance/.env |
| 411 | |
| 412 | # Add/update these lines: |
| 413 | AUTH_LOGIN=your_username |
| 414 | AUTH_PASSWORD=your_secure_password |
| 415 | |
| 416 | # Restart container to apply |
| 417 | docker restart a0-instance |
| 418 | ``` |
| 419 | |
| 420 | ### Password Requirements |
| 421 | |
| 422 | - Minimum 8 characters recommended |
| 423 | - Special characters are supported (properly escaped) |
| 424 | - Avoid these characters in passwords: `' " \` $ \` (or escape carefully) |
| 425 | |
| 426 | ### Disabling Authentication (Not Recommended) |
| 427 | |
| 428 | To disable authentication (local/dev use only): |
| 429 | |
| 430 | ```bash |
| 431 | # Remove or comment out both lines in .env: |
| 432 | # AUTH_LOGIN= |
| 433 | # AUTH_PASSWORD= |
| 434 | |
| 435 | docker restart a0-instance |
| 436 | ``` |
| 437 | |
| 438 | --- |
| 439 | |
| 440 | ## Domain & DNS Setup |
| 441 | |
| 442 | ### DNS Configuration |
| 443 | |
| 444 | Create an A record pointing to your server: |
| 445 | |
| 446 | | Type | Name | Value | TTL | |
| 447 | |------|------|-------|-----| |
| 448 | | A | a0 | YOUR_SERVER_IP | 300 | |
| 449 | | A | www.a0 | YOUR_SERVER_IP | 300 | |
| 450 | |
| 451 | ### DirectAdmin Subdomain Setup |
| 452 | |
| 453 | 1. Log into DirectAdmin |
| 454 | 2. Navigate to: **Domain Setup** → Select domain → **Subdomain Management** |
| 455 | 3. Create subdomain (e.g., `a0`) |
| 456 | 4. Note: You'll override the DocumentRoot with Apache proxy config |
| 457 | |
| 458 | ### Verify DNS Propagation |
| 459 | |
| 460 | ```bash |
| 461 | # Check DNS resolution |
| 462 | dig a0.example.com +short |
| 463 | nslookup a0.example.com |
| 464 | |
| 465 | # Should return your server IP |
| 466 | ``` |
| 467 | |
| 468 | --- |
| 469 | |
| 470 | ## Verification & Testing |
| 471 | |
| 472 | ### Step-by-Step Verification Checklist |
| 473 | |
| 474 | ```bash |
| 475 | # 1. Verify Docker container is running |
| 476 | docker ps | grep a0-instance |
| 477 | |
| 478 | # 2. Check container logs for errors |
| 479 | docker logs a0-instance --tail 50 |
| 480 | |
| 481 | # 3. Test local container access |
| 482 | curl -I http://127.0.0.1:50080/ |
| 483 | # Expected: HTTP/1.1 302 FOUND, Location: /login |
| 484 | |
| 485 | # 4. Test Apache config |
| 486 | httpd -t # or apache2ctl -t |
| 487 | |
| 488 | # 5. Check Apache is proxying correctly |
| 489 | curl -I http://127.0.0.1:80 -H "Host: a0.example.com" |
| 490 | curl -Ik https://127.0.0.1:443 -H "Host: a0.example.com" |
| 491 | |
| 492 | # 6. Test external HTTPS access |
| 493 | curl -I https://a0.example.com/ |
| 494 | # Expected: HTTP/2 302 with Location: /login |
| 495 | |
| 496 | # 7. Test login page loads |
| 497 | curl -s https://a0.example.com/login | grep -i "<title>" |
| 498 | # Expected: <title>Login - Agent Zero</title> |
| 499 | ``` |
| 500 | |
| 501 | ### WebSocket Verification |
| 502 | |
| 503 | ```bash |
| 504 | # Install wscat if needed |
| 505 | npm install -g wscat |
| 506 | |
| 507 | # Test WebSocket connection |
| 508 | wscat -c wss://a0.example.com/ws |
| 509 | ``` |
| 510 | |
| 511 | --- |
| 512 | |
| 513 | ## Troubleshooting |
| 514 | |
| 515 | ### Issue: "Invalid Credentials" on Login |
| 516 | |
| 517 | **Cause:** Incorrect `.env` configuration |
| 518 | |
| 519 | **Fix:** |
| 520 | ```bash |
| 521 | # Verify .env inside container |
| 522 | docker exec a0-instance cat /a0/.env |
| 523 | |
| 524 | # Ensure format is: |
| 525 | # AUTH_LOGIN=username (NOT AUTH_LOGIN=true) |
| 526 | # AUTH_PASSWORD=password |
| 527 | |
| 528 | # Restart after fixing |
| 529 | docker restart a0-instance |
| 530 | ``` |
| 531 | |
| 532 | ### Issue: 403 Forbidden |
| 533 | |
| 534 | **Cause:** DirectAdmin vhost overriding custom proxy config |
| 535 | |
| 536 | **Fix:** |
| 537 | ```bash |
| 538 | # Check vhost order |
| 539 | httpd -S 2>&1 | grep your-domain |
| 540 | |
| 541 | # Ensure custom config loads BEFORE directadmin-vhosts.conf |
| 542 | # Use specific IP binding (e.g., 192.168.1.1:443) not wildcards (*:443) |
| 543 | |
| 544 | # Restart Apache |
| 545 | systemctl restart httpd |
| 546 | ``` |
| 547 | |
| 548 | ### Issue: 502 Bad Gateway |
| 549 | |
| 550 | **Cause:** Container not running or wrong port |
| 551 | |
| 552 | **Fix:** |
| 553 | ```bash |
| 554 | # Check container status |
| 555 | docker ps -a | grep a0-instance |
| 556 | |
| 557 | # If stopped, check logs |
| 558 | docker logs a0-instance |
| 559 | |
| 560 | # Restart container |
| 561 | docker start a0-instance |
| 562 | |
| 563 | # Verify port binding |
| 564 | netstat -tlnp | grep 50080 |
| 565 | ``` |
| 566 | |
| 567 | ### Issue: 504 Gateway Timeout |
| 568 | |
| 569 | **Cause:** Container overloaded or unresponsive |
| 570 | |
| 571 | **Fix:** |
| 572 | ```bash |
| 573 | # Check container resource usage |
| 574 | docker stats a0-instance --no-stream |
| 575 | |
| 576 | # Restart container |
| 577 | docker restart a0-instance |
| 578 | |
| 579 | # Check for memory issues |
| 580 | free -h |
| 581 | ``` |
| 582 | |
| 583 | ### Issue: WebSocket Connection Failed |
| 584 | |
| 585 | **Cause:** Missing WebSocket proxy rules |
| 586 | |
| 587 | **Fix:** |
| 588 | Ensure these lines are in your vhost config: |
| 589 | |
| 590 | ```apache |
| 591 | RewriteEngine On |
| 592 | RewriteCond %{HTTP:Upgrade} websocket [NC] |
| 593 | RewriteCond %{HTTP:Connection} upgrade [NC] |
| 594 | RewriteRule ^/?(.*) ws://127.0.0.1:50080/$1 [P,L] |
| 595 | ``` |
| 596 | |
| 597 | ### Issue: Container Won't Start |
| 598 | |
| 599 | **Cause:** Port conflict or Docker issue |
| 600 | |
| 601 | **Fix:** |
| 602 | ```bash |
| 603 | # Check what's using the port |
| 604 | netstat -tlnp | grep 50080 |
| 605 | |
| 606 | # Remove conflicting container |
| 607 | docker rm -f conflicting-container |
| 608 | |
| 609 | # Check Docker daemon |
| 610 | systemctl status docker |
| 611 | journalctl -u docker --since "1 hour ago" |
| 612 | ``` |
| 613 | |
| 614 | ### Issue: Changes to .env Not Taking Effect |
| 615 | |
| 616 | **Cause:** Container needs restart to reload env |
| 617 | |
| 618 | **Fix:** |
| 619 | ```bash |
| 620 | docker restart a0-instance |
| 621 | |
| 622 | # Verify env is loaded |
| 623 | docker exec a0-instance cat /a0/.env |
| 624 | ``` |
| 625 | |
| 626 | --- |
| 627 | |
| 628 | ## Maintenance & Updates |
| 629 | |
| 630 | ### Updating Agent Zero |
| 631 | |
| 632 | ```bash |
| 633 | # Pull latest image |
| 634 | docker pull agent0ai/agent-zero:latest |
| 635 | |
| 636 | # Stop and remove old container (data persists in volumes) |
| 637 | docker stop a0-instance |
| 638 | docker rm a0-instance |
| 639 | |
| 640 | # Recreate with same settings |
| 641 | 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 |
| 642 | ``` |
| 643 | |
| 644 | ### Backup Strategy |
| 645 | |
| 646 | ```bash |
| 647 | # Backup all instance data |
| 648 | tar -czvf a0-backup-$(date +%Y%m%d).tar.gz /opt/a0-instance/ |
| 649 | |
| 650 | # Key items to backup: |
| 651 | # - /opt/a0-instance/.env (configuration) |
| 652 | # - /opt/a0-instance/memory/ (agent memories) |
| 653 | # - /opt/a0-instance/work_dir/ (working files) |
| 654 | ``` |
| 655 | |
| 656 | ### Monitoring |
| 657 | |
| 658 | ```bash |
| 659 | # Check container health |
| 660 | docker ps --format "table {{.Names}} {{.Status}} {{.Ports}}" |
| 661 | |
| 662 | # View recent logs |
| 663 | docker logs --tail 100 -f a0-instance |
| 664 | |
| 665 | # Resource usage |
| 666 | docker stats a0-instance |
| 667 | ``` |
| 668 | |
| 669 | ### Docker Cleanup |
| 670 | |
| 671 | ```bash |
| 672 | # Remove unused images |
| 673 | docker image prune -f |
| 674 | |
| 675 | # Remove all unused Docker resources |
| 676 | docker system prune -f |
| 677 | ``` |
| 678 | |
| 679 | --- |
| 680 | |
| 681 | ## Quick Reference |
| 682 | |
| 683 | ### Essential Commands |
| 684 | |
| 685 | ```bash |
| 686 | # Container Management |
| 687 | docker start a0-instance |
| 688 | docker stop a0-instance |
| 689 | docker restart a0-instance |
| 690 | docker logs a0-instance |
| 691 | docker exec -it a0-instance bash |
| 692 | |
| 693 | # Apache Management |
| 694 | systemctl restart httpd # RHEL/AlmaLinux |
| 695 | systemctl restart apache2 # Debian/Ubuntu |
| 696 | httpd -t # Test config |
| 697 | |
| 698 | # Quick Diagnostics |
| 699 | docker ps | grep a0 |
| 700 | curl -I https://your-domain.com/login |
| 701 | ``` |
| 702 | |
| 703 | ### Standard Paths |
| 704 | |
| 705 | | Component | Path | |
| 706 | |-----------|----- | |
| 707 | | Instance Data | `/opt/a0-instance/` | |
| 708 | | Environment File | `/opt/a0-instance/.env` | |
| 709 | | Memory Storage | `/opt/a0-instance/memory/` | |
| 710 | | Work Directory | `/opt/a0-instance/work_dir/` | |
| 711 | | Apache Config (Standard) | `/etc/apache2/sites-available/` | |
| 712 | | Apache Config (DirectAdmin) | `/etc/httpd/conf/extra/httpd-includes.conf` | |
| 713 | | DirectAdmin SSL Certs | `/usr/local/directadmin/data/users/USER/domains/` | |
| 714 | |
| 715 | ### Standard Ports |
| 716 | |
| 717 | | Port | Purpose | |
| 718 | |------|---------| |
| 719 | | 50080 | First A0 instance | |
| 720 | | 50081 | Second A0 instance | |
| 721 | | 50082 | Third A0 instance | |
| 722 | | 80 | HTTP (redirect to HTTPS) | |
| 723 | | 443 | HTTPS (main access) | |
| 724 | |
| 725 | ### .env Template |
| 726 | |
| 727 | ```bash |
| 728 | # Agent Zero Configuration Template |
| 729 | # Copy and customize for each instance |
| 730 | |
| 731 | # Authentication (REQUIRED for production) |
| 732 | AUTH_LOGIN=your_username |
| 733 | AUTH_PASSWORD=your_secure_password |
| 734 | |
| 735 | # Optional: Additional settings |
| 736 | # Refer to Agent Zero documentation for all options |
| 737 | ``` |
| 738 | |
| 739 | --- |
| 740 | |
| 741 | ## Appendix: Multi-Instance Setup |
| 742 | |
| 743 | For running multiple A0 instances on the same server: |
| 744 | |
| 745 | ```bash |
| 746 | # Instance 1: a0-primary on port 50080 |
| 747 | mkdir -p /opt/a0-primary |
| 748 | # ... create .env, run container on port 50080 |
| 749 | |
| 750 | # Instance 2: a0-dev on port 50081 |
| 751 | mkdir -p /opt/a0-dev |
| 752 | # ... create .env, run container on port 50081 |
| 753 | |
| 754 | # Instance 3: a0-backup on port 50082 |
| 755 | mkdir -p /opt/a0-backup |
| 756 | # ... create .env, run container on port 50082 |
| 757 | ``` |
| 758 | |
| 759 | Each instance needs: |
| 760 | - Unique container name |
| 761 | - Unique host port |
| 762 | - Separate data directory |
| 763 | - Separate domain/subdomain |
| 764 | - Separate Apache vhost config |
| 765 | |
| 766 | --- |
| 767 | |
| 768 | *This guide comes from successful Agent Zero deployments across DirectAdmin and standard Linux environments.* |
| 769 | |
| 770 | Contributed by @hurtdidit in the A0 Community. |