Estimated reading time: 7 minutes
If you want to keep your Homelab under control without messing around with complex tools like Prometheus or Grafana, Beszel is for you. This streamlined monitoring tool gives you everything you need - from system metrics to Docker statistics to configurable alerts - all with minimal setup.
For detailed instructions and an explanation of all configuration options, I recommend the YouTube video linked below. In this video, every single setting is explained in detail so that you receive comprehensive instructions for the exact setup. You can find any code from the video in this article so that you can use it directly without having to type it in.
This blog post and video is part of a series in which we create and set up our own home server. We start with the basics like an Ubuntu VM installation with Docker and then continue with the configuration of your own domain, security precautions and above all lots of cool and useful self-hosted services. Whether media servers like Plex or Jellyfin or document management like Paperless-NGX. Together we'll build the setup you want to see. We even tackle topics such as single sign-on (SSO) together.
What is Beszel?
Beszel is a lightweight, self-hosted monitoring system that consists of two main components.
- Stroke: A web application that provides you with a central dashboard for monitoring and managing your systems.
- AgentA service that runs on each system to be monitored and transmits the system metrics to the hub.
Beszel is particularly suitable for home labs as it is easy to install and does not require a public Internet connection.
Features at a glance
Beszel offers a variety of functions that make monitoring easier for you.
- Docker statisticsMonitor CPU, memory and network consumption of your containers.
- Configurable alertsReceive notifications when threshold values for CPU, RAM, hard disk space, bandwidth, temperature and system status are exceeded.
- Multi-user supportEach user can manage their own systems; admins can share systems with others.
- OAuth/OIDC integrationSupports multiple OAuth2 providers; password authentication can be disabled.
- Automatic backupsSave and restore data from the hard disk or S3-compatible memory.
- REST APIUse or update your data in your own scripts and applications.
You can find more information on the official website of Bescell.
Which metrics does Beszel monitor?
Beszel provides you with a wide range of system and container data at a glance. As soon as the agent is active, it regularly transmits metrics to the hub. You can visualize and evaluate this data in a clear dashboard.
Beszel supports the following metrics as standard:
🧠 Systemressourcen
- CPU utilization (total + per core)
- Working memory (total + used)
- Hard disk space (free + used per partition)
- System temperature (CPU and GPU, if available)
- Network traffic (upload/download per interface)
- Uptime and Hostname
🐳 Docker-Metriken (sofern aktiviert)
- Container CPU- and RAM utilization
- Network statistics per container
- Container status (running, stopped, etc.)
Optionally, you can feed in your own metrics via the REST API if you want to monitor smart devices, sensors or external services, for example.
Notifications: Be warned before something goes wrong
Beszel can automatically notify you as soon as certain limits are exceeded - perfect for detecting problems before they become serious.
You can configure notifications for:
- CPU or RAM usage above threshold X
- Too little free disk space
- High network utilization
- High system temperatures
- Container status (e.g. when an important container stops)
- General "Agent offline" status
These notifications are displayed directly in the web interface. You can also add your own notification integrations via webhooks (e.g. with Discord, Slack, ntfy or Pushover).
Installation with Docker Compose
The installation of Beszel is straightforward thanks to Docker Compose. Follow these steps.
Create directory
mkdir beszel && cd beszeldocker-compose.yml Create
services:
beszel:
image: henrygd/beszel:latest
container_name: beszel
restart: unless-stopped
extra_hosts:
- host.docker.internal:host-gateway
environment:
- USER_CREATION=true #for OIDC
ports:
- 8090:8090
volumes:
- /mnt/cache/appdata/beszel/data:/beszel_data
beszel-agent:
image: henrygd/beszel-agent:latest
container_name: beszel-agent
restart: unless-stopped
network_mode: host
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
environment:
PORT: 45876
KEY: "YOUR_PUBLIC_KEY"
networks: {}This Docker Compose file starts two containers: the Beszel Hub and the Beszel Agent.
The Stroke provides the web interface (accessible via port 8090), saves all data permanently on the host and allows the creation of an admin account when logging in for the first time. The configuration also allows the container to communicate with the host system.
The Agent collects metrics from the host system and from running Docker containers. It uses the "host" network mode to gain direct access to system information and reads the Docker socket to collect container data. It is securely connected to the hub via a public key.
Both containers are configured so that they restart automatically after a restart.
Start container
docker compose up -d
Create an admin user
Open your browser and navigate to http://:8090. You will be asked to create an account. The first user is automatically set as the administrator.
Configure your first system
Click on the "Add System" button at the top right to open the system creation dialog box.
ImportantStart the agent first before you click on "Add System" in the dialog. But we have already done that.
Add the system
After the agent is running, return to the "Add System" dialog and click on "Add System".
If the new system appears green in the list, everything is set up correctly.
If it appears red, check the Common Issues for possible solutions.
Monitoring with agents
The Beszel agent collects system metrics and sends them to the hub. You can install the agent in different ways.
- Docker/Podman containerIdeal for systems that already use containers.
- Single binary fileFor direct installation on the system.
- Home Assistant Add-onFor Home Assistant users.
If the agent and the hub are running on different hosts, you may need to configure the agent system's firewall to allow incoming TCP connections on the agent's port. Alternatively, you can use software such as WireGuard or Cloudflare Tunnel to securely bypass the firewall.
YouTube video implementation
Conclusion
Beszel offers you a simple and effective way to monitor your Homelab. With minimal effort, you get a powerful monitoring tool that can be seamlessly integrated into your existing infrastructure. Whether you want to keep an eye on your server resources or monitor Docker containers, Beszel is the right choice for you.
0 Comments