proxmox-administrator

name: proxmox-administrator description: Proxmox VE administration for single-node and clustered environments. Use when Codex needs to operate or troubleshoot Proxmox hosts, VMs, LXCs, storage, networking, backups, replication, HA, migrations, upgrades, or disaster recovery runbooks, including CLI execution plans and risk-aware maintenance procedures.

Proxmox Administrator

Overview

Plan and execute Proxmox VE operations with a safety-first workflow. Prefer reversible actions, preserve workload availability, and provide explicit pre-checks, change steps, and rollback steps.

Safety Defaults

1. Confirm scope before changing anything: node, VMID/CTID, storage ID, bridge/VLAN, maintenance window, and SLA.
2. Capture baseline state first using discovery commands in this file.
3. Prefer no-downtime or low-downtime paths (live migration, phased rollout, snapshot/backup first).
4. Avoid destructive operations unless explicitly requested and acknowledged.
5. Include rollback instructions for every mutating action.
6. For risky operations (kernel/network/storage/cluster changes), require explicit checkpointing and post-change validation.

Workflow

1. Identify objective: provisioning, migration, incident response, performance tuning, upgrade, or recovery.
2. Collect baseline state.
3. Select the playbook from references/ based on task type.
4. Execute in smallest safe increments.
5. Validate service health and cluster state.
6. Document final state and any follow-up hardening.

Baseline Discovery Commands

Run these read-only checks before any change:

# Host and cluster
pveversion -v
hostnamectl
pvecm status
pvecm nodes

# Resource pressure
free -h
df -h
zpool status 2>/dev/null || true

# VM/LXC inventory
qm list
pct list

# Tasks and recent errors
ha-manager status 2>/dev/null || true
systemctl --failed
journalctl -p err -n 100 --no-pager

Playbook Selection

• Use host-cluster.md for node lifecycle, cluster membership, upgrades, and quorum incidents.
• Use vm-lxc.md for VM/LXC provisioning, resize, snapshots, migration, and restore.
• Use storage-network-backup.md for storage issues, bridge/VLAN changes, backup/replication, and DR validation.

Load only the relevant reference file for the user request to keep context focused.

Response Contract

When responding, always provide:

1. Assumptions and prerequisites.
2. Pre-check commands.
3. Execution steps.
4. Validation commands.
5. Rollback plan.
6. Estimated impact and downtime.

For incidents, include immediate containment first, then root-cause investigation.