Agent skill

Headscale Derp

Configure and manage DERP relay servers for Tailscale/Headscale — embedded and standalone DERP deployment, latency testing, and connectivity diagnostics.

MITAuto-check passedDevOps & Cloud

Install Headscale Derp

skills CLI

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

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

GitHub CLI

$ gh skill install magnus919/agent-skills headscale-derp --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-derp .claude/skills/headscale-derp && 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-derp" agent skill from https://github.com/magnus919/agent-skills/tree/main/tailscale/skills/headscale-derp into .claude/skills/headscale-derp/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "headscale-derp", 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-derp

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-derp -a codex

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

GitHub CLI

$ gh skill install magnus919/agent-skills headscale-derp --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-derp .agents/skills/headscale-derp && 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-derp" agent skill from https://github.com/magnus919/agent-skills/tree/main/tailscale/skills/headscale-derp into .agents/skills/headscale-derp/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "headscale-derp", 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-derp -a cursor

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

GitHub CLI

$ gh skill install magnus919/agent-skills headscale-derp --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-derp .cursor/skills/headscale-derp && 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-derp" agent skill from https://github.com/magnus919/agent-skills/tree/main/tailscale/skills/headscale-derp into .cursor/skills/headscale-derp/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "headscale-derp", 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-derp

--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-derp -a gemini-cli

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

GitHub CLI

$ gh skill install magnus919/agent-skills headscale-derp --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-derp .gemini/skills/headscale-derp && 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-derp" agent skill from https://github.com/magnus919/agent-skills/tree/main/tailscale/skills/headscale-derp into .gemini/skills/headscale-derp/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "headscale-derp", 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-derp

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-derp -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-derp .github/skills/headscale-derp && 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-derp" agent skill from https://github.com/magnus919/agent-skills/tree/main/tailscale/skills/headscale-derp into .github/skills/headscale-derp/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "headscale-derp", 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-derp -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-derp --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-derp .opencode/skills/headscale-derp && 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-derp" agent skill from https://github.com/magnus919/agent-skills/tree/main/tailscale/skills/headscale-derp into .opencode/skills/headscale-derp/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "headscale-derp", 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-derp
GitHub stars: 115
Token cost: ~1.4k tokens
SKILL.md length: 581 words
Files: 6 (incl. scripts)
Skills in repo: 131
Repo updated: Oct 10, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Configure and manage DERP relay servers for Tailscale/Headscale — embedded and standalone DERP deployment, latency testing, and connectivity diagnostics.

Works in 3 steps: Let's Encrypt (auto) — tailscale/derper… → Manual certs — Pass… → Reverse proxy — Terminate TLS at a…
Direct peer connections fail
SKILL.md covers Overview, DERP in Headscale, DERP Map and Connectivity Testing, plus 6 more sections
Runs Shell and Python scripts from its folder; calls docker

What it does

Headscale Derp is an agent skill from magnus919/agent-skills. Configure and manage DERP relay servers for Tailscale/Headscale — embedded and standalone DERP deployment, latency testing, and connectivity diagnostics. Use when direct peer connections fail, traffic is routed through DERP relays, or setting up custom relay regions.

