nixos/docs/beszel.md

Beszel agent

Beszel is the monitoring dashboard used in this LAN. The hub runs as a Docker container on docker.sweet.home (port vars.ports.beszelHub, 8090). Each monitored NixOS host runs a beszel-agent that connects back to the hub.

---

How it works

Everything is handled by a single module:

modules/beszel/enable-agent.nix — imported by a build type. It:

• Enables beszel-agent
• Sets HUB_URL to docker.sweet.home:8090
• Reads the universal beszel-token from secrets/common.yaml via sops and passes it to the agent as TOKEN in an env file
• Fixes an upstream bug where the agent couldn't persist its hub-pairing fingerprint across restarts (adds a real StateDirectory)

The only thing a host file ever needs to add is KEY — the hub's public key for that agent slot, which comes from the beszel hub UI after first pairing.

---

Adding beszel to a new build type

Add ../beszel/enable-agent.nix to the imports list in modules/build-types/<type>.nix:

imports = [
  ../beszel/enable-agent.nix
  # ... other imports
];

That's the only build-type change required.

---

Wiring the host file

No imports are needed in the host file. Just set KEY once you've paired the agent with the hub:

services.beszel.agent.environment = {
  KEY = "ssh-ed25519 AAAA...";
};

Leave KEY commented out until after the first pairing (see "Pairing with the hub" below).

---

One-time setup: add the token to secrets/common.yaml

The universal token is stored once in the common secrets file, shared by all agents. You only need to do this once, not per-host:

sops secrets/common.yaml

Add:

beszel-token: <token from the beszel hub UI>

The token is found in the beszel hub under Settings → Keys or in the "Add system" flow.

secrets/common.yaml is already a sops recipient for every host via their SSH host keys, so no additional sops recipient setup is needed for hosts that are already provisioned.

---

Optional: monitoring extra filesystems

To report disk usage for a mount beyond the root filesystem, add EXTRA_FILESYSTEMS alongside KEY in the host file:

services.beszel.agent.environment = {
  KEY = "ssh-ed25519 AAAA...";
  EXTRA_FILESYSTEMS = "/mnt/data";   # colon-separated for multiple paths
};

The server host uses this to expose its ZFS data pool:

EXTRA_FILESYSTEMS = "${vars.storageRoot}/${vars.nfsShares.dockerVolumes.subpath}";

---

Optional: monitoring Docker containers

enable-agent.nix has a commented-out line for Docker monitoring:

#DOCKER_HOST = "tcp://docker-socket-proxy:2375";

Uncomment it if the host runs docker-socket-proxy and you want per-container stats. Hosts without Docker should leave it commented out.

---

Pairing with the hub

1. Deploy the host with its build type importing enable-agent.nix. Leave KEY unset (commented out) for now.
2. Open the beszel hub (http://docker.sweet.home:8090).
3. Go to Systems → Add system. The new host should appear as an unpaired entry — copy the KEY value shown there.
4. In hosts/<name>/host.nix, set:

   services.beszel.agent.environment.KEY = "<copied key>";
   

5. Rebuild and deploy the host. The agent will now pair permanently.

---

Example: complete host file

Minimal case (hosts/tor-relay/host.nix — one filesystem, no Docker, LXC):

{ vars, ... }:
{
  networking = { ... };

  services.beszel.agent.environment = {
    KEY = "ssh-ed25519 AAAA...";
  };

  system.stateVersion = "26.05";
}

Fuller case (hosts/server/host.nix — extra filesystem, debug logging):

services.beszel.agent.environment = {
  KEY = "ssh-ed25519 AAAA...";
  EXTRA_FILESYSTEMS = "${vars.storageRoot}/${vars.nfsShares.dockerVolumes.subpath}";
  LOG_LEVEL = "debug";
};