claude-configs/skills/proxmox/README.md

Proxmox Skill for Jarvis PAI

Comprehensive Proxmox VE management for virtual infrastructure operations.

Overview

This skill provides full control over Proxmox VE hypervisor operations including:

• VM lifecycle management (start/stop/restart)
• VM creation and cloning
• Snapshot management
• Resource monitoring
• LXC container operations
• Storage and backup management

Components

1. Python Client Library (proxmox_client.py)

High-level Python interface for Proxmox API operations.

Usage:

from proxmox_client import ProxmoxClient

client = ProxmoxClient()
vms = client.list_vms()
client.start_vm(100)

2. MCP Server (mcp_server.py)

Model Context Protocol server for Claude Code integration.

Available MCP Tools:

• proxmox_list_vms - List all VMs with status
• proxmox_get_vm - Get detailed VM information
• proxmox_start_vm - Start a VM
• proxmox_stop_vm - Stop a VM
• proxmox_restart_vm - Restart a VM
• proxmox_create_snapshot - Create VM snapshot
• proxmox_list_snapshots - List all snapshots
• proxmox_rollback_snapshot - Rollback to snapshot
• proxmox_delete_snapshot - Delete snapshot
• proxmox_clone_vm - Clone a VM
• proxmox_get_node_status - Get node resource status
• proxmox_list_containers - List LXC containers
• proxmox_start_container - Start container
• proxmox_stop_container - Stop container
• proxmox_list_storage - List storage pools

3. Skill Documentation

• SKILL.md - Quick reference and common workflows
• README.md - This file, comprehensive setup and usage
• examples/ - Working code examples

Installation

Prerequisites

• Python 3.8+
• Proxmox VE 7.0+ with API access
• API token with appropriate permissions

Setup Steps

1. Install Dependencies

pip install --user proxmoxer requests

2. Create API Token (if not done already)

• Navigate to Proxmox web UI: https://10.10.0.11:8006
• Go to: Datacenter → Permissions → API Tokens
• Click "Add" and create token with:
  • User: root@pam
  • Token ID: jarvis
  • Privilege Separation: UNCHECKED (important!)
• Copy the token secret immediately

3. Configure Credentials Credentials are stored in ~/.claude/secrets/proxmox.json:

{
  "host": "10.10.0.11",
  "port": 8006,
  "token_id": "root@pam!jarvis",
  "token_secret": "YOUR-TOKEN-SECRET",
  "verify_ssl": false,
  "node": "proxmox"
}

4. Test Connection

python3 ~/.claude/skills/proxmox/proxmox_client.py list

Usage

CLI Interface

Quick operations from the command line:

# 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

Python API

Use the client library in your scripts:

from proxmox_client import ProxmoxClient

client = ProxmoxClient()

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

# Start a VM
client.start_vm(100)

# Create snapshot
client.create_snapshot(100, "before-upgrade", "Pre-upgrade backup")

# Clone a VM
client.clone_vm(vmid=100, newid=101, name="cloned-vm")

# Monitor resources
status = client.get_vm_status(100)
print(f"CPU: {status['cpu']*100:.1f}%")
print(f"Memory: {status['mem']/(1024**3):.1f}GB")

MCP Integration

Enable the Proxmox MCP server for Claude Code:

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

# Restart Claude Code to activate

Then use natural language with Claude:

• "List all my VMs"
• "Start VM 100"
• "Create a snapshot of the docker-tdarr VM"
• "Clone the ubuntu-template to VM 150"

Examples

See examples/vm_operations.py for comprehensive examples:

python3 ~/.claude/skills/proxmox/examples/vm_operations.py

Examples include:

• Listing VMs with detailed status
• VM lifecycle management
• Snapshot workflows
• Cloning VMs
• Resource monitoring
• Finding VMs by name
• Batch operations

Common Workflows

Pre-Upgrade Snapshot

# Before making system changes
client.create_snapshot(
    vmid=100,
    snapname="pre-upgrade-2025-01-11",
    description="Before system upgrade",
    vmstate=True  # Include RAM
)

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

Deploy VM from Template

# Clone template
upid = client.clone_vm(vmid=100, newid=101, name="new-server")
client.wait_for_task(upid)

# Start VM
client.start_vm(101)

Monitor High Resource Usage

