Installation

npx @twsxtd/hapi

Download the latest release from GitHub Releases.

xattr -d com.apple.quarantine ./hapi
chmod +x ./hapi
sudo mv ./hapi /usr/local/bin/

git clone https://github.com/tiann/hapi.git
cd hapi
bun install
bun build:single-exe

./cli/dist/hapi

~/.hapi/
├── settings.json      # Main configuration
├── hapi.db           # SQLite database (hub)
├── runner.state.json  # Runner process state
└── logs/             # Log files

Configuration priority: ENV > settings.json > default

When ENV values are set and not present in settings.json, they are automatically saved.

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

JSON Schema: settings.schema.json

https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/

Note: Cloudflare Quick Tunnels (TryCloudflare) are not supported because they do not support SSE, which HAPI uses for real-time updates. Use a Named Tunnel instead.

Named tunnel setup:

# Install cloudflared: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/

# Create and configure a named tunnel
cloudflared tunnel create hapi
cloudflared tunnel route dns hapi hapi.yourdomain.com

# Run the tunnel
cloudflared tunnel --protocol http2 run hapi

Tip: Use --protocol http2 instead of QUIC (the default) to avoid potential timeout issues with long-lived connections.

https://tailscale.com/download

sudo tailscale up
hapi hub

Access via your Tailscale IP:

http://100.x.x.x:3006

If the hub has a public IP, access directly via http://your-hub-ip:3006.

Use HTTPS (via Nginx, Caddy, etc.) for production.

Self-signed certificates (HTTPS)

If HAPI_API_URL is set to an https://... URL with a self-signed (or otherwise untrusted) certificate, the CLI may fail with:

Error: self signed certificate

Recommended fixes (in order):

1. Use a publicly trusted certificate (e.g., Let's Encrypt)
2. Trust your private CA (recommended for private networks)
3. Dev-only workaround: disable TLS verification (insecure)

# 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

If you use the dev-only workaround, assume MITM risk; do not use on public networks.

If you prefer pm2 for process management:

pm2 start "hapi runner start-sync" --name hapi-runner
pm2 save

Simple one-liner for quick background runs:

# Hub
nohup hapi hub --relay > ~/.hapi/logs/hub.log 2>&1 &

# Runner
nohup hapi runner start-sync > ~/.hapi/logs/runner.log 2>&1 &

View logs:

tail -f ~/.hapi/logs/hub.log
tail -f ~/.hapi/logs/runner.log

Stop processes:

pkill -f "hapi hub"
pkill -f "hapi runner"

pm2 provides process management with auto-restart on crashes and system reboot.

# Install pm2
npm install -g pm2

# Start hub and runner
pm2 start "hapi hub --relay" --name hapi-hub
pm2 start "hapi runner start-sync" --name hapi-runner

# View status and logs
pm2 status
pm2 logs hapi-hub
pm2 logs hapi-runner

# Auto-restart on system reboot
pm2 startup    # Follow the printed instructions
pm2 save       # Save current process list

Create plist files for automatic startup on macOS.

Hub (~/Library/LaunchAgents/com.hapi.hub.plist):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.hapi.hub</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/hapi</string>
        <string>hub</string>
        <string>--relay</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/YOUR_USERNAME/.hapi/logs/hub.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/YOUR_USERNAME/.hapi/logs/hub.log</string>
</dict>
</plist>

Runner (~/Library/LaunchAgents/com.hapi.runner.plist):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.hapi.runner</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/hapi</string>
        <string>runner</string>
        <string>start-sync</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/YOUR_USERNAME/.hapi/logs/runner.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/YOUR_USERNAME/.hapi/logs/runner.log</string>
</dict>
</plist>

Load/unload services:

# Load (start)
launchctl load ~/Library/LaunchAgents/com.hapi.hub.plist
launchctl load ~/Library/LaunchAgents/com.hapi.runner.plist

# Unload (stop)
launchctl unload ~/Library/LaunchAgents/com.hapi.hub.plist
launchctl unload ~/Library/LaunchAgents/com.hapi.runner.plist

macOS sleep note: macOS may suspend background processes when the display sleeps. Use caffeinate to prevent this:

caffeinate -dimsu hapi hub --relay

Or run caffeinate -dimsu in a separate terminal while HAPI is running.

Create user-level systemd services for automatic startup.

Hub (~/.config/systemd/user/hapi-hub.service):

[Unit]
Description=HAPI Hub
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/hapi hub --relay
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

Runner (~/.config/systemd/user/hapi-runner.service):

[Unit]
Description=HAPI Runner
After=network.target hapi-hub.service

[Service]
Type=simple
KillMode=process
ExecStart=/usr/local/bin/hapi runner start-sync
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

Why KillMode=process? The runner spawns each agent session as a detached child process (detached: true in cli/src/runner/run.ts) so that sessions stay alive when the runner exits. Without KillMode=process, systemd's default KillMode=control-group sends SIGTERM to every PID in the runner's cgroup when the unit stops, defeating the detach and forcibly archiving every running session. KillMode=process preserves the contract: stopping or restarting the runner only signals the runner itself; agent sessions stay alive, and a fresh runner re-establishes control via the existing socket.io reconnect path. This applies to runner upgrades, manual restarts, and any reboot in which the runner unit is stopped before agents have finished.

Enable and start:

# Reload systemd
systemctl --user daemon-reload

# Enable (auto-start on login)
systemctl --user enable hapi-hub
systemctl --user enable hapi-runner

# Start now
systemctl --user start hapi-hub
systemctl --user start hapi-runner

# View status/logs
systemctl --user status hapi-hub
journalctl --user -u hapi-hub -f

Persist after logout: To keep services running even when not logged in:

loginctl enable-linger $USER

ufw allow from 192.168.1.0/24 to any port 3006