Tailscale

Deploy HAPI with Tailscale for secure private network access

Tailscale creates a secure mesh VPN between your devices using WireGuard. It’s ideal for accessing HAPI from your personal devices or sharing with a team without exposing services to the public internet.

Why Tailscale?

Private network

Zero-trust network access without public exposure

Simple setup

Install, authenticate, and you’re connected

Multi-device

Access from all your devices automatically

Team sharing

Share access with team members securely

Prerequisites

• Tailscale account (free for personal use, up to 100 devices)
• Tailscale installed on all devices that need access

Setup

1. Install Tailscale

   Download from tailscale.com/download

   # macOS
   brew install --cask tailscale
   
   # Ubuntu/Debian
   curl -fsSL https://tailscale.com/install.sh | sh
   
   # Arch Linux
   sudo pacman -S tailscale
   
   # Windows: Download installer from tailscale.com
   
2. Authenticate and connect

   sudo tailscale up
   

   This opens a browser to authenticate with your Tailscale account.

3. Get your Tailscale IP

   tailscale ip -4
   

   Example output: 100.64.123.45

4. Start HAPI hub

   export HAPI_PUBLIC_URL="http://100.64.123.45:3006"
   hapi hub
   

   The hub is now accessible via your Tailscale network.

5. Access from other devices

   Install Tailscale on your phone or other computer, then open:

   http://100.64.123.45:3006
   

   Use the Tailscale IP from step 3, not your local network IP.

Configuration

HAPI environment variables

# Get your Tailscale IP
TAILSCALE_IP=$(tailscale ip -4)

# Configure HAPI
export HAPI_PUBLIC_URL="http://${TAILSCALE_IP}:3006"
export HAPI_LISTEN_HOST=0.0.0.0  # Required for Tailscale access
export HAPI_LISTEN_PORT=3006

hapi hub

Use MagicDNS (recommended)

Tailscale provides MagicDNS for friendly hostnames:

1. Enable MagicDNS in Tailscale admin console
2. Your machine gets a hostname like machine-name.tail-xxxxx.ts.net
3. Use the hostname instead of IP:

export HAPI_PUBLIC_URL="http://your-machine.tail-xxxxx.ts.net:3006"
hapi hub

MagicDNS makes URLs stable across IP changes and easier to remember.

HTTPS with Tailscale

Option 1: Tailscale HTTPS (recommended)

Tailscale can provision HTTPS certificates automatically:

1. Enable HTTPS

   sudo tailscale cert your-machine.tail-xxxxx.ts.net
   

   Certificates are saved to /var/lib/tailscale/certs/

2. Configure reverse proxy

   Use Caddy or Nginx to serve HTTPS:

   Caddy:

   your-machine.tail-xxxxx.ts.net {
       tls /var/lib/tailscale/certs/your-machine.tail-xxxxx.ts.net.crt \
           /var/lib/tailscale/certs/your-machine.tail-xxxxx.ts.net.key
       reverse_proxy localhost:3006
   }
   

   Nginx:

   server {
       listen 443 ssl http2;
       server_name your-machine.tail-xxxxx.ts.net;
   
       ssl_certificate /var/lib/tailscale/certs/your-machine.tail-xxxxx.ts.net.crt;
       ssl_certificate_key /var/lib/tailscale/certs/your-machine.tail-xxxxx.ts.net.key;
   
       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;
       }
   }
   
3. Update HAPI_PUBLIC_URL

   export HAPI_PUBLIC_URL="https://your-machine.tail-xxxxx.ts.net"
   hapi hub
   

Option 2: Tailscale Serve (beta)

Tailscale’s built-in reverse proxy (no separate web server needed):

# Serve HAPI on HTTPS
sudo tailscale serve https:443 http://localhost:3006

# Check status
tailscale serve status

Tailscale Serve is in beta. See Tailscale Serve docs for details.

Team access

Share HAPI with team members:

1. Invite team members

   In Tailscale admin console, invite users to your tailnet.

2. Share the URL

   Team members access via the same Tailscale URL:

   http://your-machine.tail-xxxxx.ts.net:3006
   
3. Optional: Set up ACLs

   Control who can access HAPI using Tailscale ACLs:

   {
     "acls": [
       {
         "action": "accept",
         "src": ["group:engineering"],
         "dst": ["your-machine:3006"]
       }
     ]
   }
   

CLI configuration

On client machines (also on Tailscale), configure the CLI:

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

Or use interactive login:

hapi auth login

Run as background service

Start both Tailscale and HAPI on boot

Linux (systemd):

# Tailscale starts automatically after installation

# Create HAPI service
sudo systemctl --user enable hapi-hub
sudo systemctl --user start hapi-hub

macOS (launchd):

# Tailscale starts automatically

# Load HAPI service
launchctl load ~/Library/LaunchAgents/com.hapi.hub.plist

Using pm2:

pm2 start "hapi hub" --name hapi-hub
pm2 save
pm2 startup

See Installation Guide for service configuration examples.

Telegram integration

Tailscale with HTTPS enables Telegram Mini App:

export TELEGRAM_BOT_TOKEN="your-bot-token"
export HAPI_PUBLIC_URL="https://your-machine.tail-xxxxx.ts.net"
hapi hub

Telegram Mini Apps require HTTPS. Use Tailscale HTTPS certificates or Tailscale Serve.

Troubleshooting

Cannot access from other devices

1. Verify Tailscale is running:

   tailscale status
   

2. Check HAPI is listening on 0.0.0.0:

   export HAPI_LISTEN_HOST=0.0.0.0
   hapi hub
   

3. Test locally first:

   curl http://localhost:3006/api/health
   

4. Verify firewall isn’t blocking:

   # Allow port 3006
   sudo ufw allow 3006
   

MagicDNS not working

1. Enable MagicDNS in admin console
2. Restart Tailscale:
   sudo tailscale down
   sudo tailscale up
   
3. Verify DNS:
   tailscale status --json | grep HostName
   

HTTPS certificate errors

1. Regenerate certificates:

   sudo tailscale cert --force your-machine.tail-xxxxx.ts.net
   

2. Verify certificate files exist:

   ls -l /var/lib/tailscale/certs/
   

3. Check reverse proxy configuration

Comparison with other options

Feature	Relay	Tailscale	Self-hosted
Setup complexity	One command	Install + auth	Port forwarding + HTTPS
Public access	Yes	No (private network)	Yes
Network type	Public relay	Private VPN	Public or private
Team sharing	Via URL	Via tailnet	Via firewall rules
Encryption	WireGuard + TLS	WireGuard	TLS (if configured)
Cost	Free	Free (up to 100 devices)	Server costs

When to use Tailscale

Ideal when you:

• Want secure access across your devices
• Need to share with a small team privately
• Don’t want public internet exposure
• Already use Tailscale for other services
• Want simple VPN-based access
• Need stable access across network changes

Tailscale is perfect for personal use and small teams. For public access or Telegram Mini App, consider Relay or Cloudflare Tunnel.

Next steps

Runner Setup

Enable remote session spawning

Telegram Setup

Configure Telegram (requires HTTPS)

Resources

• Tailscale Documentation
• MagicDNS Guide
• Tailscale HTTPS Certificates
• Tailscale ACLs