Proxmox Monitor Agent

O Proxmox Monitor Agent e um coletor leve em Bash para hosts Proxmox VE. Ele coleta um snapshot JSON com dados do host, sensores, storage, discos, rede fisica, VMs e LXCs, e pode expor esse snapshot via HTTP para consumidores como Home Assistant, Grafana, Prometheus bridges, MQTT bridges ou Node-RED.

O problema

Meu Home Assistant roda dentro de uma VM no Proxmox. Isso resolve muita coisa no homelab, mas cria um ponto cego: o HA consegue monitorar dispositivos da casa, mas nao enxerga diretamente sensores fisicos do host que sustenta a propria VM.

Esse ponto cego apareceu quando a ventoinha do servidor queimou. O host desligou por temperatura, eu reiniciei sem saber a causa, e so depois de acessar fisicamente o rack percebi que o servidor estava muito quente.

A solucao

A ideia do agent e simples: rodar no host Proxmox, coletar dados locais usando ferramentas do proprio Linux/Proxmox e publicar um contrato JSON previsivel.

Ele pode ser usado de duas formas:

pma-metrics, para imprimir o snapshot no terminal.
HTTP snapshot server, para servir GET /health e GET /metrics.json.

O que ele coleta

Identidade e uptime do host.
CPU, load average, memoria e swap.
Interfaces de rede fisicas, sem incluir interfaces virtuais ruidosas como vmbr*, tap* e veth*.
Filesystems relevantes, filtrando mounts de runtime como /proc, /sys, /dev e /run.
Storages do Proxmox e status local.
Discos e dispositivos de bloco.
Sensores normalizados, incluindo temperaturas e fans quando disponiveis.
Inventario e estado atual de VMs e containers LXC.
Diagnosticos de coleta em collection.errors e ferramentas ausentes em capabilities.missing_tools.

Decisoes de design

O agent nao guarda historico, nao dispara alertas e nao executa automacoes. Ele entrega um snapshot confiavel. Quem consome esse snapshot decide o que fazer com ele.

Essa separacao mantem o agent pequeno e facilita integrar com Home Assistant, Grafana, Prometheus, MQTT, Node-RED ou scripts proprios.

Quick Start

curl -fsSL https://raw.githubusercontent.com/mauricioj/proxmox-monitor-agent/main/install.sh | sudo bash

Depois da instalacao, teste localmente:

pma-metrics | jq .
curl -fsS http://127.0.0.1:9782/health | jq .
curl -fsS http://127.0.0.1:9782/metrics.json | jq '.schema, .host.hostname, .collection.status'