{"id":"91b42130-334a-41ef-a045-b3548e5f557b","entityType":"agent","slug":"clawhub-zw008-proxmox-aiops","name":"proxmox-aiops","canonicalUrl":"https://www.xpersona.co/agent/clawhub-zw008-proxmox-aiops","canonicalPath":"/agent/clawhub-zw008-proxmox-aiops","generatedAt":"2026-10-10T03:06:08.324Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T19:54:31.160Z","emptyReason":null},"description":"Use this skill whenever the user needs to manage VMs and containers on Proxmox VE — list/inspect/configure VMs, power and lifecycle (start/stop/shutdown/reboot/reconfigure/clone/delete/migrate), snapshots (create/delete/list/rollback), disk grow/move, vzdump backups (create/list/restore), LXC containers (list/start/stop), cluster/node status, cluster resource inventory, async task polling + logs, free-VMID lookup, HA status, resource pools, firewall inspection, guest-agent ping, and storage listing. Also use it to diagnose cluster health — rank nodes by CPU/memory/disk pressure and scan guests for saturation (read-only RCA). Always use this skill for \"list proxmox vms\", \"start proxmox vm\", \"stop proxmox vm\", \"proxmox snapshot\", \"proxmox backup\", \"restore proxmox vm\", \"resize proxmox disk\", \"proxmox vm status\", \"migrate proxmox vm\", \"proxmox container\", \"proxmox ha\", \"proxmox pool\", \"proxmox firewall\", \"list proxmox storage\", \"proxmox node pressure\", or \"why is proxmox slow\" when the context is explicitly Proxmox / Proxmox VE / PVE. Do NOT use for non-Proxmox hypervisors, Kubernetes, or cloud providers. Broad coverage of common Proxmox operations, with a built-in governance harness (audit, token budget, undo, risk-tier labels).","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.1K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s171xgnmqse0nqvgqvqnaq5f9183kyre:proxmox-aiops","sourceUrl":"https://clawhub.ai/zw008/proxmox-aiops","homepage":"https://clawhub.ai/zw008/skills/proxmox-aiops","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/zw008/proxmox-aiops","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/zw008/skills/proxmox-aiops","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":66,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"proxmox-aiops technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T19:54:31.160Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T19:54:31.160Z","emptyReason":null},"stars":null,"forks":null,"downloads":2052,"packageName":null,"latestVersion":"0.13.3","tractionLabel":"2.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T19:54:31.160Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T19:54:31.160Z","lastCrawledAt":"2026-10-09T19:54:31.160Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T19:54:31.160Z","lastVerifiedAt":null,"highlights":[{"version":"0.13.3","createdAt":"2026-09-15T06:16:49.059Z","changelog":"proxmox-aiops 0.13.3 - Removed the skill-card.md file from the project. - No functional or user-facing changes.","fileCount":7,"zipByteSize":15023},{"version":"0.13.2","createdAt":"2026-09-12T14:40:14.942Z","changelog":"- Updated OpenClaw plugin installation example in documentation to use the `@zw008/proxmox-aiops` namespace. - Removed the redundant skill-card.md file from the repository. - No functional or interface changes to the skill code itself.","fileCount":7,"zipByteSize":14901},{"version":"0.13.1","createdAt":"2026-09-12T10:23:51.301Z","changelog":"- Added OpenClaw plugin installation instructions and server integration details to documentation. - The file skill-card.md was removed. - SKILL.md updated with instructions for use as an OpenClaw plugin and new compatibility note for uvx. - No functional changes to the skill's core operations.","fileCount":7,"zipByteSize":14944},{"version":"0.13.0","createdAt":"2026-09-12T01:11:36.705Z","changelog":"proxmox-aiops 0.13.0 - Updated metadata: the skill no longer requires a specific config file, but supports either the \"proxmox-aiops\" or \"uvx\" binaries, and now lists both PROXMOX_AIOPS_CONFIG and PROXMOX_TARGET_SECRET as optional environment variables. - Compatibility and requirements information improved for clarity and flexibility. - Documentation and metadata enhancements in SKILL.md. - Removed the obsolete skill-card.md file.","fileCount":7,"zipByteSize":14663},{"version":"0.12.0","createdAt":"2026-08-10T06:53:36.952Z","changelog":"- Removed the sample file skill-card.md from the project. - No functionality or behavioral changes to the skill itself in this release.","fileCount":7,"zipByteSize":14801},{"version":"0.11.0","createdAt":"2026-08-03T05:54:33.182Z","changelog":"- Removed the file skill-card.md from the project. - No changes to skill features or code behavior. - Documentation and functionality remain unchanged.","fileCount":7,"zipByteSize":14877},{"version":"0.10.0","createdAt":"2026-08-02T14:49:53.903Z","changelog":"proxmox-aiops 0.10.0 - Removed the redundant skill-card.md file. - Updated references/capabilities.md to reflect recent changes. - No changes to core functionality or usage.","fileCount":7,"zipByteSize":14861},{"version":"0.9.0","createdAt":"2026-08-02T09:41:19.412Z","changelog":"- Removed the file skill-card.md from the project. - No changes to any functionality or other documentation. - Version 0.9.0 is a maintenance release focused on cleanup.","fileCount":7,"zipByteSize":14881}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s171xgnmqse0nqvgqvqnaq5f9183kyre:proxmox-aiops","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s171xgnmqse0nqvgqvqnaq5f9183kyre:proxmox-aiops` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/zw008/proxmox-aiops before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-proxmox-aiops/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-proxmox-aiops/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-proxmox-aiops/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zw008-proxmox-aiops/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zw008-proxmox-aiops/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zw008-proxmox-aiops/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T03:06:08.318Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-proxmox-aiops/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-proxmox-aiops/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-proxmox-aiops/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-proxmox-aiops/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T19:54:31.160Z","emptyReason":null},"readme":"Skill: proxmox-aiops\n\nOwner: zw008\n\nSummary: Use this skill whenever the user needs to manage VMs and containers on Proxmox VE — list/inspect/configure VMs, power and lifecycle (start/stop/shutdown/reboot/reconfigure/clone/delete/migrate), snapshots (create/delete/list/rollback), disk grow/move, vzdump backups (create/list/restore), LXC containers (list/start/stop), cluster/node status, cluster resource inventory, async task polling + logs, free-VMID lookup, HA status, resource pools, firewall inspection, guest-agent ping, and storage listing. Also use it to diagnose cluster health — rank nodes by CPU/memory/disk pressure and scan guests for saturation (read-only RCA). Always use this skill for \"list proxmox vms\", \"start proxmox vm\", \"stop proxmox vm\", \"proxmox snapshot\", \"proxmox backup\", \"restore proxmox vm\", \"resize proxmox disk\", \"proxmox vm status\", \"migrate proxmox vm\", \"proxmox container\", \"proxmox ha\", \"proxmox pool\", \"proxmox firewall\", \"list proxmox storage\", \"proxmox node pressure\", or \"why is proxmox slow\" when the context is explicitly Proxmox / Proxmox VE / PVE. Do NOT use for non-Proxmox hypervisors, Kubernetes, or cloud providers. Broad coverage of common Proxmox operations, with a built-in governance harness (audit, token budget, undo, risk-tier labels).\n\nTags: latest:0.13.3\n\nVersion history:\n\nv0.13.3 | 2026-09-15T06:16:49.059Z | auto\n\nproxmox-aiops 0.13.3\n\n- Removed the skill-card.md file from the project.\n- No functional or user-facing changes.\n\nv0.13.2 | 2026-09-12T14:40:14.942Z | auto\n\n- Updated OpenClaw plugin installation example in documentation to use the `@zw008/proxmox-aiops` namespace.\n- Removed the redundant skill-card.md file from the repository.\n- No functional or interface changes to the skill code itself.\n\nv0.13.1 | 2026-09-12T10:23:51.301Z | auto\n\n- Added OpenClaw plugin installation instructions and server integration details to documentation.\n- The file skill-card.md was removed.\n- SKILL.md updated with instructions for use as an OpenClaw plugin and new compatibility note for uvx.\n- No functional changes to the skill's core operations.\n\nv0.13.0 | 2026-09-12T01:11:36.705Z | auto\n\nproxmox-aiops 0.13.0\n\n- Updated metadata: the skill no longer requires a specific config file, but supports either the \"proxmox-aiops\" or \"uvx\" binaries, and now lists both PROXMOX_AIOPS_CONFIG and PROXMOX_TARGET_SECRET as optional environment variables.\n- Compatibility and requirements information improved for clarity and flexibility.\n- Documentation and metadata enhancements in SKILL.md.\n- Removed the obsolete skill-card.md file.\n\nv0.12.0 | 2026-08-10T06:53:36.952Z | auto\n\n- Removed the sample file skill-card.md from the project.\n- No functionality or behavioral changes to the skill itself in this release.\n\nv0.11.0 | 2026-08-03T05:54:33.182Z | auto\n\n- Removed the file skill-card.md from the project.\n- No changes to skill features or code behavior.\n- Documentation and functionality remain unchanged.\n\nv0.10.0 | 2026-08-02T14:49:53.903Z | auto\n\nproxmox-aiops 0.10.0\n\n- Removed the redundant skill-card.md file.\n- Updated references/capabilities.md to reflect recent changes.\n- No changes to core functionality or usage.\n\nv0.9.0 | 2026-08-02T09:41:19.412Z | auto\n\n- Removed the file skill-card.md from the project.\n- No changes to any functionality or other documentation.\n- Version 0.9.0 is a maintenance release focused on cleanup.\n\nv0.8.0 | 2026-07-21T15:30:46.168Z | auto\n\n- Removed the file: skill-card.md\n- No changes to functionality or user-facing features\n- Maintains existing governance, audit, undo, and risk-tier guards\n- Documentation and usage remain unchanged\n\nv0.7.0 | 2026-07-21T09:42:41.881Z | auto\n\nproxmox-aiops 0.7.0\n\n- Governance terminology updated: \"policy\" references removed in favor of \"token budget\" and \"risk-tier labels\" across docs and descriptions.\n- Documentation improved: clearer explanation of built-in governance harness, updated compatibility, and task coverage.\n- Removed the skill-card.md file.\n- References reworked and setup guidance updated for clarity and accuracy.\n\nv0.6.0 | 2026-07-20T11:17:03.690Z | auto\n\n- Removed the sample file skill-card.md.\n- No other user-facing changes.\n\nv0.5.0 | 2026-07-19T03:53:02.101Z | auto\n\n**Summary:** \nAdds cluster/guest diagnostics and health triage tools; expands governance and removes legacy metadata.\n\n- Introduced diagnostics tools for node pressure and guest health (RCA/triage support).\n- Tool count increases from 39 to 43, covering new read-only diagnostics.\n- Now supports health-driven usage, e.g., \"why is proxmox slow\" and \"node pressure\".\n- Improved documentation and metadata for discoverability (summary, tags, slug, etc.).\n- Removed the deprecated skill-card.md file; added agent guardrails documentation.\n- General updates for clarity, feature coverage, and governance explainer.\n\nv0.4.0 | 2026-07-17T05:54:04.969Z | auto\n\n- Removed the file skill-card.md.\n- No other user-facing changes or new features in this release.\n\nv0.3.0 | 2026-07-13T13:07:14.513Z | auto\n\n- Removed the skill-card.md file for cleanup and simplification.\n- Updated SKILL.md documentation with streamlined content and clarified workflow guidance.\n- No changes to toolset; user functionality and compatibility remain unchanged.\n\nv0.2.0 | 2026-06-27T02:23:35.199Z | auto\n\nVersion 0.2.0 of proxmox-aiops introduces expanded Proxmox VE management coverage.\n\n- Added support for disk operations (grow/move), vzdump backup/restore, cluster inventory, HA status, pools, VM firewall, and guest agent ping.\n- Number of MCP tools increased from 23 to 39, including new read and write operations.\n- Broader CLI commands and usage documentation to reflect the expanded feature set.\n- Skill-card.md file removed for cleanup.\n- Documentation updated for new workflows and capability details.\n\nv0.1.0 | 2026-06-22T05:51:44.374Z | user\n\nv0.1.0 first release: standalone governed Proxmox VE ops — 23 MCP tools with built-in audit/budget/undo/risk-tier harness\n\nArchive index:\n\nArchive v0.13.3: 7 files, 15023 bytes\n\nFiles: references/agent-guardrails.md (4785b), references/capabilities.md (4523b), references/cli-reference.md (2012b), references/setup-guide.md (2363b), skill-card.md (2928b), SKILL.md (15970b), _meta.json (133b)\n\nFile v0.13.3:SKILL.md\n\n---\nname: proxmox-aiops\nslug: proxmox-aiops\ndisplayName: \"Proxmox AIops\"\nsummary: \"Governed Proxmox VE VM/container ops — 43 MCP tools with audit, budget, undo & risk-tier guards.\"\nlicense: MIT\nhomepage: https://github.com/AIops-tools/Proxmox-AIops\ntags: [aiops, mcp, governance, proxmox]\ndescription: >\n Use this skill whenever the user needs to manage VMs and containers on Proxmox VE — list/inspect/configure VMs, power and lifecycle (start/stop/shutdown/reboot/reconfigure/clone/delete/migrate), snapshots (create/delete/list/rollback), disk grow/move, vzdump backups (create/list/restore), LXC containers (list/start/stop), cluster/node status, cluster resource inventory, async task polling + logs, free-VMID lookup, HA status, resource pools, firewall inspection, guest-agent ping, and storage listing.\n Also use it to diagnose cluster health — rank nodes by CPU/memory/disk pressure and scan guests for saturation (read-only RCA).\n Always use this skill for \"list proxmox vms\", \"start proxmox vm\", \"stop proxmox vm\", \"proxmox snapshot\", \"proxmox backup\", \"restore proxmox vm\", \"resize proxmox disk\", \"proxmox vm status\", \"migrate proxmox vm\", \"proxmox container\", \"proxmox ha\", \"proxmox pool\", \"proxmox firewall\", \"list proxmox storage\", \"proxmox node pressure\", or \"why is proxmox slow\" when the context is explicitly Proxmox / Proxmox VE / PVE.\n Do NOT use for non-Proxmox hypervisors, Kubernetes, or cloud providers.\n Broad coverage of common Proxmox operations, with a built-in governance harness (audit, token budget, undo, risk-tier labels).\ninstaller:\n kind: uv\n package: proxmox-aiops\nargument-hint: \"[vmid or describe your Proxmox task]\"\nallowed-tools:\n - Bash\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"proxmox-aiops\",\"uvx\"]},\"optional\":{\"env\":[\"PROXMOX_AIOPS_CONFIG\",\"PROXMOX_TARGET_SECRET\"]},\"homepage\":\"https://github.com/AIops-tools/Proxmox-AIops\",\"emoji\":\"🧱\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n Standalone, self-governed Proxmox VE operations. The governance harness (audit, token/runaway budget, undo, risk-tier labels) is bundled in the package — no external skill-family dependency.\n All write operations are audited to a local SQLite DB under ~/.proxmox-aiops/ (relocatable via PROXMOX_AIOPS_HOME).\n Credentials: Each Proxmox target requires a per-target secret env var in ~/.proxmox-aiops/.env following the pattern PROXMOX__SECRET (API token UUID for token auth, or login password). Secrets are never logged or echoed; .env should be chmod 600.\n Destructive operations (vm stop/delete/snapshot-delete/snapshot-rollback, ct stop) require double confirmation at the CLI layer and support --dry-run. All write tools pass through the @governed_tool decorator (budget guard + audit + risk-tier tagging). Reversible writes record an inverse undo descriptor to the undo store.\n Webhooks: none — no outbound network calls beyond the configured Proxmox API endpoint.\n SSL: verify_ssl defaults to true; disable only for self-signed lab certificates.\n Transitive dependencies: proxmoxer (Proxmox API client) and the MCP SDK. No post-install scripts or background services.\n---\n\n# Proxmox AIops\n\n> **Disclaimer**: This is a community-maintained open-source project and is **not affiliated with, endorsed by, or sponsored by Proxmox Server Solutions GmbH.** \"Proxmox\" is a trademark of its owner. Source code is publicly auditable at [github.com/AIops-tools/Proxmox-AIops](https://github.com/AIops-tools/Proxmox-AIops) under the MIT license.\n\nGoverned VM and container lifecycle operations for Proxmox VE — **43 MCP tools**, every one wrapped with the bundled `@governed_tool` harness: a local unified audit log under `~/.proxmox-aiops/`, token/runaway budget guard, undo-token recording, and descriptive risk-tier labels.\n\n> **Standalone**: the governance harness is bundled in the package (`proxmox_aiops.governance`) — proxmox-aiops has no external skill-family dependency. Coverage focuses on common Proxmox operations and is not yet exhaustive.\n\n## What This Skill Does\n\n| Category | Tools | Count | Read or Write |\n|----------|-------|:-----:|:-------------:|\n| **VM Lifecycle** | list, get, config, start, stop, shutdown, reboot, reconfigure, clone, delete, migrate | 11 | 3 read / 8 write |\n| **Snapshots** | create, delete, list, rollback | 4 | 1 read / 3 write |\n| **Disk** | resize (grow-only), move | 2 | 0 read / 2 write |\n| **Backups (vzdump)** | create, list, restore | 3 | 1 read / 2 write |\n| **LXC Containers** | list, start, stop | 3 | 1 read / 2 write |\n| **Cluster / Tasks** | node list, cluster status, task poll, cluster resources, node status, task log, next vmid | 7 | 7 read |\n| **HA** | status, resource list | 2 | 2 read |\n| **Pools** | list, members | 2 | 2 read |\n| **Firewall** | vm rules, cluster status | 2 | 2 read |\n| **Guest Agent** | ping | 1 | 1 read |\n| **Storage** | list pools, list content | 2 | 2 read |\n| **Diagnostics / RCA** | node-pressure, guest-health | 2 | 2 read |\n\n## Quick Install\n\n```bash\nuv tool install proxmox-aiops\nproxmox-aiops doctor\n```\n\nOr as an OpenClaw plugin, which installs this skill and its MCP server together:\n\n```bash\nopenclaw plugins install clawhub:@zw008/proxmox-aiops\nopenclaw skills info proxmox-aiops # expect: Visible to model: yes\n```\n\nNeeds `uvx` on `PATH`: the MCP server is fetched with uv, pinned to this release.\n\n## When to Use This Skill\n\n- List/inspect Proxmox QEMU VMs and their config\n- Power ops: start, hard-stop, graceful shutdown, reboot\n- Reconfigure (cores/memory), clone, delete, or migrate a VM between nodes\n- Grow a VM disk (grow-only — shrink is refused) or move it to another storage\n- Create, list, and restore vzdump backups\n- Create / delete / list / roll back VM snapshots\n- Manage LXC containers (list, start, stop)\n- Inspect cluster nodes, quorum, the `/cluster/resources` inventory, node load/mem, and poll async tasks + fetch their logs by UPID; get a free VMID\n- Check HA status / HA-managed resources (handles \"HA not configured\" gracefully)\n- List resource pools and their members\n- Inspect VM firewall rules and the cluster firewall enable state (read-only)\n- Ping a VM's QEMU guest agent\n- List storage pools and their content (ISOs, disk images, backups)\n- **Diagnose** cluster health: rank nodes by CPU/memory/root-fs pressure, and scan VMs/containers for stopped guests, memory saturation, and disks near full — each finding cites the measured number and a concrete action (read-only RCA)\n\n**Do NOT use when** the target is not Proxmox VE (other hypervisors, Kubernetes, or cloud providers are out of scope for this skill).\n\n## Common Workflows\n\n### Triage a \"cluster feels slow\" complaint (read-only)\n\n1. `proxmox-aiops diagnose node-pressure` → worst-first table of nodes over the CPU/mem/disk thresholds, each row citing the measured % and the fix\n2. `proxmox-aiops diagnose guest-health` → guests near their memory ceiling or with disks near full, plus the list of stopped guests\n3. Act on the top finding — e.g. `proxmox-aiops vm migrate --to-node ` to shed load off a hot node, or `vm reconfigure --memory ...` for a RAM-starved guest. All of these route through the governed path (audited, undo recorded).\n\n### Snapshot, then reconfigure a VM\n\n1. `proxmox-aiops vm list` → find the vmid and confirm it is the right VM/node\n2. `proxmox-aiops vm snapshot-create --name pre-change` → baseline before any risky change\n3. `proxmox-aiops vm reconfigure --cores 8 --memory 16384` → the harness captures the prior cores/memory as the undo descriptor\n4. **Failure branch**: if the change goes wrong, the write recorded an `_undo_id` — reverse it with `proxmox-aiops undo apply `, or roll back with `proxmox-aiops vm snapshot-rollback --name pre-change`.\n\n### Free a node that is out of memory\n\n1. `proxmox-aiops diagnose node-pressure` → identify the node flagged `high memory`\n2. `proxmox-aiops cluster resources --type vm` → find a movable guest on that node\n3. `proxmox-aiops vm migrate --to-node --dry-run` → preview, then run without `--dry-run` (migrate is `high` risk; the inverse migrate-back is recorded)\n4. Re-run `diagnose node-pressure` to confirm the pressure cleared.\n\n### Stop a VM safely\n\n1. `proxmox-aiops vm get ` → confirm current status is `running`\n2. `proxmox-aiops vm stop --dry-run` → preview the exact API call\n3. `proxmox-aiops vm stop ` → double confirmation required; `vm_stop` records an inverse `vm_start` undo descriptor\n4. **Failure branch**: if `doctor` shows the node unreachable or the secret env var is missing, fix credentials with `proxmox-aiops secret set ` before retrying — the stop is never issued against an unauthenticated session.\n\n## Usage Mode\n\n| Scenario | Recommended | Why |\n|----------|:-----------:|-----|\n| Local/small models | **CLI** | fewer tokens than MCP |\n| Cloud models (Claude, GPT) | Either | MCP gives structured JSON I/O |\n| Automated pipelines | **MCP** | type-safe parameters, audited |\n\n## MCP Tools (43 — 25 read, 18 write)\n\n| Category | Tools | R/W |\n|----------|-------|:---:|\n| VM Lifecycle | `vm_list`, `vm_get`, `vm_config` | Read |\n| | `vm_start`, `vm_stop`, `vm_shutdown`, `vm_reboot`, `vm_reconfigure`, `vm_clone`, `vm_delete`, `vm_migrate` | Write |\n| Snapshots | `vm_list_snapshots` | Read |\n| | `vm_snapshot_create`, `vm_snapshot_delete`, `vm_snapshot_rollback` | Write |\n| Disk | `vm_resize_disk` (grow-only), `vm_move_disk` | Write |\n| Backups | `backup_list` | Read |\n| | `vm_backup`, `backup_restore` (high) | Write |\n| LXC Containers | `ct_list` | Read |\n| | `ct_start`, `ct_stop` | Write |\n| Cluster / Tasks | `node_list`, `cluster_status`, `task_status`, `cluster_resources`, `node_status`, `task_log`, `next_vmid` | Read |\n| HA | `ha_status`, `ha_resource_list` | Read |\n| Pools | `pool_list`, `pool_members` | Read |\n| Firewall | `vm_firewall_rules_list`, `cluster_firewall_status` | Read |\n| Guest Agent | `vm_agent_ping` | Read |\n| Storage | `storage_list`, `storage_content` | Read |\n| Diagnostics / RCA | `node_pressure_rca`, `guest_health_rca` | Read |\n| Undo | `undo_list` | Read |\n| | `undo_apply` | Write |\n\n**Harness features that light up**: write tools with a clean inverse (`vm_start`/`vm_stop`/`vm_shutdown`/`vm_reconfigure`/`vm_clone`/`vm_migrate`/`vm_snapshot_create`/`vm_move_disk`/`ct_start`/`ct_stop`) pass an `undo=` lambda so the harness records an inverse descriptor (with `_undo_id`) to the undo store — `vm_reconfigure` captures the prior cores/memory, `vm_clone`'s inverse is `vm_delete(newid)`, `vm_migrate`'s is migrate-back, `vm_move_disk`'s is move-back to the captured source storage. `backup_restore` records a `vm_delete` inverse **only** when it restored into a free VMID (a forced overwrite is destructive and declares none). Irreversible writes (`vm_delete`, `vm_snapshot_rollback`, `backup_restore` with `force`) declare no undo and are tagged `risk_level=high`; `vm_resize_disk` is grow-only and refuses shrink before any API call. All 43 tools are audit-logged under `~/.proxmox-aiops/` and pass through the budget/runaway guard + risk-tier tagging. Proxmox writes are async (return a task UPID) — poll with `task_status` (and read lines with `task_log`) instead of re-issuing (the runaway breaker backs this up).\n\n## CLI Quick Reference\n\n```bash\nproxmox-aiops vm list [--target ] [--node ]\nproxmox-aiops vm get [--node ]\nproxmox-aiops vm start [--node ]\nproxmox-aiops vm stop [--dry-run] # double confirm\nproxmox-aiops vm resize-disk --disk scsi0 --size +10G # grow-only\nproxmox-aiops vm move-disk --disk scsi0 --storage ceph [--delete]\nproxmox-aiops vm agent-ping \nproxmox-aiops vm snapshot-create --name \nproxmox-aiops vm snapshot-delete --name [--dry-run] # double confirm\nproxmox-aiops vm snapshot-list \nproxmox-aiops backup create --storage [--mode snapshot]\nproxmox-aiops backup list [--vmid ]\nproxmox-aiops backup restore --archive --storage [--force] [--dry-run] # double confirm\nproxmox-aiops cluster resources [--type vm|node|storage]\nproxmox-aiops cluster node-status \nproxmox-aiops cluster task-log \nproxmox-aiops cluster next-vmid\nproxmox-aiops ha status\nproxmox-aiops pool list\nproxmox-aiops firewall vm-rules \nproxmox-aiops storage list [--node ]\nproxmox-aiops diagnose node-pressure # rank nodes by CPU/mem/disk pressure (read-only RCA)\nproxmox-aiops diagnose guest-health # stopped guests, mem saturation, disks near full\nproxmox-aiops undo apply # reverse a recorded governed write\nproxmox-aiops init # onboarding wizard (encrypted creds)\nproxmox-aiops secret set # manage encrypted secret store\nproxmox-aiops doctor\nproxmox-aiops mcp # start MCP server (stdio)\n```\n\n> Credentials are managed by the `proxmox-aiops init` onboarding wizard and the\n> `proxmox-aiops secret` commands, which back an encrypted secret store (no\n> plaintext passwords in `config.yaml`).\n\n## Troubleshooting\n\n### \"Config file not found\"\nCreate `~/.proxmox-aiops/config.yaml` with a `targets:` list (see README), and put secrets in `~/.proxmox-aiops/.env` (chmod 600).\n\n### \"Secret not found. Set environment variable: PROXMOX__SECRET\"\nEach target needs a per-target secret env var. For target `pve-lab`, set `PROXMOX_PVE_LAB_SECRET=` in `.env`.\n\n### \"Token auth requires user in the form 'user@realm!tokenid'\"\nFor API-token auth (recommended, least privilege), `user` must include the token id after `!`, e.g. `root@pam!claude`. For password auth set `auth_kind: password` and use `user@realm`.\n\n### \"No node specified and no default node configured\"\nEither pass `--node ` / `node=`, or set `node:` on the target in `config.yaml`. VM operations can auto-locate a vmid across nodes, but storage listing needs an explicit node.\n\n## Audit & Safety\n\nThe skill delivers reads and writes and records them; it does **not** decide whether a write is\npermitted. That is your agent's judgement, or the permission of the account you connect it with —\nuse a Proxmox VE user or API token granted only read privileges (no VM.*/Datastore.* write roles),\nand writes then fail at the server. There is no read-only switch, policy file, or approval gate.\n\n- **Audit is the guarantee, and it is not bypassable.** Every operation — MCP and CLI alike — is logged to `~/.proxmox-aiops/audit.db` (relocatable via `PROXMOX_AIOPS_HOME`): params, result, status, duration, and the risk tier. The CLI writes the same row the MCP path does.\n- `PROXMOX_AUDIT_APPROVED_BY` / `PROXMOX_AUDIT_RATIONALE` are optional annotations recorded on the audit row (who/why); they are never required and never block.\n- **Runaway guard** — a safety backstop, not authorization: the same call looped in a tight window trips a circuit breaker. Disable with `PROXMOX_RUNAWAY_MAX=0`; optional hard ceilings via `PROXMOX_MAX_TOOL_CALLS` / `PROXMOX_MAX_TOOL_SECONDS`.\n- Undo store records inverse descriptors for reversible writes (start/stop/shutdown/reconfigure/clone/migrate/snapshot-create, container start/stop).\n- Writes support `--dry-run` / `dry_run=True` and double confirmation at the CLI.\n\nThe harness is bundled in the package — no external dependency, no manual setup.\n\n## Contributing & feature requests\n\nCoverage is intentionally focused. **Missing a device, action, or feature you need?** Open an issue or pull request at [github.com/AIops-tools/Proxmox-AIops](https://github.com/AIops-tools/Proxmox-AIops/issues) — feature requests, contributions, and comments are all welcome.\n\n## License\n\nMIT — [github.com/AIops-tools/Proxmox-AIops](https://github.com/AIops-tools/Proxmox-AIops)\n\nFile v0.13.3:_meta.json\n\n{\n \"ownerId\": \"kn7b067awq2s97bn3d7p5qfhw5827pxc\",\n \"slug\": \"proxmox-aiops\",\n \"version\": \"0.13.3\",\n \"publishedAt\": 1789453009059\n}\n\nFile v0.13.3:references/agent-guardrails.md\n\n# Agent guardrails — running proxmox-aiops with a smaller / local model\n\nIf you drive these tools with a local model (Llama, Qwen, Mistral … via Goose,\nOllama, LM Studio, or any OpenAI-compatible runtime), you will get noticeably\nbetter results with a short system prompt. This page gives you one, and — more\nimportantly — tells you which guardrails you **no longer need to write**, because\nthe tool now enforces them itself.\n\nThe distinction matters. A guardrail in a prompt is a request. A guardrail in the\nharness is a guarantee. Anything below that we could move into the harness, we did.\n\n## What the tool now enforces — do not waste prompt budget on these\n\n| You might be tempted to prompt | Why you don't need to |\n|---|---|\n| \"Don't invent a value when a field is missing\" | A field the API did not return comes back as `null`, never as `\"\"`. Absent and empty are distinguishable in the payload. |\n| \"Tell me if the output was cut off\" | Anything with a `limit` returns `{\"lines\": [...], \"returned\": N, \"limit\": L, \"truncated\": true/false}`. Truncation is measured (one extra row is fetched), not guessed. |\n| \"Preserve the ordering / tell me what's most urgent\" | `diagnose` findings carry an explicit 1-based `rank`, worst-first. Priority is in the payload, not implied by list position. |\n| \"Confirm before anything destructive\" | Destructive operations require a `--dry-run`-able preview + double confirmation at the CLI. |\n| \"Log what you did\" | Every call is audited to `~/.proxmox-aiops/audit.db` regardless of what the model says it did. |\n\n## What still needs a prompt\n\nThese are model-behaviour problems the harness cannot fix from the outside.\nCopy this into your agent's system prompt:\n\n```text\nYou operate a Proxmox VE environment through the proxmox-aiops MCP tools.\n\nTOOL USE\n- Before answering any question about the current Proxmox environment, you MUST\n call a tool. Never answer from memory or assumption.\n- Actually invoke the tool. Do not describe the call you would make, and do not\n emit an example JSON response in place of calling it.\n- If a tool call fails, report the real error verbatim. Never fill the gap with\n a plausible-sounding answer.\n\nREADING RESULTS\n- Read the whole result before concluding. If a result contains a \"truncated\"\n field that is true, say so and re-run with a higher limit instead of treating\n the partial result as complete.\n- A null field means the API did not return that value. Report it as \"not\n available\" — never infer it.\n- Report values exactly as returned. Do not normalise, translate, or prettify\n status strings, severities, or IDs.\n- When a diagnose result has findings, work in \"rank\" order and cite the\n measured number in each finding's \"detail\".\n\nSCOPE\n- Separate observation from interpretation. State what the tools returned, then\n any interpretation, clearly marked as such.\n- Do not assert a capacity, performance, or availability problem unless a tool\n result supports it.\n- Do not add generic advice that does not follow from the tool output.\n- Do not confuse a VMID with a node name, or a task UPID with either.\n```\n\n## Recommended setup for a local model\n\nAuthorization is not this tool's job — decide it via the account you connect\nwith or the agent's prompt, not a switch in the tool. To work read-only, connect\nwith a Proxmox VE user or API token granted only read privileges (no\n`VM.*`/`Datastore.*` write roles); a write then fails at the server, the place\nthat actually owns the permission.\n\n```bash\nproxmox-aiops doctor # verify connectivity with your least-privilege token\n```\n\nOptionally, annotate who is running changes and why — these land on the audit\nrow, and are never required and never blocking:\n\n```bash\nexport PROXMOX_AUDIT_APPROVED_BY=\"your.name@example.com\"\nexport PROXMOX_AUDIT_RATIONALE=\"scheduled maintenance window\"\n```\n\n## If your model still struggles\n\nSome behaviours are model-capacity limits rather than prompt problems:\n\n- **Multi-tool workflows time out or drift.** Prefer the `diagnose` tools — they\n do the multi-step correlation inside one call, so the model does not have to\n chain reads and keep IDs straight.\n- **The model ignores later tool results in a long context.** Ask narrower\n questions and use `--limit` deliberately rather than pulling whole inventories.\n- **The model describes calls instead of making them.** This is usually a\n runtime/tool-calling-format mismatch, not a prompt problem — check that your\n client advertises the tools in the format your model was trained on.\n\nFeedback on running this with a specific local model is genuinely useful —\nopen an issue at\n[github.com/AIops-tools/Proxmox-AIops](https://github.com/AIops-tools/Proxmox-AIops/issues)\nwith the model, runtime, and what went wrong.\n\nFile v0.13.3:references/capabilities.md\n\n# proxmox-aiops capabilities\n\n43 MCP tools (25 read / 18 write). Every tool is wrapped with the bundled\n`@governed_tool` harness (audit + budget + risk-tier + undo). Typical response\nsizes are small high-signal summaries, not full API blobs.\n\n## VM lifecycle (11)\n\n| Tool | R/W | Inverse (undo) | Typical response |\n|------|:---:|----------------|------------------|\n| `vm_list` | R | — | ~50–500 tok (one row per VM) |\n| `vm_get` | R | — | ~120 tok |\n| `vm_config` | R | — | ~120 tok |\n| `vm_start` | W | `vm_stop` | task UPID |\n| `vm_stop` | W | `vm_start` | task UPID |\n| `vm_shutdown` | W | `vm_start` | task UPID |\n| `vm_reboot` | W | — (no inverse) | task UPID |\n| `vm_reconfigure` | W | `vm_reconfigure` (prior cores/memory) | applied + previous |\n| `vm_clone` | W | `vm_delete(newid)` | task UPID |\n| `vm_delete` | W | — (irreversible, risk=high) | task UPID |\n| `vm_migrate` | W | `vm_migrate` (back to source node) | task UPID |\n\n## Snapshots (4)\n\n| Tool | R/W | Inverse | Notes |\n|------|:---:|---------|-------|\n| `vm_list_snapshots` | R | — | name + description |\n| `vm_snapshot_create` | W | `vm_snapshot_delete` | |\n| `vm_snapshot_delete` | W | — | |\n| `vm_snapshot_rollback` | W | — (irreversible, risk=high) | discards newer state |\n\n## Disk (2)\n\n| Tool | R/W | Inverse | Notes |\n|------|:---:|---------|-------|\n| `vm_resize_disk` | W | — (grow-only; shrink refused) | `+G` or larger absolute |\n| `vm_move_disk` | W | `vm_move_disk` (back to source storage) | task UPID |\n\n## Backups — vzdump (3)\n\n| Tool | R/W | Inverse | Notes |\n|------|:---:|---------|-------|\n| `backup_list` | R | — | archives on a storage, filterable by vmid |\n| `vm_backup` | W | — | task UPID; mode snapshot/suspend/stop |\n| `backup_restore` | W | `vm_delete` only when restored into a free vmid; none on forced overwrite (risk=high) | task UPID |\n\n## LXC containers (3)\n\n| Tool | R/W | Inverse |\n|------|:---:|---------|\n| `ct_list` | R | — |\n| `ct_start` | W | `ct_stop` |\n| `ct_stop` | W | `ct_start` |\n\n## Cluster / tasks (7)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `node_list` | R | status, cpu load, memory |\n| `cluster_status` | R | membership + quorum |\n| `task_status` | R | poll an async UPID (clone/migrate/backup) |\n| `cluster_resources` | R | `/cluster/resources` inventory (vm/node/storage filter) |\n| `node_status` | R | one node: cpu, load average, memory, uptime |\n| `task_log` | R | log lines of an async task by UPID |\n| `next_vmid` | R | a free VMID for a new guest |\n\n## HA (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `ha_status` | R | `{configured, entries}`; `configured` is true only when HA manages a resource — every cluster reports quorum/master/lrm rows regardless |\n| `ha_resource_list` | R | HA-managed resources; empty when HA absent |\n\n## Pools (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `pool_list` | R | poolid + comment |\n| `pool_members` | R | members (VMs/CTs/storage) of a pool |\n\n## Firewall — read-only (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `vm_firewall_rules_list` | R | per-VM firewall rules |\n| `cluster_firewall_status` | R | cluster firewall enable + default policies |\n\n## Guest agent (1)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `vm_agent_ping` | R | `responsive` bool; absence reported, not crashed |\n\n## Storage (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `storage_list` | R | pools: type, total/used/avail |\n| `storage_content` | R | volumes: ISOs, disk images, backups, templates |\n\n## Diagnostics / RCA (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `node_pressure_rca` | R | node CPU/memory/IO pressure: ranked causes + evidence |\n| `guest_health_rca` | R | one guest: ranked causes (resource, agent, disk, task history) |\n\n## Undo (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `undo_list` | R | recorded, not-yet-applied undo tokens (most recent first): original tool, inverse tool, `undoId` |\n| `undo_apply` | W | executes a recorded inverse by `undoId` — itself governed (the inverse re-gates on its own risk tier), single-use, `dry_run=True` previews |\n\n## Not yet covered\n\nVM create-from-scratch / template instantiation, guest agent **exec**\n(intentionally omitted as too risky), container create/clone/destroy, firewall\n**rule mutation** (read-only for now), and ACL management. These are the natural\nnext additions — each gets a matching `@governed_tool` wrapper and an `undo=`\ndeclaration where a clean inverse exists. Missing something? Open an issue/PR.\n\nFile v0.13.3:references/cli-reference.md\n\n# proxmox-aiops CLI reference\n\nAll commands take `--target/-t ` (config target; omit for default) and,\nwhere relevant, `--node/-n `. Destructive commands support `--dry-run`.\n\n## VM lifecycle\n\n```bash\nproxmox-aiops vm list [-t ] [-n ]\nproxmox-aiops vm get \nproxmox-aiops vm config \nproxmox-aiops vm start \nproxmox-aiops vm stop [--dry-run] # hard power-off (double confirm)\nproxmox-aiops vm shutdown [--dry-run] # graceful ACPI\nproxmox-aiops vm reboot \nproxmox-aiops vm reconfigure [--cores N] [--memory MiB] [--dry-run]\nproxmox-aiops vm clone --newid [--name ]\nproxmox-aiops vm delete [--dry-run] # irreversible (double confirm)\nproxmox-aiops vm migrate --to-node [--offline] [--dry-run]\n```\n\n## Snapshots\n\n```bash\nproxmox-aiops vm snapshot-create --name \nproxmox-aiops vm snapshot-list \nproxmox-aiops vm snapshot-delete --name [--dry-run] # double confirm\nproxmox-aiops vm snapshot-rollback --name [--dry-run] # irreversible\n```\n\n## LXC containers\n\n```bash\nproxmox-aiops ct list [-n ]\nproxmox-aiops ct start \nproxmox-aiops ct stop [--dry-run] # double confirm\n```\n\n## Cluster / async tasks\n\n```bash\nproxmox-aiops cluster nodes\nproxmox-aiops cluster status # membership + quorum\nproxmox-aiops cluster task-status # poll a clone/migrate/backup task\n```\n\n## Storage\n\n```bash\nproxmox-aiops storage list [-n ]\nproxmox-aiops storage content [--content iso|images|backup|vztmpl]\n```\n\n## Diagnostics & MCP\n\n```bash\nproxmox-aiops doctor # verify connectivity + credentials\nproxmox-aiops mcp # start the MCP server (stdio)\n```\n\n> Proxmox writes are asynchronous and return a task UPID. Poll completion with\n> `cluster task-status ` rather than re-issuing the operation.\n\nFile v0.13.3:references/setup-guide.md\n\n# proxmox-aiops setup guide\n\n## Install\n\n```bash\nuv tool install proxmox-aiops\n# or: pipx install proxmox-aiops\n```\n\n## Configure\n\n```bash\nmkdir -p ~/.proxmox-aiops && chmod 700 ~/.proxmox-aiops\n```\n\n`~/.proxmox-aiops/config.yaml` (no secrets here):\n\n```yaml\ntargets:\n - name: pve-lab\n host: 10.0.0.10\n user: \"root@pam!claude\" # API token form: user@realm!tokenid\n node: pve1 # default node for this target\n auth_kind: token # 'token' or 'password'\n verify_ssl: false # self-signed lab certs only; true in prod\n```\n\n`~/.proxmox-aiops/.env` (chmod 600 — secrets only):\n\n```bash\nPROXMOX_PVE_LAB_SECRET=\n```\n\nThe secret variable is `PROXMOX__SECRET` (hyphens → underscores).\n\n```bash\nchmod 600 ~/.proxmox-aiops/.env\nproxmox-aiops doctor # verifies connectivity + credentials\n```\n\n## Use as an MCP server\n\n```jsonc\n{\n \"command\": \"proxmox-aiops\",\n \"args\": [\"mcp\"],\n \"env\": { \"PROXMOX_AIOPS_CONFIG\": \"~/.proxmox-aiops/config.yaml\" }\n}\n```\n\nUsing the `proxmox-aiops mcp` subcommand (rather than `uvx --from`) means the\nMCP client launches the already-installed entry point and does not re-resolve\nthe package over the network at startup.\n\n## Security\n\n> **Disclaimer**: Community-maintained project, **not affiliated with Proxmox\n> Server Solutions GmbH**. MIT licensed. See `SECURITY.md`.\n\n- **Credentials**: `.env` only, chmod 600, per-target `PROXMOX__SECRET`.\n- **Audit**: every operation logged to a local SQLite DB under\n `~/.proxmox-aiops/` (relocate with `PROXMOX_AIOPS_HOME`).\n- **Budget guard**: cap calls/wall-time with `PROXMOX_MAX_TOOL_CALLS` /\n `PROXMOX_MAX_TOOL_SECONDS`; a runaway poll/retry loop trips automatically.\n- **Risk tiers**: each tool's `risk_level` is recorded on the audit row as a\n descriptive tier (none/confirm/review) — a label, not a gate.\n `PROXMOX_AUDIT_APPROVED_BY` / `PROXMOX_AUDIT_RATIONALE` are optional audit\n annotations, never required.\n- **Destructive ops**: double confirmation + `--dry-run` at the CLI.\n- **TLS**: `verify_ssl` defaults true; disable only for self-signed labs.\n- **No webhooks / telemetry / background services.**\n\n## Least privilege\n\nCreate a dedicated Proxmox API token with only the roles your workflows need\n(e.g. `PVEVMAdmin` on the relevant pool) rather than `root@pam`.\n\nFile v0.13.3:skill-card.md\n\n## Description:\n\nProxmox AIops helps agents manage and diagnose Proxmox VE virtual machines, containers, storage, backups, snapshots, HA, firewall, and cluster health with governed CLI and MCP operations.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[zw008](https://clawhub.ai/user/zw008)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, infrastructure operators, and external agents use this skill to inspect, operate, and troubleshoot Proxmox VE environments. It is suited for VM and container lifecycle work, storage and backup workflows, cluster status checks, and read-only root-cause analysis when the target is explicitly Proxmox VE.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can perform destructive Proxmox infrastructure actions.\n\nMitigation: Use a dedicated least-privilege Proxmox API token, prefer read-only roles unless writes are required, preview supported destructive operations with dry-run, and rely on audited write paths and undo records where available.\n\nRisk: Credential-storage guidance is inconsistent across the release evidence and artifact text.\n\nMitigation: Verify how the installed version stores secrets, keep ~/.proxmox-aiops out of backups and sync tools, keep config files free of secrets, and restrict secret files to the local user.\n\nRisk: Disabling TLS verification can expose Proxmox API credentials or operations outside isolated labs.\n\nMitigation: Keep TLS verification enabled in normal environments and disable it only for isolated self-signed lab deployments.\n\nRisk: Repeated asynchronous writes or polling can amplify operational mistakes.\n\nMitigation: Poll returned task identifiers instead of reissuing operations, pin package versions in sensitive environments, and use the documented call and wall-time budget controls.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/zw008/skills/proxmox-aiops)\n- [Project homepage](https://github.com/AIops-tools/Proxmox-AIops)\n- [Capabilities](references/capabilities.md)\n- [CLI reference](references/cli-reference.md)\n- [Setup guide](references/setup-guide.md)\n- [Agent guardrails](references/agent-guardrails.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands and configuration snippets]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May propose or invoke Proxmox CLI or MCP operations; write operations can return asynchronous task identifiers that require polling.]\n\n## Skill Version(s):\n\n0.13.3 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.13.2: 7 files, 14901 bytes\n\nFiles: references/agent-guardrails.md (4785b), references/capabilities.md (4523b), references/cli-reference.md (2012b), references/setup-guide.md (2363b), skill-card.md (2676b), SKILL.md (15970b), _meta.json (133b)\n\nFile v0.13.2:SKILL.md\n\n---\nname: proxmox-aiops\nslug: proxmox-aiops\ndisplayName: \"Proxmox AIops\"\nsummary: \"Governed Proxmox VE VM/container ops — 43 MCP tools with audit, budget, undo & risk-tier guards.\"\nlicense: MIT\nhomepage: https://github.com/AIops-tools/Proxmox-AIops\ntags: [aiops, mcp, governance, proxmox]\ndescription: >\n Use this skill whenever the user needs to manage VMs and containers on Proxmox VE — list/inspect/configure VMs, power and lifecycle (start/stop/shutdown/reboot/reconfigure/clone/delete/migrate), snapshots (create/delete/list/rollback), disk grow/move, vzdump backups (create/list/restore), LXC containers (list/start/stop), cluster/node status, cluster resource inventory, async task polling + logs, free-VMID lookup, HA status, resource pools, firewall inspection, guest-agent ping, and storage listing.\n Also use it to diagnose cluster health — rank nodes by CPU/memory/disk pressure and scan guests for saturation (read-only RCA).\n Always use this skill for \"list proxmox vms\", \"start proxmox vm\", \"stop proxmox vm\", \"proxmox snapshot\", \"proxmox backup\", \"restore proxmox vm\", \"resize proxmox disk\", \"proxmox vm status\", \"migrate proxmox vm\", \"proxmox container\", \"proxmox ha\", \"proxmox pool\", \"proxmox firewall\", \"list proxmox storage\", \"proxmox node pressure\", or \"why is proxmox slow\" when the context is explicitly Proxmox / Proxmox VE / PVE.\n Do NOT use for non-Proxmox hypervisors, Kubernetes, or cloud providers.\n Broad coverage of common Proxmox operations, with a built-in governance harness (audit, token budget, undo, risk-tier labels).\ninstaller:\n kind: uv\n package: proxmox-aiops\nargument-hint: \"[vmid or describe your Proxmox task]\"\nallowed-tools:\n - Bash\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"proxmox-aiops\",\"uvx\"]},\"optional\":{\"env\":[\"PROXMOX_AIOPS_CONFIG\",\"PROXMOX_TARGET_SECRET\"]},\"homepage\":\"https://github.com/AIops-tools/Proxmox-AIops\",\"emoji\":\"🧱\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n Standalone, self-governed Proxmox VE operations. The governance harness (audit, token/runaway budget, undo, risk-tier labels) is bundled in the package — no external skill-family dependency.\n All write operations are audited to a local SQLite DB under ~/.proxmox-aiops/ (relocatable via PROXMOX_AIOPS_HOME).\n Credentials: Each Proxmox target requires a per-target secret env var in ~/.proxmox-aiops/.env following the pattern PROXMOX__SECRET (API token UUID for token auth, or login password). Secrets are never logged or echoed; .env should be chmod 600.\n Destructive operations (vm stop/delete/snapshot-delete/snapshot-rollback, ct stop) require double confirmation at the CLI layer and support --dry-run. All write tools pass through the @governed_tool decorator (budget guard + audit + risk-tier tagging). Reversible writes record an inverse undo descriptor to the undo store.\n Webhooks: none — no outbound network calls beyond the configured Proxmox API endpoint.\n SSL: verify_ssl defaults to true; disable only for self-signed lab certificates.\n Transitive dependencies: proxmoxer (Proxmox API client) and the MCP SDK. No post-install scripts or background services.\n---\n\n# Proxmox AIops\n\n> **Disclaimer**: This is a community-maintained open-source project and is **not affiliated with, endorsed by, or sponsored by Proxmox Server Solutions GmbH.** \"Proxmox\" is a trademark of its owner. Source code is publicly auditable at [github.com/AIops-tools/Proxmox-AIops](https://github.com/AIops-tools/Proxmox-AIops) under the MIT license.\n\nGoverned VM and container lifecycle operations for Proxmox VE — **43 MCP tools**, every one wrapped with the bundled `@governed_tool` harness: a local unified audit log under `~/.proxmox-aiops/`, token/runaway budget guard, undo-token recording, and descriptive risk-tier labels.\n\n> **Standalone**: the governance harness is bundled in the package (`proxmox_aiops.governance`) — proxmox-aiops has no external skill-family dependency. Coverage focuses on common Proxmox operations and is not yet exhaustive.\n\n## What This Skill Does\n\n| Category | Tools | Count | Read or Write |\n|----------|-------|:-----:|:-------------:|\n| **VM Lifecycle** | list, get, config, start, stop, shutdown, reboot, reconfigure, clone, delete, migrate | 11 | 3 read / 8 write |\n| **Snapshots** | create, delete, list, rollback | 4 | 1 read / 3 write |\n| **Disk** | resize (grow-only), move | 2 | 0 read / 2 write |\n| **Backups (vzdump)** | create, list, restore | 3 | 1 read / 2 write |\n| **LXC Containers** | list, start, stop | 3 | 1 read / 2 write |\n| **Cluster / Tasks** | node list, cluster status, task poll, cluster resources, node status, task log, next vmid | 7 | 7 read |\n| **HA** | status, resource list | 2 | 2 read |\n| **Pools** | list, members | 2 | 2 read |\n| **Firewall** | vm rules, cluster status | 2 | 2 read |\n| **Guest Agent** | ping | 1 | 1 read |\n| **Storage** | list pools, list content | 2 | 2 read |\n| **Diagnostics / RCA** | node-pressure, guest-health | 2 | 2 read |\n\n## Quick Install\n\n```bash\nuv tool install proxmox-aiops\nproxmox-aiops doctor\n```\n\nOr as an OpenClaw plugin, which installs this skill and its MCP server together:\n\n```bash\nopenclaw plugins install clawhub:@zw008/proxmox-aiops\nopenclaw skills info proxmox-aiops # expect: Visible to model: yes\n```\n\nNeeds `uvx` on `PATH`: the MCP server is fetched with uv, pinned to this release.\n\n## When to Use This Skill\n\n- List/inspect Proxmox QEMU VMs and their config\n- Power ops: start, hard-stop, graceful shutdown, reboot\n- Reconfigure (cores/memory), clone, delete, or migrate a VM between nodes\n- Grow a VM disk (grow-only — shrink is refused) or move it to another storage\n- Create, list, and restore vzdump backups\n- Create / delete / list / roll back VM snapshots\n- Manage LXC containers (list, start, stop)\n- Inspect cluster nodes, quorum, the `/cluster/resources` inventory, node load/mem, and poll async tasks + fetch their logs by UPID; get a free VMID\n- Check HA status / HA-managed resources (handles \"HA not configured\" gracefully)\n- List resource pools and their members\n- Inspect VM firewall rules and the cluster firewall enable state (read-only)\n- Ping a VM's QEMU guest agent\n- List storage pools and their content (ISOs, disk images, backups)\n- **Diagnose** cluster health: rank nodes by CPU/memory/root-fs pressure, and scan VMs/containers for stopped guests, memory saturation, and disks near full — each finding cites the measured number and a concrete action (read-only RCA)\n\n**Do NOT use when** the target is not Proxmox VE (other hypervisors, Kubernetes, or cloud providers are out of scope for this skill).\n\n## Common Workflows\n\n### Triage a \"cluster feels slow\" complaint (read-only)\n\n1. `proxmox-aiops diagnose node-pressure` → worst-first table of nodes over the CPU/mem/disk thresholds, each row citing the measured % and the fix\n2. `proxmox-aiops diagnose guest-health` → guests near their memory ceiling or with disks near full, plus the list of stopped guests\n3. Act on the top finding — e.g. `proxmox-aiops vm migrate --to-node ` to shed load off a hot node, or `vm reconfigure --memory ...` for a RAM-starved guest. All of these route through the governed path (audited, undo recorded).\n\n### Snapshot, then reconfigure a VM\n\n1. `proxmox-aiops vm list` → find the vmid and confirm it is the right VM/node\n2. `proxmox-aiops vm snapshot-create --name pre-change` → baseline before any risky change\n3. `proxmox-aiops vm reconfigure --cores 8 --memory 16384` → the harness captures the prior cores/memory as the undo descriptor\n4. **Failure branch**: if the change goes wrong, the write recorded an `_undo_id` — reverse it with `proxmox-aiops undo apply `, or roll back with `proxmox-aiops vm snapshot-rollback --name pre-change`.\n\n### Free a node that is out of memory\n\n1. `proxmox-aiops diagnose node-pressure` → identify the node flagged `high memory`\n2. `proxmox-aiops cluster resources --type vm` → find a movable guest on that node\n3. `proxmox-aiops vm migrate --to-node --dry-run` → preview, then run without `--dry-run` (migrate is `high` risk; the inverse migrate-back is recorded)\n4. Re-run `diagnose node-pressure` to confirm the pressure cleared.\n\n### Stop a VM safely\n\n1. `proxmox-aiops vm get ` → confirm current status is `running`\n2. `proxmox-aiops vm stop --dry-run` → preview the exact API call\n3. `proxmox-aiops vm stop ` → double confirmation required; `vm_stop` records an inverse `vm_start` undo descriptor\n4. **Failure branch**: if `doctor` shows the node unreachable or the secret env var is missing, fix credentials with `proxmox-aiops secret set ` before retrying — the stop is never issued against an unauthenticated session.\n\n## Usage Mode\n\n| Scenario | Recommended | Why |\n|----------|:-----------:|-----|\n| Local/small models | **CLI** | fewer tokens than MCP |\n| Cloud models (Claude, GPT) | Either | MCP gives structured JSON I/O |\n| Automated pipelines | **MCP** | type-safe parameters, audited |\n\n## MCP Tools (43 — 25 read, 18 write)\n\n| Category | Tools | R/W |\n|----------|-------|:---:|\n| VM Lifecycle | `vm_list`, `vm_get`, `vm_config` | Read |\n| | `vm_start`, `vm_stop`, `vm_shutdown`, `vm_reboot`, `vm_reconfigure`, `vm_clone`, `vm_delete`, `vm_migrate` | Write |\n| Snapshots | `vm_list_snapshots` | Read |\n| | `vm_snapshot_create`, `vm_snapshot_delete`, `vm_snapshot_rollback` | Write |\n| Disk | `vm_resize_disk` (grow-only), `vm_move_disk` | Write |\n| Backups | `backup_list` | Read |\n| | `vm_backup`, `backup_restore` (high) | Write |\n| LXC Containers | `ct_list` | Read |\n| | `ct_start`, `ct_stop` | Write |\n| Cluster / Tasks | `node_list`, `cluster_status`, `task_status`, `cluster_resources`, `node_status`, `task_log`, `next_vmid` | Read |\n| HA | `ha_status`, `ha_resource_list` | Read |\n| Pools | `pool_list`, `pool_members` | Read |\n| Firewall | `vm_firewall_rules_list`, `cluster_firewall_status` | Read |\n| Guest Agent | `vm_agent_ping` | Read |\n| Storage | `storage_list`, `storage_content` | Read |\n| Diagnostics / RCA | `node_pressure_rca`, `guest_health_rca` | Read |\n| Undo | `undo_list` | Read |\n| | `undo_apply` | Write |\n\n**Harness features that light up**: write tools with a clean inverse (`vm_start`/`vm_stop`/`vm_shutdown`/`vm_reconfigure`/`vm_clone`/`vm_migrate`/`vm_snapshot_create`/`vm_move_disk`/`ct_start`/`ct_stop`) pass an `undo=` lambda so the harness records an inverse descriptor (with `_undo_id`) to the undo store — `vm_reconfigure` captures the prior cores/memory, `vm_clone`'s inverse is `vm_delete(newid)`, `vm_migrate`'s is migrate-back, `vm_move_disk`'s is move-back to the captured source storage. `backup_restore` records a `vm_delete` inverse **only** when it restored into a free VMID (a forced overwrite is destructive and declares none). Irreversible writes (`vm_delete`, `vm_snapshot_rollback`, `backup_restore` with `force`) declare no undo and are tagged `risk_level=high`; `vm_resize_disk` is grow-only and refuses shrink before any API call. All 43 tools are audit-logged under `~/.proxmox-aiops/` and pass through the budget/runaway guard + risk-tier tagging. Proxmox writes are async (return a task UPID) — poll with `task_status` (and read lines with `task_log`) instead of re-issuing (the runaway breaker backs this up).\n\n## CLI Quick Reference\n\n```bash\nproxmox-aiops vm list [--target ] [--node ]\nproxmox-aiops vm get [--node ]\nproxmox-aiops vm start [--node ]\nproxmox-aiops vm stop [--dry-run] # double confirm\nproxmox-aiops vm resize-disk --disk scsi0 --size +10G # grow-only\nproxmox-aiops vm move-disk --disk scsi0 --storage ceph [--delete]\nproxmox-aiops vm agent-ping \nproxmox-aiops vm snapshot-create --name \nproxmox-aiops vm snapshot-delete --name [--dry-run] # double confirm\nproxmox-aiops vm snapshot-list \nproxmox-aiops backup create --storage [--mode snapshot]\nproxmox-aiops backup list [--vmid ]\nproxmox-aiops backup restore --archive --storage [--force] [--dry-run] # double confirm\nproxmox-aiops cluster resources [--type vm|node|storage]\nproxmox-aiops cluster node-status \nproxmox-aiops cluster task-log \nproxmox-aiops cluster next-vmid\nproxmox-aiops ha status\nproxmox-aiops pool list\nproxmox-aiops firewall vm-rules \nproxmox-aiops storage list [--node ]\nproxmox-aiops diagnose node-pressure # rank nodes by CPU/mem/disk pressure (read-only RCA)\nproxmox-aiops diagnose guest-health # stopped guests, mem saturation, disks near full\nproxmox-aiops undo apply # reverse a recorded governed write\nproxmox-aiops init # onboarding wizard (encrypted creds)\nproxmox-aiops secret set # manage encrypted secret store\nproxmox-aiops doctor\nproxmox-aiops mcp # start MCP server (stdio)\n```\n\n> Credentials are managed by the `proxmox-aiops init` onboarding wizard and the\n> `proxmox-aiops secret` commands, which back an encrypted secret store (no\n> plaintext passwords in `config.yaml`).\n\n## Troubleshooting\n\n### \"Config file not found\"\nCreate `~/.proxmox-aiops/config.yaml` with a `targets:` list (see README), and put secrets in `~/.proxmox-aiops/.env` (chmod 600).\n\n### \"Secret not found. Set environment variable: PROXMOX__SECRET\"\nEach target needs a per-target secret env var. For target `pve-lab`, set `PROXMOX_PVE_LAB_SECRET=` in `.env`.\n\n### \"Token auth requires user in the form 'user@realm!tokenid'\"\nFor API-token auth (recommended, least privilege), `user` must include the token id after `!`, e.g. `root@pam!claude`. For password auth set `auth_kind: password` and use `user@realm`.\n\n### \"No node specified and no default node configured\"\nEither pass `--node ` / `node=`, or set `node:` on the target in `config.yaml`. VM operations can auto-locate a vmid across nodes, but storage listing needs an explicit node.\n\n## Audit & Safety\n\nThe skill delivers reads and writes and records them; it does **not** decide whether a write is\npermitted. That is your agent's judgement, or the permission of the account you connect it with —\nuse a Proxmox VE user or API token granted only read privileges (no VM.*/Datastore.* write roles),\nand writes then fail at the server. There is no read-only switch, policy file, or approval gate.\n\n- **Audit is the guarantee, and it is not bypassable.** Every operation — MCP and CLI alike — is logged to `~/.proxmox-aiops/audit.db` (relocatable via `PROXMOX_AIOPS_HOME`): params, result, status, duration, and the risk tier. The CLI writes the same row the MCP path does.\n- `PROXMOX_AUDIT_APPROVED_BY` / `PROXMOX_AUDIT_RATIONALE` are optional annotations recorded on the audit row (who/why); they are never required and never block.\n- **Runaway guard** — a safety backstop, not authorization: the same call looped in a tight window trips a circuit breaker. Disable with `PROXMOX_RUNAWAY_MAX=0`; optional hard ceilings via `PROXMOX_MAX_TOOL_CALLS` / `PROXMOX_MAX_TOOL_SECONDS`.\n- Undo store records inverse descriptors for reversible writes (start/stop/shutdown/reconfigure/clone/migrate/snapshot-create, container start/stop).\n- Writes support `--dry-run` / `dry_run=True` and double confirmation at the CLI.\n\nThe harness is bundled in the package — no external dependency, no manual setup.\n\n## Contributing & feature requests\n\nCoverage is intentionally focused. **Missing a device, action, or feature you need?** Open an issue or pull request at [github.com/AIops-tools/Proxmox-AIops](https://github.com/AIops-tools/Proxmox-AIops/issues) — feature requests, contributions, and comments are all welcome.\n\n## License\n\nMIT — [github.com/AIops-tools/Proxmox-AIops](https://github.com/AIops-tools/Proxmox-AIops)\n\nFile v0.13.2:_meta.json\n\n{\n \"ownerId\": \"kn7b067awq2s97bn3d7p5qfhw5827pxc\",\n \"slug\": \"proxmox-aiops\",\n \"version\": \"0.13.2\",\n \"publishedAt\": 1789224014942\n}\n\nFile v0.13.2:references/agent-guardrails.md\n\n# Agent guardrails — running proxmox-aiops with a smaller / local model\n\nIf you drive these tools with a local model (Llama, Qwen, Mistral … via Goose,\nOllama, LM Studio, or any OpenAI-compatible runtime), you will get noticeably\nbetter results with a short system prompt. This page gives you one, and — more\nimportantly — tells you which guardrails you **no longer need to write**, because\nthe tool now enforces them itself.\n\nThe distinction matters. A guardrail in a prompt is a request. A guardrail in the\nharness is a guarantee. Anything below that we could move into the harness, we did.\n\n## What the tool now enforces — do not waste prompt budget on these\n\n| You might be tempted to prompt | Why you don't need to |\n|---|---|\n| \"Don't invent a value when a field is missing\" | A field the API did not return comes back as `null`, never as `\"\"`. Absent and empty are distinguishable in the payload. |\n| \"Tell me if the output was cut off\" | Anything with a `limit` returns `{\"lines\": [...], \"returned\": N, \"limit\": L, \"truncated\": true/false}`. Truncation is measured (one extra row is fetched), not guessed. |\n| \"Preserve the ordering / tell me what's most urgent\" | `diagnose` findings carry an explicit 1-based `rank`, worst-first. Priority is in the payload, not implied by list position. |\n| \"Confirm before anything destructive\" | Destructive operations require a `--dry-run`-able preview + double confirmation at the CLI. |\n| \"Log what you did\" | Every call is audited to `~/.proxmox-aiops/audit.db` regardless of what the model says it did. |\n\n## What still needs a prompt\n\nThese are model-behaviour problems the harness cannot fix from the outside.\nCopy this into your agent's system prompt:\n\n```text\nYou operate a Proxmox VE environment through the proxmox-aiops MCP tools.\n\nTOOL USE\n- Before answering any question about the current Proxmox environment, you MUST\n call a tool. Never answer from memory or assumption.\n- Actually invoke the tool. Do not describe the call you would make, and do not\n emit an example JSON response in place of calling it.\n- If a tool call fails, report the real error verbatim. Never fill the gap with\n a plausible-sounding answer.\n\nREADING RESULTS\n- Read the whole result before concluding. If a result contains a \"truncated\"\n field that is true, say so and re-run with a higher limit instead of treating\n the partial result as complete.\n- A null field means the API did not return that value. Report it as \"not\n available\" — never infer it.\n- Report values exactly as returned. Do not normalise, translate, or prettify\n status strings, severities, or IDs.\n- When a diagnose result has findings, work in \"rank\" order and cite the\n measured number in each finding's \"detail\".\n\nSCOPE\n- Separate observation from interpretation. State what the tools returned, then\n any interpretation, clearly marked as such.\n- Do not assert a capacity, performance, or availability problem unless a tool\n result supports it.\n- Do not add generic advice that does not follow from the tool output.\n- Do not confuse a VMID with a node name, or a task UPID with either.\n```\n\n## Recommended setup for a local model\n\nAuthorization is not this tool's job — decide it via the account you connect\nwith or the agent's prompt, not a switch in the tool. To work read-only, connect\nwith a Proxmox VE user or API token granted only read privileges (no\n`VM.*`/`Datastore.*` write roles); a write then fails at the server, the place\nthat actually owns the permission.\n\n```bash\nproxmox-aiops doctor # verify connectivity with your least-privilege token\n```\n\nOptionally, annotate who is running changes and why — these land on the audit\nrow, and are never required and never blocking:\n\n```bash\nexport PROXMOX_AUDIT_APPROVED_BY=\"your.name@example.com\"\nexport PROXMOX_AUDIT_RATIONALE=\"scheduled maintenance window\"\n```\n\n## If your model still struggles\n\nSome behaviours are model-capacity limits rather than prompt problems:\n\n- **Multi-tool workflows time out or drift.** Prefer the `diagnose` tools — they\n do the multi-step correlation inside one call, so the model does not have to\n chain reads and keep IDs straight.\n- **The model ignores later tool results in a long context.** Ask narrower\n questions and use `--limit` deliberately rather than pulling whole inventories.\n- **The model describes calls instead of making them.** This is usually a\n runtime/tool-calling-format mismatch, not a prompt problem — check that your\n client advertises the tools in the format your model was trained on.\n\nFeedback on running this with a specific local model is genuinely useful —\nopen an issue at\n[github.com/AIops-tools/Proxmox-AIops](https://github.com/AIops-tools/Proxmox-AIops/issues)\nwith the model, runtime, and what went wrong.\n\nFile v0.13.2:references/capabilities.md\n\n# proxmox-aiops capabilities\n\n43 MCP tools (25 read / 18 write). Every tool is wrapped with the bundled\n`@governed_tool` harness (audit + budget + risk-tier + undo). Typical response\nsizes are small high-signal summaries, not full API blobs.\n\n## VM lifecycle (11)\n\n| Tool | R/W | Inverse (undo) | Typical response |\n|------|:---:|----------------|------------------|\n| `vm_list` | R | — | ~50–500 tok (one row per VM) |\n| `vm_get` | R | — | ~120 tok |\n| `vm_config` | R | — | ~120 tok |\n| `vm_start` | W | `vm_stop` | task UPID |\n| `vm_stop` | W | `vm_start` | task UPID |\n| `vm_shutdown` | W | `vm_start` | task UPID |\n| `vm_reboot` | W | — (no inverse) | task UPID |\n| `vm_reconfigure` | W | `vm_reconfigure` (prior cores/memory) | applied + previous |\n| `vm_clone` | W | `vm_delete(newid)` | task UPID |\n| `vm_delete` | W | — (irreversible, risk=high) | task UPID |\n| `vm_migrate` | W | `vm_migrate` (back to source node) | task UPID |\n\n## Snapshots (4)\n\n| Tool | R/W | Inverse | Notes |\n|------|:---:|---------|-------|\n| `vm_list_snapshots` | R | — | name + description |\n| `vm_snapshot_create` | W | `vm_snapshot_delete` | |\n| `vm_snapshot_delete` | W | — | |\n| `vm_snapshot_rollback` | W | — (irreversible, risk=high) | discards newer state |\n\n## Disk (2)\n\n| Tool | R/W | Inverse | Notes |\n|------|:---:|---------|-------|\n| `vm_resize_disk` | W | — (grow-only; shrink refused) | `+G` or larger absolute |\n| `vm_move_disk` | W | `vm_move_disk` (back to source storage) | task UPID |\n\n## Backups — vzdump (3)\n\n| Tool | R/W | Inverse | Notes |\n|------|:---:|---------|-------|\n| `backup_list` | R | — | archives on a storage, filterable by vmid |\n| `vm_backup` | W | — | task UPID; mode snapshot/suspend/stop |\n| `backup_restore` | W | `vm_delete` only when restored into a free vmid; none on forced overwrite (risk=high) | task UPID |\n\n## LXC containers (3)\n\n| Tool | R/W | Inverse |\n|------|:---:|---------|\n| `ct_list` | R | — |\n| `ct_start` | W | `ct_stop` |\n| `ct_stop` | W | `ct_start` |\n\n## Cluster / tasks (7)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `node_list` | R | status, cpu load, memory |\n| `cluster_status` | R | membership + quorum |\n| `task_status` | R | poll an async UPID (clone/migrate/backup) |\n| `cluster_resources` | R | `/cluster/resources` inventory (vm/node/storage filter) |\n| `node_status` | R | one node: cpu, load average, memory, uptime |\n| `task_log` | R | log lines of an async task by UPID |\n| `next_vmid` | R | a free VMID for a new guest |\n\n## HA (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `ha_status` | R | `{configured, entries}`; `configured` is true only when HA manages a resource — every cluster reports quorum/master/lrm rows regardless |\n| `ha_resource_list` | R | HA-managed resources; empty when HA absent |\n\n## Pools (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `pool_list` | R | poolid + comment |\n| `pool_members` | R | members (VMs/CTs/storage) of a pool |\n\n## Firewall — read-only (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `vm_firewall_rules_list` | R | per-VM firewall rules |\n| `cluster_firewall_status` | R | cluster firewall enable + default policies |\n\n## Guest agent (1)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `vm_agent_ping` | R | `responsive` bool; absence reported, not crashed |\n\n## Storage (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `storage_list` | R | pools: type, total/used/avail |\n| `storage_content` | R | volumes: ISOs, disk images, backups, templates |\n\n## Diagnostics / RCA (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `node_pressure_rca` | R | node CPU/memory/IO pressure: ranked causes + evidence |\n| `guest_health_rca` | R | one guest: ranked causes (resource, agent, disk, task history) |\n\n## Undo (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `undo_list` | R | recorded, not-yet-applied undo tokens (most recent first): original tool, inverse tool, `undoId` |\n| `undo_apply` | W | executes a recorded inverse by `undoId` — itself governed (the inverse re-gates on its own risk tier), single-use, `dry_run=True` previews |\n\n## Not yet covered\n\nVM create-from-scratch / template instantiation, guest agent **exec**\n(intentionally omitted as too risky), container create/clone/destroy, firewall\n**rule mutation** (read-only for now), and ACL management. These are the natural\nnext additions — each gets a matching `@governed_tool` wrapper and an `undo=`\ndeclaration where a clean inverse exists. Missing something? Open an issue/PR.\n\nFile v0.13.2:references/cli-reference.md\n\n# proxmox-aiops CLI reference\n\nAll commands take `--target/-t ` (config target; omit for default) and,\nwhere relevant, `--node/-n `. Destructive commands support `--dry-run`.\n\n## VM lifecycle\n\n```bash\nproxmox-aiops vm list [-t ] [-n ]\nproxmox-aiops vm get \nproxmox-aiops vm config \nproxmox-aiops vm start \nproxmox-aiops vm stop [--dry-run] # hard power-off (double confirm)\nproxmox-aiops vm shutdown [--dry-run] # graceful ACPI\nproxmox-aiops vm reboot \nproxmox-aiops vm reconfigure [--cores N] [--memory MiB] [--dry-run]\nproxmox-aiops vm clone --newid [--name ]\nproxmox-aiops vm delete [--dry-run] # irreversible (double confirm)\nproxmox-aiops vm migrate --to-node [--offline] [--dry-run]\n```\n\n## Snapshots\n\n```bash\nproxmox-aiops vm snapshot-create --name \nproxmox-aiops vm snapshot-list \nproxmox-aiops vm snapshot-delete --name [--dry-run] # double confirm\nproxmox-aiops vm snapshot-rollback --name [--dry-run] # irreversible\n```\n\n## LXC containers\n\n```bash\nproxmox-aiops ct list [-n ]\nproxmox-aiops ct start \nproxmox-aiops ct stop [--dry-run] # double confirm\n```\n\n## Cluster / async tasks\n\n```bash\nproxmox-aiops cluster nodes\nproxmox-aiops cluster status # membership + quorum\nproxmox-aiops cluster task-status # poll a clone/migrate/backup task\n```\n\n## Storage\n\n```bash\nproxmox-aiops storage list [-n ]\nproxmox-aiops storage content [--content iso|images|backup|vztmpl]\n```\n\n## Diagnostics & MCP\n\n```bash\nproxmox-aiops doctor # verify connectivity + credentials\nproxmox-aiops mcp # start the MCP server (stdio)\n```\n\n> Proxmox writes are asynchronous and return a task UPID. Poll completion with\n> `cluster task-status ` rather than re-issuing the operation.\n\nFile v0.13.2:references/setup-guide.md\n\n# proxmox-aiops setup guide\n\n## Install\n\n```bash\nuv tool install proxmox-aiops\n# or: pipx install proxmox-aiops\n```\n\n## Configure\n\n```bash\nmkdir -p ~/.proxmox-aiops && chmod 700 ~/.proxmox-aiops\n```\n\n`~/.proxmox-aiops/config.yaml` (no secrets here):\n\n```yaml\ntargets:\n - name: pve-lab\n host: 10.0.0.10\n user: \"root@pam!claude\" # API token form: user@realm!tokenid\n node: pve1 # default node for this target\n auth_kind: token # 'token' or 'password'\n verify_ssl: false # self-signed lab certs only; true in prod\n```\n\n`~/.proxmox-aiops/.env` (chmod 600 — secrets only):\n\n```bash\nPROXMOX_PVE_LAB_SECRET=\n```\n\nThe secret variable is `PROXMOX__SECRET` (hyphens → underscores).\n\n```bash\nchmod 600 ~/.proxmox-aiops/.env\nproxmox-aiops doctor # verifies connectivity + credentials\n```\n\n## Use as an MCP server\n\n```jsonc\n{\n \"command\": \"proxmox-aiops\",\n \"args\": [\"mcp\"],\n \"env\": { \"PROXMOX_AIOPS_CONFIG\": \"~/.proxmox-aiops/config.yaml\" }\n}\n```\n\nUsing the `proxmox-aiops mcp` subcommand (rather than `uvx --from`) means the\nMCP client launches the already-installed entry point and does not re-resolve\nthe package over the network at startup.\n\n## Security\n\n> **Disclaimer**: Community-maintained project, **not affiliated with Proxmox\n> Server Solutions GmbH**. MIT licensed. See `SECURITY.md`.\n\n- **Credentials**: `.env` only, chmod 600, per-target `PROXMOX__SECRET`.\n- **Audit**: every operation logged to a local SQLite DB under\n `~/.proxmox-aiops/` (relocate with `PROXMOX_AIOPS_HOME`).\n- **Budget guard**: cap calls/wall-time with `PROXMOX_MAX_TOOL_CALLS` /\n `PROXMOX_MAX_TOOL_SECONDS`; a runaway poll/retry loop trips automatically.\n- **Risk tiers**: each tool's `risk_level` is recorded on the audit row as a\n descriptive tier (none/confirm/review) — a label, not a gate.\n `PROXMOX_AUDIT_APPROVED_BY` / `PROXMOX_AUDIT_RATIONALE` are optional audit\n annotations, never required.\n- **Destructive ops**: double confirmation + `--dry-run` at the CLI.\n- **TLS**: `verify_ssl` defaults true; disable only for self-signed labs.\n- **No webhooks / telemetry / background services.**\n\n## Least privilege\n\nCreate a dedicated Proxmox API token with only the roles your workflows need\n(e.g. `PVEVMAdmin` on the relevant pool) rather than `root@pam`.\n\nFile v0.13.2:skill-card.md\n\n## Description:\n\nUse this skill to manage and diagnose Proxmox VE virtual machines, containers, storage, backups, snapshots, cluster health, HA, pools, firewall status, and async tasks through governed CLI and MCP operations.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[zw008](https://clawhub.ai/user/zw008)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and infrastructure operators use this skill to inspect, operate, and troubleshoot Proxmox VE environments with audited read and write workflows. It is intended for explicit Proxmox VE tasks such as VM lifecycle changes, snapshots, backups, migration, storage inspection, and read-only cluster diagnostics.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The release installs a community package that can receive operational access to Proxmox infrastructure.\n\nMitigation: Install only a pinned and verified package version, and review the package before granting access to production systems.\n\nRisk: The skill handles powerful Proxmox credentials and can perform destructive operations.\n\nMitigation: Use a dedicated least-privilege API token, keep TLS verification enabled, protect the local Proxmox configuration directory, and start with dry runs or read-only credentials.\n\nRisk: Write operations can change VM, container, disk, backup, snapshot, and migration state.\n\nMitigation: Confirm the target VMID, node, storage, and task status before action; prefer dry-run previews and use recorded undo identifiers where available.\n\n## Reference(s):\n\n- [Proxmox AIops project homepage](https://github.com/AIops-tools/Proxmox-AIops)\n- [ClawHub skill page](https://clawhub.ai/zw008/skills/proxmox-aiops)\n- [Capabilities](references/capabilities.md)\n- [CLI reference](references/cli-reference.md)\n- [Setup guide](references/setup-guide.md)\n- [Agent guardrails](references/agent-guardrails.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance, API calls]\n\n**Output Format:** [Markdown guidance with inline shell commands and structured MCP tool results]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Outputs may include Proxmox task UPIDs, audit references, dry-run previews, ranked diagnostic findings, and undo identifiers for reversible writes.]\n\n## Skill Version(s):\n\n0.13.2 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.13.1: 7 files, 14944 bytes\n\nFiles: references/agent-guardrails.md (4785b), references/capabilities.md (4523b), references/cli-reference.md (2012b), references/setup-guide.md (2363b), skill-card.md (2770b), SKILL.md (15976b), _meta.json (133b)\n\nFile v0.13.1:SKILL.md\n\n---\nname: proxmox-aiops\nslug: proxmox-aiops\ndisplayName: \"Proxmox AIops\"\nsummary: \"Governed Proxmox VE VM/container ops — 43 MCP tools with audit, budget, undo & risk-tier guards.\"\nlicense: MIT\nhomepage: https://github.com/AIops-tools/Proxmox-AIops\ntags: [aiops, mcp, governance, proxmox]\ndescription: >\n Use this skill whenever the user needs to manage VMs and containers on Proxmox VE — list/inspect/configure VMs, power and lifecycle (start/stop/shutdown/reboot/reconfigure/clone/delete/migrate), snapshots (create/delete/list/rollback), disk grow/move, vzdump backups (create/list/restore), LXC containers (list/start/stop), cluster/node status, cluster resource inventory, async task polling + logs, free-VMID lookup, HA status, resource pools, firewall inspection, guest-agent ping, and storage listing.\n Also use it to diagnose cluster health — rank nodes by CPU/memory/disk pressure and scan guests for saturation (read-only RCA).\n Always use this skill for \"list proxmox vms\", \"start proxmox vm\", \"stop proxmox vm\", \"proxmox snapshot\", \"proxmox backup\", \"restore proxmox vm\", \"resize proxmox disk\", \"proxmox vm status\", \"migrate proxmox vm\", \"proxmox container\", \"proxmox ha\", \"proxmox pool\", \"proxmox firewall\", \"list proxmox storage\", \"proxmox node pressure\", or \"why is proxmox slow\" when the context is explicitly Proxmox / Proxmox VE / PVE.\n Do NOT use for non-Proxmox hypervisors, Kubernetes, or cloud providers.\n Broad coverage of common Proxmox operations, with a built-in governance harness (audit, token budget, undo, risk-tier labels).\ninstaller:\n kind: uv\n package: proxmox-aiops\nargument-hint: \"[vmid or describe your Proxmox task]\"\nallowed-tools:\n - Bash\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"proxmox-aiops\",\"uvx\"]},\"optional\":{\"env\":[\"PROXMOX_AIOPS_CONFIG\",\"PROXMOX_TARGET_SECRET\"]},\"homepage\":\"https://github.com/AIops-tools/Proxmox-AIops\",\"emoji\":\"🧱\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n Standalone, self-governed Proxmox VE operations. The governance harness (audit, token/runaway budget, undo, risk-tier labels) is bundled in the package — no external skill-family dependency.\n All write operations are audited to a local SQLite DB under ~/.proxmox-aiops/ (relocatable via PROXMOX_AIOPS_HOME).\n Credentials: Each Proxmox target requires a per-target secret env var in ~/.proxmox-aiops/.env following the pattern PROXMOX__SECRET (API token UUID for token auth, or login password). Secrets are never logged or echoed; .env should be chmod 600.\n Destructive operations (vm stop/delete/snapshot-delete/snapshot-rollback, ct stop) require double confirmation at the CLI layer and support --dry-run. All write tools pass through the @governed_tool decorator (budget guard + audit + risk-tier tagging). Reversible writes record an inverse undo descriptor to the undo store.\n Webhooks: none — no outbound network calls beyond the configured Proxmox API endpoint.\n SSL: verify_ssl defaults to true; disable only for self-signed lab certificates.\n Transitive dependencies: proxmoxer (Proxmox API client) and the MCP SDK. No post-install scripts or background services.\n---\n\n# Proxmox AIops\n\n> **Disclaimer**: This is a community-maintained open-source project and is **not affiliated with, endorsed by, or sponsored by Proxmox Server Solutions GmbH.** \"Proxmox\" is a trademark of its owner. Source code is publicly auditable at [github.com/AIops-tools/Proxmox-AIops](https://github.com/AIops-tools/Proxmox-AIops) under the MIT license.\n\nGoverned VM and container lifecycle operations for Proxmox VE — **43 MCP tools**, every one wrapped with the bundled `@governed_tool` harness: a local unified audit log under `~/.proxmox-aiops/`, token/runaway budget guard, undo-token recording, and descriptive risk-tier labels.\n\n> **Standalone**: the governance harness is bundled in the package (`proxmox_aiops.governance`) — proxmox-aiops has no external skill-family dependency. Coverage focuses on common Proxmox operations and is not yet exhaustive.\n\n## What This Skill Does\n\n| Category | Tools | Count | Read or Write |\n|----------|-------|:-----:|:-------------:|\n| **VM Lifecycle** | list, get, config, start, stop, shutdown, reboot, reconfigure, clone, delete, migrate | 11 | 3 read / 8 write |\n| **Snapshots** | create, delete, list, rollback | 4 | 1 read / 3 write |\n| **Disk** | resize (grow-only), move | 2 | 0 read / 2 write |\n| **Backups (vzdump)** | create, list, restore | 3 | 1 read / 2 write |\n| **LXC Containers** | list, start, stop | 3 | 1 read / 2 write |\n| **Cluster / Tasks** | node list, cluster status, task poll, cluster resources, node status, task log, next vmid | 7 | 7 read |\n| **HA** | status, resource list | 2 | 2 read |\n| **Pools** | list, members | 2 | 2 read |\n| **Firewall** | vm rules, cluster status | 2 | 2 read |\n| **Guest Agent** | ping | 1 | 1 read |\n| **Storage** | list pools, list content | 2 | 2 read |\n| **Diagnostics / RCA** | node-pressure, guest-health | 2 | 2 read |\n\n## Quick Install\n\n```bash\nuv tool install proxmox-aiops\nproxmox-aiops doctor\n```\n\nOr as an OpenClaw plugin, which installs this skill and its MCP server together:\n\n```bash\nopenclaw plugins install clawhub:@aiops-tools/proxmox-aiops\nopenclaw skills info proxmox-aiops # expect: Visible to model: yes\n```\n\nNeeds `uvx` on `PATH`: the MCP server is fetched with uv, pinned to this release.\n\n## When to Use This Skill\n\n- List/inspect Proxmox QEMU VMs and their config\n- Power ops: start, hard-stop, graceful shutdown, reboot\n- Reconfigure (cores/memory), clone, delete, or migrate a VM between nodes\n- Grow a VM disk (grow-only — shrink is refused) or move it to another storage\n- Create, list, and restore vzdump backups\n- Create / delete / list / roll back VM snapshots\n- Manage LXC containers (list, start, stop)\n- Inspect cluster nodes, quorum, the `/cluster/resources` inventory, node load/mem, and poll async tasks + fetch their logs by UPID; get a free VMID\n- Check HA status / HA-managed resources (handles \"HA not configured\" gracefully)\n- List resource pools and their members\n- Inspect VM firewall rules and the cluster firewall enable state (read-only)\n- Ping a VM's QEMU guest agent\n- List storage pools and their content (ISOs, disk images, backups)\n- **Diagnose** cluster health: rank nodes by CPU/memory/root-fs pressure, and scan VMs/containers for stopped guests, memory saturation, and disks near full — each finding cites the measured number and a concrete action (read-only RCA)\n\n**Do NOT use when** the target is not Proxmox VE (other hypervisors, Kubernetes, or cloud providers are out of scope for this skill).\n\n## Common Workflows\n\n### Triage a \"cluster feels slow\" complaint (read-only)\n\n1. `proxmox-aiops diagnose node-pressure` → worst-first table of nodes over the CPU/mem/disk thresholds, each row citing the measured % and the fix\n2. `proxmox-aiops diagnose guest-health` → guests near their memory ceiling or with disks near full, plus the list of stopped guests\n3. Act on the top finding — e.g. `proxmox-aiops vm migrate --to-node ` to shed load off a hot node, or `vm reconfigure --memory ...` for a RAM-starved guest. All of these route through the governed path (audited, undo recorded).\n\n### Snapshot, then reconfigure a VM\n\n1. `proxmox-aiops vm list` → find the vmid and confirm it is the right VM/node\n2. `proxmox-aiops vm snapshot-create --name pre-change` → baseline before any risky change\n3. `proxmox-aiops vm reconfigure --cores 8 --memory 16384` → the harness captures the prior cores/memory as the undo descriptor\n4. **Failure branch**: if the change goes wrong, the write recorded an `_undo_id` — reverse it with `proxmox-aiops undo apply `, or roll back with `proxmox-aiops vm snapshot-rollback --name pre-change`.\n\n### Free a node that is out of memory\n\n1. `proxmox-aiops diagnose node-pressure` → identify the node flagged `high memory`\n2. `proxmox-aiops cluster resources --type vm` → find a movable guest on that node\n3. `proxmox-aiops vm migrate --to-node --dry-run` → preview, then run without `--dry-run` (migrate is `high` risk; the inverse migrate-back is recorded)\n4. Re-run `diagnose node-pressure` to confirm the pressure cleared.\n\n### Stop a VM safely\n\n1. `proxmox-aiops vm get ` → confirm current status is `running`\n2. `proxmox-aiops vm stop --dry-run` → preview the exact API call\n3. `proxmox-aiops vm stop ` → double confirmation required; `vm_stop` records an inverse `vm_start` undo descriptor\n4. **Failure branch**: if `doctor` shows the node unreachable or the secret env var is missing, fix credentials with `proxmox-aiops secret set ` before retrying — the stop is never issued against an unauthenticated session.\n\n## Usage Mode\n\n| Scenario | Recommended | Why |\n|----------|:-----------:|-----|\n| Local/small models | **CLI** | fewer tokens than MCP |\n| Cloud models (Claude, GPT) | Either | MCP gives structured JSON I/O |\n| Automated pipelines | **MCP** | type-safe parameters, audited |\n\n## MCP Tools (43 — 25 read, 18 write)\n\n| Category | Tools | R/W |\n|----------|-------|:---:|\n| VM Lifecycle | `vm_list`, `vm_get`, `vm_config` | Read |\n| | `vm_start`, `vm_stop`, `vm_shutdown`, `vm_reboot`, `vm_reconfigure`, `vm_clone`, `vm_delete`, `vm_migrate` | Write |\n| Snapshots | `vm_list_snapshots` | Read |\n| | `vm_snapshot_create`, `vm_snapshot_delete`, `vm_snapshot_rollback` | Write |\n| Disk | `vm_resize_disk` (grow-only), `vm_move_disk` | Write |\n| Backups | `backup_list` | Read |\n| | `vm_backup`, `backup_restore` (high) | Write |\n| LXC Containers | `ct_list` | Read |\n| | `ct_start`, `ct_stop` | Write |\n| Cluster / Tasks | `node_list`, `cluster_status`, `task_status`, `cluster_resources`, `node_status`, `task_log`, `next_vmid` | Read |\n| HA | `ha_status`, `ha_resource_list` | Read |\n| Pools | `pool_list`, `pool_members` | Read |\n| Firewall | `vm_firewall_rules_list`, `cluster_firewall_status` | Read |\n| Guest Agent | `vm_agent_ping` | Read |\n| Storage | `storage_list`, `storage_content` | Read |\n| Diagnostics / RCA | `node_pressure_rca`, `guest_health_rca` | Read |\n| Undo | `undo_list` | Read |\n| | `undo_apply` | Write |\n\n**Harness features that light up**: write tools with a clean inverse (`vm_start`/`vm_stop`/`vm_shutdown`/`vm_reconfigure`/`vm_clone`/`vm_migrate`/`vm_snapshot_create`/`vm_move_disk`/`ct_start`/`ct_stop`) pass an `undo=` lambda so the harness records an inverse descriptor (with `_undo_id`) to the undo store — `vm_reconfigure` captures the prior cores/memory, `vm_clone`'s inverse is `vm_delete(newid)`, `vm_migrate`'s is migrate-back, `vm_move_disk`'s is move-back to the captured source storage. `backup_restore` records a `vm_delete` inverse **only** when it restored into a free VMID (a forced overwrite is destructive and declares none). Irreversible writes (`vm_delete`, `vm_snapshot_rollback`, `backup_restore` with `force`) declare no undo and are tagged `risk_level=high`; `vm_resize_disk` is grow-only and refuses shrink before any API call. All 43 tools are audit-logged under `~/.proxmox-aiops/` and pass through the budget/runaway guard + risk-tier tagging. Proxmox writes are async (return a task UPID) — poll with `task_status` (and read lines with `task_log`) instead of re-issuing (the runaway breaker backs this up).\n\n## CLI Quick Reference\n\n```bash\nproxmox-aiops vm list [--target ] [--node ]\nproxmox-aiops vm get [--node ]\nproxmox-aiops vm start [--node ]\nproxmox-aiops vm stop [--dry-run] # double confirm\nproxmox-aiops vm resize-disk --disk scsi0 --size +10G # grow-only\nproxmox-aiops vm move-disk --disk scsi0 --storage ceph [--delete]\nproxmox-aiops vm agent-ping \nproxmox-aiops vm snapshot-create --name \nproxmox-aiops vm snapshot-delete --name [--dry-run] # double confirm\nproxmox-aiops vm snapshot-list \nproxmox-aiops backup create --storage [--mode snapshot]\nproxmox-aiops backup list [--vmid ]\nproxmox-aiops backup restore --archive --storage [--force] [--dry-run] # double confirm\nproxmox-aiops cluster resources [--type vm|node|storage]\nproxmox-aiops cluster node-status \nproxmox-aiops cluster task-log \nproxmox-aiops cluster next-vmid\nproxmox-aiops ha status\nproxmox-aiops pool list\nproxmox-aiops firewall vm-rules \nproxmox-aiops storage list [--node ]\nproxmox-aiops diagnose node-pressure # rank nodes by CPU/mem/disk pressure (read-only RCA)\nproxmox-aiops diagnose guest-health # stopped guests, mem saturation, disks near full\nproxmox-aiops undo apply # reverse a recorded governed write\nproxmox-aiops init # onboarding wizard (encrypted creds)\nproxmox-aiops secret set # manage encrypted secret store\nproxmox-aiops doctor\nproxmox-aiops mcp # start MCP server (stdio)\n```\n\n> Credentials are managed by the `proxmox-aiops init` onboarding wizard and the\n> `proxmox-aiops secret` commands, which back an encrypted secret store (no\n> plaintext passwords in `config.yaml`).\n\n## Troubleshooting\n\n### \"Config file not found\"\nCreate `~/.proxmox-aiops/config.yaml` with a `targets:` list (see README), and put secrets in `~/.proxmox-aiops/.env` (chmod 600).\n\n### \"Secret not found. Set environment variable: PROXMOX__SECRET\"\nEach target needs a per-target secret env var. For target `pve-lab`, set `PROXMOX_PVE_LAB_SECRET=` in `.env`.\n\n### \"Token auth requires user in the form 'user@realm!tokenid'\"\nFor API-token auth (recommended, least privilege), `user` must include the token id after `!`, e.g. `root@pam!claude`. For password auth set `auth_kind: password` and use `user@realm`.\n\n### \"No node specified and no default node configured\"\nEither pass `--node ` / `node=`, or set `node:` on the target in `config.yaml`. VM operations can auto-locate a vmid across nodes, but storage listing needs an explicit node.\n\n## Audit & Safety\n\nThe skill delivers reads and writes and records them; it does **not** decide whether a write is\npermitted. That is your agent's judgement, or the permission of the account you connect it with —\nuse a Proxmox VE user or API token granted only read privileges (no VM.*/Datastore.* write roles),\nand writes then fail at the server. There is no read-only switch, policy file, or approval gate.\n\n- **Audit is the guarantee, and it is not bypassable.** Every operation — MCP and CLI alike — is logged to `~/.proxmox-aiops/audit.db` (relocatable via `PROXMOX_AIOPS_HOME`): params, result, status, duration, and the risk tier. The CLI writes the same row the MCP path does.\n- `PROXMOX_AUDIT_APPROVED_BY` / `PROXMOX_AUDIT_RATIONALE` are optional annotations recorded on the audit row (who/why); they are never required and never block.\n- **Runaway guard** — a safety backstop, not authorization: the same call looped in a tight window trips a circuit breaker. Disable with `PROXMOX_RUNAWAY_MAX=0`; optional hard ceilings via `PROXMOX_MAX_TOOL_CALLS` / `PROXMOX_MAX_TOOL_SECONDS`.\n- Undo store records inverse descriptors for reversible writes (start/stop/shutdown/reconfigure/clone/migrate/snapshot-create, container start/stop).\n- Writes support `--dry-run` / `dry_run=True` and double confirmation at the CLI.\n\nThe harness is bundled in the package — no external dependency, no manual setup.\n\n## Contributing & feature requests\n\nCoverage is intentionally focused. **Missing a device, action, or feature you need?** Open an issue or pull request at [github.com/AIops-tools/Proxmox-AIops](https://github.com/AIops-tools/Proxmox-AIops/issues) — feature requests, contributions, and comments are all welcome.\n\n## License\n\nMIT — [github.com/AIops-tools/Proxmox-AIops](https://github.com/AIops-tools/Proxmox-AIops)\n\nFile v0.13.1:_meta.json\n\n{\n \"ownerId\": \"kn7b067awq2s97bn3d7p5qfhw5827pxc\",\n \"slug\": \"proxmox-aiops\",\n \"version\": \"0.13.1\",\n \"publishedAt\": 1789208631301\n}\n\nFile v0.13.1:references/agent-guardrails.md\n\n# Agent guardrails — running proxmox-aiops with a smaller / local model\n\nIf you drive these tools with a local model (Llama, Qwen, Mistral … via Goose,\nOllama, LM Studio, or any OpenAI-compatible runtime), you will get noticeably\nbetter results with a short system prompt. This page gives you one, and — more\nimportantly — tells you which guardrails you **no longer need to write**, because\nthe tool now enforces them itself.\n\nThe distinction matters. A guardrail in a prompt is a request. A guardrail in the\nharness is a guarantee. Anything below that we could move into the harness, we did.\n\n## What the tool now enforces — do not waste prompt budget on these\n\n| You might be tempted to prompt | Why you don't need to |\n|---|---|\n| \"Don't invent a value when a field is missing\" | A field the API did not return comes back as `null`, never as `\"\"`. Absent and empty are distinguishable in the payload. |\n| \"Tell me if the output was cut off\" | Anything with a `limit` returns `{\"lines\": [...], \"returned\": N, \"limit\": L, \"truncated\": true/false}`. Truncation is measured (one extra row is fetched), not guessed. |\n| \"Preserve the ordering / tell me what's most urgent\" | `diagnose` findings carry an explicit 1-based `rank`, worst-first. Priority is in the payload, not implied by list position. |\n| \"Confirm before anything destructive\" | Destructive operations require a `--dry-run`-able preview + double confirmation at the CLI. |\n| \"Log what you did\" | Every call is audited to `~/.proxmox-aiops/audit.db` regardless of what the model says it did. |\n\n## What still needs a prompt\n\nThese are model-behaviour problems the harness cannot fix from the outside.\nCopy this into your agent's system prompt:\n\n```text\nYou operate a Proxmox VE environment through the proxmox-aiops MCP tools.\n\nTOOL USE\n- Before answering any question about the current Proxmox environment, you MUST\n call a tool. Never answer from memory or assumption.\n- Actually invoke the tool. Do not describe the call you would make, and do not\n emit an example JSON response in place of calling it.\n- If a tool call fails, report the real error verbatim. Never fill the gap with\n a plausible-sounding answer.\n\nREADING RESULTS\n- Read the whole result before concluding. If a result contains a \"truncated\"\n field that is true, say so and re-run with a higher limit instead of treating\n the partial result as complete.\n- A null field means the API did not return that value. Report it as \"not\n available\" — never infer it.\n- Report values exactly as returned. Do not normalise, translate, or prettify\n status strings, severities, or IDs.\n- When a diagnose result has findings, work in \"rank\" order and cite the\n measured number in each finding's \"detail\".\n\nSCOPE\n- Separate observation from interpretation. State what the tools returned, then\n any interpretation, clearly marked as such.\n- Do not assert a capacity, performance, or availability problem unless a tool\n result supports it.\n- Do not add generic advice that does not follow from the tool output.\n- Do not confuse a VMID with a node name, or a task UPID with either.\n```\n\n## Recommended setup for a local model\n\nAuthorization is not this tool's job — decide it via the account you connect\nwith or the agent's prompt, not a switch in the tool. To work read-only, connect\nwith a Proxmox VE user or API token granted only read privileges (no\n`VM.*`/`Datastore.*` write roles); a write then fails at the server, the place\nthat actually owns the permission.\n\n```bash\nproxmox-aiops doctor # verify connectivity with your least-privilege token\n```\n\nOptionally, annotate who is running changes and why — these land on the audit\nrow, and are never required and never blocking:\n\n```bash\nexport PROXMOX_AUDIT_APPROVED_BY=\"your.name@example.com\"\nexport PROXMOX_AUDIT_RATIONALE=\"scheduled maintenance window\"\n```\n\n## If your model still struggles\n\nSome behaviours are model-capacity limits rather than prompt problems:\n\n- **Multi-tool workflows time out or drift.** Prefer the `diagnose` tools — they\n do the multi-step correlation inside one call, so the model does not have to\n chain reads and keep IDs straight.\n- **The model ignores later tool results in a long context.** Ask narrower\n questions and use `--limit` deliberately rather than pulling whole inventories.\n- **The model describes calls instead of making them.** This is usually a\n runtime/tool-calling-format mismatch, not a prompt problem — check that your\n client advertises the tools in the format your model was trained on.\n\nFeedback on running this with a specific local model is genuinely useful —\nopen an issue at\n[github.com/AIops-tools/Proxmox-AIops](https://github.com/AIops-tools/Proxmox-AIops/issues)\nwith the model, runtime, and what went wrong.\n\nFile v0.13.1:references/capabilities.md\n\n# proxmox-aiops capabilities\n\n43 MCP tools (25 read / 18 write). Every tool is wrapped with the bundled\n`@governed_tool` harness (audit + budget + risk-tier + undo). Typical response\nsizes are small high-signal summaries, not full API blobs.\n\n## VM lifecycle (11)\n\n| Tool | R/W | Inverse (undo) | Typical response |\n|------|:---:|----------------|------------------|\n| `vm_list` | R | — | ~50–500 tok (one row per VM) |\n| `vm_get` | R | — | ~120 tok |\n| `vm_config` | R | — | ~120 tok |\n| `vm_start` | W | `vm_stop` | task UPID |\n| `vm_stop` | W | `vm_start` | task UPID |\n| `vm_shutdown` | W | `vm_start` | task UPID |\n| `vm_reboot` | W | — (no inverse) | task UPID |\n| `vm_reconfigure` | W | `vm_reconfigure` (prior cores/memory) | applied + previous |\n| `vm_clone` | W | `vm_delete(newid)` | task UPID |\n| `vm_delete` | W | — (irreversible, risk=high) | task UPID |\n| `vm_migrate` | W | `vm_migrate` (back to source node) | task UPID |\n\n## Snapshots (4)\n\n| Tool | R/W | Inverse | Notes |\n|------|:---:|---------|-------|\n| `vm_list_snapshots` | R | — | name + description |\n| `vm_snapshot_create` | W | `vm_snapshot_delete` | |\n| `vm_snapshot_delete` | W | — | |\n| `vm_snapshot_rollback` | W | — (irreversible, risk=high) | discards newer state |\n\n## Disk (2)\n\n| Tool | R/W | Inverse | Notes |\n|------|:---:|---------|-------|\n| `vm_resize_disk` | W | — (grow-only; shrink refused) | `+G` or larger absolute |\n| `vm_move_disk` | W | `vm_move_disk` (back to source storage) | task UPID |\n\n## Backups — vzdump (3)\n\n| Tool | R/W | Inverse | Notes |\n|------|:---:|---------|-------|\n| `backup_list` | R | — | archives on a storage, filterable by vmid |\n| `vm_backup` | W | — | task UPID; mode snapshot/suspend/stop |\n| `backup_restore` | W | `vm_delete` only when restored into a free vmid; none on forced overwrite (risk=high) | task UPID |\n\n## LXC containers (3)\n\n| Tool | R/W | Inverse |\n|------|:---:|---------|\n| `ct_list` | R | — |\n| `ct_start` | W | `ct_stop` |\n| `ct_stop` | W | `ct_start` |\n\n## Cluster / tasks (7)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `node_list` | R | status, cpu load, memory |\n| `cluster_status` | R | membership + quorum |\n| `task_status` | R | poll an async UPID (clone/migrate/backup) |\n| `cluster_resources` | R | `/cluster/resources` inventory (vm/node/storage filter) |\n| `node_status` | R | one node: cpu, load average, memory, uptime |\n| `task_log` | R | log lines of an async task by UPID |\n| `next_vmid` | R | a free VMID for a new guest |\n\n## HA (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `ha_status` | R | `{configured, entries}`; `configured` is true only when HA manages a resource — every cluster reports quorum/master/lrm rows regardless |\n| `ha_resource_list` | R | HA-managed resources; empty when HA absent |\n\n## Pools (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `pool_list` | R | poolid + comment |\n| `pool_members` | R | members (VMs/CTs/storage) of a pool |\n\n## Firewall — read-only (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `vm_firewall_rules_list` | R | per-VM firewall rules |\n| `cluster_firewall_status` | R | cluster firewall enable + default policies |\n\n## Guest agent (1)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `vm_agent_ping` | R | `responsive` bool; absence reported, not crashed |\n\n## Storage (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `storage_list` | R | pools: type, total/used/avail |\n| `storage_content` | R | volumes: ISOs, disk images, backups, templates |\n\n## Diagnostics / RCA (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `node_pressure_rca` | R | node CPU/memory/IO pressure: ranked causes + evidence |\n| `guest_health_rca` | R | one guest: ranked causes (resource, agent, disk, task history) |\n\n## Undo (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `undo_list` | R | recorded, not-yet-applied undo tokens (most recent first): original tool, inverse tool, `undoId` |\n| `undo_apply` | W | executes a recorded inverse by `undoId` — itself governed (the inverse re-gates on its own risk tier), single-use, `dry_run=True` previews |\n\n## Not yet covered\n\nVM create-from-scratch / template instantiation, guest agent **exec**\n(intentionally omitted as too risky), container create/clone/destroy, firewall\n**rule mutation** (read-only for now), and ACL management. These are the natural\nnext additions — each gets a matching `@governed_tool` wrapper and an `undo=`\ndeclaration where a clean inverse exists. Missing something? Open an issue/PR.\n\nFile v0.13.1:references/cli-reference.md\n\n# proxmox-aiops CLI reference\n\nAll commands take `--target/-t ` (config target; omit for default) and,\nwhere relevant, `--node/-n `. Destructive commands support `--dry-run`.\n\n## VM lifecycle\n\n```bash\nproxmox-aiops vm list [-t ] [-n ]\nproxmox-aiops vm get \nproxmox-aiops vm config \nproxmox-aiops vm start \nproxmox-aiops vm stop [--dry-run] # hard power-off (double confirm)\nproxmox-aiops vm shutdown [--dry-run] # graceful ACPI\nproxmox-aiops vm reboot \nproxmox-aiops vm reconfigure [--cores N] [--memory MiB] [--dry-run]\nproxmox-aiops vm clone --newid [--name ]\nproxmox-aiops vm delete [--dry-run] # irreversible (double confirm)\nproxmox-aiops vm migrate --to-node [--offline] [--dry-run]\n```\n\n## Snapshots\n\n```bash\nproxmox-aiops vm snapshot-create --name \nproxmox-aiops vm snapshot-list \nproxmox-aiops vm snapshot-delete --name [--dry-run] # double confirm\nproxmox-aiops vm snapshot-rollback --name [--dry-run] # irreversible\n```\n\n## LXC containers\n\n```bash\nproxmox-aiops ct list [-n ]\nproxmox-aiops ct start \nproxmox-aiops ct stop [--dry-run] # double confirm\n```\n\n## Cluster / async tasks\n\n```bash\nproxmox-aiops cluster nodes\nproxmox-aiops cluster status # membership + quorum\nproxmox-aiops cluster task-status # poll a clone/migrate/backup task\n```\n\n## Storage\n\n```bash\nproxmox-aiops storage list [-n ]\nproxmox-aiops storage content [--content iso|images|backup|vztmpl]\n```\n\n## Diagnostics & MCP\n\n```bash\nproxmox-aiops doctor # verify connectivity + credentials\nproxmox-aiops mcp # start the MCP server (stdio)\n```\n\n> Proxmox writes are asynchronous and return a task UPID. Poll completion with\n> `cluster task-status ` rather than re-issuing the operation.\n\nFile v0.13.1:references/setup-guide.md\n\n# proxmox-aiops setup guide\n\n## Install\n\n```bash\nuv tool install proxmox-aiops\n# or: pipx install proxmox-aiops\n```\n\n## Configure\n\n```bash\nmkdir -p ~/.proxmox-aiops && chmod 700 ~/.proxmox-aiops\n```\n\n`~/.proxmox-aiops/config.yaml` (no secrets here):\n\n```yaml\ntargets:\n - name: pve-lab\n host: 10.0.0.10\n user: \"root@pam!claude\" # API token form: user@realm!tokenid\n node: pve1 # default node for this target\n auth_kind: token # 'token' or 'password'\n verify_ssl: false # self-signed lab certs only; true in prod\n```\n\n`~/.proxmox-aiops/.env` (chmod 600 — secrets only):\n\n```bash\nPROXMOX_PVE_LAB_SECRET=\n```\n\nThe secret variable is `PROXMOX__SECRET` (hyphens → underscores).\n\n```bash\nchmod 600 ~/.proxmox-aiops/.env\nproxmox-aiops doctor # verifies connectivity + credentials\n```\n\n## Use as an MCP server\n\n```jsonc\n{\n \"command\": \"proxmox-aiops\",\n \"args\": [\"mcp\"],\n \"env\": { \"PROXMOX_AIOPS_CONFIG\": \"~/.proxmox-aiops/config.yaml\" }\n}\n```\n\nUsing the `proxmox-aiops mcp` subcommand (rather than `uvx --from`) means the\nMCP client launches the already-installed entry point and does not re-resolve\nthe package over the network at startup.\n\n## Security\n\n> **Disclaimer**: Community-maintained project, **not affiliated with Proxmox\n> Server Solutions GmbH**. MIT licensed. See `SECURITY.md`.\n\n- **Credentials**: `.env` only, chmod 600, per-target `PROXMOX__SECRET`.\n- **Audit**: every operation logged to a local SQLite DB under\n `~/.proxmox-aiops/` (relocate with `PROXMOX_AIOPS_HOME`).\n- **Budget guard**: cap calls/wall-time with `PROXMOX_MAX_TOOL_CALLS` /\n `PROXMOX_MAX_TOOL_SECONDS`; a runaway poll/retry loop trips automatically.\n- **Risk tiers**: each tool's `risk_level` is recorded on the audit row as a\n descriptive tier (none/confirm/review) — a label, not a gate.\n `PROXMOX_AUDIT_APPROVED_BY` / `PROXMOX_AUDIT_RATIONALE` are optional audit\n annotations, never required.\n- **Destructive ops**: double confirmation + `--dry-run` at the CLI.\n- **TLS**: `verify_ssl` defaults true; disable only for self-signed labs.\n- **No webhooks / telemetry / background services.**\n\n## Least privilege\n\nCreate a dedicated Proxmox API token with only the roles your workflows need\n(e.g. `PVEVMAdmin` on the relevant pool) rather than `root@pam`.\n\nFile v0.13.1:skill-card.md\n\n## Description:\n\nProxmox AIops helps agents manage and diagnose Proxmox VE virtual machines, containers, cluster resources, storage, backups, snapshots, firewall state, HA resources, and common lifecycle operations with audit, undo, and risk-tier guardrails.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[zw008](https://clawhub.ai/user/zw008)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, platform engineers, and infrastructure operators use this skill to inspect, troubleshoot, and perform governed VM and container operations in explicitly Proxmox VE environments. It is suited for agent-assisted operations where read/write actions should be auditable and destructive actions require extra care.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can make destructive infrastructure changes such as stopping, deleting, rolling back, restoring, migrating, or reconfiguring Proxmox guests.\n\nMitigation: Use dry-run previews where available, require human review for destructive actions, and connect with a dedicated least-privilege Proxmox API token so unauthorized writes fail at the server.\n\nRisk: Credential handling, TLS configuration, and package provenance are left under user control.\n\nMitigation: Pin a reviewed package version, keep TLS verification enabled in production, avoid plaintext passwords where possible, and restrict permissions on Proxmox AIops configuration, audit, and undo files.\n\nRisk: Audit and undo data can reveal sensitive infrastructure details.\n\nMitigation: Treat local audit and undo files as sensitive operational records and store them with restricted filesystem permissions.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/zw008/skills/proxmox-aiops)\n- [Project homepage](https://github.com/AIops-tools/Proxmox-AIops)\n- [Capabilities reference](references/capabilities.md)\n- [CLI reference](references/cli-reference.md)\n- [Setup guide](references/setup-guide.md)\n- [Agent guardrails](references/agent-guardrails.md)\n\n## Skill Output:\n\n**Output Type(s):** [guidance, shell commands, configuration, analysis, API calls]\n\n**Output Format:** [Markdown with inline shell commands and structured MCP tool results]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May return Proxmox task UPIDs for asynchronous write operations; operational outputs can include audit and undo identifiers.]\n\n## Skill Version(s):\n\n0.13.1 (source: ClawHub release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.13.0: 7 files, 14663 bytes\n\nFiles: references/agent-guardrails.md (4785b), references/capabilities.md (4523b), references/cli-reference.md (2012b), references/setup-guide.md (2363b), skill-card.md (2401b), SKILL.md (15662b), _meta.json (133b)\n\nFile v0.13.0:SKILL.md\n\n---\nname: proxmox-aiops\nslug: proxmox-aiops\ndisplayName: \"Proxmox AIops\"\nsummary: \"Governed Proxmox VE VM/container ops — 43 MCP tools with audit, budget, undo & risk-tier guards.\"\nlicense: MIT\nhomepage: https://github.com/AIops-tools/Proxmox-AIops\ntags: [aiops, mcp, governance, proxmox]\ndescription: >\n Use this skill whenever the user needs to manage VMs and containers on Proxmox VE — list/inspect/configure VMs, power and lifecycle (start/stop/shutdown/reboot/reconfigure/clone/delete/migrate), snapshots (create/delete/list/rollback), disk grow/move, vzdump backups (create/list/restore), LXC containers (list/start/stop), cluster/node status, cluster resource inventory, async task polling + logs, free-VMID lookup, HA status, resource pools, firewall inspection, guest-agent ping, and storage listing.\n Also use it to diagnose cluster health — rank nodes by CPU/memory/disk pressure and scan guests for saturation (read-only RCA).\n Always use this skill for \"list proxmox vms\", \"start proxmox vm\", \"stop proxmox vm\", \"proxmox snapshot\", \"proxmox backup\", \"restore proxmox vm\", \"resize proxmox disk\", \"proxmox vm status\", \"migrate proxmox vm\", \"proxmox container\", \"proxmox ha\", \"proxmox pool\", \"proxmox firewall\", \"list proxmox storage\", \"proxmox node pressure\", or \"why is proxmox slow\" when the context is explicitly Proxmox / Proxmox VE / PVE.\n Do NOT use for non-Proxmox hypervisors, Kubernetes, or cloud providers.\n Broad coverage of common Proxmox operations, with a built-in governance harness (audit, token budget, undo, risk-tier labels).\ninstaller:\n kind: uv\n package: proxmox-aiops\nargument-hint: \"[vmid or describe your Proxmox task]\"\nallowed-tools:\n - Bash\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"proxmox-aiops\",\"uvx\"]},\"optional\":{\"env\":[\"PROXMOX_AIOPS_CONFIG\",\"PROXMOX_TARGET_SECRET\"]},\"homepage\":\"https://github.com/AIops-tools/Proxmox-AIops\",\"emoji\":\"🧱\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n Standalone, self-governed Proxmox VE operations. The governance harness (audit, token/runaway budget, undo, risk-tier labels) is bundled in the package — no external skill-family dependency.\n All write operations are audited to a local SQLite DB under ~/.proxmox-aiops/ (relocatable via PROXMOX_AIOPS_HOME).\n Credentials: Each Proxmox target requires a per-target secret env var in ~/.proxmox-aiops/.env following the pattern PROXMOX__SECRET (API token UUID for token auth, or login password). Secrets are never logged or echoed; .env should be chmod 600.\n Destructive operations (vm stop/delete/snapshot-delete/snapshot-rollback, ct stop) require double confirmation at the CLI layer and support --dry-run. All write tools pass through the @governed_tool decorator (budget guard + audit + risk-tier tagging). Reversible writes record an inverse undo descriptor to the undo store.\n Webhooks: none — no outbound network calls beyond the configured Proxmox API endpoint.\n SSL: verify_ssl defaults to true; disable only for self-signed lab certificates.\n Transitive dependencies: proxmoxer (Proxmox API client) and the MCP SDK. No post-install scripts or background services.\n---\n\n# Proxmox AIops\n\n> **Disclaimer**: This is a community-maintained open-source project and is **not affiliated with, endorsed by, or sponsored by Proxmox Server Solutions GmbH.** \"Proxmox\" is a trademark of its owner. Source code is publicly auditable at [github.com/AIops-tools/Proxmox-AIops](https://github.com/AIops-tools/Proxmox-AIops) under the MIT license.\n\nGoverned VM and container lifecycle operations for Proxmox VE — **43 MCP tools**, every one wrapped with the bundled `@governed_tool` harness: a local unified audit log under `~/.proxmox-aiops/`, token/runaway budget guard, undo-token recording, and descriptive risk-tier labels.\n\n> **Standalone**: the governance harness is bundled in the package (`proxmox_aiops.governance`) — proxmox-aiops has no external skill-family dependency. Coverage focuses on common Proxmox operations and is not yet exhaustive.\n\n## What This Skill Does\n\n| Category | Tools | Count | Read or Write |\n|----------|-------|:-----:|:-------------:|\n| **VM Lifecycle** | list, get, config, start, stop, shutdown, reboot, reconfigure, clone, delete, migrate | 11 | 3 read / 8 write |\n| **Snapshots** | create, delete, list, rollback | 4 | 1 read / 3 write |\n| **Disk** | resize (grow-only), move | 2 | 0 read / 2 write |\n| **Backups (vzdump)** | create, list, restore | 3 | 1 read / 2 write |\n| **LXC Containers** | list, start, stop | 3 | 1 read / 2 write |\n| **Cluster / Tasks** | node list, cluster status, task poll, cluster resources, node status, task log, next vmid | 7 | 7 read |\n| **HA** | status, resource list | 2 | 2 read |\n| **Pools** | list, members | 2 | 2 read |\n| **Firewall** | vm rules, cluster status | 2 | 2 read |\n| **Guest Agent** | ping | 1 | 1 read |\n| **Storage** | list pools, list content | 2 | 2 read |\n| **Diagnostics / RCA** | node-pressure, guest-health | 2 | 2 read |\n\n## Quick Install\n\n```bash\nuv tool install proxmox-aiops\nproxmox-aiops doctor\n```\n\n## When to Use This Skill\n\n- List/inspect Proxmox QEMU VMs and their config\n- Power ops: start, hard-stop, graceful shutdown, reboot\n- Reconfigure (cores/memory), clone, delete, or migrate a VM between nodes\n- Grow a VM disk (grow-only — shrink is refused) or move it to another storage\n- Create, list, and restore vzdump backups\n- Create / delete / list / roll back VM snapshots\n- Manage LXC containers (list, start, stop)\n- Inspect cluster nodes, quorum, the `/cluster/resources` inventory, node load/mem, and poll async tasks + fetch their logs by UPID; get a free VMID\n- Check HA status / HA-managed resources (handles \"HA not configured\" gracefully)\n- List resource pools and their members\n- Inspect VM firewall rules and the cluster firewall enable state (read-only)\n- Ping a VM's QEMU guest agent\n- List storage pools and their content (ISOs, disk images, backups)\n- **Diagnose** cluster health: rank nodes by CPU/memory/root-fs pressure, and scan VMs/containers for stopped guests, memory saturation, and disks near full — each finding cites the measured number and a concrete action (read-only RCA)\n\n**Do NOT use when** the target is not Proxmox VE (other hypervisors, Kubernetes, or cloud providers are out of scope for this skill).\n\n## Common Workflows\n\n### Triage a \"cluster feels slow\" complaint (read-only)\n\n1. `proxmox-aiops diagnose node-pressure` → worst-first table of nodes over the CPU/mem/disk thresholds, each row citing the measured % and the fix\n2. `proxmox-aiops diagnose guest-health` → guests near their memory ceiling or with disks near full, plus the list of stopped guests\n3. Act on the top finding — e.g. `proxmox-aiops vm migrate --to-node ` to shed load off a hot node, or `vm reconfigure --memory ...` for a RAM-starved guest. All of these route through the governed path (audited, undo recorded).\n\n### Snapshot, then reconfigure a VM\n\n1. `proxmox-aiops vm list` → find the vmid and confirm it is the right VM/node\n2. `proxmox-aiops vm snapshot-create --name pre-change` → baseline before any risky change\n3. `proxmox-aiops vm reconfigure --cores 8 --memory 16384` → the harness captures the prior cores/memory as the undo descriptor\n4. **Failure branch**: if the change goes wrong, the write recorded an `_undo_id` — reverse it with `proxmox-aiops undo apply `, or roll back with `proxmox-aiops vm snapshot-rollback --name pre-change`.\n\n### Free a node that is out of memory\n\n1. `proxmox-aiops diagnose node-pressure` → identify the node flagged `high memory`\n2. `proxmox-aiops cluster resources --type vm` → find a movable guest on that node\n3. `proxmox-aiops vm migrate --to-node --dry-run` → preview, then run without `--dry-run` (migrate is `high` risk; the inverse migrate-back is recorded)\n4. Re-run `diagnose node-pressure` to confirm the pressure cleared.\n\n### Stop a VM safely\n\n1. `proxmox-aiops vm get ` → confirm current status is `running`\n2. `proxmox-aiops vm stop --dry-run` → preview the exact API call\n3. `proxmox-aiops vm stop ` → double confirmation required; `vm_stop` records an inverse `vm_start` undo descriptor\n4. **Failure branch**: if `doctor` shows the node unreachable or the secret env var is missing, fix credentials with `proxmox-aiops secret set ` before retrying — the stop is never issued against an unauthenticated session.\n\n## Usage Mode\n\n| Scenario | Recommended | Why |\n|----------|:-----------:|-----|\n| Local/small models | **CLI** | fewer tokens than MCP |\n| Cloud models (Claude, GPT) | Either | MCP gives structured JSON I/O |\n| Automated pipelines | **MCP** | type-safe parameters, audited |\n\n## MCP Tools (43 — 25 read, 18 write)\n\n| Category | Tools | R/W |\n|----------|-------|:---:|\n| VM Lifecycle | `vm_list`, `vm_get`, `vm_config` | Read |\n| | `vm_start`, `vm_stop`, `vm_shutdown`, `vm_reboot`, `vm_reconfigure`, `vm_clone`, `vm_delete`, `vm_migrate` | Write |\n| Snapshots | `vm_list_snapshots` | Read |\n| | `vm_snapshot_create`, `vm_snapshot_delete`, `vm_snapshot_rollback` | Write |\n| Disk | `vm_resize_disk` (grow-only), `vm_move_disk` | Write |\n| Backups | `backup_list` | Read |\n| | `vm_backup`, `backup_restore` (high) | Write |\n| LXC Containers | `ct_list` | Read |\n| | `ct_start`, `ct_stop` | Write |\n| Cluster / Tasks | `node_list`, `cluster_status`, `task_status`, `cluster_resources`, `node_status`, `task_log`, `next_vmid` | Read |\n| HA | `ha_status`, `ha_resource_list` | Read |\n| Pools | `pool_list`, `pool_members` | Read |\n| Firewall | `vm_firewall_rules_list`, `cluster_firewall_status` | Read |\n| Guest Agent | `vm_agent_ping` | Read |\n| Storage | `storage_list`, `storage_content` | Read |\n| Diagnostics / RCA | `node_pressure_rca`, `guest_health_rca` | Read |\n| Undo | `undo_list` | Read |\n| | `undo_apply` | Write |\n\n**Harness features that light up**: write tools with a clean inverse (`vm_start`/`vm_stop`/`vm_shutdown`/`vm_reconfigure`/`vm_clone`/`vm_migrate`/`vm_snapshot_create`/`vm_move_disk`/`ct_start`/`ct_stop`) pass an `undo=` lambda so the harness records an inverse descriptor (with `_undo_id`) to the undo store — `vm_reconfigure` captures the prior cores/memory, `vm_clone`'s inverse is `vm_delete(newid)`, `vm_migrate`'s is migrate-back, `vm_move_disk`'s is move-back to the captured source storage. `backup_restore` records a `vm_delete` inverse **only** when it restored into a free VMID (a forced overwrite is destructive and declares none). Irreversible writes (`vm_delete`, `vm_snapshot_rollback`, `backup_restore` with `force`) declare no undo and are tagged `risk_level=high`; `vm_resize_disk` is grow-only and refuses shrink before any API call. All 43 tools are audit-logged under `~/.proxmox-aiops/` and pass through the budget/runaway guard + risk-tier tagging. Proxmox writes are async (return a task UPID) — poll with `task_status` (and read lines with `task_log`) instead of re-issuing (the runaway breaker backs this up).\n\n## CLI Quick Reference\n\n```bash\nproxmox-aiops vm list [--target ] [--node ]\nproxmox-aiops vm get [--node ]\nproxmox-aiops vm start [--node ]\nproxmox-aiops vm stop [--dry-run] # double confirm\nproxmox-aiops vm resize-disk --disk scsi0 --size +10G # grow-only\nproxmox-aiops vm move-disk --disk scsi0 --storage ceph [--delete]\nproxmox-aiops vm agent-ping \nproxmox-aiops vm snapshot-create --name \nproxmox-aiops vm snapshot-delete --name [--dry-run] # double confirm\nproxmox-aiops vm snapshot-list \nproxmox-aiops backup create --storage [--mode snapshot]\nproxmox-aiops backup list [--vmid ]\nproxmox-aiops backup restore --archive --storage [--force] [--dry-run] # double confirm\nproxmox-aiops cluster resources [--type vm|node|storage]\nproxmox-aiops cluster node-status \nproxmox-aiops cluster task-log \nproxmox-aiops cluster next-vmid\nproxmox-aiops ha status\nproxmox-aiops pool list\nproxmox-aiops firewall vm-rules \nproxmox-aiops storage list [--node ]\nproxmox-aiops diagnose node-pressure # rank nodes by CPU/mem/disk pressure (read-only RCA)\nproxmox-aiops diagnose guest-health # stopped guests, mem saturation, disks near full\nproxmox-aiops undo apply # reverse a recorded governed write\nproxmox-aiops init # onboarding wizard (encrypted creds)\nproxmox-aiops secret set # manage encrypted secret store\nproxmox-aiops doctor\nproxmox-aiops mcp # start MCP server (stdio)\n```\n\n> Credentials are managed by the `proxmox-aiops init` onboarding wizard and the\n> `proxmox-aiops secret` commands, which back an encrypted secret store (no\n> plaintext passwords in `config.yaml`).\n\n## Troubleshooting\n\n### \"Config file not found\"\nCreate `~/.proxmox-aiops/config.yaml` with a `targets:` list (see README), and put secrets in `~/.proxmox-aiops/.env` (chmod 600).\n\n### \"Secret not found. Set environment variable: PROXMOX__SECRET\"\nEach target needs a per-target secret env var. For target `pve-lab`, set `PROXMOX_PVE_LAB_SECRET=` in `.env`.\n\n### \"Token auth requires user in the form 'user@realm!tokenid'\"\nFor API-token auth (recommended, least privilege), `user` must include the token id after `!`, e.g. `root@pam!claude`. For password auth set `auth_kind: password` and use `user@realm`.\n\n### \"No node specified and no default node configured\"\nEither pass `--node ` / `node=`, or set `node:` on the target in `config.yaml`. VM operations can auto-locate a vmid across nodes, but storage listing needs an explicit node.\n\n## Audit & Safety\n\nThe skill delivers reads and writes and records them; it does **not** decide whether a write is\npermitted. That is your agent's judgement, or the permission of the account you connect it with —\nuse a Proxmox VE user or API token granted only read privileges (no VM.*/Datastore.* write roles),\nand writes then fail at the server. There is no read-only switch, policy file, or approval gate.\n\n- **Audit is the guarantee, and it is not bypassable.** Every operation — MCP and CLI alike — is logged to `~/.proxmox-aiops/audit.db` (relocatable via `PROXMOX_AIOPS_HOME`): params, result, status, duration, and the risk tier. The CLI writes the same row the MCP path does.\n- `PROXMOX_AUDIT_APPROVED_BY` / `PROXMOX_AUDIT_RATIONALE` are optional annotations recorded on the audit row (who/why); they are never required and never block.\n- **Runaway guard** — a safety backstop, not authorization: the same call looped in a tight window trips a circuit breaker. Disable with `PROXMOX_RUNAWAY_MAX=0`; optional hard ceilings via `PROXMOX_MAX_TOOL_CALLS` / `PROXMOX_MAX_TOOL_SECONDS`.\n- Undo store records inverse descriptors for reversible writes (start/stop/shutdown/reconfigure/clone/migrate/snapshot-create, container start/stop).\n- Writes support `--dry-run` / `dry_run=True` and double confirmation at the CLI.\n\nThe harness is bundled in the package — no external dependency, no manual setup.\n\n## Contributing & feature requests\n\nCoverage is intentionally focused. **Missing a device, action, or feature you need?** Open an issue or pull request at [github.com/AIops-tools/Proxmox-AIops](https://github.com/AIops-tools/Proxmox-AIops/issues) — feature requests, contributions, and comments are all welcome.\n\n## License\n\nMIT — [github.com/AIops-tools/Proxmox-AIops](https://github.com/AIops-tools/Proxmox-AIops)\n\nFile v0.13.0:_meta.json\n\n{\n \"ownerId\": \"kn7b067awq2s97bn3d7p5qfhw5827pxc\",\n \"slug\": \"proxmox-aiops\",\n \"version\": \"0.13.0\",\n \"publishedAt\": 1789175496705\n}\n\nFile v0.13.0:references/agent-guardrails.md\n\n# Agent guardrails — running proxmox-aiops with a smaller / local model\n\nIf you drive these tools with a local model (Llama, Qwen, Mistral … via Goose,\nOllama, LM Studio, or any OpenAI-compatible runtime), you will get noticeably\nbetter results with a short system prompt. This page gives you one, and — more\nimportantly — tells you which guardrails you **no longer need to write**, because\nthe tool now enforces them itself.\n\nThe distinction matters. A guardrail in a prompt is a request. A guardrail in the\nharness is a guarantee. Anything below that we could move into the harness, we did.\n\n## What the tool now enforces — do not waste prompt budget on these\n\n| You might be tempted to prompt | Why you don't need to |\n|---|---|\n| \"Don't invent a value when a field is missing\" | A field the API did not return comes back as `null`, never as `\"\"`. Absent and empty are distinguishable in the payload. |\n| \"Tell me if the output was cut off\" | Anything with a `limit` returns `{\"lines\": [...], \"returned\": N, \"limit\": L, \"truncated\": true/false}`. Truncation is measured (one extra row is fetched), not guessed. |\n| \"Preserve the ordering / tell me what's most urgent\" | `diagnose` findings carry an explicit 1-based `rank`, worst-first. Priority is in the payload, not implied by list position. |\n| \"Confirm before anything destructive\" | Destructive operations require a `--dry-run`-able preview + double confirmation at the CLI. |\n| \"Log what you did\" | Every call is audited to `~/.proxmox-aiops/audit.db` regardless of what the model says it did. |\n\n## What still needs a prompt\n\nThese are model-behaviour problems the harness cannot fix from the outside.\nCopy this into your agent's system prompt:\n\n```text\nYou operate a Proxmox VE environment through the proxmox-aiops MCP tools.\n\nTOOL USE\n- Before answering any question about the current Proxmox environment, you MUST\n call a tool. Never answer from memory or assumption.\n- Actually invoke the tool. Do not describe the call you would make, and do not\n emit an example JSON response in place of calling it.\n- If a tool call fails, report the real error verbatim. Never fill the gap with\n a plausible-sounding answer.\n\nREADING RESULTS\n- Read the whole result before concluding. If a result contains a \"truncated\"\n field that is true, say so and re-run with a higher limit instead of treating\n the partial result as complete.\n- A null field means the API did not return that value. Report it as \"not\n available\" — never infer it.\n- Report values exactly as returned. Do not normalise, translate, or prettify\n status strings, severities, or IDs.\n- When a diagnose result has findings, work in \"rank\" order and cite the\n measured number in each finding's \"detail\".\n\nSCOPE\n- Separate observation from interpretation. State what the tools returned, then\n any interpretation, clearly marked as such.\n- Do not assert a capacity, performance, or availability problem unless a tool\n result supports it.\n- Do not add generic advice that does not follow from the tool output.\n- Do not confuse a VMID with a node name, or a task UPID with either.\n```\n\n## Recommended setup for a local model\n\nAuthorization is not this tool's job — decide it via the account you connect\nwith or the agent's prompt, not a switch in the tool. To work read-only, connect\nwith a Proxmox VE user or API token granted only read privileges (no\n`VM.*`/`Datastore.*` write roles); a write then fails at the server, the place\nthat actually owns the permission.\n\n```bash\nproxmox-aiops doctor # verify connectivity with your least-privilege token\n```\n\nOptionally, annotate who is running changes and why — these land on the audit\nrow, and are never required and never blocking:\n\n```bash\nexport PROXMOX_AUDIT_APPROVED_BY=\"your.name@example.com\"\nexport PROXMOX_AUDIT_RATIONALE=\"scheduled maintenance window\"\n```\n\n## If your model still struggles\n\nSome behaviours are model-capacity limits rather than prompt problems:\n\n- **Multi-tool workflows time out or drift.** Prefer the `diagnose` tools — they\n do the multi-step correlation inside one call, so the model does not have to\n chain reads and keep IDs straight.\n- **The model ignores later tool results in a long context.** Ask narrower\n questions and use `--limit` deliberately rather than pulling whole inventories.\n- **The model describes calls instead of making them.** This is usually a\n runtime/tool-calling-format mismatch, not a prompt problem — check that your\n client advertises the tools in the format your model was trained on.\n\nFeedback on running this with a specific local model is genuinely useful —\nopen an issue at\n[github.com/AIops-tools/Proxmox-AIops](https://github.com/AIops-tools/Proxmox-AIops/issues)\nwith the model, runtime, and what went wrong.\n\nFile v0.13.0:references/capabilities.md\n\n# proxmox-aiops capabilities\n\n43 MCP tools (25 read / 18 write). Every tool is wrapped with the bundled\n`@governed_tool` harness (audit + budget + risk-tier + undo). Typical response\nsizes are small high-signal summaries, not full API blobs.\n\n## VM lifecycle (11)\n\n| Tool | R/W | Inverse (undo) | Typical response |\n|------|:---:|----------------|------------------|\n| `vm_list` | R | — | ~50–500 tok (one row per VM) |\n| `vm_get` | R | — | ~120 tok |\n| `vm_config` | R | — | ~120 tok |\n| `vm_start` | W | `vm_stop` | task UPID |\n| `vm_stop` | W | `vm_start` | task UPID |\n| `vm_shutdown` | W | `vm_start` | task UPID |\n| `vm_reboot` | W | — (no inverse) | task UPID |\n| `vm_reconfigure` | W | `vm_reconfigure` (prior cores/memory) | applied + previous |\n| `vm_clone` | W | `vm_delete(newid)` | task UPID |\n| `vm_delete` | W | — (irreversible, risk=high) | task UPID |\n| `vm_migrate` | W | `vm_migrate` (back to source node) | task UPID |\n\n## Snapshots (4)\n\n| Tool | R/W | Inverse | Notes |\n|------|:---:|---------|-------|\n| `vm_list_snapshots` | R | — | name + description |\n| `vm_snapshot_create` | W | `vm_snapshot_delete` | |\n| `vm_snapshot_delete` | W | — | |\n| `vm_snapshot_rollback` | W | — (irreversible, risk=high) | discards newer state |\n\n## Disk (2)\n\n| Tool | R/W | Inverse | Notes |\n|------|:---:|---------|-------|\n| `vm_resize_disk` | W | — (grow-only; shrink refused) | `+G` or larger absolute |\n| `vm_move_disk` | W | `vm_move_disk` (back to source storage) | task UPID |\n\n## Backups — vzdump (3)\n\n| Tool | R/W | Inverse | Notes |\n|------|:---:|---------|-------|\n| `backup_list` | R | — | archives on a storage, filterable by vmid |\n| `vm_backup` | W | — | task UPID; mode snapshot/suspend/stop |\n| `backup_restore` | W | `vm_delete` only when restored into a free vmid; none on forced overwrite (risk=high) | task UPID |\n\n## LXC containers (3)\n\n| Tool | R/W | Inverse |\n|------|:---:|---------|\n| `ct_list` | R | — |\n| `ct_start` | W | `ct_stop` |\n| `ct_stop` | W | `ct_start` |\n\n## Cluster / tasks (7)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `node_list` | R | status, cpu load, memory |\n| `cluster_status` | R | membership + quorum |\n| `task_status` | R | poll an async UPID (clone/migrate/backup) |\n| `cluster_resources` | R | `/cluster/resources` inventory (vm/node/storage filter) |\n| `node_status` | R | one node: cpu, load average, memory, uptime |\n| `task_log` | R | log lines of an async task by UPID |\n| `next_vmid` | R | a free VMID for a new guest |\n\n## HA (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `ha_status` | R | `{configured, entries}`; `configured` is true only when HA manages a resource — every cluster reports quorum/master/lrm rows regardless |\n| `ha_resource_list` | R | HA-managed resources; empty when HA absent |\n\n## Pools (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `pool_list` | R | poolid + comment |\n| `pool_members` | R | members (VMs/CTs/storage) of a pool |\n\n## Firewall — read-only (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `vm_firewall_rules_list` | R | per-VM firewall rules |\n| `cluster_firewall_status` | R | cluster firewall enable + default policies |\n\n## Guest agent (1)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `vm_agent_ping` | R | `responsive` bool; absence reported, not crashed |\n\n## Storage (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `storage_list` | R | pools: type, total/used/avail |\n| `storage_content` | R | volumes: ISOs, disk images, backups, templates |\n\n## Diagnostics / RCA (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `node_pressure_rca` | R | node CPU/memory/IO pressure: ranked causes + evidence |\n| `guest_health_rca` | R | one guest: ranked causes (resource, agent, disk, task history) |\n\n## Undo (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `undo_list` | R | recorded, not-yet-applied undo tokens (most recent first): original tool, inverse tool, `undoId` |\n| `undo_apply` | W | executes a recorded inverse by `undoId` — itself governed (the inverse re-gates on its own risk tier), single-use, `dry_run=True` previews |\n\n## Not yet covered\n\nVM create-from-scratch / template instantiation, guest agent **exec**\n(intentionally omitted as too risky), container create/clone/destroy, firewall\n**rule mutation** (read-only for now), and ACL management. These are the natural\nnext additions — each gets a matching `@governed_tool` wrapper and an `undo=`\ndeclaration where a clean inverse exists. Missing something? Open an issue/PR.\n\nFile v0.13.0:references/cli-reference.md\n\n# proxmox-aiops CLI reference\n\nAll commands take `--target/-t ` (config target; omit for default) and,\nwhere relevant, `--node/-n `. Destructive commands support `--dry-run`.\n\n## VM lifecycle\n\n```bash\nproxmox-aiops vm list [-t ] [-n ]\nproxmox-aiops vm get \nproxmox-aiops vm config \nproxmox-aiops vm start \nproxmox-aiops vm stop [--dry-run] # hard power-off (double confirm)\nproxmox-aiops vm shutdown [--dry-run] # graceful ACPI\nproxmox-aiops vm reboot \nproxmox-aiops vm reconfigure [--cores N] [--memory MiB] [--dry-run]\nproxmox-aiops vm clone --newid [--name ]\nproxmox-aiops vm delete [--dry-run] # irreversible (double confirm)\nproxmox-aiops vm migrate --to-node [--offline] [--dry-run]\n```\n\n## Snapshots\n\n```bash\nproxmox-aiops vm snapshot-create --name \nproxmox-aiops vm snapshot-list \nproxmox-aiops vm snapshot-delete --name [--dry-run] # double confirm\nproxmox-aiops vm snapshot-rollback --name [--dry-run] # irreversible\n```\n\n## LXC containers\n\n```bash\nproxmox-aiops ct list [-n ]\nproxmox-aiops ct start \nproxmox-aiops ct stop [--dry-run] # double confirm\n```\n\n## Cluster / async tasks\n\n```bash\nproxmox-aiops cluster nodes\nproxmox-aiops cluster status # membership + quorum\nproxmox-aiops cluster task-status # poll a clone/migrate/backup task\n```\n\n## Storage\n\n```bash\nproxmox-aiops storage list [-n ]\nproxmox-aiops storage content [--content iso|images|backup|vztmpl]\n```\n\n## Diagnostics & MCP\n\n```bash\nproxmox-aiops doctor # verify connectivity + credentials\nproxmox-aiops mcp # start the MCP server (stdio)\n```\n\n> Proxmox writes are asynchronous and return a task UPID. Poll completion with\n> `cluster task-status ` rather than re-issuing the operation.\n\nFile v0.13.0:references/setup-guide.md\n\n# proxmox-aiops setup guide\n\n## Install\n\n```bash\nuv tool install proxmox-aiops\n# or: pipx install proxmox-aiops\n```\n\n## Configure\n\n```bash\nmkdir -p ~/.proxmox-aiops && chmod 700 ~/.proxmox-aiops\n```\n\n`~/.proxmox-aiops/config.yaml` (no secrets here):\n\n```yaml\ntargets:\n - name: pve-lab\n host: 10.0.0.10\n user: \"root@pam!claude\" # API token form: user@realm!tokenid\n node: pve1 # default node for this target\n auth_kind: token # 'token' or 'password'\n verify_ssl: false # self-signed lab certs only; true in prod\n```\n\n`~/.proxmox-aiops/.env` (chmod 600 — secrets only):\n\n```bash\nPROXMOX_PVE_LAB_SECRET=\n```\n\nThe secret variable is `PROXMOX__SECRET` (hyphens → underscores).\n\n```bash\nchmod 600 ~/.proxmox-aiops/.env\nproxmox-aiops doctor # verifies connectivity + credentials\n```\n\n## Use as an MCP server\n\n```jsonc\n{\n \"command\": \"proxmox-aiops\",\n \"args\": [\"mcp\"],\n \"env\": { \"PROXMOX_AIOPS_CONFIG\": \"~/.proxmox-aiops/config.yaml\" }\n}\n```\n\nUsing the `proxmox-aiops mcp` subcommand (rather than `uvx --from`) means the\nMCP client launches the already-installed entry point and does not re-resolve\nthe package over the network at startup.\n\n## Security\n\n> **Disclaimer**: Community-maintained project, **not affiliated with Proxmox\n> Server Solutions GmbH**. MIT licensed. See `SECURITY.md`.\n\n- **Credentials**: `.env` only, chmod 600, per-target `PROXMOX__SECRET`.\n- **Audit**: every operation logged to a local SQLite DB under\n `~/.proxmox-aiops/` (relocate with `PROXMOX_AIOPS_HOME`).\n- **Budget guard**: cap calls/wall-time with `PROXMOX_MAX_TOOL_CALLS` /\n `PROXMOX_MAX_TOOL_SECONDS`; a runaway poll/retry loop trips automatically.\n- **Risk tiers**: each tool's `risk_level` is recorded on the audit row as a\n descriptive tier (none/confirm/review) — a label, not a gate.\n `PROXMOX_AUDIT_APPROVED_BY` / `PROXMOX_AUDIT_RATIONALE` are optional audit\n annotations, never required.\n- **Destructive ops**: double confirmation + `--dry-run` at the CLI.\n- **TLS**: `verify_ssl` defaults true; disable only for self-signed labs.\n- **No webhooks / telemetry / background services.**\n\n## Least privilege\n\nCreate a dedicated Proxmox API token with only the roles your workflows need\n(e.g. `PVEVMAdmin` on the relevant pool) rather than `root@pam`.\n\nFile v0.13.0:skill-card.md\n\n## Description:\n\nProxmox AIops helps agents operate and diagnose Proxmox VE VMs and containers through governed CLI and MCP workflows with audit logs, undo support, token budgets, and risk-tier labels.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[zw008](https://clawhub.ai/user/zw008)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and infrastructure operators use this skill to inspect, diagnose, and perform governed lifecycle operations on Proxmox VE VMs and containers from an agent session.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can perform destructive Proxmox infrastructure actions.\n\nMitigation: Use a dedicated least-privilege Proxmox API token, scope permissions to the required pools or guests, and preview high-impact changes with dry-run workflows when available.\n\nRisk: Credentials, audit history, and undo metadata may be stored under ~/.proxmox-aiops/.\n\nMitigation: Treat the directory as sensitive, restrict local file permissions, avoid password authentication where possible, and keep secrets out of shared configuration.\n\nRisk: Weak TLS or unpinned installs can increase supply-chain and connection risk.\n\nMitigation: Review the package source or pin a trusted release before installation, keep TLS verification enabled, or trust a specific internal CA for self-signed environments.\n\n## Reference(s):\n\n- [Proxmox AIops homepage](https://github.com/AIops-tools/Proxmox-AIops)\n- [Capabilities](references/capabilities.md)\n- [CLI reference](references/cli-reference.md)\n- [Setup guide](references/setup-guide.md)\n- [Agent guardrails](references/agent-guardrails.md)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown with inline shell commands, configuration snippets, and operational guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May reference CLI or MCP operations, dry-run flows, task UPIDs, audit records, and undo identifiers when relevant.]\n\n## Skill Version(s):\n\n0.13.0 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.12.0: 7 files, 14801 bytes\n\nFiles: references/agent-guardrails.md (4785b), references/capabilities.md (4523b), references/cli-reference.md (2012b), references/setup-guide.md (2363b), skill-card.md (2740b), SKILL.md (15763b), _meta.json (133b)\n\nFile v0.12.0:SKILL.md\n\n---\nname: proxmox-aiops\nslug: proxmox-aiops\ndisplayName: \"Proxmox AIops\"\nsummary: \"Governed Proxmox VE VM/container ops — 43 MCP tools with audit, budget, undo & risk-tier guards.\"\nlicense: MIT\nhomepage: https://github.com/AIops-tools/Proxmox-AIops\ntags: [aiops, mcp, governance, proxmox]\ndescription: >\n Use this skill whenever the user needs to manage VMs and containers on Proxmox VE — list/inspect/configure VMs, power and lifecycle (start/stop/shutdown/reboot/reconfigure/clone/delete/migrate), snapshots (create/delete/list/rollback), disk grow/move, vzdump backups (create/list/restore), LXC containers (list/start/stop), cluster/node status, cluster resource inventory, async task polling + logs, free-VMID lookup, HA status, resource pools, firewall inspection, guest-agent ping, and storage listing.\n Also use it to diagnose cluster health — rank nodes by CPU/memory/disk pressure and scan guests for saturation (read-only RCA).\n Always use this skill for \"list proxmox vms\", \"start proxmox vm\", \"stop proxmox vm\", \"proxmox snapshot\", \"proxmox backup\", \"restore proxmox vm\", \"resize proxmox disk\", \"proxmox vm status\", \"migrate proxmox vm\", \"proxmox container\", \"proxmox ha\", \"proxmox pool\", \"proxmox firewall\", \"list proxmox storage\", \"proxmox node pressure\", or \"why is proxmox slow\" when the context is explicitly Proxmox / Proxmox VE / PVE.\n Do NOT use for non-Proxmox hypervisors, Kubernetes, or cloud providers.\n Broad coverage of common Proxmox operations, with a built-in governance harness (audit, token budget, undo, risk-tier labels).\ninstaller:\n kind: uv\n package: proxmox-aiops\nargument-hint: \"[vmid or describe your Proxmox task]\"\nallowed-tools:\n - Bash\nmetadata: {\"openclaw\":{\"requires\":{\"env\":[\"PROXMOX_AIOPS_CONFIG\"],\"bins\":[\"proxmox-aiops\"],\"config\":[\"~/.proxmox-aiops/config.yaml\",\"~/.proxmox-aiops/.env\"]},\"optional\":{\"env\":[\"PROXMOX_TARGET_SECRET\"]},\"primaryEnv\":\"PROXMOX_AIOPS_CONFIG\",\"homepage\":\"https://github.com/AIops-tools/Proxmox-AIops\",\"emoji\":\"🧱\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n Standalone, self-governed Proxmox VE operations. The governance harness (audit, token/runaway budget, undo, risk-tier labels) is bundled in the package — no external skill-family dependency.\n All write operations are audited to a local SQLite DB under ~/.proxmox-aiops/ (relocatable via PROXMOX_AIOPS_HOME).\n Credentials: Each Proxmox target requires a per-target secret env var in ~/.proxmox-aiops/.env following the pattern PROXMOX__SECRET (API token UUID for token auth, or login password). Secrets are never logged or echoed; .env should be chmod 600.\n Destructive operations (vm stop/delete/snapshot-delete/snapshot-rollback, ct stop) require double confirmation at the CLI layer and support --dry-run. All write tools pass through the @governed_tool decorator (budget guard + audit + risk-tier tagging). Reversible writes record an inverse undo descriptor to the undo store.\n Webhooks: none — no outbound network calls beyond the configured Proxmox API endpoint.\n SSL: verify_ssl defaults to true; disable only for self-signed lab certificates.\n Transitive dependencies: proxmoxer (Proxmox API client) and the MCP SDK. No post-install scripts or background services.\n---\n\n# Proxmox AIops\n\n> **Disclaimer**: This is a community-maintained open-source project and is **not affiliated with, endorsed by, or sponsored by Proxmox Server Solutions GmbH.** \"Proxmox\" is a trademark of its owner. Source code is publicly auditable at [github.com/AIops-tools/Proxmox-AIops](https://github.com/AIops-tools/Proxmox-AIops) under the MIT license.\n\nGoverned VM and container lifecycle operations for Proxmox VE — **43 MCP tools**, every one wrapped with the bundled `@governed_tool` harness: a local unified audit log under `~/.proxmox-aiops/`, token/runaway budget guard, undo-token recording, and descriptive risk-tier labels.\n\n> **Standalone**: the governance harness is bundled in the package (`proxmox_aiops.governance`) — proxmox-aiops has no external skill-family dependency. Coverage focuses on common Proxmox operations and is not yet exhaustive.\n\n## What This Skill Does\n\n| Category | Tools | Count | Read or Write |\n|----------|-------|:-----:|:-------------:|\n| **VM Lifecycle** | list, get, config, start, stop, shutdown, reboot, reconfigure, clone, delete, migrate | 11 | 3 read / 8 write |\n| **Snapshots** | create, delete, list, rollback | 4 | 1 read / 3 write |\n| **Disk** | resize (grow-only), move | 2 | 0 read / 2 write |\n| **Backups (vzdump)** | create, list, restore | 3 | 1 read / 2 write |\n| **LXC Containers** | list, start, stop | 3 | 1 read / 2 write |\n| **Cluster / Tasks** | node list, cluster status, task poll, cluster resources, node status, task log, next vmid | 7 | 7 read |\n| **HA** | status, resource list | 2 | 2 read |\n| **Pools** | list, members | 2 | 2 read |\n| **Firewall** | vm rules, cluster status | 2 | 2 read |\n| **Guest Agent** | ping | 1 | 1 read |\n| **Storage** | list pools, list content | 2 | 2 read |\n| **Diagnostics / RCA** | node-pressure, guest-health | 2 | 2 read |\n\n## Quick Install\n\n```bash\nuv tool install proxmox-aiops\nproxmox-aiops doctor\n```\n\n## When to Use This Skill\n\n- List/inspect Proxmox QEMU VMs and their config\n- Power ops: start, hard-stop, graceful shutdown, reboot\n- Reconfigure (cores/memory), clone, delete, or migrate a VM between nodes\n- Grow a VM disk (grow-only — shrink is refused) or move it to another storage\n- Create, list, and restore vzdump backups\n- Create / delete / list / roll back VM snapshots\n- Manage LXC containers (list, start, stop)\n- Inspect cluster nodes, quorum, the `/cluster/resources` inventory, node load/mem, and poll async tasks + fetch their logs by UPID; get a free VMID\n- Check HA status / HA-managed resources (handles \"HA not configured\" gracefully)\n- List resource pools and their members\n- Inspect VM firewall rules and the cluster firewall enable state (read-only)\n- Ping a VM's QEMU guest agent\n- List storage pools and their content (ISOs, disk images, backups)\n- **Diagnose** cluster health: rank nodes by CPU/memory/root-fs pressure, and scan VMs/containers for stopped guests, memory saturation, and disks near full — each finding cites the measured number and a concrete action (read-only RCA)\n\n**Do NOT use when** the target is not Proxmox VE (other hypervisors, Kubernetes, or cloud providers are out of scope for this skill).\n\n## Common Workflows\n\n### Triage a \"cluster feels slow\" complaint (read-only)\n\n1. `proxmox-aiops diagnose node-pressure` → worst-first table of nodes over the CPU/mem/disk thresholds, each row citing the measured % and the fix\n2. `proxmox-aiops diagnose guest-health` → guests near their memory ceiling or with disks near full, plus the list of stopped guests\n3. Act on the top finding — e.g. `proxmox-aiops vm migrate --to-node ` to shed load off a hot node, or `vm reconfigure --memory ...` for a RAM-starved guest. All of these route through the governed path (audited, undo recorded).\n\n### Snapshot, then reconfigure a VM\n\n1. `proxmox-aiops vm list` → find the vmid and confirm it is the right VM/node\n2. `proxmox-aiops vm snapshot-create --name pre-change` → baseline before any risky change\n3. `proxmox-aiops vm reconfigure --cores 8 --memory 16384` → the harness captures the prior cores/memory as the undo descriptor\n4. **Failure branch**: if the change goes wrong, the write recorded an `_undo_id` — reverse it with `proxmox-aiops undo apply `, or roll back with `proxmox-aiops vm snapshot-rollback --name pre-change`.\n\n### Free a node that is out of memory\n\n1. `proxmox-aiops diagnose node-pressure` → identify the node flagged `high memory`\n2. `proxmox-aiops cluster resources --type vm` → find a movable guest on that node\n3. `proxmox-aiops vm migrate --to-node --dry-run` → preview, then run without `--dry-run` (migrate is `high` risk; the inverse migrate-back is recorded)\n4. Re-run `diagnose node-pressure` to confirm the pressure cleared.\n\n### Stop a VM safely\n\n1. `proxmox-aiops vm get ` → confirm current status is `running`\n2. `proxmox-aiops vm stop --dry-run` → preview the exact API call\n3. `proxmox-aiops vm stop ` → double confirmation required; `vm_stop` records an inverse `vm_start` undo descriptor\n4. **Failure branch**: if `doctor` shows the node unreachable or the secret env var is missing, fix credentials with `proxmox-aiops secret set ` before retrying — the stop is never issued against an unauthenticated session.\n\n## Usage Mode\n\n| Scenario | Recommended | Why |\n|----------|:-----------:|-----|\n| Local/small models | **CLI** | fewer tokens than MCP |\n| Cloud models (Claude, GPT) | Either | MCP gives structured JSON I/O |\n| Automated pipelines | **MCP** | type-safe parameters, audited |\n\n## MCP Tools (43 — 25 read, 18 write)\n\n| Category | Tools | R/W |\n|----------|-------|:---:|\n| VM Lifecycle | `vm_list`, `vm_get`, `vm_config` | Read |\n| | `vm_start`, `vm_stop`, `vm_shutdown`, `vm_reboot`, `vm_reconfigure`, `vm_clone`, `vm_delete`, `vm_migrate` | Write |\n| Snapshots | `vm_list_snapshots` | Read |\n| | `vm_snapshot_create`, `vm_snapshot_delete`, `vm_snapshot_rollback` | Write |\n| Disk | `vm_resize_disk` (grow-only), `vm_move_disk` | Write |\n| Backups | `backup_list` | Read |\n| | `vm_backup`, `backup_restore` (high) | Write |\n| LXC Containers | `ct_list` | Read |\n| | `ct_start`, `ct_stop` | Write |\n| Cluster / Tasks | `node_list`, `cluster_status`, `task_status`, `cluster_resources`, `node_status`, `task_log`, `next_vmid` | Read |\n| HA | `ha_status`, `ha_resource_list` | Read |\n| Pools | `pool_list`, `pool_members` | Read |\n| Firewall | `vm_firewall_rules_list`, `cluster_firewall_status` | Read |\n| Guest Agent | `vm_agent_ping` | Read |\n| Storage | `storage_list`, `storage_content` | Read |\n| Diagnostics / RCA | `node_pressure_rca`, `guest_health_rca` | Read |\n| Undo | `undo_list` | Read |\n| | `undo_apply` | Write |\n\n**Harness features that light up**: write tools with a clean inverse (`vm_start`/`vm_stop`/`vm_shutdown`/`vm_reconfigure`/`vm_clone`/`vm_migrate`/`vm_snapshot_create`/`vm_move_disk`/`ct_start`/`ct_stop`) pass an `undo=` lambda so the harness records an inverse descriptor (with `_undo_id`) to the undo store — `vm_reconfigure` captures the prior cores/memory, `vm_clone`'s inverse is `vm_delete(newid)`, `vm_migrate`'s is migrate-back, `vm_move_disk`'s is move-back to the captured source storage. `backup_restore` records a `vm_delete` inverse **only** when it restored into a free VMID (a forced overwrite is destructive and declares none). Irreversible writes (`vm_delete`, `vm_snapshot_rollback`, `backup_restore` with `force`) declare no undo and are tagged `risk_level=high`; `vm_resize_disk` is grow-only and refuses shrink before any API call. All 43 tools are audit-logged under `~/.proxmox-aiops/` and pass through the budget/runaway guard + risk-tier taggin\n\nArchive v0.11.0: 7 files, 14877 bytes\n\nFiles: references/agent-guardrails.md (4785b), references/capabilities.md (4523b), references/cli-reference.md (2012b), references/setup-guide.md (2363b), skill-card.md (3049b), SKILL.md (15763b), _meta.json (133b)\n\nArchive v0.10.0: 7 files, 14861 bytes\n\nFiles: references/agent-guardrails.md (4785b), references/capabilities.md (4523b), references/cli-reference.md (2012b), references/setup-guide.md (2363b), skill-card.md (2920b), SKILL.md (15763b), _meta.json (133b)\n\nArchive v0.9.0: 7 files, 14881 bytes\n\nFiles: references/agent-guardrails.md (4785b), references/capabilities.md (4438b), references/cli-reference.md (2012b), references/setup-guide.md (2363b), skill-card.md (3038b), SKILL.md (15763b), _meta.json (132b)\n\nArchive v0.8.0: 7 files, 14912 bytes\n\nFiles: references/agent-guardrails.md (4785b), references/capabilities.md (4438b), references/cli-reference.md (2012b), references/setup-guide.md (2363b), skill-card.md (3109b), SKILL.md (15763b), _meta.json (132b)\n\nArchive v0.7.0: 7 files, 14697 bytes\n\nFiles: references/agent-guardrails.md (4785b), references/capabilities.md (4438b), references/cli-reference.md (2012b), references/setup-guide.md (2363b), skill-card.md (2647b), SKILL.md (15763b), _meta.json (132b)","readmeExcerpt":"Skill: proxmox-aiops Owner: zw008 Summary: Use this skill whenever the user needs to manage VMs and containers on Proxmox VE — list/inspect/configure VMs, power and lifecycle (start/stop/shutdown/reboot/reconfigure/clone/delete/migrate), snapshots (create/delete/list/rollback), disk grow/move, vzdump backups (create/list/restore), LXC containers (list/start/stop), cluster/node status, cluster resource inventory, asyn","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"uv tool install proxmox-aiops\nproxmox-aiops doctor"},{"language":"bash","snippet":"openclaw plugins install clawhub:@zw008/proxmox-aiops\nopenclaw skills info proxmox-aiops # expect: Visible to model: yes"},{"language":"bash","snippet":"proxmox-aiops vm list [--target ] [--node ]\nproxmox-aiops vm get [--node ]\nproxmox-aiops vm start [--node ]\nproxmox-aiops vm stop [--dry-run] # double confirm\nproxmox-aiops vm resize-disk --disk scsi0 --size +10G # grow-only\nproxmox-aiops vm move-disk --disk scsi0 --storage ceph [--delete]\nproxmox-aiops vm agent-ping \nproxmox-aiops vm snapshot-create --name \nproxmox-aiops vm snapshot-delete --name [--dry-run] # double confirm\nproxmox-aiops vm snapshot-list \nproxmox-aiops backup create --storage [--mode snapshot]\nproxmox-aiops backup list [--vmid ]\nproxmox-aiops backup restore --archive --storage [--force] [--dry-run] # double confirm\nproxmox-aiops cluster resources [--type vm|node|storage]\nproxmox-aiops cluster node-status \nproxmox-aiops cluster task-log \nproxmox-aiops cluster next-vmid\nproxmox-aiops ha status\nproxmox-aiops pool list\nproxmox-aiops firewall vm-rules \nproxmox-aiops storage list [--node ]\nproxmox-aiops diagnose node-pressure # rank nodes by CPU/mem/disk pressure (read-only RCA)\nproxmox-aiops diagnose guest-health # stopped guests, mem saturation, disks near full\nproxmox-aiops undo apply # reverse a recorded governed write\nproxmox-aiops init # onboarding wizard (encrypted creds)\nproxmox-aiops secret set # manage encrypted secret store\nproxmox-aiops doctor\nproxmox-aiops mcp # start MCP server (stdio)"},{"language":"text","snippet":"You operate a Proxmox VE environment through the proxmox-aiops MCP tools.\n\nTOOL USE\n- Before answering any question about the current Proxmox environment, you MUST\n call a tool. Never answer from memory or assumption.\n- Actually invoke the tool. Do not describe the call you would make, and do not\n emit an example JSON response in place of calling it.\n- If a tool call fails, report the real error verbatim. Never fill the gap with\n a plausible-sounding answer.\n\nREADING RESULTS\n- Read the whole result before concluding. If a result contains a \"truncated\"\n field that is true, say so and re-run with a higher limit instead of treating\n the partial result as complete.\n- A null field means the API did not return that value. Report it as \"not\n available\" — never infer it.\n- Report values exactly as returned. Do not normalise, translate, or prettify\n status strings, severities, or IDs.\n- When a diagnose result has findings, work in \"rank\" order and cite the\n measured number in each finding's \"detail\".\n\nSCOPE\n- Separate observation from interpretation. State what the tools returned, then\n any interpretation, clearly marked as such.\n- Do not assert a capacity, performance, or availability problem unless a tool\n result supports it.\n- Do not add generic advice that does not follow from the tool output.\n- Do not confuse a VMID with a node name, or a task UPID with either."},{"language":"bash","snippet":"proxmox-aiops doctor # verify connectivity with your least-privilege token"},{"language":"bash","snippet":"export PROXMOX_AUDIT_APPROVED_BY=\"your.name@example.com\"\nexport PROXMOX_AUDIT_RATIONALE=\"scheduled maintenance window\""}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: proxmox-aiops\nslug: proxmox-aiops\ndisplayName: \"Proxmox AIops\"\nsummary: \"Governed Proxmox VE VM/container ops — 43 MCP tools with audit, budget, undo & risk-tier guards.\"\nlicense: MIT\nhomepage: https://github.com/AIops-tools/Proxmox-AIops\ntags: [aiops, mcp, governance, proxmox]\ndescription: >\n Use this skill whenever the user needs to manage VMs and containers on Proxmox VE — list/inspect/configure VMs, power and lifecycle (start/stop/shutdown/reboot/reconfigure/clone/delete/migrate), snapshots (create/delete/list/rollback), disk grow/move, vzdump backups (create/list/restore), LXC containers (list/start/stop), cluster/node status, cluster resource inventory, async task polling + logs, free-VMID lookup, HA status, resource pools, firewall inspection, guest-agent ping, and storage listing.\n Also use it to diagnose cluster health — rank nodes by CPU/memory/disk pressure and scan guests for saturation (read-only RCA).\n Always use this skill for \"list proxmox vms\", \"start proxmox vm\", \"stop proxmox vm\", \"proxmox snapshot\", \"proxmox backup\", \"restore proxmox vm\", \"resize proxmox disk\", \"proxmox vm status\", \"migrate proxmox vm\", \"proxmox container\", \"proxmox ha\", \"proxmox pool\", \"proxmox firewall\", \"list proxmox storage\", \"proxmox node pressure\", or \"why is proxmox slow\" when the context is explicitly Proxmox / Proxmox VE / PVE.\n Do NOT use for non-Proxmox hypervisors, Kubernetes, or cloud providers.\n Broad coverage of common Proxmox operations, with a built-in governance harness (audit, token budget, undo, risk-tier labels).\ninstaller:\n kind: uv\n package: proxmox-aiops\nargument-hint: \"[vmid or describe your Proxmox task]\"\nallowed-tools:\n - Bash\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"proxmox-aiops\",\"uvx\"]},\"optional\":{\"env\":[\"PROXMOX_AIOPS_CONFIG\",\"PROXMOX_TARGET_SECRET\"]},\"homepage\":\"https://github.com/AIops-tools/Proxmox-AIops\",\"emoji\":\"🧱\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n Standalone, self-governed Proxmox VE operations. The governance harness (audit, token/runaway budget, undo, risk-tier labels) is bundled in the package — no external skill-family dependency.\n All write operations are audited to a local SQLite DB under ~/.proxmox-aiops/ (relocatable via PROXMOX_AIOPS_HOME).\n Credentials: Each Proxmox target requires a per-target secret env var in ~/.proxmox-aiops/.env following the pattern PROXMOX__SECRET (API token UUID for token auth, or login password). Secrets are never logged or echoed; .env should be chmod 600.\n Destructive operations (vm stop/delete/snapshot-delete/snapshot-rollback, ct stop) require double confirmation at the CLI layer and support --dry-run. All write tools pass through the @governed_tool decorator (budget guard + audit + risk-tier tagging). Reversible writes record an inverse undo descriptor to the undo store.\n Webhooks: none — no outbound network calls beyond the configured Proxmox API endpoint.\n SSL: verify_ssl defaults to true; disable only for self-signed lab "},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7b067awq2s97bn3d7p5qfhw5827pxc\",\n \"slug\": \"proxmox-aiops\",\n \"version\": \"0.13.3\",\n \"publishedAt\": 1789453009059\n}"},{"path":"references/agent-guardrails.md","content":"# Agent guardrails — running proxmox-aiops with a smaller / local model\n\nIf you drive these tools with a local model (Llama, Qwen, Mistral … via Goose,\nOllama, LM Studio, or any OpenAI-compatible runtime), you will get noticeably\nbetter results with a short system prompt. This page gives you one, and — more\nimportantly — tells you which guardrails you **no longer need to write**, because\nthe tool now enforces them itself.\n\nThe distinction matters. A guardrail in a prompt is a request. A guardrail in the\nharness is a guarantee. Anything below that we could move into the harness, we did.\n\n## What the tool now enforces — do not waste prompt budget on these\n\n| You might be tempted to prompt | Why you don't need to |\n|---|---|\n| \"Don't invent a value when a field is missing\" | A field the API did not return comes back as `null`, never as `\"\"`. Absent and empty are distinguishable in the payload. |\n| \"Tell me if the output was cut off\" | Anything with a `limit` returns `{\"lines\": [...], \"returned\": N, \"limit\": L, \"truncated\": true/false}`. Truncation is measured (one extra row is fetched), not guessed. |\n| \"Preserve the ordering / tell me what's most urgent\" | `diagnose` findings carry an explicit 1-based `rank`, worst-first. Priority is in the payload, not implied by list position. |\n| \"Confirm before anything destructive\" | Destructive operations require a `--dry-run`-able preview + double confirmation at the CLI. |\n| \"Log what you did\" | Every call is audited to `~/.proxmox-aiops/audit.db` regardless of what the model says it did. |\n\n## What still needs a prompt\n\nThese are model-behaviour problems the harness cannot fix from the outside.\nCopy this into your agent's system prompt:\n\n```text\nYou operate a Proxmox VE environment through the proxmox-aiops MCP tools.\n\nTOOL USE\n- Before answering any question about the current Proxmox environment, you MUST\n call a tool. Never answer from memory or assumption.\n- Actually invoke the tool. Do not describe the call you would make, and do not\n emit an example JSON response in place of calling it.\n- If a tool call fails, report the real error verbatim. Never fill the gap with\n a plausible-sounding answer.\n\nREADING RESULTS\n- Read the whole result before concluding. If a result contains a \"truncated\"\n field that is true, say so and re-run with a higher limit instead of treating\n the partial result as complete.\n- A null field means the API did not return that value. Report it as \"not\n available\" — never infer it.\n- Report values exactly as returned. Do not normalise, translate, or prettify\n status strings, severities, or IDs.\n- When a diagnose result has findings, work in \"rank\" order and cite the\n measured number in each finding's \"detail\".\n\nSCOPE\n- Separate observation from interpretation. State what the tools returned, then\n any interpretation, clearly marked as such.\n- Do not assert a capacity, performance, or availability problem unless a tool\n result supports it.\n- Do not add generic advice that doe"},{"path":"references/capabilities.md","content":"# proxmox-aiops capabilities\n\n43 MCP tools (25 read / 18 write). Every tool is wrapped with the bundled\n`@governed_tool` harness (audit + budget + risk-tier + undo). Typical response\nsizes are small high-signal summaries, not full API blobs.\n\n## VM lifecycle (11)\n\n| Tool | R/W | Inverse (undo) | Typical response |\n|------|:---:|----------------|------------------|\n| `vm_list` | R | — | ~50–500 tok (one row per VM) |\n| `vm_get` | R | — | ~120 tok |\n| `vm_config` | R | — | ~120 tok |\n| `vm_start` | W | `vm_stop` | task UPID |\n| `vm_stop` | W | `vm_start` | task UPID |\n| `vm_shutdown` | W | `vm_start` | task UPID |\n| `vm_reboot` | W | — (no inverse) | task UPID |\n| `vm_reconfigure` | W | `vm_reconfigure` (prior cores/memory) | applied + previous |\n| `vm_clone` | W | `vm_delete(newid)` | task UPID |\n| `vm_delete` | W | — (irreversible, risk=high) | task UPID |\n| `vm_migrate` | W | `vm_migrate` (back to source node) | task UPID |\n\n## Snapshots (4)\n\n| Tool | R/W | Inverse | Notes |\n|------|:---:|---------|-------|\n| `vm_list_snapshots` | R | — | name + description |\n| `vm_snapshot_create` | W | `vm_snapshot_delete` | |\n| `vm_snapshot_delete` | W | — | |\n| `vm_snapshot_rollback` | W | — (irreversible, risk=high) | discards newer state |\n\n## Disk (2)\n\n| Tool | R/W | Inverse | Notes |\n|------|:---:|---------|-------|\n| `vm_resize_disk` | W | — (grow-only; shrink refused) | `+G` or larger absolute |\n| `vm_move_disk` | W | `vm_move_disk` (back to source storage) | task UPID |\n\n## Backups — vzdump (3)\n\n| Tool | R/W | Inverse | Notes |\n|------|:---:|---------|-------|\n| `backup_list` | R | — | archives on a storage, filterable by vmid |\n| `vm_backup` | W | — | task UPID; mode snapshot/suspend/stop |\n| `backup_restore` | W | `vm_delete` only when restored into a free vmid; none on forced overwrite (risk=high) | task UPID |\n\n## LXC containers (3)\n\n| Tool | R/W | Inverse |\n|------|:---:|---------|\n| `ct_list` | R | — |\n| `ct_start` | W | `ct_stop` |\n| `ct_stop` | W | `ct_start` |\n\n## Cluster / tasks (7)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `node_list` | R | status, cpu load, memory |\n| `cluster_status` | R | membership + quorum |\n| `task_status` | R | poll an async UPID (clone/migrate/backup) |\n| `cluster_resources` | R | `/cluster/resources` inventory (vm/node/storage filter) |\n| `node_status` | R | one node: cpu, load average, memory, uptime |\n| `task_log` | R | log lines of an async task by UPID |\n| `next_vmid` | R | a free VMID for a new guest |\n\n## HA (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `ha_status` | R | `{configured, entries}`; `configured` is true only when HA manages a resource — every cluster reports quorum/master/lrm rows regardless |\n| `ha_resource_list` | R | HA-managed resources; empty when HA absent |\n\n## Pools (2)\n\n| Tool | R/W | Notes |\n|------|:---:|-------|\n| `pool_list` | R | poolid + comment |\n| `pool_members` | R | members (VMs/CTs/storage) of a pool |\n\n## Firewall — read-only (2)\n\n| Tool | R/W | Notes |\n|----"},{"path":"references/cli-reference.md","content":"# proxmox-aiops CLI reference\n\nAll commands take `--target/-t ` (config target; omit for default) and,\nwhere relevant, `--node/-n `. Destructive commands support `--dry-run`.\n\n## VM lifecycle\n\n```bash\nproxmox-aiops vm list [-t ] [-n ]\nproxmox-aiops vm get \nproxmox-aiops vm config \nproxmox-aiops vm start \nproxmox-aiops vm stop [--dry-run] # hard power-off (double confirm)\nproxmox-aiops vm shutdown [--dry-run] # graceful ACPI\nproxmox-aiops vm reboot \nproxmox-aiops vm reconfigure [--cores N] [--memory MiB] [--dry-run]\nproxmox-aiops vm clone --newid [--name ]\nproxmox-aiops vm delete [--dry-run] # irreversible (double confirm)\nproxmox-aiops vm migrate --to-node [--offline] [--dry-run]\n```\n\n## Snapshots\n\n```bash\nproxmox-aiops vm snapshot-create --name \nproxmox-aiops vm snapshot-list \nproxmox-aiops vm snapshot-delete --name [--dry-run] # double confirm\nproxmox-aiops vm snapshot-rollback --name [--dry-run] # irreversible\n```\n\n## LXC containers\n\n```bash\nproxmox-aiops ct list [-n ]\nproxmox-aiops ct start \nproxmox-aiops ct stop [--dry-run] # double confirm\n```\n\n## Cluster / async tasks\n\n```bash\nproxmox-aiops cluster nodes\nproxmox-aiops cluster status # membership + quorum\nproxmox-aiops cluster task-status # poll a clone/migrate/backup task\n```\n\n## Storage\n\n```bash\nproxmox-aiops storage list [-n ]\nproxmox-aiops storage content [--content iso|images|backup|vztmpl]\n```\n\n## Diagnostics & MCP\n\n```bash\nproxmox-aiops doctor # verify connectivity + credentials\nproxmox-aiops mcp # start the MCP server (stdio)\n```\n\n> Proxmox writes are asynchronous and return a task UPID. Poll completion with\n> `cluster task-status ` rather than re-issuing the operation."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1721,"uniquenessScore":40,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T19:54:31.160Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T19:54:31.160Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T03:06:08.324Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}