Beszel: self-hosted server monitoring with Docker Compose
Beszel monitors servers and Docker containers with history charts and alerts, using a small hub and agent. How to install it with Docker Compose and set up alerts.
Beszel is a lightweight server monitoring platform. A small web application, the hub, shows CPU, memory, disk, network, temperature and per-container statistics for every server you connect, keeps the history and sends alerts through the messengers you already use. Each monitored machine runs a small agent that reports to the hub.
It covers host and container metrics, alerts and network probes. It does not do application tracing, and it checks your machines from the inside: for “is my website answering from the outside” you want a tool like Uptime Kuma. The two work well together, see the heartbeat section below.
Beszel is still below version 1.0, so read the release notes before updates.
How it works
- Hub. A web application built on PocketBase. It stores the data, draws the dashboard, handles users and sends notifications.
- Agent. A small program on each monitored system. It collects metrics, and container statistics through the Docker socket.
The hub and an agent can talk in two ways, and the choice decides which ports you open:
- WebSocket. The agent connects out to the hub’s URL. The agent needs no open port, but the hub must be reachable from every agent at
/api/beszel/agent-connect. Use an HTTPS hub address when the agent is on another network. - SSH. The hub connects to the agent on port 45876. This suits a hub that can reach its agents but not the other way round, for example a hub on a private network. The hub uses its own key, and the agent’s SSH server accepts only that key and cannot run commands.
What you need
- A server with Docker and the Compose plugin for the hub
- A way for agents to reach the hub: the same host, a private network or a domain with HTTPS
- A domain and a reverse proxy if you want to open the hub from the internet
Install the hub and a local agent
This is the setup from the Beszel documentation for monitoring the same server the hub runs on. They talk over a Unix socket, because localhost does not work between two containers. Create a folder and a docker-compose.yml:
mkdir beszel
cd beszel
services:
beszel:
image: henrygd/beszel:latest
container_name: beszel
restart: unless-stopped
environment:
APP_URL: http://localhost:8090
ports:
- 8090:8090
volumes:
- ./beszel_data:/beszel_data
- ./beszel_socket:/beszel_socket
beszel-agent:
image: henrygd/beszel-agent:latest
container_name: beszel-agent
restart: unless-stopped
network_mode: host
volumes:
- ./beszel_agent_data:/var/lib/beszel-agent
- ./beszel_socket:/beszel_socket
- /var/run/docker.sock:/var/run/docker.sock:ro
environment:
LISTEN: /beszel_socket/beszel.sock
HUB_URL: http://localhost:8090
TOKEN: "<token>"
KEY: "<key>"
- Change
APP_URLto the address you will use to open the hub, a domain or an IP with the port. It is used in notification links and in the agent configuration the hub generates. - The agent runs in host network mode because it needs the host’s network interfaces for network statistics. This also exposes its port, which you can change with
LISTEN. Without host network mode you lose host network stats. - The Docker socket is mounted read-only. That is how the agent sees containers.
- The image tags above follow the project’s default. Docker Hub also has version tags such as
0.21if you prefer updates to stay inside one minor version.
Start the stack. The agent cannot connect yet, because KEY and TOKEN are placeholders:
docker compose up -d
Create the admin account
Open http://<host>:8090. Beszel asks you to create an account right away, so do it before you expose the address to anyone else. This account becomes an administrator.
Beszel keeps two kinds of accounts apart: the regular user you just created and a PocketBase superuser created for it at the same time. Changing the password of one does not change the other.
Connect the first system
- Click Add System in the top right corner.
- Enter a name. As Host / IP use the socket path:
/beszel_socket/beszel.sock
- The dialog shows a public key and a token. Put them into
KEYandTOKENindocker-compose.ymland apply the change:
docker compose up -d
- Click Add System in the dialog. The new system appears in the table. When it turns green, the agent is connected. If it turns red, the Beszel page “Common issues” starts with a connection checklist.
Monitor other servers
Install an agent on each additional server. The hub’s Add System dialog generates the whole docker-compose.yml with your key and token already filled in, so copy it from there. It looks like this:
services:
beszel-agent:
image: henrygd/beszel-agent
container_name: beszel-agent
restart: unless-stopped
network_mode: host
volumes:
- ./beszel_agent_data:/var/lib/beszel-agent
- /var/run/docker.sock:/var/run/docker.sock:ro
environment:
LISTEN: 45876
KEY: "<public key>"
HUB_URL: "https://beszel.example.com"
TOKEN: "<token>"
HUB_URL is the public address of the hub, which is what lets the agent connect over WebSocket. Run docker compose up -d, then finish adding the system in the dialog.
You can also create a universal token under /settings/tokens and use the same token on many agents. They connect without being set up in the hub one by one.
If a server has no Docker, install the agent as a binary. The dialog shows an install command for Linux that downloads the agent, creates a beszel user and a service and can turn on automatic daily updates. It needs root to set up the service, but the agent itself does not run as root. The Beszel documentation also covers Homebrew, WinGet, Scoop and a Home Assistant add-on for other platforms.
Put the hub behind HTTPS
Run a reverse proxy in front of the hub and set APP_URL to the public address. The proxy has to pass WebSocket connections, otherwise agents that connect over WebSocket cannot reach the hub. Beszel’s documentation gives this Caddy example:
beszel.example.com {
request_body {
max_size 10MB
}
reverse_proxy 127.0.0.1:8090 {
transport http {
read_timeout 360s
}
}
}
To use it, bind the hub port to the loopback interface: 127.0.0.1:8090:8090.
Turn off compression on the proxy for responses of type text/event-stream. The interface needs it for live stats, and with gzip applied real-time charts stop updating.
Agents verify HTTPS certificates. If your hub uses a self-signed certificate or a private CA, give the agent the CA file in CA_CERT_FILE, or the connection is rejected.
Alerts and notifications
Notifications use Shoutrrr URLs. Add one under Settings, then Notifications. Alerts are enabled per system in the systems table. The supported services include Telegram, Discord, Slack, Matrix, Mattermost, Gotify, ntfy, Pushover, Signal, MQTT and a generic webhook. A Telegram URL looks like this:
telegram://change-me@telegram?chats=123456789
Replace the token with the bot token and 123456789 with your chat ID. The format of every service is on its own page in the documentation.
Disks, GPUs and containers
Some metrics need extra permissions or mounts on the agent:
- More disks. Mount a folder from each filesystem into
/extra-filesystemsin the agent container. A name after two underscores becomes the display name:
volumes:
- /mnt/disk1/.beszel:/extra-filesystems/sdb1:ro
- /mnt/media/.beszel:/extra-filesystems/sdc1__Media:ro
- S.M.A.R.T. Switch the agent to the
:alpineimage and pass the drives, using the controller name (sda,nvme0), not the partition:
beszel-agent:
image: henrygd/beszel-agent:alpine
devices:
- /dev/sda:/dev/sda
- /dev/nvme0:/dev/nvme0
cap_add:
- SYS_RAWIO # required for S.M.A.R.T. data
- SYS_ADMIN # required for NVMe S.M.A.R.T. data
- GPUs. NVIDIA and Intel GPUs have their own agent images,
beszel-agent-nvidiaandbeszel-agent-intel. - Root disk. If the root disk is not detected correctly inside a container, set
FILESYSTEMto a device fromlsblkordf -h. - ZFS. Pools and datasets are monitored automatically.
- Network monitors. Under Network Monitors in the navbar the agent can probe a target (ICMP, TCP, HTTP or DNS) and report response time and packet loss from that server’s point of view. This needs agent 0.20.0 or newer.
Watch the hub itself
If the hub or the server it runs on goes down, nobody gets an alert. Beszel can send a periodic ping to an external endpoint, for example an Uptime Kuma push monitor, Healthchecks.io or BetterStack. Set these variables on the hub:
environment:
HEARTBEAT_URL: https://uptime.example.com/api/push/change-me
HEARTBEAT_METHOD: GET
HEARTBEAT_INTERVAL: 60
Push monitors expect a plain GET. With the default POST, which suits endpoints that read the body, Beszel also sends a JSON status that lists systems that are down and triggered alerts.
Users and sign-in
Roles are admin, user and read-only. Admins also see backups, SMTP settings and the YAML export, which contains the token of every system, so give the role only to people you trust. Users manage their own systems, and an admin can share systems with others. Read-only users can see systems shared with them and create alerts.
Beszel supports OAuth2 and OpenID Connect providers such as GitHub, Google, Authelia and Zitadel. The setup is done in the PocketBase admin panel and described in the documentation. To turn password login off after OAuth works, set DISABLE_PASSWORD_AUTH=true on the hub.
Backup
Use the backup feature in the hub under /#/settings/backups. It saves to disk or to S3-compatible storage and can restore from either. The other way is to stop the hub and copy the whole beszel_data folder.
Updating
Hub and agents are updated separately. For Docker, on the hub and on every agent server:
docker compose pull && docker compose up -d
For binary installs, the hub updates itself with ./beszel update, and the agent install script can turn on automatic daily updates.
Because the project is below 1.0, changes between versions can matter. Version 0.19.0, for example, started to verify HTTPS certificates in agents and broke connections to hubs with self-signed certificates until CA_CERT_FILE was set. Read the release notes, and back up first.
Beszel compared with other tools
These tools overlap but do different jobs. Facts are from each project’s own repository and documentation on 15 November 2026.
| License | What it is | Setup | |
|---|---|---|---|
| Beszel | MIT | Host and container metrics with history, alerts, S.M.A.R.T. and network probes | One hub and an agent per server |
| Uptime Kuma | MIT | Checks whether sites and services answer, with notifications and status pages | One container |
| Netdata | GPL-3.0 | Per-second metrics, zero configuration, machine-learning anomaly detection | An agent on every node |
| Prometheus and Grafana | Apache-2.0 and AGPL-3.0 | A time series database and a dashboard tool that you assemble | Several parts: Prometheus, node_exporter for machine metrics, cAdvisor for containers, Grafana for dashboards |
- Take Beszel when you have a handful of servers and want one dashboard with history and alerts running in minutes. The project describes itself as smaller and less resource-intensive than the leading solutions.
- Take Prometheus and Grafana when you need custom metrics, your own queries or monitoring of applications. It is far more flexible and takes real time to build and maintain.
- Take Netdata when per-second detail and automatic anomaly detection matter more than a small footprint.
- Add Uptime Kuma to any of them if you also need to know whether your services answer from outside.