Bare metal integration agent

[arthur-lbchn]

Description

Hi guys, do I need to grab /usr/libexec/headplane/agent from somewhere when using Headplane on bare-metal? This is what I get when trying to restart it with:

integration:
agent:
# The Headplane agent allows retrieving information about nodes
# This allows the UI to display version, OS, and connectivity data
# You will see the Headplane agent in your Tailnet as a node when
# it connects.
enabled: true

Oct 08 15:15:04 REDACTED node[356061]: 2025-10-08T14:15:04.682Z [server] INFO: Running Node.js 22.20.0
Oct 08 15:15:04 REDACTED node[356061]: (node:356061) ExperimentalWarning: SQLite is an experimental feature and might change at any time
Oct 08 15:15:04 REDACTED node[356061]: (Use `node --trace-warnings ...` to show where the warning was created)
Oct 08 15:15:04 REDACTED node[356061]: 2025-10-08T14:15:04.684Z [config] INFO: Found a valid configuration file at /etc/headplane/config.yaml
Oct 08 15:15:04 REDACTED node[356061]: 2025-10-08T14:15:04.704Z [config] INFO: Found a valid Headscale configuration file at /etc/headscale/config.yaml
Oct 08 15:15:04 REDACTED node[356061]: 2025-10-08T14:15:04.723Z [config] INFO: Using user database file at /var/lib/headplane/users.json
Oct 08 15:15:04 REDACTED node[356061]: 2025-10-08T14:15:04.725Z [agent] INFO: Using agent cache file at /var/lib/headplane/agent_cache.json
Oct 08 15:15:04 REDACTED node[356061]: 2025-10-08T14:15:04.726Z [agent] INFO: Starting agent process (attempt 0)
Oct 08 15:15:04 REDACTED node[356061]: 2025-10-08T14:15:04.734Z [agent] ERROR: Failed to start agent process
Oct 08 15:15:04 REDACTED node[356061]: node:events:497
Oct 08 15:15:04 REDACTED node[356061]:       throw er; // Unhandled 'error' event
Oct 08 15:15:04 REDACTED node[356061]:       ^
Oct 08 15:15:04 REDACTED node[356061]: Error: spawn /usr/libexec/headplane/agent ENOENT
Oct 08 15:15:04 REDACTED node[356061]:     at ChildProcess._handle.onexit (node:internal/child_process:285:19)
Oct 08 15:15:04 REDACTED node[356061]:     at onErrorNT (node:internal/child_process:483:16)
Oct 08 15:15:04 REDACTED node[356061]:     at process.processTicksAndRejections (node:internal/process/task_queues:90:21)
Oct 08 15:15:04 REDACTED node[356061]: Emitted 'error' event on ChildProcess instance at:
Oct 08 15:15:04 REDACTED node[356061]:     at ChildProcess._handle.onexit (node:internal/child_process:291:12)
Oct 08 15:15:04 REDACTED node[356061]:     at onErrorNT (node:internal/child_process:483:16)
Oct 08 15:15:04 REDACTED node[356061]:     at process.processTicksAndRejections (node:internal/process/task_queues:90:21) {
Oct 08 15:15:04 REDACTED node[356061]:   errno: -2,
Oct 08 15:15:04 REDACTED node[356061]:   code: 'ENOENT',
Oct 08 15:15:04 REDACTED node[356061]:   syscall: 'spawn /usr/libexec/headplane/agent',
Oct 08 15:15:04 REDACTED node[356061]:   path: '/usr/libexec/headplane/agent',
Oct 08 15:15:04 REDACTED node[356061]:   spawnargs: []
Oct 08 15:15:04 REDACTED node[356061]: }
Oct 08 15:15:04 REDACTED node[356061]: Node.js v22.20.0

I'm trying to get /proc integration working, but not luck so far. Any help is appreciated.

Headplane Version

v0.6.0

Headscale Version

v0.26.1

[tale]

This needs improved documentation, but you'll need to build the native module manually by running the go build script (see mise.toml it'll be called agent). Then the executable needs to be moved to the path in the error for it work correctly.

[arthur-lbchn]

@tale thank you, I've built hp_agent executable and put it to /usr/libexec/headplane/agent

Seems like that error is fixed, but its still not properly detect head scale process, showing me the following:

Oct 14 13:40:47 REDACTED node[381392]: 2025-10-14T12:40:47.628Z [config] ERROR: Found 2 Headscale processes: 362577, 381392
Oct 14 13:40:47 REDACTED node[381392]: 2025-10-14T12:40:47.629Z [config] ERROR: Integration Native Linux (/proc) is not available

Looks like the process "/usr/bin/node /opt/headplane/build/server/index.js" is being mistakenly identified:

root@REDACTED:~# ps xauf | grep 362577
headsca+  362577  0.2  0.3 1288484 56616 ?       Ssl  Oct10  12:12 /usr/bin/headscale serve
root@REDACTED~# ps xauf | grep 381392
root      381392  4.2  0.8 22217084 142876 ?     Ssl  13:40   0:01 /usr/bin/node /opt/headplane/build/server/index.js

Anything you're aware of?

[tale]

Was not aware, thank you for bringing it up.

[arthur-lbchn]

Hi @tale . Hope you're doing fine. Just wondering if you have a chance to review this one. Appreciate your help on this!

[tale]

Still not, going to take a look today.