Connects to a Beszel Hub and exposes server monitoring metrics for all registered systems as ioBroker states.
- Fetches metrics from all systems registered in your Beszel Hub
- Per-system states: CPU, memory, disk, network, temperature, load average
- Optional: GPU metrics, Docker/Podman containers, battery, extra filesystems, CPU breakdown, systemd services
- Configurable poll interval (10–300 seconds)
- Automatic re-authentication when the token expires
- Connection test button in the admin UI
- Automatic cleanup of states for removed systems and disabled metrics
- Node.js >= 22
- ioBroker js-controller >= 7.0.7
- ioBroker Admin >= 7.8.23
- A running Beszel Hub with at least one registered system
| Option | Description | Default |
|---|---|---|
| Beszel Hub URL | Full URL of your Beszel Hub (e.g. http://192.168.1.100:8090) |
— |
| Username | Beszel Hub login email/username | — |
| Password | Beszel Hub password | — |
| Poll Interval (s) | How often to fetch data from the Hub | 60 |
Use the Test Connection button to verify your credentials before saving.
All metrics are global toggles that apply to all systems. Disabled metrics are automatically removed from the state tree on the next adapter start.
| Group | Metric | Default |
|---|---|---|
| System | Uptime | on |
| Agent Version | off | |
| Systemd Services (total / failed) | off | |
| CPU | CPU Usage (%) | on |
| Load Average (1m / 5m / 15m) | on | |
| CPU Breakdown (User / System / IOWait / Steal / Idle) | off | |
| Memory | Memory Usage (% and GB) | on |
| Memory Details (Buffers, ZFS ARC) | off | |
| Swap | off | |
| Disk | Disk Usage (% and GB) | on |
| Disk Read/Write Speed | on | |
| Additional Filesystems | off | |
| Network | Network Traffic (Upload / Download MB/s) | on |
| Temperature | Temperature (hottest sensors avg) | on |
| Individual Temperature Sensors | off | |
| GPU | GPU Metrics (Usage, Memory, Power) | off |
| Containers | Container Monitoring (Docker / Podman) | off |
| Battery | Battery Status | off |
States are organized into channels per metric group. Optional channels (marked *) are only created when the corresponding metric is enabled.
beszel.0.
├── info.connection — Connection status (bool)
└── systems.
└── {system_name}/ — Device (sanitized name)
├── info/ — System info
│ ├── online — Is system up? (bool, used as device indicator)
│ ├── status — Status string (up/down/paused/pending)
│ ├── uptime — Uptime in seconds
│ ├── uptime_text — Human-readable uptime (e.g. "14d 6h")
│ ├── agent_version * — Beszel agent version
│ ├── services_total * — Systemd services total
│ └── services_failed * — Systemd services failed
├── cpu/ — CPU metrics
│ ├── usage — CPU usage (%)
│ ├── load_1m — Load average 1 min
│ ├── load_5m — Load average 5 min
│ ├── load_15m — Load average 15 min
│ ├── user * — CPU user (%)
│ ├── system * — CPU system (%)
│ ├── iowait * — CPU I/O wait (%)
│ ├── steal * — CPU steal (%)
│ └── idle * — CPU idle (%)
├── memory/ — Memory metrics
│ ├── percent — RAM usage (%)
│ ├── used — RAM used (GB)
│ ├── total — RAM total (GB)
│ ├── buffers * — Buffers + cache (GB)
│ ├── zfs_arc * — ZFS ARC (GB)
│ ├── swap_used * — Swap used (GB)
│ └── swap_total * — Swap total (GB)
├── disk/ — Disk metrics
│ ├── percent — Disk usage (%)
│ ├── used — Disk used (GB)
│ ├── total — Disk total (GB)
│ ├── read — Disk read (MB/s)
│ └── write — Disk write (MB/s)
├── network/ — Network metrics
│ ├── sent — Upload (MB/s)
│ └── recv — Download (MB/s)
├── temperature/ — Temperature metrics
│ ├── average — Avg of top 3 sensors (°C)
│ └── sensors/ * — Individual sensor readings
├── battery/ * — Battery metrics
│ ├── percent — Battery level (%)
│ └── charging — Is charging? (bool)
├── gpu/ * — GPU metrics (per GPU)
│ └── {gpu_name}/
│ ├── usage — GPU usage (%)
│ ├── memory_used — VRAM used (GB)
│ ├── memory_total — VRAM total (GB)
│ └── power — Power draw (W)
├── filesystems/ * — Extra filesystems (per mount)
│ └── {fs_name}/
│ ├── disk_percent — Usage (%)
│ ├── disk_used — Used (GB)
│ ├── disk_total — Total (GB)
│ ├── read_speed — Read (MB/s)
│ └── write_speed — Write (MB/s)
└── containers/ * — Docker/Podman containers
└── {container_name}/
├── status — Container status
├── health — Health (none/starting/healthy/unhealthy)
├── cpu — CPU usage (%)
├── memory — Memory (MB)
└── image — Image name
Breaking change in 0.3.0: States moved from flat paths (e.g.
cpu_usage) to channels (e.g.cpu.usage). Legacy states are automatically cleaned up on first start.
- Verify the Hub URL is reachable from the ioBroker host
- Check username and password (use the Test Connection button)
- Check that no firewall blocks access to the Beszel Hub port
- Check the ioBroker log for errors from the
beszeladapter - Ensure the poll interval is not too short (minimum 10 seconds)
- Check
info.connectionstate — iffalse, authentication failed
- The system may be
downorpausedin Beszel — no stats records exist yet - Verify the metric is enabled in the adapter configuration
- Adapter shuts down cleanly even if the "Test Connection" button was still running — the test request is now aborted at unload along with regular polling.
- Debug log traces previously silent paths: HTTP request lifecycle, token authentication, pagination walks and the 429-retry. Default log unchanged.
- Test Connection in admin no longer hangs on an unknown command — it now gets a clear error response instead.
- Big setups (200+ servers / 500+ containers) now load completely instead of being silently truncated, and they start up noticeably faster — system updates, cleanups and the startup migration run in parallel.
- New "Request timeout" setting in admin (5–120 s, default 15 s) for slow links or very large payloads.
- Hub rate-limit (429): one transparent retry that honours
Retry-After; permanent rate-limits surface as a clear log so you can raise the poll interval. - "Forbidden" (403) responses now show a permission hint instead of looping reauth.
- Two servers whose names sanitize to the same id no longer overwrite each other — the second gets a hash suffix and a warn so you can rename on the Hub.
- Adapter shuts down cleanly even if the Hub is slow — pending requests are aborted.
- Adapter log messages are now English only, in line with the ioBroker community standard. Localized state names (11 languages) are unchanged.
- Restored the blank line between the changelog footer and the Support section (release-script swallowed it in v0.4.0).
Older entries are in CHANGELOG_OLD.md.
This adapter is free and open source. If you find it useful, consider buying me a coffee:
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
