headscale

Breaking changes

What to check before upgrading, taken from the notes of the last 30 releases.

• v0.29.0Jun 17, 2026
  • all IPs (see BREAKING below). The name is intentional: accepting traffic from the entire

  BREAKING

  Hostname handling

  • The GivenName collision policy changed from an 8-char random hash suffix (laptop-abc12xyz) to a monotonic numeric suffix (laptop, laptop-1, laptop-2, …), matching Tailscale SaaS. Empty / all-non-ASCII hostnames now fall back to the literal node instead of invalid-. MagicDNS names change on upgrade for any node whose previous label was a random-suffix form; the raw Hostname column is unchanged. #3202

  ACL Policy

  • Wildcard (*) in ACL sources and destinations now resolves to Tailscale's CGNAT range (100.64.0.0/10) and ULA range (fd7a:115c:a1e0::/48) instead of all IPs (0.0.0.0/0 and ::/0) #3036
  • This better matches Tailscale's security model where * means "any node in the tailnet" rather than "any IP address"
  • Policies that need to match all IP addresses including non-Tailscale IPs should use autogroup:danger-all as a source, or explicit CIDR ranges as destinations #2180
  • autogroup:danger-all can only be used as a source; it cannot be used as a destination
  • Note: Users with non-standard IP ranges configured in prefixes.ipv4 or prefixes.ipv6 (which is unsupported and produces a warning) will need to explicitly specify their CIDR ranges in ACL rules instead of using *
  • Validate autogroup:self source restrictions matching Tailscale behavior - tags, hosts, and IPs are rejected as sources for autogroup:self destinations #3036
  • Policies using tags, hosts, or IP addresses as sources for autogroup:self destinations will now fail validation
  • The proto:icmp protocol name now only includes ICMPv4 (protocol 1), matching Tailscale behavior #3036
  • Previously, proto:icmp included both ICMPv4 and ICMPv6
  • Use proto:ipv6-icmp or protocol number 58 explicitly for ICMPv6

  Upgrade Path

  • Headscale now enforces a strict version upgrade path #3083
  • Skipping minor versions (e.g. 0.27 → 0.29) is blocked; upgrade one minor version at a time
  • Downgrading to a previous minor version is blocked
  • Patch version changes within the same minor are always allowed

  Configuration

  • The randomize_client_port server-config key was removed; the

  toggle now lives in the policy file as a top-level

  randomizeClientPort field, matching the Tailscale-hosted schema. #3251

• v0.28.0Feb 4, 2026

  Database migration support removed for pre-0.25.0 databases

  Headscale no longer supports direct upgrades from databases created before version 0.25.0. Users on older versions must upgrade

  sequentially through each stable release, selecting the latest patch version available for each minor release.

  BREAKING

  • API: The Node message in the gRPC/REST API has been simplified - the ForcedTags, InvalidTags, and ValidTags fields have been removed and replaced with a single Tags field that contains the node's applied tags #2993
  • API clients should use the Tags field instead of ValidTags
  • The headscale nodes list CLI command now always shows a Tags column and the --tags flag has been removed
  • PreAuthKey CLI: Commands now use ID-based operations instead of user+key combinations #2992
  • headscale preauthkeys create no longer requires --user flag (optional for tracking creation)
  • headscale preauthkeys list lists all keys (no longer filtered by user)
  • headscale preauthkeys expire --id replaces --user
  • headscale preauthkeys delete --id replaces --user

  Before:

    headscale preauthkeys create --user 1 --reusable --tags tag:server
    headscale preauthkeys list --user 1
    headscale preauthkeys expire --user 1
    headscale preauthkeys delete --user 1
  

  After:

    headscale preauthkeys create --reusable --tags tag:server
    headscale preauthkeys list
    headscale preauthkeys expire --id 123
    headscale preauthkeys delete --id 123
  

  • Tags: The gRPC SetTags endpoint now allows converting user-owned nodes to tagged nodes by setting tags. #2885
  • Tags: Tags are now resolved from the node's stored Tags field only #2931
• v0.27.0Oct 27, 2025

  BREAKING

  • Remove support for 32-bit binaries

  #2692

  • Policy: Zero or empty destination port is no longer allowed

  #2606

  • Stricter hostname validation #2383
  • Hostnames must be valid DNS labels (2-63 characters, alphanumeric and

  hyphens only, cannot start/end with hyphen)

  • Client Registration (New Nodes): Invalid hostnames are automatically

  renamed to invalid-XXXXXX format

  • my-laptop → accepted as-is
  • My-Laptop → my-laptop (lowercased)
  • my_laptop → invalid-a1b2c3 (underscore not allowed)
  • test@host → invalid-d4e5f6 (@ not allowed)
  • laptop-🚀 → invalid-j1k2l3 (emoji not allowed)
  • Hostinfo Updates / CLI: Invalid hostnames are rejected with an error
  • Valid names are accepted or lowercased
  • Names with invalid characters, too short (<2), too long (>63), or

  starting/ending with hyphen are rejected

• v0.26.0May 14, 2025

  BREAKING

  Routes

  Route internals have been rewritten, removing the dedicated route table in the

  database. This was done to simplify the codebase, which had grown unnecessarily

  complex after the routes were split into separate tables. The overhead of having

  to go via the database and keeping the state in sync made the code very hard to

  reason about and prone to errors. The majority of the route state is only

  relevant when headscale is running, and is now only kept in memory. As part of

  this, the CLI and API has been simplified to reflect the changes;

  $ headscale nodes list-routes
  ID | Hostname           | Approved | Available       | Serving (Primary)
  1  | ts-head-ruqsg8     |          | 0.0.0.0/0, ::/0 |
  2  | ts-unstable-fq7ob4 |          | 0.0.0.0/0, ::/0 |
  
  $ headscale nodes approve-routes --identifier 1 --routes 0.0.0.0/0,::/0
  Node updated
  
  $ headscale nodes list-routes
  ID | Hostname           | Approved        | Available       | Serving (Primary)
  1  | ts-head-ruqsg8     | 0.0.0.0/0, ::/0 | 0.0.0.0/0, ::/0 | 0.0.0.0/0, ::/0
  2  | ts-unstable-fq7ob4 |                 | 0.0.0.0/0, ::/0 |
  

  Note that if an exit route is approved (0.0.0.0/0 or ::/0), both IPv4 and IPv6

  will be approved.

  • Route API and CLI has been removed
• v0.25.0Feb 11, 2025

  BREAKING

  • Authentication flow has been rewritten

  #2374 This change should be

  transparent to users with the exception of some buxfixes that has been

  discovered and was fixed as part of the rewrite.

  • When a node is registered with _a new user_, it will be registered as a new

  node (#2327 and

  #1310).

  • A logged out node logging in with the same user will replace the existing

  node.

  • Remove support for Tailscale clients older than 1.62 (Capability version 87)

  #2405