| 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.
