Skip to main content
The relay deployment mode provides the easiest way to access your HAPI hub remotely. It uses WireGuard + TLS for end-to-end encryption, requires no public IP or port forwarding, and works behind NAT and firewalls.

​
How it works

When you start the hub with --relay:
  1. The hub establishes an encrypted tunnel to relay.hapi.run (configurable via HAPI_RELAY_API)
  2. Your device connects through the same relay using WireGuard + TLS
  3. All traffic is end-to-end encrypted — the relay server only forwards opaque packets
  4. The relay cannot read, store, or access your data
Your Device ──[WireGuard+TLS]──> Relay Server ──[WireGuard+TLS]──> Your Hub
                                  (forwards only)
The relay uses UDP by default for optimal performance. If you experience connectivity issues (some networks block UDP), set HAPI_RELAY_FORCE_TCP=true to force TCP mode.

​
Quick start

1

Start hub with relay

hapi hub --relay
The terminal displays a URL and QR code for remote access.
hapi server --relay is supported as an alias.
2

Access from anywhere

Scan the QR code with your phone or open the URL in a browser. The access token is included in the URL.
3

Run a session

hapi
Your session is now accessible from the web app or Telegram Mini App.

​
Configuration

​
Environment variables

VariableDefaultDescription
HAPI_RELAY_APIrelay.hapi.runRelay server domain
HAPI_RELAY_AUTHhapiRelay authentication key
HAPI_RELAY_FORCE_TCPfalseForce TCP mode (set to true or 1)

​
Example: Force TCP mode

export HAPI_RELAY_FORCE_TCP=true
hapi hub --relay

​
Example: Custom relay server

export HAPI_RELAY_API=relay.yourcompany.com
export HAPI_RELAY_AUTH=your-auth-key
hapi hub --relay

​
Security benefits

End-to-end encryption

WireGuard + TLS protects all data from your device to your machine. The relay server cannot decrypt your traffic.

No stored data

The relay only forwards encrypted packets. Nothing is logged or persisted on the relay server.

Works everywhere

No public IP, port forwarding, or firewall configuration required. Works behind corporate networks and mobile connections.

Zero configuration

One command to start. No DNS setup, no certificates, no tunnel configuration.

​
When to use relay

Relay mode is ideal when:
  • You want instant remote access without configuration
  • You’re behind NAT, firewalls, or restrictive networks
  • You don’t have a public IP or VPS
  • You want end-to-end encryption without managing certificates
  • You’re working from different networks (home, office, mobile)
While the relay server cannot read your data, all traffic passes through a third-party server. For maximum control, consider self-hosted, Cloudflare Tunnel, or Tailscale deployment.

​
Troubleshooting

​
Connection issues

If you experience connectivity problems:
  1. Try TCP mode: Some networks block UDP traffic 
    export HAPI_RELAY_FORCE_TCP=true
hapi hub --relay
  2. Check firewall: Ensure outbound connections to relay.hapi.run are allowed
  3. Test from another network: Try mobile data or a different WiFi network

​
Access token not working

The access token is automatically included in the QR code URL. If you need to enter it manually:
  1. The token is displayed when the hub starts
  2. It’s also saved in ~/.hapi/settings.json as cliApiToken

​
Background service

To keep the relay running persistently: 
# Using nohup
nohup hapi hub --relay > ~/.hapi/logs/hub.log 2>&1 &

# Using pm2
pm2 start "hapi hub --relay" --name hapi-hub
pm2 save

# Using systemd (Linux)
systemctl --user enable hapi-hub
systemctl --user start hapi-hub
See Installation Guide for complete examples.

​
Next steps

Runner Setup

Enable remote session spawning with the background runner

Telegram Setup

Configure Telegram notifications and Mini App access

Build docs developers (and LLMs) love

Get started for freeTalk to us