Tailscale

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.

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.

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

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.

Read the relevant reference

• Policy and security: 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: 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: Serve, Funnel, Tailscale

Services, identity and app-capabilities headers, HTTPS certificates, and tsidp (OIDC provider).

• Automation and API: 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: Docker

image, state and credentials, userspace networking, serverless, tailscaled on Linux servers (state storage, declarative config), and tsnet.

• Kubernetes: the Operator's ingress, egress, API

server proxy, Connector, ProxyGroup, ProxyClass, Recorder, multi-tailnet, PeerRelay, and sidecars without the Operator.

• Production diagnostics: 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 incident change discipline.

• Aperture: the AI gateway, client setup, the two

grant layers, config, MCP and HTTP connectors, and the CLI.

Load only the references the task needs; combine them for cross-cutting work.

Defaults and gotchas that span references

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

Research opportunities, not just syntax

Use these sources, in this order, for design and hard troubleshooting:

• 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 for client versions and

feature stages, security bulletins, the 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.

Verify sources

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.

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.

Stay within the task

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.

Output

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.