| name | headscale-node-lifecycle |
| description | Manage the full lifecycle of nodes in a Headscale tailnet — generate pre-authenticated keys, register, approve, tag, list, and decommission nodes. Use when adding new devices, generating auth keys for automation, or managing node inventory. |
| metadata | {"category":"devops"} |
headscale-node-lifecycle
Overview
Headscale manages nodes in a tailnet with two identity models:
- Personal nodes — registered under a specific user account (e.g.
yourname@domain). The node key is tied to that user's identity.
- Tagged nodes — belong to the special
tagged-devices user (created automatically by Headscale). These nodes are identified by one or more tags (e.g. tag:webserver, tag:monitoring) and are typically used for infrastructure service nodes.
Registration happens through:
- Web auth — user visits a URL to authenticate with an OIDC/OAuth provider
- Pre-authenticated key (auth key) — a one-time or reusable key generated by the admin that embeds tags, user, and expiry
- CLI / API — direct node registration via
headscale commands or REST API calls
Pre-authenticated Keys
Auth keys streamline automated node registration. Key attributes:
| Parameter | Description |
|---|
| Expiration | Default: 1 hour. Use 0 for no expiry (not recommended). |
| Reusable | Single-use by default. Mark reusable for fleet provisioning. |
| Ephemeral | Ephemeral nodes are removed from the tailnet when they disconnect. Perfect for CI runners and ephemeral workloads. |
| Tags | Assign tags to create a tagged node automatically. |
Node Registration
- Personal nodes: Create an auth key for a user → run
tailscale up --auth-key=<key> on the device → approve in Headscale if registration is open.
- Tagged nodes: Create an auth key with
--tags → run tailscale up --auth-key=<key> → the node is auto-approved and tagged.
Node Listing
List nodes filtered by user, tag, or online status. Output includes:
- Node ID
- Name (hostname)
- Tailscale IP address(es)
- Assigned tags
- User/owner
- Online/offline status
- Last seen timestamp
- Operating system
- Tailscale client version
Node Tagging
Tags can be added or replaced on existing nodes. Tags always carry the tag: prefix in Headscale. When adding tags, existing tags are preserved unless --replace is specified.
Node Deletion
To decommission a node permanently:
headscale nodes delete -i <node-id>
Or via the REST API: DELETE /api/v1/node/<node-id>
Decommissioning is irreversible. For ephemeral nodes, disconnection alone is sufficient — the server removes them automatically.
Environment
| Variable | Description |
|---|
HEADSCALE_URL | Base URL of the Headscale server (e.g. https://headscale.example.com) |
HEADSCALE_API_KEY | API key from headscale apikeys create |
Both env vars are required for API-based operations when the headscale CLI is not available on PATH.
Gotchas
- Auth key expiration: Default is 1 hour. If you're provisioning a device and it takes longer, the key expires and registration fails. Set a longer expiry explicitly.
- Tagged node user: Tagged nodes always belong to the
tagged-devices user. Do not try to assign them to a personal user.
- Connectivity testing: Nodes must be online (
Connected: true) to test connectivity. Offline nodes do not respond to ping/ICMP within the tailnet.
- CLI vs API: When both are available, the CLI is preferred for interactive use. The REST API is preferred for automation scripts.
- Key reuse: Reusable keys are convenient but less secure. Use with care, especially in production environments.
- Ephemeral nodes: Setting
--ephemeral means the node is fully removed on disconnection — there is no record of it in the tailnet afterward.
Trigger Conditions
- "auth key"
- "preauthkey"
- "register node"
- "approve node"
- "tag node"
- "node list"
- "decommission node"
Scripts
hs-create-authkey.sh
Create pre-authenticated keys via Headscale CLI or REST API.
hs-create-authkey.sh --user <user> --tags <tag> --expiration <duration> --reusable --ephemeral [--json] [--dry-run]
hs-list-nodes.sh
List all nodes in the tailnet with status and metadata.
hs-list-nodes.sh [--json] [--user <user>] [--tag <tag>] [--online-only]
hs-approve-nodes.sh
Approve pending node registrations.
hs-approve-nodes.sh [--all] [--auth-id <id>] [--dry-run] [--json]
hs-tag-node.sh
Update tags on an existing node.
hs-tag-node.sh --node <id/name> --tags <tag1,tag2> [--replace | --add] [--dry-run] [--json]
When not to use
Do not use this skill for installing or configuring the Tailscale client (load tailscale-client instead) or for ACL/policy authoring (load tailnet-policy). It covers node registration, tagging, listing, and decommissioning only.
