claude-configs/skills/proxmox/SKILL.md

name	description
proxmox	Proxmox VE management - VM lifecycle, creation/cloning, snapshots, monitoring, LXC containers, storage, and backups. USE WHEN user mentions "proxmox", "vm", "virtual machine", "qemu", "lxc", "container", or "hypervisor".

Proxmox - Virtual Infrastructure Management

SCOPE: Only use in claude-home or vm-management contexts. Do not activate in unrelated projects.

When to Activate

• "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"
• "LXC containers", "manage containers"
• "backup VM", "restore from backup"

Approach: MCP First, Python Fallback

Option 1: Proxmox MCP (Preferred)

Load the Proxmox MCP on-demand for interactive use:

python3 ~/.claude/skills/mcp-manager/mcp_control.py enable proxmox
# Restart Claude Code to activate, then use MCP tools directly

The MCP provides direct API access without writing Python code.

Option 2: Python Client (Complex/Batch Operations)

For multi-step automation, batch operations, or when MCP is unavailable:

from proxmox_client import ProxmoxClient
client = ProxmoxClient()

CLI shorthand:

python3 ~/.claude/skills/proxmox/proxmox_client.py [list|status|start|stop|nodes] [vmid]

Key Capabilities

• VM Lifecycle: list, start, stop, restart, shutdown, create, clone, delete
• Snapshots: create (with/without RAM), list, rollback, delete
• Monitoring: real-time CPU/RAM/disk, node health, storage capacity
• LXC Containers: list, start, stop, status
• Backups: create, list, job management
• Storage: pool listing, capacity, content
• Tasks: async task monitoring, wait for completion

Common Workflows

Deploy VM from Template

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

Pre-Upgrade Snapshot

upid = client.create_snapshot(vmid=100, snapname="pre-upgrade", description="Before upgrade", vmstate=True)
client.wait_for_task(upid)
# If issues: client.rollback_snapshot(100, "pre-upgrade")

Bulk Status Check

vms = client.get_all_vms_status()
for vm in vms:
    if vm['status'] != 'running':
        print(f"VM {vm['vmid']} ({vm['name']}) is {vm['status']}")

Configuration

Credentials: ~/.claude/secrets/proxmox.json

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

Integration

• VM docs: /mnt/NV2/Development/claude-home/vm-management/
• Network: 10.10.0.x internal network
• API docs: https://pve.proxmox.com/pve-docs/api-viewer/
• Python lib: https://github.com/proxmoxer/proxmoxer

Security

• API token has full root privileges
• Credentials in ~/.claude/secrets/ (700 permissions)
• SSL verification disabled (self-signed certs)
• Never commit secrets to git

---

Client Library: ~/.claude/skills/proxmox/proxmox_client.py Updated: 2026-03-05 Version: 2.0.0