config.example.yaml

# Configuration for the Headplane server and web application
server:
  # These are the default values, change them as needed
  host: "0.0.0.0"
  port: 3000

  # The base URL for Headplane. Please keep in mind that this will be required
  # for Headscale to properly function going forward AND it should not include
  # the dashboard prefix (/admin) portion.
  base_url: "http://localhost:3000"

  # The secret used to encode and decode web sessions (must be 32 characters)
  # You may also provide `cookie_secret_path` instead to read a value from disk.
  # See https://headplane.net/configuration/#sensitive-values
  cookie_secret: "<change_me_to_something_secure!>"

  # Whether cookies should be marked as Secure
  # * Should be false if running without HTTPs
  # * Should be true if running behind a reverse proxy with HTTPs
  # When `tls_cert_path`/`tls_key_path` are set below this is forced
  # to true automatically.
  cookie_secure: true

  # Optional TLS termination. When both `tls_cert_path` and
  # `tls_key_path` are set, Headplane serves HTTPS on `server.port`.
  # Both files must be PEM encoded.
  #
  # If you are terminating TLS at a reverse proxy (recommended for most
  # deployments) leave these unset.
  # tls_cert_path: "/var/lib/headplane/tls/fullchain.pem"
  # tls_key_path: "/var/lib/headplane/tls/privkey.pem"

  # The maximum age of the session cookie in seconds
  cookie_max_age: 86400 # 1 day in seconds

  # This is not required, but if you want to restrict the cookie
  # to a specific domain, set it here. Otherwise leave it commented out.
  # This may not work as expected if not using a reverse proxy.
  # cookie_domain: ""

  # Optional proxy authentication mode. When enabled, Headplane trusts identity
  # headers from requests that come directly from one of `allowed_cidrs` and
  # uses `headscale.api_key` for Headscale API access.
  #
  # Only enable this when a trusted reverse proxy in front of Headplane already
  # performs authentication (for example, nginx basic auth, Authelia, Authentik,
  # etc.). The source IP check uses the direct client address connected to
  # Headplane by default, not X-Forwarded-For headers.
  #
  # If `allowed_cidrs` is omitted, only localhost is trusted.
  # proxy_auth:
  #   enabled: false
  #
  #   # Optional. If set, Headplane checks allowed_cidrs against the first IP in
  #   # this header (for example, "X-Forwarded-For" or "X-Real-IP") instead of
  #   # the direct client address. The direct client must still match
  #   # trusted_proxy_cidrs before this header is used.
  #   ip_header: "X-Forwarded-For"
  #   trusted_proxy_cidrs:
  #     - "127.0.0.1/32"
  #     - "::1/128"
  #
  #   user_header: "Remote-User"
  #   email_header: "Remote-Email"
  #   name_header: "Remote-Name"
  #   picture_header: "Remote-Picture"
  #   allowed_cidrs:
  #     - "127.0.0.1/32"
  #     - "::1/128"

  # 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.
  # PLEASE ensure this directory is mounted if running in Docker.
  data_path: "/var/lib/headplane"

  # The info secret is optional and allows access to certain debug endpoints
  # that may expose sensitive information about your Headplane instance.
  #
  # As of now, this protects the /api/info endpoint which exposes details about
  # the Headplane and Headscale versions in use. In the future, more endpoints
  # may be protected by this secret.
  #
  # If not set, these endpoints will be disabled.
  # info_secret: "<change_me_to_something_secure!>"

