NetBird vs Headscale: which to choose

NetBird vs Headscale: when each one is the right choice

NetBird fits multi-user, identity-driven access with a dashboard, and Headscale fits a single small tailnet with a narrower scope. Headscale's documentation describes a narrow design goal: one Tailscale network for personal use or a small open-source organization, aimed at self-hosters and hobbyists. NetBird is the stronger choice when access must be granted to people and their identity provider groups, and when administrators want one web interface for policies, posture checks and logs. It also suits several teams and sites sharing one network over time. Headscale is the better choice when a small group already runs Tailscale clients and wants a lean control server it can maintain itself.

Three questions decide it. First, how many people and devices will join? Headscale is built for one small network, so a growing user base or device count points toward NetBird. Second, must identity provider groups drive access? Headscale supports basic OIDC login and updates profiles from the provider, but OIDC groups cannot be used in ACLs and autogroups are only partly supported, according to its feature documentation. NetBird lists SSO, MFA, groups and rules for access control, but SCIM provisioning and enterprise SSO appear on its paid tiers, so confirm which tier your identity requirements need. Third, how much operating work can the team carry? NetBird's self-hosted operators handle backups, upgrades and scaling themselves, so budget that effort before committing.

Which NetBird vs Headscale scenario fits your team

This table maps common team situations to the platform that usually fits better, based on scope, identity integration, access control and hosting constraints. Read each row as a default: the answers to the questions in the last column can move a scenario toward the other option.

Scenario	Better fit	Why, and what would change the answer
A small open-source team on one tailnet with no external identity provider	Headscale	Headscale is built for a single tailnet for personal use or a small open-source organization. If the team is comfortable with the Tailscale client model and does not need SSO, MFA or posture checks, its narrower scope may be enough. Confirm the team will not need group-based access later.
A company with an SSO provider and group-based access rules	NetBird	NetBird lists SSO and MFA support, groups and rules for access control, and device posture checks. Headscale supports basic OIDC login, but OIDC groups cannot be used in its ACLs, so group-driven policy needs a different design. Confirm which identity provider you use and whether it must drive policy.
A homelab with mixed devices such as NAS units, routers and Linux hosts	Depends on the client list and proxy setup	NetBird publishes clients for many platforms, including Synology, TrueNAS, pfSense, OPNsense, MikroTik RouterOS, OpenWRT and Proxmox. Headscale can work well for Tailscale-compatible devices. Check each device you need against the current client documentation for both projects before choosing.
A team that wants a managed control plane and no servers to run	NetBird Cloud, with self-hosted NetBird as the alternative	The self-hosting quickstart leaves backups, upgrades and scaling to the operator, while NetBird Cloud needs no servers or domain. Neither Headscale option is a managed service in the supplied facts, so a team that wants vendor-run operations should ask about hosted options for Headscale before assuming they exist.
An environment that cannot run containers or a reverse proxy	Headscale, with a caveat	Headscale's README says the project does not support or encourage running it behind reverse proxies or in containers. If that is a hard constraint, Headscale's own guidance applies. NetBird's self-hosted stack runs as Docker Compose with a Traefik reverse proxy, so it fits only if containers and a proxy are allowed.
A regulated organization that needs audit trails for access changes	NetBird	NetBird lists activity and traffic event logging, and its Team plan adds audit event logging. Headscale's supplied feature list does not describe an equivalent audit feature. Ask both vendors which logs you can export and retain before you decide.
A team that must manage device compliance before granting access	NetBird	NetBird's Business plan adds device approvals, MDM and EDR device controls, and posture checks. Headscale's supplied documentation does not list posture checks, so confirm this with the project before relying on it.
A team that expects to add many users or grow the network over time	Confirm before deciding	NetBird's cloud pricing counts active users and machines, and its self-hosted deployment needs its own sizing. Headscale is scoped to a single tailnet. Ask how each platform scales in users, machines and network segments, and what that means for your operating effort.

How NetBird and Headscale are built and what that means for operations

