---
title: "Beszel — Monitoring Hub and Agent Deployment Across Proxmox + LXC"
aliases: [beszel, beszel-agent, beszel-deployment, beszel-proxmox]
tags: [beszel, monitoring, proxmox, lxc, homelab, systemd, metrics]
sources:
  - "daily/2026-04-21.md"
created: 2026-04-21
updated: 2026-04-21
---

# Beszel — Monitoring Hub and Agent Deployment Across Proxmox + LXC

Beszel is a lightweight server monitoring tool with a hub-and-agent architecture. The hub runs as a single container and collects metrics from `beszel-agent` binaries deployed on each host. Agents authenticate using the hub's Ed25519 public key — not tokens or passwords. Deploying agents across a Proxmox host and all LXC containers requires installing the binary and creating a systemd service on each.

## Key Points

- **Beszel shows no systems until `beszel-agent` is installed** — the hub UI is empty by default; agents must be deployed separately on each target host
- **Authentication uses Ed25519 public key** from the hub — obtain from Beszel UI when adding a new system; not a JWT or API token
- **Each agent gets its own port** — Proxmox host typically on 45876; LXC containers on 45877–45882 (sequential); must be unique per host
- **"System shows red" usually means wrong IP/port in the hub UI**, not a broken agent — verify the agent is listening before debugging the agent itself
- **CT102 (Docker host) exposes inner container metrics** to Beszel via socket access, not separate per-container agents

## Details

### Architecture

```
Beszel Hub (PocketBase-based)
  ├── port 8090 (web UI + API)
  └── Agents push metrics via Ed25519-secured connection
      ├── Proxmox host → beszel-agent :45876
      ├── CT100 (Ollama) → beszel-agent :45877
      ├── CT102 (Docker) → beszel-agent :45878 (+ Docker socket for container metrics)
      ├── CT105 (NPM) → beszel-agent :45879
      ├── CT107 (Homarr) → beszel-agent :45880
      ├── CT109 (Grafana) → beszel-agent :45881
      └── CT110 (Uptime Kuma) → beszel-agent :45882
```

### Agent Installation (Each Host)

```bash
# Download and install beszel-agent binary
curl -sL https://raw.githubusercontent.com/henrygd/beszel/main/supplemental/scripts/install-agent.sh | bash -s -- \
  -p 45876 \
  -k "ed25519 public key from hub"

# The install script creates a systemd service automatically
systemctl status beszel-agent
```

Replace `45876` with the appropriate port for each container. The Ed25519 public key is shown in the Beszel hub UI when you click "Add System".

### Manual Systemd Service (Alternative)

If the install script is unavailable or fails:

```ini
# /etc/systemd/system/beszel-agent.service
[Unit]
Description=Beszel Agent
After=network-online.target

[Service]
ExecStart=/usr/local/bin/beszel-agent
Environment=PORT=45876
Environment=KEY="ed25519 AAAA..."
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
systemctl daemon-reload
systemctl enable --now beszel-agent
```

### CT102 — Docker Socket Integration

For the container that runs Docker Compose services, mount the Docker socket into the beszel-agent to expose inner container metrics (CPU, memory per container):

```bash
# Add to beszel-agent environment
Environment=DOCKER_HOST=unix:///var/run/docker.sock
```

Or use docker-socket-proxy if exposing the raw socket is a concern.

### Adding Systems in the Hub UI

After deploying agents, add each system in `http://<hub-ip>:8090/`:

1. Click **Add System**
2. Enter Name, Host (IP of the container/host), Port (the agent port)
3. Copy the **Ed25519 public key** shown in the dialog — paste this into the agent's `KEY` environment variable
4. Save

If a system shows **red** after adding:
- First check the IP and port in the UI — this is the most common cause
- `curl http://<agent-ip>:<port>/healthz` from another container to confirm connectivity
- Only then check the agent's systemd logs

### Diagnosing "System Shows Red"

```bash
# On the hub or another container — check agent is reachable
curl http://192.168.1.127:45877/

# On the agent container — check it's listening
ss -tlnp | grep 45877

# Check agent logs
journalctl -u beszel-agent -n 20

# If agent is healthy but hub shows red → fix IP/port in hub UI
```

The 2026-04-21 incident: Ollama (CT100) showed red in Beszel despite a healthy agent at `192.168.1.127:45877`. Root cause was the hub UI entry had the wrong IP — corrected to `.127` from `.xxx`, and Ollama turned green immediately.

### Temperature Variance Across Containers

All LXC containers on the same Proxmox host read the **same physical temperature sensors** (CPU cores, NVMe, board). Temperature readings may differ by ±5–10°C across containers due to different polling timestamps — this is normal polling jitter, not a hardware issue.

## Related Concepts

- [[wiki/concepts/ollama-lxc-ram-requirements]] — Ollama LXC container context where Beszel was used to monitor RAM usage
- [[wiki/concepts/homarr-proxmox-integration]] — Homarr is another monitoring/dashboard layer alongside Beszel
- [[wiki/concepts/proxmox-mcp-server]] — Proxmox MCP for managing the underlying infrastructure
- [[wiki/homelab/_index]] — full homelab infrastructure context

## Sources

- [[daily/2026-04-21.md]] — Beszel showed empty UI because no agents were installed; deployed beszel-agent on Proxmox host (45876) and 6 LXC containers (45877–45882); CT102 Docker socket integration; Ollama showed red due to wrong IP in hub UI (`.xxx` vs `.127`); temperature variance explained
