NixOS module options
All options must be under services.headplane.
For example: settings.headscale.config_path becomes services.headplane.settings.headscale.config_path.
debug
Description: Enable debug logging
Type: boolean
Default: false
enable
Description: Whether to enable headplane.
Type: boolean
Default: false
Example: true
package
Description: The headplane package to use.
Type: package
Default: pkgs.headplane
settings
Description: Headplane configuration options. Generates a YAML config file. See: https://github.com/tale/headplane/blob/main/config.example.yaml
Type: submodule
Default: { }
settings.headscale
Description: Headscale specific settings for Headplane integration.
Type: submodule
Default: { }
settings.headscale.api_key_path
Description: Path to a file containing the Headscale API key. Required for OIDC authentication and the Headplane agent.
Type: null or absolute path
Default: null
Example: "config.sops.secrets.headscale_api_key.path"
settings.headscale.config_path
Description: Path to the Headscale configuration file. This is optional, but HIGHLY recommended for the best experience. If this is read only, Headplane will show your configuration settings in the Web UI, but they cannot be changed.
Type: null or absolute path
Default: null
Example: "/etc/headscale/config.yaml"
settings.headscale.config_strict
Description: Headplane internally validates the Headscale configuration to ensure that it changes the configuration in a safe way. If you want to disable this validation, set this to false.
Type: boolean
Default: true
settings.headscale.dns_records_path
Description: If you are using dns.extra_records_path in your Headscale configuration, you need to set this to the path for Headplane to be able to read the DNS records. Ensure that the file is both readable and writable by the Headplane process. When using this, Headplane will no longer need to automatically restart Headscale for DNS record changes.
Type: null or absolute path
Default: null
Example: "/var/lib/headplane/extra_records.json"
settings.headscale.public_url
Description: Public URL if differrent. This affects certain parts of the web UI.
Type: null or string
Default: null
Example: "https://headscale.example.com"
settings.headscale.tls_cert_path
Description: Path to a file containing the TLS certificate.
Type: null or absolute path
Default: null
Example: "config.sops.secrets.tls_cert.path"
settings.headscale.url
Description: The URL to your Headscale instance. All API requests are routed through this URL. THIS IS NOT the gRPC endpoint, but the HTTP endpoint. IMPORTANT: If you are using TLS this MUST be set to https://.
Type: string
Default: "http://127.0.0.1:8080"
Example: "https://headscale.example.com"
settings.integration
Description: Integration configurations for Headplane to interact with Headscale.
Type: submodule
Default: { }
settings.integration.agent
Description: Agent configuration for the Headplane agent.
Type: submodule
Default: { }
settings.integration.agent.cache_ttl
Description: How long to cache agent information (in milliseconds). If you want data to update faster, reduce the TTL, but this will increase the frequency of requests to Headscale.
Type: signed integer
Default: 180000
settings.integration.agent.enabled
Description: The Headplane agent periodically syncs node information (version, OS, etc.) from your Tailnet. It auto-generates ephemeral pre-auth keys using headscale.api_key, so no manual key configuration is needed. Requires Headscale 0.28 or newer.
Type: boolean
Default: false
settings.integration.agent.executable_path
Description: Path to the Headplane agent binary. The default is correct if using the NixOS module package.
Type: absolute path
Default: "/usr/libexec/headplane/agent"
settings.integration.agent.host_name
Description: Optionally change the name of the agent in the Tailnet
Type: string
Default: "headplane-agent"
settings.integration.agent.package
Description: The headplane-agent package to use.
Type: package
Default: pkgs.headplane-agent
settings.integration.agent.work_dir
Description: Do not change this unless you are running a custom deployment. The work_dir represents where the agent will store its data to be able to automatically reauthenticate with your Tailnet. It needs to be writable by the user running the Headplane process.
Type: absolute path
Default: "/var/lib/headplane/agent"
settings.integration.proc
Description: Native process integration settings.
Type: submodule
Default: { }
settings.integration.proc.enabled
Description: Enable "Native" integration that works when Headscale and Headplane are running outside of a container. There is no additional configuration, but you need to ensure that the Headplane process can terminate the Headscale process.
Type: boolean
Default: true
settings.oidc
Description: OIDC Configuration for authentication.
Type: submodule
Default: { }
settings.oidc.client_id
Description: The client ID for the OIDC client.
Type: string
Default: ""
Example: "your-client-id"
settings.oidc.client_secret_path
Description: Path to a file containing the OIDC client secret.
Type: null or absolute path
Default: null
Example: "config.sops.secrets.oidc_client_secret.path"
settings.oidc.disable_api_key_login
Description: Whether to disable API key login.
Type: boolean
Default: false
settings.oidc.headscale_api_key_path
Description: DEPRECATED: Use headscale.api_key_path instead. Path to a file containing the Headscale API key.
Type: null or absolute path
Default: null
Example: "config.sops.secrets.headscale_api_key.path"
settings.oidc.issuer
Description: URL to OpenID issuer.
Type: string
Default: ""
Example: "https://provider.example.com/issuer-url"
settings.oidc.redirect_uri
Description: This should point to your publicly accessible URL for your Headplane instance with /admin/oidc/callback.
Type: string
Default: ""
Example: "https://headscale.example.com/admin/oidc/callback"
settings.oidc.token_endpoint_auth_method
Description: The token endpoint authentication method.
Type: one of "client_secret_post", "client_secret_basic", "client_secret_jwt"
Default: "client_secret_post"
settings.server
Description: Server configuration for Headplane web application.
Type: submodule
Default: { }
settings.server.cookie_secret_path
Description: Path to a file containing the cookie secret. The secret must be exactly 32 characters long.
Type: null or absolute path
Default: null
Example: "config.sops.secrets.headplane_cookie.path"
settings.server.cookie_secure
Description: Should the cookies only work over HTTPS? Set to false if running via HTTP without a proxy. Recommended to be true in production.
Type: boolean
Default: true
settings.server.data_path
Description: The path to persist Headplane specific data. All data going forward is stored in this directory, including the internal database and any cache related files. Data formats prior to 0.6.1 will automatically be migrated.
Type: absolute path
Default: "/var/lib/headplane"
Example: "/var/lib/headplane"
settings.server.host
Description: The host address to bind to.
Type: string
Default: "127.0.0.1"
Example: "0.0.0.0"
settings.server.port
Description: The port to listen on.
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default: 3000