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.
- Headscale is reachable from the Internet. Verify this by visiting the health endpoint: https://headscale.example.com/health
- 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:

NativeContainer

    # 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 headscale from another local user

By default only the user `headscale` or `root` will have the necessary permissions to access the unix socket (`/var/run/headscale/headscale.sock`) that is used to communicate with the service. In order to be able to communicate with the headscale service you have to make sure the unix socket is accessible by the user that runs the commands. In general you can achieve this by any of the following methods:

- using `sudo`
- run the commands as user `headscale`
- add your user to the `headscale` group

To verify you can run the following command using your preferred method:

    headscale users list

## Manage headscale users

In headscale, a node (also known as machine or device) is typically assigned to a headscale user. Such a headscale user1 may have many nodes assigned to them and can be managed with the `headscale users` command. Invoke the built-in help for more information: `headscale users --help`.

### Create a headscale user

NativeContainer

    headscale users create <USER>

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

### List existing headscale users

NativeContainer

    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 server 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. Read registration methods for an overview of available registration methods.

### Web authentication

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. This page explains how to complete the registration on your headscale server and it also prints the Auth ID required to approve the node:

NativeContainer

    headscale auth register --user <USER> --auth-id <AUTH_ID>

    docker exec -it headscale \
      headscale auth register --user <USER> --auth-id <AUTH_ID>

### Pre authenticated key

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):

NativeContainer

    headscale preauthkeys create --user <USER_ID>

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

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>

1. Ensure that the Headscale username does not end with `@`. ↩