Self hosted

Headscale: Awesome Self-Hosted Tailscale Control Server

Networking has undergone significant transformations in recent years, driven by many open-source projects that present new possibilities. If you are a home lab enthusiast, you may host many self-hosted services in your lab. Accessing these services remotely or when traveling presents challenges and possibly security issues if you open ports to the Internet. Tailscale and its open-source alternative, Headscale, offer unique solutions as we move towards more decentralized and private networks. Let’s look at Headscale, an excellent way to host your Tailscale control server, be self-sufficient with the Tailscale open-source project, and control all aspects of your connectivity.

What is Tailscale?

Tailscale is a powerful tool that creates a secure, private network between your devices, regardless of their location. It leverages WireGuard, a modern VPN protocol, to establish encrypted peer-to-peer connections. With the Tailscale network, you gain secure access to your devices and services as if you were on the same local network.

Tailscale remote network VPN solution
Tailscale remote network VPN solution

All components of Tailscale are open source, with the exception of the GUI clients for proprietary operating systems like Windows and macOS/iOS, as well as the control server.

Functioning as a central hub for the exchange of Wireguard public keys, the control server is integral to the operation of the Tailscale network. It is responsible for assigning IP addresses to clients, establishing user boundaries, facilitating machine sharing between users, and managing the advertised routes of your nodes.

In Tailscale’s terminology, a “tailnet” refers to a private network assigned to an individual user or an organization by Tailscale. This tailnet is a private space in the network structure designed for secure, managed interactions.

What is Headscale?

Headscale, on the other hand, is an open-source implementation of the Tailscale control server. Developed to give users control over their private networks, Headscale allows users to host their own Tailscale networks. As a completely open-source project, it empowers you to manage and operate your network without relying on Tailscale’s hosted solution.

Headscale open source control server for Tailscale
Headscale open source control server for Tailscale

Headscale aims to equip self-hosting enthusiasts and hobbyists with an open-source server that they can employ for their various projects and labs. It offers a focused implementation, accommodating a single Tailnet. This makes it ideal for personal use or for small open-source organizations.

Headscale features

Headscale boasts a variety of features, which include:

  1. Comprehensive support for fundamental Tailscale features

  2. Customizable DNS

  3. Split DNS capabilities

  4. Node registration functionality

  5. Single-Sign-On facilitated through Open ID Connect

  6. Pre-authenticated keys

  7. Taildrop feature for File Sharing

  8. Access Control Lists for security and permissions management

  9. MagicDNS, a simplified DNS management feature

  10. Capability to support multiple IP ranges within the tailnet

  11. Dual stack compatibility, supporting both IPv4 and IPv6

  12. Routing advertising, encompassing exit nodes

  13. Ephemeral nodes for temporary network members

  14. An embedded DERP server for reliable connectivity.

The Value of Open Source in Networking

The open-source model has been instrumental in developing many innovative networking tools, and Headscale is a prime example of this. As an open-source alternative to Tailscale’s control server, it allows for customization and control that isn’t typically possible with commercial offerings. The fact that it’s an open-source project also allows users to contribute to its development, resulting in a tool that continually evolves and improves based on community input.

Harnessing the Potential of Headscale

Setting up Headscale: The Basics

Headscale operates in sync with the Tailscale clients, managing their access to your private network. Its installation involves creating a config file, typically in a YAML format, where you define key aspects like your server’s IP address, private keys, and more.

Headscale can be set up on multiple operating systems, including Linux and Windows. It ensures that your Tailscale network is secure, efficient, and completely self-hosted.

Notable Features of Headscale

Headscale, being feature complete, supports all Tailscale clients, including their Windows and Android app. This means connecting devices running these operating systems to your Headscale-hosted Tailscale network.

How Headscale Fits in Your Use Case

Whether you are looking to secure your personal data, manage a private network for a project, or even host a larger corporate network, Headscale has valuable tools to offer. With Headscale, you can have direct control over your private network without compromising on security or performance.

