Self-Hosting Guide

Deploy Agentbase on your own infrastructure with full control over your data and configuration.

Quick Install

# Clone the repository
git clone https://github.com/AgentaFlow/agentbase.git
cd agentbase
 
# Run the installer
npx @agentbase/installer install

The installer will walk you through:

Database configuration (PostgreSQL, MongoDB, Redis)
Admin account setup
AI provider API key configuration
Environment file generation

Using the CLI

System Requirements Check

npx @agentbase/installer check

This verifies:

Node.js >= 20.0.0
pnpm >= 9
Python >= 3.10
Docker and Docker Compose (optional)
Git
Sufficient RAM (>= 2 GB) and CPU cores (>= 2)

Installation

# Interactive (recommended)
npx @agentbase/installer install
 
# Non-interactive with flags
npx @agentbase/installer install \
  --non-interactive \
  --db-host localhost \
  --db-port 5432 \
  --db-name agentbase \
  --admin-email admin@example.com \
  --admin-password mysecurepassword \
  --port 3000

Status Check

npx @agentbase/installer status

Shows version, running services, and health of all components.

Updates

# Update to latest (with automatic backup)
npx @agentbase/installer update
 
# Update to specific version
npx @agentbase/installer update --version 1.2.0
 
# Skip backup
npx @agentbase/installer update --no-backup

Docker Deployment

Development

docker compose up -d

This starts PostgreSQL, MongoDB, and Redis. The application services run on the host.

Production

docker compose -f docker-compose.prod.yml up -d

This starts all services (including the app) in containers with production settings.

Environment Variables

Variable	Description	Default
`NODE_ENV`	Environment (`development`/`production`)	`development`
`APP_PORT`	Core API port	`3001`
`APP_URL`	Core API public URL	`http://localhost:3001`
`FRONTEND_URL`	Frontend URL (used for CORS)	`http://localhost:3000`
PostgreSQL
`POSTGRES_HOST`	PostgreSQL host	`localhost`
`POSTGRES_PORT`	PostgreSQL port	`5432`
`POSTGRES_USER`	PostgreSQL username	`agentbase`
`POSTGRES_PASSWORD`	PostgreSQL password	—
`POSTGRES_DB`	PostgreSQL database name	`agentbase`
`RUN_MIGRATIONS`	Auto-run migrations on startup	`false`
MongoDB
`MONGO_URI`	MongoDB connection string	`mongodb://agentbase:agentbase_dev@localhost:27017/agentbase?authSource=admin`
Redis
`REDIS_HOST`	Redis host	`localhost`
`REDIS_PORT`	Redis port	`6379`
`REDIS_PASSWORD`	Redis password	—
JWT
`JWT_SECRET`	JWT signing secret	— (auto-generated by installer)
`JWT_EXPIRATION`	JWT access token expiry	`24h`
`JWT_REFRESH_SECRET`	Refresh token signing secret	— (auto-generated by installer)
`JWT_REFRESH_EXPIRATION`	Refresh token expiry	`7d`
AI Providers
`OPENAI_API_KEY`	OpenAI API key	—
`ANTHROPIC_API_KEY`	Anthropic API key	—
`GEMINI_API_KEY`	Google Gemini API key	—
`HUGGINGFACE_API_KEY`	HuggingFace Inference API key	—
`DEFAULT_AI_PROVIDER`	Default provider when none specified	`openai`
`AI_SERVICE_URL`	Internal URL of the Python AI microservice	`http://localhost:8000`
OAuth (optional)
`GITHUB_CLIENT_ID`	GitHub OAuth App client ID	—
`GITHUB_CLIENT_SECRET`	GitHub OAuth App client secret	—
`GITHUB_CALLBACK_URL`	GitHub OAuth callback URL	`http://localhost:3001/api/auth/github/callback`
`GOOGLE_CLIENT_ID`	Google OAuth client ID	—
`GOOGLE_CLIENT_SECRET`	Google OAuth client secret	—
`GOOGLE_CALLBACK_URL`	Google OAuth callback URL	`http://localhost:3001/api/auth/google/callback`
Security
`ENCRYPTION_KEY`	64-hex-char AES-256-GCM key for BYOK provider key encryption	— (generate: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`)
Stripe (billing)
`STRIPE_SECRET_KEY`	Stripe secret key (`sk_live_...` / `sk_test_...`)	—
`STRIPE_WEBHOOK_SECRET`	Stripe webhook signing secret	—
`STRIPE_PUBLISHABLE_KEY`	Stripe publishable key	—
`STRIPE_METERED_PRICE_ID`	Stripe metered price ID for token overage billing	—
Email (optional)
`SMTP_HOST`	SMTP server host	—
`SMTP_PORT`	SMTP port	`587`
`SMTP_USER`	SMTP username	—
`SMTP_PASSWORD`	SMTP password	—
`EMAIL_FROM`	Default from address	`noreply@agentbase.dev`
File Uploads (S3)
`S3_BUCKET`	S3 bucket name	—
`S3_REGION`	S3 region	`us-east-1`
`S3_ACCESS_KEY`	S3 access key ID	—
`S3_SECRET_KEY`	S3 secret access key	—
`S3_ENDPOINT`	Custom S3-compatible endpoint (e.g. MinIO)	—
Custom Domains
`PLATFORM_DOMAIN`	Apex domain for custom domain routing	`custom.agentbase.dev`
Misc
`ENABLE_SWAGGER`	Enable Swagger UI in production	`false`

SSL/TLS Setup

For production deployments, use the included Nginx configuration:

# Run the SSL setup script
bash deploy/scripts/ssl-setup.sh your-domain.com

This configures Let's Encrypt certificates via certbot.

Backup & Restore

# Create a backup
bash deploy/scripts/backup.sh
 
# Backups include:
# - PostgreSQL database dump
# - MongoDB database dump
# - .env configuration
# - Uploaded files

Getting Started Overview