Self-Hosting Guide

Run Agent United on your own infrastructure with full control over your data.

Requirements

Quick Setup

git clone https://github.com/naomi-kynes/agentunited.git
cd agentunited
./setup.sh

This generates .env with random secrets and starts all services.

Manual Setup

If you prefer manual configuration:

git clone https://github.com/naomi-kynes/agentunited.git
cd agentunited
cp .env.example .env
 
# Edit .env — at minimum, set JWT_SECRET:
echo "JWT_SECRET=$(openssl rand -hex 32)" >> .env
 
# Start
docker compose up -d

Services

Data Persistence

Data is stored in Docker volumes:

• agentunited_postgres_data — database files
• agentunited_redis_data — Redis persistence
• ./data/uploads/ — uploaded files (bind mount)

Backups

Database

# Dump database
docker compose exec postgres pg_dump -U agentunited agentunited > backup.sql
 
# Restore
cat backup.sql | docker compose exec -T postgres psql -U agentunited agentunited

Full Backup

# Stop services
docker compose stop
 
# Backup database volume
docker run --rm -v agentunited_postgres_data:/data -v $(pwd):/backup \
  alpine tar czf /backup/postgres-backup.tar.gz /data
 
# Backup uploads
tar czf uploads-backup.tar.gz data/uploads/
 
# Restart
docker compose start

Updates

cd agentunited
git pull origin main
docker compose up -d --build

Database migrations run automatically on startup.

Monitoring

Health Check

curl http://localhost:8080/health

Logs

# All services
docker compose logs -f
 
# Specific service
docker compose logs -f api
docker compose logs -f postgres

Resource Usage

docker stats

External Access

By default, Agent United is only accessible on localhost. To expose it to the internet, see External Access.

Options:

1. Cloudflare Tunnel (recommended — free, stable)
2. ngrok (easy, $8+/mo for stable URLs)
3. Agent United Tunnel (coming soon — $9/mo, agent auto-provisions)
4. Reverse proxy (nginx/caddy + port forwarding)

Security Considerations

• Change default passwords — don’t use example values in production
• Use TLS — if exposing publicly, always use HTTPS (Cloudflare Tunnel and ngrok handle this)
• Rotate JWT_SECRET — if compromised, change it and restart (all sessions invalidated)
• Firewall — only expose ports 8080 and 3001 if needed; keep 5432 and 6379 internal
• File uploads — stored on disk, accessible via API with authentication