"title":"Integraciones de Proxmox — Homepage, Home Assistant, Grafana, Prometheus | ProxMenux Monitor",
"description":"Guías copia-pega para conectar ProxMenux Monitor con los paneles de tu homelab: Homepage, Home Assistant, Grafana vía Prometheus, Uptime Kuma. Cada guía con la configuración exacta que esperan los paneles, los endpoints de la API usados y el patrón de cabecera de auth.",
"ogTitle":"Integraciones de Proxmox — Homepage, Home Assistant, Grafana, Prometheus",
"ogDescription":"Conjunto de guías para conectar ProxMenux Monitor con Homepage, Home Assistant, Grafana, Prometheus y Uptime Kuma.",
"twitterTitle":"Integraciones de Proxmox | ProxMenux Monitor",
"twitterDescription":"Guías para Homepage, Home Assistant, Grafana, Prometheus y Uptime Kuma."
},
"header":{
"title":"Integraciones",
"description":"Guías copia-pega para conectar ProxMenux Monitor en los paneles y herramientas que tu homelab ya usa — Homepage, Home Assistant, Grafana vía Prometheus, Uptime Kuma. Cada guía muestra la configuración exacta que espera la herramienta receptora, el endpoint del Monitor con el que habla y el patrón de cabecera de auth que lo une todo.",
"body":"Copia cada ejemplo en la herramienta correspondiente. Los endpoints están documentados en la <link>Referencia de la API</link>; esta página explica cómo utilizarlos en Homepage, Home Assistant y Grafana. Las capturas muestran el resultado de esas configuraciones."
"optAbody1":"Entra en <strong>Ajustes → Seguridad → Tokens API</strong>. Pulsa <em>Generar token</em>, ponle un nombre, como <em>homepage</em>, <em>home-assistant</em> o <em>prometheus</em>, y cópialo: se muestra <em>una sola vez</em>. Caduca al año por defecto y puede revocarse individualmente. Úsalo para los clientes externos al navegador.",
"optAbody2":"A partir de ahí cada petición es simplemente:",
"optBtitle":"Opción B — flujo de login (usuario + contraseña)",
"optBbody":"Útil para scripts que se autentican como un usuario humano. El token devuelto es de corta duración; la mayoría de integraciones deberían preferir la Opción A.",
"outro":"El campo TOTP solo hace falta con la autenticación en dos pasos activada. La rotación y revocación de tokens, la política de contraseñas y el registro de auditoría se explican en <link>Acceso y autenticación</link>.",
"httpsIntro":"Cada guía de abajo usa <code>http://</code> en las URLs para mantener los ejemplos cortos. Si has activado TLS en el Monitor (<strong>Settings → Security → SSL/HTTPS</strong>), cambia <code>http://</code> por <code>https://</code> en cada URL — ese es el único cambio. Dos notas específicas para ciertas herramientas:",
"httpsItems":[
"<strong>Certificados autofirmados.</strong> La integración <code>rest:</code> de Home Assistant verifica TLS por defecto. Si el Monitor está usando su propio cert autofirmado, añade <code>verify_ssl: false</code> a cada bloque REST (junto a <code>scan_interval:</code>), o importa la CA del Monitor al trust store de HA. Lo mismo para cualquier herramienta que rechace certs no confiables.",
"<strong>Prometheus</strong> ya tiene <code>scheme: https</code> listo en la configuración de scrape de abajo; descomenta / déjalo como <code>https</code> si TLS está activado en el Monitor."
]
},
"homepage":{
"heading":"Homepage",
"headingHref":"https://gethomepage.dev",
"intro":"Homepage es un panel de aplicaciones totalmente estático y personalizable. ProxMenux Monitor se enchufa vía el widget <code>customapi</code> integrado — pega una entrada de servicio en <code>services.yaml</code>, reinicia Homepage y la tarjeta aparece con números en vivo.",
"iconCalloutTitle":"El logo oficial de ProxMenux está en dashboardicons.com",
"iconCalloutBody":"Las guías de abajo usan <code>icon: proxmenux.png</code>. Homepage resuelve automáticamente los nombres de archivo simples contra <a1>dashboardicons.com</a1> — una librería de iconos curada para paneles autoalojados. La entrada de ProxMenux vive en <a2>dashboardicons.com/icons/external/proxmenux</a2> y Homepage la descarga en el primer render. La misma búsqueda funciona para miles de otras herramientas (Telegram, Discord, Grafana, Tailscale, etc.) — basta con escribir <code>icon: <name>.png</code> en cualquier entrada de servicio.",
"imageAlt":"Panel Homepage mostrando tres tarjetas de ProxMenux Monitor (EDGE, VOID, DREAM) con uptime, CPU, RAM y temperatura para cada host Proxmox",
"imageCaption":"Tres instancias de ProxMenux Monitor renderizadas como tarjetas Homepage — uptime, CPU, RAM y temperatura de CPU leídas en vivo desde <code>/api/system</code> en cada host cada 10 s.",
"basicTitle":"Widget básico — sin autenticación",
"basicIntro":"Usa esto cuando ProxMenux Monitor esté en una red de confianza y aún no hayas activado la autenticación en el lado del Monitor. La entrada más simple posible en <code>services.yaml</code>:",
"authedTitle":"Widget autenticado",
"authedIntro":"Genera un API token en <strong>Settings → Security → API Tokens</strong> en el Monitor, cópialo y pégalo en la cabecera <code>Authorization</code> de abajo — reemplaza el token de ejemplo mostrado tras <code>Bearer</code> con el que acabas de copiar:",
"authedOutro":"Reinicia Homepage y la tarjeta se enciende con valores en vivo. Reutiliza el mismo token en todos los widgets Homepage que apunten al mismo host de ProxMenux Monitor.",
"multiTitle":"Setup multi-widget — sistema, almacenamiento, red",
"multiIntro":"Para una vista más rica, renderiza tres tarjetas separadas respaldadas por distintos endpoints — una para métricas del sistema, una para almacenamiento, una para red. Usa el mismo token en cada tarjeta; es la misma instancia del Monitor.",
"multiCalloutBody":"Repite el bloque para cada host y obtendrás las tarjetas de la captura. Cada entrada usa la URL <code>http://<host>:8008</code> de su propia instancia. Genera y guarda un token por host: cada instalación tiene su clave de firma y no debes asumir que el token de otra funcione."
"intro":"Estos ejemplos usan la integración <code>rest</code> de Home Assistant y no necesitan un componente HACS propio. Leen endpoints del Monitor descritos en la <link>Referencia de la API</link> y convierten sus respuestas en sensores y atributos para automatizaciones. La configuración ofrece unos 25 sensores de recursos, salud, VMs/CTs, almacenamiento, red y actualizaciones. Añádela a <code>configuration.yaml</code> y recarga o reinicia HA.",
"imageAlt":"Panel Home Assistant mostrando entidades de ProxMenux Monitor — badge de estado de salud, gauges de CPU / RAM / Temp, contador de VMs, uso de almacenamiento y contador de errores activos",
"imageCaption":"ProxMenux Monitor como integración de primera clase en Home Assistant — sensores construidos desde la guía YAML de abajo.",
"step1Body":"Guarda el token en <code>secrets.yaml</code> para separarlo de la configuración principal. Incluye el prefijo Bearer y el token en un único valor para usarlo como cabecera. El archivo no está cifrado y también debe mantenerse privado. Su ubicación depende de la instalación; normalmente es <code>/config/secrets.yaml</code> en HA OS o Container.",
"step2Body":"Seis bloques REST cubren toda la superficie — uno por área principal del Monitor. Cada bloque tiene un <code>scan_interval</code> sensato ajustado a cuán a menudo cambian los datos subyacentes (recursos del sistema cada 30 s, salud cada 60 s, inventarios que cambian despacio cada 5-10 min). Pega en <code>configuration.yaml</code>:",
"step3Title":"3 · Añade sensores binarios y helpers de template",
"step3Body":"Dos sensores binarios y un par de sensores template redondean la integración — hacen que las automatizaciones y las tarjetas condicionales de Lovelace queden mucho más limpias que encadenar Jinja en cada sitio.",
"step4Title":"4 · Recarga y verifica",
"step4Body":"Desde la UI de HA: <em>Developer Tools → YAML → Check Configuration</em> primero para validar la sintaxis, luego recarga <em>All YAML configuration</em> (o reinicia completo). Después de que vuelva, filtra <em>Settings → Devices & Services → Entities</em> por <em>proxmenux</em> — deberías ver las ~25 entidades llenándose dentro de un intervalo de scan.",
"replaceTitle":"¿Reemplazando una versión anterior de esta guía?",
"replaceBody":"Si usaste una versión anterior, el registro de entidades puede conservar IDs obsoletos y las tarjetas mostrar <em>Entidad no encontrada</em>. Quita los bloques anteriores <code>rest:</code> y <code>template:</code> de <code>configuration.yaml</code> y recarga. En <em>Ajustes → Dispositivos y servicios → Entidades</em>, filtra por <em>proxmenux</em> y elimina las entradas antiguas restauradas o no disponibles. Añade después el YAML actual y recarga para registrar las nuevas.",
"step5Body":"El YAML de abajo es una única tarjeta <strong>vertical-stack</strong> que combina todas las sub-tarjetas en un bloque — cabecera con logo, KPIs rápidos, detalle del sistema, VMs, almacenamiento, red y una tarjeta condicional de problemas de salud. Para usarla: abre tu panel, pulsa el lápiz (editar), pulsa <em>Add card</em>, baja al final y elige <em>Manual</em>, luego pega:",
"viewTipTitle":"¿Lo quieres como vista completa de panel en lugar de una sola tarjeta?",
"viewTipBody":"Abre el menú de 3 puntos del panel → <em>Raw configuration editor</em> y añade una vista nueva con esta cabecera (encima de la lista <code>cards:</code> del YAML de arriba):",
"viewTipOutro":"Eso te da una pestaña/vista dedicada en tu panel con su propio icono y título, en vez de una tarjeta larga en una vista existente.",
"altViewTitle":"Alternativa — una vista de panel dedicada",
"altViewIntro":"Para crear una pestaña propia dentro de un panel existente, añade una vista con el YAML de abajo. Una vista es una pestaña del panel; no crea una entrada nueva en la barra lateral. Pasos:",
"twoEditorsTitle":"Dos editores YAML en HA — elige el correcto",
"twoEditorsIntro":"Home Assistant tiene dos editores YAML que parecen similares pero esperan formatos distintos:",
"twoEditorsItems":[
"<strong>Editor de una sola vista</strong> (esta guía) — abierto desde la pestaña <em>+</em> o desde <em>Edit view → Code editor</em>. Espera el cuerpo de una vista directamente: <code>title:</code>, <code>path:</code>, <code>cards:</code> al top level, sin guion inicial.",
"<strong>Editor Raw del panel entero</strong> — abierto desde el menú de 3 puntos del panel. Espera la lista <code>views:</code> entera, con cada vista como item de lista (<code>-</code> inicial)."
],
"twoEditorsOutro":"Pegar YAML de cuerpo de vista en el editor de panel entero (o viceversa) te deja con una <em>Vista sin nombre</em> y <code>cards: []</code>. El YAML de abajo es para el editor de una sola vista — pega exactamente como se muestra.",
"viewImageAlt":"Vista dedicada de Home Assistant renderizando ProxMenux Monitor — cabecera picture-entity, KPIs glance y tarjetas de entidad Sistema / VMs / Almacenamiento / Red distribuidas automáticamente por HA en múltiples columnas",
"viewImageCaption":"La vista <em>ProxMenux Monitor</em> en pantalla ancha. La disposición Masonry distribuye las tarjetas automáticamente en columnas; el resultado depende del tipo de vista configurado.",
"twoColTipTitle":"¿Quieres un layout fijo de dos columnas en lugar del auto layout?",
"twoColTipBody":"Reemplaza cualquier par de tarjetas (p. ej. <em>Sistema</em> + <em>VMs</em>, o <em>Almacenamiento</em> + <em>Red</em>) con un único <code>horizontal-stack</code> envolviendo ambas, para que siempre se rendericen lado a lado independientemente del ancho de pantalla:",
"twoColTipOutro":"En móvil la fila se mantiene comprimida; el auto layout de HA (sin horizontal-stack) refluye mejor a anchos estrechos.",
"step6Body":"Tres automatizaciones que cubren los escenarios reactivos más comunes — reemplaza <code>notify.mobile_app_<your_phone></code> por el servicio notify que uses:",
"logoBody":"La tarjeta picture-entity en la parte superior del YAML Lovelace descarga el logo oficial de ProxMenux desde <a1>dashboardicons.com</a1> — una librería de iconos gratuita curada para paneles autoalojados. La entrada de ProxMenux vive en <a2>dashboardicons.com/icons/external/proxmenux</a2>. Home Assistant descarga el SVG sobre HTTPS en el primer render y lo cachea.",
"logoBrokenTitle":"Si la tarjeta del logo muestra una imagen rota",
"logoBrokenIntro":"Algunas instalaciones de HA (redes con firewall, bloqueadores de contenido, hosts sin internet pública) no pueden alcanzar jsdelivr.net en el momento del render. El arreglo es una copia local:",
"logoBrokenSteps":[
"Descarga el SVG desde <a>cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/proxmenux.svg</a>.",
"Guárdalo en <code>/config/www/icons/proxmenux.svg</code> en tu host HA.",
"En el YAML Lovelace, reemplaza la URL <code>image:</code> por <code>/local/icons/proxmenux.svg</code>. Guarda y recarga — la imagen se renderiza desde el archivo local, sin internet necesaria."
],
"scanTipTitle":"Regla práctica para scan_interval",
"scanTipBody":"Un punto de partida razonable es consultar <code>/api/system</code> cada 30 s. <code>/api/health/full</code> suele leer datos en caché válidos hasta seis minutos; consultarlo cada 60 s no evita esa caché. Prueba cinco minutos para <code>/api/storage/summary</code> y una hora para <code>/api/proxmenux/update-status</code>. Ajusta los intervalos a tu hardware y número de hosts."
"intro":"ProxMenux Monitor expone <code>GET /api/prometheus</code> con formato de exposición de texto Prometheus 0.0.4. Necesita un token Bearer si la autenticación está activada. Configura Prometheus para recoger las métricas y Grafana para visualizar la base de datos de series temporales.",
"imageAlt":"Panel Grafana renderizando métricas de ProxMenux Monitor — gauge de uso de CPU, timeseries de uso de memoria, contador de VMs en ejecución, throughput de red",
"imageCaption":"Un panel Grafana básico construido desde el scrape Prometheus de ProxMenux — CPU, memoria, VMs en ejecución, throughput de red. El catálogo completo de métricas vive en la <link>API Reference → Métricas Prometheus</link>.",
"step1Title":"1 · Añade el job de scrape a Prometheus",
"step1Body":"Pasa el API token vía el bloque nativo <code>authorization</code> de Prometheus (más limpio que cabeceras personalizadas y funciona con secret stores):",
"step1After":"Recarga Prometheus con <code>kill -HUP <PID></code> (sustituye PID por su ID de proceso), <code>systemctl reload prometheus</code> si el servicio lo permite o <code>docker compose restart prometheus</code> para el contenedor. Revisa <em>Status → Targets</em>: el job proxmenux debería pasar a UP en un intervalo de recogida. Las métricas llevan <code>node=\"<hostname>\"</code> para distinguir los hosts.",
"tokenTipTitle":"Guarda el token en un archivo separado",
"tokenTipBody":"Para despliegues en producción evita poner el token inline. Prometheus soporta <code>credentials_file: /etc/prometheus/secrets/proxmenux.token</code> como alternativa — guarda el token en un archivo 0600 y deja que Prometheus lo lea.",
"step2Title":"2 · Verifica el scrape con un par de queries",
"step2Body":"Antes de configurar Grafana, confirma que Prometheus realmente tiene los datos. Abre la propia UI de Prometheus en <code>http://<prometheus-host>:9090</code>, pulsa <em>Query</em> y ejecuta cualquiera de estas — deberías obtener números en vivo de tu host Proxmox:",
"confirms":"Devuelve <code>1</code> si Prometheus recoge datos del Monitor correctamente y <code>0</code> si falla. Es la comprobación inicial más rápida."
"calloutBody":"Con la autenticación activa, al pulsar el enlace en <em>Status → Targets</em> el navegador consulta <code>/api/prometheus</code> sin la cabecera Bearer de Prometheus. Puede responder <code>'{'\"error\":\"Authentication required\"'}'</code>. Comprueba el <em>State: UP</em> del destino para confirmar que Prometheus recoge los datos con su token.",
"step3Body":"En Grafana, abre <em>Connections → Data sources → Add new → Prometheus</em>. Indica la URL de Prometheus, por ejemplo <code>http://prometheus.lan:9090</code>, guarda y prueba. Si tu servidor Prometheus exige autenticación, configúrala aquí por separado. El token del Monitor pertenece al job de recogida de Prometheus.",
"outro":"Añade cada query como un panel Grafana, configura la visualización adecuada (<em>Stat</em> para gauges, <em>Time series</em> para tendencias) y agrupa paneles en filas por categoría. Usa la etiqueta <code>node</code> como variable de panel (<em>Settings → Variables → New → Query → label_values(proxmox_cpu_usage, node)</em>) para filtrar todos los paneles por host."
"intro":"Para comprobar una palabra clave, usa <code>GET /api/system-info</code>. Esta ruta no exige token y devuelve nombre del host, tiempo de actividad y salud como <code>healthy</code>, <code>warning</code> o <code>critical</code>. Es una comprobación pública, a diferencia de los endpoints detallados protegidos.",
"kumaTitle":"Uptime Kuma — Monitor HTTP de palabras clave",
"healthchecksBody":"Un trabajo cron puede consultar <code>/api/system-info</code> y comprobar <code>.health.status == \"healthy\"</code>. Solo si supera la prueba debe enviar un ping de éxito a la URL única de Healthchecks.io. Ese servicio recibe pings de los trabajos; no consulta el Monitor. Un HTTP 2xx por sí solo no demuestra buena salud del host.",
"richBody":"Para el estado completo —diez categorías de salud, errores activos y descartados— usa <code>GET /api/health/full</code>. Devuelve los datos de la ventana del panel en una respuesta y necesita un token Bearer si la autenticación está activada."
"intro":"Las herramientas de workflow y scripts pueden <em>enviar</em> notificaciones con un POST a <code>/api/notifications/send</code>, por ejemplo por un fallo de CI o un trabajo cron demasiado largo. Es un envío directo: omite la cola y la espera entre huellas de eventos. Conserva el formato por canal, la IA opcional y la entrega a los canales configurados. Controla los duplicados desde quien llama.",
"n8nBody":"En n8n, usa un nodo <em>HTTP Request</em> con POST, la URL anterior y el mismo JSON que curl. Elige credenciales genéricas Header Auth: nombre <em>Authorization</em> y valor <code>Bearer YOUR_API_TOKEN</code>, sustituyendo el marcador. Conecta una programación, webhook u otro nodo para disparar la petición.",
"severityBody":"La gravedad usa <code>INFO</code>, <code>WARNING</code> o <code>CRITICAL</code> en mayúsculas. El objeto <code>data</code> aporta contexto del evento y campos de plantilla. En este endpoint, la IA solo recibe el título y el mensaje; los campos de <code>data</code> no se envían al proveedor. Consulta <link>Notificaciones → Catálogo de eventos</link>."
"intro1":"El sistema de notificaciones llegó en PVE 8.1; los destinos webhook nativos requieren Proxmox VE 8.3 o posterior. <em>Activar notificaciones</em> en Ajustes intenta registrar el Monitor como destino. Los avisos que PVE enruta allí, como informes de backups o replicación, entran en su flujo de envío. El alta depende de que la configuración esté disponible y permita escritura.",
"intro2":"La mecánica, la plantilla de body que PVE envía, las entradas escritas en <code>/etc/pve/notifications.cfg</code> y el comportamiento en clusters están documentados en <link>Notifications → Integración del webhook de PVE</link>."