NetBird ships a full stack: management, signal, relay, STUN, a dashboard and an identity provider in one deployment. Headscale is a control server that Tailscale clients talk to, and it leaves much of the surrounding stack to you. The cards below trace each design choice to the work it leaves with your team.

NetBird's combined control stack

A self-hosted NetBird deployment runs management, signal, relay and STUN from one combined configuration, alongside a dashboard container. Your team operates that whole set as one unit, so upgrades, backups and scaling apply to the stack together. Check that the single Linux host you plan for can carry the relay traffic your users will generate, since relay load grows with the number of peers that cannot connect directly.

Traefik and embedded Dex by default

The default NetBird install puts a Traefik reverse proxy in front of the stack with Let's Encrypt certificates, and it bundles the Dex identity provider. Dex can add external SSO providers such as Google, Microsoft or Okta. The consequence is that your team owns the identity layer's configuration and its place in your login policy. Confirm with the NetBird documentation how the bundled Dex is maintained and how an external IdP is wired in before you commit to the default install.

Headscale as a control server

Headscale handles the control plane for a Tailscale-style network. It exchanges WireGuard public keys, assigns client IP addresses, sets the boundaries between users and exposes advertised routes. Data-plane traffic still moves directly between clients where possible. Your team owns everything the control server decides, so review how user boundaries and route advertisement map to your access model before rollout.

Embedded DERP and peer relays

Headscale includes an embedded DERP server and supports peer relays, so relay capacity can be placed on infrastructure you choose. Relay placement is an operating decision: a relay in a poorly connected location adds latency for every fallback path. Test relayed paths from each site your users work from, not only direct connections on a shared office network.

Headscale's position on proxies and containers

The Headscale README says the project does not support or encourage running Headscale behind reverse proxies or in containers. That removes a common pattern many platform teams use to standardize hosting. If your standard is containers behind a proxy, Headscale will need a separate hosting pattern, and you will carry that support question yourself. NetBird's quickstart uses containers and a reverse proxy by default, so the two models differ on day one.

Client compatibility and licensing

Tailscale's client code in the tailscale/tailscale repository is BSD-3-Clause licensed, which is why Headscale can work with Tailscale clients. Headscale is also BSD-3-Clause. Client compatibility still depends on your device mix, so test each platform you support, including mobile, NAS and router devices, against the exact client versions your users will install. Confirm the supported client versions with the Headscale project before you standardize on them.

NetBird vs Headscale feature by feature

This table sets NetBird's supplied feature set against Headscale's, row by row, for a team choosing a self-hosted mesh VPN. Where a capability is not covered by the supplied project information, the cell tells you what to confirm in the project documentation. Use the rows on scope, access policy and operating effort to decide which fit your team.

Capability	NetBird	Headscale
Scope	Company-wide overlay with a web dashboard, relays, routes, exit nodes and private DNS managed centrally	Control server for a single Tailscale network (tailnet), aimed at personal use or a small open-source organization
Client coverage	Linux, macOS, Windows, Android, iOS, FreeBSD, pfSense, OPNsense, MikroTik RouterOS, OpenWRT, Synology, TrueNAS, Proxmox, Raspberry Pi and others	Uses Tailscale clients, which are open source except the GUI clients for Windows, macOS and iOS; confirm current client support in the Headscale documentation
SSO and MFA	SSO and MFA supported; the Team plan adds SSO and MFA with an enterprise identity provider on the pricing page	Basic OIDC login with profile updates from the identity provider; confirm MFA handling with the identity provider and project documentation
Group-based access	Groups and rules for access control in the README feature list	OIDC groups cannot be used in ACLs; autogroups are only partly supported
ACLs and policy model	Centralized access control with groups and rules	ACLs, grants, some autogroups and tags
Device posture checks	Listed in the README; posture checks and device approvals appear on the Business plan	Not listed in the supplied feature set; confirm with the Headscale documentation
Activity and traffic logging	Activity and traffic event logging in the README; traffic logging and streaming on the Business plan	Not listed in the supplied feature set; confirm with the Headscale documentation
SSH with central policy	SSH with central access policies	Tailscale SSH is supported; confirm how it is governed by Headscale policy
Subnet routers and exit nodes	Routes to external networks and exit nodes	Subnet routers and exit nodes listed in the feature set
DNS	Private DNS in the README feature list	MagicDNS and split DNS
Public API and infrastructure as code	Public API, setup keys, a Terraform provider and an Ansible collection	Pre-authenticated keys and ephemeral nodes listed; confirm API and automation tooling in the documentation
Relay and NAT traversal	Peer-to-peer WireGuard with relay fallback; self-hosted relay and STUN in the combined stack	Embedded DERP server and peer relays
Deployment requirements	Linux VM with at least 1 CPU and 2 GB of memory, a public domain, TCP 80 and 443, UDP 3478 and Docker with Compose	Documentation says Headscale is not supported behind reverse proxies or in containers; confirm your hosting model
License	BSD-3-Clause for most of the repository; AGPLv3 for management, signal, relay and combined directories	BSD-3-Clause

