---
name: Beszel
description: Lightweight server monitoring hub — CPU, memory, disk, network, Docker container stats, temperature, GPU, battery. Hub + agent architecture over SSH. Built on PocketBase.
---

# Beszel

Beszel is a small, self-contained monitoring platform: you run one **hub** (web UI + PocketBase DB) and install an **agent** on each host you want to monitor. The hub pulls metrics from agents over an SSH-authenticated connection — no agent listens on a public port unless you want it to, and no third-party telemetry leaves your network.

- Upstream repo: <https://github.com/henrygd/beszel>
- Docs: <https://beszel.dev/>
- Images:
  - Hub: `henrygd/beszel`
  - Agent: `henrygd/beszel-agent` (standard) / `henrygd/beszel-agent-nvidia` (CUDA/GPU stats) / `henrygd/beszel-agent-intel` (Intel GPU)

## Architecture in one minute

```
[agent on host A]  ─┐
                    │   SSH (ed25519 keypair)
[agent on host B]  ─┼──────────────────────────▶  [hub] ──── HTTP ──── you (browser)
                    │
[agent on host C]  ─┘
```

The hub is a Go binary wrapping PocketBase; all state (registered systems, history, users) lives in a single SQLite dir (`/beszel_data`).

## Compatible install methods

| Role  | Infra              | Runtime                                      | Notes                                                                       |
| ----- | ------------------ | -------------------------------------------- | --------------------------------------------------------------------------- |
| Hub   | Any Linux host     | Docker + Compose                             | Recommended; tiny footprint                                                 |
| Hub   | Any Linux host     | Native binary (systemd)                      | Installer script available                                                  |
| Hub   | Kubernetes         | Helm chart (upstream `supplemental/kubernetes/beszel-hub`) | Upstream-shipped chart                                           |
| Agent | Linux host         | Docker (host networking) / binary / brew     | `install-agent.sh` script supported                                         |
| Agent | Windows / macOS    | Installer / brew                             | Supported                                                                   |

## Inputs to collect

| Input              | Example                                | Phase      | Notes                                                                    |
| ------------------ | -------------------------------------- | ---------- | ------------------------------------------------------------------------ |
| Hub hostname       | `beszel.example.com` or LAN IP         | Hub        | Agents will connect out; no inbound ports on the agent unless you use port 45876 |
| Hub port           | `8090`                                 | Hub        | Web UI; reverse-proxy in front for TLS + auth-chain                      |
| SSH public key     | `ssh-ed25519 AAAA...`                  | Hub→Agent  | Generated by the hub on first boot; shown in UI as the agent's `KEY`     |
| Agent port         | `45876`                                | Agent      | Only needed when hub → agent connectivity is "pull over SSH"             |
| Docker socket      | `/var/run/docker.sock` (ro)            | Agent      | Mount if you want container stats                                         |
| Extra filesystems  | `/mnt/disk/.beszel:/extra-filesystems/sda1:ro` | Agent | Mount folders to include additional disks/partitions in stats        |

## Install — hub only (separate-system layout)

```yaml
# compose.yml
services:
  beszel:
    image: henrygd/beszel:0.18.7    # pin; see https://github.com/henrygd/beszel/releases
    container_name: beszel
    restart: unless-stopped
    ports:
      - '8090:8090'
    volumes:
      - ./beszel_data:/beszel_data
```

```sh
mkdir -p beszel && cd beszel
docker compose up -d
```

Browse `http://<host>:8090`:

1. Create the first super-admin user.
2. "Add system" → copy the SSH public key Beszel gives you — that's what you'll set as `KEY` on each agent.

## Install — agent

### Docker (recommended)

```yaml
# on each monitored host
services:
  beszel-agent:
    image: henrygd/beszel-agent:0.18.7    # match hub major.minor
    container_name: beszel-agent
    restart: unless-stopped
    network_mode: host
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      PORT: 45876
      KEY: 'ssh-ed25519 AAAA...'     # the key shown by the hub
```

For NVIDIA GPUs, swap the image to `henrygd/beszel-agent-nvidia` and add `runtime: nvidia` + `NVIDIA_VISIBLE_DEVICES=all`.

### Native binary

Upstream's installer script (reviewed before running):

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

Installs a systemd unit. Edit `/etc/beszel-agent/config.yml` (or equivalent) to set `KEY` and `PORT`.

### Same-system (hub + agent on one host)

Upstream ships a `supplemental/docker/same-system/docker-compose.yml` that runs both containers side-by-side. Uses `extra_hosts: - host.docker.internal:host-gateway` so the hub can reach the agent's host-network port.

## Data & config layout

- **Hub:** `./beszel_data/` → `/beszel_data` in container. Contains:
  - `data.db` — PocketBase SQLite file (users, systems, history)
  - `pb_data/` — PocketBase internals
  - `id_ed25519*` — hub's SSH keypair used to authenticate to agents
- **Agent:** stateless; configured entirely via env vars or `config.yml`.

## Backup

```sh
# Hub — stop briefly and copy the whole data dir
docker compose stop beszel
tar czf beszel-$(date +%F).tgz beszel_data/
docker compose start beszel
```

Losing `beszel_data/` means losing the hub's SSH key — **you will have to re-enroll every agent** with a new public key.

## Upgrade

1. Check release notes: <https://github.com/henrygd/beszel/releases>.
2. Bump both hub and agent image tags **together** — the RPC protocol isn't strictly versioned and mismatched versions occasionally break.
3. `docker compose pull && docker compose up -d` on the hub, then roll out agents.
4. Hub schema migrations run on start; check logs if the UI 500s after an upgrade.

## Gotchas

- **Agents use host networking.** That's how they read physical NIC stats, per-CPU load, etc. If you can't grant `network_mode: host`, many metrics will be missing or wrong.
- **The hub's SSH key = your trust root.** Anyone with `beszel_data/id_ed25519` can impersonate the hub and connect to any enrolled agent. Back it up encrypted; permission-guard the mount.
- **Agents have no user-facing auth** — only the hub's SSH key is trusted. Don't expose the agent's port 45876 on the public internet; firewall it to the hub's IP.
- **Docker socket mount = root-equivalent access.** If an attacker compromises the agent container, they can spawn privileged containers on the host. Keep the mount `:ro` (agent doesn't need write) and consider `docker-socket-proxy` for hardening.
- **GPU stats need the matching agent image.** `henrygd/beszel-agent` → CPU/mem/disk only. Add `-nvidia` or `-intel` and the matching runtime to see GPU data.
- **No alerting via email by default.** Beszel supports notifications through PocketBase's mail settings + webhook providers; configure under the hub's Settings once you register.
- **Retention is configurable per metric type.** Default history windows are documented in the hub's Settings UI — don't be surprised when older points are downsampled.
- **PocketBase admin UI** lives at `/_/` on the hub port. It's gated by the same admin account but exposes raw DB editing — don't hand out admin credentials casually.
- **Versions before 1.0**: Beszel is pre-1.0. Read every release note for breaking changes; pin major.minor.patch in production.

## Links

- Repo: <https://github.com/henrygd/beszel>
- Docs: <https://beszel.dev/>
- Release notes: <https://github.com/henrygd/beszel/releases>
- Compose examples: <https://github.com/henrygd/beszel/tree/main/supplemental/docker>
- Agent install script: <https://github.com/henrygd/beszel/blob/main/supplemental/scripts/install-agent.sh>
- Kubernetes chart: <https://github.com/henrygd/beszel/tree/main/supplemental/kubernetes/beszel-hub>
