New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Headscale Backup

by magnus919 in magnus919/agent-skills

Manage Headscale backups, restores, or migrations with a verified SQLite snapshot and explicit recovery paths before upgrades, host moves, or disaster recovery; do not use for server deployment…

MITAuto-check passedDevOps & Cloud

Install Headscale Backup

skills CLI
$ npx skills add magnus919/agent-skills --skill headscale-backup -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install magnus919/agent-skills headscale-backup --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/magnus919/agent-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/tailscale/skills/headscale-backup .claude/skills/headscale-backup && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
headscale-backup
GitHub stars
116
Token cost
~1.4k tokens
SKILL.md length
727 words
Files
8 (incl. scripts)
Skills in repo
130
Repo updated
First seen
Licence
MIT

At a glance

Manage Headscale backups, restores, or migrations with a verified SQLite snapshot and explicit recovery paths before upgrades, host moves, or disaster recovery; do not use for server deployment…

  • Works in 5 steps: Stop headscale service → Preview the mapped restore paths with… → Restore files from backup tarball with… → …
  • Server deployment
  • SKILL.md covers Overview, Backup Contents, Backup Methods and Restore, plus 7 more sections
  • Runs Shell and Python scripts from its folder; calls sqlite3; needs HEADSCALE_API_KEY

What it does

Headscale Backup is an agent skill from magnus919/agent-skills. Manage Headscale backups, restores, or migrations with a verified SQLite snapshot and explicit recovery paths before upgrades, host moves, or disaster recovery; do not use for server deployment, routine node management, or PostgreSQL backups.

Its SKILL.md is about 1.4k tokens, which your agent loads only when the skill is triggered. The skill folder holds 9 other files, including scripts (for example `README.md`, `evals/evals.json` and `scripts/hs-archive.py`).

It sits in DevOps & Cloud, covering Backup and disaster recovery. It works with SQLite and PostgreSQL. The repository describes itself as: Curated collection of AI agent skills for Hermes and other agent frameworks. The licence is MIT.

When your agent uses it

  • Server deployment
  • Routine node management
  • PostgreSQL backups

Example prompts

  • “/headscale-backup”

Requirements

  • Python 3
  • A Bash shell
  • A credential in HEADSCALE_API_KEY

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

  1. Stop headscale service
  2. Preview the mapped restore paths with hs-restore.sh --backup --dry-run --json
  3. Restore files from backup tarball with hs-restore.sh --backup
  4. Start headscale service
  5. Verify with a health check or headscale nodes list

What it can do on your machine

Read from SKILL.md and the folder at commit c545c2b. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 5 files in scripts/ (Shell and Python), which the agent can run.

    Shell commands in SKILL.md call:

    • sqlite3

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names these keys or tokens, usually read from environment variables:

    • HEADSCALE_API_KEY

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Headscale Backup loads about 1.4k tokens when it runs. Until then it costs about 65 tokens; SKILL.md has 727 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~65
When it runs · the whole SKILL.md, loaded when a task matches
~1.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from magnus919/agent-skills at commit c545c2b, republished under its MIT licence (© magnus919). 727 words, ~1,414 tokens.

Download SKILL.mdSave it as .claude/skills/headscale-backup/SKILL.md (or your agent's skills folder). This skill also uses 7 other files; get the full folder from GitHub.
name
headscale-backup
description
Manage Headscale backups, restores, or migrations with a verified SQLite snapshot and explicit recovery paths before upgrades, host moves, or disaster recovery; do not use for server deployment, routine node management, or PostgreSQL backups.
metadata.category
devops

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.

Before creating an archive or restoring files, confirm the target, scope, and rollback path. Read-only discovery and --dry-run previews may proceed without confirmation.

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 and key, Headscale node private key, and configured DERP server private key
  • 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.

hs-backup.sh reads the database path and optional policy, TLS, node-key, DERP key, and DERP map paths from config.yaml. It supports database.sqlite.path, database.path, and the legacy database_path setting. PostgreSQL configurations are rejected. TLS certificates and keys are included only when configured explicitly (or found in the configured standard /etc/headscale locations); the helper does not scan unrelated Let's Encrypt certificates. The resulting archive contains a manifest with SHA-256 checksums, file modes, and restore destinations. Restore verifies every declared asset before it asks to overwrite files. It preserves the recorded destinations by default. Root overrides that would move any asset are rejected because the config or service may still point at archived paths. A migration to different paths requires a separate planned config update and validation before restore.

Restore

Before the first restore write, confirm the target host and mapped paths, the set of files to replace, and the rollback archive or recovery route. A dry run is read-only and can be used without confirmation.

  1. Stop headscale service
  2. Preview the mapped restore paths with hs-restore.sh --backup <archive> --dry-run --json
  3. Restore files from backup tarball with hs-restore.sh --backup <archive>
  4. Start headscale service
  5. Verify with a health check or headscale nodes list

The wrapper stops and restarts an active systemd or SysV service around a restore. For isolated tests only, set HEADSCALE_SKIP_SERVICE_CONTROL=1; this is intended for disposable fixtures and does not make a production restore safe to run while Headscale is active. Restored files keep the ownership of an existing destination; for a new file, the helper uses the destination directory's owner and group. On a new host, prepare directories with the ownership expected by the Headscale service before restoring. If a restore fails after stopping the service, the helper leaves it stopped to avoid running with mixed state.

Show full SKILL.md (273 more words)Show less

Migration

  1. Backup on source host (or use an existing backup)
  2. rsync or scp the backup tarball to the target host
  3. Set up headscale on the target (same version)
  4. Restore from backup on target
  5. Update DNS to point to the new server
  6. 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:

bash
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

HEADSCALE_CONFIG, HEADSCALE_DATA_DIR, HEADSCALE_CERTS_DIR, HEADSCALE_CONFIG_DIR, and HEADSCALE_SERVICE override the corresponding script defaults. For migration, HEADSCALE_REMOTE_RESTORE_SCRIPT names the verified restore helper path installed on the destination host; the default uses the same path as the local script.

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.

© magnus919, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 7 other files (scripts) in tailscale/skills/headscale-backup of magnus919/agent-skills.

  • SKILL.md
  • README.md
  • evals/evals.json
  • scripts/hs-archive.py
  • scripts/hs-backup.sh
  • scripts/hs-migrate.sh
  • scripts/hs-restore.sh
  • scripts/test_hs_archive.py

Open the folder on GitHubat commit c545c2b

Compare with similar skills

Headscale Backup next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Headscale Backup compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Headscale Backup this skillmagnus919/agent-skills116—~1.4kAutomated safety check: PassMIT
Monstermq Broker Configvogler75/monster-mq143—~2.2kAutomated safety check: PassGPL-3.0
Mg Local DB Restoremodelguide/modelguide108—~645Automated safety check: PassMIT
Azure Resource Manager Postgresql Dotnetmicrosoft/skills3.1k5 repos~4kAutomated safety check: PassMIT
Database Adminaiskillstore/marketplace4307 repos~2.5kAutomated safety check: PassNone
Planetscale Postgres Safety Reviewplanetscale/skills133—~2.4kAutomated safety check: PassMIT

Similar skills

  • Monstermq Broker Config

    vogler75/monster-mq

    Guide for configuring, deploying, and operating the MonsterMQ broker.

    143 GitHub stars~2.2k tokensUpdated today
    DevOps & CloudAuto-check passed

  • Mg Local DB Restore

    modelguide/modelguide

    Trigger phrases - "reset local db", "recreate local postgres", "restore dump to local", "reset local database", "load backup locally"

    108 GitHub stars~645 tokensUpdated 3 mo ago
    DevOps & CloudAuto-check passed

  • Azure Resource Manager Postgresql Dotnet

    microsoft/skills

    Official

    Azure PostgreSQL Flexible Server SDK for .NET. An agent skill from microsoft/skills.

    3.1k GitHub starsUsed in 5 repos~4k tokens
    DevOps & CloudAuto-check passed

  • Database Admin

    aiskillstore/marketplace

    Expert database administrator specializing in modern cloud databases, automation, and reliability engineering.

    430 GitHub starsUsed in 7 repos~2.5k tokens
    DevOps & CloudAuto-check passed

  • Planetscale Postgres Safety Review

    planetscale/skills

    Official

    Review PlanetScale Postgres for Traffic Control, query tags, roles, pgstrict, backups/PITR, private connectivity, webhooks, branches, and safe agent operation.

    133 GitHub stars~2.4k tokensUpdated today
    DevOps & CloudAuto-check passed

  • Automating Database Backups

    jeremylongshore/tons-of-skills-marketplace

    Automate database backup processes with scheduling, compression, and encryption.

    2.8k GitHub stars~1.5k tokensUpdated yesterday
    DatabasesAuto-check passed

More from magnus919/agent-skills

All 130 skills in this repo

  • Artifact Pyramids

    magnus919/agent-skills

    Organize durable agent research outputs as summaries, analysis, and evidence dossiers.

    116 GitHub stars~2.7k tokensUpdated yesterday
    Auto-check passed

  • Ascii City Engine

    magnus919/agent-skills

    Build portable, first-person colored ASCII city engines and small GIS-derived city packs.

    116 GitHub stars~1.1k tokensUpdated yesterday
    Auto-check passed

  • Color Management

    magnus919/agent-skills

    Manage color workflows with ICC profiles, working spaces, gamut mapping, and color science.

    116 GitHub stars~2.6k tokensUpdated yesterday
    Auto-check: notes

  • Data Scientist

    magnus919/agent-skills

    A skill your agent uses for PhD-level expertise in data science, statistics, and machine learning: rigorous statistical analysis, experimental design, causal inference, advanced modeling, research…

    116 GitHub stars~4.1k tokensUpdated yesterday
    Auto-check passed

  • Docker Compose

    magnus919/agent-skills

    Use Docker Compose to define, run, debug, and harden multi-container applications.

    116 GitHub stars~2k tokensUpdated yesterday
    Auto-check: notes

  • Fpga Development

    magnus919/agent-skills

    Design, review, simulate, and verify FPGA logic using explicit RTL contracts, clock and reset models, CDC analysis, timing constraints, and reproducible implementation evidence.

    116 GitHub stars~2.7k tokensUpdated yesterday
    Auto-check passed

Works with

Categories

Questions about Headscale Backup

What does Headscale Backup do?

Manage Headscale backups, restores, or migrations with a verified SQLite snapshot and explicit recovery paths before upgrades, host moves, or disaster recovery; do not use for server deployment…. Headscale Backup is an agent skill from magnus919/agent-skills. Manage Headscale backups, restores, or migrations with a verified SQLite snapshot and explicit recovery paths before upgrades, host moves, or disaster recovery; do not use for server deployment, routine node management, or PostgreSQL backups.

When should I use Headscale Backup?

Headscale Backup fits situations like: server deployment; routine node management; postgreSQL backups.

How do I install Headscale Backup in Claude Code?

Run `npx skills add magnus919/agent-skills --skill headscale-backup -a claude-code`. Or copy the skill folder (tailscale/skills/headscale-backup in magnus919/agent-skills) into .claude/skills/headscale-backup in your project. Claude Code loads it when a task matches its description.

How do I install Headscale Backup in Codex?

Run `npx skills add magnus919/agent-skills --skill headscale-backup -a codex`. Or copy the skill folder (tailscale/skills/headscale-backup in magnus919/agent-skills) into .agents/skills/headscale-backup in your project. Codex loads it when a task matches its description.

Can I use Headscale Backup in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add magnus919/agent-skills --skill headscale-backup -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/headscale-backup, .gemini/skills/headscale-backup, .github/skills/headscale-backup and .opencode/skills/headscale-backup in your project.

What does Headscale Backup need to run?

Going by SKILL.md and its folder, Headscale Backup needs a shell and Python for the scripts in its folder, the command-line tools its instructions call (sqlite3) and credentials named HEADSCALE_API_KEY. Our summary lists: Python 3; A Bash shell; A credential in HEADSCALE_API_KEY.

Does Headscale Backup access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Headscale Backup safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Headscale Backup use?

Headscale Backup is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Headscale Backup use?

About 1.4k tokens (SKILL.md is roughly 5.7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Headscale Backup?

Skills that share tags, products or a category with Headscale Backup: Monstermq Broker Config (vogler75/monster-mq, 143 stars), Mg Local DB Restore (modelguide/modelguide, 108 stars), Azure Resource Manager Postgresql Dotnet (microsoft/skills, 3.1k stars) and Database Admin (aiskillstore/marketplace, 430 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Headscale Backup?

magnus919 (a GitHub user) maintains it in magnus919/agent-skills, which has 116 GitHub stars. The repository holds 130 skills in this directory. The repository was last updated on October 8, 2026.

Source: magnus919/agent-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.