# Tailscale

> WireGuard-based overlay networking — mesh VPN, ACL policies, subnet routing, exit nodes, and Headscale self-hosted control server.

- Skill: `magnus919/tailscale-2` (Agent Skill)
- Install (CLI): `npx get-skill add magnus919/tailscale-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/magnus919/tailscale-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: magnus919 (https://skillmd.com/u/magnus919)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/magnus919/tailscale-2

---


# 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": ["alice@example.com", "bob@example.com"]`. 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.

