# Beszel agent

[Beszel](https://github.com/henrygd/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`
- Sets `KEY` from `vars.beszelHubKey` (`variables.nix`) — the hub's SSH
  public key, shared by every agent. Update `beszelHubKey` if the docker
  host is ever rebuilt and the hub generates a new keypair.
- 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`)

A host file needs no beszel configuration at all — just import the module
in the build type and add the system in the hub UI.

---

## Adding beszel to a new build type

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

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

That's the only change required. The host file needs nothing.

---

## Adding a new system to the hub

1. Rebuild and deploy the host with its build type importing `enable-agent.nix`.
2. Open the beszel hub (`http://docker.sweet.home:8090`).
3. Go to **Systems → Add system**, enter the host's IP and the default port
   (45876). The agent will connect and the system will appear as active.

---

## 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. Only needed once, not per-host:

```sh
sops secrets/common.yaml
```

Add:
```yaml
beszel-token: <token from the beszel hub Settings → Keys>
```

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

---

## Optional: monitoring extra filesystems

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

```nix
services.beszel.agent.environment = {
  EXTRA_FILESYSTEMS = "/mnt/data";   # colon-separated for multiple paths
};
```

---

## Optional: monitoring Docker containers

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

```nix
#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.

---

## If the hub key changes

If the docker host is ever rebuilt and beszel generates a new SSH keypair,
update `beszelHubKey` in `variables.nix` and rebuild all beszel-enabled hosts.
The new key is visible in the beszel hub under **Settings → Keys**.