Repolode
Submit
juanfont

juanfont/headscale

A self-hosted, open source implementation of the Tailscale control server for running your own WireGuard-based mesh network.

Open-source alternative to:Tailscale

View on GitHub
Stars
44,970
Forks
2,614
Open issues
135
Last commit
16 hours ago

What is it?

Tailscale is a VPN built on WireGuard that connects devices into an overlay network using NAT traversal. Its control server handles the exchange of WireGuard public keys between nodes, assigns client IP addresses, enforces boundaries between users, allows machines to be shared, and distributes advertised routes. Headscale is a self-hosted, open source reimplementation of that control server, so you can run the coordination layer yourself instead of relying on Tailscale's hosted service.

Headscale targets a single tailnet suited to personal use or a small organisation, rather than the full scope of the commercial service. Official Tailscale clients can be pointed at a headscale instance. The project is written in Go, and its documentation covers supported client operating systems and features.

The project is not affiliated with Tailscale Inc. Development is guided by the self-hosting and hobbyist community, and the repository includes a NixOS module and development builds from the main branch.

Key features

  • 01Implements the Tailscale control server for coordinating WireGuard nodes
  • 02Assigns IP addresses and manages boundaries between users
  • 03Supports sharing machines and advertising routes between nodes
  • 04Provides a NixOS module and container and binary builds

Use cases

  • Running a private mesh network for a homelab or personal devices
  • Giving a small open-source team a self-hosted tailnet
  • Keeping the coordination server under your own control instead of a hosted service

Quick start

  1. 1

    Clone the repository

  2. 2

    Enter the Nix development shell (recommended)

    nix develop
  3. 3

    Run the test suite

    make test
  4. 4

    Build the program

    make build

Things to know

  • The README does not support running Headscale behind reverse proxies or in containers.
  • Requires a Tailscale-compatible client setup and self-hosting effort to operate a control server.

In collections

Self-hosted apps

Topics

#tailscale#wireguard#vpn#self-hosted#networking#go#tailscale-control-server#tailscale-server

FAQ

What is headscale?
A self-hosted, open source implementation of the Tailscale control server for running your own WireGuard-based mesh network. Tailscale is a VPN built on WireGuard that connects devices into an overlay network using NAT traversal. Its control server handles the exchange of WireGuard public keys between nodes, assigns client IP addresses, enforces boundaries between users, allows machines to be shared, and distributes advertised routes. Headscale is a self-hosted, open source reimplementation of that control server, so you can run the coordination layer yourself instead of relying on Tailscale's hosted service.
Is headscale free to use? What license does it have?
headscale is open source under the BSD-3-Clause license. Check the license terms before using it in commercial products.
Is headscale still maintained?
Actively maintained. The last commit to headscale was on Oct 24, 2026.
What can I use headscale for?
Running a private mesh network for a homelab or personal devices Giving a small open-source team a self-hosted tailnet Keeping the coordination server under your own control instead of a hosted service
How do I install headscale?
Clone the repository Enter the Nix development shell (recommended): nix develop Run the test suite: make test Build the program: make build
Where can I get headscale?
The source code and installation instructions are on GitHub: https://github.com/juanfont/headscale

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects