Proxmon: A Simple TUI to Monitor and Manage Your Proxmox Cluster

If you’re running a Proxmox VE cluster in your homelab or production environment — or if you’re reading this, you probably are (or planning to) — you already know how powerful the platform is. Proxmox offers excellent tools like pvesh, qm, and a solid web interface for managing your virtual machines and containers.

However, I always found myself wishing for something more native to my work style—a proper CLI tool that lets me manage everything directly from the terminal without constantly reaching for the mouse.

That’s precisely why I built Proxmon — a TUI (Text User Interface) powered by Python, Rich, and Textual that makes it effortless to monitor and manage Proxmox VMs and LXCs directly from your terminal. No more jumping between browser tabs, parsing JSON frompvesh, or writing custom bash scripts. Proxmon gives you a polished, real-time view of your infrastructure where you need it.

🚀 What is Proxmon?

Proxmon is a Python-based TUI that interfaces with the Proxmox API to give you a powerful and elegant way to:

• View real-time metrics of all VMs and containers
• Start, stop instances
• Navigate across nodes, types (VM or LXC), and statuses
• Run the whole thing inside your terminal — perfect for SSH sessions and headless setups

Think htop, but for Proxmox.

Thanks to Rich and Textual, the UI is modern, responsive, and visually appealing — with live-updating metrics, colored status indicators, and intuitive keybindings.

🎨 UI Walkthrough

Here’s what you get when you launch Proxmon:

• Live Dashboard: A constantly updating table of your VMs and containers, with stats like CPU%, memory usage, and uptime.
• Color-Coded Status: Instantly spot running, stopped machines at a glance.
• Command Palette: Quickly start and stop machines with keyboard shortcuts.

🛠️Features at a Glance

The features available currently on Proxmon:

✅ Live metrics: Real-time CPU, memory, disk usage stats

✅ VM/LXC management: Start, stop, reboot actions via keyboard

✅ API-powered: All data comes from the Proxmox API

✅ Built with Rich/Textual: Clean, modern terminal UI

✅ Lightweight & fast: Perfect for low-resource servers and headless environments

🐍 Under the Hood: The Tech Stack

Proxmon is written entirely in Python, and leverages:

• Rich for elegant, styled console output
• Textual for building the interactive TUI components
• Proxmox API for pulling in data and performing actions
• A config (more precisely, ENV) file for authentication and node info

⚡ Getting Started

Step 1: Clone the Repo

git clone https://github.com/Sr-vZ/Proxmon.git
cd Proxmon

Step 2: Install Dependencies

I recommend using a virtual environment:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Step 3: Configure Access

Create a .env file with your Proxmox API credentials:

PROXMOX_HOST='https://<PROXMOX-IP>:8006'
# generate API keys from UI
TOKEN_ID='<token-id'
TOKEN_SECRET='<token-secret>'
# pve is default
NODE ='<node-name>'
# SSH is required to run some commands 
# which is not possible via Proxmox API
SSH_HOST= '<PROXMOX-IP>'
SSH_USER='<admin-user>'
SSH_PASSWORD='<admin-user-password>'
# Mention different port if not using default
SSH_PORT='22'
# if want to use keys instead of User/Pass
SSH_KEY='<ssh-key>'

Step 4: Launch the App

python proxmon.py

🗺️Roadmap

Proxmon is still evolving. Some upcoming features I’m exploring:

• 🔐 SSH passthrough: Launch a shell directly into your VM/LXC
• 🧱 VM/LXC creation: Create machines directly from the CLI
• 📦 PyPI packaging: Install with a simple pip install proxmon

If you want to contribute, feel free to star the repo, fork it, or open an issue.

If you enjoyed this article and want to support what I’m building, feel free to follow me here on Medium, subscribe to my newsletter, or connect with me on Twitter for more updates.

If Proxmon made your homelab life a little easier and you’d like to show some love, you can always buy me a coffee — every bit helps fuel future projects like this one ☕🚀