Minimum supported Tailscale client version: v1.74.0

Tags as identity

Tags are now implemented following the Tailscale model where tags and user ownership are mutually exclusive. Devices can be either user-owned (authenticated via web/OIDC) or tagged (authenticated via tagged PreAuthKeys). Tagged devices receive their identity from tags rather than users, making them suitable for servers and infrastructure. Applying a tag to a device removes user-based ownership. See the Tailscale tags documentation for details on how tags work.

User-owned nodes can now request tags during registration using --advertise-tags. Tags are validated against the tagOwners policy and applied at registration time. Tags can be managed via the CLI or API after registration.

Smarter map updates

The map update system has been rewritten to send smaller, partial updates instead of full network maps whenever possible. This reduces bandwidth usage and improves performance, especially for large networks. The system now properly tracks peer changes and can send removal notifications when nodes are removed due to policy changes. #2856 #2961

Pre-authentication key security improvements

Pre-authentication keys now use bcrypt hashing for improved security #2853. Keys are stored as a prefix and bcrypt hash instead of plaintext. The full key is only displayed once at creation time. When listing keys, only the prefix is shown (e.g., hskey-auth-{prefix}-***). All new keys use the format hskey-auth-{prefix}-{secret}. Legacy plaintext keys in the format {secret} will continue to work for backwards compatibility.

Web registration templates redesign

The OIDC callback and device registration web pages have been updated to use the Material for MkDocs design system from the official documentation. The templates now use consistent typography, spacing, and colours across all registration flows.

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

• Tags: The gRPC SetTags endpoint now allows converting user-owned nodes to tagged nodes by setting tags. Once a node is tagged, it cannot be converted back to a user-owned node. #2885
• Tags: Tags are now resolved from the node's stored Tags field only #2931
  • --advertise-tags is processed during registration, not on every policy evaluation
  • PreAuthKey tagged devices ignore --advertise-tags from clients
  • User-owned nodes can use --advertise-tags if authorized by tagOwners policy
  • Tags can be managed via CLI (headscale nodes tag) or the SetTags API after registration
• Database migration support removed for pre-0.25.0 databases #2883
  • If you are running a version older than 0.25.0, you must upgrade to 0.25.1 first, then upgrade to this release
  • See the upgrade path documentation for detailed guidance
  • In version 0.29, all migrations before 0.28.0 will also be removed
• Remove ability to move nodes between users #2922
  • The headscale nodes move CLI command has been removed

Changes

• Smarter change notifications send partial map updates and node removals instead of full maps #2961
  • Send lightweight endpoint and DERP region updates instead of full maps #2856
• Add oidc.email_verified_required config option to control email verification requirement #2860
  • When true (default), only verified emails can authenticate via OIDC with allowed_domains or allowed_users
  • When false, unverified emails are allowed for OIDC authentication
• Add NixOS module in repository for faster iteration #2857
• Add favicon to webpages #2858
• Redesign OIDC callback and registration web templates #2832
• Reclaim IPs from the IP allocator when nodes are deleted #2831
• Add bcrypt hashing for pre-authentication keys

Upgrade

Please follow the steps outlined in the upgrade guide to update your existing Headscale installation.

It's best to update from one stable version to the next (e.g., 0.24.0 → 0.25.1 → 0.26.1) in case you are multiple releases behind. You should always pick the latest available patch release.

Be sure to check the changelog above for version-specific upgrade instructions and breaking changes.

Backup Your Database

Always backup your database before upgrading. Here's how to backup a SQLite database:

# Stop headscale
systemctl stop headscale

# Backup sqlite database
cp /var/lib/headscale/db.sqlite /var/lib/headscale/db.sqlite.backup

# Backup sqlite WAL/SHM files (if they exist)
cp /var/lib/headscale/db.sqlite-wal /var/lib/headscale/db.sqlite-wal.backup
cp /var/lib/headscale/db.sqlite-shm /var/lib/headscale/db.sqlite-shm.backup

# Start headscale (migration will run automatically)
systemctl start headscale

Changelog

• c4600346f9c29b514dc9725ac103efb9d0381f23 .github/workflows: prebuilt integration test artifacts (#2954)
• 2c3c943acf1219b6861941e640a2fe2d4cd7b99e .github/workflows: split long TestAutoApproveMultiNetwork into multiple jobs
• 5655ef86d750110623418416c5d671a30cb529ad AGENTS: golangci-lint from main, no "full matrix"
• 249630bed8001e3ec634b8c3578ba6d6308616d3 Add API documentation
• 14af9b3ab168c69cb187d416a96b34abcedfb7cd Add docs to manage headscale from another local user
• 21af106f68fa38f37d80c9ac91a336a4f53bc074 Containers should be read-only
• a288f04a1a2b089278366df8d1d473eebc5dbf48 Dockerfile: align packages
• 9c33cbfdc8fadfb5662479edab59a9cd56a21850 Exclude docs/ only for prettier pre-commit hook
• 665cc44094981a57f2223076903773c72aa1429e Explicitly drop apt-get clean and use dist-clean
• c5133ee5d3235d02e531a6f8e84c36b71877c770 Fix trailing whitespace
• 5c6cd62df125e7b3c1ce9d37954b9ce5fbbfe231 Legacy preauthkeys must be used as-is
• e86d0630564921389e19f498e96b182f38d85f3a Mention /health instead of /windows
• f00c412cde4a000cc091037f926519b99ceb7626 Move static doc assets into docs/assets
• 2010805712f725a6f44a42dc21c3b13a020fc6cd Provide Headscale's favicon at its expected place
• 72d5fd04a74fae6ec248aeaf1b8ad8a5c6920375 Remove duplicated documentation and link to getting started instead
• e0c9e18e222a3f6f71d1d49d62386a51173ae69f Update OIDC documentation for allowed groups filter
• 9b327f6b56cffa1551bdc5bea15af7df0f149b72 Update pre-commit-hooks
• 6359511a626a3ff549ce7d32c14c5cf12082fe60 Use debian13 distroless images
• bba91a89be8f95a2f367a0c7c601d68159f0bbf1 Use lists for integration docs
• 218a8db1b901cc6c7b777c5855c01b15154d932e add favicon to webpages (#2858)
• 6d24afba1ce773ac935f4acc1c35d6521725ac26 add pre-commit hooks, move claude to agents. (#2877)
• 0e1673041cbe3d13f696cb0766da09ccdc4cf3e2 all: remove deadcode (#2952)
• 56bec66a44f68d90a411dcd562c0e44578b399fa app: only wire up debug server if set
• 3cf2d7195ab7df229855644f3f90bdbdc1e5d0be auth: ensure machines are allowed in when pak change (#2917)
• f3767dddf8b1af91e5b67126a9dd519bb284cfec batcher: ensure removal from batcher
• 616c0e895d5eeb96b2627b004d1e32861c7e1037 batcher: fix closed panic
• 7fb0f9a50120630fe45131a98c2d3f6841dafc51 batcher: send endpoint and derp only updates. (#2856)
• e8753619de9240aee93c624f724939bcd0b4b5d9 capver: generate
• 8394e7094a4201456071885aed63e282dd5e0bf6 capver: update latest (#2774)
• 5767ca5085a7b089cba45f8175a507c104cedb36 change: smarter change notifications
• 1dcb04ce9b2f98f5aaa8fd361d4e3d9abd682027 changelog: add changelog entry