How do I install the Headscale Backup skill?

Run npx skillmds@latest add magnus919/headscale-backup in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Headscale Backup safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: executes scripts. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Headscale Backup?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Headscale Backup free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Headscale Backup?

magnus919 (@magnus919) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Headscale Backup by magnus919 — Agent Skill

Name: Headscale Backup
Rating: 4.666666666666667 (3 reviews)
Author: magnus919

Headscale Backup

Backup, restore, and migrate Headscale installations — SQLite database, configuration file, policy file, and TLS certificates. Use when backing up a headscale server before upgrades, migrating to new hardware, or restoring from a disaster.

magnus919 33304d9 6 files · 37.9 KB Updated Sep 10, 2026

File contents

headscale-backup

Overview

Headscale state is stored in SQLite (its database), config.yaml, policy.json, and TLS certificates. Regular backups are critical before upgrades, as database corruption or misconfiguration can result in complete loss of node registration and routing state. This skill provides three scripts covering the full lifecycle: backup, restore, and migration.

Backup Contents

A complete backup tarball includes:

SQLite DB — Full node state, users, routes, pre-auth keys, API keys
config.yaml — Headscale server configuration
policy.json — ACL policy file (if present)
Certs and keys — TLS certificate, private key, and node private key (/var/lib/headscale/)
DERP map — DERP configuration file (if customized)

Backup Methods

sqlite3 .backup (recommended) — Safe for live databases; uses SQLite online backup API. This is what hs-backup.sh uses.
File copy (cp) — Requires stopping headscale first to avoid WAL corruption.

Restore

Stop headscale service
Restore files from backup tarball
Start headscale service
Verify with a health check or headscale nodes list

Migration

Backup on source host (or use an existing backup)
rsync or scp the backup tarball to the target host
Set up headscale on the target (same version)
Restore from backup on target
Update DNS to point to the new server
Verify clients reconnect

Version Compatibility

Source and target headscale versions should match exactly. Restoring a database from a different headscale version may cause schema migration failures or data corruption. Check versions with headscale version before migrating.

Automated Backups (Cron)

Set up a daily cron job:

0 2 * * * /path/to/hs-backup.sh --auto --output-dir /backups/headscale/

Gotchas

SQLite WAL mode: sqlite3 .backup is safe; cp of the database file while headscale is running will produce a corrupt copy.
Version mismatch: Restoring to a different headscale version may break schema migrations.
Node keys: If node keys change, all nodes must re-authenticate.
API keys: API keys are stored hashed in the database; restoring a DB backup does not recover the original key secrets — regenerate them with headscale apikeys create.
Pre-auth keys: Pre-auth keys are restored along with the database, but if they've expired they won't work.

Environment

HEADSCALE_URL — Headscale server URL
HEADSCALE_API_KEY — API key for health checks and validation

Trigger Conditions

"backup headscale"
"restore headscale"
"migrate headscale"
"headscale backup"

When not to use

Do not use this skill for deploying or configuring a Headscale server — load headscale-deploy instead, or headscale-node-lifecycle for node management. It covers backup, restore, and migration of an existing installation only.

---name: headscale-backupdescription: Backup, restore, and migrate Headscale installations — SQLite database, configuration file, policy file, and TLS certificates. Use when backing up a headscale server before upgrades, migrating to new hardware, or restoring from a disaster.---# headscale-backup## OverviewHeadscale state is stored in SQLite (its database), `config.yaml`, `policy.json`, and TLS certificates. Regular backups are critical before upgrades, as database corruption or misconfiguration can result in complete loss of node registration and routing state. This skill provides three scripts covering the full lifecycle: backup, restore, and migration.## Backup ContentsA complete backup tarball includes:- **SQLite DB** — Full node state, users, routes, pre-auth keys, API keys- **`config.yaml`** — Headscale server configuration- **`policy.json`** — ACL policy file (if present)- **Certs and keys** — TLS certificate, private key, and node private key (`/var/lib/headscale/`)- **DERP map** — DERP configuration file (if customized)## Backup Methods- **`sqlite3 .backup`** (recommended) — Safe for live databases; uses SQLite online backup API. This is what `hs-backup.sh` uses.- **File copy (`cp`)** — Requires stopping headscale first to avoid WAL corruption.## Restore1. Stop headscale service2. Restore files from backup tarball3. Start headscale service4. Verify with a health check or `headscale nodes list`## Migration1. Backup on source host (or use an existing backup)2. `rsync` or `scp` the backup tarball to the target host3. Set up headscale on the target (same version)4. Restore from backup on target5. Update DNS to point to the new server6. Verify clients reconnect## Version CompatibilitySource and target headscale versions **should match exactly**. Restoring a database from a different headscale version may cause schema migration failures or data corruption. Check versions with `headscale version` before migrating.## Automated Backups (Cron)Set up a daily cron job:```bash0 2 * * * /path/to/hs-backup.sh --auto --output-dir /backups/headscale/```## Gotchas- **SQLite WAL mode**: `sqlite3 .backup` is safe; `cp` of the database file while headscale is running will produce a corrupt copy.- **Version mismatch**: Restoring to a different headscale version may break schema migrations.- **Node keys**: If node keys change, all nodes must re-authenticate.- **API keys**: API keys are stored hashed in the database; restoring a DB backup does not recover the original key secrets — regenerate them with `headscale apikeys create`.- **Pre-auth keys**: Pre-auth keys are restored along with the database, but if they've expired they won't work.## Environment- `HEADSCALE_URL` — Headscale server URL- `HEADSCALE_API_KEY` — API key for health checks and validation## Trigger Conditions- "backup headscale"- "restore headscale"- "migrate headscale"- "headscale backup"## When not to useDo not use this skill for deploying or configuring a Headscale server — load `headscale-deploy` instead, or `headscale-node-lifecycle` for node management. It covers backup, restore, and migration of an existing installation only.

Frequently asked questions