NetBird and Headscale licensing and paid editions

NetBird's repository is mostly licensed under BSD-3-Clause, but the management, signal, relay and combined directories are licensed under AGPLv3. Copyright is held by NetBird GmbH and the individual authors. For a self-hosted deployment, the AGPLv3 directories matter most, because they cover the server components you run yourself. Legal review of how the AGPLv3 applies to your modifications and internal use is a question for your counsel. NetBird's cloud pricing page lists the following plans:

Free: up to 5 users and 100 machines.
Team: 6 euros per user per month. The page adds SSO and MFA with an enterprise identity provider, SCIM provisioning and audit event logging.
Business: 12 euros per user per month, with 100 machines included plus 10 per user, and extra machines at 0.50 euros each. It adds device approvals, MDM and EDR device controls, posture checks and traffic logging and streaming.
Enterprise: custom pricing.
Billing: only active users and machines count toward the bill.

Confirm current plan terms, machine allowances and what counts as an active user directly with NetBird before you buy.

How SSO and access policies differ in practice

NetBird ties access control to identity inside its own dashboard. The README lists SSO and MFA support, groups and rules for access control, device posture checks, and SSH with central access policies. The pricing page splits these features across plans: SSO and MFA with an enterprise identity provider, along with SCIM provisioning and audit event logging, sit on Team, while device approvals, MDM and EDR device controls, posture checks and traffic logging sit on Business. A self-hosted deployment runs an embedded Dex identity provider that can add external SSO providers such as Google, Microsoft or Okta. Before you commit, confirm with NetBird which of these controls your chosen edition and self-hosted build expose, and whether SCIM provisioning is available to you at the tier you need, since group membership in your identity provider is the input your access rules depend on.

Headscale's identity model is narrower and needs more manual design. It supports basic OIDC login and updates user profiles from the identity provider when users sign in. However, OIDC groups cannot be used in ACLs, and autogroups are only partly supported. In practice, a rule such as "engineers can reach the staging subnet" cannot follow your identity provider's group membership directly. Teams usually work around this by maintaining users and tags in the Headscale configuration, pre-authenticated keys, or by mapping access through tags that someone updates by hand. That adds an ongoing administrative task and a drift risk every time a person changes role or leaves. Headscale's design goal of a single tailnet for personal use or a small organization makes this manageable at small scale, but it is a different operating model from one where policy is driven by directory groups.

If access must follow identity provider groups, plan the pilot around that requirement. Group-driven access changes the design work, the testing time and who owns the policy. On NetBird, test that group changes in the identity provider reach the dashboard and alter peer access as expected, and that offboarding removes access without manual cleanup. On Headscale, map a sample of your groups to tags or ACL entries, count how many manual edits a single role change requires, and confirm that revocation takes effect for an existing session. Run the same test for a removed user, a moved user and a device that should be blocked by posture. Record the hours your team spends on each test, because that figure, not the licence line, is what most often decides the total cost of ownership.

Switching from Headscale to NetBird or back: what transfers and what is rebuilt

This sequence moves a working mesh network from one control server to another with a tested cutover and a clear record of what was carried over and what had to be enrolled or declared again. Most of the value sits in the inventory and policy intent, since client enrollment, keys and policy objects are rebuilt on the target.

Inventory users, devices, ACLs and routes
Record every user, every enrolled device with its owner and purpose, the ACL and grant rules in force, the tags and autogroups in use, every advertised subnet route, each exit node, and the MagicDNS and split DNS settings. Export the policy file and keep it under version control, since it is the most portable artifact you hold. The step is done when a reviewer can rebuild the full picture of who reaches what from the document alone, without querying the old server. Ask each vendor which of these objects, if any, its tooling can import directly.
Stand up the target control plane in a test environment
Deploy NetBird in a separate test environment, following the self-hosting quickstart if you run it yourself, or create a NetBird Cloud tenant for evaluation. Confirm the prerequisites first: a Linux host with the required CPU and memory, a public domain, TCP 80 and 443 and UDP 3478 reachable, and Docker with the Compose plugin. The step is done when a test client enrolled in the new network can reach a test service through a policy you wrote from the inventory, and when you have confirmed the identity provider path you intend to use.
Map users and groups to target groups and rules
Translate each Headscale user, tag and autogroup into the NetBird equivalent: groups, access rules and, where needed, posture checks. Headscale OIDC groups cannot be used in ACLs, so decide how group membership will come from your identity provider on the NetBird side and confirm that flow in the test environment. Mark every rule that has no direct equivalent so it is reviewed by hand instead of assumed. The step is done when each rule in the inventory has a documented target object or an explicit decision to drop or redesign it.
Re-enroll clients and re-declare routes and DNS
Enroll each device in the target network, since client keys and node identities are not carried between control planes. Re-declare subnet routes, exit nodes and DNS settings on the target, and test each one from a device in the matching group. Use setup keys for headless servers and routers, and confirm the client platform support for every device class in scope. The step is done when every device in the inventory has a reachable path to the resources it needs and a test confirms that a device outside its group cannot reach them.
Cut over in stages
Move one group of devices at a time, starting with low-impact users and a rollback plan that keeps the old network available until the new one is verified. Run both networks in parallel for the stage, watch access logs and connection failures on the target, and confirm that critical services keep working before moving the next group. The step is done when every group has been moved, the agreed acceptance tests pass for each, and no device still depends on the old control server for a route or name.
Retire the old control server
Once all devices have moved and no route or DNS record still points at the old network, disable enrollment on Headscale, export and archive its database and configuration, and then shut the service down. Keep the archive for a retention period set by your own policy, and record the decommission in your asset and access inventory. Revoke any credentials or keys tied to the old server. The step is done when the archive is verified as restorable and the old control plane no longer appears in routing, DNS or access reviews.

What drives the running cost of each option

Running cost for either product is mostly people time and infrastructure, not licence fees, since both are open source at their core. The cards below separate what NetBird Cloud bills, what a self-hosted NetBird or Headscale deployment consumes, and what each vendor or community leaves to your team. Use them to build a like-for-like quote.

NetBird Cloud subscription cost

NetBird's pricing page lists a Free tier for up to 5 users and 100 machines, Team at 6 euros and Business at 12 euros per user per month, and custom Enterprise pricing. Billing counts only active users and machines, so a cloud estimate depends on how many devices your team actually connects. Team adds SSO and MFA with an enterprise identity provider, SCIM provisioning and audit event logging, which are the features most regulated teams need. Headscale has no equivalent hosted subscription, so the comparison is between a recurring fee and your own operating hours.

Self-hosted infrastructure floor

The NetBird self-hosting quickstart needs a Linux VM with at least 1 CPU and 2 GB of memory, a public domain, TCP ports 80 and 443 open, and UDP port 3478 open for STUN, plus Docker with the Compose plugin. That is the minimum to start, not a sizing for production load, so ask your vendor or partner to size relays and the management service for your peer count and traffic pattern. Cloud spend for the VM, domain, backups and egress recurs monthly and grows with the mesh.

Staff time for backups and upgrades

