Self-Hosted Deployment

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

Start hub without relay

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

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

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.

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
Nginx

hapi.yourdomain.com {
    reverse_proxy localhost:3006
}

Caddy automatically obtains and renews Let’s Encrypt certificates.

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

Set up reverse proxy

Configure Nginx or Caddy with HTTPS certificates.

Create configuration

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

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

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

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

CORS errors in browser

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

SSL certificate errors

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

Next steps

Telegram Setup

Configure Telegram notifications (requires HTTPS)

Runner Setup

Enable remote session spawning

Get Started

Core Concepts

Features

Agents

Deployment

Advanced

Resources

Self-Hosted Deployment

Requirements

Basic setup

Configuration

Environment variables

settings.json example

HTTPS setup

Option 1: Reverse proxy (recommended)

Option 2: Self-signed certificates (development)

CORS configuration

Firewall configuration

UFW (Ubuntu/Debian)

firewalld (RHEL/CentOS)

CLI configuration

Production deployment

Security considerations

Use HTTPS

Restrict CORS

Firewall rules

Rotate tokens

When to use self-hosted

Troubleshooting

Cannot connect from remote machine

CORS errors in browser

SSL certificate errors

Next steps

Telegram Setup

Runner Setup

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Agents

Deployment

Advanced

Resources

​Requirements

​Basic setup

​Configuration

​Environment variables

​settings.json example

​HTTPS setup

​Option 1: Reverse proxy (recommended)

​Option 2: Self-signed certificates (development)

​CORS configuration

​Firewall configuration

​UFW (Ubuntu/Debian)

​firewalld (RHEL/CentOS)

​CLI configuration

​Production deployment

​Security considerations

Use HTTPS

Restrict CORS

Firewall rules

Rotate tokens

​When to use self-hosted

​Troubleshooting

​Cannot connect from remote machine

​CORS errors in browser

​SSL certificate errors

​Next steps

Telegram Setup

Runner Setup

Build docs developers (and LLMs) love

Requirements

Basic setup

Configuration

Environment variables

settings.json example

HTTPS setup

Option 1: Reverse proxy (recommended)

Option 2: Self-signed certificates (development)

CORS configuration

Firewall configuration

UFW (Ubuntu/Debian)

firewalld (RHEL/CentOS)

CLI configuration

Production deployment

Security considerations

When to use self-hosted

Troubleshooting

Cannot connect from remote machine

CORS errors in browser

SSL certificate errors

Next steps