Add Beszel Agent

[not-first]

Description

I added a package for the beszel agent, a monitoring tool used to connect to an externally running beszel hub. This package ONLY contains the agent.

It was created due to there being no easy way to install the agent on your NAS.

If SMART monitoring is wanted the user must also install the SynoCli Disk Tools package and run the command: sudo setcap 'cap_sys_rawio+ep' $(readlink -f /usr/local/bin/smartctl) as root on their NAS.
I am slightly unsure where to put this. I plan to contribute it to the beszel documentation, which container similar instruction for setting up correct permissions for other systems.
I have added a simple notice to refer to beszel documentation in the package description.

Checklist

• Build rule all-supported completed successfully
• New installation of package completed successfully
• Package upgrade completed successfully (Manually install the package again)
• Package functionality was tested
• Any needed documentation is updated/created

Type of change

• Bug fix
• New Package
• Package update
• Includes small framework changes
• This change requires a documentation update (e.g. Wiki)

[hgy59]

we already have #6566

To update #6566 clone the owners repo and work on the related branch.
But this might only work as a maintainer of spksrc repo.

[not-first]

Ahh sorry ,after writing that I don't have write access to the owner's repo's branch in discord, th0ma7 responded saying to make a new PR.

I don't think I can update the owner's branch, I have tried adding their repo as a remote to my local repo, and merging my branch into theirs (the one the PR was created from). After resolving the merge conflicts I got permission errors when trying to push the changes of the related branch to the owner's repo.

I think only people with write access to SynoCommunity/spksrc can make changes to a PR.

[not-first]

Also, the old PR contains the beszel hub as well. I only have created a beszel agent package, and have not looked into the hub in any way.

If I merge with that PR am I obliged to also update the hub package too?

[not-first]

Hello @hgy59, I would really appreciate just a bit of guidance on how to continue with this package being merged.

I have been asked to edit the existing PR. I cannot.

What am I expected to do now? Perhaps I can merge the old PR into this new one?

[mreid-tt]

Hi @not-first,

I've been reviewing both this PR and #6566, and I think there's a clean path forward that addresses the coordination concerns.

Proposal: This PR focuses solely on beszel-agent, while #6566 is reworked to only include beszel-hub. Since the Hub and Agent are architecturally independent (they communicate via SSH, with no code dependencies), this separation makes sense:

• beszel-agent - For users who want to monitor their Synology NAS from an existing Beszel Hub running elsewhere
• beszel-hub - For users who want to run the Beszel dashboard on their Synology NAS

This way, each PR author maintains their own package, and users can install one or both depending on their needs.

Suggested improvements for this PR:

1. Add architecture restriction - The agent uses Go with native compilation, so PPC architectures should be excluded:

   UNSUPPORTED_ARCHS = $(PPC_ARCHS)

2. Update to latest version - Beszel 0.18.4 was released recently with several improvements including GPU monitoring enhancements and bug fixes.

3. Minor service-setup improvement - The LOG_LEVEL=debug export might be better as a configurable option or removed for production use.

The wizard implementation with SSH key validation, extra filesystems, and SMART device configuration looks good.

Let me know if you'd like any help with these changes.

[not-first]

Thank you for the quick review @mreid-tt.

That proposal seems appropriate given the circumstances.

I will make the following changes:

• Exclude PPC architectures
• Remove the LOG_LEVEL-DEBUG, it must have been left in there for testing purposes

I attempted an update to the latest beszel version 1.18.4 already, and built successfully for my Synology NAS arch-armada370-7.1. However, the package could not run and crashed with errors on startup.

[not-first]

oops, I must have accidentally closed the PR with my last comment! Reopened it just now.

I would appreciate some help with debugging this crash on the newer package version! AI seems to think it is a go runtime issue (as the newer beszel just updated to 1.26.0):
The binary itself segfaults (--version crashes), which points to the Go runtime used for compile
The crash is in Go runtime before main, so it’s a binary/runtime compatibility issue, not a package script issue.
Your crash is a Go runtime crash before app startup, and Beszel 0.18.4 requires Go 1.26 APIs. On armada370/ARMv7, that currently looks unstable in this build path.

