Skip to main content
The Headscale server is configured via config/config.yaml. This file controls all aspects of the control server including networking, database connections, DNS, and policy management.

​
Configuration File Location

The configuration file is mounted at /etc/headscale/config.yaml inside the Headscale container. 
volumes:
  - ./config:/etc/headscale
  - ./data:/var/lib/headscale

​
Server Configuration

​
server_url
string
required
The public URL of your Headscale server. This URL is provided to clients when they connect.Development: http://localhost:8000Production: https://your-domain.com
server_url: http://localhost:8000
​
listen_addr
string
default:"0.0.0.0:8080"
The address and port that Headscale listens on for HTTP connections.
listen_addr: 0.0.0.0:8080
​
metrics_listen_addr
string
default:"0.0.0.0:9090"
The address and port for Prometheus metrics endpoint.
metrics_listen_addr: 0.0.0.0:9090
Access metrics at http://localhost:9090/metrics

​
gRPC Configuration

​
grpc_listen_addr
string
default:"0.0.0.0:50443"
The address and port for gRPC API connections.
grpc_listen_addr: 0.0.0.0:50443
​
grpc_allow_insecure
boolean
default:false
Whether to allow insecure gRPC connections. Should be false in production.
grpc_allow_insecure: false

​
Encryption Keys

​
private_key_path
string
required
Path to the server’s private key file. This is automatically generated on first startup.
private_key_path: /var/lib/headscale/private.key
​
noise.private_key_path
string
required
Path to the Noise protocol private key for encrypted control plane communication.
noise:
  private_key_path: /var/lib/headscale/noise_private.key

​
IP Address Allocation

​
prefixes.v4
string
default:"100.64.0.0/10"
IPv4 CGNAT range for the Tailscale network.
prefixes:
  v4: 100.64.0.0/10
Do not change this unless you have a specific reason. This is the standard Tailscale range.
​
prefixes.v6
string
default:"fd7a:115c:a1e0::/48"
IPv6 Unique Local Address (ULA) range for the network.
prefixes:
  v6: fd7a:115c:a1e0::/48

​
DERP Configuration

DERP (Designated Encrypted Relay for Packets) servers facilitate NAT traversal when direct connections aren’t possible.
​
derp.server.enabled
boolean
default:false
Enable embedded DERP server in Headscale.
derp:
  server:
    enabled: false
​
derp.urls
array
List of DERP map URLs. By default, uses Tailscale’s public DERP servers.
derp:
  urls:
    - https://controlplane.tailscale.com/derpmap/default
​
derp.auto_update_enabled
boolean
default:true
Automatically update DERP map from configured URLs.
derp:
  auto_update_enabled: true
  update_frequency: 24h

​
Database Configuration

​
database.type
string
required
Database backend type. Use postgres for production deployments.Options: sqlite, postgres
database:
  type: postgres
​
database.postgres.host
string
required
PostgreSQL server hostname. Use the Docker service name for container deployments.
database:
  postgres:
    host: postgres
    port: 5432
​
database.postgres.name
string
required
Database name.
database:
  postgres:
    name: headscale
​
database.postgres.user
string
required
Database user.
database:
  postgres:
    user: headscale
​
database.postgres.pass
string
required
Database password.
database:
  postgres:
    pass: changeme  # Must match POSTGRES_PASSWORD in .env
This password must match POSTGRES_PASSWORD in your .env file.
​
database.postgres.max_open_conns
integer
default:10
Maximum number of open connections to the database.
database:
  postgres:
    max_open_conns: 10
    max_idle_conns: 10
    conn_max_idle_time_secs: 3600

​
DNS Configuration

​
dns.magic_dns
boolean
default:true
Enable MagicDNS for automatic hostname resolution within the network.
dns:
  magic_dns: true
​
dns.base_domain
string
default:"headscale.net"
Base domain for MagicDNS hostnames. Nodes will be accessible at <nodename>.headscale.net.
dns:
  base_domain: headscale.net
​
dns.nameservers.global
array
default:["1.1.1.1","1.0.0.1"]
Global DNS nameservers for external domain resolution.
dns:
  nameservers:
    global:
      - 1.1.1.1
      - 1.0.0.1

​
Unix Socket

​
unix_socket
string
default:"/var/run/headscale/headscale.sock"
Path to Unix socket for local CLI communication.
unix_socket: /var/run/headscale/headscale.sock
unix_socket_permission: "0770"

​
Logging

​
log.format
string
default:"text"
Log output format.Options: text, json
log:
  format: text
  level: info
​
log.level
string
default:"info"
Logging verbosity level.Options: trace, debug, info, warn, error
log:
  level: info

​
Policy Configuration

​
policy.mode
string
default:"database"
ACL policy storage mode.Options:
  • file: Read-only policy from file
  • database: Editable policy via API/GUI (recommended)
policy:
  mode: database
  path: /etc/headscale/policy.json
Use database mode to manage policies through Headplane GUI.

​
Node Management

​
ephemeral_node_inactivity_timeout
duration
default:"30m"
Time before inactive ephemeral nodes are automatically removed.
ephemeral_node_inactivity_timeout: 30m
​
node_update_check_interval
duration
default:"10s"
Interval for checking node status updates.
node_update_check_interval: 10s

​
Miscellaneous

​
disable_check_updates
boolean
default:false
Disable automatic checking for Headscale updates.
disable_check_updates: false
​
randomize_client_port
boolean
default:false
Randomize client UDP port for better NAT traversal.
randomize_client_port: false

​
Complete Example

config/config.yaml
server_url: http://localhost:8000

listen_addr: 0.0.0.0:8080
metrics_listen_addr: 0.0.0.0:9090

grpc_listen_addr: 0.0.0.0:50443
grpc_allow_insecure: false

private_key_path: /var/lib/headscale/private.key

noise:
  private_key_path: /var/lib/headscale/noise_private.key

prefixes:
  v6: fd7a:115c:a1e0::/48
  v4: 100.64.0.0/10

derp:
  server:
    enabled: false
  urls:
    - https://controlplane.tailscale.com/derpmap/default
  auto_update_enabled: true
  update_frequency: 24h

database:
  type: postgres
  postgres:
    host: postgres
    port: 5432
    name: headscale
    user: headscale
    pass: changeme
    max_open_conns: 10
    max_idle_conns: 10
    conn_max_idle_time_secs: 3600

dns:
  magic_dns: true
  base_domain: headscale.net
  nameservers:
    global:
      - 1.1.1.1
      - 1.0.0.1

unix_socket: /var/run/headscale/headscale.sock
unix_socket_permission: "0770"

log:
  format: text
  level: info

policy:
  mode: database
  path: /etc/headscale/policy.json

ephemeral_node_inactivity_timeout: 30m
node_update_check_interval: 10s
disable_check_updates: false
randomize_client_port: false

​
Health Check

Verify your configuration is valid: 
docker exec headscale headscale health

​
Restart After Changes

Configuration changes require a restart: 
docker compose restart headscale

Build docs developers (and LLMs) love

Get started for freeTalk to us