Deployment

Q: What's the recommended way to deploy AI OS?

PM2 + Nginx. Run sudo bash deploy/install-vps.sh yourdomain.com on a fresh Ubuntu 22.04+ VPS, and it configures the UFW firewall, installs Node.js 20 LTS, installs PM2 with startup configuration, installs Nginx with the reverse proxy config, installs Certbot for Let's Encrypt TLS, and creates a dedicated aios system user.

Q: Can I deploy AI OS with Docker instead?

Yes, with docker compose up -d. The setup uses node:20-alpine with a non-root user, a health check endpoint, volume mounts for .magent/ and logs/ persistence, and port binding to 127.0.0.1:3000 so Nginx fronts external traffic. Docker is optional; the PM2 + Nginx path is simpler and recommended for most deployments.

Q: How is TLS handled?

Run sudo certbot --nginx -d yourdomain.com. Certbot auto-renews certificates, and Nginx is configured to redirect HTTP to HTTPS.

Q: What environment variables must be set in production?

All STRIPE_* variables must use live keys (prefix sk_live_), and NODE_ENV=production must be set.

AI OS offers two supported production deployment paths: PM2 + Nginx (recommended) or Docker. This guide provides VPS provisioning, TLS setup, and a production hardening checklist.

Option 1 — PM2 + Nginx (Recommended)

The recommended production deployment uses PM2 for process management and Nginx as a reverse proxy with TLS termination.

VPS Provisioning

Run the automated install script on a fresh Ubuntu 22.04+ VPS:

sudo bash deploy/install-vps.sh yourdomain.com

This script automatically:

Configures UFW firewall (allows SSH, HTTP, HTTPS only)
Installs Node.js 20 LTS via NodeSource
Installs PM2 globally with startup configuration
Installs Nginx and deploys the reverse proxy config
Installs Certbot for Let's Encrypt TLS certificates
Creates a dedicated aios system user

Application Setup

cd /opt/ai-os
npm install --production
cp .env.example .env
nano .env   # Configure all required variables

pm2 start ecosystem.config.js --env production
pm2 save

TLS Certificate

sudo certbot --nginx -d yourdomain.com

Certbot auto-renews certificates. Nginx is configured to redirect HTTP to HTTPS.

Option 2 — Docker

docker compose up -d

The Docker setup uses node:20-alpine with:

Non-root user for security
Health check endpoint monitoring
Volume mounts for .magent/ and logs/ persistence
Port binding to 127.0.0.1:3000 (Nginx fronts external traffic)

Note: Docker is optional. The PM2 + Nginx path is simpler and recommended for most deployments.

Nginx Configuration

The included deploy/nginx.conf provides:

TLS termination — SSL certificates via Certbot
WebSocket upgrade — Proper Upgrade and Connection headers for WS
Static caching — 7 days for CSS/JS, 30 days for images and fonts
Rate limiting — 10 req/s burst with nodelay
Security headers — X-Frame-Options, X-Content-Type-Options, Referrer-Policy
Sensitive path blocking — Returns 404 for /.magent/, /.claude/, /.env

PM2 Configuration

The ecosystem.config.js configures:

Auto-restart — Restarts on crash with exponential backoff
Memory limit — 512 MB max, restarts if exceeded
Log rotation — Timestamped logs with daily rotation
Environment separation — Distinct configs for development and production
Watch mode — Disabled in production, enabled in development

Production Hardening Checklist

Item	Status
Helmet CSP headers	Built-in
CORS origin restriction	Via `CORS_ORIGIN` env var
Response compression (gzip)	Built-in
Request logging (morgan)	Built-in (file in prod, console in dev)
API rate limiting	120/min general, 10/min heavy
Input validation	Built-in on all POST endpoints
Bearer token auth	Via `API_TOKEN` env var
Session cookie auth	HTTP-only, 30-day expiry
Stripe webhook signature verification	Built-in
Graceful shutdown (SIGTERM/SIGINT)	Built-in
Uncaught exception handler	Built-in
State auto-save with debounce	Built-in
WebSocket heartbeat (30s)	Built-in
robots.txt (blocks /api, /.magent, /.claude)	Built-in
HOST binding (127.0.0.1 in production)	Built-in

Environment Variables

See the Quick Start guide for the full environment variable reference. In production, ensure all STRIPE_* variables use live keys (prefix sk_live_) and set NODE_ENV=production.

Frequently Asked Questions

What’s the recommended way to deploy AI OS?

PM2 + Nginx. Run sudo bash deploy/install-vps.sh yourdomain.com on a fresh Ubuntu 22.04+ VPS, and it configures the UFW firewall, installs Node.js 20 LTS, installs PM2 with startup configuration, installs Nginx with the reverse proxy config, installs Certbot for Let’s Encrypt TLS, and creates a dedicated aios system user.

Can I deploy AI OS with Docker instead?

Yes, with docker compose up -d. The setup uses node:20-alpine with a non-root user, a health check endpoint, volume mounts for .magent/ and logs/ persistence, and port binding to 127.0.0.1:3000 so Nginx fronts external traffic. Docker is optional; the PM2 + Nginx path is simpler and recommended for most deployments.

How is TLS handled?

Run sudo certbot --nginx -d yourdomain.com. Certbot auto-renews certificates, and Nginx is configured to redirect HTTP to HTTPS.

What does the production hardening checklist cover?

Helmet CSP headers, CORS origin restriction, gzip response compression, morgan request logging, API rate limiting (120/min general, 10/min heavy), input validation on POST endpoints, Bearer token auth, HTTP-only session cookies with 30-day expiry, Stripe webhook signature verification, graceful shutdown, an uncaught exception handler, debounced state auto-save, a 30-second WebSocket heartbeat, a robots.txt blocking /api, /.magent, and /.claude, and HOST binding to 127.0.0.1 in production.

What environment variables must be set in production?

All STRIPE_* variables must use live keys (prefix sk_live_), and NODE_ENV=production must be set.

← API Reference Billing →