tailscale
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.
How do I install this agent skill?
npx skills add https://github.com/magnus919/agent-skills --skill tailscaleIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill bundle provides a robust set of tools for deploying and managing a self-hosted Tailscale (Headscale) VPN. It includes utilities for server deployment, ACL policy authoring, node registration, and manifest-backed backups. While the skill requires administrative privileges (sudo) and access to sensitive network configuration files, its behavior is consistent with its stated purpose, and it uses secure practices like checksum verification for archives and official download sources.
- Socketwarn
3 alerts: gptAnomaly
- Snykwarn
Risk: MEDIUM · 2 issues
What does this agent skill do?
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 | Offline help and syntax smoke for bundle entry points. CI runs it via scripts/check-skill-tests.py. The skill-local pytest suite checks root backup and restore previews using temporary fixtures; run relay latency checks manually. | 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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/magnus919/agent-skills/tailscale">View tailscale on skillZs</a>