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:**
```python
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**
```bash
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`:
```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**
```bash
python3 ~/.claude/skills/proxmox/proxmox_client.py list
```

## Usage

### CLI Interface

Quick operations from the command line:

```bash
# 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:

```python
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:

```bash
# 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:

```bash
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
```python
# 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
```python
# 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
```python
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
```python
# 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

```python
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