Where Does Headscale Store Config and Data?
Headscale reads config.yaml from /etc/headscale first, with its SQLite database at /var/lib/headscale/db.sqlite.
Last updated
Headscale looks for config.yaml in three places, in order: /etc/headscale, ~/.headscale, and the current directory. Package installs use the first. The database defaults to SQLite at /var/lib/headscale/db.sqlite, with Postgres kept only for legacy setups.
Upgrades deserve respect here, since schema migrations run automatically and old mistakes compound. The documented drill is stop, copy the database plus WAL sidecars, then start and let migration run. Config and database travel as a pair on every move.
Where Headscale stores this, by platform
/etc/headscale/config.yaml
First search path and package default. Validate edits with headscale configtest. ACL policies and DERP settings live in this file.
/var/lib/headscale/db.sqlite
Default SQLite location with WAL mode on. Back up the -wal and -shm sidecars alongside it while the service is stopped.
Frequently asked questions
How do I back up Headscale before upgrading?
Stop the service, then copy db.sqlite plus any db.sqlite-wal and db.sqlite-shm sidecars. Copying while running splits the database from its write ahead log.
How do I point Headscale at a different config file?
Pass the config flag or set HEADSCALE_CONFIG in the environment. The search order is /etc/headscale, home .headscale, then the working directory.
How do I check a Headscale config edit?
Run headscale configtest after editing. It validates the file before a restart turns a typo into downtime for every tailnet node.
Notice an outdated path? Let us know.