Skip to content
Get packs

Guide · Open source

How to use Beszel: install the hub and agents, monitor Docker

Updated · written with AI from the project's own documentation and checked against our catalogue data

Beszel is a self-hosted server monitoring tool. A hub runs a web dashboard, and small agents installed on each machine you want to watch send it metrics. This guide explains the two parts, what Beszel can track, and where to find the full install instructions. After reading it, you will know how the pieces fit together and what to do first.

Beszelhenrygd/beszel · ★ 26.8k · MIT

Quick start

  1. 1Check the prerequisites. Install Docker, which the project's Docker-based install requires.
  2. 2Clone the repository. Run the git clone command to get the project files from GitHub.
  3. 3Follow the quick start guide. Open beszel.dev and follow the getting-started guide to run the hub.
  4. 4Install an agent on each machine. Run the agent on every system you want to monitor so it reports to the hub.
  5. 5Open the dashboard. Sign in to the web interface and check that each connected system appears.
  6. 6Configure alerts. Set limits for the metrics you care about and pick a notification service.
  7. 7Set up backups. Choose disk or S3-compatible storage for automatic backups.

What Beszel is made of: the hub and the agent

Beszel has two main components. The hub is a web application built on PocketBase that provides a dashboard for viewing and managing connected systems. The agent runs on each system you want to monitor and sends system metrics to the hub.

You install one hub and then one agent per machine. The hub is where you look at everything; the agents do the collecting.

  • Hub: web dashboard for viewing and managing connected systems
  • Agent: runs on each monitored system and reports metrics to the hub

Install Beszel with Docker

The project's docs show a Docker-based install, so Docker is the prerequisite for the method covered here. The README's only install command is cloning the repository, shown below. The step-by-step setup lives in the quick start guide on beszel.dev, which the README points to and says takes a few minutes.

Follow the quick start guide for the exact Docker commands and settings for the hub and agents, since this page does not reproduce them.

  • Prerequisite: Docker
  • Clone the source repository to browse the project files
  • Use the quick start guide at beszel.dev for the hub and agent setup
git clone https://github.com/henrygd/beszel

Add systems and see their metrics on the dashboard

Once the hub and at least one agent are running, the dashboard shows metrics from every connected system. Each system has its own page with detailed metrics. The README's screenshots show a dashboard view with several systems and a single-system page side by side.

Beszel covers host metrics and container metrics. You can see CPU, memory (including swap and ZFS ARC), disk usage and I/O, network, load average, temperature, fan speed, GPU usage, battery charge, and S.M.A.R.T. disk health. It also reports ZFS pool status and the status of running Docker or Podman containers.

  • CPU, memory, disk usage and I/O, network, load average on the host
  • Temperature and fan speed from host sensors (fan speed on Linux)
  • GPU usage and power draw for Nvidia, AMD and Intel
  • Status and metrics of all running Docker or Podman containers
  • S.M.A.R.T. disk health and ZFS pool health, I/O and scrub status

Watch Docker containers alongside the host

Beszel tracks CPU, memory, and network usage history for each container. This lets you see whether a container is responsible for a load spike on a machine, without leaving the same dashboard you use for the host.

Container tracking works with Docker and Podman, according to the supported metrics list.

  • Per-container CPU, memory and network history
  • Works with Docker and Podman containers

Set up alerts and notifications

Beszel can alert you when metrics cross limits you set. The README says alerts are configurable for most metrics and that many notification services are supported. Drive failure is also covered: S.M.A.R.T. data can trigger notifications when a disk fails.

Network monitoring can check response time and interruptions directly from agents, which helps catch a service that stops answering.

  • Configure thresholds for most metrics
  • Send notifications to many supported services
  • S.M.A.R.T. notifications on drive failure
  • Network response time and interruption checks from agents

Manage users, backups and sign-in

Beszel supports multiple users. Each user manages their own systems, and admins can share systems across users. It supports OAuth2 and OIDC providers, and password login can be disabled.

Automatic backups can be saved to disk or to S3-compatible storage, and restored from either. Check the documentation for how to configure these.

  • Multi-user: users manage their own systems, admins can share them
  • OAuth / OIDC sign-in, with password auth optionally disabled
  • Automatic backups to disk or S3-compatible storage

What people use it for

  • Watching CPU, memory and disk on a few home servers from one dashboard
  • Tracking how much CPU and memory each Docker or Podman container uses over time
  • Getting a notification when a disk's S.M.A.R.T. data shows a failure
  • Checking whether a service responds and whether it has been interrupted
  • Sharing selected systems with other users on a small team

Frequently asked questions

Is Beszel free?

Beszel is licensed under the MIT License, which the README states. The license file in the repository has the full terms.

What do I need to run Beszel?

The Docker-based install shown in the project's docs requires Docker. The quick start guide on beszel.dev covers the rest of the setup.

How do I install Beszel?

The README points to the quick start guide on beszel.dev for installation. Its only command in the README is git clone https://github.com/henrygd/beszel. Follow the guide for the hub and agent setup.

Does Beszel monitor Docker containers?

Yes. It tracks CPU, memory and network usage history for each container and shows the status of running Docker or Podman containers.

Does Beszel have a REST API?

Not in the README as written. The REST API feature is commented out in the feature list, so do not plan on it until the project documents it.

How does Beszel compare to Netdata, Prometheus, Grafana or Uptime Kuma?

The README calls Beszel lightweight and says it is smaller and less resource-intensive than leading solutions. It does not provide a direct benchmark against those projects, so test it on your own machines before deciding.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Beszel suits people running a homelab or a few personal servers who want a web dashboard, container stats and alerts without a heavy setup. It is not designed for large-scale or enterprise monitoring, and it is not a fit if you do not want to host software yourself or need a REST API today.

Install options & downloads