Its SKILL.md is about 1.4k 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/deploy-derp.sh`).

It sits in DevOps & Cloud. 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

Direct peer connections fail
Traffic is routed through DERP relays
Setting up custom relay regions

Example prompts

“/headscale-derp”

Requirements

Python 3
A Bash shell
Docker

Workflow steps

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

Let's Encrypt (auto) — tailscale/derper supports automatic certificate issuance via Let's Encrypt. It listens on port 80 for the ACME…
Manual certs — Pass --cert=/path/to/cert.pem --key=/path/to/key.pem to the derper binary.
Reverse proxy — Terminate TLS at a reverse proxy (nginx, Caddy, Traefik) and forward to the local DERP port.

What it can do on your machine

Read from SKILL.md and the folder at commit 22b4723. 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 and Python), which the agent can run.
Shell commands in SKILL.md call:
- docker
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use 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.

Context cost

Headscale Derp loads about 1.4k tokens when it runs. Until then it costs about 71 tokens; SKILL.md has 581 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~71
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 22b4723, republished under its MIT licence (© magnus919). 581 words, ~1,436 tokens.

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

name: headscale-derp
description: Configure and manage DERP relay servers for Tailscale/Headscale — embedded and standalone DERP deployment, latency testing, and connectivity diagnostics. Use when direct peer connections fail, traffic is routed through DERP relays, or setting up custom relay regions.
metadata.category: devops

headscale-derp Skill

Overview

DERP = Designated Encrypted Relay Protocol. DERP is Tailscale's TURN-like fallback mechanism used when direct peer-to-peer NAT traversal fails. Traffic through DERP is fully encrypted (WireGuard inside TLS), but it routes through a relay server rather than directly between peers, so it introduces additional latency.

Common scenarios where DERP is used:

Symmetric NAT — Both peers behind symmetric NAT gateways
Corporate firewalls — Restrictive egress policies that block UDP/STUN
Double NAT — Carrier-grade NAT on both sides
Blocked STUN — UDP port 3478 is filtered

DERP in Headscale

Headscale includes an embedded DERP server that is enabled by default in the config.yaml:

yaml

derp:
  server:
    enabled: true
    region_id: 999
    region_code: "headscale"
    region_name: "Headscale Embedded DERP"
    stun_listen_addr: "0.0.0.0:3478"
    private_key_path: "/var/lib/headscale/derp_server_private.key"

The embedded server runs a STUN endpoint on port 3478 and relays on port 443 (or whatever port Headscale listens on). It's suitable for small tailnets (under ~50 nodes).

Key config options

Option	Default	Description
`derp.server.enabled`	`true`	Enable the embedded DERP server
`derp.server.region_id`	`999`	Numeric region identifier (must be unique across all regions)
`derp.urls`	`[]`	Additional DERP map URLs (for standalone servers)
`derp.paths`	`[]`	Local DERP map JSON file paths
`derp.auto_update`	`true`	Automatically fetch Tailscale's default DERP map
`derp.stun_listen_addr`	`0.0.0.0:3478`	STUN listener address

DERP Map

A DERP map is a JSON structure that defines relay regions and nodes. Example:

json

{
  "Regions": {
    "900": {
      "RegionID": 900,
      "RegionCode": "us-nyc",
      "RegionName": "New York",
      "Nodes": [
        {
          "Name": "900a",
          "RegionID": 900,
          "HostName": "derp-nyc.example.com",
          "DERPPort": 443,
          "STUNPort": 3478,
          "STUNOnly": false
        }
      ]
    }
  }
}

The DERP map can be served via HTTPS URL (put in derp.urls) or as a local JSON file (put in derp.paths).

Connectivity Testing

Run tailscale netcheck to see which DERP regions are reachable and their latency:

$ tailscale netcheck
Report:
    * UDP: true
    * IPv4: yes
    * IPv6: no
    * MappingVariesByDestIP: true
    * HairPinning: false
    * PortMapping: UPnP
    * Nearest DERP: Dallas
    * DERP latency:
        - dallas: 18ms (dallas)
        - us-west: 35ms (us-west)
        - new-york-city: 5ms (new-york-city)
        - london: 85ms (london)

Standalone DERP

For larger tailnets or dedicated relay capacity, run a standalone DERP server using the official tailscale/derper Docker image:

bash

docker run -d \
  --name=derper \
  --restart=always \
  -p 3478:3478/udp \
  -p 443:443 \
  -v /etc/letsencrypt:/certs \
  -v /var/lib/derper:/var/lib/derper \
  tailscale/derper \
  --hostname=derp.example.com

TLS Certificates

DERP requires TLS. Recommended approaches:

Let's Encrypt (auto) — tailscale/derper supports automatic certificate issuance via Let's Encrypt. It listens on port 80 for the ACME HTTP-01 challenge.
Manual certs — Pass --cert=/path/to/cert.pem --key=/path/to/key.pem to the derper binary.
Reverse proxy — Terminate TLS at a reverse proxy (nginx, Caddy, Traefik) and forward to the local DERP port.

Region Selection

Tailscale clients automatically select the DERP region with the lowest latency. The selection algorithm:

Sends STUN requests to all configured DERP regions
Measures round-trip time for each
Picks the region with the lowest latency
Falls back to the next-closest region if connectivity fails

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

Gotchas

DERP is encrypted but slower — All DERP traffic is WireGuard-inside-TLS, adding ~5-15ms overhead. Direct connections are always preferred.
Embedded DERP works for small tailnets — The embedded server in Headscale uses the same Headscale process for relaying. Under heavy relay traffic, it can impact Headscale control-plane performance. For >50 nodes doing active relay, deploy a standalone DERP.
All traffic routes through DERP if STUN is blocked — If UDP port 3478 is blocked anywhere in the network path, Tailscale cannot establish direct peer-to-peer connections and will route ALL traffic through the nearest DERP relay.
Port 3478 (STUN) and 443 (DERP) must be open — STUN uses UDP for NAT traversal probing; DERP uses TCP/TLS for relay traffic. Both must be reachable from clients.
Multiple regions improve resilience — Deploy DERP relays in at least two geographically diverse locations so clients have a fallback.
DERP map caching — Clients cache the DERP map. If you add a new region, it can take up to 5 minutes for clients to pick it up. Use tailscale netcheck to force a refresh.

Trigger Conditions

This skill is activated by keywords: DERP, relay, peer relay, STUN, direct connection failed

When not to use

Do not use this skill when direct peer connections work — DERP tuning is only needed when NAT traversal fails. For general client connectivity diagnostics, load tailscale-client instead.

Files

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

SKILL.md
README.md
evals/evals.json
scripts/deploy-derp.sh
scripts/derp-health-check.py
scripts/test-derp-latency.sh

Open the folder on GitHubat commit 22b4723

Compare with similar skills

Headscale Derp 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 Derp compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Headscale Derp this skillmagnus919/agent-skills	115	—	~1.4k	Automated safety check: Pass	MIT	today
Monitor CInrwl/nx	29k	6 repos	~4.7k	Automated safety check: Pass	MIT	today
Terraform and OpenTofu Guideagentscope-ai/QwenPaw	36k	6 repos	~4.2k	Automated safety check: Pass	Apache-2.0	today
Vercel Optimize Auditvercel-labs/agent-skills	32k	8 repos	~4.3k	Automated safety check: Pass	None	1 mo ago
Analyze GitHub Action Logswithastro/astro	63k	1 repos	~1.3k	Automated safety check: Pass	Custom licence	today
Openclaw Live Updateropenclaw/openclaw	392k	—	~3.7k	Automated safety check: Pass	MIT	today

Similar skills

Monitor CI
nrwl/nx
Monitor Nx Cloud CI pipeline and handle self-healing fixes. An agent skill from nrwl/nx.
29k GitHub starsUsed in 6 repos~4.7k tokens
DevOps & CloudAuto-check passed
Terraform and OpenTofu Guide
agentscope-ai/QwenPaw
Guidance for writing and testing Terraform and OpenTofu code: module structure, naming, test approaches, CI/CD workflows, state handling and security scanning.
36k GitHub starsUsed in 6 repos~4.2k tokens
DevOps & CloudAuto-check passed
Vercel Optimize Audit
vercel-labs/agent-skills
Official
Runs a metrics-first audit of a deployed Vercel project, gating investigations on real signals to produce ranked, citation-backed cost and performance recommendations.
32k GitHub starsUsed in 8 repos~4.3k tokens
DevOps & CloudAuto-check passed
Analyze GitHub Action Logs
withastro/astro
Official
Analyze recent GitHub Actions workflow runs to identify patterns, mistakes, and improvements.
63k GitHub starsUsed in 1 repo~1.3k tokens
DevOps & CloudAuto-check passed
Openclaw Live Updater
openclaw/openclaw
Maintain the canonical live OpenClaw main checkout, macOS LaunchAgent-managed Gateway, local macOS app, exact-head main CI, and recurring full release validation.
392k GitHub stars~3.7k tokensUpdated today
DevOps & CloudAuto-check passed
Docs Learn PR Preview
netdata/netdata
Use only when the user explicitly asks to build, run, preview, inspect, or validate learn.netdata.cloud locally using the contents of a PR or documentation branch before merge.
81k GitHub stars~2k tokensUpdated today
DevOps & CloudAuto-check passed

Questions about Headscale Derp

What does Headscale Derp do?

Configure and manage DERP relay servers for Tailscale/Headscale — embedded and standalone DERP deployment, latency testing, and connectivity diagnostics. Headscale Derp is an agent skill from magnus919/agent-skills. Configure and manage DERP relay servers for Tailscale/Headscale — embedded and standalone DERP deployment, latency testing, and connectivity diagnostics.

When should I use Headscale Derp?

Headscale Derp fits situations like: direct peer connections fail; traffic is routed through DERP relays; setting up custom relay regions.

How do I install Headscale Derp in Claude Code?

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

How do I install Headscale Derp in Codex?

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

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

What does Headscale Derp need to run?

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

Does Headscale Derp access the network?

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

Is Headscale Derp 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 Derp use?

Headscale Derp 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 Derp 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 Derp?

Skills that share tags, products or a category with Headscale Derp: Monitor CI (nrwl/nx, 29k stars), Terraform and OpenTofu Guide (agentscope-ai/QwenPaw, 36k stars), Vercel Optimize Audit (vercel-labs/agent-skills, 32k stars) and Analyze GitHub Action Logs (withastro/astro, 63k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Headscale Derp?

magnus919 (a GitHub user) maintains it in magnus919/agent-skills, which has 115 GitHub stars. The repository holds 131 skills in this directory. The repository was last updated on October 10, 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 Derp

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

Context cost

Safety

SKILL.md

headscale-derp Skill

Overview

DERP in Headscale

Key config options

DERP Map

Connectivity Testing

Standalone DERP

TLS Certificates

Region Selection

Gotchas

Trigger Conditions

When not to use

Files

Compare with similar skills

Similar skills

More from magnus919/agent-skills

Related

Questions about Headscale Derp