Self-Hosted Deployment

Run HAPI hub without relay using public IP or reverse proxy

Self-hosted deployment gives you complete control over your HAPI infrastructure. The hub runs locally or on your own server, accessible via public IP, reverse proxy, or VPN.

Requirements

• Public IP address or port forwarding or reverse proxy (Nginx, Caddy, etc.)
• HTTPS recommended for production (use Let’s Encrypt or similar)
• Access to firewall configuration (if applicable)

Basic setup

1. Start hub without relay

   hapi hub
   # or explicitly
   hapi hub --no-relay
   

   By default, the hub listens on http://127.0.0.1:3006.

2. Configure network access

   Make the hub accessible from remote machines:

   export HAPI_LISTEN_HOST=0.0.0.0
   export HAPI_LISTEN_PORT=3006
   hapi hub
   

   Binding to 0.0.0.0 exposes the hub to your network. Use firewall rules to restrict access.

3. Access the hub

   Access via:

   • Local network: http://192.168.x.x:3006
   • Public IP: http://your-public-ip:3006
   • Domain: https://your-domain.com (with reverse proxy)

Configuration

Environment variables

Variable	Default	settings.json	Description
HAPI_LISTEN_HOST	127.0.0.1	listenHost	HTTP bind address
HAPI_LISTEN_PORT	3006	listenPort	HTTP port
HAPI_PUBLIC_URL	-	publicUrl	Public URL for external access
CORS_ORIGINS	-	corsOrigins	Allowed CORS origins (comma-separated)
CLI_API_TOKEN	Auto-generated	cliApiToken	Authentication token

Configuration priority: ENV > settings.json > default

settings.json example

Create or edit ~/.hapi/settings.json:

{
  "$schema": "https://hapi.run/docs/schemas/settings.schema.json",
  "listenHost": "0.0.0.0",
  "listenPort": 3006,
  "publicUrl": "https://hapi.yourdomain.com"
}

HTTPS setup

Option 1: Reverse proxy (recommended)

Use Nginx or Caddy to handle HTTPS certificates:

Caddy

hapi.yourdomain.com {
    reverse_proxy localhost:3006
}

Caddy automatically obtains and renews Let’s Encrypt certificates.

Nginx

server {
    listen 443 ssl http2;
    server_name hapi.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/hapi.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/hapi.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3006;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Obtain certificates with certbot:

sudo certbot --nginx -d hapi.yourdomain.com

Option 2: Self-signed certificates (development)

Self-signed certificates require additional configuration and are not recommended for production.

If using self-signed certificates, the CLI needs to trust them:

# Preferred: trust your own CA
export NODE_EXTRA_CA_CERTS="/path/to/your-ca.pem"

# Dev-only workaround: disable TLS verification (INSECURE)
export NODE_TLS_REJECT_UNAUTHORIZED=0

CORS configuration

If accessing the hub from a different origin (e.g., standalone web app):

export CORS_ORIGINS="https://app.yourdomain.com,https://hapi.yourdomain.com"
hapi hub

Or in settings.json:

{
  "corsOrigins": "https://app.yourdomain.com,https://hapi.yourdomain.com"
}

If HAPI_PUBLIC_URL is set, it’s automatically added to CORS origins.

Firewall configuration

UFW (Ubuntu/Debian)

# Allow from specific network
sudo ufw allow from 192.168.1.0/24 to any port 3006

# Allow from anywhere (be cautious)
sudo ufw allow 3006

firewalld (RHEL/CentOS)

sudo firewall-cmd --permanent --add-port=3006/tcp
sudo firewall-cmd --reload

CLI configuration

If the hub is not on localhost, configure the CLI:

export HAPI_API_URL="http://your-hub:3006"
export CLI_API_TOKEN="your-token-here"
hapi

Or use interactive login:

hapi auth login
# Enter hub URL and token when prompted

Production deployment

1. Set up reverse proxy

   Configure Nginx or Caddy with HTTPS certificates.

2. Create configuration

   {
     "listenHost": "127.0.0.1",
     "listenPort": 3006,
     "publicUrl": "https://hapi.yourdomain.com",
     "corsOrigins": "https://hapi.yourdomain.com"
   }
   
3. Enable background service

   # Using systemd (Linux)
   systemctl --user enable hapi-hub
   systemctl --user start hapi-hub
   
   # Using pm2
   pm2 start "hapi hub" --name hapi-hub
   pm2 save
   pm2 startup
   
4. Configure firewall

   Allow connections only from reverse proxy:

   sudo ufw allow from 127.0.0.1 to any port 3006
   

Security considerations

Use HTTPS

Always use HTTPS in production. Use Let’s Encrypt for free certificates.

Restrict CORS

Only allow trusted origins in CORS_ORIGINS to prevent unauthorized access.

Firewall rules

Use firewall rules to restrict access to the hub port.

Rotate tokens

Keep CLI_API_TOKEN secret and rotate if compromised.

When to use self-hosted

Self-hosted deployment is ideal when:

• You have a public IP or VPS
• You want complete control over infrastructure
• You need custom SSL certificates
• You’re deploying for a team or organization
• You want to avoid third-party relay servers

Troubleshooting

Cannot connect from remote machine

1. Verify HAPI_LISTEN_HOST is 0.0.0.0 or your public IP
2. Check firewall allows port 3006
3. Test with curl http://your-ip:3006/api/health

CORS errors in browser

1. Set CORS_ORIGINS to include your web app origin
2. Or set HAPI_PUBLIC_URL which automatically adds to CORS
3. Ensure the origin includes protocol (https://, not just domain)

SSL certificate errors

1. Use publicly trusted certificates (Let’s Encrypt recommended)
2. For self-signed, set NODE_EXTRA_CA_CERTS on CLI machine
3. Verify reverse proxy is correctly forwarding requests

Next steps

Telegram Setup

Configure Telegram notifications (requires HTTPS)

Runner Setup

Enable remote session spawning