claude-configs/skills/proxmox/SKILL.md

name	description
proxmox	Comprehensive Proxmox VE management - VM lifecycle (start/stop/restart), VM creation/cloning, snapshot management, resource monitoring, LXC containers, storage operations, and backup management. USE WHEN user mentions "proxmox", "vm", "virtual machine", "qemu", "lxc", "container", "hypervisor", or needs VM infrastructure operations.

Proxmox - Virtual Infrastructure Management

When to Activate This Skill

• "list my VMs", "show virtual machines"
• "start/stop/restart VM X"
• "create a new VM", "clone VM"
• "take a snapshot", "rollback to snapshot"
• "check VM resources", "monitor VMs"
• "proxmox status", "hypervisor info"
• "LXC containers", "manage containers"
• "backup VM", "restore from backup"
• Any Proxmox VE infrastructure operations

Quick Start

List All VMs

from proxmox_client import ProxmoxClient
client = ProxmoxClient()

# Get all VMs with status
vms = client.get_all_vms_status()
for vm in vms:
    print(f"VM {vm['vmid']}: {vm['name']} - {vm['status']}")

VM Lifecycle Operations

# Start a VM
client.start_vm(100)

# Stop a VM (graceful)
client.stop_vm(100)

# Force stop
client.stop_vm(100, force=True)

# Restart a VM
client.restart_vm(100)

# Graceful shutdown with timeout
client.shutdown_vm(100, timeout=60)

Create and Clone VMs

# Create new VM
client.create_vm(
    vmid=101,
    name="docker-host-01",
    memory=4096,
    cores=2,
    sockets=1
)

# Clone existing VM
client.clone_vm(
    vmid=100,
    newid=102,
    name="cloned-vm",
    full=True  # Full clone, not linked
)

Snapshot Management

# Create snapshot
client.create_snapshot(
    vmid=100,
    snapname="before-upgrade",
    description="Pre-system upgrade snapshot",
    vmstate=True  # Include RAM for running VMs
)

# List snapshots
snapshots = client.list_snapshots(100)

# Rollback to snapshot
client.rollback_snapshot(100, "before-upgrade")

# Delete snapshot
client.delete_snapshot(100, "before-upgrade")

Resource Monitoring

# Get VM status and resources
status = client.get_vm_status(100)
print(f"CPU: {status['cpu']}")
print(f"Memory: {status['mem']} / {status['maxmem']}")
print(f"Uptime: {status['uptime']}s")

# Get node resources
node_status = client.get_node_status()
print(f"Node CPU: {node_status['cpu']}")
print(f"Node Memory: {node_status['memory']}")

Container Operations

# List LXC containers
containers = client.list_containers()

# Start/stop containers
client.start_container(200)
client.stop_container(200)

CLI Usage

The Python client has a CLI interface for quick operations:

# List all VMs
python3 ~/.claude/skills/proxmox/proxmox_client.py list

# Get VM status
python3 ~/.claude/skills/proxmox/proxmox_client.py status 100

# Start a VM
python3 ~/.claude/skills/proxmox/proxmox_client.py start 100

# Stop a VM
python3 ~/.claude/skills/proxmox/proxmox_client.py stop 100

# List nodes
python3 ~/.claude/skills/proxmox/proxmox_client.py nodes

Key Capabilities

VM Lifecycle

• ✅ List all VMs with status
• ✅ Start, stop, restart, shutdown VMs
• ✅ Create new VMs from scratch
• ✅ Clone existing VMs
• ✅ Delete VMs

Snapshot Management

• ✅ Create snapshots (with/without RAM)
• ✅ List all snapshots
• ✅ Rollback to snapshot
• ✅ Delete snapshots

Monitoring & Resources

• ✅ Real-time VM resource usage (CPU, RAM, disk)
• ✅ Node status and health
• ✅ Storage status and capacity
• ✅ Network interface information

Container (LXC) Operations

• ✅ List containers
• ✅ Start/stop containers
• ✅ Get container status

