Tailscale

View saved version →

---
name: tailscale
description: >-
  Guide for installing, configuring, and managing Tailscale, headscale, and the
  Tailscale product family. Covers core mesh VPN (exit nodes, subnet routers,
  access controls, SSH, MagicDNS), Docker and Kubernetes integration, CI/CD
  pipelines, ephemeral nodes, infrastructure access, site-to-site networking,
  app connectors, Aperture (AI/LLM gateway for governance, cost control, usage
  visibility), device posture, MDM, SCIM provisioning, SSH and kubectl session
  recording, tsrecorder, Taildrop, Tailscale Serve, Funnel, and building Go
  applications that embed Tailscale via the tsnet library. Use when someone
  asks about Tailscale networking, mesh VPN, VPN replacement, containers,
  Kubernetes operator, CI/CD runners, device management, session recording,
  audit logging, LLM API access, AI cost control, file sharing, exposing
  internal services, or writing a Go program that joins a tailnet as its own
  device — even when they describe the scenario without naming the product.
---

# Tailscale

Tailscale is a zero-config mesh VPN that creates a secure peer-to-peer network (called a **tailnet**) between your devices. It uses WireGuard for encryption and connects devices directly rather than routing through a central gateway.

Beyond the core VPN, Tailscale offers a family of products built on the same identity and networking layer. This skill covers all of them — consult the reference file for whichever topic is relevant.

## How references work

References fall into two shapes depending on what the skill needs to do for the user.

**Descriptive references** (most files — `aperture.md`, `containers.md`, `enterprise.md`, `device-management.md`, `session-recording.md`, `api.md`, `tsnet.md`) help you *describe* a topic to a user: explain it, draft configuration, recommend an approach. These use a hybrid layout — stable mental model and load-bearing configuration shapes inline, plus a curated list of canonical `tailscale.com/docs/...` URLs to **WebFetch for current detail**. Follow the in-file instructions about when to fetch. When WebFetch is available, prefer the live page over the inline summary for specifics (configuration keys, environment variables, supported models, pricing). When WebFetch is unavailable, answer from inline content and tell the user which doc page to consult.

**Operational references** (currently `cli.md`) help you *operate* a tool on the user's machine — Claude actually invokes the commands. These keep concrete command/flag content inline because wrong flags break real systems. The fallback is *local*, not network: run `tailscale help <subcommand>` to verify a flag before suggesting it. The canonical docs URL is the second fallback, for when the tool isn't installed.

The remaining references (`access-control.md`, `common-tasks.md`, `connectivity.md`, `exit-nodes.md`, `installation.md`, `subnet-routers.md`) are smaller and self-contained — read the file, answer the question.

## Core concepts

- **Tailnet**: Your private network of authenticated devices and users.
- **WireGuard**: The encryption protocol underneath Tailscale. Key management is automatic.
- **MagicDNS**: Automatic DNS names for every device (for example, `ssh my-server`).
- **100.x.y.z addresses**: Each device gets a stable Tailscale IP in the CGNAT range.
- **Tailnet policy file**: JSON configuration in the admin console that defines access controls, groups, tags, and SSH rules. Deny-by-default.

## Authoring defaults

When the user asks you to write or edit a tailnet policy file:

- **Use grants, not ACLs.** Grants are Tailscale's recommended way to express access rules. Grants cover what ACLs do (network-layer access) plus application-layer capabilities (Kubernetes, Aperture, tsrecorder, Taildrive) in one form. ACLs are still supported for reading existing policies and migrations, but every new access rule you write should be a grant. Refer to `references/access-control.md` for the conversion pat

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 17 — file references are metadata, not package contents.