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

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

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

## 3. Copy files to the Proxmox host

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

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

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

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