Contributing to Headscale: Open Source Collaboration

One of the beautiful aspects of Headscale is that it is a project that invites contribution from its users. Open source code allows users to submit bug reports, suggest features, and even contribute to the project’s development. The growing number of contributors is a testament to the project’s success and the value it offers.

In-depth into Headscale’s Inner Workings

Understanding Headscale’s Architecture

Headscale’s architecture is based around the Tailscale protocol. This protocol is built on WireGuard and uses it to establish encrypted VPN connections between nodes on a network. The role of Headscale is essentially to coordinate these nodes, a feature that’s very valuable for those wanting to self-host their networks.

At the heart of Headscale is its server, which you can host on your own infrastructure. The server is responsible for managing the private keys of the nodes, and it’s crucial for the successful operation of your private network. It’s worth noting that these keys are only used for authentication purposes; they do not have access to your network traffic.

The Headscale Web UI: Simplifying Network Management

A notable addon for Headscale is the Headscale Web UI, a handy tool that offers a graphical interface for managing your Tailscale network. Through the Web UI, you can monitor network activity, manage access to your network, and adjust various settings as per your requirements. This feature makes network management more accessible and user-friendly, especially for those new to the networking world.

You can check out that project here: GitHub – gurucomputing/headscale-ui: A web frontend for the headscale Tailscale-compatible coordination server

Web UI for headscale
Web UI for headscale

Headscale’s Cross-Platform Support

Headscale is designed to support a wide range of platforms. The Headscale server can be set up on various operating systems, including Linux and Windows. Meanwhile, Tailscale clients – which are compatible with Headscale – are available for even more platforms. This means you can connect a wide variety of devices to your self-hosted Tailscale network, making Headscale a highly versatile tool for managing your private network.

Installing Headscale – What’s required?

It is important to note the developer for Headscale makes mention in the Github repository, they do not encourage or support the use of containers or reverse proxies for Headscale. So, this is something to keep in mind.

However, you will find community projects like here: that show how to get up and running with Headscale in a Docker container.

So for the purposes of this install walkthrough, I am using an Ubuntu 22.04 virtual machine.

Loading Headscale on Ubuntu 22.04 virtual machine
Loading Headscale on Ubuntu 22.04 virtual machine

First we need to download the .deb file used for the installation of headscale. To do that, I used the latest version of headscale (at the time of this writing) as an example. Below is the command I used:

wget --output-document=headscale.deb
Downloading the installer file for Headscale on Ubuntu
Downloading the installer file for Headscale on Ubuntu

Now, we install the package.

sudo dpkg --install headscale.deb
Installing the deb package in Ubuntu
Installing the deb package in Ubuntu

Now we enable the headscale service.

sudo systemctl enable headscale
Enabling headscale service
Enabling headscale service

Now we need to customize the server URL and the listen address.

Customizing the Headscale configuration file
Customizing the Headscale configuration file

Start the headscale service and get the status of the service.

sudo systemctl start headscale
systemctl status headscale
Start headscale and get the status of the service
Start headscale and get the status of the service

Now we need to create a namespace/user. The namespace directive appears to now be deprecated. Even if you issue the namespaces command, you will see it creates a user.

sudo headscale namespaces create <your namespace>
sudo headscale users create <your user> 
Creating a headscale namespace or user
Creating a headscale namespace or user

You can use the following command to list the namespaces/users:

sudo headscale namespaces list
Listing out the namespaces
Listing out the namespaces

Now we can create a preauthkey to authenticate with a client. As an example, you can use the following to create your preauth key along with the expiration time:

sudo headscale --user <your user/namespace> preauthkeys create --expiration <expiration time>
Creating preauth keys for tailscale clients to authenticate
Creating preauth keys for tailscale clients to authenticate

Installing the Tailscale client and connecting a client to headscale

Now that we have the headscale server running, we can install Tailscale and connect our client. First, let’s install the tailscale client. On an Ubuntu 22.04 workstation, you can use the command:

curl -fsSL | sh
Installing the tailscale client
Installing the tailscale client

After the client installation, to connect the client, you can use the command:

sudo tailscale up --login-server <your server URL> --authkey <your authkey generated in the previous step>
Connecting the tailscale client to the headscale control server
Connecting the tailscale client to the headscale control server

Once you connect your client, you can see the connected client with the command:

sudo headscale nodes list 
Viewing connected Tailscale clients on the headscale control server
Viewing connected Tailscale clients on the headscale control server

Practical Example: Setting up a Self-Hosted Tailscale Network

Let’s consider a simple example to demonstrate the practical application of these technologies. Suppose you have a set of devices scattered across various locations – your home PC, your work laptop, a server in a data center, and a mobile device. With Tailscale and Headscale, you can connect these devices into a single Tailnet (Tailscale network), regardless of their geographical locations or the networks they’re connected to.

After setting up the Headscale server on an operating system of your choice and configuring it using the config file, you can install the Tailscale clients on your devices and connect them to your Tailscale network.

Frequently Asked Questions

What are the benefits of a self-hosted Tailscale network?

A self-hosted Tailscale network gives you complete control over your network configuration and data. This ensures higher privacy and allows for custom configuration based on your unique needs.

Can I use Headscale for my personal use?

Absolutely. Headscale is suitable for both personal and professional use. It’s a great tool for managing access to your devices and services securely.

How can I contribute to the Headscale project?

You can contribute to the Headscale project by submitting bug reports, suggesting new features, or even writing code. The project is open source, and contributions from the community are always welcome.

How secure is Headscale?

Headscale, as a self-hosted Tailscale control server, adopts the same high-level security measures as Tailscale. This includes using encryption for all network traffic, securing data in transit. However, the security of a Headscale network is also largely determined by the security measures implemented by the user, including server configurations, access control policies, and the secure handling of private keys.

Can Headscale be used on multiple platforms?

Yes, Headscale is versatile and can be used on various operating systems. Its functionality spans Linux, Windows, macOS, and more. This cross-platform compatibility makes it suitable for diverse environments with different operating systems.

Is it challenging to manage a Headscale network?

setting up and managing a Headscale network requires some technical understanding, its design aims to simplify the management of complex network topologies. Tools like the web UI and config files make it easier to manage the network. An active community and ample documentation are also available to help users navigate any challenges.

Does Headscale support traffic between clients?

Headscale does support traffic between clients. This is one of the features that makes it a powerful tool for creating private networks. However, how the traffic flows – directly between clients or via the server – can depend on the network configuration and settings in the individual client setups.

Wrapping Up

Open-source tools like Tailscale and Headscale are transforming how we manage our networks, offering excellent control, security, and versatility. Whether you’re a hobbyist looking for a convenient way to manage your devices or a business seeking a robust solution for your networking needs, these tools offer significant advantages.

As open-source projects, both Tailscale and Headscale offer the potential for community-driven development, creating continuous improvement and customization opportunities. Headscale, a self-hosted implementation of Tailscale’s control server, is an excellent way for home lab enthusiasts to connect their nodes and access private resources without needing to open ports on their firewall.

Subscribe to VirtualizationHowto via Email 🔔

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

Brandon Lee

Brandon Lee is the Senior Writer, Engineer and owner at and has over two decades of experience in Information Technology. Having worked for numerous Fortune 500 companies as well as in various industries, Brandon has extensive experience in various IT segments and is a strong advocate for open source technologies. Brandon holds many industry certifications, loves the outdoors and spending time with family.

Related Articles

One Comment

  1. I find your tutorial interesting. However, it would be a more comprehensive and complete tutorial if you had included the fact that certain ports needed to be opened in the host system.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.