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:

1. Web auth — user visits a URL to authenticate with an OIDC/OAuth provider
2. Pre-authenticated key (auth key) — a one-time or reusable key generated by the admin that embeds tags, user, and expiry
3. CLI / API — direct node registration via headscale commands or REST API calls

Pre-authenticated Keys

Auth keys streamline automated node registration. Key attributes: