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
- Aidas-dev/k8s-agent-skillstheir own version, first seen Nov 16, 2026
- usetemi/skillstheir own version, first seen Nov 8, 2026
- Rajveerx11/skillstheir own version, first seen Oct 25, 2026
- obra/muse-skillstheir own version, first seen Oct 13, 2026
- jacobwell/muse-skillstheir own version, first seen Sep 25, 2026
- pepebot-space/skillstheir own version, first seen Feb 16, 2026
Other versions6 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 6
- obra/muse-skills★ 20same name
- jacobwell/muse-skills★ 8same name
- usetemi/skills★ 6same name
- Aidas-dev/k8s-agent-skills★ 4same name
- pepebot-space/skills★ 2same name
- Rajveerx11/skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository192 other files it gives its agents.
- agent-production-operations/AGENTS.mdAGENTS.md
- AGENTS.mdAGENTS.md
- forward-deployed-engineering/AGENTS.mdAGENTS.md
- production-excellence/AGENTS.mdAGENTS.md
- product-lifecycle/AGENTS.mdAGENTS.md
- tailscale/AGENTS.mdAGENTS.md
- workflow-architect/AGENTS.mdAGENTS.md
- llms.txtllms.txt
- actuarial-risk-modelingSkill
- adr-authoringSkill
- agent-councilSkill
- agent-evals-and-observabilitySkill
- agent-production-operationsSkill
- agent-skillsSkill
- ai-governanceSkill
- ai-operating-economicsSkill
- amazon-memoSkill
- analog-occultismSkill
- anydocSkill
- api-design-and-evolutionSkill
- artifact-pyramidsSkill
- ascii-city-engineSkill
- autogenSkill
- backend-engineeringSkill
- binary-analysisSkill
- bmadSkill
- brand-designerSkill
- c4-diagrammingSkill
- camera-hackingSkill
- capacity-and-cost-engineeringSkill
- chief-of-staff-methodologySkill
- cli-builderSkill
- cncf-landscapeSkill
- code-reviewSkill
- color-managementSkill
- community-guidesSkill
- conditional-customer-successSkill
- confluence-cliSkill
- constrained-optimizationSkill
- crewaiSkill
- crmSkill
- crowdsecSkill
- cryptpadSkill
- cyberpunkSkill
- daily-life-discoverySkill
- data-architectSkill
- data-cleaningSkill
- data-engineeringSkill
- data-scientistSkill
- de-spinSkill
- digital-twinSkill
- docker-composeSkill
- documentsSkill
- dsm5Skill
- dspySkill
- electronicsSkill
- emailSkill
- enterprise-architectureSkill
- epubSkill
- esp32-developmentSkill
- The first 60 shown.
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
- Distinctive: line 25
Read security triage before enabling SSH, Serve, Funnel, app connectors, onboarding, or changing control-plane exposure.
- Distinctive: line 29
Do not reject hosted users seeking these protections merely because this bundle's administrative scripts target Headscale.
- Distinctive: line 34
Never enable Tailscale SSH as a convenience default.
- Very specific: line 41
When the user's message matches a trigger keyword, the corresponding sub-skill's SKILL.md is loaded.
- Distinctive: line 69
headscale-deploy: must be completed first — the others require a running Headscale server
- Distinctive: line 72
headscale-backup: should be run regularly on any production deployment
- Very specific: line 109
All scripts use --json, --dry-run, and have informative --help output.
“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.
Files
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 Keywords | Sub-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
| Script | Purpose | Invocation |
scripts/headscale-health-check.sh | Probe 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.sh | Create 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.sh | Validate 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.sh | Structured 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.sh | Smoke 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 TLStemplates/headscale-config.yaml— Annotated full headscale configurationtemplates/policy-allow-all.json— Minimal allow-all policytemplates/policy-deny-all.json— Locked-down deny-all policytemplates/policy-tagged-segmented.json— Tag-based access modeltemplates/derp-map.json— Custom DERP relay map
Environment Variables
| Variable | Used By | Purpose |
HEADSCALE_URL | All | Headscale server URL (e.g. https://headscale.example.com) |
HEADSCALE_API_KEY | All | Headscale API key (created via headscale apikeys create) |
TAILSCALE_AUTHKEY | tailscale-client | Pre-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, andcurlon the host running the scripts (percompatibility). - A running Headscale server with
HEADSCALE_URLandHEADSCALE_API_KEYset for server-side operations (API key created viaheadscale apikeys create);TAILSCALE_AUTHKEYfor non-interactive client enrollment. - The
tailscaleclient installed on target machines for status and routing sub-skills; theheadscaleCLI (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_SCRIPTto 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.
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
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.

