HomeLab Monitor

HomeLab Monitor

Uma página para todo o seu home lab e rig de IA — verdade sobre GPU (qualquer fabricante), tokens/seg, custo de energia por hora, uptime, execuções de treinamento, contêineres, discos. Sem agentes, sem stack de métricas separada, sem nuvem.

Seu home lab cresceu para algumas máquinas, um Pi e uma GPU que está misteriosamente sempre ocupada — e ultimamente também está rodando modelos. O HomeLab Monitor oferece uma página auto-hospedada que responde às perguntas reais: o que essa GPU está realmente fazendo, qual modelo está segurando ela, quanto custa para rodar, qual contêiner está consumindo RAM, o que está enchendo seus discos e se algo está fora do ar — em todas as máquinas via SSH: Linux, um Pi, até Windows. Legível pelo celular via VPN.

Comece agora

# Grab the compose file and go. No GPU required — the GPU panels just light up when one's present.
curl -fsSLO https://raw.githubusercontent.com/SikamikanikoBG/homelab-monitor/main/docker-compose.yml
docker compose up -d

Abra http://<your-host>:9800 e pronto. Opções completas (a partir do código-fonte, toolkit de GPU, Windows/WSL2) → Documentação de instalação.

🆕 Novidades — cada versão é documentada por completo, com a justificativa por trás dela: última versão · changelog. O painel também mostra as notas uma vez, no aplicativo, após se atualizar.

O que você obtém

Uma página, todas as máquinas, as perguntas que você realmente tem. Os clássicos estão todos aqui — e um cockpit de IA completo é construído sobre eles.

Uma página inicial para o seu laboratório — e uma tela de parede. A Visão Geral abre com um Launchpad: os aplicativos que você realmente abre, como blocos com seus logotipos reais, fixados diretamente de uma linha de contêiner com o endereço já preenchido, agrupados e arrastados na ordem que você quiser. Os pinos ficam no hub, não em um navegador — fixe no laptop e estará no celular e na parede. O quadro inteiro cabe na tela: ele mede seu próprio excesso após cada renderização e cede espaço em ordem — encurtando listas, apertando a trilha da frota, dobrando pinos atrás de um +N mais — em vez de cortar um cartão ao meio ou passar da dobra. Verificado de 4K até 1366×768. E ⛶ Display (ou /?display=1, tudo o que um box de kiosk dedicado precisa) remove todo o excesso de interface e preenche o monitor: você escolhe quais painéis a parede mostra, e em navegadores baseados em Chromium ele abre em tela cheia na tela que você apontar.

Sua GPU, desmistificada — e a mesma aba em todas as máquinas. Um cartão fixado em "utilização 100%" ainda pode estar com throttling, limitado por largura de banda de memória ou com clocks caindo silenciosamente. A aba de GPU decodifica os motivos de throttle do nvidia-smi e mostra utilização de largura de banda de memória, clocks de núcleo/memória, potência vs. limite, p-state — e velocidade do ventilador — para todas as máquinas da frota, não apenas a que está rodando o contêiner. Máquinas com múltiplas GPUs recebem um painel por placa em uma escala compartilhada por métrica, então uma linha de temperatura mais alta realmente é uma placa mais quente; janelas de throttle térmico são sombreadas diretamente no sparkline. Você pode ver em qual placa um serviço está rodando (uma máquina 3×3090 mostra os 63 GB de um modelo divididos em 22,5 / 22,1 / 18,8 entre as placas, não um número agregado), quanto cada serviço custou em energia, e receber alertas quando uma placa sofre throttle, superaquece ou perde um ventilador — sustentado, por placa, com limites por host, porque uma máquina com limite de potência deliberadamente reduzido deve ficar no seu teto. E não é mais apenas NVIDIA: GPUs AMD são lidas no Linux diretamente da interface amdgpu do kernel (sem ROCm), e GPUs AMD e Intel em hosts Windows — então sua placa aparece com nome, utilização e VRAM, sem ferramentas do fabricante. Qualquer coisa que um driver não reportar é indicada como tal, em vez de desenhar um zero confiante.

