📱 ProxPad - Proxmox Control Center & Macro Pad

Turn your old iPad/Android tablet/phone into a dedicated Proxmox Control Center and macro pad! 📱⚡

ProxPad is a web-based Stream Deck that puts your entire Proxmox infrastructure at your fingertips. Designed with mobile-first usability, it delivers seamless VM management, macro automation, and media control - all from a touch-optimized interface that works anywhere!

✨ Why ProxPad? Practical Benefits

📱 Device Reuse: Turn your old iPad/Android tablet/phone into a dedicated Proxmox Control Center and macro pad

⚡ Real-Time Updates: Live VM status with instant auto-refresh. Always know what's running

🎯 Smart Resource Management: Hides VMs that share the same resources. Prevents running 2 VMs with the same GPU/SSD/etc

🎮 Macro Automation: Execute macros, launch apps, control media - all with one tap

📳 Haptic Feedback: Vibration feedback on button press (configurable)

🎨 GIF Support: Animated buttons for a dynamic interface

📸 See It In Action!

Mobile Experience - Clean Interface! Your entire Proxmox fleet, beautifully organized

One-tap macro execution - convenient control

Media control features, integrated with the interface

🛠️ Architecture - Elegantly Simple

🖥️ Server Component (`proxpad.py`)

Runs on your Proxmox server or LXC container
Serves the stunning web interface
Handles all VM management via Proxmox API
Centralized configuration in config.py

📱 Client Component (`macro_handler.py`)

Ultra-lightweight Python script
Cross-platform: Windows & Linux support
Minimal dependencies: pynput + optional uinput
Listens for UDP commands and executes locally

🚀 Feature Showcase - What ProxPad Offers

Feature	What It Does	Practical Benefit
📱 Mobile-Optimized	Touch-first responsive design	Use it anywhere, anytime
🔄 Live Updates	Real-time VM status monitoring	Always know what's running
⚡ Quick Actions	One-tap Start/Stop/Reboot/Shutdown	Control VMs instantly
🎯 Smart Resources	Auto-hide conflicting VMs	No more hardware conflicts
🎮 Macro Pages	Customizable macro buttons	Automate tasks efficiently
🎨 GIF Icons	Animated button support	Dynamic visual interface
🎵 Media Control	Integrated media player controls	Complete media hub
📳 Haptic Feedback	Vibration feedback on button press	Configurable user feedback
🔒 Secure API	Proxmox token authentication	Secure access
🛠️ Easy Setup	Automated install scripts	Running in minutes

🎯 Quick Start - Get Running in 5 Minutes!

1️⃣ Clone & Install

git clone https://github.com/Yury-MonZon/ProxPad.git
cd ProxPad

# Server dependencies (Proxmox/LXC)
./install_deps_debian.sh  # or install_debs_cachyos.sh

# Client dependencies (VMs)
pip install pynput

2️⃣ Configure Proxmox API

Log into Proxmox → Datacenter → Permissions → API Tokens
Create token: root@pam!ProxPad
CRITICAL: Disable "Privilege Separation"

3️⃣ Setup Config

# config.py
PROXMOX_HOST = "your-proxmox-ip"
PROXMOX_TOKEN_ID = "root@pam!ProxPad"
PROXMOX_TOKEN_SECRET = "your-secret-token"
VM_IDS = [101, 102, 103, 104]
SAME_RESOURCES = [[101, 102], [103, 104]]  # Conflict groups

4️⃣ Launch & Go!

python proxpad.py
# Visit: http://your-ip:5000

🎮 Macro Commands - Available Actions

Create powerful macros with these commands:

Command	Example	What It Does
Key Press	`key:win+l`	Lock screen
Execute	`exe:calc`	Open calculator
Type Text	`type:Hello World`	Type text
Delay	`delay:0.5`	Wait 0.5 seconds
Open URL	`url:https://google.com`	Open browser
Chain Commands	`key:win; delay:0.1; type:calc; key:enter`	Complex sequences

🎨 Color Editor - Customize Your Macro Buttons

ProxPad includes a standalone color editor (color_editor.py) for customizing macro button colors with a live preview.

Quick Start

python color_editor.py
# Visit: http://localhost:9999

Features

Live Preview: Colors update in real-time, no Apply button needed
Custom Color Picker: Built from scratch — no external dependencies
- Saturation/Value square
- Hue rainbow slider
- R/G/B sliders with numeric input
- Hex input with live sync
Randomize: Per-button random color (bright, saturated range)
Save to Config: Writes changes directly back to config.py with proper formatting

How It Works

Reads config.py in the same directory and extracts all PAGE#_MACROS, PAGE#_MACRO_ROWS, and PAGE#_MACRO_COLS definitions
Each page renders as a grid of buttons matching your configured rows × columns
Click a button to open the per-cell color picker
"Save to Config"

🔔 Popup Notifications - Send Alerts to Your Display

Send on-screen popup messages to the ProxPad web interface with text, icons, and optional persistent display.

SSH Script (`proxpad-popup.sh`)

# Basic popup, auto-dismiss after 10s
proxpad-popup.sh -t "Backup complete"

# Persistent popup with custom icon
proxpad-popup.sh -t "VM started" -i play-circle-fill -k

