Monitoring, checked 2026-09-07
Beszel: Docker configuration reference
Lightweight self-hosted server monitoring hub with a Go agent reporting CPU, memory, disk and container stats.
At a glance
Ports
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 listener the hub connects to when using a universal token instead of a unix socket. Not needed on the same Docker network as the hub. | source for port 45876 |
Environment variables
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 | Universal token the agent uses to register itself with the hub. | generated from the hub's Add System dialog | source for TOKEN |
KEY | Yes | Public key the agent uses to verify the hub, paired with TOKEN during agent setup. | 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 to trust for forwarded authentication, for use behind an identity gate like Cloudflare Access. Bypasses built-in login when set, so only set it if the gate is actually enforced upstream. | Cf-Access-Authenticated-User-Email | source for TRUSTED_AUTH_HEADER |
Volumes that must persist
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
- Increase the proxy's read timeout to at least 360s, matching the hub's own transport timeout, or long-running requests get cut off early. source for this reverse-proxy note
What it needs alongside it
Release timeline
Releases| Version | Date | Breaking | What changed | Source |
|---|
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
Read from the upstream documentation, repository and container registry by Keita Emsden on 2026-09-07. Every row links the page it came from. Upstream changes without telling anyone, so check the source link before you rely on a value.
Other app references
All app references