Quanto custa — até o processo. Energia vira dinheiro: por máquina, depois por componente (GPU medida via nvidia-smi, CPU/DRAM via RAPL), depois por processo, contêiner ou modelo — clique em qualquer linha para ver o que consumiu e quanto custou em qualquer período. Tarifas de dia e noite (Economy 7, Heures Creuses, …), ou apenas escolha seu país para uma estimativa razoável. Cada watt é medido ou uma linha de base que você define; a energia da tomada nunca é adivinhada. E um mapa de calor de horários de pico transforma meses de amostras em uma imagem de quando seu laboratório custa dinheiro — uma grade 7×24 de dia da semana × hora que mostra qual hora da semana é a mais cara de relance.

Suas execuções de treinamento, precificadas. Envie uma execução do Jupyter, Colab ou Kaggle com um cliente de arquivo único (ou espelhe do MLflow), e ela volta com a curva de perda e a energia real de GPU que consumiu, na mesma linha do tempo. Crie, nomeie, expire e revogue chaves de API você mesmo.

"Vai caber?" — medido, não adivinhado. O Benchmark Lab carrega cada um dos seus modelos locais do ollama e varre uma escada de tamanhos de contexto nas suas placas reais, registrando tokens/seg de geração e prompt, tempo de carregamento, quanto vazou da VRAM para a RAM do sistema e o maior contexto que ainda cabe totalmente na VRAM — o limite que vale a pena definir. Escolha qual(is) GPU(s) testar (via um contêiner ollama descartável fixado — o principal nunca é tocado), sobreponha execuções armazenadas para comparar placas, e cada execução volta com a energia que consumiu e o custo. Os resultados são armazenados: faça benchmark uma vez, reexecute apenas quando algo mudar.

E o resto do laboratório, como sempre foi:

• Contêineres, honestamente — saúde mais RAM e VRAM em colunas separadas (RAM residente real, não cache de página), e clique em um para ver os logs em uma gaveta lateral. Todas as máquinas da frota recebem os mesmos controles — logs, iniciar/parar/reiniciar, política de reinício, fixar — pela mesma conexão SSH que a sonda já usa, e a aba inteira funciona no celular.
• Serviços systemd — locais ou remotos, suas próprias unidades destacadas, falhas primeiro.
• Treemaps de disco estilo WizTree — em qualquer máquina da frota. Clique nas pastas que estão enchendo um disco no hub ou em qualquer host Linux que você adicionou; um remoto é escaneado pela mesma conexão SSH que tudo o resto usa, então ainda não há nada para instalar nele. Além de I/O de rede com os maiores consumidores por contêiner e um mini-htop para quem está consumindo CPU e RAM.
• Move-se como um painel ao vivo. Utilização, RAM, temperatura e potência atualizam a cada poucos segundos por um stream push em vez de polling fixo — e faz isso fazendo menos requisições do que antes, porque a consulta cara de histórico é buscada apenas na frequência em que os buckets do gráfico podem mudar, e uma aba que você não está olhando para de custar qualquer coisa. A cadência de amostragem e armazenamento não é alterada, então o histórico permanece exatamente tão denso (e os custos exatamente tão precisos) quanto eram.
• Multi-máquina via SSH — cole uma chave por máquina; Linux, um Pi, até Windows. Sem agentes, sem instalações. A aba de GPU também funciona por host: um rig remoto multi-GPU mostra VRAM, utilização, potência e temperatura de cada placa, e os processos que seguram a memória.
• Monitoramento de uptime, dentro do box — monitore qualquer endpoint HTTP ou porta TCP (seus serviços, um NAS, um site remoto) direto do contêiner: faixa de heartbeat, % de uptime 24h/7d, latência e alertas inteligentes por verificação — confirmação anti-flap, recuperação com tempo de inatividade e um aviso opcional de resposta lenta. Sem serviço de uptime extra para auto-hospedar — já está no box.
• Alertas push — Discord, ntfy.sh e Telegram, acionados por borda para não gerar spam.

Tour completo aba por aba → Recursos.

Multi-máquina, em duas frases

Abra a aba Hosts, cole a chave SSH gerada automaticamente pelo hub em cada remoto, e o hub começa a fazer polling — sem agentes, apenas SSH + Python 3 (PowerShell no Windows). O hub envia uma sonda pequena e autocontida via SSH; nada persiste no remoto. A mesma conexão é o que permite abrir o cockpit de GPU de um remoto e escanear seus discos a partir do hub — ainda sem nada instalado na outra ponta.

Onboarding, configuração do Windows e o modelo de segurança → Documentação multi-máquina.

Configuração

Defina estas opções em environment: no docker-compose.yml (todas opcionais):

Variável	Padrão	Significado
SAMPLE_INTERVAL	10	Segundos entre amostras armazenadas. Esta é a cadência de armazenamento — cada figura de energia e custo é integrada contra ela, então alterá-la muda como o histórico é precificado
FAST_INTERVAL	2	Segundos entre atualizações de valores ao vivo na tela. Lê apenas contadores baratos e não armazena nada, então não custa histórico nem precisão. 0 desliga o stream push e o painel volta a usar polling
RETENTION_DAYS	180	Por quanto tempo o histórico é mantido
PRESSURE_FREE_MB	2048	VRAM livre abaixo deste valor conta como "pressão"
PORT	9800	Porta do painel
MCP_PORT	9810	Porta do servidor MCP somente leitura integrado
ENABLE_MCP	1	Defina 0 para rodar o painel sem o servidor MCP
ENABLE_CONTROLS	1	Defina 0 para remover os botões iniciar/parar/reiniciar das abas Contêineres e Serviços
ALLOW_SELF_UPDATE	1	Defina 0 para desativar a atualização no aplicativo
WATCH_CONTAINERS	—	Contêineres extras para escanear por OOM (separados por vírgula)
WATCH_SERVICES	—	Unidades systemd para sempre mostrar, mesmo as de fornecedores (separadas por vírgula)
CHECK_UPDATES	true	Defina false para desativar a verificação diária de versões do GitHub (sem chamadas de saída)
CHECK_OS_UPDATES	true	Defina false para parar de reportar atualizações de pacotes do SO pendentes
PUBLIC_STATUS	—	Defina para ativar a página de status pública (também um alternador em Configurações, que não requer reinício)
DB_PATH	/data/gpu.db	Onde o histórico é armazenado dentro do contêiner
HOST_ROOT	/rootfs	Ponto de montagem da raiz do host somente leitura
DOCKER_SOCK	/var/run/docker.sock	Socket Docker para ler contêineres

O histórico vive em ./data/gpu.db (um bind mount), então sobrevive a reinícios e atualizações. Alertas, o mount D-Bus do systemd e ajustes por servidor → Documentação de configuração.

Por baixo do capô

O hub costura nvidia-smi (mais GPUs AMD via interface sysfs amdgpu no kernel, e AMD/Intel em hosts Windows via contadores de desempenho de GPU integrados), a API Docker, APIs de servidores de modelo (Ollama, vLLM, llama.cpp, A1111, …), D-Bus do systemd e /proc + /sys em uma visão amostrada, persistida em SQLite e com downsampling na leitura, para que um intervalo de seis meses carregue tão rápido quanto a última hora. Página única, Chart.js embutido, sem etapa de build.

• Mais de 30 servidores de modelo reconhecidos → Servidores de modelo
• Endpoint /metrics padrão para coletar nos painéis que você já usa → Exportação de métricas
• O pipeline completo de dados + atribuição de chamadas → Como funciona

Conecte um agente de IA (MCP)

Seu homelab agora é legível para agentes de IA — aponte um cliente para uma URL e ele pode ver cada host, contêiner, GPU e disco. Somente leitura, sem configuração extra.

