agentleFS
magnus919magnus919/agent-skills/tailscale/SKILL.md

tailscale

Skill177 starsChanged 4 months agoMITView on GitHub

Deploy and manage the self-hosted Tailscale/Headscale ecosystem: a Headscale control server, tailscale clients, ACL policies, node lifecycle, subnet routing, DERP relays, backup/migration, and Tailworm security exposure triage. Use when the user mentions Tailscale, Headscale, tailnet, mesh VPN, WireGuard mesh, or self-hosted VPN infrastructure. Do not use this skill for unrelated requests; route to the nearest named specialist.

  • Reads credentials

6 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 5 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 6 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read security triage before enabling SSH, Serve, Funnel, app connectors, onboarding, or changing control-plane exposure.

    line 25
  2. Distinctive:

    Do not reject hosted users seeking these protections merely because this bundle's administrative scripts target Headscale.

    line 29
  3. Distinctive:

    Never enable Tailscale SSH as a convenience default.

    line 34
  4. Very specific:

    When the user's message matches a trigger keyword, the corresponding sub-skill's SKILL.md is loaded.

    line 41
  5. Distinctive:

    headscale-deploy: must be completed first — the others require a running Headscale server

    line 69
  6. Distinctive:

    headscale-backup: should be run regularly on any production deployment

    line 72
  7. Very specific:

    All scripts use --json, --dry-run, and have informative --help output.

    line 109

“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Tailscale + Headscale Skill Bundle

This umbrella skill covers the self-hosted Tailscale ecosystem using Headscale as the open-source control server. It provides 7 sub-skills that are auto-loaded by context.

Security preflight

Read security triage before enabling SSH, Serve, Funnel, app connectors, onboarding, or changing control-plane exposure; also load it for Tailworm, suspected compromise, or hardening requests. Its shared client defenses apply to hosted Tailscale too; Headscale operations remain self-hosted only. Do not reject hosted users seeking these protections merely because this bundle's administrative scripts target Headscale.

Confirm the target, scope, and rollback path before acting. Read-only discovery may proceed without confirmation. Destructive containment (including device deletion) requires an explicit user directive. Never enable Tailscale SSH as a convenience default. Preserve and test another administrative access path before disabling it. Do not run public exploit kits on users' systems. Finish with an exposure inventory, supported mitigations, observed verification, and unresolved risks; stop when further verification needs unavailable evidence or authority.

Auto-Loading by Context

When the user's message matches a trigger keyword, the corresponding sub-skill's SKILL.md is loaded. Multiple sub-skills can load together when triggers overlap.

Trigger KeywordsSub-Skill(s) Loaded
"deploy headscale", "install headscale", "setup headscale server", "headscale config"headscale-deploy
"ACL", "policy file", "tailnet policy", "access control", "grant", "tag owners"tailnet-policy
"install tailscale", "connect to headscale", "tailscale client", "tailscale up", "tailscale status", "diagnose tailscale", "connectivity"tailscale-client
"auth key", "preauthkey", "register node", "approve node", "tag node", "node list", "decommission node"headscale-node-lifecycle
"subnet router", "exit node", "advertise route", "approve route"headscale-routing
"DERP", "relay", "peer relay", "STUN"headscale-derp
"backup headscale", "restore headscale", "migrate headscale", "headscale backup"headscale-backup
"Tailscale", "Headscale", "tailnet", "mesh VPN", "WireGuard mesh", "self-hosted VPN"Loads this umbrella SKILL.md for navigation

Sub-Skill Ordering & Dependencies

headscale-deploy ─────┬──> tailnet-policy ───> headscale-routing
                       │
                       ├──> headscale-node-lifecycle
                       │
                       ├──> tailscale-client
                       │
                       ├──> headscale-derp
                       │
                       └──> headscale-backup (prerequisite: a running headscale instance)
  • headscale-deploy must be completed first — the others require a running Headscale server
  • tailnet-policy (configures ACLs) is recommended before opening the tailnet to other users
  • headscale-derp is optional but recommended for reliability across NATs
  • headscale-backup should be run regularly on any production deployment

Root Scripts (Shared Utilities)

These live in scripts/ at the bundle root and are available to all sub-skills.

