Monitoring, checked 2026-10-17
Beszel: Docker configuration reference
Lightweight self-hosted server monitoring hub with a Go agent reporting CPU, memory, disk and container stats.
At a glance
- Image:
docker.io/henrygd/beszel - Tags:
latest,0.21.0,0.21,0.20.0,0.20 - Licence: MIT
- Source: https://github.com/henrygd/beszel
- Docs: https://beszel.dev/guide/what-is-beszel
Ports
| Port | What listens | Source |
|---|---|---|
8090 | HTTP listener for the hub web UI. Point the reverse proxy here. | source for port 8090 |
45876 (beszel-agent) | Default agent LISTEN port, used when the hub connects to the agent over SSH. Not needed when the agent connects out to the hub by WebSocket with HUB_URL and TOKEN. | source for port 45876 |
Environment variables
| Variable | Required | What it does | Example | Source |
|---|---|---|---|---|
APP_URL | No | Public URL of the hub, used in notification and agent-config links. Required if the hub is served at a sub-path. | https://beszel.example.com | source for APP_URL |
TOKEN | Yes | WebSocket registration token provided by the hub. The agent uses it with HUB_URL to connect to the hub. | generated from the hub's Add System dialog | source for TOKEN |
KEY | Yes | Public SSH key(s) the agent accepts for hub authentication. Provided by the hub when adding a system. | public key from the hub | source for KEY |
CA_CERT_FILE | No | Path to a PEM CA certificate. Since 0.19.0 agents verify the hub's HTTPS certificate, so a self-signed or private CA needs to be supplied here or the connection is rejected. | /certs/ca.pem | source for CA_CERT_FILE |
TRUSTED_AUTH_HEADER | No | Header name trusted for forwarded authentication, e.g. behind Cloudflare Access. Bypasses built-in login, so set it only if the gate is enforced; restrict it with TRUSTED_PROXY_IPS (0.20.0). | Cf-Access-Authenticated-User-Email | source for TRUSTED_AUTH_HEADER |
Volumes that must persist
| Path | What is in it | Source |
|---|---|---|
/beszel_data | Hub database: users, systems, alerts and history. | source for /beszel_data |
/var/lib/beszel-agent (beszel-agent) | Agent-side state. | source for /var/lib/beszel-agent |
Behind a reverse proxy
- The reverse proxy must forward WebSocket connections; agents using a universal token connect to the hub over a websocket rather than the unix socket path. source for this reverse-proxy note
- Set client_max_body_size (or the equivalent) to at least 10MB; the hub accepts request bodies up to that size and a stricter proxy default will reject them. source for this reverse-proxy note
- Set APP_URL to the externally visible URL, including any sub-path; it is baked into notification links and the agent connection config the hub generates. source for this reverse-proxy note
- Set the proxy read timeout to 360s, as in the documented Caddy and nginx examples, so long-running requests are not cut off early. source for this reverse-proxy note
What it needs alongside it
| Dependency | Why | Source |
|---|---|---|
| None; agent connects over a unix socket or the hub's websocket | The hub embeds its own SQLite-backed PocketBase database, and the local agent example connects over a shared unix socket volume rather than a network port. | source for None; agent connects over a unix socket or the hub's websocket |
Release timeline
| Version | Date | Breaking | What changed | Source |
|---|---|---|---|---|
v0.21.0 | 2026-10-02 | No | Adds pending package update lists, Wi-Fi signal monitoring, TLS certificate expiry checks for HTTPS monitors and a SYNC_SYSTEM_NAMES variable. | source for release v0.21.0 |
v0.20.0 | 2026-09-19 | No | Adds network monitoring from agents, btrfs pool reporting, container image update flags and a TRUSTED_PROXY_IPS allowlist for TRUSTED_AUTH_HEADER. | source for release v0.20.0 |
v0.19.0 | 2026-09-03 | Yes | Agents now verify the hub's HTTPS certificate; a self-signed or private CA needs CA_CERT_FILE set or the connection is rejected. | source for release v0.19.0 |
v0.18.8 | 2026-08-17 | No | Adds multi-battery monitoring, Linux fan RPM monitoring and Intel Arc GPU monitoring through nvtop. | source for release v0.18.8 |
v0.18.7 | 2026-04-05 | No | Adds more disk I/O metrics and the ability to copy alerts between systems. | source for release v0.18.7 |
v0.18.6 | 2026-03-29 | No | Fixes a partition-discovery regression on Docker and a chart display bug. | source for release v0.18.6 |
If it is not coming up
- WebSocket connection to 'wss://<your-domain>:6001/app/...' failed (UI shows "WARNING: Cannot connect to real-time service")
- ntfy: Push Notifications From Your Own Scripts
Read from the upstream documentation, repository and container registry by Keita Emsden on 2026-10-17. Every row links the page it came from. Upstream changes without telling anyone, so check the source link before you rely on a value.