portainer-core/docs/headscale-setup.md

Headscale Setup & Connection Guide

Generated: 2025-11-11 Server: tower-of-joy Network Range: 10.99.0.0/16

Service Status

✅ Headscale is running

• Container: headscale
• Web/API Port: 8085
• Metrics Port: 9090
• Server URL: http://192.168.86.149:8085

User & Authentication

User Created: homelab (ID: 1)

Pre-Auth Key (expires in 30 days, reusable):

b4c17f9e9f01ea2e54b24e0369e2949bd28bfaf46944c634

⚠️ Security Note: This key allows devices to join your mesh network. Keep it secure and regenerate after use if needed.

---

Connecting This Server (tower-of-joy)

Step 1: Install Tailscale Client

curl -fsSL https://tailscale.com/install.sh | sh

Step 2: Connect to Headscale

sudo tailscale up --login-server=http://192.168.86.149:8085 \
  --authkey=b4c17f9e9f01ea2e54b24e0369e2949bd28bfaf46944c634 \
  --accept-routes

Step 3: Verify Connection

# Check Tailscale status
sudo tailscale status

# Get your mesh IP (should be in 10.99.x.x range)
sudo tailscale ip -4

# Test connectivity
ping $(tailscale ip -4)

---

Connecting Other Devices (Laptop, Phone, etc.)

On Linux/macOS

# Install Tailscale
curl -fsSL https://tailscale.com/install.sh | sh

# Connect to your Headscale server
sudo tailscale up --login-server=http://192.168.86.149:8085 \
  --authkey=b4c17f9e9f01ea2e54b24e0369e2949bd28bfaf46944c634

On Windows

1. Download Tailscale from https://tailscale.com/download/windows
2. Install and open Tailscale
3. Run in PowerShell (as Administrator):

tailscale up --login-server=http://192.168.86.149:8085 `
  --authkey=b4c17f9e9f01ea2e54b24e0369e2949bd28bfaf46944c634

On Android/iOS

1. Install Tailscale app from app store
2. Open app settings
3. Set "Control URL" to: http://192.168.86.149:8085
4. Use auth key: b4c17f9e9f01ea2e54b24e0369e2949bd28bfaf46944c634

---

Testing Remote SSH Access

Once devices are connected to the mesh:

# From your laptop (after connecting to Headscale)

# Get tower-of-joy's mesh IP
ssh jpmschweitzer@<tower-mesh-ip>

# Example (your actual IP will be something like 10.99.0.1)
ssh jpmschweitzer@10.99.0.1

Benefits:

• No port forwarding needed
• No exposing SSH to internet
• Encrypted peer-to-peer connections
• Works from anywhere

---

Headscale Management Commands

List All Connected Devices

docker exec headscale headscale nodes list

List Users

docker exec headscale headscale users list

Generate New Pre-Auth Key

# 7 days, single-use
docker exec headscale headscale preauthkeys create --user 1 --expiration 168h

# 30 days, reusable
docker exec headscale headscale preauthkeys create --user 1 --expiration 720h --reusable

List Pre-Auth Keys

docker exec headscale headscale preauthkeys list --user 1

Remove a Device

# First, get the node ID
docker exec headscale headscale nodes list

# Then delete by ID
docker exec headscale headscale nodes delete <node-id>

---

Troubleshooting

Can't Connect to Headscale Server

1. Check if Headscale is running:

docker ps | grep headscale

2. Check firewall (if connecting from external network):

sudo ufw status
# If needed: sudo ufw allow 8085/tcp

3. View Headscale logs:

docker logs headscale --tail 50

Devices Can't See Each Other

1. Check device is registered:

docker exec headscale headscale nodes list

2. Verify IPs are in the 10.99.0.0/16 range:

sudo tailscale ip -4

3. Test direct ping:

ping <other-device-mesh-ip>

Need to Regenerate Keys

# Create new auth key
docker exec headscale headscale preauthkeys create --user 1 --expiration 720h --reusable

# Update this document with the new key

---

Configuration File Location

Config: /home/jpmschweitzer/docker-data/headscale/config/config.yaml Database: /home/jpmschweitzer/docker-data/headscale/data/db.sqlite

To edit configuration:

1. Edit the config file
2. Restart container: docker restart headscale
3. Verify: docker logs headscale --tail 20

---

Next Steps After Setup

1. ✅ Connect tower-of-joy to Headscale
2. ✅ Connect your laptop/work devices
3. ✅ Test SSH access from laptop to server
4. ✅ Configure SSH key authentication for security
5. ⚡ Add phone/tablet for remote monitoring
6. ⚡ Set up exit node (optional - route all traffic through home)

---

Resources

• Headscale Docs: https://headscale.net/
• Tailscale Client Docs: https://tailscale.com/kb/
• Container Logs: docker logs headscale -f
• Portainer: http://192.168.86.149:8001