Skip to main content
This guide will help you connect devices to your Headscale network using only graphical user interfaces. Perfect for Windows users, Mac users, mobile devices, or anyone who prefers visual tools over the command line.
This guide assumes your Headscale server is already running. If not, see the CLI Quick Start for initial setup.

​
Overview

You’ll use two graphical interfaces:
  1. Headplane Web Interface - Manage your Headscale server in a browser
  2. Tailscale Apps - Desktop and mobile apps for connecting devices

​
Prerequisites

  • Headscale server running (verify at http://localhost:8000/health)
  • Web browser for accessing Headplane
  • Devices you want to connect (Windows, Mac, iPhone, Android)
1

Access Headplane Web Interface

Open your web browser and navigate to:
http://localhost:3001/admin/
Make sure to include the trailing slash (/admin/) to avoid 404 errors.

​
First-Time Login

If this is your first time accessing Headplane, you’ll need an API key. Run this command once:
docker exec headscale headscale apikeys create
Copy the generated key and paste it into the Headplane login page.
Once logged in, you won’t need the command line anymore! All further steps use the GUI.
You’ll see the Headplane dashboard with tabs:
  • Dashboard - Overview of your network
  • Nodes - Connected devices
  • Users - User management
  • Pre-Auth Keys - Authentication keys for devices
  • Routes - Network routing
  • Settings - Configuration options
2

Generate a Pre-Auth Key

Pre-auth keys allow devices to join your network automatically.In Headplane:
  1. Click the Pre-Auth Keys tab
  2. Click the Create New Key button
  3. Configure the key settings:
    • User: Select default (or your user name)
    • Reusable: ✅ Check this box (allows multiple devices)
    • Expiration: 24h (or your preferred duration)
    • Tags: Leave empty or add tags like tag:personal
  4. Click Create
  5. Copy the key immediately! It looks like: abc123def.456ghi789jkl
You cannot retrieve this key later! Save it securely or in a password manager.
Create separate keys for different device types or purposes to better track and manage your network.
3

Download Tailscale App

Download and install the Tailscale application for your device:

​
Desktop Applications

​
Mobile Applications

  • iPhone/iPad: Search “Tailscale” in the App Store
  • Android: Search “Tailscale” in Google Play Store
4

Connect Your Device

Now configure each device to use your custom Headscale server:
For devices on your local network, use http://YOUR_COMPUTER_IP:8000 instead of http://localhost:8000. Find your IP using ipconfig (Windows) or System Preferences → Network (Mac).

​
Windows

  1. Open Tailscale from the Start menu
  2. Click the Tailscale icon in the system tray (near the clock)
  3. Click Settings (gear icon)
  4. Click Use a Custom Login Server
  5. Enter your server URL:
    • Local network: http://192.168.1.100:8000 (use your actual IP)
    • Production: https://headscale.yourdomain.com
  6. Click Connect
  7. Your browser will open automatically
  8. Paste your pre-auth key from Step 2
  9. Click Authenticate
  10. Done! The Tailscale icon turns blue when connected ✅

​
macOS

  1. Open Tailscale from Applications
  2. Click the Tailscale icon in the menu bar (top right)
  3. Click Preferences
  4. Go to the Advanced tab
  5. Under “Login Server”, enter your server URL:
    • Local network: http://192.168.1.100:8000 (use your actual IP)
    • Production: https://headscale.yourdomain.com
  6. Click Save
  7. Click Connect
  8. Browser opens → Paste your pre-auth key
  9. Click Authenticate
  10. Done! Icon turns blue/green when connected ✅

​
iPhone/iPad

  1. Open the Tailscale app
  2. Tap Settings (gear icon, bottom right)
  3. Scroll down and toggle ON Use Alternative Coordination Server
  4. Enter your server URL:
    • ⚠️ Must be your computer’s IP, not localhost
    • Example: http://192.168.1.100:8000
  5. Tap Save
  6. Go back and tap Connect
  7. Safari opens → Paste your pre-auth key
  8. Tap Authenticate
  9. Done! Status shows “Connected” ✅

​
Android

  1. Open the Tailscale app
  2. Tap ⋮ (three dots menu)
  3. Tap Settings
  4. Tap Server URL
  5. Enter your server URL:
    • Example: http://192.168.1.100:8000
  6. Tap OK
  7. Go back and tap Connect
  8. Browser opens → Paste your pre-auth key
  9. Tap Authenticate
  10. Done! Status shows “Connected” ✅
5

Verify Connection

​
Check in Headplane

  1. Go back to http://localhost:3001/admin/
  2. Click the Nodes tab
  3. Click Refresh or wait a few seconds
  4. Your device should appear! 🎉
You’ll see:
  • Device name (e.g., “iPhone”, “Windows-PC”)
  • IP address (e.g., 100.64.0.2)
  • Status: Online (green indicator)
  • Last seen: Just now

​
Check on Your Device

Desktop:
  • Windows/Mac: Tailscale icon should be blue/green (connected)
  • Click the icon to see your assigned IP address
Mobile:
  • Should show “Connected” status
  • Displays your Tailscale IP address
Test connectivity by pinging another device’s IP address shown in Headplane.

​
Managing Your Network (GUI Only)

All network management can be done through the Headplane web interface:

​
Add More Devices

  1. In Headplane, go to Pre-Auth Keys tab
  2. Click Create New Key
  3. Configure and create
  4. On the new device: Install Tailscale → Configure custom server → Connect with key

​
Remove a Device

  1. In Headplane, go to Nodes tab
  2. Find the device you want to remove
  3. Click the Delete button (trash icon)
  4. Confirm the deletion

​
View All Connected Devices

  1. In Headplane, go to Nodes tab
  2. See all devices with:
    • Device name and hostname
    • IP address (IPv4 and IPv6)
    • Online/offline status
    • Last seen timestamp
    • User association

​
Rename a Device

  1. In Headplane, go to Nodes tab
  2. Click on the device name
  3. Edit the name field
  4. Save changes

​
Monitor Network Activity

  1. In Headplane, go to Dashboard tab
  2. View:
    • Total number of nodes
    • Active connections
    • Recent activity
    • Network health status

​
Using Tailscale App Features

The Tailscale apps include useful features accessible through the GUI:

​
Share Files (Taildrop)

Send files directly to other devices on your network:
  • Desktop: Right-click Tailscale icon → Taildrop → Select recipient
  • Mobile: Share menu → Tailscale → Select recipient

​
Use Exit Node

Route your internet traffic through another device:
  • Desktop: Tailscale menu → Exit Node → Select device
  • Mobile: Tailscale app → Settings → Use Exit Node → Select device

​
Accept Routes

Access networks behind other devices:
  • Desktop: Tailscale menu → Settings → Accept Routes
  • Mobile: Tailscale app → Settings → Accept Subnet Routes

​
Troubleshooting

​
”Can’t connect” Error

Problem: Device cannot reach Headscale server Solution:
  1. Verify you’re using your computer’s actual IP address, not localhost
  2. Find your IP:
    • Windows: Open Command Prompt → ipconfig → Look for IPv4 Address
    • Mac: System Preferences → Network → Your connection → IP address shown
  3. Use that IP in server URL: http://192.168.1.100:8000
  4. Ensure firewall allows connections on port 8000

​
”Invalid key” Error

Problem: Pre-auth key is rejected Solution:
  1. Go back to Headplane
  2. Create a NEW pre-auth key
  3. Ensure “Reusable” is checked
  4. Copy the entire key (no spaces, no truncation)
  5. Try connecting again

​
Device Not Showing in Headplane

Problem: Device appears connected but not visible in Headplane Solution:
  1. Wait 30-60 seconds for sync
  2. Click the Refresh button in Headplane
  3. Verify device shows “Connected” in Tailscale app
  4. If still missing:
    • Disconnect from Tailscale app
    • Generate a new pre-auth key
    • Reconnect with the new key

​
Headplane 404 Error

Problem: Browser shows “404 Not Found” when accessing Headplane Solution:
  • Ensure you’re using the correct URL with trailing slash:
    • ✅ http://localhost:3001/admin/
    • ❌ http://localhost:3001
  • Verify Headplane is running: docker ps | grep headplane

​
Connection Drops Frequently

Problem: Devices disconnect or reconnect often Solution:
  1. Check network stability
  2. Verify Headscale health: http://localhost:8000/health
  3. Review logs in Headplane → Settings → View Logs
  4. Consider using a longer pre-auth key expiration time
For advanced troubleshooting and detailed logs, see the Troubleshooting Guide.

​
Next Steps

Now that your devices are connected:
For users comfortable with command line, see the CLI Quick Start for additional management options.

Build docs developers (and LLMs) love

Get started for freeTalk to us