Skip to content

Getting started

This page helps you get started with headscale and provides a few usage examples for the headscale command line tool headscale.

Prerequisites

  • Headscale is installed and running as system service. Read the setup section for installation instructions.
  • The configuration file exists and is adjusted to suit your environment, see Configuration for details.
  • The Tailscale client is installed, see Client and operating system support for more information.

Getting help

The headscale command line tool provides built-in help. To show available commands along with their arguments and options, run:

# Show help
headscale help

# Show help for a specific command
headscale <COMMAND> --help

# Show help
docker exec -it headscale \
  headscale help

# Show help for a specific command
docker exec -it headscale \
  headscale <COMMAND> --help

Manage users

In headscale, a node (also known as machine or device) is always assigned to a specific user, a tailnet. Such users can be managed with the headscale users command. Invoke the built-in help for more information: headscale users --help.

Create a user

headscale users create <USER>

docker exec -it headscale \
  headscale users create <USER>

List existing users

headscale users list

docker exec -it headscale \
  headscale users list

Register a node

One has to register a node first to use headscale as coordination with Tailscale. The following examples work for the Tailscale client on Linux/BSD operating systems. Alternatively, follow the instructions to connect Android, Apple or Windows devices.

Normal, interactive login

On a client machine, run the tailscale up command and provide the FQDN of your headscale instance as argument:

tailscale up --login-server <YOUR_HEADSCALE_URL>

Usually, a browser window with further instructions is opened and contains the value for <YOUR_MACHINE_KEY>. Approve and register the node on your headscale server:

headscale nodes register --user <USER> --key <YOUR_MACHINE_KEY>

docker exec -it headscale \
  headscale nodes register --user <USER> --key <YOUR_MACHINE_KEY>

Using a preauthkey

It is also possible to generate a preauthkey and register a node non-interactively. First, generate a preauthkey on the headscale instance. By default, the key is valid for one hour and can only be used once (see headscale preauthkeys --help for other options):

headscale preauthkeys create --user <USER>

docker exec -it headscale \
  headscale preauthkeys create --user <USER>

The command returns the preauthkey on success which is used to connect a node to the headscale instance via the tailscale up command:

tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>