ProxMenux Monitor

What the dashboard covers

Eight first-class sections, each backed by its own API endpoints:

Every section has a dedicated documentation page under Dashboard in the sidebar.

How it runs

ProxMenux Monitor ships as a self-contained AppImage. A single systemd unit (proxmenux-monitor.service) starts a Flask process that:

• Listens on TCP 8008 on the host (HTTP).
• Serves the Next.js dashboard as static assets under / and the API under /api/* from the same process.
• Pulls live data with standard host tools: psutil, pvesh, smartctl, journalctl, zpool, ip, nvidia-smi, etc.
• Persists its own state in a local SQLite database (/usr/local/share/proxmenux/health_monitor.db): dismissed alerts, disk observations, notification config, AI config. Authentication state lives separately in /root/.config/proxmenux-monitor/auth.json.

The full request flow, file layout and the systemd integration are described in Architecture.

Accessing the dashboard

Two access patterns are supported and the application detects which one is in use:

# 1) Direct access on the host
http://<your-proxmox-ip>:8008

# 2) Via reverse proxy (Nginx / Caddy / Traefik)
https://<your-domain>/proxmenux-monitor/

When fronted by a reverse proxy, the Monitor honours X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host so URLs and CORS behave correctly without manual configuration.

First-launch setup, password + TOTP 2FA, and reverse-proxy snippets are covered in Access & Authentication.

Mobile use and home-screen install

The dashboard is responsive and ships as a Progressive Web App. The packaged public/manifest.json declares display: standalone with an app name, icon and theme colour, so adding the URL to the home screen produces a real standalone launcher — no browser address bar, custom splash, dark theme matched to the dashboard.

Add to home screen

• iOS Safari: share button → Add to Home Screen. The icon comes from /apple-touch-icon.png shipped in the AppImage.
• Android Chrome / Edge: three-dot menu → Install app (or Add to Home screen on older versions).
• Once installed, opening the icon launches the dashboard in standalone mode with its own task switcher entry.

Online-only

The PWA is installable but it is not offline-capable — there is no service worker. The launcher behaves like a native app, but the device still needs to reach the host on TCP 8008 (LAN, VPN or reverse-proxied HTTPS) for the dashboard to load.

The Health Monitor and notifications

Inside the dashboard, the Health Monitor runs continuously in the background and produces a structured stream of events: high CPU temperature, disk SMART warnings, ZFS pool degradation, OOM kills, VM/CT failures, security incidents, and so on. Each event has a category, a severity (INFO / WARNING / CRITICAL) and a stable error_key so duplicates collapse instead of flooding the screen.

Events feed three things at the same time:

• The Health Monitor view in the dashboard (active + dismissed lists).
• The notification engine — Telegram, Discord, Email, Gotify and Apprise (multi-channel). Each channel is configured independently and per-event categories can be silenced.
• The optional AI assistant — when enabled, the configured provider (OpenAI, Anthropic, Gemini, Groq, Ollama or OpenRouter) explains incoming events in plain language and, if enabled in the AI settings, proposes next steps.

REST API and integrations

Everything the UI shows is available as JSON over HTTP/HTTPS. The same endpoints power Homepage widgets, Home Assistant sensors, Grafana dashboards (via the Prometheus exporter at /api/prometheus), Uptime Kuma probes and any custom script that speaks curl.

• Long-lived API tokens (365 days) are generated from Settings → API Access Tokens or via POST /api/auth/generate-api-token.
• Tokens travel as Authorization: Bearer …. Public endpoints (/api/health, /api/auth/*) work without a token so external uptime probes can hit the host without handing out credentials.
• The full endpoint catalog, token rotation guidance and security best-practices live in API Reference; ready-made examples for Homepage, Home Assistant, Grafana, Uptime Kuma and a generic cURL pattern are in Integrations.

Service control

Day-to-day, the Monitor is managed exactly like any other systemd service. It is also exposed as two entries inside the ProxMenux TUI under Settings:

# Manual control
systemctl status proxmenux-monitor.service
systemctl is-active proxmenux-monitor.service
systemctl enable --now proxmenux-monitor.service
systemctl disable --now proxmenux-monitor.service
journalctl -u proxmenux-monitor.service -f

See Settings → ProxMenux Monitor for the in-menu toggle and status verification flow.

Where to next

• Architecture — Flask backend, systemd unit, SQLite schema, AI providers, notification channels.
• Access & Authentication — first launch, password setup, TOTP 2FA, reverse-proxy configuration, Fail2Ban integration.
• Dashboard — every section of the UI, one page each.
• API Reference — every endpoint, request / response shape and token management.
• Integrations — Homepage, Home Assistant, Grafana / Prometheus, Uptime Kuma, generic cURL pattern.