Skip to main content

​
Self-Hosted Deployment

Run Xagent on your own infrastructure for full control, data privacy, and customization.

​
Why Self-Host?

Data Privacy

Keep all data on your infrastructure

Customization

Modify and extend as needed

Compliance

Meet regulatory requirements

Cost Control

Predictable infrastructure costs

​
Deployment Options

​
Docker Compose (Simplest)

Best for: Small teams, testing, initial deployment 
git clone https://github.com/xorbitsai/xagent.git
cd xagent
cp example.env .env
# Edit .env with your configuration
docker compose up -d
Requirements:
  • Docker Engine 20+
  • Docker Compose 2+
  • 4GB RAM minimum
  • 20GB disk space
What’s Included:
  • PostgreSQL database
  • Xagent backend
  • Next.js frontend
  • nginx reverse proxy

​
Manual Deployment

Best for: Custom setups, specific requirements See Installation for step-by-step instructions.

​
Production Checklist

​
Security

​
Database

​
Observability

​
Scalability

​
Cloud Deployment Guides

​
AWS

​
Google Cloud

​
Azure

​
Backup & Recovery

​
Database Backups

# Automated backups (recommended)
# Configure in your managed database service

# Manual backup (PostgreSQL)
pg_dump -U xagent -h localhost xagent > backup.sql

# Restore
psql -U xagent -h localhost xagent < backup.sql

# Manual backup (SQLite)
cp xagent.db xagent.db.backup

​
Configuration Backups

# Backup environment configuration
cp .env .env.backup

# Backup custom configurations
tar -czf config-backup.tar.gz custom/

​
Memory Store Backups

If using LanceDB for memory: 
# Backup memory store
tar -czf memory-backup.tar.gz memory_store/

​
Performance Tuning

​
Database

  • Enable connection pooling
  • Add indexes for common queries
  • Regular vacuum and analyze (PostgreSQL)
  • Monitor slow queries

​
Application

  • Increase CONCURRENT for parallel image processing
  • Tune memory store settings
  • Enable gzip compression
  • Use CDN for static assets

​
Infrastructure

  • Use SSD storage
  • Sufficient memory for database and models
  • Network optimization within VPC

​
Troubleshooting

​
Database Connection Issues

Check:
  • DATABASE_URL is correctly formatted
  • Database is running and accessible
  • Network allows connection
  • Credentials are correct
Solutions:
  • Verify database is running: docker ps
  • Check database logs: docker logs postgres
  • Test connection: psql $DATABASE_URL

​
Memory Issues

Check:
  • Available system memory
  • Concurrent operations limit
  • Memory store size
Solutions:
  • Reduce CONCURRENT value
  • Use in-memory store instead of LanceDB
  • Increase available RAM
  • Clear memory store cache

​
API Key Errors

Check:
  • API keys are set in .env
  • Keys have necessary permissions
  • Keys are valid and not expired
Solutions:
  • Verify .env file is loaded
  • Regenerate expired keys
  • Check API key permissions
  • Verify BASE_URL if using custom endpoint

​
Next Steps