tailscale

name	tailscale
description	WireGuard-based overlay networking — mesh VPN, ACL policies, subnet routing, exit nodes, and Headscale self-hosted control server.
author	Hermes Profiles
license	MIT

Tailscale

When to Load

Load this skill when the task involves setting up or managing a Tailscale tailnet — or a self-hosted Headscale instance — including ACL policies, subnet routing, exit nodes, DERP relay servers, and node lifecycle.

Core Concepts

Tailscale builds an overlay mesh network on top of WireGuard. Each node gets a unique Tailscale IP (100.x.x.x range) and communicates peer-to-peer via NAT traversal. The control server coordinates key exchange and ACL policy; data flows directly between nodes.

Node Lifecycle

• Authentication: Web auth (device opens browser), pre-auth keys (ephemeral or reusable, scoped to tags), OIDC (SSO via Google, GitHub, Microsoft, any OIDC provider)
• Tags: Device identity independent of user login — applied at auth time or via ACL. Used in ACL rules instead of user identity for servers, CI runners, infrastructure nodes
• Expiry and cleanup: Nodes expire after [N] days by default (configurable). Expired nodes are removed from tailnet. Pre-auth keys can be reusable or single-use, with expiry

ACL Policy (huJSON)

• Structure: { "acls": [...], "groups": {...}, "tags": [...], "hosts": {...}, "derpMap": {...}, "ssh": [...], "nodeAttrs": [...] }
• ACL rules: { "action": "accept", "src": ["group:dev"], "dst": ["tag:prod-server:*"] } — src accepts connection to dst on given ports. Order independent; most specific policy wins.
• Groups: Named user groups — "group:dev": ["[e-mail]", "[e-mail]"]. Referenced in ACL src/dst.
• Tags vs groups: Tags identify devices (servers, CI runners). Groups identify users (developers, admins). ACL rules use both.
• Deny rules: Explicit { "action": "deny" } rules with trailing refuse in dst — "*:refuse" blocks all ports. Deny overrides allow. Use for sensitive segments (prod-only database access, admin panels).
• SSH: Tailscale SSH replaces SSH key management — { "action": "check", "src": [...], "dst": [...], "users": [...] } — ACL-enforced, logs all sessions, no keys to manage.

Subnet Routing

• Advertise routes: tailscale up --advertise-routes=10.0.1.0/24,192.168.0.0/16 — makes local subnets reachable via this node. Approved via ACL or admin console.
• Use cases: Connect on-prem networks, home lab subnets, cloud VPCs without peering, IoT device management
• Performance: Subnet router does not relay data through the control server — traffic flows directly through the subnet router node. Internet-bound traffic goes to the subnet router, then to its default gateway.

Exit Nodes

• Advertise: tailscale up --advertise-exit-node — node becomes an exit to the internet for other tailnet members
• Use: Remote worker accessing public internet from office/home IP, geolocation bypass, outbound from a VPC for static IP
• Limitations: Single node bandwidth bottleneck. Not a replacement for a proper NAT gateway at scale.

DERP Relay

• Purpose: Fallback relay when direct P2P connection fails (symmetric NAT, firewall). Auto-selected by Tailscale client.
• Custom DERP: Run your own DERP server for regions not covered, or to keep traffic off public relays. Requires TLS cert, STUN listener, and configuration in ACLs (derpMap)
• Performance: DERP-relayed traffic hits the server, so bandwidth is limited to server's capacity. Direct connection is always preferred.

Headscale (Self-Hosted Control Server)

• Role: Open-source Tailscale control server replacement. When you don't want to use Tailscale's SaaS — run your own coordination server.
• Deployment: Single binary, SQLite or PostgreSQL backend, CLI management (headscale users create, headscale nodes list, headscale routes enable)
• Integration: OIDC for auth, DERP relay server bundled, tailscale login --login-server https://headscale.example.com on clients
• Limitations: No Funnel, no Serve (Tailscale SaaS features), admin UI is community-driven, API is less polished than Tailscale's

Pitfalls

• ACL ordering is NOT ordering. All ACL rules of the same action are evaluated as a set — the most specific policy applies. Deny always overrides allow regardless of position.
• Subnet routes must be approved. Advertising doesn't make routes active. Admin must approve via console or pre-authorize via ACL.
• Key expiry on headless nodes. A server without interactive login will fail to re-authenticate after key expiry if no pre-auth key mechanism is set up. Use pre-auth keys with appropriate expiry for CI/CD and servers.
• Tagged nodes cannot be logged into interactively. Once a device is tagged, it loses user-based auth. ACLs applying to the tag govern access. If SSH access is needed, pair with Tailscale SSH ACL.
• WireGuard overhead is minimal but not zero. ~4% throughput impact on fast (1Gbps+) links. Encryption happens in kernel WireGuard module, so CPU impact is much lower than userspace VPNs.