Skip to content

# Configuration

- Headscale loads its configuration from a YAML file
- It searches for `config.yaml` in the following paths:
  - `/etc/headscale`
  - `$HOME/.headscale`
  - the current working directory
- To load the configuration from a different path, use:
  - the command line flag `-c`, `--config`
  - the environment variable `HEADSCALE_CONFIG`
- Validate the configuration file with: `headscale configtest`

Get the example configuration from the GitHub repository

Always select the same GitHub tag as the released version you use to ensure you have the correct example configuration. The `main` branch might contain unreleased changes.

View on GitHubDownload with `wget`Download with `curl`

- Development version: https://github.com/juanfont/headscale/blob/main/config-example.yaml
- Version 0.29.1: https://github.com/juanfont/headscale/blob/v0.29.1/config-example.yaml

    # Development version
    wget -O config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml

    # Version 0.29.1
    wget -O config.yaml https://raw.githubusercontent.com/juanfont/headscale/v0.29.1/config-example.yaml

    # Development version
    curl -o config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml

    # Version 0.29.1
    curl -o config.yaml https://raw.githubusercontent.com/juanfont/headscale/v0.29.1/config-example.yaml