Agent skill

Headscale Deploy

Deploy, configure, and maintain a self-hosted Headscale control server on Linux or Docker.

Install Headscale Deploy

skills CLI

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

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

GitHub CLI

$ gh skill install magnus919/agent-skills headscale-deploy --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-deploy .claude/skills/headscale-deploy && 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/

Paste into Claude Code

Install the "headscale-deploy" agent skill from https://github.com/magnus919/agent-skills/tree/main/tailscale/skills/headscale-deploy into .claude/skills/headscale-deploy/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "headscale-deploy", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/magnus919/agent-skills/tree/main/tailscale/skills/headscale-deploy

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add magnus919/agent-skills --skill headscale-deploy -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install magnus919/agent-skills headscale-deploy --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

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

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "headscale-deploy" agent skill from https://github.com/magnus919/agent-skills/tree/main/tailscale/skills/headscale-deploy into .agents/skills/headscale-deploy/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "headscale-deploy", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add magnus919/agent-skills --skill headscale-deploy -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install magnus919/agent-skills headscale-deploy --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

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

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "headscale-deploy" agent skill from https://github.com/magnus919/agent-skills/tree/main/tailscale/skills/headscale-deploy into .cursor/skills/headscale-deploy/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "headscale-deploy", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/magnus919/agent-skills.git --path tailscale/skills/headscale-deploy

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add magnus919/agent-skills --skill headscale-deploy -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install magnus919/agent-skills headscale-deploy --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

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

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "headscale-deploy" agent skill from https://github.com/magnus919/agent-skills/tree/main/tailscale/skills/headscale-deploy into .gemini/skills/headscale-deploy/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "headscale-deploy", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install magnus919/agent-skills headscale-deploy

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add magnus919/agent-skills --skill headscale-deploy -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

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

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "headscale-deploy" agent skill from https://github.com/magnus919/agent-skills/tree/main/tailscale/skills/headscale-deploy into .github/skills/headscale-deploy/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "headscale-deploy", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add magnus919/agent-skills --skill headscale-deploy -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install magnus919/agent-skills headscale-deploy --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

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

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "headscale-deploy" agent skill from https://github.com/magnus919/agent-skills/tree/main/tailscale/skills/headscale-deploy into .opencode/skills/headscale-deploy/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "headscale-deploy", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: headscale-deploy
GitHub stars: 116
Token cost: ~1.3k tokens
SKILL.md length: 481 words
Files: 6 (incl. scripts)
Skills in repo: 130
Repo updated: Oct 8, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Deploy, configure, and maintain a self-hosted Headscale control server on Linux or Docker.

Works in 6 steps: Detecting platform (linux/amd64,… → Downloading the release tarball from… → Installing the binary to /usr/local/bin → …
Setting up a new Headscale instance
SKILL.md covers Overview, Prerequisites, Deployment Methods and Configuration, plus 4 more sections
Runs Shell scripts from its folder; calls curl and docker

What it does

Headscale Deploy is an agent skill from magnus919/agent-skills. Deploy, configure, and maintain a self-hosted Headscale control server on Linux or Docker. Use when setting up a new Headscale instance, troubleshooting deployment issues, or configuring server settings.

Its SKILL.md is about 1.3k tokens, which your agent loads only when the skill is triggered. The skill folder holds 7 other files, including scripts (for example `README.md`, `evals/evals.json` and `scripts/configure-derp.sh`). Compatibility notes: linux, docker

It sits in DevOps & Cloud, covering Deployment and Containers. It works with Linux and Docker. 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

Setting up a new Headscale instance
Troubleshooting deployment issues
Configuring server settings

Example prompts

“/headscale-deploy”

Requirements

A Bash shell
Docker
Compatibility (from SKILL.md): linux, docker

Workflow steps

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

Detecting platform (linux/amd64, linux/arm64)
Downloading the release tarball from GitHub
Installing the binary to /usr/local/bin
Creating the headscale system user
Writing a systemd unit file
Creating default config at /etc/headscale/config.yaml

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 3 files in scripts/ (Shell), which the agent can run.
Shell commands in SKILL.md call:
- curl
- docker
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use curl and docker, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Compatibility
linux, docker
From compatibility in the SKILL.md frontmatter.

Context cost

Headscale Deploy loads about 1.3k tokens when it runs. Until then it costs about 55 tokens; SKILL.md has 481 words of instructions outside code blocks.

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

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: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

NoteRuns commands with sudoSKILL.md:27

- Root or sudo access on the target machine

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). 481 words, ~1,252 tokens.