# Headscale specific settings to allow Headplane to talk
# to Headscale and access deep integration features
headscale:
  # 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://`
  url: "http://headscale:5000"

  # If you use the TLS configuration in Headscale, and you are not using
  # Let's Encrypt for your certificate, pass in the path to the certificate.
  # (This has no effect if `url` does not start with `https://`)
  #
  # Note: this pins Headscale's connection to exactly this one cert. If you
  # have a private CA you want trusted everywhere (Headscale, OIDC, Docker,
  # etc.), set `NODE_EXTRA_CA_CERTS=/path/to/ca.pem` on the Headplane
  # process instead — see https://headplane.net/configuration/tls#custom-certificate-authorities
  # tls_cert_path: "/var/lib/headplane/tls.crt"

  # Optional, public URL if its different from the `headscale.url`
  # This affects certain parts of the web UI which shows Headscale's URL
  # public_url: "https://headscale.example.com"

  # 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.
  config_path: "/etc/headscale/config.yaml"

  # The API key used by Headplane for server-side operations.
  # This is required for OIDC authentication, proxy authentication, and the
  # Headplane agent.
  # Generate one with: headscale apikeys create
  # api_key: "<your-api-key>"

  # If you are using `dns.extra_records_path` in your Headscale
  # configuration, Headplane will read that path automatically. Set
  # this only when Headplane needs to access the same file at a
  # different path, such as in Docker bind mounts.
  #
  # Ensure that the file is both readable and writable to the Headplane process.
  # When using this, Headplane will no longer need to automatically
  # restart Headscale for DNS record changes.
  # dns_records_path: "/var/lib/headscale/extra_records.json"

# Integration configurations for Headplane to interact with Headscale
integration:
  # The Headplane agent periodically syncs node information (version, OS, etc.)
  # from your Tailnet. It auto-generates ephemeral pre-auth keys using the
  # OIDC headscale_api_key, so no manual key configuration is needed.
  agent:
    enabled: false

    # The name of the Headscale user to create pre-auth keys under.
    # A user with this name must exist in Headscale.
    # host_name: "headplane-agent"

    # How often to sync node information (in milliseconds).
    # Default: 180000 (3 minutes)
    # cache_ttl: 180000

    # 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.
    #
    # If using Docker, it is best to leave this as the default.
    # work_dir: "/var/lib/headplane/agent"

  # Only one of these should be enabled at a time or you will get errors
  # This does not include the agent integration (above), which can be enabled
  # at the same time as any of these and is recommended for the best experience.
  docker:
    enabled: false

    # By default we check for the presence of a container label (see the docs)
    # to determine the container to signal when changes are made to DNS settings.
    container_label: "me.tale.headplane.target=headscale"

    # HOWEVER, you can fallback to a container name if you desire, but this is
    # not recommended as its brittle and doesn't work with orchestrators that
    # automatically assign container names.
    #
    # If `container_name` is set, it will override any label checks.
    # container_name: "headscale"

    # The path to the Docker socket (do not change this if you are unsure)
    # Docker socket paths must start with unix:// or tcp:// and at the moment
    # https connections are not supported.
    socket: "unix:///var/run/docker.sock"

  # Please refer to docs/integration/Kubernetes.md for more information
  # on how to configure the Kubernetes integration. There are requirements in
  # order to allow Headscale to be controlled by Headplane in a cluster.
  kubernetes:
    enabled: false
    # Validates the manifest for the Pod to ensure all of the criteria
    # are set correctly. Turn this off if you are having issues with
    # shareProcessNamespace not being validated correctly.
    validate_manifest: true
    # This should be the name of the Pod running Headscale and Headplane.
    # If this isn't static you should be using the Kubernetes Downward API
    # to set this value (refer to docs/Integrated-Mode.md for more info).
    pod_name: "headscale"

  # Proc is the "Native" integration that only works when Headscale and
  # Headplane are running outside of a container. There is no configuration,
  # but you need to ensure that the Headplane process can terminate the
  # Headscale process.
  #
  # (If they are both running under systemd as sudo, this will work).
  proc:
    enabled: false