Available Scripts

ScriptPurposeInvocation
scripts/headscale-health-check.shProbe Headscale server health: version, node count, and DB integrity. Run it after any control-server change and as the first diagnostic when nodes or clients misbehave.scripts/headscale-health-check.sh --json
scripts/headscale-backup.shCreate a checksummed manifest-backed Headscale archive from configured SQLite and recovery paths. Run before upgrades or migrations; --dry-run previews without writing.scripts/headscale-backup.sh --dry-run --json
scripts/headscale-restore.shValidate and restore a supported manifest-backed archive to its recorded destinations. Run it during recovery; always verify node list and policy afterwards.scripts/headscale-restore.sh --backup headscale-backup-2026-01-01.tar.gz --dry-run --json
scripts/tailscale-status-json.shStructured wrapper around tailscale status --json with peer diagnostics. Run it from any client to check connectivity, peers, and relay/direct paths in machine-readable form.scripts/tailscale-status-json.sh
scripts/test-all.shSmoke test across all bundle scripts (--help, syntax, executability) without requiring a running Headscale. Run it after modifying any bundled script; CI runs it via scripts/check-skill-tests.py.bash scripts/test-all.sh

Templates

Templates live in templates/ and cover common deployment patterns:

  • templates/docker-compose-headscale.yaml — Headscale + embedded DERP + Traefik TLS
  • templates/headscale-config.yaml — Annotated full headscale configuration
  • templates/policy-allow-all.json — Minimal allow-all policy
  • templates/policy-deny-all.json — Locked-down deny-all policy
  • templates/policy-tagged-segmented.json — Tag-based access model
  • templates/derp-map.json — Custom DERP relay map

Environment Variables

VariableUsed ByPurpose
HEADSCALE_URLAllHeadscale server URL (e.g. https://headscale.example.com)
HEADSCALE_API_KEYAllHeadscale API key (created via headscale apikeys create)
TAILSCALE_AUTHKEYtailscale-clientPre-authenticated key for non-interactive client setup

Use the CLI tools

All scripts use --json, --dry-run, and have informative --help output. Scripts relative to bundle root: scripts/<tool> or skills/<sub-skill>/scripts/<tool>.

See the individual sub-skill SKILL.md for detailed usage.

Prerequisites

  • bash, Python 3.10+, jq, and curl on the host running the scripts (per compatibility).
  • A running Headscale server with HEADSCALE_URL and HEADSCALE_API_KEY set for server-side operations (API key created via headscale apikeys create); TAILSCALE_AUTHKEY for non-interactive client enrollment.
  • The tailscale client installed on target machines for status and routing sub-skills; the headscale CLI (or API access) for control-server administration.
  • For headscale-backup/restore: filesystem access to the server's sqlite DB, config, policy, and cert paths, plus storage for archives off the control-server host.
  • For migration: install the verified restore helper on the destination at the same path as the source helper, or set HEADSCALE_REMOTE_RESTORE_SCRIPT to the destination path; prepare the recorded archive paths and directory ownership before restoring.

Limitations

  • This bundle assumes a self-hosted Headscale control plane — it does not manage Tailscale's hosted SaaS (see When not to use).
  • Scripts check environment variables at runtime and error helpfully when missing; they do not create credentials themselves.
  • Backup/restore operates on the files present on the control-server host; it cannot recover data that was never backed up, and a restore should always be followed by health verification.
  • Restore accepts manifest version 1 archives and refuses older unmanifested tarballs. Migration requires the verified restore helper to be installed on the destination and does not fall back to raw extraction or report success without a verified restore result. Prepare the archived paths and target directory ownership before migration; root overrides that move files are rejected until config and service paths are separately updated and validated.
  • Sub-skill scripts live under skills/<sub-skill>/scripts/ and are documented in their own SKILL.md files, not here.

When not to use

Do not load this umbrella when a task maps to a single sub-skill — load the matching sub-skill directly (e.g. headscale-deploy, tailnet-policy, tailscale-client). It assumes a self-hosted Headscale control server; for hosted control-plane administration or non-Tailscale VPN tooling, use the appropriate network skill instead. Shared security triage above remains applicable to hosted Tailscale.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.