Beszel: a lightweight hub-and-agent monitor for Docker hosts and Linux boxes

What Beszel is for, and who should run it

Beszel is a server monitoring platform made of two parts: a hub, which is a web application built on PocketBase, and an agent, which runs on each system you want to watch and sends metrics back to the hub. The README describes it as lightweight, with a web interface, simple configuration, and readiness out of the box.

The problem it addresses is the gap between a bare uptime check and a full metrics stack. A host running Docker produces container CPU, memory and network numbers that a ping monitor never sees, and collecting them usually means standing up Prometheus, an exporter per host, and Grafana on top. Beszel puts the collection, storage, dashboard and alerting into one hub process plus one small agent per machine.

It is aimed at people who run a few servers or a home lab and want history, container stats and alerts without maintaining a time-series pipeline. The multi-user feature, where users manage their own systems and admins can share systems across users, points at small teams and shared lab environments rather than single-operator setups. If you have hundreds of hosts or need to query metrics programmatically at scale, this is the wrong shape of tool.

Hub, agent and the data path between them

The architecture is deliberately two-piece. The agent runs on the monitored system and communicates system metrics to the hub. The hub is the PocketBase application that stores data and serves the dashboard. Nothing in the README suggests a central collector that reaches out and scrapes agents; the agent is the component that talks to the hub.

What the agent collects is broad for its size. Host CPU, memory (including swap and ZFS ARC), disk usage and disk I/O across multiple partitions, network usage, load average, temperature, fan speed on Linux via /sys/class/hwmon, GPU usage and power draw for Nvidia, AMD and Intel, battery charge, container status and metrics for Docker and Podman, and S.M.A.R.T. disk health including eMMC wear and Linux mdraid array health through sysfs.

The dependency list in go.mod supports the README's claims rather than contradicting them. gopsutil handles host metrics, cbor suggests a compact wire format between agent and hub, and shoutrrr is the notification library behind the alerting. PocketBase supplies storage, auth and the HTTP layer for the hub. That is a small dependency surface for what the feature list promises.

One consequence worth naming: because the hub is a PocketBase application, its data lives in PocketBase's storage rather than in a time-series database. The README does not describe a retention or downsampling policy, so how much history you can keep is a deployment question rather than a documented guarantee.

Installing Beszel and getting one host reporting

The README does not repeat install commands. It points to the quick start guide at https://beszel.dev/guide/getting-started, and says you will be up and running in a few minutes. Both components are published as Docker images, henrygd/beszel and henrygd/beszel-agent, which the README links from its badge URLs, so the container path is the one the project itself advertises. The README gives no run command, no port mapping, no volume path and no environment variables, so take those from the quick start guide rather than from this page.

If you build from source instead, the Makefile is the entry point. Its default goal is build, and it defines separate targets for the two components.

make build-agent
make build-hub

The Makefile also defines build-hub-dev and dev-server targets for development, and a test target that runs go test with the testing and no_ui build tags. The Go module requires go 1.27.1.

After the hub is running, open it in a browser and create the first admin user. The README states that OAuth and OIDC are supported and that password authentication can be disabled, so the initial account is the bootstrap step rather than the only way in.

Each machine you want to monitor then gets an agent. The agent needs to know where the hub is and needs a key that the hub generates for it; both are shown in the hub interface when you add a system, so copy them from there rather than guessing values. The Docker socket is what makes container stats possible, since the README lists container status and metrics for Docker and Podman. The README marks fan speed as Linux-only, so treat non-Linux agents as a reduced feature set until you confirm otherwise on beszel.dev. The search data shows people asking how to install the agent on Windows and on Proxmox; the guide is the place to check for those, because the README does not cover them.

Alerts, backups and the parts the README leaves open

Alerts are configurable for CPU, memory, disk, bandwidth, temperature, fan speed, load average and status. The go.mod dependency on shoutrrr is consistent with a notification layer that fans out to multiple services rather than a single webhook. The README does not list which notification targets are supported, so if your alerting goes somewhere unusual, verify it before you commit.

Automatic backups save to and restore from disk or S3-compatible storage. That is a real operational feature, not a checkbox: a monitoring hub that loses its history on a failed upgrade is worse than no history at all. What the README does not document is the restore procedure, the backup schedule, or how retention interacts with backup size. Those are the questions to answer from the guide before you rely on it.

The REST API line in the README is commented out, which suggests it is not part of the advertised feature set at this revision. If your plan involves reading Beszel data from your own scripts, treat that as unconfirmed rather than available.

The honest limitation is scope. Beszel is not a log aggregator, not a tracing system, and not a general-purpose time-series store. If you need to correlate a latency spike with a specific request trace, this tool will not do it. It is also not a synthetic uptime checker in the way a dedicated status page tool is: it monitors hosts you install an agent on, not arbitrary URLs.

How Beszel differs from Uptime Kuma and from Prometheus

The most common comparison in the search data is Beszel against Uptime Kuma. The difference is in what each one watches. Uptime Kuma is an uptime and status-page tool: you give it endpoints, it probes them from the outside, and it tells you whether they respond. Beszel watches the inside of a machine through an installed agent, and its container stats, disk I/O, S.M.A.R.T. health and per-container CPU history are things an external prober cannot see at all. If your question is whether a service answers, Uptime Kuma is the smaller answer. If your question is why a host is slow, Beszel has the data.

Against Prometheus and Grafana, the difference is architecture and operational cost. Prometheus pulls from exporters, stores in its own time-series database, and expects you to build dashboards and alert rules in Grafana and Alertmanager. That buys you retention control, query language, and an ecosystem of exporters. Beszel trades all of that for a single hub that already has a dashboard, alerts and backups wired together. The trade is real in both directions: you give up query flexibility and long-term retention guarantees, and you get a system you can stand up in an afternoon.

Maintenance, releases and licence

The repository is not archived, and the last push was on 2026-08-17, which is the same date as the v0.18.8 release. Before that, v0.18.7 landed on 2026-04-05 and v0.18.6 on 2026-03-29. The shape of that history matters more than the count: two releases a week apart in late March, then a four-month gap, then a release in August. That is a project that ships when there is something to ship rather than on a schedule, and you should plan upgrades around that rhythm instead of expecting a steady cadence.

Upgrade cost looks low on the surface. The hub and agent are distributed as Docker images, and the Go module requires go 1.27.1 if you build from source. The Makefile notes that NVML support for GPU metrics is controlled by a build tag: the NVML variable defaults to auto, and on linux/amd64 glibc hosts it adds the glibc tag, while setting NVML to true or false forces it on or off. That is a build-time decision, not a runtime flag, so a custom agent build has to get it right or GPU metrics will be missing.

Beszel is MIT licensed, which permits commercial use, modification and redistribution with the licence and copyright notice preserved. That is a permissive arrangement with few obligations, but it also means no warranty and no support commitment from the author. The README itself says the maintainer tries to respond to issues but may not always have time. Plan for community support, not a vendor.

Editorial conclusion

Adopt Beszel if you run a handful of Linux or Docker hosts and want a single dashboard with alerts and automatic backups without operating Prometheus and Grafana. Skip it if you need long-term metric retention, high-cardinality queries, or dashboards your own tooling builds on top of, because the README does not describe a supported public API surface for that. Before rolling it out, check the agent install path for your platform on beszel.dev, confirm how the hub stores its data and backups in your deployment, and verify that the metrics you care about (GPU, S.M.A.R.T., fan speed) are actually exposed on your hardware, since several of them are Linux-specific.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes