Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
📸 Screenshot
🎯 What It Does
Proxmox Manager is a single Bash script that wraps Proxmox CLI tools (qm, pct) into an interactive menu or scriptable interface. No daemons, no agents, no dependencies beyond what ships with Proxmox VE.
Core capabilities:
- List all VMs and containers with status (running, stopped, paused)
- Start, stop, restart instances — with confirmation prompt for destructive actions; shows Proxmox error details on failure
- Open console (LXC shell or QEMU terminal) — verifies CT is running before entering
- Manage snapshots (list, create, rollback, delete) — shows existing snapshots before rollback/delete; validates snapshot name format before calling Proxmox
- Enable and retrieve SPICE connection details for VMs
- Machine-readable JSON and plain-text output for automation
- Optional structured logging via
LOG_FILEenvironment variable - Node hostname, PVE version, and system uptime displayed in the header
🚀 Installation
Run directly on a Proxmox VE host:
git clone https://github.com/TimInTech/proxmox-manager.git
cd proxmox-manager
chmod +x proxmox-manager.sh
No build step. The core script has no required extra packages; optional helpers are available.
To install optional packages and register pman as a global command (requires root, run from the repo):
./install_dependencies.sh
Afterwards pman is available system-wide via a symlink in /usr/local/bin/:
pman # interactive menu
pman --list # plain-text table of all VMs/CTs
pman --json # machine-readable JSON output
pman --version # print version and exit
📋 Requirements
System:
- Proxmox VE (tested on 7.x, 8.x, and 9.x)
- Bash ≥ 4.0 (included in Proxmox)
- Root privileges (or
PROXMOX_MANAGER_ALLOW_NONROOT=1for CI overrides) - SPICE bind address defaults to 127.0.0.1 (override via PROXMOX_MANAGER_SPICE_ADDR).
CLI tools (bundled with Proxmox):
qm(VM management)pct(container management)- Standard POSIX utilities (
awk,sed,grep)
No Python. No Docker. No external APIs.
🛠️ Usage
Interactive mode (default)
pman
Displays a table of all VMs/containers with status symbols:
[+]running[-]stopped[~]paused[?]unknown
Enter a VMID to open an action menu. Press r to refresh, q to quit.
A summary line below the table shows the count of running and stopped instances.
List mode (plain text)
pman --list
Prints a formatted table. Useful for logging or quick checks.
JSON mode (machine-readable)
pman --json
Outputs VM/CT data as JSON array:
[
{"id":100,"type":"VM","status":"running","symbol":"[+]","name":"web-server"},
{"id":101,"type":"CT","status":"stopped","symbol":"[-]","name":"db-container"}
]
Use with jq or automation tools.
Non-interactive / scripted use
The script is designed for interactive use. For automation, prefer --list or --json and parse output.
All destructive actions (stop, restart, snapshot rollback) require confirmation in interactive mode.
Options
--list Print plain-text table (no TUI)
--json Print JSON output
--version Print version and exit
--no-clear Do not clear screen in interactive mode
--once Run one refresh cycle (useful for recording)
-h, --help Show usage
🔐 Security
- Root required: The script calls
qm,pct, and other Proxmox tools that require elevated privileges. - No credentials stored: Relies on Proxmox host authentication.
- No outbound traffic: All operations are local.
- CI hardening:
- ShellCheck enforced on all
.shfiles. - Gitleaks scan prevents accidental secret commits.
- ShellCheck enforced on all
- Vulnerability reporting: See
SECURITY.mdfor responsible disclosure.
🧩 What It Is Not
- Not a UI replacement: Use the Proxmox web UI for rich workflows.
- Not configuration management: No Terraform/Ansible integration (yet).
- Not a daemon: Runs on demand, exits immediately.
- Not multi-host: Manages only the local Proxmox node.
🧪 CI & Testing
Automated checks:
- ShellCheck on every
.shfile - Gitleaks scan for secrets (scan results never committed)
- No generated files or scan outputs in the repository
Local testing:
shellcheck proxmox-manager.sh
tests/run.sh # 8 tests against mock-bin/ stubs, no real Proxmox needed
CI runs on every push and PR.
🤝 Contributing
Contributions welcome if they preserve the tool's simplicity.
Guidelines:
-
Fork and create a feature branch:
git checkout -b feature/your-change -
Keep Bash readable. Avoid external dependencies.
-
Run ShellCheck locally:
shellcheck proxmox-manager.sh -
Commit with conventional format:
type(scope): summaryExamples:
feat(vm): add suspend action,fix(ct): handle missing hostname -
Open a Pull Request.
Do NOT commit:
- Generated files (logs, reports, artifacts)
- Scan outputs (Gitleaks, ShellCheck results)
- Binary files or large test data
📜 License
MIT License. See LICENSE for full text.
