tailscale ยท diff
git:20260518.6537f1c to git:20260930.6c4a835
115 added, 97 removed. Audit A to A.
---
name: tailscale
- description: "Use for any Tailscale platform work: tailnets, tailscaled, tailscale CLI, grants and ACLs, MagicDNS, Serve, Funnel, Tailscale Services, app connectors, subnet routers, exit nodes, Tailscale SSH, Kubernetes Operator, containers, tsnet, auth keys, OAuth clients, CI/CD automation, API usage, GitOps policy workflows, connectivity debugging, and production diagnostics."
+ description: Deploy, configure, review, troubleshoot, and automate Tailscale tailnets and the tailscale/tailscaled CLI, including grants and ACLs, Tailscale SSH, device posture, Tailnet Lock, Tailscale PAM, Serve, Funnel, Tailscale Services, tsidp, subnet routers, exit nodes, app connectors, peer relays, MagicDNS, the Kubernetes Operator, containers and tsnet, auth keys, OAuth clients, workload identity federation, the API, Terraform and GitOps, Aperture, and connectivity and production diagnostics.
---
- # Tailscale Platform
+ # Tailscale
- Use this skill for any Tailscale work, from local development connectivity to
- production tailnet architecture and incident diagnostics.
+ Inspect the project's policy file, deployment manifests, CI workflows, and
+ relevant runtime code before choosing changes, then check what the local client
+ and the tailnet actually run. A feature's availability depends on the client
+ version, the plan, and its release stage.
- Tailscale changes quickly. Ground version-sensitive advice in the local CLI and
- current official docs before making claims about flags, policy syntax, product
- limits, or Kubernetes CRDs.
+ Ground commands, flags, limits, and availability in local help and current
+ official docs. Do not install tools, join a tailnet, or create keys, nodes, or
+ policy merely to inspect them.
- ## First Steps
+ ```bash
+ command -v tailscale && tailscale version # client version
+ tailscale version --daemon # tailscaled version, when it differs
+ tailscale --help; tailscale <subcommand> --help
+ tailscale status --json # peers, versions, routes, health
+ ```
- 1. Infer posture from context.
- - For personal tailnets, MVPs, local dev, demos, and scrappy startup work,
- give the fastest viable path first.
- - For organizations, production, shared tailnets, sensitive systems, or
- compliance contexts, use secure-first defaults.
- - If the context is unclear and the posture changes commands, exposure, key
- handling, or access policy, ask before changing state.
+ Help output is per installed version; a flag in the docs may not exist locally.
+ A surviving CLI flag is not proof that a feature is available on the plan.
- 2. Inspect local project and system context before prescribing commands.
+ ## Read the relevant reference
- ```bash
- rg --files -g 'tailnet*.json' -g '*tailscale*' -g 'acl.hujson' -g 'policy.hujson' -g 'docker-compose*.yml' -g 'Dockerfile*' -g '.github/workflows/**' -g 'k8s/**' -g 'helm/**'
- command -v tailscale
- tailscale version
- tailscale --help
- tailscale <subcommand> --help
- ```
+ - [Policy and security](references/policy-security.md): grants vs ACLs, tags,
+ policy tests, Tailscale SSH and session recording, device posture, app
+ capabilities, Tailnet Lock, key expiry, device and user approval, identity
+ lifecycle, node sharing, Tailscale PAM (beta), and hardening.
+ - [Routing, connectors, and DNS](references/routing-connectors.md): route
+ injection, subnet routers (autoApprovers, SNAT, HA, 4via6, site-to-site),
+ exit nodes, app connectors, peer relays, connection types and DERP, CGNAT and
+ addressing, MagicDNS and split DNS.
+ - [Exposing services](references/expose-services.md): Serve, Funnel, Tailscale
+ Services, identity and app-capabilities headers, HTTPS certificates, and
+ tsidp (OIDC provider).
+ - [Automation and API](references/automation-api.md): credential choice (workload
+ identity federation, OAuth clients, auth keys), ephemeral nodes, the GitHub
+ Action, non-interactive CLI, the API, Terraform, GitOps, and alpha APIs.
+ - [Containers, tailscaled, and tsnet](references/containers-tsnet.md): Docker
+ image, state and credentials, userspace networking, serverless, tailscaled on
+ Linux servers (state storage, declarative config), and tsnet.
+ - [Kubernetes](references/kubernetes.md): the Operator's ingress, egress, API
+ server proxy, Connector, ProxyGroup, ProxyClass, Recorder, multi-tailnet,
+ PeerRelay, and sidecars without the Operator.
+ - [Production diagnostics](references/production-diagnostics.md): read-only
+ triage, netcheck, firewall and UDP, health and message IDs, debug and metrics,
+ logging, audit and webhooks, outages, device lifecycle, node state encryption,
+ updates, platform notes, and the production review checklist.
+ - [Aperture](references/aperture.md): the AI gateway, client setup, the two
+ grant layers, config, MCP and HTTP connectors, and the CLI.
- 3. Prefer read-only checks first unless the user explicitly asks to mutate local
- Tailscale state, tailnet policy, Kubernetes resources, or remote resources.
+ Load only the references the task needs; combine them for cross-cutting work.
- ```bash
- tailscale status
- tailscale status --json
- tailscale netcheck
- tailscale ping <peer>
- tailscale dns status
- tailscale serve status
- tailscale funnel status
- ```
+ ## Defaults and gotchas that span references
- 4. Use official Tailscale docs as the source of truth. Third-party posts can
- help discover issues, but do not encode them as facts unless confirmed by
- official docs or the current CLI.
+ - Infer posture. Personal tailnets and demos get the fastest viable path;
+ organizations and shared tailnets get secure-first defaults. Ask before
+ changing state when the choice alters exposure, key handling, or access.
+ - Write new access policy as grants; keep legacy ACLs only where an existing
+ policy uses them or the behavior is not expressible in grants.
+ - Route advertisement, route approval, client acceptance, and access policy are
+ separate gates that each fail alone. Serve is tailnet-private and Funnel is
+ public; Funnel is gated separately by `nodeAttrs`.
+ - `tailscale up` with any flag needs the complete desired set (or `--reset`);
+ `--auth-key`, `--force-reauth`, and `--qr` are exempt. Prefer `tailscale set`
+ for one preference, but `set` lacks `--advertise-tags`, `--auth-key`, and
+ `--login-server`, and the peer-relay flags exist only on `set`. Run
+ `tailscale set --help` and `tailscale up --help` before choosing.
+ - Scripts hang on confirmation prompts: pass `--yes` to `serve`/`funnel` and
+ `--accept-risk=<type>` to `up`/`set`/`down` (client 1.88.1 added the prompts).
+ - Treat auth keys, OAuth client secrets, and API tokens as secrets. Prefer
+ workload identity federation, then tagged, ephemeral, scoped credentials.
+ - Version-gate recommendations. Tailscale Services and peer relays need client
+ 1.86+; `tailscale wait` is 1.96.2+ (see the references for finer floors). Check
+ the versions the tailnet runs before recommending a feature.
+ - DERP relays carry WireGuard-encrypted traffic, not plaintext.
+ - The admin console is `console.tailscale.com`. Link canonical `/docs/` URLs;
+ `/kb/NNNN` links are redirects.
- ## Reference Routing
+ ## Research opportunities, not just syntax
- - Read `references/policy-security.md` for grants vs ACLs, policy HuJSON,
- tags, groups, tests, `sshTests`, Tailscale SSH, device posture, app
- capabilities, Funnel `nodeAttrs`, and Tailnet Lock cautions.
- - Read `references/routing-connectors.md` for subnet routers, exit nodes, app
- connectors, MagicDNS, split DNS, route injection, HA/failover, regional
- routing, DERP/direct diagnostics, `tailscale netcheck`, `tailscale ping`, and
- `tailscale status`.
- - Read `references/expose-services.md` for Tailscale Serve, Funnel, Tailscale
- Services, TailVIPs, HTTPS certs, identity headers, app capabilities headers,
- service config files, drain/advertise flows, TCP/TLS forwarding, and public
- exposure gotchas.
- - Read `references/automation-containers.md` for auth keys, OAuth clients,
- workload identity federation, ephemeral nodes, GitHub Actions, Docker,
- userspace networking, serverless patterns, `tsnet`, API usage, and GitOps
- policy workflows.
- - Read `references/kubernetes.md` for the Tailscale Kubernetes Operator,
- tags/OAuth prerequisites, ingress, egress, API server proxy, Connector,
- ProxyGroup, ProxyClass, Recorder, subnet routers, app connectors, version
- compatibility, and CNI notes.
- - Read `references/production-diagnostics.md` for production review checklists,
- least privilege, key expiry, device approval, logs, network flow logs, audit
- logs, webhooks/log streaming, update policy, incident diagnostics, and safe
- read-only commands.
+ Use these sources, in this order, for design and hard troubleshooting:
- ## Defaults
+ - Official docs at `tailscale.com/docs`. Append `.md` to a docs URL for clean
+ Markdown (for example `https://tailscale.com/docs/features/exit-nodes.md`);
+ pages carry a "Last validated" date. `https://tailscale.com/docs/llms.txt` is
+ a curated index and `https://tailscale.com/api` is the interactive API
+ reference; its OpenAPI spec is
+ `https://api.tailscale.com/api/v2?outputOpenapiSchema=true` (the endpoints
+ are stable unless noted, the spec document itself is not).
+ - The [changelog](https://tailscale.com/changelog) for client versions and
+ feature stages, [security bulletins](https://tailscale.com/security-bulletins),
+ the [blog](https://tailscale.com/blog), and health or console messages by ID
+ at `https://tailscale.com/docs/reference/messages`.
+ - GitHub issues and source in `tailscale/tailscale` (and `tailscale/tsidp`,
+ `tailscale/tailscale-skill`). Tailscale's own agent skill,
+ `tailscale/tailscale-skill`, is alpha and unsupported; treat it as another
+ community-grade source and verify it.
+ - r/Tailscale for field reports. The forum at `forum.tailscale.com` was sunset
+ in July 2023 and is a read-only archive: useful history, often stale.
- - For new access policy, prefer grants. Use legacy ACLs only when maintaining an
- existing ACL-only policy or when the needed behavior is not yet expressible in
- grants.
- - Treat `tailscale up` flags as a complete desired state. To change one
- preference, prefer `tailscale set` when available.
- - Keep route advertisement, route approval, client route acceptance, and access
- policy separate in explanations. Routing makes paths reachable; policy
- decides who may connect.
- - Treat auth keys, OAuth client secrets, and generated auth keys as secrets.
- Prefer tagged, ephemeral, short-lived, scoped automation identities.
- - For public exposure, make the Serve vs Funnel boundary explicit: Serve is
- tailnet-private; Funnel is internet-public.
- - Use dry runs, status commands, policy tests, and local config inspection
- before changing production tailnets.
+ ## Verify sources
- ## Gotchas To Surface Early
+ Treat community reports and archived forum threads as diagnostic leads, not
+ platform guarantees. Check dates, the whole thread, staff corrections, and later
+ releases. Confirm a claim against current docs, the installed CLI, the source,
+ or a disposable reproduction. When sources conflict, state the conflict and use
+ the narrower confirmed contract. Do not claim behavior was tested when only
+ help or docs were read.
- - `tailscale up` with flags requires the complete set of desired settings; an
- omitted setting can trigger an error or reset only with `--reset`.
- - Grants are preferred for new policy, but existing tailnets may still use ACLs.
- - Subnet routes, exit-node routing, app connector route injection, and access
- rules are separate control layers.
- - Serve and Funnel cannot both own the same node, DNS name, and port combination
- as private and public exposure at the same time.
- - Auth keys expire; connector or automation key expiry can fail closed.
- - MagicDNS and split DNS behavior depends on resolver setup and platform DNS
- integration.
- - DERP relay use is a performance and reachability fallback, not plaintext
- traffic. Tailscale traffic remains WireGuard-encrypted between nodes.
+ Check the release stage before recommending a feature. Alpha may break and has
+ no support obligation; beta is public, may still change, and has no support
+ obligation; only GA carries support and no breaking changes. The CLI marks
+ alpha and beta commands in `--help`. Do not put alpha or beta surfaces (for
+ example `tailscale switch`, `tailscale drive`, the Tailnets API, declarative
+ sharing, PAM) into production automation without a fallback, and re-check the
+ stage before each use. Confirm plan-dependent features against current plan pages.
- ## Output Style
+ ## Stay within the task
- When answering Tailscale tasks, include:
+ Reviews and investigations are read-only: use `status`, `netcheck`, `ping`,
+ `serve status`, `dns status`, `get`, and GET calls on the API. Do not run `up`,
+ `set`, `serve`, `funnel`, `logout`, `kubectl apply`, or policy or API writes
+ during a review. Ask before mutating a shared tailnet, its policy, keys, or remote
+ nodes. For authorized changes, validate with policy tests or a dry run first,
+ make the bounded change, and verify the resulting behavior.
- 1. The fastest viable path.
- 2. The security hardening path when relevant.
- 3. Exact commands, policy shape, Kubernetes manifests, or API calls.
- 4. The gotchas checked and any remaining risk.
+ ## Output
- Downrank dashboard-only instructions, stale CLI flags, broad tailnet access, and
- long-lived reusable keys unless the user explicitly asks for them.
+ Report the recommendation or change, exact commands, policy, manifests, or API
+ calls, the evidence (docs pages and versions checked), gotchas checked, and
+ remaining risks. Give the fastest viable path and, for organizations, the
+ hardening path. Downrank dashboard-only steps, stale
+ flags, broad tailnet access, and long-lived reusable keys unless asked.