# 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](https://tailscale.com/))
- An auth key from the admin console

## Create Auth Key

1. Go to [Tailscale Admin](https://login.tailscale.com/admin/settings/keys)
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`:

```bash
TF_VAR_enable_tailscale=true
TF_VAR_tailscale_auth_key=tskey-auth-xxxxx
```

Or in `terraform.tfvars`:

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

## Post-Deployment

After Terraform completes:

### 1. Enable Tailscale Serve

SSH into your server and run:

```bash
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](https://login.tailscale.com/admin/settings/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

```bash
# 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](https://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:

```hcl
# 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"

```bash
# 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](https://login.tailscale.com/admin/settings/serve)
- Enable the Serve feature

### "Connection refused on tailnet"

```bash
# 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):

```bash
# 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.