proxmox-admin

Files (42)

• DESIGN-project-folder-pattern.md
• SKILL.md
• backup-job.cfg · assets/
• cloud-init-user-data.yaml · assets/
• connection-profile.example.yaml · assets/
• ct-create.json · assets/
• firewall-cluster.fw · assets/
• profile.schema.json · assets/
• sdn-vlan-zone.json · assets/
• vm-create.json · assets/
• api-tokens.md · references/
• backup-pbs.md · references/
• cli-cheat-sheet.md · references/
• cluster-ha.md · references/
• container-management.md · references/
• iac-terraform-ansible.md · references/
• networking-sdn.md · references/
• onboarding.md · references/
• pegaprox.md · references/
• project-folder.md · references/
• remote-cli-tools.md · references/
• security-hardening.md · references/
• storage.md · references/
• troubleshooting.md · references/
• vm-management.md · references/
• profile.sh · scripts/lib/
• pmx-api · scripts/
• pmx-backup · scripts/
• pmx-cluster · scripts/
• pmx-ct · scripts/
• pmx-cv4 · scripts/
• pmx-cv4pve-install · scripts/
• pmx-cv4pve-sync · scripts/
• pmx-doctor · scripts/
• pmx-init · scripts/
• pmx-inventory · scripts/
• pmx-onboard · scripts/
• pmx-profile · scripts/
• pmx-ssh · scripts/
• pmx-storage · scripts/
• pmx-token-create · scripts/
• pmx-vm · scripts/

SKILL.md (first lines)

# Proxmox VE Administration

## Overview

This skill drives Proxmox VE 8.x/9.x **remotely** from the user's workstation.
It maintains a per-instance **connection profile** (SSH credentials + API
token + defaults). Every helper script reads the active profile, so the
agent never needs to ask the user for credentials twice.

The profile can live in either of two places:

1. **A project folder** that you own — recommended. Auto-detected when a
   `.proxmox-admin/` directory is found in `$PWD` or any ancestor. Lets
   you version-control profiles, inventory, decisions, and runbooks
   together. Scaffold with `scripts/pmx-init`. See
   [project-folder.md](references/project-folder.md).
2. **`~/.config/proxmox-admin/`** — the historical default. Used when no
   project folder is detected. Backwards compatible with all prior versions.

Two execution paths run side by side:

1. **SSH + curl helpers** (`scripts/pmx-*`) — always available, even with
   only an SSH key. Required for shell-level ops with no REST equivalent.
2. **cv4pve-cli** (`scripts/pmx-cv4`) — optional fast path. Single binary,
   kubectl-style contexts, full REST coverage. Recommended.

Profiles are the canonical source of truth. `pmx-cv4pve-sync` mirrors them
into cv4pve-cli contexts so the user never duplicates credentials.

## Decision tree — start here

```
Is there an active profile?
  (.proxmox-admin/active in cwd or ancestor, OR ~/.config/proxmox-admin/active)
├── NO  →  For a single-throwaway profile: read references/onboarding.md, run scripts/pmx-onboard.
│           For anything you want to keep:  run scripts/pmx-init <dir>, then pmx-onboard from inside.
│           See references/project-folder.md for the recommended pattern.
└── YES →  Run scripts/pmx-doctor to confirm reachability.
          ├── Any check fails       → references/troubleshooting.md
          └── All checks pass       → Pick the task lane below.
```

### Task lanes

| User intent | Primary helper | Deep reference |
|-------------|----------------|----------------|
| Provision / manage a VM | `scripts/pmx-vm` or `pmx-cv4 do start guest --guest X` | [vm-management.md](references/vm-management.md) |
| Provision / manage an LXC container | `scripts/pmx-ct` | [container-management.md](references/container-management.md) |
| Storage (ZFS, LVM-thin, NFS, Ceph) | `scripts/pmx-storage` | [storage.md](references/storage.md) |
| Networking / SDN (zones, VNets, Fabrics, BGP) | `scripts/pmx-ssh 'pvesh ...'` | [networking-sdn.md](references/networking-sdn.md) |
| Cluster, HA, quorum, dynamic load balancer | `scripts/pmx-cluster` | [cluster-ha.md](references/cluster-ha.md) |
| Backups, restore, PBS | `scripts/pmx-backup` | [backup-pbs.md](references/backup-pbs.md) |
| API tokens, roles, ACLs | `scripts/pmx-token-create` | [api-tokens.md](references/api-tokens.md) |
| Security hardening | (multiple) | [security-hardening.md](references/security-hardening.md) |
| Terraform / Ansible / IaC | n/a (delegate to provider) | [iac-terraform-ansible.md](references/iac-terraform-ansible.md) |
| PegaProx / multi-cluster orchestration | n/a (community tool) | [pegaprox.md](references/pegaprox.md) |
| Compare or install remote CLIs | `scripts/pmx-cv4pve-install` | [remote-cli-tools.md](references/remote-cli-tools.md) |
| Scaffold a project folder for this skill | `scripts/pmx-init` | [project-folder.md](references/project-folder.md) |
| Capture live state into diffable markdown | `scripts/pmx-inventory snapshot` | [project-folder.md](references/project-folder.md) |
| Look up any CLI flag fast | — | [cli-cheat-sheet.md](references/cli-cheat-sheet.md) |
| Anything broken | `scripts/pmx-doctor` | [troubleshooting.md](references/troubleshooting.md) |

## Project layout (recommended)

For anything beyond a single throwaway profile, scaffold a **project
folder** that holds connection profiles, inventory, decisions, and
runbooks together in version control:

```bash
mkdir my-proxmox-project && cd my-proxmox-project
~/.claude/skills/proxmox-admin/scripts/pmx-init
```

The skill auto-detects `.proxmox-admin/` in `$PWD` or any ancestor and
uses it as the config root. Falls back to `~/.config/proxmox-admin/` if
no project folder is found — backwards compatible with prior versions.

Full layout, secret-handling conventions, cross-OS notes, and migration
path from `~/.config/`: **[references/project-folder.md](references/project-folder.md)**.

## Onboarding workflow (first run)

Before any other action, if no profile exists yet:

```bash
# (Recommended) scaffold a project folder first
scripts/pmx-init <project-dir>
cd <project-dir>
cp secrets/env.sh.example secrets/env.sh
$EDITOR secrets/env.sh                  # fill in the token secret(s) later

# Profile creation + verification
scripts/pmx-onboard            # interactive wizard, writes 0600 YAML
scripts/pmx-doctor             # verifies SSH + REST reachability
scripts/pmx-inventory snapshot # capture initial inventory as diffable markdown
scripts/pmx-cv4pve-install     # optional but recommended
scripts/pmx-cv4pve-sync --activate
```

Full prerequisites and the discovery commands to gather the inputs the
wizard asks for: **[references/onboarding.md](references/onboarding.md)**.

If the user has no API token yet, the wizard can run without one; then:

```bash
scripts/pmx-token-create skill /      # creates user, role, ACL, token
# Capture the secret it prints once; re-run pmx-onboard to embed it
```

## Daily workflow (after onboarding)

```bash
# Pick / inspect profile
scripts/pmx-profile list                # mark active with *
scripts/pmx-profile use prod-east       # switch active

# Read-only sanity
scripts/pmx-cv4 get vms                 # or: pmx-cv4 get cts, get nodes
scripts/pmx-ssh 'pvesm status'

From kryptobaseddev/awesome-skills, MIT.

More from kryptobaseddev/awesome-skills