headscale
An open source, self-hosted implementation of the Tailscale control server
Top Related Projects
The easiest, most secure way to use WireGuard and 2FA.
Netmaker makes networks with WireGuard. Netmaker automates fast, secure, and distributed virtual networks.
A scalable overlay networking tool with a focus on performance, simplicity and security
Connect your devices into a secure WireGuard®-based overlay network with SSO, MFA and granular access controls.
Connect your devices into a secure WireGuard®-based overlay network with SSO, MFA and granular access controls.
A private network system that uses WireGuard under the hood.
Quick Overview
Headscale is an open-source, self-hosted implementation of the Tailscale control server. It allows users to create and manage their own private networks without relying on Tailscale's infrastructure. Headscale aims to provide a more customizable and privacy-focused alternative to the official Tailscale service.
Pros
- Self-hosted solution, giving users full control over their network infrastructure
- Compatible with official Tailscale clients, allowing easy integration with existing devices
- Free and open-source, enabling community contributions and customizations
- Supports various authentication methods, including pre-authorized keys and OIDC
Cons
- Requires more technical knowledge to set up and maintain compared to the official Tailscale service
- May lack some advanced features available in the commercial Tailscale offering
- Smaller community and support base compared to the official Tailscale product
- Potential for security vulnerabilities if not properly configured and maintained
Getting Started
To get started with Headscale, follow these steps:
- Install Headscale on your server:
# For Debian/Ubuntu
sudo apt-get install headscale
# For macOS using Homebrew
brew install headscale
- Configure Headscale by editing the configuration file:
sudo nano /etc/headscale/config.yaml
- Start the Headscale service:
sudo systemctl start headscale
- Generate a pre-authorization key:
headscale preauthkeys create --user username --expiration 24h
- Use the generated key to connect Tailscale clients to your Headscale server.
For more detailed instructions and advanced configuration options, refer to the official Headscale documentation.
Competitor Comparisons
The easiest, most secure way to use WireGuard and 2FA.
Pros of Tailscale
- Official implementation with robust support and documentation
- More feature-rich and mature, with advanced networking capabilities
- Seamless integration with major cloud providers and identity systems
Cons of Tailscale
- Closed-source control server, limiting self-hosting options
- Requires paid plans for certain features and larger deployments
- Less flexibility for customization and modification
Code Comparison
Tailscale (Go):
func (c *Conn) Close() error {
c.mu.Lock()
defer c.mu.Unlock()
if c.closed {
return nil
}
c.closed = true
return c.pconn.Close()
}
Headscale (Go):
func (s *Server) Close() error {
s.mu.Lock()
defer s.mu.Unlock()
if s.closed {
return nil
}
s.closed = true
return s.listener.Close()
}
Both projects use similar patterns for closing connections, with mutex locks to ensure thread safety. The main difference lies in the specific components being closed (pconn vs. listener).
Headscale aims to provide an open-source, self-hosted alternative to Tailscale's control server. It offers greater control and customization but may lack some advanced features and polish of the official Tailscale implementation. Headscale is suitable for users prioritizing self-hosting and open-source solutions, while Tailscale is ideal for those seeking a more comprehensive, fully-supported networking solution.
Netmaker makes networks with WireGuard. Netmaker automates fast, secure, and distributed virtual networks.
Pros of Netmaker
- Supports multiple VPN protocols (WireGuard, OpenVPN, IPSec)
- Offers a user-friendly GUI for network management
- Provides advanced features like multi-cloud networking and split tunneling
Cons of Netmaker
- More complex setup and configuration process
- Requires additional infrastructure components (e.g., database)
- May have a steeper learning curve for beginners
Code Comparison
Headscale (Go):
func (ns *Namespace) GetMachine(machineKey key.MachinePublic) (*Machine, error) {
for _, machine := range ns.Machines {
if machine.PublicKey.Equal(machineKey) {
return machine, nil
}
}
return nil, ErrMachineNotFound
}
Netmaker (Go):
func (network *Network) GetNode(macaddress string) (models.Node, error) {
var node models.Node
record := database.DB.Where("macaddress = ? AND network = ?", macaddress, network.NetID).First(&node)
if errors.Is(record.Error, gorm.ErrRecordNotFound) {
return models.Node{}, errors.New("node not found")
}
return node, record.Error
}
Both projects use Go and implement similar functionality for retrieving network nodes/machines. Headscale uses in-memory storage, while Netmaker relies on a database (GORM) for persistence.
A scalable overlay networking tool with a focus on performance, simplicity and security
Pros of Nebula
- Lightweight and efficient peer-to-peer VPN solution
- Built-in security features like encryption and certificate-based authentication
- Highly scalable, suitable for large networks
Cons of Nebula
- Steeper learning curve for setup and configuration
- Limited centralized management capabilities
- Requires manual configuration for each node
Code Comparison
Headscale (Go):
func (h *Headscale) RegisterMachine(ctx context.Context, key *machine.MachineKey) (*machine.Machine, error) {
// Implementation details
}
Nebula (Go):
func (s *udpServer) ReadFromUDP(b []byte) (int, *net.UDPAddr, error) {
// Implementation details
}
Both projects are written in Go, but they serve different purposes. Headscale is a control server for Tailscale, while Nebula is a complete VPN solution. The code snippets show different aspects of their functionality: Headscale focuses on machine registration, while Nebula handles UDP communication.
Headscale provides a centralized management solution for Tailscale networks, making it easier to administer and control access. Nebula, on the other hand, offers a more distributed approach with peer-to-peer connections, providing better scalability and performance in certain scenarios.
Choose Headscale for easier management and integration with Tailscale, or Nebula for a lightweight, scalable VPN solution with strong security features.
Connect your devices into a secure WireGuard®-based overlay network with SSO, MFA and granular access controls.
Pros of Netbird
- User-friendly web UI for easier management and configuration
- Built-in support for multiple platforms (Windows, macOS, Linux, iOS, Android)
- Offers additional features like access control and activity logging
Cons of Netbird
- Closed-source control plane, limiting customization options
- Requires a centralized management server, potentially impacting privacy
Code Comparison
Headscale (Go):
func (s *Server) handleRegister(w http.ResponseWriter, r *http.Request) {
machineKey, err := key.NewMachinePublicKeyFromHex(r.Header.Get("Authorization"))
if err != nil {
http.Error(w, "Invalid machine key", http.StatusBadRequest)
return
}
// ... (additional registration logic)
}
Netbird (Go):
func (s *Server) handlePeerRegistration(w http.ResponseWriter, r *http.Request) {
peerKey, err := wgtypes.ParseKey(r.Header.Get("X-Peer-Key"))
if err != nil {
http.Error(w, "Invalid peer key", http.StatusBadRequest)
return
}
// ... (additional registration logic)
}
Both projects use Go and implement similar functionality for peer registration, but with different key handling approaches and naming conventions.
Connect your devices into a secure WireGuard®-based overlay network with SSO, MFA and granular access controls.
Pros of Netbird
- User-friendly web UI for easier management and configuration
- Built-in support for multiple platforms (Windows, macOS, Linux, iOS, Android)
- Offers additional features like access control and activity logging
Cons of Netbird
- Closed-source control plane, limiting customization options
- Requires a centralized management server, potentially impacting privacy
Code Comparison
Headscale (Go):
func (s *Server) handleRegister(w http.ResponseWriter, r *http.Request) {
machineKey, err := key.NewMachinePublicKeyFromHex(r.Header.Get("Authorization"))
if err != nil {
http.Error(w, "Invalid machine key", http.StatusBadRequest)
return
}
// ... (additional registration logic)
}
Netbird (Go):
func (s *Server) handlePeerRegistration(w http.ResponseWriter, r *http.Request) {
peerKey, err := wgtypes.ParseKey(r.Header.Get("X-Peer-Key"))
if err != nil {
http.Error(w, "Invalid peer key", http.StatusBadRequest)
return
}
// ... (additional registration logic)
}
Both projects use Go and implement similar functionality for peer registration, but with different key handling approaches and naming conventions.
A private network system that uses WireGuard under the hood.
Pros of innernet
- Built on WireGuard, offering better performance and simpler setup
- Designed for self-hosted, private networks with a focus on security
- Provides a user-friendly CLI for managing the network
Cons of innernet
- Less flexible than Headscale for public-facing VPN scenarios
- Smaller community and ecosystem compared to Headscale
- May require more manual configuration for complex network setups
Code Comparison
innernet configuration example:
[server]
external_address = "example.com:51820"
listen_port = 51820
private_key = "YOUR_PRIVATE_KEY"
Headscale configuration example:
server_url: http://127.0.0.1:8080
listen_addr: 0.0.0.0:8080
private_key_path: /var/lib/headscale/private.key
Both projects aim to provide secure networking solutions, but they have different focuses. innernet is designed for private, self-hosted networks using WireGuard, while Headscale is a more flexible implementation of the Tailscale control server. The choice between them depends on specific use cases and network requirements.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
An open source, self-hosted implementation of the Tailscale control server.
Join our Discord server for a chat.
Note: Always select the same GitHub tag as the released version you use
to ensure you have the correct example configuration and documentation.
The main
branch might contain unreleased changes.
What is Tailscale
Tailscale is a modern VPN built on top of Wireguard. It works like an overlay network between the computers of your networks - using NAT traversal.
Everything in Tailscale is Open Source, except the GUI clients for proprietary OS (Windows and macOS/iOS), and the control server.
The control server works as an exchange point of Wireguard public keys for the nodes in the Tailscale network. It assigns the IP addresses of the clients, creates the boundaries between each user, enables sharing machines between users, and exposes the advertised routes of your nodes.
A Tailscale network (tailnet) is private network which Tailscale assigns to a user in terms of private users or an organisation.
Design goal
Headscale aims to implement a self-hosted, open source alternative to the Tailscale control server. Headscale's goal is to provide self-hosters and hobbyists with an open-source server they can use for their projects and labs. It implements a narrow scope, a single Tailnet, suitable for a personal use, or a small open-source organisation.
Supporting Headscale
If you like headscale
and find it useful, there is a sponsorship and donation
buttons available in the repo.
Features
- Full "base" support of Tailscale's features
- Configurable DNS
- Node registration
- Single-Sign-On (via Open ID Connect)
- Pre authenticated key
- Taildrop (File Sharing)
- Access control lists
- MagicDNS
- Dual stack (IPv4 and IPv6)
- Routing advertising (including exit nodes)
- Ephemeral nodes
- Embedded DERP server
Client OS support
OS | Supports headscale |
---|---|
Linux | Yes |
OpenBSD | Yes |
FreeBSD | Yes |
macOS | Yes (see /apple on your headscale for more information) |
Windows | Yes docs |
Android | Yes docs |
iOS | Yes docs |
Running headscale
Please note that we do not support nor encourage the use of reverse proxies and container to run Headscale.
Please have a look at the documentation
.
Talks
- Fosdem 2023 (video): Headscale: How we are using integration testing to reimplement Tailscale
- presented by Juan Font Alonso and Kristoffer Dalby
Disclaimer
This project is not associated with Tailscale Inc.
However, one of the active maintainers for Headscale is employed by Tailscale and he is allowed to spend work hours contributing to the project. Contributions from this maintainer are reviewed by other maintainers.
The maintainers work together on setting the direction for the project. The underlying principle is to serve the community of self-hosters, enthusiasts and hobbyists - while having a sustainable project.
Contributing
Please read the CONTRIBUTING.md file.
Requirements
To contribute to headscale you would need the latest version of Go and Buf(Protobuf generator).
We recommend using Nix to setup a development environment. This can
be done with nix develop
, which will install the tools and give you a shell.
This guarantees that you will have the same dev env as headscale
maintainers.
Code style
To ensure we have some consistency with a growing number of contributions, this project has adopted linting and style/formatting rules:
The Go code is linted with golangci-lint
and
formatted with golines
(width 88) and
gofumpt
.
Please configure your editor to run the tools while developing and make sure to
run make lint
and make fmt
before committing any code.
The Proto code is linted with buf
and
formatted with clang-format
.
The rest (Markdown, YAML, etc) is formatted with prettier
.
Check out the .golangci.yaml
and Makefile
to see the specific configuration.
Install development tools
- Go
- Buf
- Protobuf tools
Install and activate:
nix develop
Testing and building
Some parts of the project require the generation of Go code from Protobuf
(if changes are made in proto/
) and it must be (re-)generated with:
make generate
Note: Please check in changes from gen/
in a separate commit to make it easier to review.
To run the tests:
make test
To build the program:
nix build
or
make build
Contributors
Made with contrib.rocks.
Top Related Projects
The easiest, most secure way to use WireGuard and 2FA.
Netmaker makes networks with WireGuard. Netmaker automates fast, secure, and distributed virtual networks.
A scalable overlay networking tool with a focus on performance, simplicity and security
Connect your devices into a secure WireGuard®-based overlay network with SSO, MFA and granular access controls.
Connect your devices into a secure WireGuard®-based overlay network with SSO, MFA and granular access controls.
A private network system that uses WireGuard under the hood.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot