headscale v0.29.0 released on 17-06-2026
headscale v0.29.0 is out now. Operators and administrators get closer parity with Tailscale SaaS: ACL and packet-filter generation have been aligned, policy and SSH testing flows are improved, and Grants plus nodeAttrs/Taildrive controls expand policy expressiveness.
Read the full release notes on the project GitHub and follow the upgrade guide at https://headscale.net/stable/setup/upgrade/ for detailed migration steps and examples.
What’s in this release
- ACL and filter-generation compatibility fixes to match Tailscale SaaS: wildcard handling, ICMP semantics, merged/reduced filter rules, subnet-to-subnet peer fixes, and clearer policy validation errors.
- Policy testing (beta) and SSH improvements: evaluate policy tests and sshTests on writes and reloads, plus SSH “action”:”check” with OIDC/CLI approval and new headscale auth CLI commands (register/approve/reject).
- Grants, nodeAttrs and Taildrive support: Tailscale-style grants (ip, app, via), the autogroup:danger-all source for true “all IPs” semantics, node attribute capability assignments, and Taildrive drive:share/drive:access controls.
Upgrade notes
- Breaking config change: the old randomize_client_port server config key was removed. Move the setting to your policy as randomizeClientPort and ensure headscale is not started with the old key present; follow the upgrade guide at https://headscale.net/stable/setup/upgrade/.
- Strict upgrade path enforced: do not skip minor versions (for example, upgrade one minor at a time). Downgrades across minor versions are blocked, so take backups and plan upgrades carefully; rollbacks across minors may not be possible.
Let the project know how the upgrade went or report any unexpected behaviour on the project’s GitHub issues — feedback on policy and compatibility edge cases is especially welcome.
