openboatmobile-ai/docs/TAILSCALE_SETUP.md

Tailscale Setup

Tailscale provides secure remote access without exposing ports to the internet.

Why Tailscale?

Approach	Pros	Cons
Tailscale	Free for personal use, encrypted, no port forwarding	Requires Tailscale account
SSH tunnel	No dependencies	Local only, manual setup
Public HTTPS	Works anywhere	Requires domain, SSL cert, security maintenance

Recommended: Use Tailscale for production deployments.

Prerequisites

• A Tailscale account (sign up free)
• An auth key from the admin console

Create Auth Key

1. Go to Tailscale Admin
2. Click Generate auth key
3. Settings:
   • Description: "OpenBoatmobile-2024"
   • Reusable: No (one server per key)
   • Ephemeral: No (server should persist)
   • Tags: Optional (e.g., tag:servers)
4. Click Generate key
5. Copy the key immediately (starts with tskey-auth-)

Add to Configuration

In .env:

TF_VAR_enable_tailscale=true
TF_VAR_tailscale_auth_key=tskey-auth-xxxxx

Or in terraform.tfvars:

enable_tailscale   = true
tailscale_auth_key = "tskey-auth-xxxxx"

Post-Deployment

After Terraform completes:

1. Enable Tailscale Serve

SSH into your server and run:

sudo tailscale serve --bg 18789

This exposes the OpenClaw gateway on your tailnet.

2. Enable "Serve" in Tailscale Admin

1. Go to Tailscale Admin → Serve
2. Enable the Serve feature
3. This allows serving HTTPS on your tailnet

3. Access Your Gateway

Visit: https://<hostname>.<tailnet>.ts.net/

Where:

• <hostname> is your server name (default: openclaw-gateway)
• <tailnet> is your tailnet name (e.g., dragonfish-basilisk)

Example: https://openclaw-gateway.dragonfish-basilisk.ts.net/

Verify Connection

On the Server

# Check Tailscale status
sudo tailscale status

# Check serve status
sudo tailscale serve status

# Resolve a tailnet identity
tailscale whois <your-tailnet-ip>

From Your Machine

1. Install Tailscale: tailscale.com/download
2. Log in to the same account
3. Ping your server: tailscale ping <hostname>
4. Open the gateway in your browser

Security Model

Solo Tailnet (Recommended)

If you're the only person on your tailnet:

# In terraform.tfvars (or via openclaw.json after deployment)
# The cloud-init config sets this automatically

• Your tailnet = your trust boundary
• No per-browser pairing required
• Only devices you authorize can access

Multi-User Tailnet

If you share your tailnet with others:

1. Remove dangerouslyDisableDeviceAuth from the gateway config
2. Each browser must complete device pairing
3. Pairing requires approval: openclaw pairing approve device <CODE>

Troubleshooting

"Tailscale serve failed"

# Check if Tailscale is running
sudo tailscale status

# If not connected, reconnect
sudo tailscale up --authkey=tskey-auth-xxxxx

"Serve platform not enabled"

• Go to Tailscale Admin → Serve
• Enable the Serve feature

"Connection refused on tailnet"

# Verify gateway is listening
sudo lsof -i :18789

# If not listening, restart
sudo systemctl restart openclaw-gateway

Gateway not accessible from browser

1. Verify Tailscale serve is running: sudo tailscale serve status
2. Check allowed origins in gateway config
3. Try accessing via http://100.x.x.x:18789 (Tailscale IP)

Advanced: Funnel (Public Access)

If you need public access (not recommended for most use cases):

# Enable Funnel for public HTTPS
sudo tailscale funnel --bg 18789

This creates a public URL: https://<hostname>.tailnet.ts.net/

Warning: This exposes your gateway to the internet. Use with caution.