rgcosta
3f8e8f545a
By using Python's threading library and a deque (a highly efficient rolling array). A background thread will wake up every 1 second, take a snapshot, and push it into the array. When your website hits the API, it just grabs whatever is currently in the arrays.
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!