How to set up Headscale on Saplo: a private network with Tailscale clients

A laptop at home, a server in the office, and a test computer at a co-worker's place all need to operate on a single private network, even if each device uses a different connection. Headscale allows you to manage such a network from your own coordinating server. In this guide, we'll show you how to set up Headscale on Saplo, connect your first devices, and check communication between them.

What is Headscale

Headscale is an open-source implementation of a coordination server for Tailscale clients. You install the Tailscale client on your devices, but point it to your own Headscale server. The project is primarily designed for personal networks and small organizations. The scope of the project is described in the official Headscale documentation.

This solution is for a home lab administrator, a developer working on several machines, or a small team. It's worth starting with two of your own devices before adding colleagues' equipment and establishing access rules.

Installing Headscale does not automatically grant access to the Saplo Box private network. The server coordinates devices that you register with it. The mere fact of running the application on a Box does not make the Box a participant in that network.

Requirements and Hosting Headscale on Saplo

The cheapest plan that meets the installation requirements is Box S for $29 per year. The Headscale recipe requires a minimum of 256 MB RAM and 2 GB disk space. If other applications are running on your Box, check the remaining free resources as well. You can find a description of the service on the Headscale hosting page on Saplo.

Prepare an active Box, the application name, its target address, and two devices to test the connection. Box S provides a panel and SFTP, without SSH. You will perform the installation from the panel, and you can download the startup instructions file from the application catalog via SFTP. The Tailscale client commands in this guide are run on your computer, not on the Box.

Step-by-step installation

1. Log in to the Saplo panel and go to the app catalog.
2. Select Headscale and start creating the application.
3. Give it a name, for example my-network, and indicate a Box with available resources.
4. Select a domain or an available subdomain *.saploapp.pl. Keep the exact address displayed in the panel.
5. Confirm the installation and wait for the deployment to complete. Check the application status and messages instead of assuming a specific waiting time.
6. Connect via SFTP using your Box's access data and locate the HEADSCALE-SETUP.txt file in the application's directory. Download it to your computer and open it as text.

The installer prepares the Headscale service, a local SQLite database, configuration, and a starting user admin. There's no need to set up a separate database. The HTTPS address is the coordinating server's address, not a browser management panel. This installation does not include a separate graphical Headscale panel.

Startup Key and First Device

The HEADSCALE-SETUP.txt file contains the server address and the connection command with the generated key. The startup key is valid for 24 hours from generation and can be used multiple times during this period. Treat the entire file as access data: do not publish it in a repository or on screenshots.

On the first Linux computer, install the client from the official Tailscale website. Then, execute the command from the startup file in the terminal, with the permissions required by the system. Its scheme looks like this:

sudo tailscale up --login-server=https://YOUR-HEADSCALE-ADDRESS --authkey=KEY-FROM-FILE

Replace both example fields with your own values. Do not enter your Saplo panel password here. The method of registration with a key is described in the Headscale client startup documentation.

If the computer is already connected to another Tailscale network, plan the change consciously. Do not switch the only remote connection to the machine in this way. For the first attempt, choose hardware to which you also have local access.

If the file indicates that the key could not be generated, or the key has expired, a new key created on the Headscale side is needed. Box S does not provide SSH to execute administrative commands from the file. In such a situation, contact Saplo Support for further configuration, providing the application name and message, without sending the key. Do not delete a working installation just to re-register the device.

Second device and connection check

On the second Linux computer, install the client and point it to the same server address. You can reuse the startup key during its validity period for this attempt. For Windows, Android, and Apple devices, follow the platform-specific instructions in the Headscale client documentation; the method for pointing to your own server depends on the system.

On both computers, check the client's status and the assigned address:

tailscale status
tailscale ip -4

Then, on the first computer, execute the following, substituting the address of the second computer:

tailscale ping SECOND-DEVICE-ADDRESS

These commands are described in the Tailscale CLI documentation. Also, check the specific service you intend to use, for example, an SSH connection to your own server via its VPN address. The service must be running, and its access must be allowed by the firewall and network rules. The mere appearance of the device on the list does not confirm that the application is working.

It's worth repeating the test with different internet connections, for example, with the second computer connected via a phone hotspot. Record the result and check the reconnection after restarting the client.

What happens to traffic and access

Saplo's recipe uses the public Tailscale DERP relay map and does not run its own DERP. Therefore, your own coordinating server does not mean that the entire installation is independent of Tailscale's infrastructure. Also, do not treat Box parameters as a guarantee of connection bandwidth between devices.

Before adding a team, plan separate users, access rules, and how to remove unused devices. A shared starter user is for getting started, but it doesn't replace the target permission split. Keep a secure copy of your Headscale configuration and data. The starter key file itself is not a backup of the service.

FAQ

How much does Headscale hosting cost?

Box S for $29 per year is enough to start. If you share a Box with other applications, consider their memory and disk usage.

Why don't I see the login panel under the domain?

This installation provides a coordinating server without a graphical administration panel. Start with the application status and the HEADSCALE-SETUP.txt file, and check network operation with the Tailscale client.

Why isn't the device joining?

Compare the server address with the startup file, check HTTPS availability and key validity. Pay attention to whether the client is trying to log into the default Tailscale service. Keep the error content, removing keys before submitting it for Support.

Does Headscale replace the Tailscale client?

No. You still use the Tailscale client on your devices. Headscale acts as your own coordinating server.

Do I need to open SSH on the Box to get started?

Not for installation from the catalog and the first connection using a correctly generated key. Further management of users, keys and access policy requires administrative actions on the Headscale side. Consider this when planning to use the service permanently on Box S without SSH.

Open the Headscale offer on Saplo, launch the application, and start by connecting two of your own devices. Only after checking communication and access rules should you add more machines.