Skip to content

Instantly share code, notes, and snippets.

@jpolvora

jpolvora/proxmox-AGENTS.md

Created June 29, 2026 22:02
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save jpolvora/f9fb635d5841861f8d9ffde71418cf79 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save jpolvora/f9fb635d5841861f8d9ffde71418cf79 to your computer and use it in GitHub Desktop.
Download ZIP
an agents.md for proxmox
Raw
proxmox-AGENTS.md

AGENTS.md — Proxmox / Linux Host with LXC & VMs

General Principles

  • Read-only first — always inspect before modifying.
  • Prefer non-destructive queries — use pct list, qm list, pvesh over direct config edits.
  • Backup before changes — snapshot VMs/LXC via pvesr or vzdump before risky operations.
  • Make one change at a time, verify, then proceed.
  • Use pct / qm CLI rather than raw config file editing when possible — they validate inputs.

System Critical Criteria (Safety First)

  1. NO FORCE FLAGS — Never append -f, --force, or override confirmation prompts unless explicitly authorized by the operator.
  2. UI SYNCHRONIZATION — Never manually modify raw configuration files if a Proxmox wrapper command exists (pvecm, qm, pct, pveceph). Direct edits out-of-sync with the PVE cluster engine can cause catastrophic splits.
  3. DRY RUN MANDATE — For any resource modification (LVM resize, ZFS pool adjustments, CPU pinning), first output a --dry-run or echo-equivalent command to verify boundaries.
  4. BACKUP VALIDATION — Before modifying configuration files (e.g. /etc/pve/storage.cfg, /etc/network/interfaces), perform an explicit backup: cp file file.bak_$(date +%F).

Command Request Blueprint

When proposing any change, present the plan in this format:

[OBJECTIVE]: Brief description of optimization.
[RISK LEVEL]: Low / Medium / High (with explanation).
[TEST COMMAND]: A safe verification/dry-run script.
[EXECUTE COMMAND]: The actual command awaiting permission.

Checking Host State

System Health

  • uptime && free -h && df -h — quick resource overview.
  • dmesg -T | tail -30 — recent kernel/hardware messages.
  • journalctl -xe -p err --since "1 hour ago" — recent errors.
  • top -bn1 | head -20 or htop — CPU/memory hogs.
  • lm-sensors — confirm CPU temperatures before setting persistent power policies.

Storage & ZFS

  • zpool status -v — pool health and scrub status.
  • zfs list -o name,used,avail,refer,mountpoint — dataset usage.
  • lsblk -f — block device mapping.
  • pvesm status — Proxmox storage status.

Networking

  • ip -br a — interface addresses.
  • ip route show — routing table.
  • cat /etc/network/interfaces or /etc/netplan/*.yaml — host network config.
  • bridge link show vmbr0 — bridge / vnet details.
  • tcpdump -i any -c 50 -n — traffic sampling (only when debugging).

Cluster & Service Healthcheck

If asked for /healthcheck or a general status review, chain these safely:

  1. pvecm status — Cluster status and quorum verification.
  2. pvesubscription get — Subscription alerts / repository conflicts.
  3. zpool status or df -h — Storage pool degradation analysis.
  4. systemctl is-active pve-cluster pvedaemon pveproxy — Core service operational status.

LXC Containers

Inspection

  • pct list — all containers with status.
  • pct config <CT_ID> — full container config.
  • pct enter <CT_ID> — interactive shell inside (read-only commands).
  • lxc-top — per-container resource usage.

Safe Modifications

  • Memory/CPU: pct set <CT_ID> -memory 2048 -cores 2 -swap 1024
  • Mount point: pct set <CT_ID> -mp0 /storage/data,mp=/mnt/data
  • Network: pct set <CT_ID> -net0 name=eth0,bridge=vmbr0,ip=dhcp
  • Restart container after resource changes: pct reboot <CT_ID>

Optimization

  • Disable swap inside containers where not needed: pct set <CT_ID> -swap 0
  • Unprivileged containers are more secure; prefer them.
  • Use idmap for bind mounts to avoid permission issues.
  • Limit conntrack if running many containers: sysctl -w net.netfilter.nf_conntrack_max=262144
  • Use pveperf to benchmark CPU/storage.

QEMU/KVM Virtual Machines

Inspection

  • qm list — all VMs with status.
  • qm config <VM_ID> — full VM config.
  • qm monitor <VM_ID> — QEMU monitor (use info commands).
  • qm guest cmd <VM_ID> network-get-interfaces — guest agent queries (requires qemu-guest-agent).

Safe Modifications

  • Memory/CPU: qm set <VM_ID> -memory 8192 -cores 4 -sockets 1
  • Disk resize: qm resize <VM_ID> scsi0 +10G (grow only; never shrink online)
  • Add NIC: qm set <VM_ID> -net1 virtio,bridge=vmbr1
  • Hotplug (if enabled): memory and CPU can be changed live.
  • Restart VM after config change unless hotplug supported: qm reboot <VM_ID>

Optimization

  • Use VirtIO for disk (scsihw=virtio-scsi-pci) and NIC (virtio) for best performance.
  • Enable KVM (-cpu host) for full hardware virtualization.
  • Enable NUMA for large VMs: qm set <VM_ID> -numa 1
  • Install qemu-guest-agent inside guests for graceful shutdown/backup.
  • Use discard=on on VM disks backed by thin-provisioned storage.
  • Enable balloon for dynamic memory: qm set <VM_ID> -balloon 2048
  • Set iothread + aio=native for high I/O workloads.

Host-Level Optimization

CPU & Power Governor

  • Action: Shift host governor from power-saving to performance for low-latency VM operations.
  • Safe Command: echo "performance" | tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
  • Constraint: Confirm CPU temperatures (lm-sensors) before setting persistent cron or systemd policies.

ZFS ARC RAM Limits

  • Action: Prevent ZFS from starving QEMU/KVM processes by pinning ARC size.
  • Method: Modify dynamically via /sys/module/zfs/parameters/zfs_arc_max or persistently via /etc/modprobe.d/zfs.conf.
  • Rule of Thumb: 10% of total host RAM for ARC if running mostly heavy VMs; 50% if heavy LXC storage.

KSM (Kernel Samepage Merging) Tuning

  • Action: Control memory overcommit efficiency.
  • Safe Command: Adjust /sys/kernel/mm/ksm/pages_to_scan and /sys/kernel/mm/ksm/sleep_millisecs; scale back if CPU overhead exceeds 5%.

Storage Optimization

ZFS Tuning

  • zfs set atime=off <POOL/DATASET> — disable access time updates.
  • zfs set compression=zstd <POOL/DATASET> — enable compression (saves space, often speeds up I/O).
  • zfs set xattr=sa <POOL/DATASET> — improve Samba/NFS performance.
  • Set recordsize=16K for VM/LXC volumes (matches typical block size).

I/O Scheduler

  • Check: cat /sys/block/*/queue/scheduler
  • Set to none (NVMe) or mq-deadline (SSD): echo none > /sys/block/<dev>/queue/scheduler

