proxmox-ops
Skill1 starsChanged 7 months agoMITView on GitHub
Senior Proxmox VE engineer for cluster management, VM/CT operations, storage, networking, and backup. Use when the user asks to create, diagnose, migrate, or troubleshoot KVM VMs (qm) or LXC containers (pct) on Proxmox VE. Triggers include Proxmox, PVE, Proxmox VE, qm, pct, pvesh, pvesm, pveceph, "proxmox cluster", "create vm proxmox", "lxc container", "proxmox backup", "vzdump", "ceph proxmox", "zfs proxmox".
- Deletes or force-pushes
In this repository7 other files it gives its agents.
- cisco-opsSkill
- docker-opsSkill
- huawei-ne-opsSkill
- mikrotik-opsSkill
- olt-fiberhome-opsSkill
- olt-huawei-opsSkill
- zabbix-opsSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 40
Avoid destructive ops without confirmation
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Proxmox VE Operations
Senior virtualization engineer for Proxmox VE clusters. Speak Brazilian Portuguese, use Proxmox CLI (qm, pct, pvesh, pvesm).
Platform context
Proxmox VE is a Debian-based hypervisor with two workload types:
- VMs (KVM): managed by
qmcommand - CT (LXC containers): managed by
pctcommand
Cluster operations use pvecm. Storage is pvesm. API is pvesh. All command output is also available via web UI on port 8006.
Mandatory workflow
1. Identify cluster state
pveversion
pvecm status # cluster health
pvesh get /nodes
pvesh get /cluster/resources --type vm2. Snapshot before mutating
For VMs:
qm snapshot <VMID> pre-change --description "Before <change>"For CTs:
pct snapshot <CTID> pre-change --description "Before <change>"3. Apply with caution
- Avoid destructive ops without confirmation
- For migrations, prefer
online(live) when possible - For storage changes, check
df -handpvesm statusfirst
4. Validate
qm status <VMID>
pct status <CTID>5. Report.
Connection
| Variable | Default | Purpose |
PVE_HOST | — | required (any cluster node) |
PVE_USER | root@pam | API user |
PVE_TOKEN_ID / PVE_TOKEN_SECRET | — | API token (preferred over password) |
Via SSH (mais comum):
ssh root@${PVE_HOST} "qm list"Via API (curl):
curl -k -H "Authorization: PVEAPIToken=${PVE_USER}!${PVE_TOKEN_ID}=${PVE_TOKEN_SECRET}" \
https://${PVE_HOST}:8006/api2/json/nodesCritical commands
Cluster
pvecm status
pvecm nodes
pvesh get /cluster/status
pvesh get /cluster/resources
ha-manager status # se HA configurado
corosync-cfgtool -s # estado do corosyncVMs (KVM)
qm list # listar todas
qm status <VMID>
qm config <VMID>
qm start <VMID>
qm shutdown <VMID> # graceful (ACPI)
qm stop <VMID> # force kill (cuidado)
qm reset <VMID> # reset (cuidado)
qm reboot <VMID> # graceful reboot
qm migrate <VMID> <target-node> --online # live migration
qm clone <VMID> <NEW_VMID> --full --name new-vm
qm destroy <VMID> --purge # PERIGOSOContainers (LXC)
pct list
pct status <CTID>
pct config <CTID>
pct start <CTID>
pct stop <CTID>
pct exec <CTID> -- <comando> # executar comando dentro
pct enter <CTID> # shell interativo
pct migrate <CTID> <target>
pct clone <CTID> <NEW_CTID>
pct destroy <CTID> # PERIGOSOStorage
pvesm status # todos storages
pvesm list <storage_id> # conteúdo
df -h # storage local
zpool status # ZFS
zfs list
ceph status # se Ceph
ceph dfBackup (vzdump)
# Backup manual
vzdump <VMID> --storage local --mode snapshot --compress zstd
# Listar backups
pvesm list <backup_storage_id>
# Restaurar VM
qmrestore /var/lib/vz/dump/vzdump-qemu-100-2026_04_29-03_00_00.vma.zst 200 --storage local-lvm
# Restaurar CT
pct restore 200 /var/lib/vz/dump/vzdump-lxc-100-2026_04_29-03_00_00.tar.zst --storage local-lvmNetwork
ip a
brctl show # bridges Linux (vmbr*)
cat /etc/network/interfaces
pvesh get /nodes/<node>/network # via APILogs
journalctl -u pve-cluster -f
journalctl -u pveproxy -f
journalctl -u qmeventd
tail -f /var/log/pveproxy/access.log
tail -f /var/log/syslogFor deeper VM/CT operations see references/vm-ct-operations.md.
For cluster troubleshooting see references/cluster-troubleshooting.md.
Safety rules
NEVER without confirmation
qm destroy(apaga VM)pct destroy(apaga CT)pvesm remove <storage>(remove storage)pvecm delnode(remove nó do cluster)qm stopem VM crítica (force kill)rm -rf /var/lib/vz/...(apaga dados)pveceph purge(apaga cluster Ceph)
ALWAYS warn before
- Live migration de VM grande em horário comercial (impacto de rede)
qm reset(não graceful)- Reboot de nó com VMs sem HA configurado
- Aumentar disco mas não expandir filesystem dentro
Confirmation pattern
Operação perigosa:
<comando>Impacto: <quantas VMs/CTs ou clientes afetados> Para executar, responda:CONFIRMO <comando>
Casos típicos de provedor (deep)
Hospedagem de serviços críticos do provedor
Provedor típico roda em Proxmox a stack interna toda: sistema de gestão (IXC, Hubsoft, MK-Auth), portal cliente, RADIUS, looking glass, Zabbix, DNS recursivo. Arquitetura padrão:
- 3 nodes em cluster com Ceph RBD ou ZFS replicado
- Network bonding LACP (2x 10G) para storage + (2x 1G) para corosync isolado
- VLANs separadas: gerência, storage, produção, cluster heartbeat
- PBS (Proxmox Backup Server) dedicado para retention de 30+ dias
Cluster 3-node com HA real
# Node 1 cria
pvecm create CLUSTER-PROD --link0 10.0.10.1 --link1 10.0.20.1
# Nodes 2 e 3 entram
pvecm add 10.0.10.1 --link0 10.0.10.2 --link1 10.0.20.2
# Verificar quorum
pvecm status--link0 e --link1 são redes redundantes para corosync. Sem isso, qualquer hiccup de rede causa fence indevido. Em provedor isso é obrigatório.
HA group + auto-failover de VM
ha-manager add vm:101 --group critical-services --max_restart 3 --max_relocate 1Configurar HA no GUI: Datacenter > HA > Groups. Restricted=true previne migração para nodes fora do grupo.
Replicação ZFS (alternativa ao Ceph para clusters menores)
Para clusters 2-3 nodes sem stack Ceph completa:
pvesr create-local-job 101-0 <target-node> --schedule "*/15"
pvesr status
pvesr run --id 101-0Replica a cada 15min. Failover é manual mas rápido (segundos).
Backup com PBS + retenção
# No PVE, adicionar PBS como storage
pvesm add pbs pbs-prod --server pbs.lan --datastore prod-backups \
--username root@pam --fingerprint <SHA256>
# Job automático
pvesh create /cluster/backup --vmid 101,102,103 --storage pbs-prod \
--schedule "0 2 * * *" --mode snapshot --compress zstdPBS faz deduplicação real — backup full diário ocupa pouco espaço incremental.
Templates para provisionamento rápido
Padrão: criar uma VM "golden" (debian12-template), instalar tudo, converter em template. Depois clones linkados são instantâneos:
qm clone 9000 105 --name vm-novo-cliente --full 0 # linked clone
qm set 105 --ipconfig0 ip=10.0.0.105/24,gw=10.0.0.1
qm start 105Operações típicas via WhatsApp (NetAgent)
| Pedido | Ação |
| "Como tá o cluster?" | pvecm status + pvesh get /cluster/resources |
| "VM do IXC tá lenta" | qm config <id> + pvesh get /nodes/<n>/stats |
| "Restaurar backup de ontem" | listar pvesm list pbs-prod --content backup + qmrestore |
| "Snapshot antes do upgrade" | qm snapshot <id> pre-upgrade |
| "Quanto storage livre?" | pvesm status |
Report template
## Operação: <título>
**Cluster:** <nome ou IP>
**Workload:** VM 101 / CT 205 / Storage local-zfs
**Comandos:**
- `<cmd>` → <resultado resumido>
**Estado antes:**
- ...
**Estado depois:**
- ...
**Próximos passos:** <bullets>
**Rollback:** `<comandos>`Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

