The architecture

  • Hub — one Beszel instance with the web UI + SQLite database + alert dispatcher. Runs anywhere.
  • Agent — one per monitored host. Tiny Go binary; collects CPU, memory, disk, network, swap, plus optional Docker container metrics; pushes to the hub via SSH.

SSH is the transport because it's already trusted, encrypted, and authenticated — no separate TLS layer to manage, no pre-shared tokens.

Install the hub

# docker-compose.yml on whatever host will run the hub
services:
  beszel:
    image: henrygd/beszel:latest
    container_name: beszel
    restart: unless-stopped
    ports:
      - "127.0.0.1:8090:8090"
    volumes:
      - ./data:/beszel_data
docker compose up -d
docker compose logs -f beszel

Browse to http://<host>:8090. Create the admin user (first user = admin). The UI is clean and self-explanatory; no per-component config files.

Reverse proxy

# Caddy
beszel.example.com {
    reverse_proxy 127.0.0.1:8090
}

Add an agent

In the UI, click "+ Add System." The form asks for:

  • Display name (e.g. web-01).
  • Host (IP or hostname; the hub will SSH to it).
  • Port (defaults to 45876, the Beszel agent port).
  • The agent's public key — Beszel auto-generates a unique key pair per system.

The UI then shows the install command for the agent on the target host:

# Run on the monitored host
curl -sL https://get.beszel.dev -o /tmp/install-agent.sh
chmod +x /tmp/install-agent.sh
sudo /tmp/install-agent.sh -p 45876 -k "<beszel-public-key>"

The script:

  1. Downloads the agent binary.
  2. Creates a beszel system user.
  3. Installs a systemd unit.
  4. Configures the SSH allow-list with the provided hub public key.
  5. Starts the agent.

Back in the hub UI, the system appears green within ~30 seconds. The dashboard shows CPU, memory, disk, network, load, uptime, OS, kernel, IP. Click any tile for a detail view with last 1h / 12h / 24h / 1w time-series charts.

Docker container metrics

If the agent runs on a host with Docker, it auto-discovers running containers and ships per-container CPU + memory + network. The Containers tab in the system view shows each one with its own charts. Filter by container name. Useful for "which of these 30 containers is suddenly eating RAM."

For non-Docker container runtimes (Podman, containerd directly), agent support exists but is less polished — check the latest release notes.

Alerts

Per system, per metric, set thresholds:

  • CPU > 90% for 10 min
  • Memory > 95% for 5 min
  • Disk > 90% (any mount)
  • System down (no agent check-in in N minutes)
  • Per-container CPU / memory thresholds

Alert destinations: email (SMTP configured in the admin settings), webhook (HTTP POST to any URL — pair with n8n / ntfy / Slack incoming webhook / Discord webhook).

The alert dispatch is deduplicated — one notification per condition firing, then re-notify only on resolution or escalation.

Multi-user / RBAC

Beszel supports multiple users with per-system access. Useful for "this team only sees their own boxes" patterns. The admin user can grant per-system or per-system-group read access to other users.

OIDC SSO

Recent Beszel versions support OIDC via PocketBase's built-in auth (Beszel uses PocketBase internally for the user store). Configure under Settings → Auth providers → OIDC. Works with Authentik (see that tutorial) and any other OIDC provider.

What Beszel doesn't have

  • No PromQL / LogQL — the metrics are fixed; you don't write custom queries. Want a custom metric? Beszel isn't the tool.
  • No log aggregation — metrics only. Pair with Loki (see that tutorial) for logs.
  • No trace ingestion — metrics only.
  • No long-term storage with high cardinality — SQLite caps growth. For multi-month retention with many hosts, plan to prune or export periodically.
  • No clustering / HA — the hub is a single node.

When Beszel is the right pick

  • Homelab or small business with <30 hosts.
  • "I want to know when a server is unhappy" is the only question; you don't need custom dashboards or PromQL.
  • You want install + first dashboard in under 10 minutes.
  • The fleet is reachable via SSH from a central point; no need to install a Prometheus exporter on every host with its own firewall hole.

When to graduate to Prometheus + Grafana

  • Custom application metrics are needed — the apps emit their own metrics in Prometheus format.
  • Dashboards need to combine metrics across systems with complex math.
  • You're already paying the operational cost of Prometheus for something else; adding Beszel duplicates work.
  • Fleet is large enough that the per-system push model becomes operationally inconvenient.

Both tools have a place; pick by the size of the actual question you have. For most homelabs in 2026, the question is small enough that Beszel is the right tool.