headscale-derp

Deploy and manage DERP relay servers for Tailscale and Headscale networks.

40|6|Updated Jul 11, 2026

Search Tags:#devops #networking #tailscale #relay #headscale #stun #derp

Ready to run

npx skills add https://github.com/magnus919/agent-skills --skill headscale-derp

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: headscale-derp
Source: https://github.com/magnus919/agent-skills/tree/main/bundles/tailscale/skills/headscale-derp
Command: npx skills add https://github.com/magnus919/agent-skills --skill headscale-derp

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires docker, websocket-client, and includes scripts (resource) components.

What problem does it solve?

This skill resolves connectivity issues in Tailscale or Headscale networks where direct peer-to-peer NAT traversal fails, ensuring traffic remains encrypted while providing a reliable fallback relay mechanism.

Core Features & Use Cases

Automated Deployment: Quickly provision standalone DERP relay servers using Docker with integrated TLS and STUN configuration.
Connectivity Diagnostics: Perform comprehensive health checks including STUN, TLS, and WebSocket verification to ensure relay availability.
Latency Analysis: Measure and rank DERP region performance to optimize network routing for distributed tailnets.

Quick Start

Use the headscale-derp skill to deploy a new relay server on your host by running the deployment script with your specific region ID and hostname.

Frequently Asked Questions about headscale-derp

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I deploy a DERP relay server for Headscale when NAT traversal fails?▼

To deploy a DERP relay server for Headscale, use the deployment script to provision a standalone relay node with Docker, specifying your region ID and hostname. This containerized deployment includes integrated TLS and STUN configuration for encrypted traffic relay.

What is a DERP relay and when do I need it for my Tailscale network?▼

A DERP relay is an encrypted traffic relay server used when direct peer-to-peer connections in Tailscale or Headscale networks are unavailable. You need it when NAT traversal fails, ensuring your tailnet maintains connectivity through a reliable fallback relay mechanism.

Can I run health checks on STUN and WebSocket endpoints for my DERP servers?▼

Yes, you can perform comprehensive connectivity diagnostics on DERP relay servers, including STUN, TLS, and WebSocket endpoint verification. These health checks ensure relay availability and help identify issues across your Tailscale or Headscale environment.

Do I need Docker to configure and manage standalone DERP relay nodes?▼

Yes, Docker is required for containerized deployment of standalone DERP relay nodes. The automated deployment process uses Docker to provision relay servers with integrated TLS and STUN configuration, alongside standard network utilities for connectivity verification.

How do I measure and rank DERP region latency for a distributed tailnet?▼

You can measure and rank DERP region performance using built-in latency analysis features. This measures relay response times across different geographic regions to optimize network routing for your distributed Tailscale or Headscale tailnet.

Why does Tailscale traffic fallback to relay mode instead of using direct connections?▼

Tailscale traffic falls back to DERP relay mode when direct peer-to-peer NAT traversal fails to establish a connection. The relay mechanism ensures traffic remains encrypted while providing a reliable fallback path for environments where direct connectivity is blocked.