NetBird's documentation states that self-hosted operators handle backups, upgrades and scaling themselves. That work recurs with every release and includes restoring the management database and the embedded identity provider configuration, so test a restore before go-live. Ask a partner for a fixed-scope estimate covering backup design, the upgrade runbook and the number of hours each quarter, and confirm whether ongoing support is a separate retainer.

Headscale community maintenance

Headscale is a community-maintained project, and its repository carries sponsorship and donation buttons rather than a vendor support contract. Its documentation is published separately for stable and development versions, so your team owns the choice of release line and the fixes it needs. Budget for internal engineers or a paid support arrangement with an external provider, and confirm in writing what response, patching and upgrade work that arrangement covers.

Identity provider licensing

Neither product includes the identity provider that signs your staff in. NetBird's self-hosted stack embeds Dex, which can add external providers such as Google, Microsoft or Okta, and Headscale relies on basic OIDC login from your own provider. Your existing Microsoft Entra, Okta or Keycloak subscription or licence is a separate line item that stays the same either way. Confirm which SSO features your IdP tier includes, such as group claims and MFA, because those drive access policy design.

Testing cost on each release line

Both projects publish frequent releases. NetBird v0.81.2 followed v0.81.0 within a day, and Headscale v0.29.5 followed v0.29.4 and v0.29.3 across several months. Each upgrade needs a staging mesh with real client platforms, including Linux, Windows, macOS, mobile and any router platforms you run, plus a rollback plan. Ask for the test matrix and the time it covers in any quote, since this is usually the largest recurring effort.

Implementation effort by deployment path

This path fits a small group that wants one tailnet with a self-hosted control server and little central policy. Headscale is built for this scope: a single tailnet for personal use or a small open-source organization. The setup centers on one control server, a public hostname, and enrolling a few clients. Most of the effort sits in getting the basics right on the first pass, not in scale.

Server placement: Plan a host that is reachable by every client. The README does not support or encourage running Headscale behind a reverse proxy or in containers, so the control server usually runs directly on a host you can keep patched.
Client rollout: Each operating system needs its own enrollment step. Confirm which clients you need, since some GUI clients are not part of the open-source Tailscale code.
ACL design: Keep the policy small and written down before enrolling users, so later changes do not become a rewrite.
DNS and routes: MagicDNS and split DNS, plus any subnet routes, need testing on every client type.
Supply list: A public domain, the ports your chosen design requires, and a named person who will own upgrades.

Before you commit, confirm the required ports, the client platforms you need, and the upgrade process with the vendor documentation and your own network team.

NetBird vs Headscale questions buyers ask before hiring help

How much more effort is a self-hosted NetBird deployment than Headscale?

NetBird asks for more running parts, while Headscale asks for more care in how it is placed on your network. A self-hosted NetBird deployment runs management, signal, relay and STUN from one combined configuration, a dashboard container, a Traefik reverse proxy with Let's Encrypt by default, and an embedded Dex identity provider. The self-hosting quickstart needs a Linux VM with at least 1 CPU and 2 GB of memory, a public domain, TCP ports 80 and 443 and UDP port 3478 open, and Docker with the Compose plugin. Headscale is a single control server, but its README says the project does not support or encourage running it behind reverse proxies or in containers, so placement and certificate handling need separate planning. Both need ongoing upgrades and backups, which NetBird's documentation assigns to the self-hosting operator.

Can a small team run NetBird or Headscale without outside help?

A team with Linux, container and identity administration experience can run either, but the answer depends on how much of the stack it already owns. NetBird's self-hosted setup covers more components, so the team needs to be comfortable with Docker Compose, public DNS, certificates and an OIDC identity provider. Headscale fits a narrower scope, a single tailnet for a small group, and its feature list covers ACLs, MagicDNS, subnet routers and exit nodes. Its OIDC support is basic, and OIDC groups cannot be used in ACLs, which matters if access must follow directory groups. Ask whether your own staff can own upgrades, backup restores and incident response on a schedule, because those are the tasks that recur after launch.

What would an implementation partner do, and what must our team supply?

