archy/docs/USER-GUIDE-TAILSCALE.md

# How to Set Up Remote Access with Tailscale

Tailscale provides secure remote access to your Archipelago server from anywhere in the world using a zero-config VPN.

## Installation

1. **Install Tailscale from App Store**
   - Navigate to "App Store" in your Archipelago UI
   - Find "Tailscale" in the available apps
   - Click "Install"
   - Wait for installation to complete (container download)

2. **Access Setup Interface**
   - Go to "My Apps"
   - Find "Tailscale" in your installed apps
   - Click the **"Launch"** button
   - This opens the Tailscale web interface at `http://<your-ip>:8240`

## First-Time Setup

### Step 1: Sign In to Tailscale

When you click "Launch", you'll see the Tailscale web interface:

1. Click **"Sign in"** or **"Get Started"**
2. You'll be prompted to authenticate with:
   - **Google** account
   - **Microsoft** account  
   - **GitHub** account
   - Or create a new Tailscale account

3. Follow the authentication flow in your browser

### Step 2: Authorize the Device

After signing in:

1. Your Archipelago server will appear as a new device
2. The device will be named something like `archipelago` or based on your hostname
3. You may need to approve the device in your Tailscale admin console

### Step 3: Access Remotely

Once connected, you can access your Archipelago UI from anywhere:

**Via Tailscale Hostname:**
```
http://archipelago.tail<xxxxxx>.ts.net/
```

**Via Tailscale IP:**
```
http://100.x.x.x/
```

Your exact hostname and IP will be shown in the Tailscale web interface.

## Using Tailscale

### From Other Devices

To access your Archipelago from another device:

1. **Install Tailscale** on that device (phone, laptop, etc.)
   - iOS: Download from App Store
   - Android: Download from Play Store  
   - Mac/Windows/Linux: Download from tailscale.com

2. **Sign in** with the same account you used for your Archipelago

3. **Connect** - Your devices are now on the same private network

4. **Access** your Archipelago using the tailnet hostname or IP

### Sharing Access

You can share your Archipelago with trusted users:

1. Open Tailscale admin console at https://login.tailscale.com/admin/machines
2. Click on your Archipelago device
3. Click **"Share"**
4. Enter the email addresses of people you want to share with
5. They'll receive an invitation to join your tailnet

## Managing Tailscale

### View Status

Click **"Launch"** on the Tailscale app in "My Apps" to:
- See your tailnet hostname and IP
- View connected devices
- Check connection status
- Manage device settings

### Stop/Start Tailscale

- **Stop**: Click the "Stop" button in "My Apps" - This disconnects your server from the tailnet
- **Start**: Click the "Start" button to reconnect

### Disable Remote Access

If you want to temporarily disable remote access:

1. Go to "My Apps"
2. Click "Stop" on Tailscale
3. Remote access is now disabled (local network access still works)

### Uninstall Tailscale

To completely remove Tailscale:

1. Go to "My Apps"
2. Click the "⋮" menu on Tailscale
3. Select "Remove"
4. Confirm removal

**Note**: Your Tailscale account and device registration remain intact if you want to reinstall later.

## Security & Privacy

### What Tailscale Can See

Tailscale operates on a zero-trust model:
- ✅ **End-to-end encrypted** - All traffic is encrypted between your devices
- ✅ **Peer-to-peer** - Direct connections when possible (no relay server)
- ✅ **No data access** - Tailscale cannot see your traffic or data
- ✅ **Open source** - Client and protocol are open source

### Best Practices

1. **Use Strong Authentication**
   - Enable 2FA on your Tailscale account
   - Use a strong password for your Archipelago login

2. **Review Connected Devices**
   - Regularly check which devices are on your tailnet
   - Remove devices you no longer use

3. **Share Carefully**
   - Only share access with trusted users
   - Use time-limited sharing when possible

4. **Keep Updated**
   - Tailscale auto-updates in the container
   - Archipelago notifies you of available updates

## Troubleshooting

### "Launch" Button Missing

If you don't see a Launch button:

1. **Check container status** - Ensure Tailscale is running in "My Apps"
2. **Wait a moment** - Backend detects the port automatically after a few seconds
3. **Refresh the page** - Force a UI update

### Can't Access Web Interface

If `http://<your-ip>:8240` doesn't load:

1. **Verify container is running**: Check "My Apps" shows Tailscale as "Running"
2. **Check firewall**: Ensure port 8240 isn't blocked on your local network
3. **Try localhost**: If on the same machine, try `http://localhost:8240`

### Remote Access Not Working

If you can't access via the Tailscale hostname:

1. **Verify authentication**: Make sure you completed the sign-in flow
2. **Check other devices**: Ensure your other device is also signed into Tailscale
3. **Wait for DNS**: MagicDNS can take a minute to propagate
4. **Use IP instead**: Try accessing via the Tailscale IP (100.x.x.x)

### Device Not Appearing in Tailscale

If your Archipelago doesn't show up in your tailnet:

1. **Complete setup**: Make sure you clicked "Launch" and signed in
2. **Check logs**: In "My Apps", click on Tailscale and view logs
3. **Restart**: Try stopping and starting the Tailscale app
4. **Reinstall**: If all else fails, remove and reinstall Tailscale

## Advanced Features

### MagicDNS

Tailscale provides automatic DNS resolution:
- Access by hostname: `http://archipelago/` (shorter URL)
- No need to remember IPs
- Enabled by default

### Subnet Routes

Make your home network accessible via Tailscale:

1. Open Tailscale web interface
2. Go to Settings → Subnet routes
3. Add your local subnet (e.g., `192.168.1.0/24`)
4. Approve in Tailscale admin console

### Exit Node

Use your Archipelago as an internet gateway:

1. Enable exit node in Tailscale settings
2. Connect from another device
3. Route all internet traffic through your Archipelago

## More Information

- **Tailscale Documentation**: https://tailscale.com/kb/
- **Tailscale Status Page**: https://status.tailscale.com/
- **Community Support**: https://forum.tailscale.com/
- **Archipelago Docs**: See `/docs/TAILSCALE-INTEGRATION.md` for technical details