# Image URL as icon
proxpad-popup.sh -t "Alert!" -i "https://example.com/warning.png" -k

# From another machine via SSH
ssh user@proxpad-host ./proxpad-popup.sh -t "Server is down!" -i exclamation-triangle -k

# Custom host
proxpad-popup.sh -t "Hello" -u 192.168.1.100

Options

Flag	Description	Default
`-t TEXT`	Message text (supports HTML: `<b>`, `<br>`, etc.)	required
`-i ICON`	Bootstrap icon name or image URL	`info-circle`
`-k`	Keep popup until user taps (otherwise auto-dismiss after 10s)	off
`-u HOST`	ProxPad server host/IP	`localhost`

Python API

def send_popup(text, icon="info-circle", keep=False, host="192.168.1.250", port=5000):
    import json, urllib.request
    data = json.dumps({"text": text, "icon": icon, "keep": keep}).encode()
    req = urllib.request.Request(f"http://{host}:{port}/api/popup", data=data,
                                 headers={"Content-Type": "application/json"})
    with urllib.request.urlopen(req) as resp:
        return json.loads(resp.read())

send_popup("Backup done", "check-circle", keep=True)

Pre-made Scripts

./send_tg_msg.sh "New message from Telegram"       # telegram icon
./send_warning_msg.sh "Something went wrong!"        # warning icon
./send_slack_msg.sh "Deploy complete"               # slack icon

🐧 Linux Support - The uinput Advantage!

Why uinput is useful:

✅ Reliable: All key combos work perfectly (including Super/Win!)
✅ No Popups: No annoying permission dialogs (Wayland)
✅ Secure: Proper kernel-level input handling
✅ Flexible: Non-root usage with correct permissions

Setup in 30 seconds:

# Inside your Linux VM
./install_uinput.sh
reboot

That's it! Full keyboard emulation without any limitations!

📱 Usage Scenarios - How People Love ProxPad!

🎮 Gamers & Streamers

Launch gaming VMs with one tap
Control media without alt-tabbing
Macro automation for streaming

🏠 Home Lab Enthusiasts

Manage homelab from couch
Automate daily tasks
Show off to friends! 😎

🏢 IT Professionals

Manage server farms from anywhere
Quick VM restarts during emergencies
Monitor infrastructure on-the-go

🔧 Advanced Configuration

Resource Management

SAME_RESOURCES = [
    [101, 102],  # GPU sharing VMs
    [103, 104],  # USB device VMs
]

Custom Macros

MACROS = {
    "gaming": "key:win; delay:0.2; type:steam; key:enter",
    "work": "url:https://company-portal.com",
}

Security Options

VERIFY_SSL = False  # For self-signed certs
SHY_MODE = True    # Confirmation dialogs

🚨 Troubleshooting - Quick Fixes!

Problem	Solution
Connection Failed	Check API token permissions (VM.Audit + VM.PowerMgmt)
VMs Not Showing	Verify VM_IDS in config and token permissions
Page Not Updating	Clear browser cache, ensure server running
Macros Not Working	Run macro_handler.py in target VM
Linux Keys Not Working	Install uinput and reboot

🌟 Community & Support

Need Help? We've Got You Covered!

📋 Issues: Report bugs on GitHub
💬 Discord: DM author monzon4765
💰 Premium Support: One-on-one setup paid assistance available

Contributing Welcome!

🎨 UI/UX improvements
🔧 New features
🐛 Bug fixes
📚 Documentation

📜 License - Open Source!

ProxPad - Proxmox Control Deck & Macro Pad
Copyright (C) 2024 Yury Monzon

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

🎉 Support the Project - Help Us Improve

Love ProxPad? Show your support and help us keep developing!

Every donation helps us:

🚀 Add new features
🐛 Fix bugs faster
📚 Improve documentation
🌟 Grow the community

Your support helps ProxPad development! ❤️

🚀 Ready to Enhance Your Proxmox Experience?

What are you waiting for?

⭐ Star the repo - Show your love!
🚀 Install now - Get running in minutes!
📱 Transform your phone - Become a Proxmox power user!
🎉 Join the community - Share your experience!

#Homelab #Proxmox #ReuseOldTablet #HardwareMacroPad #VFIO

Name		Name	Last commit message	Last commit date
.github		.github
images		images
templates		templates
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
TODO		TODO
color_editor.py		color_editor.py
config.py		config.py
install_deps_cachyos.sh		install_deps_cachyos.sh
install_deps_debian.sh		install_deps_debian.sh
install_uinput.sh		install_uinput.sh
macro_handler.py		macro_handler.py
matrix.jpg		matrix.jpg
proxpad-popup.sh		proxpad-popup.sh
proxpad.py		proxpad.py
randomize_macro_colors.py		randomize_macro_colors.py
requirements.txt		requirements.txt
restart_me.sh		restart_me.sh
run_me.sh		run_me.sh
send_slack_msg.sh		send_slack_msg.sh
send_tg_msg.sh		send_tg_msg.sh
send_warning_msg.sh		send_warning_msg.sh
upload_restart.sh		upload_restart.sh

Latest commit

History

Folders and files

Repository files navigation