An implementation partner typically plans the topology, installs and hardens the deployment inside your infrastructure, connects identity, writes access policies, documents the result and sets up backup and upgrade routines. DeployOpen works under a written, fixed scope in which deliverables and timelines are agreed before work starts. Your team usually supplies the cloud or data center accounts, DNS control, the identity provider and its group structure, the list of networks and machines to reach, the access rules your security owners approve, and named people for sign-off. Ask any vendor, including DeployOpen, to state which of these items are in scope and which remain with your staff.

How long does a migration from Headscale to NetBird usually take?

No supplied fact gives a migration duration, so the reader should treat any single figure with caution. The time is driven by the number of devices that must re-enroll, how many ACL or policy rules must be rewritten as NetBird groups and rules, how many subnet routes and exit nodes must be rebuilt, and how many services depend on the current addresses. Identity is another driver: if you move from basic OIDC login to SSO and MFA with group-based rules, the identity work can take longer than the network work. Ask for a dependency inventory and a phased cutover plan in the written scope, and ask the vendor to state which assumptions the timeline depends on.

Does the licensing split between NetBird and Headscale affect a commercial product?

It can, because the licenses differ in what they require. NetBird's repository is BSD-3-Clause except the management, signal, relay and combined directories, which are AGPLv3, so modifications to those components carry AGPL obligations. Headscale is BSD-3-Clause, but its README states that the control server and the GUI clients for Windows, macOS and iOS are not open source, while the rest of Tailscale is. Tailscale's client code is BSD-3-Clause. Whether these terms fit your product depends on whether you modify or distribute the components. Have your legal team review the exact license files and the components you plan to ship before you commit.

How does NetBird Cloud pricing compare with running NetBird yourself?

NetBird's pricing page lists a Free tier for up to 5 users and 100 machines, Team at 6 euros and Business at 12 euros per user per month, each with 100 machines included plus extra machines at 0.50 euros, and custom Enterprise pricing. Billing counts only active users and machines. Team adds SSO and MFA with an enterprise identity provider, SCIM provisioning and audit event logging, while Business adds device approvals, MDM and EDR controls, posture checks and traffic logging. Self-hosting removes subscription fees but adds server hosting, your own time for upgrades and backups, and the scope cost of an implementation partner if you want one. Ask for a quote that separates one-time setup from recurring operations.

Can Headscale run behind a reverse proxy?

The Headscale README says the project does not support or encourage running Headscale behind reverse proxies or in containers. That makes it a poor fit for teams whose standard pattern is a shared proxy with managed certificates in front of every service. NetBird's self-hosted quickstart uses a Traefik reverse proxy with Let's Encrypt by default, so its proxy layout is part of the supported design. If your environment requires a proxy or container platform, confirm with the Headscale maintainers and your own testing whether your layout is supported, and plan a test environment before any production move.

How DeployOpen helps choose, implement or migrate

DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, including cloud accounts, data centers and air-gapped networks. For NetBird vs Headscale, we start by settling which overlay model fits your access policies, identity provider and operating capacity, then carry that decision through to a working, documented deployment.

How we scope

We confirm which users, devices, networks and services the overlay must reach before choosing a platform.
We map your identity provider, group structure and ACL or access policy requirements against each option's documented capabilities.
Engagements are fixed-scope, with deliverables and timelines agreed in writing before any work starts.

How we build

We deploy the chosen control plane, relays and clients in your infrastructure, including the reverse proxy and TLS setup your design requires.
We configure SSO, groups and access rules, then test them against the device and network cases your team actually uses.
We run security testing on the deployment and document the findings, configuration and remediation steps.

How we hand over

We deliver architecture notes, runbooks for backups and upgrades, and a record of access policies as written in the scope.
We walk your platform and security staff through daily administration, troubleshooting and the exit path if you change platforms later.
We prepare the systems, controls and evidence your compliance assessors will ask for, while auditors issue any formal opinion.

How we support

Ongoing support, upgrades and continuous testing are available as retainers, scoped in writing like the original engagement.
We can track platform releases, plan upgrade windows and retest access policies after each change to your network.
We can revisit the choice later if your user count, compliance needs or identity provider changes, using the same written scope process.

NetBird vs Headscale