However, I am naturally sceptical of accepting this as fully true without assistance from somebody more experienced in these issues.

I am happy to provide any logs and information required, I am simply unsure of exactly what best helps debug in this scenario - package development is very new to me. I am happy to do this here or on discord.

Regardless, the 1.18.3 release is working wonderfully. Beszel supports backwards compatibility with their agents meaning even if people are running the last hub version they will still be able to connect their NAS running the previous agent version.

[not-first]

Just made the required changes. Awkwardly, every commit I push to my branch seems to close the PR...
Nothing has been changed about my development environment. That's a separate thing for me to figure out!

[not-first]

All requested changes have been applied. 👍

[mreid-tt]

So I did a basic install and upgrade. I am not able to test with a Beszel Hub since I don't have one. I did however note these concerning warnings and errors in the service log:

Sun Mar  1 13:57:51 AST 2026
Starting beszel-agent command /volume1/@appstore/beszel-agent/bin/beszel-agent
2026/03/01 13:57:51 WARN Data directory not found
2026/03/01 13:57:51 INFO Detected root device name=sda1
2026/03/01 13:57:51 INFO Detected network interface name=eth0 sent=77523142 recv=807764467
2026/03/01 13:57:51 ERROR Error listing systemd service units err="Rejected send message, 2 matched rules; type=\"method_call\", sender=\":1.36\" (uid=224346 pid=641 comm=\"/volume1/@appstore/beszel-agent/bin/beszel-agent \") interface=\"org.freedesktop.systemd1.Manager\" member=\"ListUnitsByPatterns\" error name=\"(unset)\" requested_reply=\"0\" destination=\"org.freedesktop.systemd1\" (uid=0 pid=1 comm=\"/sbin/init \")"
2026/03/01 13:57:51 WARN Error creating WebSocket client err="HUB_URL environment variable not set"
2026/03/01 13:57:51 INFO Starting SSH server addr=:45876 network=tcp

Can you share a bit more about how this agent software should work? Is there a data directory that should be configured? Do we need to capture a "HUB_URL environment variable" as part of the setup? How have you performed functional testing of the agent on your setup?

[not-first]

The methods of agent communication with the hub can be read here. Essentially there are 2: SSH and Websocket. Websocket is tried first, then falls back to SSH. This package only supports SSH.

Regarding those errors:

• I have not observed the systemd service error. However, the docs mention this env var SKIP_SYSTEMD which disables systemd monitoring for the agent. I'll add that in now.

• HUB_URL: Used for outgoing WebSocket connection (not required for SSH connection). Since a SSH key is the main method of connection, this isn't required and doesn't add/restrict any functionality.

• The data directory warning can similarly be ignored with an SSH connection, as it is used to store the Websocket fingerprint. Here is a statement from the docs:
  Attempts to find a suitable directory if unset. Currently only used to store the system fingerprint, but may be used in the future for a SQLite database. The fingerprint is deterministic, so in most cases you can ignore warnings if no directory is found.

Enabling websocket connection support would require

• adding a data directory (optional, but probably advised to allow for smoother future transition to perhaps an SQLite storage?)
• adding a HUB_URL entry
• adding a TOKEN entry

I did not plan to support this in the initial version of the package, as I am not experienced with package development and don't feel confident in maintaining a storage folder between updates with correct permissions and future SQLite database operation.

So in summary:
Can you share a bit more about how this agent software should work?
Client is created in beszel hub dashboard, KEY can be copied over into the agent. The IP address of the agent is entered in the hub, and the hub initiates all connection.

Is there a data directory that should be configured?
No, not for SSH connection.

Do we need to capture a "HUB_URL environment variable" as part of the setup?
No, not for SSH connection.

How have you performed functional testing of the agent on your setup?
I have not performed true 'testing' but I have been running the agent on my NAS ever since the package was first developed in early January and have had no issues. I have seen resource usage, storage statistics and SMART disk monitoring results.
I have also been 'upgrading' my package as the beszel updates release, by uploading the new package file to my NAS via the package centre UI and have had no issues.
I am not exactly sure on how to distribute for testing on other setups, but I have access to others who are excited for a beszel agent package, who could test and report back if needed.

