Convert Figma logo to code with AI

juanfont logoheadscale

An open source, self-hosted implementation of the Tailscale control server

22,053
1,221
22,053
84

Top Related Projects

18,532

The easiest, most secure way to use WireGuard and 2FA.

Netmaker makes networks with WireGuard. Netmaker automates fast, secure, and distributed virtual networks.

14,290

A scalable overlay networking tool with a focus on performance, simplicity and security

10,528

Connect your devices into a secure WireGuard®-based overlay network with SSO, MFA and granular access controls.

10,528

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:

  1. Install Headscale on your server:
# For Debian/Ubuntu
sudo apt-get install headscale

# For macOS using Homebrew
brew install headscale
  1. Configure Headscale by editing the configuration file:
sudo nano /etc/headscale/config.yaml
  1. Start the Headscale service:
sudo systemctl start headscale
  1. Generate a pre-authorization key:
headscale preauthkeys create --user username --expiration 24h
  1. 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

18,532

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.

14,290

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.

10,528

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.

10,528

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 Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

headscale logo

ci

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

OSSupports headscale
LinuxYes
OpenBSDYes
FreeBSDYes
macOSYes (see /apple on your headscale for more information)
WindowsYes docs
AndroidYes docs
iOSYes 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

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.