Download SKILL.mdSave it as .claude/skills/headscale-deploy/SKILL.md (or your agent's skills folder). This skill also uses 5 other files; get the full folder from GitHub.

name: headscale-deploy
description: Deploy, configure, and maintain a self-hosted Headscale control server on Linux or Docker. Use when setting up a new Headscale instance, troubleshooting deployment issues, or configuring server settings.
compatibility: linux, docker
license: MIT
metadata.tags: headscale, tailscale, wireguard, vpn, deployment, devops
metadata.spec-version: 1.0

headscale-deploy

Overview

Headscale is an open-source, self-hosted implementation of the Tailscale control server. It allows you to run your own coordination plane for WireGuard-based mesh networking, giving you full control over your tailnet without relying on Tailscale's SaaS infrastructure. The Tailscale client connects to Headscale transparently — no client modifications needed.

Use this skill to deploy Headscale from scratch, configure server settings, manage DERP relay infrastructure, and diagnose deployment issues.

Prerequisites

Linux server (x86_64 or aarch64) or Docker host with compose support
DNS record pointing to the server (A/AAAA record for server_url)
Ports 80/443 accessible from the internet (or your tailnet's ingress point)
Port 3478/udp for STUN (optional, needed for NAT traversal)
Root or sudo access on the target machine

Deployment Methods

Docker Compose (Recommended)

The fastest and most maintainable approach. Use install-headscale.sh with --docker flag to generate a compose file and systemd drop-in, or create manually:

yaml

version: "3.9"
services:
  headscale:
    image: headscale/headscale:latest
    container_name: headscale
    restart: unless-stopped
    ports:
      - "8080:8080"
      - "3478:3478/udp"
    volumes:
      - ./data:/var/lib/headscale
      - ./config:/etc/headscale
    command: headscale serve

Binary Install

Direct binary installation on the host for lightweight or container-free environments. The install-headscale.sh script handles:

Detecting platform (linux/amd64, linux/arm64)
Downloading the release tarball from GitHub
Installing the binary to /usr/local/bin
Creating the headscale system user
Writing a systemd unit file
Creating default config at /etc/headscale/config.yaml

Configuration

Key config.yaml options:

Option	Description	Example
`server_url`	Public URL of your Headscale instance	`https://headscale.example.com:443`
`listen_addr`	Local bind address	`0.0.0.0:8080`
`metrics_listen_addr`	Prometheus metrics endpoint	`127.0.0.1:9090`
`dns_config.base_domain`	MagicDNS domain suffix	`example.com`
`dns_config.magic_dns`	Enable MagicDNS	`true`
`derp.server.enabled`	Enable embedded DERP relay	`false`
`derp.server.region_id`	Numeric region ID	`999`
`derp.server.region_name`	Human-readable region name	`"my-headscale"`
`derp.urls`	External DERP map URLs	`[]`
`db_type`	Database backend: `sqlite3` or `postgres`	`sqlite3`
`tls_letsencrypt_hostname`	Auto TLS via Let's Encrypt	`""`
`tls_cert_path` / `tls_key_path`	Manual TLS cert paths	`""`

Verification

After deployment, verify the instance is healthy:

bash

# Quick health check
curl -s https://headscale.example.com/health

# Comprehensive diagnostics
headscale-health-check.sh --json

# Check registered nodes
headscale nodes list

# Verify API access
headscale apikeys list

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

Gotchas

SQLite vs PostgreSQL: SQLite is fine for small tailnets (<100 nodes). For larger deployments or high-availability, use PostgreSQL. Plan your choice upfront — migration is non-trivial.
TLS certificate management: Let's Encrypt auto-provisioning is convenient but requires port 80 to be accessible for the HTTP-01 challenge. Use a reverse proxy (Caddy, Nginx, Traefik) for more flexibility.
Port conflicts: If port 8080 or 3478 is already in use, change listen_addr in config. Ensure no other service binds port 3478/udp for STUN.
DERP configuration: The embedded DERP relay works for small deployments. For production, set up dedicated DERP nodes to avoid single-region bottlenecks.
Configuration reload: Headscale does not hot-reload config. Restart the service after config changes: systemctl restart headscale or docker compose restart.
Database backups: Always back up /var/lib/headscale/db.sqlite3 (or your PostgreSQL DB) regularly.

Trigger Conditions

Use this skill when the user says any of:

"deploy headscale"
"install headscale"
"setup headscale server"
"headscale config"
"headscale configuration"
"headscale deployment"
"headscale health"
"headscale derp"
"self-hosted tailscale"
"tailscale control server"

When not to use

Do not use this skill for client-side setup (load tailscale-client instead), for ACL/policy authoring (load tailnet-policy), or for day-to-day management of an already-running server. It covers initial deployment and server configuration only.

Files

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

SKILL.md
README.md
evals/evals.json
scripts/configure-derp.sh
scripts/headscale-health-check.sh
scripts/install-headscale.sh

Open the folder on GitHubat commit c545c2b

Compare with similar skills

Headscale Deploy 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 Deploy compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Headscale Deploy this skillmagnus919/agent-skills	116	—	~1.3k	Automated safety check: Notes	MIT	yesterday
Setup Workshopbrevdev/workshop-build-an-agent	146	—	~2.3k	Automated safety check: Notes	Apache-2.0	yesterday
Investigate Production Container Restartsblotcms/blot	2k	—	~4.7k	Automated safety check: Pass	AGPL-3.0	today
Frappe Ops DeploymentImpertio-Studio/Frappe_Claude_Skill_Package	188	—	~2.4k	Automated safety check: Notes	MIT	22 days ago
Self-Hosted n8n Deploymentczlonkowski/n8n-skills	6.4k	—	~3.5k	Automated safety check: Notes	MIT	23 days ago
GreptimeDB Dev Docker ImageGreptimeTeam/greptimedb	6.7k	—	~4k	Automated safety check: Notes	Apache-2.0	today

Similar skills

Setup Workshop
brevdev/workshop-build-an-agent
This skill should be used when the user wants to set up, install, deploy, bootstrap, or "spin up" the Build-an-Agent workshop (a.k.a.
146 GitHub stars~2.3k tokensUpdated yesterday
DevOps & CloudAuto-check: notes
Investigate Production Container Restarts
blotcms/blot
Work out why the blot-container-{blue,green,yellow} Docker containers from the most recent production deployment have restarted — distinguishing a normal deploy-triggered restart from a crash (V8…
2k GitHub stars~4.7k tokensUpdated today
DevOps & CloudAuto-check passed
Frappe Ops Deployment
Impertio-Studio/Frappe_Claude_Skill_Package
A skill your agent uses when deploying Frappe/ERPNext to production, configuring Nginx or Supervisor, setting up Docker, enabling SSL, or hardening security.
188 GitHub stars~2.4k tokensUpdated 22 days ago
DevOps & CloudAuto-check: notes
Self-Hosted n8n Deployment
czlonkowski/n8n-skills
Deploys a production n8n instance to a fresh Linux server over SSH with Docker Compose and Caddy HTTPS, in single or queue mode, and covers updates, backups and hardening.
6.4k GitHub stars~3.5k tokensUpdated 23 days ago
DevOps & CloudAuto-check: notes
GreptimeDB Dev Docker Image
GreptimeTeam/greptimedb
Packages a locally built GreptimeDB debug binary into a development-only Docker image for local-cluster testing, with an optional push to a dev registry.
6.7k GitHub stars~4k tokensUpdated today
DevOps & CloudAuto-check: notes
Senior DevOps Toolkit
maslennikov-ig/claude-code-orchestrator-kit
Comprehensive DevOps skill for CI/CD, infrastructure automation, containerization, and cloud platforms (AWS, GCP, Azure). Includes pipeline setup…
260 GitHub starsUsed in 6 repos~1.1k tokens
DevOps & CloudAuto-check: notes

Questions about Headscale Deploy

What does Headscale Deploy do?

Deploy, configure, and maintain a self-hosted Headscale control server on Linux or Docker. Headscale Deploy is an agent skill from magnus919/agent-skills. Deploy, configure, and maintain a self-hosted Headscale control server on Linux or Docker.

When should I use Headscale Deploy?

Headscale Deploy fits situations like: setting up a new Headscale instance; troubleshooting deployment issues; configuring server settings.

How do I install Headscale Deploy in Claude Code?

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

How do I install Headscale Deploy in Codex?

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

Can I use Headscale Deploy 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-deploy -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-deploy, .gemini/skills/headscale-deploy, .github/skills/headscale-deploy and .opencode/skills/headscale-deploy in your project.

What does Headscale Deploy need to run?

Going by SKILL.md and its folder, Headscale Deploy needs a shell for the scripts in its folder and the command-line tools its instructions call (curl and docker). Our summary lists: A Bash shell; Docker. Compatibility (from SKILL.md): linux, docker.

Does Headscale Deploy access the network?

SKILL.md contains no URLs. Its commands use curl and docker, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Headscale Deploy safe to install?

Our automated static check of SKILL.md found notes only (runs commands with sudo), nothing it rates as a warning. 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 Deploy use?

Headscale Deploy is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Headscale Deploy use?

About 1.3k tokens (SKILL.md is roughly 5k 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 Deploy?

Skills that share tags, products or a category with Headscale Deploy: Setup Workshop (brevdev/workshop-build-an-agent, 146 stars), Investigate Production Container Restarts (blotcms/blot, 2k stars), Frappe Ops Deployment (Impertio-Studio/Frappe_Claude_Skill_Package, 188 stars) and Self-Hosted n8n Deployment (czlonkowski/n8n-skills, 6.4k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Headscale Deploy?

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.

Install Headscale Deploy

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Compatibility

Context cost

Safety

SKILL.md

headscale-deploy

Overview

Prerequisites

Deployment Methods

Docker Compose (Recommended)

Binary Install

Configuration

Verification

Gotchas

Trigger Conditions

When not to use

Files

Compare with similar skills

Similar skills

More from magnus919/agent-skills

Related

Questions about Headscale Deploy