headscale with remote CLI¶
- A workstation to run
headscale(could be Linux, macOS, other supported platforms)
- Access to create API keys (local access to the
headscalemust be served over TLS/HTTPS
- Remote access does not support unencrypted traffic.
50443must be open in the firewall (or port overriden by
This documentation has the goal of showing a user how-to set control a
headscale instance from a remote machine with the
headscale command line binary.
Create an API key¶
We need to create an API key to authenticate our remote
headscale when using it from our workstation.
To create a API key, log into your
headscale server and generate a key:
Copy the output of the command and save it for later. Please note that you can not retrieve a key again, if the key is lost, expire the old one, and create a new key.
To list the keys currently assosicated with the server:
and to expire a key:
Download and configure
Download the latest
headscalebinary from GitHub's release page:
Put the binary somewhere in your
- Configure the CLI through Environment Variables
This will tell the
headscale binary to connect to a remote instance, instead of looking for a local instance (which is what it does on the server).
The API key is needed to make sure that your are allowed to access the server. The key is not needed when running directly on the server, as the connection is local.
- Test the connection
Let us run the headscale command to verify that we can connect by listing our nodes:
You should now be able to see a list of your nodes from your workstation, and you can now control the
headscale server from your workstation.
Behind a proxy¶
It is possible to run the gRPC remote endpoint behind a reverse proxy, like Nginx, and have it run on the same port as
While this is not a supported feature, an example on how this can be set up on NixOS is shown here.
- Make sure you have the same
headscaleversion on your server and workstation
- Make sure you use version
- Verify that your TLS certificate is valid and trusted
- If you do not have access to a trusted certificate (e.g. from Let's Encrypt), add your self signed certificate to the trust store of your OS or
HEADSCALE_CLI_INSECUREto 0 in your environement