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_URL to 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.21 if 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

  1. Click Add System in the top right corner.
  2. Enter a name. As Host / IP use the socket path:
/beszel_socket/beszel.sock
  1. The dialog shows a public key and a token. Put them into KEY and TOKEN in docker-compose.yml and apply the change:
docker compose up -d
  1. 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-filesystems in 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 :alpine image 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-nvidia and beszel-agent-intel.
  • Root disk. If the root disk is not detected correctly inside a container, set FILESYSTEM to a device from lsblk or df -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.