Agent skill

proxmox-admin

Use when administering Proxmox VE hosts, creating and managing VMs with qm, managing LXC containers with pct, configuring storage, networking, clusters, and automating provisioning tasks via the Proxmox CLI.

View SKILL.md on GitHub Repository
Stars 0
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/bastos/skills/tree/main/proxmox-admin

Metadata

Additional technical details for this skill

author
github.com/bastos
version
1.0

SKILL.md

Proxmox VE Administration

Overview

Proxmox VE is a server virtualization platform built on Debian. It manages KVM virtual machines and LXC containers through a web UI or CLI tools. This skill covers CLI-based administration using qm (VMs), pct (containers), and supporting utilities.

When to Use

  • Creating, configuring, or managing KVM virtual machines
  • Spawning and administering LXC containers
  • Managing Proxmox storage, networking, or clustering
  • Automating VM/container provisioning via scripts
  • Troubleshooting Proxmox host or guest issues

Not for: Web UI-only workflows (use the CLI equivalents below).

Quick Reference

Tool Purpose
qm Manage KVM virtual machines
pct Manage LXC containers
pvesm Manage storage
pvecm Manage cluster
pveam Manage appliance/template downloads
pvesh Access the Proxmox API from the shell
pveperf Benchmark host performance

VM Management with qm

Creating a VM

bash
# Create a VM with ID 100
qm create 100 --name my-vm --memory 2048 --cores 2 --sockets 1 \
  --net0 virtio,bridge=vmbr0 --ostype l26

# Create with SCSI disk on local-lvm storage (32GB)
qm create 100 --name my-vm --memory 4096 --cores 4 \
  --scsi0 local-lvm:32 --scsihw virtio-scsi-pci \
  --net0 virtio,bridge=vmbr0 --ostype l26

# Attach an ISO for installation
qm set 100 --cdrom local:iso/ubuntu-22.04-server.iso --boot order=ide2

VM Lifecycle

Command Purpose
qm start <vmid> Start a VM
qm shutdown <vmid> Graceful ACPI shutdown
qm stop <vmid> Force stop (like pulling power)
qm reboot <vmid> Reboot a VM
qm reset <vmid> Hard reset
qm suspend <vmid> Suspend to RAM
qm resume <vmid> Resume from suspend
qm destroy <vmid> Delete VM and its disks
qm destroy <vmid> --purge Delete VM, disks, and all related jobs

VM Configuration

bash
# Show current config
qm config 100

# Modify hardware
qm set 100 --memory 8192
qm set 100 --cores 4
qm set 100 --balloon 2048          # dynamic memory (min)
qm set 100 --cpu cputype=host      # pass through host CPU features
qm set 100 --machine q35           # use Q35 chipset (for PCIe passthrough)

# Add/resize disks
qm set 100 --scsi1 local-lvm:50    # add 50GB disk
qm disk resize 100 scsi0 +20G      # grow existing disk by 20GB

# Networking
qm set 100 --net0 virtio,bridge=vmbr0,tag=10   # VLAN tagged
qm set 100 --net1 virtio,bridge=vmbr1           # second NIC

# Cloud-init (for automated provisioning)
qm set 100 --ide2 local-lvm:cloudinit
qm set 100 --ciuser admin --cipassword 'secret'
qm set 100 --ipconfig0 ip=10.0.0.50/24,gw=10.0.0.1
qm set 100 --sshkeys ~/.ssh/authorized_keys
qm set 100 --boot order=scsi0

# EFI / UEFI boot
qm set 100 --bios ovmf --efidisk0 local-lvm:1,efitype=4m,pre-enrolled-keys=1

# Serial console (headless)
qm set 100 --serial0 socket --vga serial0

# PCI passthrough (GPU, NIC, etc.)
qm set 100 --hostpci0 0000:01:00.0,pcie=1

Snapshots and Cloning

bash
# Create a snapshot
qm snapshot 100 before-upgrade --description "Before kernel upgrade"

# List snapshots
qm listsnapshot 100

# Rollback to snapshot
qm rollback 100 before-upgrade

# Delete a snapshot
qm delsnapshot 100 before-upgrade

# Clone a VM (full copy)
qm clone 100 101 --name cloned-vm --full

# Clone as linked clone (shares base disk, faster)
qm clone 100 101 --name linked-vm

Templates

bash
# Convert VM to template (irreversible)
qm template 100

# Create VM from template (linked clone)
qm clone 100 200 --name from-template

# Create VM from template (full clone)
qm clone 100 200 --name from-template --full

Migration

bash
# Online migration to another node
qm migrate 100 node2 --online

# Offline migration
qm migrate 100 node2

Monitoring

bash
# VM status
qm status 100