Backup & Safety Net

vzdump (built-in)

  • Backup a container: vzdump <CT_ID> --mode snapshot --compress zstd --remove 0
  • Backup a VM: vzdump <VM_ID> --mode snapshot --compress zstd --remove 0
  • Check backup dir: ls -lh /var/lib/vz/dump/

Configuration Backups

  • Back up Proxmox itself: tar czf /root/pve-config-$(date +%F).tgz /etc/pve/
  • Restore individual VM/CT configs from /etc/pve/nodes/<hostname>/qemu-server/<VM_ID>.conf or /etc/pve/nodes/<hostname>/lxc/<CT_ID>.conf

Common Do Nots

  • Do not rm -rf inside /etc/pve/ — it's a clustered filesystem (pmxcfs).
  • Do not edit .conf files in /etc/pve/ while the VM/CT is running — use qm set/pct set.
  • Do not run apt upgrade or pveupdate without checking Proxmox release notes first.
  • Do not modify host kernel parameters without understanding Proxmox requirements.
  • Do not shrink ZFS datasets or VM disks — always expand.
  • Do not stop pveproxy or pvedaemon unless explicitly asked.

Verification

  • After changes: systemctl status pveproxy pvedaemon — ensure services are healthy.
  • Check VM/CT can still start: qm start <VM_ID> --dryrun (VM only).
  • Ping guest IPs, check console, verify workloads.
  • Review journalctl -u pveproxy -u pvedaemon --since "5 min ago" for errors.

References & Documentation

Online Sources

Local Mirror (pve-docs/)

The entire Proxmox VE documentation is mirrored locally in /root/pve-docs/ as markdown files for fast AI querying. See pve-docs/README.md for a complete index.

Progressive disclosure by topic:

Task / Topic Read These First
Host system administration (networking, storage, kernel) pve-docs/chapters/chapter-sysadmin.md
Creating/managing VMs pve-docs/chapters/chapter-qm.md then pve-docs/man-pages/qm.1.md
Creating/managing LXC containers pve-docs/chapters/chapter-pct.md then pve-docs/man-pages/pct.1.md
Cluster setup & management pve-docs/chapters/chapter-pvecm.md then pve-docs/man-pages/pvecm.1.md
Storage configuration (ZFS, LVM, NFS, etc.) pve-docs/chapters/chapter-pvesm.md then pve-docs/man-pages/pvesm.1.md
Ceph cluster deployment pve-docs/chapters/chapter-pveceph.md
Firewall rules & configuration pve-docs/chapters/chapter-pve-firewall.md
User management & permissions pve-docs/chapters/chapter-pveum.md
High Availability pve-docs/chapters/chapter-ha-manager.md
Backup & restore (vzdump) pve-docs/chapters/chapter-vzdump.md then pve-docs/man-pages/vzdump.1.md
Software-Defined Networking pve-docs/chapters/chapter-pvesdn.md
Notifications & alerts pve-docs/chapters/chapter-notifications.md
Cluster File System (pmxcfs) pve-docs/chapters/chapter-pmxcfs.md
Storage Replication pve-docs/chapters/chapter-pvesr.md
API usage (pvesh) pve-docs/chapters/chapter-pvesh.md then pve-docs/man-pages/pvesh.1.md
VM configuration options pve-docs/man-pages/qm.conf.5.md
Container configuration options pve-docs/man-pages/pct.conf.5.md
Datacenter configuration pve-docs/man-pages/datacenter.cfg.5.md
Daemon management (pveproxy, pvedaemon, etc.) pve-docs/man-pages/pveproxy.8.md, pve-docs/man-pages/pvedaemon.8.md
Node management pve-docs/man-pages/pvenode.1.md
Subscription management pve-docs/man-pages/pvesubscription.1.md
root@pve:~#
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment