How to install Headscale on macOS

Headscale is a self-hosted WireGuard VPN server designed for keeping security and privacy as priority. In this tutorial, we will be showing you how to install Headscale on macOS.

Before you begin, ensure that the following prerequisites are installed:

  • Homebrew
  • Go

Step 1 - Install WireGuard

To install WireGuard on your macOS, you can use the Homebrew package manager. If you don't have Homebrew installed, you can follow the official documentation here to install Homebrew on your system.

To install WireGuard, run the following command in your terminal:

brew install wireguard-go

Step 2 - Clone the Headscale repository

Next, we need to clone the Headscale repository from GitHub. To do this, open your terminal and run the following command:

git clone https://github.com/juanfont/headscale.git

Step 3 - Build Headscale

In this step, we will build the Headscale binary with Go. Change your working directory to the cloned Headscale repository and use the following command:

go build -o headscale ./cmd/headscale

Step 4 - Generate configuration

With Headscale binary built, we need to generate a configuration file. To generate a configuration file, run the following command:

./headscale initconfig

This will create a configuration file called config.yaml in the current directory.

Step 5 - Update configuration

The configuration file needs to be updated with your WireGuard configuration details. Open the config.yaml file in your preferred text editor and make the following changes:

  1. Set wgdevice to wireguard-go. Example:

    wgdevice: wireguard-go

  2. Set the wgport to a value you will use in the future.

  3. Set the default_route_ipv4 and default_route_ipv6 to the IP address of your default gateway.

  4. Change dbfile to point to the desired path for your database (e.g. /var/lib/headscale/database.sqlite3).

Step 6 - Start Headscale

With the configuration file created and updated, we can start Headscale.

To start Headscale, use the following command in your terminal:

./headscale serve

Headscale should now be up and running.

Conclusion

In this tutorial, we have shown you how to install Headscale on macOS using Go and Homebrew. Now you can start using Headscale to host your own secure and private VPN server.