| 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:
- 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.
~/.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:
- SSH + curl helpers (
scripts/pmx-*) — always available, even with
only an SSH key. Required for shell-level ops with no REST equivalent.
- 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 |
| Provision / manage an LXC container | scripts/pmx-ct | container-management.md |
| Storage (ZFS, LVM-thin, NFS, Ceph) | scripts/pmx-storage | storage.md |
| Networking / SDN (zones, VNets, Fabrics, BGP) | scripts/pmx-ssh 'pvesh ...' | networking-sdn.md |
| Cluster, HA, quorum, dynamic load balancer | scripts/pmx-cluster | cluster-ha.md |
| Backups, restore, PBS | scripts/pmx-backup | backup-pbs.md |
| API tokens, roles, ACLs | scripts/pmx-token-create | api-tokens.md |
| Security hardening | (multiple) | security-hardening.md |
| Terraform / Ansible / IaC | n/a (delegate to provider) | iac-terraform-ansible.md |
| PegaProx / multi-cluster orchestration | n/a (community tool) | pegaprox.md |
| Compare or install remote CLIs | scripts/pmx-cv4pve-install | remote-cli-tools.md |
| Scaffold a project folder for this skill | scripts/pmx-init | project-folder.md |
| Capture live state into diffable markdown | scripts/pmx-inventory snapshot | project-folder.md |
| Look up any CLI flag fast | — | cli-cheat-sheet.md |
| Anything broken | scripts/pmx-doctor | troubleshooting.md |
Project layout (recommended)
For anything beyond a single throwaway profile, scaffold a project
folder that holds connection profiles, inventory, decisions, and
runbooks together in version control:
mkdir my-proxmox-project && cd my-proxmox-project
~/.claude/skills/proxmox-admin/scripts/pmx-init
The skill auto-detects .proxmox-admin/ in $PWD or any ancestor and
uses it as the config root. Falls back to ~/.config/proxmox-admin/ if
no project folder is found — backwards compatible with prior versions.
Full layout, secret-handling conventions, cross-OS notes, and migration
path from ~/.config/: references/project-folder.md.
Onboarding workflow (first run)
Before any other action, if no profile exists yet:
scripts/pmx-init <project-dir>
cd <project-dir>
cp secrets/env.sh.example secrets/env.sh
$EDITOR secrets/env.sh
scripts/pmx-onboard
scripts/pmx-doctor
scripts/pmx-inventory snapshot
scripts/pmx-cv4pve-install
scripts/pmx-cv4pve-sync --activate
Full prerequisites and the discovery commands to gather the inputs the
wizard asks for: references/onboarding.md.
If the user has no API token yet, the wizard can run without one; then:
scripts/pmx-token-create skill /
Daily workflow (after onboarding)
scripts/pmx-profile list
scripts/pmx-profile use prod-east
scripts/pmx-cv4 get vms
scripts/pmx-ssh 'pvesm status'
scripts/pmx-vm create 110 web-1 --memory 4096
scripts/pmx-ct create 200 web debian-12-standard
scripts/pmx-vm cloudinit 110 --ciuser deploy --sshkeys ~/.ssh/id_ed25519.pub \
--ipconfig0 ip=10.0.0.110/24,gw=10.0.0.1
scripts/pmx-vm start 110
scripts/pmx-backup run --all --mode snapshot --compress zstd
scripts/pmx-cluster status
Working with multiple instances
Each Proxmox node or cluster gets its own profile file. Switch with
pmx-profile use <name> or one-shot via PMX_PROFILE=<name>. cv4pve-cli
contexts stay in sync automatically as long as the user re-runs
pmx-cv4pve-sync after profile changes.
Conventions for the agent
- Read before write. Always run
pmx-vm config <id> (or the API
equivalent) before any destructive action. Cross-check the user's
intent against the actual state.
- No password auth. SSH helpers force
BatchMode=yes. If a profile
needs new auth, edit the profile, do not pass passwords inline.
- Secrets handling. Token secrets in profiles use the
${ENV:VAR}
reference form by default. Do not echo secrets to the user; redact
before quoting profile contents.
- Prefer the REST/cv4pve path for stateless reads and config sets.
Reserve
pmx-ssh for things with no REST endpoint (network config,
pveperf, journalctl, file edits).
- Profile is canonical. Never write Proxmox credentials elsewhere on
the workstation. Other tools (Terraform, Ansible, cv4pve-cli) should
reference the same profile values.
- Confirm before destruction.
qm destroy, pct destroy, pvesm remove,
pveum acl delete, pvecm delnode, force-quorum recovery, and any
--purge flag must be confirmed with the user — no exceptions.
- 2026 defaults.
virtio-scsi-single + iothread=1, q35 + ovmf,
cputype=host, agent enabled=1, --unprivileged 1 for containers,
--mode snapshot --compress zstd for backups, --privsep 0 only when
the simpler debug path is wanted.
Available scripts
Run <script> --help for the full interface of each. All scripts read the
active profile via the resolution order documented in
references/project-folder.md — first
$PMX_CONFIG_DIR env, then auto-detected .proxmox-admin/ in cwd or
ancestor, then ~/.config/proxmox-admin/. They accept PMX_PROFILE=<name>
for one-shot override, and write JSON to stdout / diagnostics to stderr
when --json is supported.
| Script | Purpose | Notable flags |
|---|
scripts/pmx-init | Scaffold a project folder with profiles/inventory/decisions/runbooks | --force to overwrite |
scripts/pmx-onboard | Interactive wizard → YAML profile | env-driven (non-interactive) when PMX_ONBOARD_* set |
scripts/pmx-doctor | TCP + SSH + REST + cv4pve checks | --json |
scripts/pmx-inventory | Snapshot live state to diffable markdown | snapshot | diff | show <cat> |
scripts/pmx-profile | list/use/show/path/remove/active | list --json |
scripts/pmx-ssh | Run any shell command on the host | - reads command from stdin |
scripts/pmx-api | Call REST API with the active token | forwards extra args to curl |
scripts/pmx-vm | qm wrapper with profile defaults | create, from-image, cloudinit, destroy --dry-run |
scripts/pmx-ct | pct wrapper with profile defaults | create, from-oci, download-template |
scripts/pmx-storage | pvesm wrapper | scan-iso, scan-vztmpl |
scripts/pmx-cluster | pvecm + ha-manager + cluster API | resources --type vm |
scripts/pmx-backup | vzdump / qmrestore / pct restore | --dry-run, `restore vm |
scripts/pmx-token-create | One-shot least-privilege pveum token | PMX_ROLE, PMX_PRIVSEP, PMX_PRIVS |
scripts/pmx-cv4pve-install | Install Corsinvest cv4pve-cli locally | PMX_CV4PVE_VERSION, PMX_CV4PVE_PREFIX |
scripts/pmx-cv4pve-sync | Mirror profiles → cv4pve contexts | --activate, --skip |
scripts/pmx-cv4 | cv4pve-cli auto-aligned to active profile | forwards all args |
references/ and assets/ are listed in the table at the top of this file.
Open them only when their topic comes up.