# List all VMs
qm list

# Show running processes/agent info
qm agent 100 ping
qm agent 100 get-osinfo

# Monitor interface (QEMU monitor)
qm monitor 100

Container Management with pct

Creating a Container

bash
# Download a template first
pveam update
pveam available --section system
pveam download local debian-12-standard_12.2-1_amd64.tar.zst

# Create container with ID 200
pct create 200 local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst \
  --hostname my-ct --memory 1024 --cores 2 \
  --rootfs local-lvm:8 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp \
  --password 'secret' --unprivileged 1

# Create with static IP
pct create 201 local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst \
  --hostname web-ct --memory 2048 --cores 2 \
  --rootfs local-lvm:16 \
  --net0 name=eth0,bridge=vmbr0,ip=10.0.0.51/24,gw=10.0.0.1 \
  --nameserver 1.1.1.1 --unprivileged 1

Container Lifecycle

Command Purpose
pct start <ctid> Start container
pct shutdown <ctid> Graceful shutdown
pct stop <ctid> Force stop
pct reboot <ctid> Reboot container
pct destroy <ctid> Delete container and its volumes
pct enter <ctid> Open a shell inside the container
pct exec <ctid> -- <cmd> Run a command inside the container
pct console <ctid> Attach to container console

Container Configuration

bash
# Show config
pct config 200

# Modify resources
pct set 200 --memory 4096
pct set 200 --cores 4
pct set 200 --swap 1024

# Add mount point (bind mount from host)
pct set 200 --mp0 /mnt/data,mp=/data

# Add additional storage volume
pct set 200 --mp1 local-lvm:50,mp=/var/lib/data

# Networking
pct set 200 --net0 name=eth0,bridge=vmbr0,ip=10.0.0.60/24,gw=10.0.0.1
pct set 200 --net1 name=eth1,bridge=vmbr1,ip=dhcp

# Features (nesting, FUSE, NFS)
pct set 200 --features nesting=1
pct set 200 --features nesting=1,fuse=1,mount=nfs

# DNS
pct set 200 --nameserver "1.1.1.1 8.8.8.8" --searchdomain example.com

# Start on boot
pct set 200 --onboot 1 --startup order=1,up=30

Container Snapshots and Cloning

bash
# Snapshot
pct snapshot 200 clean-install

# Rollback
pct rollback 200 clean-install

# Clone
pct clone 200 201 --hostname cloned-ct --full

Storage Management

bash
# List storage pools
pvesm status

# List content of a storage
pvesm list local
pvesm list local-lvm

# Add storage (examples)
pvesm add dir my-backup --path /mnt/backup --content backup
pvesm add nfs nfs-share --server 10.0.0.5 --export /exports/pve --content images,vztmpl
pvesm add lvm my-lvm --vgname my-vg --content rootdir,images
pvesm add zfspool my-zfs --pool rpool/data --content rootdir,images

# Remove storage
pvesm remove my-backup

# Download ISO
wget -P /var/lib/vz/template/iso/ https://example.com/image.iso

Networking

bash
# List network interfaces
cat /etc/network/interfaces

# Common bridge configuration (in /etc/network/interfaces)
# auto vmbr0
# iface vmbr0 inet static
#     address 10.0.0.1/24
#     bridge-ports eno1
#     bridge-stp off
#     bridge-fd 0

# Apply network changes
ifreload -a

Cluster Management

bash
# Create a new cluster
pvecm create my-cluster

# Join an existing cluster
pvecm add 10.0.0.1

# Show cluster status
pvecm status

# List cluster nodes
pvecm nodes

# Remove a node (run from a remaining node)
pvecm delnode nodename

# Check quorum
pvecm expected 1    # force quorum (dangerous, single-node recovery only)

Firewall

bash
# Enable/disable firewall at datacenter level
pve-firewall start
pve-firewall stop
pve-firewall status

# Manage rules via config files
# Datacenter: /etc/pve/firewall/cluster.fw
# Node:       /etc/pve/nodes/<node>/host.fw
# VM/CT:      /etc/pve/firewall/<vmid>.fw

Backup and Restore

bash
# Backup a VM
vzdump 100 --storage local --mode snapshot --compress zstd

# Backup a container
vzdump 200 --storage local --mode stop --compress zstd

# Backup all guests
vzdump --all --storage local --mode snapshot --compress zstd --mailto admin@example.com

# Restore a VM
qmrestore /var/lib/vz/dump/vzdump-qemu-100-*.vma.zst 100

# Restore a container
pct restore 200 /var/lib/vz/dump/vzdump-lxc-200-*.tar.zst

# Restore to different storage
qmrestore /var/lib/vz/dump/vzdump-qemu-100-*.vma.zst 100 --storage local-lvm