vms = client.get_all_vms_status()
for vm in vms:
    if vm['status'] == 'running':
        mem_pct = (vm['mem'] / vm['maxmem']) * 100
        if mem_pct > 80:
            print(f"⚠️  VM {vm['vmid']} using {mem_pct:.1f}% memory")

Bulk VM Operations

# Get all stopped VMs
vms = client.get_all_vms_status()
stopped = [vm for vm in vms if vm['status'] == 'stopped']

# Start all (be careful!)
for vm in stopped:
    print(f"Starting VM {vm['vmid']}...")
    client.start_vm(vm['vmid'])

Integration with Home Lab

This skill integrates with Cal's home lab infrastructure:

• Current VMs: 17 total (11 running, 6 stopped)
• Running Services:
  • hass-io (Home Assistant)
  • docker-tdarr (Transcoding)
  • plex (Media Server)
  • Multiple Docker hosts for various services
• Network: 10.10.0.x internal network
• Documentation: /mnt/NV2/Development/claude-home/vm-management/

Security

• API token stored securely in ~/.claude/secrets/ (700 permissions)
• Token has full root privileges (Privilege Separation disabled)
• SSL verification disabled for self-signed certificates
• Credentials file: 600 permissions (read/write owner only)
• NEVER commit secrets to git repositories

Troubleshooting

Connection Issues

Problem: "401 Unauthorized" errors Solution: Check that Privilege Separation is unchecked for the API token

Problem: "hostname lookup failed" Solution: Verify the node name in credentials matches your Proxmox node name

Problem: "0 VMs found" but VMs exist Solution: Token doesn't have permissions - recreate with Privilege Separation unchecked

Testing Connection

from proxmox_client import ProxmoxClient
client = ProxmoxClient()
print(client.list_nodes())  # Should show node
print(client.list_vms())     # Should show VMs

Regenerating API Token

If token is compromised:

1. Go to Proxmox: Datacenter → Permissions → API Tokens
2. Delete root@pam!jarvis token
3. Create new token with same settings
4. Update ~/.claude/secrets/proxmox.json with new secret

API Reference

ProxmoxClient Methods

VM Lifecycle:

• list_vms(node) - List all VMs
• get_vm(vmid, node) - Get VM details
• start_vm(vmid, node) - Start VM
• stop_vm(vmid, node, force) - Stop VM
• restart_vm(vmid, node) - Restart VM
• shutdown_vm(vmid, node, timeout) - Graceful shutdown

VM Management:

• create_vm(vmid, name, **kwargs) - Create new VM
• clone_vm(vmid, newid, name, node, full) - Clone VM
• delete_vm(vmid, node, purge) - Delete VM

Snapshots:

• list_snapshots(vmid, node) - List snapshots
• create_snapshot(vmid, snapname, description, vmstate, node) - Create snapshot
• delete_snapshot(vmid, snapname, node) - Delete snapshot
• rollback_snapshot(vmid, snapname, node) - Rollback to snapshot

Monitoring:

• get_vm_status(vmid, node) - Get VM status and resources
• get_node_status(node) - Get node status
• get_all_vms_status(node) - Get all VMs with status summary

Containers:

• list_containers(node) - List LXC containers
• start_container(vmid, node) - Start container
• stop_container(vmid, node) - Stop container

Storage:

• list_storage(node) - List storage pools
• get_storage_status(storage, node) - Get storage details

Tasks:

• get_task_status(upid, node) - Get task status
• wait_for_task(upid, node, timeout, poll_interval) - Wait for task completion

Utilities:

• get_vm_by_name(name, node) - Find VM by name
• list_nodes() - List all cluster nodes

Resources

• Proxmox VE API: https://pve.proxmox.com/pve-docs/api-viewer/
• Proxmoxer Library: https://github.com/proxmoxer/proxmoxer
• Skill Documentation: ~/.claude/skills/proxmox/SKILL.md

Version History

• v1.0.0 (2025-01-11) - Initial release
  • Python client library with full VM management
  • MCP server with 15 tools
  • CLI interface for quick operations
  • Example scripts and workflows
  • Secure credential management

Support

For issues or questions:

1. Check troubleshooting section above
2. Review examples in examples/
3. Consult Proxmox API documentation
4. Ask Jarvis for help with skill usage

---

Author: Jarvis (PAI System) Created: 2025-01-11 License: Personal use for Cal's home lab infrastructure