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 Routing

by magnus919 in magnus919/agent-skills

Configure subnet routers and exit nodes in a Headscale tailnet to extend mesh access to non-Tailscale devices and route internet traffic.

MITAuto-check passed

Install Headscale Routing

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

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

GitHub CLI
$ gh skill install magnus919/agent-skills headscale-routing --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-routing .claude/skills/headscale-routing && 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-routing
GitHub stars
115
Token cost
~1.2k tokens
SKILL.md length
466 words
Files
6 (incl. scripts)
Skills in repo
131
Repo updated
First seen
Licence
MIT

At a glance

Configure subnet routers and exit nodes in a Headscale tailnet to extend mesh access to non-Tailscale devices and route internet traffic.

  • Works in 3 steps: On the gateway node, advertise the LAN… → On the Headscale server, approve the route → On client nodes that need to reach the…
  • Setting up subnet routing for LAN devices
  • SKILL.md covers Overview, Subnet Router Setup, Exit Node Setup and Auto-Approvers, plus 8 more sections
  • Runs Shell scripts from its folder; needs HEADSCALE_API_KEY

What it does

Headscale Routing is an agent skill from magnus919/agent-skills. Configure subnet routers and exit nodes in a Headscale tailnet to extend mesh access to non-Tailscale devices and route internet traffic. Use when setting up subnet routing for LAN devices or configuring exit nodes for privacy.

