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.

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

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

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

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