[mreid-tt]

• I have not observed the systemd service error. However, the docs mention this env var SKIP_SYSTEMD which disables systemd monitoring for the agent. I'll add that in now.

I would suggest you revert 29a6827 given you have not observed these errors in your service log. Also, according to the https://beszel.dev/guide/environment-variables, this SKIP_SYSTEMD would "Disable Systemd service monitoring."

Unless we have a good reason for doing that it should probably remain enabled. Also, the correct syntax if you did want to disable it would be:

export SKIP_SYSTEMD=true

I am not exactly sure on how to distribute for testing on other setups, but I have access to others who are excited for a beszel agent package, who could test and report back if needed.

You can direct persons to this PR and provide guidance similar to our wiki, that they need to download the package from the checks/builds, decompress and manually install.

[melo0187]

You can direct persons to this PR and provide guidance similar to our wiki, that they need to download the package from the checks/builds, decompress and manually install.

So here I am, excited about this agent ^^

I downloaded the evansport-7.1 build from the GH action workflow run and installed it manually.
On the beszel hub I chose to add system with binary agent, which gives me the required public key.
On my ds214play I provided this key when prompted for during manual install of the beszel-agent package.
I also added /volume1 (my only volume) as additional volume to check and /dev/sda:sat and /dev/sdb:sat as the ds214play is a two bay NAS. Installation proceeds to tell me firewall needs to allow access to the agent's port, which I confirmed.

Not sure what to expect, so its hard for me to report bugs. Here is an overview of what I gathered instead.

On the NAS:

On the Beszel Hub:
System index

• reported CPU load seems legitimate
• reported Memory util seems wrong (84,4 vs 59% reported by NAS)
• disk usage checks out for both root and lv
• load average matches what top reports

System details

• memory is reported at 699.3 MB while DSM reports a total of 1 GB
  • however top reports GiB Mem : 0.683 total 😕
• usage and throughput is there for both root and lv
• no S.M.A.R.T information for drives

Hope this helps.
Let me know if you need more.

Thanks for your efforts =)

[melo0187]

addendum about my missing S.M.A.R.T info:
I read more carefully through the description that says

If SMART monitoring is wanted the user must also install the SynoCli Disk Tools package and run the command: sudo setcap 'cap_sys_rawio+ep' $(readlink -f /usr/local/bin/smartctl) as root on their NAS.

So I installed SynoCli Disk Tools and ran the setcap command. I also restarted the beszel-agent, but only effect was the error messages disappearing from the log:

Starting beszel-agent command /volume1/@appstore/beszel-agent/bin/beszel-agent
2026/03/03 10:32:39 WARN Data directory not found
2026/03/03 10:32:39 INFO Detected root device name=md0
2026/03/03 10:32:39 WARN Device not found in diskstats name=lv
2026/03/03 10:32:39 INFO Detected network interface name=eth0 sent=174481153 recv=88091402
2026/03/03 10:32:39 ERROR Error listing systemd service units err="Rejected send message, 2 matched rules; type=\"method_call\", sender=\":1.47\" (uid=224346 pid=28149 comm=\"/volume1/@appstore/beszel-agent/bin/beszel-agent \") interface=\"org.freedesktop.systemd1.Manager\" member=\"ListUnitsByPatterns\" error name=\"(unset)\" requested_reply=\"0\" destination=\"org.freedesktop.systemd1\" (uid=0 pid=1 comm=\"/sbin/init \")"
2026/03/03 10:32:39 WARN Error creating WebSocket client err="HUB_URL environment variable not set"
2026/03/03 10:32:39 INFO Starting SSH server addr=:45876 network=tcp
2026/03/03 10:33:13 INFO SSH connected addr=192.168.178.60:37708
2026/03/03 10:33:13 INFO SSH connection established

But the devices still don't show up in the beszel-hub.

Also, lv throughput stays a flat 0. Likely related to WARN Device not found in diskstats name=lv.
I believe this is an issue with beszel-agent binary config options and opened an issue there: henrygd/beszel#1790