proxmox-admin

name	proxmox-admin
description	Use this skill to administer a Proxmox VE 8.x/9.x host, node, or cluster remotely — provisioning, day-2 ops, troubleshooting, hardening, IaC, migration off VMware/ESXi. Covers KVM VMs (qm), LXC containers (pct; OCI in 9.1+), storage (pvesm; ZFS, LVM-thin, NFS, Ceph), networking and SDN (zones, VNets, Fabrics in 9.0+, BGP/WireGuard in 9.2+), clustering and HA (pvecm, ha-manager, Dynamic Load Balancer in 9.2+), backup/restore (vzdump, Proxmox Backup Server), API tokens (pveum), firewall and security, and IaC (Terraform bpg/Telmate, Ansible). Onboards a YAML connection profile (SSH key + API token + defaults) under ~/.config/proxmox-admin/ and drives ops via bundled SSH/REST helpers or cv4pve-cli. Trigger even when the user does not say "Proxmox" — e.g. "spin up a VM on my homelab", "the LXC container is OOMing", "web UI at port 8006", "vCenter alternative", ProxMox, PVE, PBS, ProxLB, PegaProx, vmbr0, vmid, cloud-init, GPU passthrough, ZFS pool, cluster quorum, qm, pct, pvesh.
license	MIT
metadata	{"author":"github.com/kryptobaseddev","version":"1.2.0","last_updated":"2026-05-22 17:00:00","compatibility":"Requires SSH client, curl, and a POSIX shell (bash 3.2+) on the workstation; Linux, macOS, and Windows via Git Bash/WSL all supported. The Proxmox host must be PVE 8.0+ and reachable from the workstation. Optionally uses cv4pve-cli (auto-installed via scripts/pmx-cv4pve-install). No agent or extra package needed on the Proxmox node itself."}
allowed-tools	Bash Read Write Edit Glob Grep

Proxmox VE Administration

Overview

This skill drives Proxmox VE 8.x/9.x remotely from the user's workstation. It maintains a per-instance connection profile (SSH credentials + API token + defaults). Every helper script reads the active profile, so the agent never needs to ask the user for credentials twice.

The profile can live in either of two places:

1. A project folder that you own — recommended. Auto-detected when a .proxmox-admin/ directory is found in $PWD or any ancestor. Lets you version-control profiles, inventory, decisions, and runbooks together. Scaffold with scripts/pmx-init. See project-folder.md.
2. ~/.config/proxmox-admin/ — the historical default. Used when no project folder is detected. Backwards compatible with all prior versions.

Two execution paths run side by side:

1. SSH + curl helpers (scripts/pmx-*) — always available, even with only an SSH key. Required for shell-level ops with no REST equivalent.
2. cv4pve-cli (scripts/pmx-cv4) — optional fast path. Single binary, kubectl-style contexts, full REST coverage. Recommended.

Profiles are the canonical source of truth. pmx-cv4pve-sync mirrors them into cv4pve-cli contexts so the user never duplicates credentials.

Decision tree — start here

Is there an active profile?
  (.proxmox-admin/active in cwd or ancestor, OR ~/.config/proxmox-admin/active)
├── NO  →  For a single-throwaway profile: read references/onboarding.md, run scripts/pmx-onboard.
│           For anything you want to keep:  run scripts/pmx-init <dir>, then pmx-onboard from inside.
│           See references/project-folder.md for the recommended pattern.
└── YES →  Run scripts/pmx-doctor to confirm reachability.
          ├── Any check fails       → references/troubleshooting.md
          └── All checks pass       → Pick the task lane below.

Task lanes

User intent	Primary helper	Deep reference
Provision / manage a VM	scripts/pmx-vm or pmx-cv4 do start guest --guest X	vm-management.md