Its SKILL.md is about 1.2k 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/hs-advertise-routes.sh`).

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 subnet routing for LAN devices
  • Configuring exit nodes for privacy

Example prompts

  • “/headscale-routing”

Requirements

  • A Bash shell
  • A credential in HEADSCALE_API_KEY

Workflow steps

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

  1. On the gateway node, advertise the LAN subnet
  2. On the Headscale server, approve the route
  3. On client nodes that need to reach the subnet, enable route acceptance

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), which the agent can run.

    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 Routing loads about 1.2k tokens when it runs. Until then it costs about 61 tokens; SKILL.md has 466 words of instructions outside code blocks.

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

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). 466 words, ~1,246 tokens.

Download SKILL.mdSave it as .claude/skills/headscale-routing/SKILL.md (or your agent's skills folder). This skill also uses 5 other files; get the full folder from GitHub.
name
headscale-routing
description
Configure subnet routers and exit nodes in a Headscale tailnet to extend mesh access to non-Tailscale devices and route internet traffic. Use when setting up subnet routing for LAN devices or configuring exit nodes for privacy.
metadata.category
devops

headscale-routing

Overview

Subnet routers extend a tailnet to non-Tailscale devices (printers, NAS boxes, IoT devices) by advertising the local LAN subnet routes through a gateway node. Exit nodes route all non-tailnet internet traffic through a home server, providing privacy on untrusted networks (coffee shop Wi-Fi, hotel networks, etc.).

Headscale manages route approval centrally — routes must be advertised by the gateway node and then approved on the Headscale server before they become active.

Subnet Router Setup

  1. On the gateway node, advertise the LAN subnet:
    bash
    tailscale up --advertise-routes=192.168.1.0/24
  2. On the Headscale server, approve the route:
    bash
    headscale routes approve -r <route-id>
  3. On client nodes that need to reach the subnet, enable route acceptance:
    bash
    tailscale up --accept-routes

Exit Node Setup

  1. On the exit node, advertise it as an exit node:
    bash
    tailscale up --advertise-exit-node
  2. On the Headscale server, approve the exit node route.
  3. On the client, select the exit node:
    bash
    tailscale set --exit-node=<node-name>

Auto-Approvers

Configure Headscale ACL policy to auto-approve routes from trusted nodes:

json
{
  "autoApprovers": {
    "routes": {
      "192.168.0.0/16": ["tag:gateway"]
    },
    "exitNode": ["tag:gateway"]
  }
}

Nodes carrying tag:gateway will have their advertised routes or exit-node status approved automatically without manual intervention.

Via Filtering

Use grants.via in ACL policies to restrict cross-subnet access:

json
{
  "grants": [
    {
      "src": ["tag:monitoring"],
      "dst": ["tag:servers"],
      "app": ["prometheus"],
      "via": ["192.168.10.0/24"]
    }
  ]
}

This ensures traffic from monitoring nodes to servers is routed through the specified subnet, enabling firewall policies on the gateway to inspect or filter traffic.

SNAT on Subnet Routers

By default, Headscale enables Source NAT (SNAT) on subnet router traffic. This means traffic originating from tailnet clients destined for the advertised subnet appears to come from the gateway node's IP. To disable SNAT:

bash
tailscale up --advertise-routes=192.168.1.0/24 --snat-subnet-routes=false

Disable SNAT when the downstream network needs to see the original client IP for logging, ACLs, or per-device firewall rules.

List / Approve / Reject Routes on Headscale

bash
# List all routes with status
headscale routes list

# Approve a specific route
headscale routes approve -r <route-id>

# Approve all routes from a node
headscale routes approve --all -n <node-name>

# Reject a route
headscale routes reject -r <route-id>
Show full SKILL.md (202 more words)Show less

Gotchas

  • Stable gateway required: Subnet routes need a gateway node that stays online. If the gateway goes down, the route becomes unavailable.
  • --accept-routes on clients: Clients will NOT use advertised subnet routes unless they themselves run with --accept-routes or have it in their up flags.
  • IPv4-only by default: Tailscale subnet routing is IPv4-only unless you explicitly configure dual-stack (IPv4 + IPv6).
  • Overlapping subnets: If two nodes advertise overlapping subnets, routing behavior is undefined. Use distinct, non-overlapping CIDRs.
  • Headscale API required for scripting: The headscale routes CLI commands above require shell access to the Headscale server. For remote management, use the Headscale REST API with $HEADSCALE_URL and $HEADSCALE_API_KEY.

Environment

VariableDescription
HEADSCALE_URLHeadscale server URL
HEADSCALE_API_KEYAPI key from headscale apikeys create

Trigger Conditions

  • "subnet router"
  • "exit node"
  • "advertise route"
  • "approve route"
  • "route traffic"
  • "subnet routing"
  • "exit node setup"

Scripts

Refer to individual script help (--help) for usage details:

ScriptDescription
hs-advertise-routes.shAdvertise subnet routes on a Tailscale node
hs-approve-routes.shList and approve/reject routes on Headscale
hs-list-routes.shList all routes with detailed status

When not to use

Do not use this skill for node lifecycle management (load headscale-node-lifecycle instead) or for writing ACL policies (load tailnet-policy). It covers subnet routers and exit nodes 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 5 other files (scripts) in tailscale/skills/headscale-routing of magnus919/agent-skills.

  • SKILL.md
  • README.md
  • evals/evals.json
  • scripts/hs-advertise-routes.sh
  • scripts/hs-approve-routes.sh
  • scripts/hs-list-routes.sh

Open the folder on GitHubat commit 22b4723

Compare with similar skills

Headscale Routing 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 Routing compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Headscale Routing this skillmagnus919/agent-skills115—~1.2kAutomated safety check: PassMIT
N8n Node Configurationdavila7/claude-code-templates33k1 repos~4kAutomated safety check: PassMIT
n8n Node Configurationczlonkowski/n8n-skills6.4k—~4.5kAutomated safety check: PassMIT
Configure Channelopenclaw/openclaw392k—~946Automated safety check: PassMIT
Node Connectopenclaw/openclaw392k—~1.6kAutomated safety check: PassMIT
Node Inspect Debuggeropenclaw/openclaw392k1 repos~894Automated safety check: PassMIT

Similar skills

  • N8n Node Configuration

    davila7/claude-code-templates

    Operation-aware node configuration guidance. An agent skill from davila7/claude-code-templates.

    33k GitHub starsUsed in 1 repo~4k tokens
    Productivity & AutomationAuto-check passed

  • n8n Node Configuration

    czlonkowski/n8n-skills

    Explains how to configure n8n nodes correctly: which fields each operation requires, how property dependencies show or hide fields, and which get_node detail level to use.

    6.4k GitHub stars~4.5k tokensUpdated yesterday
    Productivity & AutomationAuto-check passed

  • Configure Channel

    openclaw/openclaw

    Configure and prove a chat channel with non-interactive one-liners; secrets only as SecretRefs.

    392k GitHub stars~946 tokensUpdated today
    Auto-check passed

  • Node Connect

    openclaw/openclaw

    Diagnose OpenClaw Control UI browser and native Android, iOS, or macOS node connection failures across route, auth, pairing, QR/setup-code, and reconnect states.

    392k GitHub stars~1.6k tokensUpdated today
    MobileAuto-check passed

  • Node Inspect Debugger

    openclaw/openclaw

    Debug Node.js with node inspect, --inspect, breakpoints, CDP, heap, and CPU profiles.

    392k GitHub starsUsed in 1 repo~894 tokens
    Frontend & DesignAuto-check passed

  • Router On

    weave-os/router

    Route Codex through the Weave Router again (turn it back on).

    5.6k GitHub stars~169 tokensUpdated yesterday
    Auto-check passed

More from magnus919/agent-skills

All 131 skills in this repo

  • Artifact Pyramids

    magnus919/agent-skills

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

    115 GitHub stars~2.7k tokensUpdated today
    Auto-check passed

  • Ascii City Engine

    magnus919/agent-skills

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

    115 GitHub stars~1.1k tokensUpdated today
    Auto-check passed

  • Color Management

    magnus919/agent-skills

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

    115 GitHub stars~2.6k tokensUpdated today
    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…

    115 GitHub stars~4.1k tokensUpdated today
    Auto-check passed

  • Docker Compose

    magnus919/agent-skills

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

    115 GitHub stars~2k tokensUpdated today
    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.

    115 GitHub stars~2.7k tokensUpdated today
    Auto-check passed

Questions about Headscale Routing

What does Headscale Routing do?

Configure subnet routers and exit nodes in a Headscale tailnet to extend mesh access to non-Tailscale devices and route internet traffic. Headscale Routing is an agent skill from magnus919/agent-skills. Configure subnet routers and exit nodes in a Headscale tailnet to extend mesh access to non-Tailscale devices and route internet traffic.

When should I use Headscale Routing?

Headscale Routing fits situations like: setting up subnet routing for LAN devices; configuring exit nodes for privacy.

How do I install Headscale Routing in Claude Code?

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

How do I install Headscale Routing in Codex?

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

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

What does Headscale Routing need to run?

Going by SKILL.md and its folder, Headscale Routing needs a shell for the scripts in its folder and credentials named HEADSCALE_API_KEY. Our summary lists: A Bash shell; A credential in HEADSCALE_API_KEY.

Does Headscale Routing 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 Routing 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 Routing use?

Headscale Routing 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 Routing use?

About 1.2k 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 Routing?

Skills that share tags, products or a category with Headscale Routing: N8n Node Configuration (davila7/claude-code-templates, 33k stars), n8n Node Configuration (czlonkowski/n8n-skills, 6.4k stars), Configure Channel (openclaw/openclaw, 392k stars) and Node Connect (openclaw/openclaw, 392k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Headscale Routing?

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.