Proxmox Admin

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

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:

# (Recommended) scaffold a project folder first
scripts/pmx-init <project-dir>
cd <project-dir>
cp secrets/env.sh.example secrets/env.sh
$EDITOR secrets/env.sh                  # fill in the token secret(s) later

# Profile creation + verification
scripts/pmx-onboard            # interactive wizard, writes 0600 YAML
scripts/pmx-doctor             # verifies SSH + REST reachability
scripts/pmx-inventory snapshot # capture initial inventory as diffable markdown
scripts/pmx-cv4pve-install     # optional but recommended
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 /      # creates user, role, ACL, token
# Capture the secret it prints once; re-run pmx-onboard to embed it

Daily workflow (after onboarding)

# Pick / inspect profile
scripts/pmx-profile list                # mark active with *
scripts/pmx-profile use prod-east       # switch active

# Read-only sanity
scripts/pmx-cv4 get vms                 # or: pmx-cv4 get cts, get nodes
scripts/pmx-ssh 'pvesm status'

# Provision
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

# Day-2 ops
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.

references/ and assets/ are listed in the table at the top of this file. Open them only when their topic comes up.