🧰 Proxmox Manager

Single-file Bash tool for managing Proxmox VMs and containers

Shell · Proxmox VE

---

📸 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_FILE environment 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=1 for 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 .sh files.
  • Gitleaks scan prevents accidental secret commits.
• Vulnerability reporting: See SECURITY.md for 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 .sh file
• 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:

1. Fork and create a feature branch:

   git checkout -b feature/your-change

2. Keep Bash readable. Avoid external dependencies.

3. Run ShellCheck locally:

   shellcheck proxmox-manager.sh

4. Commit with conventional format:

   type(scope): summary
   

   Examples: feat(vm): add suspend action, fix(ct): handle missing hostname

5. 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.

---

Boring Proxmox administration, automated ✨

🐛 Report Bug • ✨ Request Feature