Beszel Monitor

Connects to a Beszel Hub and exposes server metrics as ioBroker states

Current Release
0.17.1
Developer
krobi
License
MIT

This adapter mirrors a Beszel Hub into ioBroker. Beszel is a lightweight server monitor: small agents run on the machines you want to watch and report to a central Hub; the adapter reads that Hub over its REST API and writes one device per monitored system.

Everything is read-only. The adapter never writes to the Hub and creates no writable datapoints.

Before you start

You need a running Beszel Hub with at least one agent connected, and a login for that Hub. The adapter authenticates as a normal Beszel user — the same email and password you use for the Beszel web interface. An admin account is not required.

If you want container data, that user also needs read access to the Hub's containers collection. Without it every other metric still works; the adapter warns once and keeps the container datapoints it already created.

Setting it up

  1. Install and create an instance. In ioBroker, install beszel and open the instance settings.
  2. Enter the Hub URL under Beszel Hub URL — the same address you open the Beszel web interface with, for example http://192.168.1.100:8090. An IPv6 address goes in brackets: http://[fd00::1]:8090. Both http and https work; over http to a machine other than the ioBroker host, login and token travel the network unencrypted and the adapter says so once in the log.
  3. Enter username and password. The username is the email address of your Beszel login.
  4. Press Test Connection. It performs a real login against the Hub and reports the actual error if something is wrong — a wrong password, an unreachable host, a typo in the URL.
  5. Choose your metrics on the Metrics tab (see Datapoints and metric switches). The defaults cover uptime, CPU, load average, memory, disk, disk throughput, network and temperature. Everything else is off until you switch it on.
  6. Save. The instance starts, reads the Hub once, and creates the object tree.

Poll interval and timeout

Poll Interval accepts 10 to 300 seconds and defaults to 60. Beszel's agents record one measurement per minute, so a value below 60 seconds produces extra requests without newer data. A value entered outside that range — for example by a script writing the config directly — is clamped rather than accepted.

Request timeout (5 to 120 seconds, default 15) is how long a single request may take. Raise it for a slow link or a Hub with many containers.

What the adapter creates

beszel.0.
├── info.connection      is the Hub reachable
├── info.systemsTotal    systems registered on the Hub
├── info.systemsOnline   of those, how many report "up"
├── info.systemsAllUp    true while all of them do
└── systems.<name>.      one device per monitored system

The device name is the system name from the Hub, lower-cased with anything that is not a letter or digit replaced by _. Two systems whose names reduce to the same id get a short hash suffix so they cannot overwrite each other, and the adapter warns once when that happens.

How the adapter behaves when something is missing

  • A system goes down or is paused. Its info.online turns false and info.status shows what the Hub says. The measured values stay at their last reading rather than jumping to zero — the adapter reports what it knows, and it knows nothing new.
  • The Hub becomes unreachable. info.connection turns false, every system goes to info.online: false and info.status: unknown, and the fleet counters drop to zero. The same happens when you stop the instance, so nothing keeps claiming to be online while nobody reads.
  • The Hub answers with an empty list. Nothing is deleted. An outage must not wipe your object tree, so devices only disappear when the Hub genuinely reports a shorter list.
  • A sensor, fan, GPU, filesystem or container disappears. Its datapoints are removed. If a whole group empties at once, the adapter waits for a second consecutive poll before deleting — a single hiccup does not clear the tree.

Updating

An update reapplies names and descriptions to the datapoints you already have, so corrected wording and new translations reach existing installations, not just fresh ones. The consequence is that a datapoint you renamed yourself in the admin gets the adapter's name back on the next start.

Changelog

WORK IN PROGRESS

  • New: every system carries a pictogram of its operating system (Linux, macOS, Windows, FreeBSD) in the object tree — the icons the Beszel web UI uses, drawn to read in the light and the dark theme
  • Fixed: network upload/download were always empty against a Beszel Hub 0.19.0 or newer — the adapter now reads the bandwidth field the Hub actually stores (older Hubs keep working)
  • Fixed: disk read/write, network upload/download and swap used show 0 while idle instead of an empty value
  • Fixed: containers and systemd units of a system that is down or paused were deleted after a few minutes — they now keep their last values like every other datapoint
  • Fixed: the last SMART device, ZFS pool detail or systemd unit of a system was never removed once it disappeared on the Hub
  • Fixed: hardware and OS details are refreshed when a system reconnects — a new kernel shows after the reboot, not after the next adapter restart — and a system that was pending gets them on its first contact
  • Fixed: a Hub that is slow at adapter start no longer blanks the hardware/OS datapoints of all systems for one poll
  • Fixed: renaming a system on the Hub in a way that keeps its object id (e.g. only the case) now reaches the object tree
  • Fixed: a system added later with the same name as an existing one no longer takes over the existing system's object tree; the newcomer gets the suffix
  • Fixed: a container, dataset or unit whose name equals a group name (e.g. gpu, network, containers) kept being renamed while its system was down
  • Fixed: the adapter no longer writes states after being stopped when the shutdown lands while the detail collections are being read, and no longer tries to arm its timer during shutdown
  • Fixed: after the Hub briefly reported an empty system list, the offline markers written on errors and on shutdown reached no system
  • Fixed: a Hub without the ZFS, SMART or systemd collections (older release) or without read rights for them is asked once, not on every poll
  • Changed: temperature, battery, swap and ZFS ARC datapoints exist only on hosts that report that hardware; existing empty ones are removed
  • Changed: the four "Peak values" options are gone — a Hub never delivers peak values in the minute records the adapter reads, so they never produced a datapoint
  • Changed: the messages of the connection test follow the system language, and the test runs with the configured request timeout
  • Changed: SMART and dataset text columns the Hub does not carry read as empty (null) instead of an empty string

0.17.1 (2026-09-07)

  • Improved: sixteen datapoints now carry an explanation in the object tree — online state, OS name, load average, container and service CPU, ZFS scrub errors and drive power cycles
  • Fixed: the datapoint carrying the distribution name was labelled "OS Version" — it now reads "OS Name" in all eleven languages, matching what it actually shows

0.17.0 (2026-09-06)

  • New: SMART data per drive as an opt-in metric — the drive's own overall verdict plus temperature, capacity, power-on hours and power cycles
  • New: ZFS pool details as an opt-in metric — scrub status, per-vdev error counters and the datasets of each pool
  • New: systemd service details as an opt-in metric — state, sub-state, CPU and memory for every unit the agent reports
  • Improved: the two slow detail sources are read every 15 minutes instead of every poll, so switching them on costs your Hub almost nothing

0.16.0 (2026-09-06)

  • Fixed: switching a metric group off now really empties it — a system that was offline at the time kept the empty channel and got it back after every restart
  • Fixed: a stumble while starting no longer leaves the adapter alive but silent — it keeps going and updates your values as usual
  • Changed: the status words of a system, of a ZFS pool and of a container are shown in your ioBroker language instead of English
  • Changed: a container's health is now a proper status datapoint with its list of possible values, like the system status next to it
  • Improved: starting up puts far less load on the ioBroker database, which shows most with many systems or many metrics switched off
  • Changed: user documentation now covers the ZFS pools, the root disk name and the read/write totals

0.15.0 (2026-09-05)

  • New: ZFS pools with usage, throughput and health as an opt-in metric, the root disk's custom name and cumulative read/write totals for disks and filesystems on Beszel 0.19.0.

0.14.2 (2026-09-05)

  • Changed: Internal cleanup. No user-facing changes.

License

MIT License

Copyright (c) 2026 krobi krobi@power-dreams.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Developed with assistance from Claude.ai