Beszel

What it does here

Beszel graphs CPU, memory, disk and per-container use over time. A filling /srv shows up here first.

From the manual

Canonical setup

Two pieces: a hub with the dashboard, and an agent that reads host and container stats. Start the hub, add a system in its UI to get the agent's key, then start the agent with that key.

Upstream: Beszel: getting started.

Edited for this build

In this build

Hub and agent both on host networkingThe agent needs it for real host stats. The hub on the host network reaches the agent on localhost instead of crossing the Docker bridge.
The system added as localhost, port 45876
The key written into the compose fileNot interpolated from .env.
Served by Caddy as metrics.dev.tailnet.exampleThe hub listens on 8090.

/srv/stacks/beszel/docker-compose.yml (hub first)

services:
  beszel:
    image: henrygd/beszel:latest
    container_name: beszel
    restart: unless-stopped
    network_mode: host
    volumes:
      - /srv/data/beszel:/beszel_data

Start the hub with docker compose up -d beszel, create the admin account, then Add System with host localhost and port 45876. Copy the key it shows and add the agent:

Agent, added to the same file

  beszel-agent:
    image: henrygd/beszel-agent:latest
    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 hub key..."

Where it breaks

Seams

Where this meets the rest of the build. Each one leads with what you will actually see.

A bridge hub meets the firewall

Symptomthe system never connects

On the bridge network, the hub reaches the agent's host port across the Docker bridge, and the tailnet-only firewall drops it. Run the hub on host networking.

The agent meets a hub that hasn't retried

Symptomthe system stays red after the agent is up

The hub hasn't tried again yet. Edit the system in the hub and Save to force a reconnect.

A key with spaces meets .env

Symptomthe agent doesn't accept the hub's key

Compose's .env interpolation of a value with spaces is unreliable. Write the key into the compose file as a map value, quoted.

docker exec meets a shell-less image

Symptomdocker exec beszel-agent env fails

The agent image has no shell or env. Check its settings with docker inspect -f '{{range .Config.Env}}{{println .}}{{end}}' beszel-agent.

Verify

The system shows green in the hub, and graphs start filling within a minute or two.

Corrections and updates

17 Oct 2026First written.