O HomeLab Monitor não é apenas um painel para você; também é contexto para seu agente de IA. Um servidor MCP somente leitura está integrado no mesmo contêiner (servido em :9810) — então Claude, Claude Code ou qualquer cliente MCP conecta em uma linha e explora todo o seu laboratório através de 19 ferramentas nomeadas, com a mesma cobertura que você vê no painel: hosts, contêineres, serviços systemd, GPU e quem está usando ela, RAM por processo, servidores de modelo de IA, modelos instalados, custos, execuções de experimentos, benchmarks de modelo, treemaps de disco, histórico e alertas.

_{Conecte qualquer cliente MCP — Claude, ChatGPT ou um agente nos seus próprios modelos locais Ollama — e ele lê o estado ao vivo do seu homelab. Somente leitura: ambas as direções são apenas perguntas e respostas.}

# the dashboard is on :9800; the MCP server rides along on :9810
claude mcp add --transport http homelab http://YOUR-HUB:9810/mcp

Depois de conectado, pule a caça às abas e apenas pergunte — o agente escolhe as ferramentas certas:

• "Minha GPU está saturada há uma hora — qual servidor de modelo está carregado e quem está realmente chamando ele?"
• "O que está consumindo /backup? Me dê as maiores pastas e sinalize qualquer coisa que pareça logs descontrolados."
• "Qual host está com menos RAM agora e qual é o principal processo segurando ela?"
• "Quero reiniciar e fazer uma atualização do sistema operacional neste fim de semana — qual máquina precisa mais disso e qual é uma ordem segura considerando o que está rodando em cada uma?"

Somente leitura por design — não há ferramentas de escrita, então um agente pode olhar, mas nunca tocar na sua frota. Desligue a qualquer momento com ENABLE_MCP=0. Lista completa de ferramentas e configuração → Documentação do MCP.

Segurança

Este é um monitor de host: ele roda com acesso ao host, além de um socket Docker de leitura/escrita e um socket D-Bus (auto-atualização e os controles de iniciar/parar/reiniciar das abas Containers/Services estão ativados por padrão — defina ALLOW_SELF_UPDATE=0/ENABLE_CONTROLS=0, ou use docker-compose.readonly.yml, para restringir a monitoramento puro) e uma montagem raiz somente leitura — uma área de atuação ampla por design. O painel em si não tem login/autenticação — ele é feito para uma LAN confiável. Mantenha-o atrás da sua LAN/VPN/firewall e não o exponha à internet pública. Detalhes → documentação.

⭐ Apoie o projeto

Se o HomeLab Monitor economiza uma ou duas abas do navegador, uma ⭐ no GitHub genuinamente ajuda outros entusiastas de homelab a encontrá-lo. Obrigado!

💬 Comunidade

Construir isso é mais divertido juntos. Entre no Discord do HomeLab Monitor — diga oi, mostre seu setup, troque ideias, peça ajuda ou apenas fique por perto. É onde acontecem as conversas sobre o roadmap, perguntas de "devíamos construir X?" e ajuda rápida — e onde novos contribuidores recebem boas-vindas calorosas.

Traga um amigo, poste uma ideia, abra uma issue — vamos crescer uma comunidade de homelab amigável e saudável. 💛

Contribuindo

Issues e PRs são muito bem-vindos — especialmente novas sondas de servidores de modelo, novos monitores e back-ends de GPU. Esta é uma ferramenta de hobby feita para ajudar outros entusiastas de homelab, então seja gentil. Veja CONTRIBUTING.md.

Contribuidores

Obrigado a todos que abriram uma issue, enviaram um PR ou ajudaram a moldar o roadmap. Todo o back-end de GPU AMD — VRAM por processo via DRM fdinfo e paridade total de painel na v0.28.0, VRAM real em APUs de memória unificada na v0.26.0 — veio de @andreahaku. O registro de modelos ciente da frota da v0.27.0 e as janelas de manutenção da v0.23.0 vieram de @1HazyOne707. A energia RAPL de CPU/DRAM da v0.27.0 e o refatoramento do módulo backend/ da v0.24.0 vieram de @pehota. Veja o changelog para o registro completo e contínuo de créditos.

Licença

MIT — veja LICENSE.