# OIDC Configuration for simpler authentication
# (This is optional, but recommended for the best experience)
# oidc:
#   # Set to false to define OIDC config without enabling it.
#   # Useful for Helm charts or generating docs from config files.
#   enabled: true
#
#   # The OIDC issuer URL
#   issuer: "https://accounts.google.com"
#
#   # DEPRECATED: Use headscale.api_key instead.
#   # If set, this will be used as a fallback for headscale.api_key.
#   headscale_api_key: "<your-headscale-api-key>"
#
#   # If your OIDC provider does not support discovery (does not have the URL at
#   # `/.well-known/openid-configuration`), you need to manually set endpoints.
#   # This also works to override endpoints if you so desire or if your OIDC
#   # discovery is missing certain endpoints (ie GitHub).
#   # For some typical providers, see https://headplane.net/features/sso.
#   authorization_endpoint: ""
#   token_endpoint: ""
#   userinfo_endpoint: ""
#
#   # RP-initiated logout (https://openid.net/specs/openid-connect-rpinitiated-1_0.html).
#   # When true, /logout redirects the user to the IdP's end_session_endpoint
#   # (auto-discovered or set manually below) so the upstream session is ended too.
#   #
#   # Disabled by default: the `post_logout_redirect_uri` MUST be pre-registered
#   # in your OIDC client configuration on the IdP. If it isn't, users will land
#   # on the provider's error page after logout.
#   use_end_session: false
#
#   # Optional. Override the auto-discovered end_session_endpoint, or supply one
#   # if your provider does not advertise it via discovery.
#   end_session_endpoint: ""
#
#   # Where the identity provider should redirect after RP-initiated logout.
#   # Most providers (Keycloak, Auth0, etc.) require this URL to be pre-registered
#   # in the OIDC client configuration. If unset, Headplane defaults to its own
#   # `<server.base_url>/admin/login?s=logout` page.
#   post_logout_redirect_uri: ""
#
#   # The authentication method to use when communicating with the token endpoint.
#   # This is fully optional and Headplane will attempt to auto-detect the best
#   # method and fall back to `client_secret_basic` if unsure.
#   token_endpoint_auth_method: "client_secret_post"
#
#   # The client ID for the OIDC client
#   # For the best experience please ensure this is *identical* to the client_id
#   # you are using for Headscale.
#   client_id: "your-client-id"
#
#   # The client secret for the OIDC client
#   # You may also provide `client_secret_path` instead to read a value from disk.
#   # See https://headplane.net/configuration/#sensitive-values
#   client_secret: "<your-client-secret>"
#
#   # Whether to use PKCE when authenticating users. This is recommended as it
#   # adds an extra layer of security to the authentication process. Enabling
#   # this means your OIDC provider must support PKCE and it must be enabled on
#   # the client.
#   use_pkce: true
#
#   # If you want to disable traditional login via Headscale API keys
#   disable_api_key_login: false
#
#   # By default profile pictures are pulled from the OIDC provider when
#   # we go to fetch the userinfo endpoint. Optionally, this can be set to
#   # "oidc" or "gravatar" as of 0.6.1.
#   profile_picture_source: "gravatar"
#
#   # The scopes to request when authenticating users. The default is below.
#   scope: "openid email profile"
#
#   # Optional fallback claims to use when your provider does not return a standard
#   # OIDC `sub` claim. Headplane always checks `sub` first, then each claim here
#   # in order. For Feishu/Lark, `["open_id", "email"]` is a reasonable fallback.
#   subject_claims:
#     - "open_id"
#     - "email"
#
#   # Role assigned to new OIDC users after the first owner is bootstrapped.
#   # This is useful with Headscale's OIDC allowed_domains / allowed_groups
#   # restrictions when every permitted SSO user should receive the same
#   # Headplane permissions. Valid values: admin, network_admin, it_admin,
#   # auditor, viewer, member. The owner role is only granted to the first user.
#   default_role: "member"
#
#   # Optional OIDC claim to read a Headplane role from when creating or syncing a user.
#   # This can be a string claim, or an array claim containing one of the valid
#   # roles above. If present and valid, it takes precedence over default_role.
#   # Configure your IdP to map groups or client roles into this claim. Existing
#   # non-owner users are updated on their next OIDC sign-in when this claim changes.
#   role_claim: "headplane_role"
#
#   # Allow ID token verification with legacy RSA keys smaller than 2048 bits.
#   # This is disabled by default because it lowers token verification security and
#   # should only be used as a temporary compatibility workaround.
#   allow_weak_rsa_keys: false
#
#   # Extra query parameters can be passed to the authorization endpoint
#   # by setting them here. This is useful for providers that require any kind
#   # of custom hinting.
#   extra_params:
#     prompt: "select_account" # Example: force account selection on Google