proxmox-monitor/README.md

Proxmox Monitor

A real-time dashboard for monitoring Proxmox VE nodes, VMs, and LXC containers.

Features

• Node overview — CPU, memory, uptime, and load for each Proxmox node, grouped into collapsible cards
• VM & LXC tracking — status, resource usage across all nodes
• Summary cards — total nodes, running/stopped VMs, aggregate memory
• Per-VM/LXC IP addresses — IPv4 from guest agent (QEMU) or network config (LXC), displayed below VM/LXC name
• Power control — Start/stop/restart buttons per row
• Console links — Opens Proxmox web UI console in a new tab
• Search / filter — Client-side filtering by name, node, or status with auto-expand
• Group by node — Collapsible node cards with running/stopped subtotals
• Manual refresh — Button in header to refresh all data
• Custom poll interval — Adjustable polling interval (default 30s) via header input
• Uptime display — Formatted as "Xd Yh Zm"
• Auto-refresh — Manual setInterval polling every 30s (configurable)

Tech Stack

• Framework — Next.js 15 (App Router)
• UI — React 19, Tailwind CSS 4
• Data fetching — Axios with manual setInterval polling
• Proxmox — API2 Token-based auth

Getting Started

1. Configure environment variables

Copy the example file and fill in your Proxmox credentials:

cp .env.example .env.local

.env.local contents:

PROXMOX_API_URL=https://your-proxmox-host:8006/api2/json
PROXMOX_TOKEN_ID=root@pam!token-name
PROXMOX_TOKEN_SECRET=<your-token-secret>
API_POLL_INTERVAL=30000
NODE_TLS_REJECT_UNAUTHORIZED=0

Creating an API token in Proxmox: Datacenter > Permissions > API Tokens

2. Install dependencies

npm install

3. Run the development server

npm run dev

Open http://localhost:3000 in your browser.

4. Build for production

npm run build
npm start

Project Structure

src/
├── app/
│   ├── api/
│   │   ├── nodes/route.js   # Proxmox node stats
│   │   ├── vms/route.js     # QEMU VMs across all nodes
│   │   ├── lxc/route.js     # LXC containers across all nodes
│   │   ├── status/route.js  # Aggregated summary
│   │   ├── power/route.js   # Power control endpoint
│   │   └── proxy/[...]/     # Reverse proxy to Proxmox web UI
│   ├── layout.js
│   └── page.js
├── components/
│   ├── Dashboard.js          # Main dashboard with tabs, summary, polling
│   ├── NodeList.js           # Node overview
│   ├── NodeCard.js           # Single node card
│   ├── VMList.js             # VM list with group by node, filter, power actions
│   ├── LXCList.js            # LXC list with group by node, filter, power actions
│   └── StatusBadge.js        # Status indicator
└── lib/
    └── proxmox.js            # Proxmox API client — nodes, VMs, LXC, IPs, power control

Environment Variables

Variable	Required	Description
PROXMOX_API_URL	Yes	Base URL of the Proxmox API (e.g. https://host:8006/api2/json)
PROXMOX_TOKEN_ID	Yes	API token ID (e.g. root@pam!monitorapp)
PROXMOX_TOKEN_SECRET	Yes	API token secret
PROXMOX_WEB_URL	No	Web UI URL (defaults from PROXMOX_API_URL). Used for console links.
API_POLL_INTERVAL	No	Refresh interval in ms (default: 30000)
NODE_TLS_REJECT_UNAUTHORIZED	No	Set to 0 for self-signed certs

API Routes

Route	Method	Description
/api/nodes	GET	All Proxmox nodes
/api/vms	GET	All QEMU VMs (with IPv4 from guest agent)
/api/lxc	GET	All LXC containers (with IPv4 from interfaces/config)
/api/status	GET	Aggregated summary stats
/api/power	POST	Power control (start/stop/restart)
/api/proxy/*	GET	Reverse proxy to Proxmox web UI

Per-VM/LXC IP Addresses

• QEMU VMs: fetched from /nodes/<node>/qemu/<id>/agent/network-get-interfaces (requires QEMU guest agent installed)
• LXC: fetched from /nodes/<node>/lxc/<id>/interfaces (preferred) or parsed from /config net0-net7 fields (fallback)
• IPv4 only — IPv6 addresses are excluded