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: Deprecated. Headplane no longer validates the complete Headscale configuration and this option has no effect.
Type: boolean
Default: true
settings.headscale.dns_records_path
Description: If you are using dns.extra_records_path in your Headscale configuration, Headplane reads that path automatically. Set this only when Headplane needs to access the same file at a different path. 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.tailscale_netns
Description: Use Tailscale's socket-level routing-loop handling in the dedicated Headplane agent process. Keep enabled unless its fallback pins the agent's Headscale connection to the wrong interface. Set to false only after verifying that ordinary OS routing in the container's network namespace reaches Headscale correctly.
Type: boolean
Default: true
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.default_role
Description: Role assigned to newly created OIDC users after the first owner is bootstrapped. The owner role is reserved for the first-login bootstrap.
Type: one of "admin", "network_admin", "it_admin", "auditor", "viewer", "member"
Default: "member"
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.role_claim
Description: Optional OIDC claim containing the Headplane role to assign to newly created users. A valid role claim takes precedence over default_role.
Type: null or string
Default: null
Example: "headplane_role"
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
settings.server.proxy_auth
Description: Proxy authentication configuration.
Type: submodule
Default: { }
settings.server.proxy_auth.allowed_cidrs
Description: Direct client CIDR ranges allowed to bypass Headplane's login flow. These should be the addresses your trusted reverse proxy uses to connect to Headplane. Requires headscale.api_key_path.
Type: list of string
Default: [ "127.0.0.1/32" "::1/128" ]
Example: [ "10.0.0.0/24" ]
settings.server.proxy_auth.email_header
Description: Optional header containing the authenticated user's email address.
Type: null or string
Default: null
settings.server.proxy_auth.enabled
Description: Whether to trust reverse proxy authentication for allowed client CIDRs.
Type: boolean
Default: false
settings.server.proxy_auth.ip_header
Description: Optional header containing the original client IP, such as X-Forwarded-For or X-Real-IP.
Type: null or string
Default: null
settings.server.proxy_auth.name_header
Description: Optional header containing the authenticated user's display name.
Type: null or string
Default: null
settings.server.proxy_auth.picture_header
Description: Optional header containing the authenticated user's profile picture URL.
Type: null or string
Default: null
settings.server.proxy_auth.user_header
Description: Header containing the stable authenticated proxy user identity.
Type: string
Default: "Remote-User"
settings.server.proxy_auth.trusted_proxy_cidrs
Description: Direct proxy CIDR ranges trusted to supply ip_header. Only used when ip_header is set.
Type: list of string
Default: [ "127.0.0.1/32" "::1/128" ]
Example: [ "127.0.0.1/32" ]