Tailscale Client

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:

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

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

Environment Variables

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.