Aarnav Tale
b3c0c1c691
- Generate a fresh pre-auth key for every agent startup - Preserve existing tailscale state to avoid creating a new host - Auto-approve pending auth requests via /api/v1/auth/approve - Show approval link in settings UI as fallback Closes HP-558
4.2 KiB
title, description
| title | description |
|---|---|
| Headplane Agent | Configure the Headplane Agent for enhanced functionality. |
Headplane Agent
The Headplane Agent is an optional component that periodically syncs node information (such as version and OS details) from the Tailnet. Unlike previous versions, the agent does not require you to manually create or manage pre-auth keys — Headplane generates a fresh key for each agent startup and reuses the agent's existing Tailnet state across restarts.
Prerequisites
Before enabling the agent, ensure the following:
-
Headscale 0.28 or newer is required. The agent uses tag-only pre-auth keys which are only available in Headscale 0.28+.
-
headscale.api_keymust be set in your Headplane configuration file. The agent uses this key to auto-generate pre-auth keys for connecting to the Tailnet and to auto-approve its own registration when Headscale is configured to require manual approval.
Configuration
To enable the Headplane Agent, you'll need to modify the following fields in your Headplane configuration file. For more information on configuring Headplane please refer to the example configuration for details.
| Field | Description |
|---|---|
integration.agent.enabled |
Set to true to enable the agent. |
integration.agent.host_name |
Optional. Headscale user name for the agent (default: headplane-agent). |
integration.agent.cache_ttl |
Optional. How often to sync in milliseconds (default: 180000 / 3 minutes). |
integration.agent.work_dir |
Optional. Working directory for the agent's tailnet state. |
integration.agent.executable_path |
Optional. Path to the agent binary (default: /usr/libexec/headplane/agent). |
Native Mode Configuration
Once you've built Headplane locally, there will be a binary in the ./build
folder called hp_agent. Please move this binary to
/usr/libexec/headplane/agent and ensure that it is executable.
::: tip
If for some reason you cannot move the binary to the intended location, you can
define integration.agent.executable_path in your Headplane configuration
file to point to the correct location of the agent binary.
:::
The agent will also use /var/lib/headplane/agent as its data directory by
default. You can change this location by defining
integration.agent.work_dir in your Headplane configuration file. Ensure
that the specified directory exists and is writable by the user running
Headplane.
Headplane preserves the agent's tailscaled.state in this directory. This lets
the agent retain its Tailnet identity across Headplane restarts instead of
registering as a new host each time. If the agent's state is lost or unusable,
Headplane falls back to the pre-auth key and registers a new agent node.
Interactive approval
Under normal circumstances, the agent connects headlessly using the auto-generated
pre-auth key and no manual interaction is required. If your Headscale server is
configured to require interactive approval, Headplane detects the auth URL the
agent prints and automatically approves the request using the configured
headscale.api_key. The Settings page still shows the approval link as a
fallback in case auto-approval fails.
Usage
After enabling and configuring the Headplane Agent, restart your Headplane instance. You should now see additional options in the UI, such as host information about each node and the ability to open SSH sessions directly from the browser if the nodes have Tailscale SSH enabled.
