Agent Install (per Proxmox host)

Prerequisites on the Proxmox host

Proxmox VE 8.3+ (OpenZFS 2.3+ for the -j flags on zpool/zfs)
Root SSH access
Outbound HTTPS to the monitor server

No Erlang or Elixir needed — the Burrito binary ships its own runtime.

1. Build the binary (operator workstation)

cd proxmox_monitor/agent
./scripts/build-linux.sh            # requires Docker
ls dist/
# proxmox-monitor-agent_linux_amd64
# proxmox-monitor-agent_linux_arm64

2. Register the host in the dashboard

From the dashboard at https://monitor.example.com/admin/hosts:

"Register a new host" → enter the short name (e.g. pve-host-01).
Copy the one-time token shown.

3. Copy files to the Proxmox host

HOST=pve-host-01
scp dist/proxmox-monitor-agent_linux_amd64 \
    root@$HOST:/usr/local/bin/proxmox-monitor-agent
ssh root@$HOST 'chmod 0755 /usr/local/bin/proxmox-monitor-agent'

# systemd unit (included in the repo)
scp rel/proxmox-monitor-agent.service \
    root@$HOST:/etc/systemd/system/

4. Write the config

On the Proxmox host:

install -d -m 0700 /etc/proxmox-monitor
cat > /etc/proxmox-monitor/agent.toml <<EOF
server_url = "wss://monitor.example.com/socket/websocket"
token = "<paste-token-from-dashboard>"
host_id = "pve-host-01"

[intervals]
fast_seconds = 30
medium_seconds = 300
slow_seconds = 1800
EOF
chmod 0600 /etc/proxmox-monitor/agent.toml

5. Enable the service

install -d -m 0700 /var/cache/proxmox-monitor-agent
systemctl daemon-reload
systemctl enable --now proxmox-monitor-agent
journalctl -u proxmox-monitor-agent -f

Expected within ~10s:

agent: starting with host_id=pve-host-01
reporter: connected, joining host:pve-host-01
reporter: joined host:pve-host-01

The host's card on the dashboard should flip to online.

6. Token rotation

If a token leaks: dashboard → Admin → "Rotate". Copy the new token, update /etc/proxmox-monitor/agent.toml on the affected host, systemctl restart proxmox-monitor-agent. Old token is invalidated immediately.

7. Upgrade flow

# operator
./scripts/build-linux.sh
scp dist/proxmox-monitor-agent_linux_amd64 root@$HOST:/usr/local/bin/proxmox-monitor-agent.new

# on the host
mv /usr/local/bin/proxmox-monitor-agent{.new,}
systemctl restart proxmox-monitor-agent

Troubleshooting

Symptom	Check
`enoent` errors for `zpool`/`pvesh`	You're not on a Proxmox host, or binaries aren't in `$PATH`.
`handshake_failed: :nxdomain`	DNS for the monitor hostname fails from this host.
`unknown_host` rejection on join	Host name in `agent.toml` doesn't match the dashboard entry.
`invalid_token` rejection	Token was rotated; paste the new one.
Agent reconnects every 30s	Server's WebSocket timeout hit — check Caddy `read_timeout 90s`.

3.1 KiB Raw Blame History