How to Self-Host Beszel with Docker Compose

What Is Beszel?

Beszel is a lightweight server monitoring hub with a clean web UI, Docker container stats, historical data, and alerting. It uses a hub-agent architecture: a central hub collects data from agents running on each server you want to monitor. Recent releases (v0.18+) added experimental GPU monitoring (NVIDIA, AMD, Apple Silicon), outbound heartbeat monitoring, eMMC health tracking, and system uptime display. Beszel sits between simple tools like Uptime Kuma (which checks endpoints) and heavy stacks like Grafana + Prometheus (which require significant setup). Official site

Prerequisites

A Linux server (Ubuntu 22.04+ recommended)
Docker and Docker Compose installed (guide)
200 MB of free disk space
128 MB of RAM minimum
SSH key pair for hub-agent authentication

Docker Compose Configuration

Hub (Central Dashboard)

Create a docker-compose.yml file on your monitoring server:

services:
  beszel:
    image: henrygd/beszel:0.18.4
    container_name: beszel
    volumes:
      - ./data:/beszel_data
    ports:
      - "8090:8090"
    restart: unless-stopped

Start the hub:

docker compose up -d

Agent (On Each Monitored Server)

On each server you want to monitor, create a docker-compose.yml:

services:
  beszel-agent:
    image: henrygd/beszel-agent:0.18.4
    container_name: beszel-agent
    environment:
      - KEY=your-public-key-from-hub  # Set during hub setup
      - PORT=45876
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "45876:45876"
    restart: unless-stopped

Initial Setup

Open http://your-server-ip:8090
Create an admin account on first access
Click Add System to register your first server
The hub generates a public key — copy this to the agent’s KEY environment variable
Start the agent on the target server
The hub automatically connects and begins collecting metrics

Configuration

Adding Multiple Servers

For each server:

In the hub: Add System → enter a name and the agent’s IP:port (e.g., 192.168.1.100:45876)
Copy the public key shown
On the target server: set the KEY environment variable in the agent’s Docker Compose
Start the agent

Alerts

Beszel supports alerts for:

CPU usage thresholds
Memory usage thresholds
Disk usage thresholds
Container status changes (started/stopped)
System offline detection
Outbound heartbeat monitoring to external services (v0.18+)

Configure alerts per system in the web UI with precise value entry via text input. Notification methods include Discord, Slack, Telegram, Gotify, Ntfy, and email via SMTP.

Data Retention

Beszel stores data in a SQLite database. Configure retention under Settings to control how long historical data is kept. Default retention keeps several months of data at minimal disk cost.

Advanced Configuration (Optional)

Monitoring Without Docker Socket

If you don’t want to expose the Docker socket, the agent still monitors system metrics (CPU, RAM, disk, network). You lose per-container stats but maintain a smaller attack surface:

services:
  beszel-agent:
    image: henrygd/beszel-agent:0.18.4
    container_name: beszel-agent
    environment:
      - KEY=your-public-key
      - PORT=45876
    ports:
      - "45876:45876"
    restart: unless-stopped

GPU Monitoring (v0.18+)

Beszel experimentally supports GPU monitoring for NVIDIA, AMD, and Apple Silicon GPUs via nvtop. Set the GPU_COLLECTOR environment variable on the agent to specify your GPU collector:

services:
  beszel-agent:
    image: henrygd/beszel-agent:0.18.4
    container_name: beszel-agent
    environment:
      - KEY=your-public-key
      - PORT=45876
      - GPU_COLLECTOR=nvtop  # Options: nvtop (NVIDIA/AMD/Apple Silicon)
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "45876:45876"
    restart: unless-stopped

Disabling SSH

If you don’t need the SSH agent functionality, disable it with the DISABLE_SSH environment variable:

environment:
  - DISABLE_SSH=true

Custom Port

Change the agent port if 45876 conflicts:

environment:
  - PORT=45877
ports:
  - "45877:45877"

Update the port in the hub’s system configuration to match.

Running Agent Without Docker

Beszel provides a standalone binary agent for systems without Docker:

curl -sL https://raw.githubusercontent.com/henrygd/beszel/main/supplemental/scripts/install-agent.sh | bash

Reverse Proxy

Example Nginx Proxy Manager configuration:

Scheme: http
Forward Hostname: beszel
Forward Port: 8090

Reverse Proxy Setup

Backup

Back up the hub’s data directory:

docker compose stop beszel
tar -czf beszel-backup-$(date +%Y%m%d).tar.gz ./data
docker compose start beszel

Backup Strategy

Troubleshooting

Agent Not Connecting to Hub

Symptom: System shows as offline in the hub. Fix: Verify the agent’s KEY matches the public key shown in the hub. Check that port 45876 is open between the hub and agent servers. Verify the agent container is running: docker logs beszel-agent.

No Docker Container Stats

Symptom: System metrics show but no container-level data. Fix: Ensure /var/run/docker.sock is mounted in the agent’s Docker Compose. The Docker socket must be readable by the container user.

High Disk Usage Over Time

Symptom: The data directory grows steadily. Fix: Adjust data retention settings in the hub’s web UI. Beszel stores per-second metrics — reducing retention to 30 days significantly cuts storage.

Resource Requirements

Hub: ~50 MB RAM, negligible CPU
Agent: ~20 MB RAM per monitored server, negligible CPU
Disk: ~100 MB per monitored server per month (varies with metric count)

Verdict

Beszel hits the sweet spot between Uptime Kuma (too simple for server monitoring) and Grafana + Prometheus (too complex for small setups). If you run 2-10 servers and want per-container stats with a clean dashboard and zero YAML configuration, Beszel is the right choice. It’s newer than alternatives but actively developed and maturing quickly.

FAQ

Beszel vs Uptime Kuma?

Different focus. Uptime Kuma monitors endpoints (is this URL responding?). Beszel monitors servers (how much CPU/RAM/disk is this machine using?). Many people run both.

Beszel vs Netdata?

Netdata is per-server with thousands of metrics and per-second granularity. Beszel is a centralized multi-server hub with fewer but the most important metrics. Netdata is better for deep single-server debugging; Beszel is better for overview monitoring of multiple servers.

Is Beszel production-ready?

Beszel is pre-1.0 but stable for monitoring. It’s used by thousands of homelabbers. Don’t rely on it as your only alerting system for critical production infrastructure — pair it with something proven like Grafana alerting for that.