homelab/docs/beszel.md

Beszel

Purpose: Lightweight container and host metrics monitoring (CPU, memory, disk, network).

Property	Value
Status	Running
Hub image	henrygd/beszel:latest
Agent image	henrygd/beszel-agent:latest
Web UI	https://beszel.home.jens.pub
Compose file	../services/beszel/docker-compose.yml

---

Architecture

Beszel uses a hub + agent model:

• Hub — web UI and data store, proxied via Traefik at beszel.home.jens.pub
• Agent — runs in host network mode, collects metrics and communicates with the hub via a shared Unix socket (/beszel_socket/beszel.sock)

Setup

On first run, open beszel.home.jens.pub, create an admin account, then add the local system:

1. Go to Systems → Add system
2. Set host to the Unix socket path: /beszel_socket/beszel.sock
3. Copy the generated public key
4. Set BESZEL_KEY in Portainer's stack env vars and redeploy

Environment Variables

Variable	Description	Source
APP_URL	https://beszel.home.jens.pub	hardcoded
LISTEN	/beszel_socket/beszel.sock	hardcoded
BESZEL_KEY	Hub public key for agent auth	.env

Volumes

Volume	Mount
beszel_data	/beszel_data — hub database and config
beszel_socket	/beszel_socket — shared Unix socket between hub and agent
/var/run/docker.sock	:ro — Docker socket for container metrics (agent)

Networks

• Hub: proxy (external)
• Agent: host