gsadmin/headplane
1
0
Fork 0
mirror of https://github.com/tale/headplane.git synced 2026-07-26 07:48:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore: document agent procedure

Browse Source
This commit is contained in:
Aarnav Tale
2025-10-16 22:16:11 -04:00
parent ac9ce72078
commit d175171efc
1 changed files with 55 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/agent.md
+55 -1
View File
@@ -10,4 +10,58 @@ description: Configure the Headplane Agent for enhanced functionality.
<figcaption>SSH access via the browser</figcaption>
</figure>
TODO
The Headplane Agent is an optional component that can be enabled on your
Headplane instance in order to unlock additional features such as remote
web-based SSH and detailed machine information.
## 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](https://github.com/tale/headplane/blob/main/config.example.yaml)
for details.
| Field | Description |
|---------------------|--------------------------------------------------------|
| **`integration.agent.enabled`** | Set to `true` to enable the agent. |
| **`integration.agent.pre_authkey`** | A reusable pre-auth-key (see below). |
| `integration.agent.host_name` | *Optional*. Host name to register as. |
| `integration.agent.cache_path` | *Optional*. Cache path for the agent. |
| `integration.agent.work_dir` | *Optional*. Working directory for the 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.
## Usage
<figure>
<img class="dark-only" src="../assets/preview-dark.png" />
<img class="light-only" src="../assets/preview-light.png" />
<figcaption>Headplane Dashboard</figcaption>
</figure>
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.
<figure>
<img class="dark-only" src="../assets/machine-dark.png" />
<img class="light-only" src="../assets/machine-light.png" />
<figcaption>Machine page</figcaption>
</figure>