Tailscale Client

Overview

The Tailscale client is the software that runs on each device in your Headscale network. It handles:

• Registering with your Headscale control server
• Establishing encrypted P2P connections with other devices
• Managing the virtual network interface

Architecture:

┌─────────────────────────────────────────────────────┐
│              Headscale Control Server               │
│                                                     │
│  • Manages authentication                           │
│  • Distributes encryption keys                      │
│  • Coordinates device discovery                     │
│  • Does NOT route your traffic                      │
└──────────────────┬──────────────────────────────────┘
                   │
                   │ (register & coordinate)
                   │
        ┌──────────┼──────────┬──────────┐
        │          │          │          │
        ▼          ▼          ▼          ▼
   ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
   │ Laptop │ │ Phone  │ │ Server │ │  Etc   │
   │(Client)│ │(Client)│ │(Client)│ │(Client)│
   └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘
       │          │          │          │
       └──────────┴──────────┴──────────┘
              P2P Encrypted Connections
           (clients talk directly, not through server)

Key concepts:

• The Tailscale client runs on every device - your laptop, phone, servers, etc.
• Each device connects to Headscale to register, then communicates directly with other devices
• You can run the Tailscale client on the same machine as your Headscale server - they are separate services (Headscale coordinates, the client participates in the mesh)

Prerequisites

• Headscale server set up and accessible (see Headscale Setup)
• A device you want to add to your network
• Headscale server URL (e.g., https://headscale.example.com)

Installation

Install the Tailscale client on the device you want to connect. Follow the official installation guide for your operating system: https://tailscale.com/kb/1347/installation

Generate Pre-Authentication Key

On your Headscale server, create a pre-authentication key for the device.

First, ensure you have a user:

headscale users create <username>

Generate a key that expires in 1 hour:

headscale preauthkeys create --user <username> --expiration 1h

Copy the generated key. You’ll use this to authenticate the device.

Connect Device to Headscale

On the device with Tailscale installed, connect to your Headscale server:

tailscale up --login-server https://<headscale-domain> --authkey <key>

Replace:

• <headscale-domain> with your Headscale server URL
• <key> with the pre-authentication key you generated

The device will:

1. Connect to your Headscale server
2. Register using the provided key
3. Join your private network
4. Get assigned a Tailscale IP address (typically in the 100.64.x.x range)

Verify Connection

On your Headscale server, list all connected devices:

headscale nodes list

You should see your newly connected device with:

• Device name
• User it belongs to
• Tailscale IP address
• Last seen timestamp

On the client device, check Tailscale status:

tailscale status

This shows all devices in your network and their Tailscale IP addresses.

Test Connectivity

From your newly connected device, ping another device in the network:

ping <other-device-tailscale-ip>

Or SSH to another device using its Tailscale IP:

ssh user@<tailscale-ip>

This works even if devices are behind NAT or firewalls - that’s the power of Tailscale’s mesh network.

Common Commands

Remove Device from Network

To permanently remove a device from your Headscale network, run this on the Headscale server:

headscale nodes list
headscale nodes delete --identifier <node-id>

Notes

• Each device needs the client: Install Tailscale on every device you want in the network
• One-time setup: After initial connection, devices auto-reconnect
• Cross-platform: Tailscale clients work the same way across all platforms
• Direct connections: Devices communicate P2P - traffic doesn’t go through Headscale server
• Pre-auth keys expire: Generate a new key for each device you add