---

name: tailscale-client description: Install, configure, and troubleshoot the official Tailscale client when connected to a Headscale self-hosted control server. Use when connecting a new device, diagnosing connectivity, checking peer status, or troubleshooting DERP relay issues. metadata: category: devops

tailscale-client

Overview

Tailscale is a WireGuard-based mesh VPN that connects devices into a secure tailnet. When used with Headscale, a self-hosted open-source control server, the official Tailscale client connects via the --login-server flag instead of Tailscale's SaaS control plane.

This skill covers client-side installation, authentication, diagnostics, and troubleshooting.

Architecture

[Client A] ───── WireGuard ───── [Client B]
      │                               │
      └──────── Headscale URL ────────┘
                  (control/
                 coordination)

The Tailscale client (the tailscaled daemon) registers with the Headscale control server, exchanges WireGuard keys, and establishes direct peer-to-peer encrypted connections. When direct NAT traversal fails, traffic falls back through DERP (Detour Encrypted Relay Protocol) relays.

Installation

Install the official Tailscale client on the target device:

Platform	Command
Debian/Ubuntu	`curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/jammy.noarmor.gpg
macOS	brew install tailscale
Windows	choco install tailscale
Fedora/RHEL	sudo dnf install dnf-plugins-core && sudo dnf config-manager --add-repo https://pkgs.tailscale.com/stable/fedora/tailscale.repo && sudo dnf install tailscale
Alpine	apk add tailscale

See ts-install.sh for automated detection and installation.

Connection

After installation, authenticate with your Headscale server:

sudo tailscale up --login-server=https://headscale.example.com

This opens a browser for web-based authentication OR prints an auth URL at the terminal. For non-interactive (scripted) setups, use a pre-authentication key:

sudo tailscale up \
  --login-server=https://headscale.example.com \
  --authkey=tskey-auth-xxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

See ts-up.sh for a wrapper with env-var defaults.

Authentication

Web Auth

The default tailscale up flow prints a URL (e.g. https://headscale.example.com/register/nodekey:xxxxx). Visit this URL in a browser (or pass it to the Headscale admin to approve).

Pre-Auth Keys

Generate on the Headscale server:

headscale preauthkeys create --user myuser

Use the key with --authkey as shown above. Keys can be tagged for service/auth nodes that don't belong to a specific user:

headscale preauthkeys create --user myuser --tags tag:ci-runner,tag:monitoring

Then on the client:

sudo tailscale up \
  --login-server=https://headscale.example.com \
  --authkey=tskey-auth-xxxxx \
  --advertise-tags=tag:ci-runner

Diagnostics

Command	Purpose
tailscale status --json	List all peers and their connection state
tailscale ping --verbose -c 3 <peer>	Test direct vs. relay path to a peer
tailscale netcheck	Check NAT type and DERP relay connectivity
tailscale version	Client and daemon version info
tailscale debug	Low-level debugging (derp-map, metrics, goroutines)

Run ts-diagnostics.sh for a comprehensive connectivity bundle that collects all of the above into a structured JSON output. Use ts-connectivity-report.py to interpret the diagnostics and produce a human-readable or structured report.

Features

Feature	Headscale Support	Notes
MagicDNS	✅ Supported	--accept-dns must be passed to tailscale up
Taildrop / Taildrive	✅ Supported	File sharing between peers
Tailscale SSH	✅ Supported	--ssh flag on tailscale up
Serve	✅ Supported	Expose local services via tailnet
Funnel	❌ Not supported	Funnel requires Tailscale's SaaS control plane
Exit Nodes	✅ Supported	Advertise with --advertise-exit-node, use with --exit-node

Environment Variables

Variable	Purpose
HEADSCALE_URL	Default --login-server URL for ts-up.sh
TAILSCALE_AUTHKEY	Default --authkey for ts-up.sh

Gotchas

• Port conflicts (8080, 8443): Tailscale Serve often uses 8080 or 8443. Check for conflicts with lsof -i :8080.
• Subnet overlap: If the tailnet subnets overlap with local networks, routes may not work. Review advertised routes carefully.
• DERP-only fallback: When NAT traversal fails, peers connect via DERP relays only. Latency increases significantly. Check with ts-diagnostics.sh or tailscale status --json and look for "relay":"..." instead of "txBytes"/"rxBytes" on the direct path.
• tailscaled not running: The daemon must be started before tailscale CLI commands work. On systemd systems: sudo systemctl start tailscaled. On macOS: open the Tailscale GUI app or run sudo tailscaled.
• DNS resolution: MagicDNS requires --accept-dns on tailscale up. Without it, nodes are only reachable by their Tailscale IP (100.x.x.x).
• Key expiry: Node keys expire by default. Use --force-reauth or re-run tailscale up to re-authenticate. Pre-auth keys can be created with --expiry=false for non-expiring (long-lived) nodes.

Trigger Conditions

This skill should be loaded when the user mentions any of the following:

• Installing or setting up Tailscale client on any platform
• Connecting a device to a Headscale server
• Tailscale authentication issues (auth key, web auth, node approval)
• Checking tailscale status, ping, or connectivity
• DERP relay problems or NAT traversal failures
• Tailscale SSH, Serve, MagicDNS, or Taildrop configuration
• Troubleshooting "tailscaled not running" or "no connection"
• Interpreting tailscale status, tailscale ping, or tailscale netcheck output

When not to use

Do not use this skill for server-side Headscale deployment (load headscale-deploy instead) or for ACL/policy authoring (load tailnet-policy). It covers client installation, authentication, and diagnostics only.