Common Provisioning Patterns

Cloud-Init VM from Template

bash
# 1. Create base VM and install OS, then convert to template
qm template 9000

# 2. Clone and customize with cloud-init
qm clone 9000 110 --name web-server --full
qm set 110 --ciuser deploy --sshkeys ~/.ssh/authorized_keys
qm set 110 --ipconfig0 ip=10.0.0.110/24,gw=10.0.0.1
qm set 110 --nameserver 1.1.1.1
qm start 110

Batch Create Containers

bash
for i in $(seq 1 5); do
  CTID=$((300 + i))
  pct create $CTID local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst \
    --hostname "worker-${i}" --memory 1024 --cores 2 \
    --rootfs local-lvm:8 \
    --net0 name=eth0,bridge=vmbr0,ip=10.0.0.$((60 + i))/24,gw=10.0.0.1 \
    --unprivileged 1 --start 1
done

Import Disk Image (e.g., cloud image)

bash
# Download a cloud image
wget https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img

# Import to a VM
qm importdisk 100 jammy-server-cloudimg-amd64.img local-lvm

# Attach the imported disk
qm set 100 --scsi0 local-lvm:vm-100-disk-0
qm set 100 --boot order=scsi0

Troubleshooting

Problem Solution
VM won't start Check qm config <vmid>, verify storage exists with pvesm status
"TASK ERROR: can't lock file" rm /run/lock/qemu-server/lock-<vmid>.conf (verify VM is not running first)
Container has no network Check bridge exists: brctl show; verify firewall rules
Disk full on storage pvesm status to check usage; lvs for LVM thin pools
Cluster quorum lost pvecm expected 1 on surviving node (single-node recovery only)
Migration fails Ensure same CPU type or use --online with live migration; check network between nodes
Backup fails with lock error qm unlock <vmid> or pct unlock <ctid>
Slow disk I/O in VM Use virtio-scsi-pci controller with iothread=1 and discard=on
Guest agent not responding Install qemu-guest-agent in the VM and enable: qm set <vmid> --agent 1

Useful Paths

Path Contents
/etc/pve/ Cluster-wide config (pmxcfs)
/etc/pve/qemu-server/<vmid>.conf VM configuration files
/etc/pve/lxc/<ctid>.conf Container configuration files
/etc/pve/storage.cfg Storage definitions
/etc/pve/nodes/ Per-node configuration
/var/lib/vz/ Default local storage root
/var/lib/vz/template/iso/ ISO images
/var/lib/vz/template/cache/ Container templates
/var/lib/vz/dump/ Backup files
/var/log/pve/tasks/ Task logs

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

bastos/skills

conventional-commits

Format commit messages using the Conventional Commits specification. Use when creating commits, writing commit messages, or when the user mentions commits, git commits, or commit messages. Ensures commits follow the standard format for automated tooling, changelog generation, and semantic versioning.

0 0
Explore
bastos/skills

topydo

Manage todo.txt tasks using topydo CLI. Add, list, complete, prioritize, tag, and organize tasks with dependencies, due dates, recurrence, and projects. Use for any task management, todo lists, or when the user mentions tasks, todos, or todo.txt. Requires Python 3 and pip. Works on macOS, Linux, and Windows.

0 0
Explore
bastos/skills

tmuxinator

Use when creating, editing, or debugging tmuxinator project configurations, setting up complex tmux session layouts, or automating development environment startup with multiple windows and panes

0 0
Explore
bastos/skills

swift-review

Review Swift/Xcode codebases, pull requests, local changes, or individual files against Swift best practices including Google's Swift Style Guide, Apple's API Design Guidelines, build performance, memory management, and testing standards. Use this skill whenever the user asks to review Swift code, audit a Swift PR, check Swift style, review an Xcode project, or mentions swift code review, swift lint, swift best practices review, or swift code quality. Also trigger when reviewing .swift files, Package.swift, or Xcode project changes — even if the user just says "review this" or "check this code" and the context involves Swift.

0 0
Explore
bastos/skills

obsidian-daily

Manage Obsidian Daily Notes via obsidian-cli. Create and open daily notes, append entries (journals, logs, tasks, links), read past notes by date, and search vault content. Handles relative dates like "yesterday", "last Friday", "3 days ago". Requires obsidian-cli installed via Homebrew (Mac/Linux) or Scoop (Windows).

0 0
Explore
davila7/claude-code-templates

verl-rl-training

Provides guidance for training LLMs with reinforcement learning using verl (Volcano Engine RL). Use when implementing RLHF, GRPO, PPO, or other RL algorithms for LLM post-training at scale with flexible infrastructure backends.

23,776 2,298
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results