Homelab Telemetry API (Proxmox)

This script creates a lightweight, zero-dependency REST API endpoint directly on your Proxmox host to expose real-time system metrics (CPU, RAM, Network I/O, ZFS, and VM counts).

1 - Configure your Variables

Before running, check your primary network interface and ZFS pool names. Find your active interface:

ip -br a

Find your ZFS pool (if using ZFS):

zpool list

Edit /opt/homelab-api.py and update the configuration block at the top of the file to match your setup:

PORT = 8080
IFACE = "vmbr0"
ENABLE_ZFS = True
ZPOOL = "rpool"

2 - Open the Firewall (If applicable)

If you are using the Proxmox Datacenter Firewall, you need to allow incoming TCP traffic on port 8080. (Note: If your host firewall is disabled on your local LAN, you can skip this step).

If using ufw on a standard Debian/Ubuntu host:

sudo ufw allow 8080/tcp

If using iptables:

sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT

3 - Enable and Start the Service

Ensure the script is executable and the systemd service is loaded:

sudo chmod +x /opt/homelab-api.py
sudo systemctl daemon-reload
sudo systemctl enable --now homelab-api.service

4 - Test the Endpoint

Test the call point by using curl from a different machine on your network to ensure the firewall is open and the script is returning data correctly:

curl http://<your-proxmox-ip>:8080/api/homelab

Expected Output:

{
  "cpu": 14.5,
  "ram": {"percent": 56.2, "used_gb": 18.0, "total_gb": 32.0},
  "rx_mb": 0.45,
  "tx_mb": 2.10,
  "load_avg": [0.45, 0.51, 0.49],
  "uptime_days": 14.2,
  "root_disk_pct": 34.1,
  "temp_c": 42.5,
  "zfs_pct": 61.2,
  "vms_running": 4,
  "lxcs_running": 6
}

This endpoint can now be seamlessly consumed by your Astro/Stellar frontend dashboard, or added to Uptime-Kuma as a standard JSON HTTP monitor!