Beszel

Overview

Beszel keeps a small historical view of server resources: CPU, RAM, swap, disk usage and traffic. Agents supply the measurements; the hub stores accounts, access assignments, alert settings and history in local SQLite databases. It suits household servers and small infrastructure where a compact resource dashboard is useful.

This recipe installs the hub, not agents on every machine. Add each monitored system through the native interface and deploy a matching pinned agent on that system. Docker, GPU, SMART, ZFS and systemd integrations need separate permissions and configuration. The included smoke uses a real isolated agent without host networking or Docker socket; its readings are sandbox measurements.

The hub creates both an application administrator and a PocketBase superuser from the supplied email/password only when the database is new. Self-registration is closed. Upstream supports OIDC, email-OTP MFA and trusted-header authentication, but the recipe does not configure them. SMTP is required for email-OTP MFA.

The browser interface is built in. Android/iOS and macOS clients listed by the official documentation are independent third-party projects and were not tested here. Review their licenses and credential handling before connecting them.

For users of Netdata Cloud, Beszel covers local server-resource dashboards and history. Its monitoring scope and integrations differ; no price saving is claimed without verified current terms.

Security assessment (2026-10-24): loopback HTTP, non-root process, read-only container root, closed signup and no host/Docker access. Protect the hub’s SSH identity, the PocketBase admin interface and every agent separately. This configuration review is not a vulnerability scan.

Sources: hub installation, agents, environment, security, OIDC, mobile, desktop.

Step-by-step guide

Installation

Use Ubuntu 24.04 LTS or Debian 12/13, Docker Engine and Compose >=2.24.0 from the official repository. Download the complete recipe.

cp .env.example .env
chmod 600 .env
openssl rand -hex 24

Replace CHANGE_ME in BESZEL_ADMIN_PASSWORD with the random value and set your BESZEL_ADMIN_EMAIL and actual BESZEL_URL.

docker compose config --quiet
docker compose pull
docker compose up -d --wait
docker compose ps

Open http://localhost:8090 and sign in with the supplied email/password. On a new database they create the Beszel administrator and PocketBase superuser; environment changes do not rotate existing credentials. Set private credentials before exposing the hub.

VPS

Use a domain, HTTPS, firewall and encrypted off-server backups. Keep 8090 on loopback; expose only the reverse proxy. Restrict /_/ administration to trusted operators.

LAN / VPN

Prefer an SSH tunnel (ssh -L 8090:127.0.0.1:8090 user@server) or VPN/proxy. For direct trusted-LAN access, explicitly change the bind address in Compose and restrict it with the firewall. Set BESZEL_URL to the actual browser origin.

HTTPS

Point DNS at the proxy and set BESZEL_URL=https://metrics.example.com, then recreate the service. Forward WebSocket upgrades and allow long-lived connections; agents using WebSocket and the live interface need them.

Caddy

Use proxy/Caddyfile on the host; Caddy handles TLS and WebSocket upgrades.

Nginx

Obtain the referenced certificate, install proxy/nginx.conf in the http context, run nginx -t and reload. The map selects the appropriate Connection header.

Traefik

Load proxy/traefik.yaml through the file provider with websecure and the letsencrypt resolver. The sample assumes host Traefik; a container needs a route to the hub instead of host loopback.

Data / Данные

The named BESZEL_DATA_VOLUME is mounted at /beszel_data: data.db, auxiliary.db, SSH private key id_ed25519, notification state and any native backups. Preserve the whole directory, including WAL files while running. No agent state is mounted here. Changing the volume name selects another installation.

Backup

Run bash backup.sh. It stops the hub, archives the entire data volume plus .env and Compose, then restores its prior running/stopped state. Archives have mode 600. Encrypt and copy them off-server; keep each monitored agent’s own configuration, token and data separately.

Restore / Восстановление

Restore replaces current monitoring data. Use only a trusted archive. Start the recipe once on a new machine, compare archived configuration.env manually (it is not activated), and run bash restore.sh /safe/path/beszel-backup.tar. The script validates required files, takes a safety backup, replaces data and waits for health. Failed extraction leaves the hub stopped. Restored account passwords and SSH key are authoritative; verify old history and that agents reconnect.

Update / Обновление

Read release notes, back up, set a new explicit BESZEL_VERSION and run docker compose pull && docker compose up -d –wait. Never use latest. Upgrade separately deployed agents to a compatible pinned version and verify metrics. The hub update is an in-place replacement; review future major migration instructions before adopting them.

Rollback / Откат

Stop beszel, restore the previous BESZEL_VERSION in .env, pull and start it once, then restore the matching pre-update archive. A database migrated by a new PocketBase/Beszel version may not work with an older binary; restore the old snapshot rather than reusing migrated files. Verify login, assigned systems and agent connectivity.

Removal / Удаление

docker compose down keeps the named volume. For permanent deletion, export a backup first, verify the project and BESZEL_DATA_VOLUME, then run docker compose down –volumes. This destroys accounts, SSH identity and history. Remove .env, proxy/DNS rules and separately deployed agents only when no longer needed.

Every .env.example parameter

Connect real systems

Use Add System and the agent guide on the machine you intend to monitor. Replace any floating image in the UI-generated command with henrygd/beszel-agent:0.21.1. For SSH allow the agent port only from the hub; for WebSocket use TLS. Add Docker socket, host networking or devices only when those integrations are needed. The hub public key is not its private key. SMTP, OIDC, MFA and notification delivery are not configured by this recipe.

Report a recipe problem

Tell us how it went on your server

Opens a prefilled GitHub issue. A GitHub account is required; submitting the issue makes it public.

Troubleshooting

Diagnostics

docker compose ps
docker compose logs --tail=100 beszel
docker compose exec beszel /beszel health --url http://127.0.0.1:8090

Wrong password: bootstrap environment applies only to a new database. Restore brings back old credentials. Use your authorized PocketBase password-reset procedure; never delete the volume just to reset login.

No systems/metrics: the recipe installs only the hub. Deploy a separate agent, assign the system to the user, and check its address, port, key and version. Localhost inside the hub means the hub container. Restrict SSH to the hub; WebSocket needs a correct HUB_URL, registration token, TLS and proxy upgrade.

Permission denied: the initializer makes the data volume owned by UID/GID1000. Never use another application’s volume. Container root is read-only; data and temporary tmpfs are writable.

Missing notifications: SMTP/push is not configured. A saved alert rule does not prove delivery. Check the integration using the official documentation.

Empty history: newly connected systems collect measurements over time; aggregates arrive later. A user sees only assigned systems. Sandbox container measurements do not prove complete physical-host monitoring.

Backup/restore: FOSSARY_ENV_FILE selects another .env. Incomplete archives are rejected before stopping. Failed extraction leaves the hub stopped: inspect space, permissions, archive and safety copy. Archives contain credentials and a private SSH key; never publish them.