Backup & Recovery

• ✅ Create VM backups
• ✅ List available backups
• ✅ Backup job management

Storage Operations

• ✅ List storage pools
• ✅ Check storage capacity and usage
• ✅ Storage content listing

Task Management

• ✅ Monitor async task status
• ✅ Wait for task completion
• ✅ Task progress tracking

Configuration

Credentials are stored in:

~/.claude/secrets/proxmox.json

Format:

{
  "host": "10.10.0.11",
  "port": 8006,
  "token_id": "root@pam!jarvis",
  "token_secret": "<secret>",
  "verify_ssl": false,
  "node": "proxmox"
}

MCP Server Integration

For interactive use, the Proxmox MCP server can be loaded on-demand:

# Enable Proxmox MCP
python3 ~/.claude/skills/mcp-manager/mcp_control.py enable proxmox

# Restart Claude Code to activate
# Then use MCP tools directly

The MCP server will be automatically suggested when you use Proxmox-related keywords.

Common Workflows

1. Deploy New VM from Template

# Clone template
upid = client.clone_vm(vmid=9000, newid=101, name="app-server-01")
client.wait_for_task(upid)

# Start the VM
client.start_vm(101)

# Wait for boot and check status
import time
time.sleep(30)
status = client.get_vm_status(101)
print(f"VM Status: {status['status']}")

2. Pre-Upgrade Snapshot Workflow

# Take snapshot before changes
upid = client.create_snapshot(
    vmid=100,
    snapname="pre-upgrade-2025-01-11",
    description="Before system upgrade",
    vmstate=True
)
client.wait_for_task(upid)

# Perform upgrade operations...
# If issues occur, rollback:
# client.rollback_snapshot(100, "pre-upgrade-2025-01-11")

3. Bulk VM Status Check

# Check status of all VMs
vms = client.get_all_vms_status()
for vm in vms:
    if vm['status'] != 'running':
        print(f"⚠️  VM {vm['vmid']} ({vm['name']}) is {vm['status']}")
    else:
        cpu_pct = vm['cpu'] * 100
        mem_pct = (vm['mem'] / vm['maxmem']) * 100 if vm['maxmem'] > 0 else 0
        print(f"✅ VM {vm['vmid']} ({vm['name']}): CPU {cpu_pct:.1f}%, MEM {mem_pct:.1f}%")

4. Emergency VM Operations

# Force stop unresponsive VM
client.stop_vm(100, force=True)

# Or graceful shutdown with fallback
try:
    upid = client.shutdown_vm(100, timeout=120)
    if not client.wait_for_task(upid, timeout=130):
        print("Graceful shutdown timed out, forcing stop...")
        client.stop_vm(100, force=True)
except Exception as e:
    print(f"Shutdown failed: {e}")
    client.stop_vm(100, force=True)

Integration with Home Lab

This skill integrates with Cal's home lab infrastructure:

• VM Management: Documented in /mnt/NV2/Development/claude-home/vm-management/
• Cloud-Init Templates: Standard provisioning configurations
• Networking: 10.10.0.x internal network
• Docker Hosts: Automated Docker VM deployment
• Monitoring: Discord notifications via monitoring system

Supplementary Resources

For comprehensive Proxmox API reference and advanced usage:

read ~/.claude/skills/proxmox/CLAUDE.md

For Proxmox VE API documentation:

• Official API: https://pve.proxmox.com/pve-docs/api-viewer/
• Python Library: https://github.com/proxmoxer/proxmoxer

Security Notes

• API token has full root privileges
• Credentials stored in ~/.claude/secrets/ (700 permissions)
• SSL verification disabled for self-signed certificates
• NEVER commit secrets to git repositories
• Token can be regenerated in Proxmox web UI if compromised

---

Created: 2025-01-11 Author: Jarvis (PAI System) Client Library: ~/.claude/skills/proxmox/proxmox_client.py Version: 1.0.0