# 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`
- 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`:

```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:

```nix
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:

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

Add:
```yaml
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:

```nix
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:

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

---

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

---

## 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:
   ```nix
   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):

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

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

  system.stateVersion = "26.05";
}
```

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

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