{"id":"8f99e374-b122-4a8f-b4c3-7ec96443dcd4","entityType":"agent","slug":"clawhub-zw008-xcpng-aiops","name":"xcpng-aiops","canonicalUrl":"https://www.xpersona.co/agent/clawhub-zw008-xcpng-aiops","canonicalPath":"/agent/clawhub-zw008-xcpng-aiops","generatedAt":"2026-10-10T23:48:32.340Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T20:02:06.388Z","emptyReason":null},"description":"Use this skill whenever the user needs to operate an XCP-ng virtualization fleet through Xen Orchestra — a one-shot fleet health overview; VMs (list/get/RRD stats), hosts, pools, storage repositories (SRs) and VDIs, VM snapshots, backup jobs and run logs, XO tasks; four RCA analyses (VM health, SR usage, backup-job failures, pool patch & HA posture); and governed writes (VM start/stop/reboot/migrate, snapshot create/delete/revert, SR rescan). Always use this skill for \"xcp-ng vm\", \"xen orchestra\", \"xo backup failed\", \"sr full\", \"orphaned vdi\", \"xcp-ng snapshot\", \"migrate vm to another host\", \"xcp-ng patches\", or \"pool HA\" when the context is explicitly XCP-ng / Xen Orchestra / a Xen-based fleet. Do NOT use when the target is not an XCP-ng fleet managed by Xen Orchestra — other hypervisors (Do NOT use for Proxmox VE — use proxmox-aiops), NAS/storage appliances, backup software suites, container clusters, and network devices are out of scope (negative routing hints only). Common XCP-ng-via-XO operations with a built-in governance harness (audit, policy, token budget, undo, risk-tiers).","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.3K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s171xgnmqse0nqvgqvqnaq5f9183kyre:xcpng-aiops","sourceUrl":"https://clawhub.ai/zw008/xcpng-aiops","homepage":"https://clawhub.ai/zw008/skills/xcpng-aiops","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/zw008/xcpng-aiops","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/zw008/skills/xcpng-aiops","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":62,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"xcpng-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-10T20:02:06.388Z","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-10T20:02:06.388Z","emptyReason":null},"stars":null,"forks":null,"downloads":1272,"packageName":null,"latestVersion":"0.8.4","tractionLabel":"1.3K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T20:02:06.316Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T20:02:06.388Z","lastCrawledAt":"2026-10-10T20:02:06.316Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T20:02:06.316Z","lastVerifiedAt":null,"highlights":[{"version":"0.8.4","createdAt":"2026-09-16T05:19:16.634Z","changelog":"- Removed the skill-card.md file. - No changes to feature set or core functionality; this is a documentation/content cleanup only.","fileCount":7,"zipByteSize":21168},{"version":"0.8.3","createdAt":"2026-09-15T06:24:26.794Z","changelog":"- Removed the file skill-card.md. - No functionality or feature changes in this version. - Housekeeping update; documentation/reference file removal only.","fileCount":7,"zipByteSize":21099},{"version":"0.8.2","createdAt":"2026-09-12T14:49:52.307Z","changelog":"xcpng-aiops 0.8.2 - Updated documentation in SKILL.md for precision and clarity. - Changed the OpenClaw plugin install command in docs to use `clawhub:@zw008/xcpng-aiops`. - Removed file: skill-card.md.","fileCount":7,"zipByteSize":21266},{"version":"0.8.1","createdAt":"2026-09-12T10:31:26.874Z","changelog":"xcpng-aiops v0.8.1 - Added plugin install instructions and OpenClaw integration details to SKILL.md. - Clarified need for `uvx` on `PATH` when using OpenClaw plugin. - Removed the skill-card.md file. - No changes to functionality; documentation improvements only.","fileCount":7,"zipByteSize":21035},{"version":"0.8.0","createdAt":"2026-09-12T01:17:27.439Z","changelog":"- Updated required binaries metadata: now accepts either \"xcpng-aiops\" or \"uvx\" for improved compatibility. - Cleaned up metadata environmental variables: \"XCPNG_AIOPS_CONFIG\" and \"XCPNG_AIOPS_MASTER_PASSWORD\" moved to optional. - Removed the redundant \"skill-card.md\" file. - No changes to core features or tool functionality in this release.","fileCount":7,"zipByteSize":21210},{"version":"0.7.0","createdAt":"2026-08-10T06:54:50.816Z","changelog":"- Removed the file: skill-card.md. - No changes to functionality or interfaces. - Documentation and core skill metadata remain unchanged.","fileCount":7,"zipByteSize":21145},{"version":"0.6.0","createdAt":"2026-08-03T05:55:26.970Z","changelog":"- Removed the file skill-card.md. - No changes to core functionality, description, or metadata. - No impact to skill features or usage; this is a non-functional change. - Maintains all previous compatibility and install instructions.","fileCount":7,"zipByteSize":20960},{"version":"0.5.0","createdAt":"2026-08-02T09:42:28.176Z","changelog":"- Removed the sample file skill-card.md. - No changes to code or functionality. - Documentation and skill metadata remain unchanged.","fileCount":7,"zipByteSize":21001}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s171xgnmqse0nqvgqvqnaq5f9183kyre:xcpng-aiops","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s171xgnmqse0nqvgqvqnaq5f9183kyre:xcpng-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/xcpng-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-xcpng-aiops/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-xcpng-aiops/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-xcpng-aiops/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zw008-xcpng-aiops/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zw008-xcpng-aiops/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zw008-xcpng-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-10T23:48:32.335Z"}},"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-xcpng-aiops/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-xcpng-aiops/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-xcpng-aiops/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-xcpng-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-10T20:02:06.388Z","emptyReason":null},"readme":"Skill: xcpng-aiops\n\nOwner: zw008\n\nSummary: Use this skill whenever the user needs to operate an XCP-ng virtualization fleet through Xen Orchestra — a one-shot fleet health overview; VMs (list/get/RRD stats), hosts, pools, storage repositories (SRs) and VDIs, VM snapshots, backup jobs and run logs, XO tasks; four RCA analyses (VM health, SR usage, backup-job failures, pool patch & HA posture); and governed writes (VM start/stop/reboot/migrate, snapshot create/delete/revert, SR rescan). Always use this skill for \"xcp-ng vm\", \"xen orchestra\", \"xo backup failed\", \"sr full\", \"orphaned vdi\", \"xcp-ng snapshot\", \"migrate vm to another host\", \"xcp-ng patches\", or \"pool HA\" when the context is explicitly XCP-ng / Xen Orchestra / a Xen-based fleet. Do NOT use when the target is not an XCP-ng fleet managed by Xen Orchestra — other hypervisors (Do NOT use for Proxmox VE — use proxmox-aiops), NAS/storage appliances, backup software suites, container clusters, and network devices are out of scope (negative routing hints only). Common XCP-ng-via-XO operations with a built-in governance harness (audit, policy, token budget, undo, risk-tiers).\n\nTags: latest:0.8.4\n\nVersion history:\n\nv0.8.4 | 2026-09-16T05:19:16.634Z | auto\n\n- Removed the skill-card.md file.\n- No changes to feature set or core functionality; this is a documentation/content cleanup only.\n\nv0.8.3 | 2026-09-15T06:24:26.794Z | auto\n\n- Removed the file skill-card.md.\n- No functionality or feature changes in this version.\n- Housekeeping update; documentation/reference file removal only.\n\nv0.8.2 | 2026-09-12T14:49:52.307Z | auto\n\nxcpng-aiops 0.8.2\n\n- Updated documentation in SKILL.md for precision and clarity.\n- Changed the OpenClaw plugin install command in docs to use `clawhub:@zw008/xcpng-aiops`.\n- Removed file: skill-card.md.\n\nv0.8.1 | 2026-09-12T10:31:26.874Z | auto\n\nxcpng-aiops v0.8.1\n\n- Added plugin install instructions and OpenClaw integration details to SKILL.md.\n- Clarified need for `uvx` on `PATH` when using OpenClaw plugin.\n- Removed the skill-card.md file. \n- No changes to functionality; documentation improvements only.\n\nv0.8.0 | 2026-09-12T01:17:27.439Z | auto\n\n- Updated required binaries metadata: now accepts either \"xcpng-aiops\" or \"uvx\" for improved compatibility.\n- Cleaned up metadata environmental variables: \"XCPNG_AIOPS_CONFIG\" and \"XCPNG_AIOPS_MASTER_PASSWORD\" moved to optional.\n- Removed the redundant \"skill-card.md\" file.\n- No changes to core features or tool functionality in this release.\n\nv0.7.0 | 2026-08-10T06:54:50.816Z | auto\n\n- Removed the file: skill-card.md.\n- No changes to functionality or interfaces.\n- Documentation and core skill metadata remain unchanged.\n\nv0.6.0 | 2026-08-03T05:55:26.970Z | auto\n\n- Removed the file skill-card.md.\n- No changes to core functionality, description, or metadata.\n- No impact to skill features or usage; this is a non-functional change.\n- Maintains all previous compatibility and install instructions.\n\nv0.5.0 | 2026-08-02T09:42:28.176Z | auto\n\n- Removed the sample file skill-card.md.\n- No changes to code or functionality.\n- Documentation and skill metadata remain unchanged.\n\nv0.4.0 | 2026-07-21T09:43:25.513Z | auto\n\nxcpng-aiops v0.4.0\n\n- Updated governance harness: @governed_tool decorator now emphasizes budget guarding, audit, and descriptive risk tier labelling.\n- Clarified operational guidance and write-tool safeguards in documentation, especially regarding dry-run, audits, and irreversible actions.\n- Expanded and improved reference documentation files for guardrails, capabilities, CLI usage, and setup.\n- Removed the outdated skill-card.md file.\n- General enhancements and clarifications for consistency across documentation.\n\nv0.3.0 | 2026-07-20T11:17:52.558Z | auto\n\nxcpng-aiops 0.3.0\n\n- Clarified behavior for dry_run: dry runs of write MCP tools may perform reads to preview refusals, never write or record undo, and are audited like governed calls.\n- vm_stop now refuses to stop the current Xen Orchestra VM (if declared; opt-in guard), preventing accidental loss of API control.\n- Documentation expanded for dry_run semantics and self-stop safeguards.\n- Removed the obsolete skill-card.md file.\n\nv0.2.1 | 2026-07-19T17:36:35.008Z | auto\n\n- Removed the file: skill-card.md\n- No other changes to functionality or documentation.\n\nv0.2.0 | 2026-07-19T03:53:51.202Z | auto\n\n**Changelog for xcpng-aiops v0.2.0**\n\n- Expanded REST API tool coverage from 27 to 29 MCP tools.\n- Governance and agent guardrails documentation added.\n- Skill metadata refined: slug, displayName, summary, tags, and license fields updated.\n- References reorganized and expanded; new agent guardrails reference added, deprecated skill-card removed.\n- Clarified verification status and live-run checklist location in docs.\n\nv0.1.0 | 2026-07-17T05:57:55.082Z | auto\n\nInitial preview release: governed XCP-ng operations via Xen Orchestra REST API.\n\n- Offers 27 tools for common VM, host, pool, storage, snapshot, backup, and RCA operations.\n- All write actions are governed: local audit log, policy, risk tiers, undo-recording, and double CLI confirmation for dangerous tasks.\n- Requires encrypted XO authentication token; never stores tokens in plaintext.\n- Fully standalone—no external skill dependencies; supports both interactive and CI use.\n- Preview-only: API paths are modeled but not yet live-tested; mock-validated.\n- Use exclusively for XCP-ng fleets managed by Xen Orchestra; all other targets are out of scope.\n\nArchive index:\n\nArchive v0.8.4: 7 files, 21168 bytes\n\nFiles: references/agent-guardrails.md (7975b), references/capabilities.md (6380b), references/cli-reference.md (4010b), references/setup-guide.md (3226b), skill-card.md (2753b), SKILL.md (21953b), _meta.json (130b)\n\nFile v0.8.4:SKILL.md\n\n---\nname: xcpng-aiops\nslug: xcpng-aiops\ndisplayName: \"XCP-ng AIops\"\nsummary: \"Governed XCP-ng ops via Xen Orchestra — 29 MCP tools with audit, budget, undo guards.\"\nlicense: MIT\nhomepage: https://github.com/AIops-tools/XCPng-AIops\ntags: [aiops, mcp, governance, xcpng]\ndescription: >\n Use this skill whenever the user needs to operate an XCP-ng virtualization fleet through Xen Orchestra — a one-shot fleet health overview; VMs (list/get/RRD stats), hosts, pools, storage repositories (SRs) and VDIs, VM snapshots, backup jobs and run logs, XO tasks; four RCA analyses (VM health, SR usage, backup-job failures, pool patch & HA posture); and governed writes (VM start/stop/reboot/migrate, snapshot create/delete/revert, SR rescan).\n Always use this skill for \"xcp-ng vm\", \"xen orchestra\", \"xo backup failed\", \"sr full\", \"orphaned vdi\", \"xcp-ng snapshot\", \"migrate vm to another host\", \"xcp-ng patches\", or \"pool HA\" when the context is explicitly XCP-ng / Xen Orchestra / a Xen-based fleet.\n Do NOT use when the target is not an XCP-ng fleet managed by Xen Orchestra — other hypervisors (Do NOT use for Proxmox VE — use proxmox-aiops), NAS/storage appliances, backup software suites, container clusters, and network devices are out of scope (negative routing hints only).\n Common XCP-ng-via-XO operations with a built-in governance harness (audit, policy, token budget, undo, risk-tiers).\ninstaller:\n kind: uv\n package: xcpng-aiops\nargument-hint: \"[vm/sr/snapshot uuid or describe your XCP-ng task]\"\nallowed-tools:\n - Bash\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"xcpng-aiops\",\"uvx\"]},\"optional\":{\"env\":[\"XCPNG_AIOPS_CONFIG\",\"XCPNG_AIOPS_MASTER_PASSWORD\"]},\"homepage\":\"https://github.com/AIops-tools/XCPng-AIops\",\"emoji\":\"🖥️\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n Standalone, self-governed XCP-ng operations via Xen Orchestra's REST API /rest/v0. REQUIRES a Xen Orchestra instance (XO from sources or the Xen Orchestra Appliance, 5.x) — XO is the management plane; direct per-host XAPI access is out of scope for v0.1. The governance harness (audit, policy, token/runaway budget, undo, risk-tiers) is bundled in the package — no external skill-family dependency.\n All write operations are audited to a local SQLite DB under ~/.xcpng-aiops/ (relocatable via XCPNG_AIOPS_HOME).\n Credentials: Each XO target's personal authentication token is stored ENCRYPTED in ~/.xcpng-aiops/secrets.enc (Fernet/AES-128 + scrypt-derived key) — never plaintext on disk. Run 'xcpng-aiops init' to onboard, or 'xcpng-aiops secret set ' to add one (create the token in the XO UI: user menu → Personal tokens, or `xo-cli --createToken`). The store is unlocked by a master password from XCPNG_AIOPS_MASTER_PASSWORD (non-interactive/MCP/CI) or an interactive prompt (CLI on a TTY). A legacy plaintext env var XCPNG__TOKEN is still honoured as a fallback with a deprecation warning (migrate with 'xcpng-aiops secret migrate'). The token is sent in headers (Authorization: Bearer + authenticationToken cookie) at request time and held only in memory; tokens are never logged or echoed.\n Destructive operations (snapshot delete/revert, vm stop/reboot/migrate) require double confirmation at the CLI layer and support --dry-run; every write MCP tool takes a dry_run preview. A dry_run MAY read (that is how it can tell you the call would be refused) but never writes, records no undo, and is audited like any other governed call. All write tools pass through the @governed_tool decorator (budget guard + audit + risk-tier labelling). vm_start↔vm_stop record each other as inverses; vm_migrate records migrating back to the captured source host; snapshot_create records deleting the REAL snapshot id XO returned; snapshot_delete and snapshot_revert are high-risk and irreversible (capture BEFORE state, record no undo). vm_stop refuses the VM declared as running Xen Orchestra (xo_self_vm_uuid on the target) because stopping XO removes the API vm_start would travel over; that guard is opt-in and fails open when undeclared, since XO's REST API exposes no self endpoint.\n Webhooks: none — no outbound network calls beyond the configured Xen Orchestra REST API endpoint.\n SSL: verify_ssl defaults to true; disable only for self-signed lab certificates.\n Transitive dependencies: httpx (HTTP client) and the MCP SDK. No post-install scripts or background services.\n Verification status: mock-validated; no recorded end-to-end run against a live Xen Orchestra instance yet. Endpoint paths are modelled against the documented Xen Orchestra REST /rest/v0 API and need live verification — action names may differ across XO releases. See docs/VERIFICATION.md.\n---\n\n# XCP-ng AIops\n\n> **Disclaimer**: This is a community-maintained open-source project and is **not affiliated with, endorsed by, or sponsored by Vates, the XCP-ng project, or the Xen Orchestra project.** \"XCP-ng\", \"Xen Orchestra\", and \"Xen\" are trademarks of their owners. Source code is publicly auditable at [github.com/AIops-tools/XCPng-AIops](https://github.com/AIops-tools/XCPng-AIops) under the MIT license.\n\nGoverned XCP-ng operations via **Xen Orchestra's REST API** — **29 MCP tools**, every one wrapped with the bundled `@governed_tool` harness: a local unified audit log under `~/.xcpng-aiops/`, policy engine, token/runaway budget guard, undo-token recording, and descriptive risk tiers. The XO authentication token is stored **encrypted** (`~/.xcpng-aiops/secrets.enc`, Fernet + scrypt) — never plaintext on disk.\n\n> **Requires a Xen Orchestra instance** (5.x with `/rest/v0`) — XO is the management plane; per-host XAPI is out of scope for v0.1. **Standalone**: the governance harness is bundled in the package (`xcpng_aiops.governance`) — xcpng-aiops has no external skill-family dependency. Coverage is common operations, not exhaustive; verification status and the live-run checklist are in `docs/VERIFICATION.md`.\n\n## What This Skill Does\n\n| Category | Tools | Count | Read or Write |\n|----------|-------|:-----:|:-------------:|\n| **Overview** | fleet health overview | 1 | 1 read |\n| **VMs** | list, get, RRD stats, health RCA | 4 | 4 read |\n| | start, stop, reboot, migrate | 4 | 4 write (medium) |\n| **Hosts** | list, get | 2 | 2 read |\n| **Pools** | list, get, patch & HA posture RCA | 3 | 3 read |\n| **SRs / VDIs** | list, get, VDI list (orphan filter), usage RCA | 4 | 4 read |\n| | rescan | 1 | 1 write (medium) |\n| **Snapshots** | list | 1 | 1 read |\n| | create (medium), delete (high), revert (high) | 3 | 3 write |\n| **Backups** | jobs, run logs, failure RCA | 3 | 3 read |\n| **Tasks** | list | 1 | 1 read |\n\n## Quick Install\n\n```bash\nuv tool install xcpng-aiops\nxcpng-aiops init # interactive wizard: XO URL + encrypted token\nxcpng-aiops doctor # XO reachability + token validity + pool count\n```\n\nOr as an OpenClaw plugin, which installs this skill and its MCP server together:\n\n```bash\nopenclaw plugins install clawhub:@zw008/xcpng-aiops\nopenclaw skills info xcpng-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- Triage an XCP-ng fleet (`overview`): pools, hosts, VMs by state, SRs near full, recent backup failures\n- Root-cause an unhealthy VM (`vm health-rca`): halted unexpectedly, paused, guest tools missing, CPU/memory pressure\n- Root-cause storage pressure (`sr usage-rca`): SRs ranked near-full, thin-provision overcommit, orphaned VDIs with reclaimable bytes\n- Root-cause backup failures (`backup failure-rca`): vdi-chain / quiesce / transport / storage-full classification\n- Check patch & HA posture (`pool posture`): missing patches, pending reboots, version skew, HA state\n- Snapshot a VM before a risky change; start/stop/reboot/migrate VMs under governance\n\n**Do NOT use when** the target is not an XCP-ng fleet managed by Xen Orchestra — other hypervisors (Do NOT use for Proxmox VE — use proxmox-aiops), NAS/storage appliances, backup software suites, Kubernetes/containers, and network devices are out of scope for this skill.\n\n## Related Skills — Skill Routing\n\n| If the user wants… | Use |\n|--------------------|-----|\n| XCP-ng VMs / hosts / pools / SRs / snapshots / XO backups | **xcpng-aiops** (this skill) |\n| Proxmox VE operations | **proxmox-aiops** |\n| NAS/storage appliance operations | a storage-appliance ops skill |\n| Backup-software suite job/restore operations | a backup-software ops skill |\n| Container/cluster lifecycle | a cluster ops skill |\n\n## Common Workflows\n\nEach recipe starts from a read or an RCA and ends in a governed write. Every\nwrite accepts `--dry-run`; destructive ones also double-confirm.\n\n### 1. \"Patch a pool without breaking live migration\"\n\n1. `xcpng-aiops overview` → fleet snapshot: pools, hosts, VMs by state, SRs near full, recent backup failures.\n2. `xcpng-aiops pool posture` → the RCA: hosts missing patches, hosts pending reboot, **version skew** across the pool's hosts, and multi-host pools without HA.\n3. `xcpng-aiops host missing-patches ` → what exactly is outstanding on the host you plan to take first.\n4. `xcpng-aiops vm list --state Running` → the VMs that must move off that host.\n5. For each: `xcpng-aiops vm migrate --dry-run`, then re-run for real (double confirm; the REAL source host is captured before the move and the inverse \"migrate back\" is recorded).\n6. `xcpng-aiops undo list` → confirm a migrate-back token exists for every VM you moved, before you touch the host.\n7. Patch and reboot the host in XO, then `xcpng-aiops pool posture` again to confirm the skew cleared.\n\n**Failure branch**: if `pool posture` reports version skew *before* you start, stop — live migration between mismatched host versions can be refused or unsafe. Bring the hosts to a common version first. If a migration fails mid-run, do not retry blindly: `xcpng-aiops vm get ` to see where the VM actually landed, and `xcpng-aiops task list` for the failing XO task, since a half-finished migrate leaves the VM on one side or the other.\n\n### 2. \"This VM keeps going unhealthy\"\n\n1. `xcpng-aiops vm health-rca` → findings with cause + action: halted unexpectedly (auto-poweron / HA restart priority set), paused or suspended VMs, running VMs without guest tools, CPU/memory pressure from RRD stats.\n2. `xcpng-aiops vm get ` → the VM's configuration and current power state.\n3. `xcpng-aiops vm stats ` → the RRD series behind a pressure finding, so you confirm sustained pressure rather than one spike.\n4. If it is halted and should be running: `xcpng-aiops vm start ` (the inverse `vm_stop` is recorded).\n5. If it is wedged and needs a bounce: `xcpng-aiops vm reboot --dry-run`, then for real (double confirm; add `--force` only for a hard reboot — **no undo** either way).\n6. `xcpng-aiops vm health-rca` again to confirm the finding cleared.\n\n**Failure branch**: if a clean shutdown or clean reboot hangs, the finding \"no guest tools\" is usually the real cause — clean actions need the guest agent. Do not escalate straight to `--force`; a hard action risks filesystem damage. Snapshot first (recipe 3), then use `--force` deliberately.\n\n### 3. \"Snapshot before a risky change, and roll back cleanly\"\n\n1. `xcpng-aiops vm list` → confirm the exact VM uuid.\n2. `xcpng-aiops sr usage-rca` → make sure the SR has room; snapshots grow it, and a snapshot on a near-full SR is how you take the pool down.\n3. `xcpng-aiops snapshot create pre-change` → XO returns the new snapshot's id, and an inverse `snapshot_delete` for **that** id is recorded.\n4. `xcpng-aiops snapshot list --vm ` → confirm the snapshot exists before you change anything.\n5. Make your change. If it went wrong: `xcpng-aiops snapshot revert ` (double confirm — replaces current state, **IRREVERSIBLE**, no undo).\n6. When you are satisfied: `xcpng-aiops snapshot delete --dry-run`, then without `--dry-run` (double confirm — **IRREVERSIBLE**, BEFORE state captured for the audit record, no undo).\n\n**Failure branch**: if `sr usage-rca` flags the SR as near-full or thin-provision overcommitted, do not snapshot — reclaim first (recipe 4). If a revert is refused or leaves the VM halted, check `xcpng-aiops task list` for the XO task; and never leave snapshots stacked long-term, because unmerged chains are the usual root cause of the vdi-chain backup failures in recipe 4.\n\n### 4. \"Backups have been failing every night and storage is filling up\"\n\n1. `xcpng-aiops backup failure-rca` → failed/skipped/interrupted runs grouped by job and classified: **vdi-chain** (coalesce not finished), **quiesce** (guest VSS), **transport** (remote unreachable), **storage-full**, unknown.\n2. `xcpng-aiops backup logs -n 20` → the raw recent runs behind that classification.\n3. `xcpng-aiops sr usage-rca` → SRs ranked by physical fullness, thin-provision overcommit, and **orphaned VDIs** (attached to no VM) with reclaimable bytes per SR.\n4. `xcpng-aiops sr vdis --sr --orphaned-only` → the specific orphaned VDIs worth reclaiming on that SR.\n5. For a **vdi-chain** classification: let the coalesce finish, stop stacking snapshots (`xcpng-aiops snapshot list`), then `xcpng-aiops sr rescan --dry-run` and for real (lowest-impact write) so XO re-reads the SR.\n6. For **storage-full**: reclaim space, then re-run `sr usage-rca` to confirm the SR dropped below the near-full threshold.\n7. `xcpng-aiops backup logs -n 20` after the next scheduled run to confirm it went green.\n\n**Failure branch**: a **transport** classification is not an XCP-ng problem — the backup remote is unreachable, so fix the remote in the XO UI (Settings → Remotes); rescanning the SR will not help. A **quiesce** classification means the guest agent could not freeze the filesystem: fix guest tools on that VM rather than disabling quiesce fleet-wide. If `sr rescan` does not shrink the chain, the coalesce is still running — wait rather than rescanning in a loop, which will trip the runaway budget guard.\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 (29 — 19 read, 8 write, 2 undo)\n\n| Category | Tools | R/W |\n|----------|-------|:---:|\n| Overview | `overview` | Read |\n| VMs | `vm_list`, `vm_get`, `vm_stats`, `vm_health_rca` | Read |\n| | `vm_start`, `vm_stop`, `vm_reboot`, `vm_migrate` | Write |\n| Hosts | `host_list`, `host_get` | Read |\n| Pools | `pool_list`, `pool_get`, `pool_patch_ha_posture` | Read |\n| SRs / VDIs | `sr_list`, `sr_get`, `vdi_list`, `sr_usage_rca` | Read |\n| | `sr_rescan` | Write |\n| Snapshots | `snapshot_list` | Read |\n| | `snapshot_create`, `snapshot_delete`, `snapshot_revert` | Write |\n| Backups | `backup_job_list`, `backup_log_list`, `backup_failure_rca` | Read |\n| Tasks | `task_list` | Read |\n| Undo | `undo_list`, `undo_apply` | Read + replay |\n\n**Harness features that light up**: `vm_start`↔`vm_stop` record each other as inverses (with `_undo_id`); `vm_migrate` captures the REAL source host BEFORE moving and records \"migrate back\"; `snapshot_create` captures the REAL snapshot id from the XO response and records \"delete THAT snapshot\". `snapshot_delete` and `snapshot_revert` are `risk_level=high`, capture BEFORE state, and declare no undo (irreversible). Every write takes `dry_run=True` (may read, never writes; no undo; audited). All 29 tools are audit-logged under `~/.xcpng-aiops/` and pass through the budget/runaway guard, each carrying a descriptive risk tier into its audit row. Start any triage with `overview`.\n\n## CLI Quick Reference\n\n```bash\nxcpng-aiops init # onboarding wizard (encrypted XO token)\nxcpng-aiops overview [--target ] # fleet health summary\nxcpng-aiops vm list [--state Running] [--pool ]\nxcpng-aiops vm get \nxcpng-aiops vm stats [-g minutes]\nxcpng-aiops vm health-rca [] # RCA: cause + action\nxcpng-aiops vm start [--dry-run]\nxcpng-aiops vm stop [--force] [--dry-run] # double confirm; refuses the declared XO VM\nxcpng-aiops vm reboot [--force] [--dry-run] # double confirm\nxcpng-aiops vm migrate [--dry-run] # double confirm\nxcpng-aiops host list / get / missing-patches \nxcpng-aiops pool list / get \nxcpng-aiops pool posture [] # RCA: patches / reboots / skew / HA\nxcpng-aiops sr list / get \nxcpng-aiops sr vdis [--sr ] [--orphaned-only]\nxcpng-aiops sr usage-rca # RCA: near-full / overcommit / orphans\nxcpng-aiops sr rescan [--dry-run]\nxcpng-aiops snapshot list [--vm ]\nxcpng-aiops snapshot create [--dry-run]\nxcpng-aiops snapshot delete [--dry-run] # double confirm, IRREVERSIBLE\nxcpng-aiops snapshot revert [--dry-run] # double confirm, IRREVERSIBLE\nxcpng-aiops backup jobs / logs [-n 50]\nxcpng-aiops backup failure-rca [-n 50] # RCA: vdi-chain / quiesce / transport\nxcpng-aiops task list [--status failure]\nxcpng-aiops secret set / list / rm / migrate / rotate-password\nxcpng-aiops doctor # XO reachability + token + pool count\nxcpng-aiops mcp # start MCP server (stdio)\n```\n\nSee `references/cli-reference.md` for the full command list, and\n`references/agent-guardrails.md` when driving these tools with a smaller /\nlocal model (the guardrails the tool enforces for you, and a ready system prompt).\n\n## Troubleshooting\n\n### \"Config file not found\"\nRun `xcpng-aiops init` to set up your first target (writes `~/.xcpng-aiops/config.yaml` and stores the XO token encrypted).\n\n### \"No XO authentication token for target ''\"\nAdd it to the encrypted store: `xcpng-aiops secret set ` (prompts hidden), or run `xcpng-aiops init`. Create the token in the XO UI (user menu → Personal tokens) or with `xo-cli --createToken`. For non-interactive use (MCP/CI), also export `XCPNG_AIOPS_MASTER_PASSWORD` so the store can be unlocked without a prompt.\n\n### \"Master password not set\" / \"Wrong master password\"\nThe encrypted store `~/.xcpng-aiops/secrets.enc` is unlocked by `XCPNG_AIOPS_MASTER_PASSWORD` (or an interactive prompt). If you forgot it, delete `secrets.enc` and re-run `xcpng-aiops init`. Rotate it with `xcpng-aiops secret rotate-password`.\n\n### \"Authentication/authorization failed (401/403)\"\nThe XO token is wrong, expired, or revoked, or the XO account lacks permission. Regenerate the token in the XO UI (user menu → Personal tokens) and update it: `xcpng-aiops secret set `.\n\n### \"Could not reach Xen Orchestra … check the XO URL\"\nConfirm the XO web UI is reachable at the configured `url` and that `api_path` is `/rest/v0` (XO 5.x). For self-signed certificates set `verify_ssl: false` on the target (lab only).\n\n### \"Resource not found (404)\"\nThe VM/SR/snapshot uuid is stale, or this XO release lacks the endpoint. List the parent collection first (`vm list`, `sr list`, `snapshot list`) to get a current uuid.\n\n### Doctor says \"manages no pools yet\"\nYour XO instance is reachable but has no XCP-ng servers connected — add them in the XO UI (Settings → Servers).\n\n## Audit & Safety\n\nThe skill delivers reads and writes and records them; it does **not** decide\nwhether a write is permitted. That is your agent's judgement, or the permission\nof the Xen Orchestra account whose token you connect it with (give that XO user\na read-only ACL or scope its token down — writes then fail at Xen Orchestra).\nThere 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 `~/.xcpng-aiops/audit.db` (relocatable via `XCPNG_AIOPS_HOME`): params (secrets redacted), result, status, duration, and the risk tier. The CLI writes the same row the MCP path does.\n- The XO token is stored **encrypted** in `~/.xcpng-aiops/secrets.enc` (Fernet/AES-128 + scrypt key derivation; chmod 600) — never plaintext on disk; the master password is never stored, only a per-store salt + ciphertext.\n- `XCPNG_AUDIT_APPROVED_BY` / `XCPNG_AUDIT_RATIONALE` are optional annotations recorded on the audit row (who/why); they are never required and never block.\n- **Budget / runaway guard** — a safety backstop, not authorization: caps cumulative tool calls and wall-time, and trips on tight task-poll loops.\n- Writes support `--dry-run` / `dry_run=True` and double confirmation at the CLI; CLI writes execute through the same governed tools, so they are audited + undo-recorded.\n- Reversible writes (`vm_start`/`vm_stop`/`vm_migrate`/`snapshot_create`) capture the real before-state and record a replayable inverse descriptor; `snapshot_delete`/`snapshot_revert` are `risk=high`, irreversible, and declare no undo.\n- **Risk tier** is a descriptive label on the audit row derived from `risk_level`; it gates nothing.\n\nThe harness is bundled in the package — no external dependency, no manual setup. See `references/setup-guide.md` for security details.\n\n## Contributing & feature requests\n\nCoverage is intentionally focused. **Missing a capability you need, or hit an endpoint that differs on your Xen Orchestra version?** Open an issue or pull request at [github.com/AIops-tools/XCPng-AIops](https://github.com/AIops-tools/XCPng-AIops/issues) — feature requests, contributions, and comments are all welcome.\n\n## License\n\nMIT — [github.com/AIops-tools/XCPng-AIops](https://github.com/AIops-tools/XCPng-AIops)\n\nFile v0.8.4:_meta.json\n\n{\n \"ownerId\": \"kn7b067awq2s97bn3d7p5qfhw5827pxc\",\n \"slug\": \"xcpng-aiops\",\n \"version\": \"0.8.4\",\n \"publishedAt\": 1789535956634\n}\n\nFile v0.8.4:references/agent-guardrails.md\n\n# Agent guardrails — running xcpng-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## Authorization is not this tool's job — decide it where it belongs\n\nWhether a write should happen is your decision, or the account's. The tool does\nnot gate it — there is no read-only switch and no approval prompt to configure.\nThe two right places to control read vs write:\n\n- **The Xen Orchestra account whose token you connect with.** Give that XO user\n a read-only ACL, or scope its personal token down. A write then fails at Xen\n Orchestra, which is the only place the permission actually lives — a revoked\n permission cannot be argued around by a model, but a skill-side flag can.\n- **Your agent's system prompt.** If you want an observe-only session, tell the\n model not to call the write tools (they are clearly tagged `[WRITE]`).\n\nWhat the tool *does* guarantee is that you can always see what happened:\n\n## What the tool 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 Xen Orchestra did not return comes back as `null`, never as `\"\"`. A VM with no `name_label`, a task with no `properties.name`, an SR with no `content_type` — all report `null`. Absent and empty are distinguishable in the payload. |\n| \"Tell me if the output was cut off\" | Every listing returns `{\"vms\": [...], \"returned\": N, \"limit\": L, \"truncated\": true/false}` (same shape with `srs`, `vdis`, `snapshots`, `tasks`, `jobs`, `logs`, `undos`). Truncation is **measured** — the full collection length client-side, or one over-fetched record for `backup_log_list` — never guessed from the row count matching the limit. The RCA tools report `inputTruncated` when the listing they correlated over was itself capped. |\n| \"Preserve the ordering / tell me what's most urgent\" | RCA findings carry an explicit `severity` (`high`/`medium`/`low`) and are already sorted worst-first, each with the measured number in `evidence` and a concrete `action`. Priority is in the payload, not implied by list position. |\n| \"Confirm before anything destructive\" | Destructive operations (`snapshot_delete`, `snapshot_revert`, `vm_stop`/`reboot`/`migrate`) require a `dry_run` preview + double confirmation at the CLI. Reversible writes capture the prior state so the undo token can restore it. |\n| \"Never stop the Xen Orchestra VM itself\" | **Only if the operator declared it.** Set `xo_self_vm_uuid` on the target and `vm_stop` refuses exactly that uuid on both the MCP and CLI paths. Undeclared, nothing is refused — XO exposes no self endpoint and its token carries no claims, so the tool cannot work this out and fails open rather than guess. Keep a prompt line for this if you cannot declare the uuid. |\n| \"Log what you did\" | Every governed call is audited to `~/.xcpng-aiops/audit.db` regardless of what the model says it did — and the CLI writes the same row the MCP path does, so there is no unaudited entry point. |\n| \"Don't get stuck retrying\" | The runaway guard trips a circuit breaker if the same call is hammered in a tight loop — a stuck agent is stopped rather than left to burn calls and time. |\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 an XCP-ng environment through the xcpng-aiops MCP tools. They talk\nto Xen Orchestra's REST API; there is no direct per-host XAPI access.\n\nTOOL USE\n- Before answering any question about the current XCP-ng 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- Start broad triage with \"overview\" — it fans out over pools, hosts, VMs, SRs\n and recent backup runs in one call.\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- Listings come back as an envelope, not a bare list: read the items under\n \"vms\" / \"srs\" / \"vdis\" / \"snapshots\" / \"tasks\" / \"jobs\" / \"logs\".\n- If \"truncated\" is true, say so and re-run with a higher limit instead of\n treating the partial result as complete. If an RCA reports \"inputTruncated\",\n its conclusion covers only a subset — state that.\n- A null field means Xen Orchestra 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 power states, SR types, statuses, or uuids.\n- When an RCA result has findings, work in the order given (worst first) and\n cite the measured number in each finding's \"evidence\".\n\nIDENTIFIERS\n- Every object is addressed by its XO uuid: a VM uuid (vm_list), a host uuid\n (host_list), a pool uuid (pool_list), an SR uuid (sr_list), a VDI uuid\n (vdi_list), a snapshot uuid (snapshot_list). They are NOT interchangeable —\n do not pass a host uuid where a VM uuid is expected.\n- A name_label is a label, not an identifier: it is not unique and must never\n be used in place of a uuid. Resolve the name to a uuid with a list tool first.\n- An XO task id (task_list) identifies an async job, not the object it acted on.\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```\n\n## Recommended setup for a local model\n\nStart with a connection that *cannot* write, verify, and widen the account's\npermission only when you trust the setup — snapshot delete/revert are\nirreversible, and stopping the wrong VM can be the one XO itself runs on:\n\n```bash\n# Give the Xen Orchestra account a read-only ACL, or scope its personal token\n# down, so writes fail at XO rather than depending on a skill-side flag. Then:\nxcpng-aiops doctor\n```\n\nOptionally annotate the audit trail with who is operating and why — recorded on\nevery row, never required:\n\n```bash\nexport XCPNG_AUDIT_APPROVED_BY=\"your.name@example.com\"\nexport XCPNG_AUDIT_RATIONALE=\"scheduled maintenance window 2026-07-20\"\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 `overview` and the four RCA\n tools (`vm_health_rca`, `sr_usage_rca`, `backup_failure_rca`,\n `pool_patch_ha_posture`) — they do the multi-step correlation inside one call,\n so the model does not have to chain reads and keep uuids straight.\n- **The model ignores later tool results in a long context.** Ask narrower\n questions and use `limit` (plus the `pool` / `sr` / `power_state` / `status`\n filters) deliberately rather than pulling whole inventories. `vdi_list` in\n particular is the longest listing in a real fleet.\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/XCPng-AIops](https://github.com/AIops-tools/XCPng-AIops/issues)\nwith the model, runtime, and what went wrong.\n\nFile v0.8.4:references/capabilities.md\n\n# xcpng-aiops — Capabilities (29 MCP tools: 19 read, 8 write, 2 undo)\n\nAll tools go through the bundled `@governed_tool` harness (audit / policy /\nbudget / undo / risk-tier). XO object ids are uuids; get them from the matching\n`*_list` tool first. Every tool takes an optional `target` (XO target name\nfrom config; omit for the default).\n\n**Listing envelopes.** `vm_list`, `sr_list`, `vdi_list`, `snapshot_list`,\n`task_list`, `backup_job_list`, `backup_log_list` and `undo_list` return\n`{: [...], \"returned\": N, \"limit\": L, \"truncated\": bool}` — read the\nitems under the named key (`vms`, `srs`, `vdis`, `snapshots`, `tasks`, `jobs`,\n`logs`, `undos`). `truncated` is measured, not guessed: filters run first, the\ncap after, and `backup_log_list` over-fetches one record. When it is true,\nre-run with a higher `limit`. The RCA tools report `inputTruncated` when the\nlisting they correlated over was itself capped.\n\n**Absent vs empty.** A field XO did not return is `null`, never `\"\"` — do not\ninfer a value for it.\n\n**Authorization.** The tool records; it does not gate. Whether a write may run\nis the agent's decision or the connecting Xen Orchestra account's permissions —\nthere is no read-only switch or approval gate. See `agent-guardrails.md`.\n\n## Overview\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `overview` | low | One-shot fleet health: pools, hosts (disabled / reboot-required / versions), VMs by power state + running-without-tools, SRs near full, recent backup failures. Start any triage here. |\n\n## VMs\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `vm_list(power_state?, pool?, limit?)` | low | VMs with power state, host, guest-tools status, sizing. |\n| `vm_get(vm_id)` | low | One VM: state, host, OS, tools, tags, start time. |\n| `vm_stats(vm_id, granularity?)` | low | Recent RRD averages: cpuAvgPercent, memoryUsedPercent. |\n| `vm_health_rca(vm_id?)` | low | **RCA**: halted-unexpectedly (auto-poweron/HA set), paused, suspended, guest-tools-missing, cpu-pressure (≥90%), memory-pressure (≥90%). Cause + severity + evidence + action per finding. Fleet mode caps stats pulls at 5 running VMs. |\n| `vm_start(vm_id, dry_run?)` | medium | Start a VM. **Undo: vm_stop** (recorded). |\n| `vm_stop(vm_id, force?, dry_run?)` | medium | Clean shutdown (hard with force). **Undo: vm_start** — only recorded if the VM was Running before. Refuses the VM declared as running XO (`xo_self_vm_uuid` on the target); with none declared there is **no** such guard — XO has no self endpoint, so it fails open rather than guess. `dry_run` refuses the declared uuid too, and returns `selfVmHint` (a possible IP coincidence, never a verdict, never a block — on either path). |\n| `vm_reboot(vm_id, force?, dry_run?)` | medium | Clean/hard reboot. Prior power state captured; **no undo**. |\n| `vm_migrate(vm_id, host_id, dry_run?)` | medium | Live-migrate. Captures the REAL source host before moving; **undo: migrate back to it**. |\n\n## Hosts\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `host_list(pool?)` | low | Hosts: version, enabled, reboot-required, memory %, resident VMs. |\n| `host_get(host_id)` | low | One host: version, build, memory, tags. |\n\n## Pools\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `pool_list()` | low | Pools with master, HA state, default SR. |\n| `pool_get(pool_id)` | low | One pool detail. |\n| `pool_patch_ha_posture(pool_id?)` | low | **RCA**: patches-missing, reboot-required, version-skew (high — breaks live migration), ha-disabled. Per-host rows + per-pool findings. |\n\n## SRs / VDIs\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `sr_list(pool?, limit?)` | low | SRs: capacity, physical usage %, virtual allocation. |\n| `sr_get(sr_id)` | low | One SR detail. |\n| `vdi_list(sr?, orphaned_only?, limit?)` | low | VDIs; `orphaned_only=true` → disks attached to no VM (reclaim candidates). |\n| `sr_usage_rca()` | low | **RCA**: sr-critical (≥95%), sr-near-full (≥85%), sr-overcommitted (allocation > capacity), orphaned-vdis with reclaimable bytes per SR. ISO SRs excluded. |\n| `sr_rescan(sr_id, dry_run?)` | medium | Metadata refresh; no data change, no undo. Lowest-impact write, but still a write. |\n\n## Snapshots\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `snapshot_list(vm_id?, limit?)` | low | VM snapshots with time and parent VM. |\n| `snapshot_create(vm_id, name, dry_run?)` | medium | Snapshot a VM. Captures the REAL new snapshot id from XO's response; **undo: delete THAT snapshot**. |\n| `snapshot_delete(snapshot_id, dry_run?)` | **high** | IRREVERSIBLE. Captures BEFORE state (name/time/VM); no undo. |\n| `snapshot_revert(snapshot_id, dry_run?)` | **high** | IRREVERSIBLE — replaces the VM's current state. Captures snapshot state; no undo. Take a fresh snapshot first. |\n\n## Backups\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `backup_job_list(limit?)` | low | VM backup jobs (id, name, mode). |\n| `backup_log_list(limit?)` | low | Recent run logs: status + failed-task messages. |\n| `backup_failure_rca(limit?)` | low | **RCA**: failures per job classified — vdi-chain (coalesce), quiesce (guest VSS), transport (remote unreachable), storage-full, unknown. Counts + sample findings + action per class. |\n\n## Tasks\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `task_list(status?, limit?)` | low | XO tasks (pending / success / failure). |\n\n## Write semantics\n\n- `dry_run=true` → preview dict (`{\"dryRun\": true, \"would...\": {...}}`). A dry-run **may\n read** — resolving ids and evaluating guards is what lets it tell you the call would be\n refused — but **never writes** and records **no undo**. It runs through `@governed_tool`\n like any other call, so it is audited and it can be refused. The CLI `--dry-run` routes\n through the same governed function, so both entry points behave identically.\n- Successful reversible writes return `_undo_id` referencing the recorded inverse descriptor in `~/.xcpng-aiops/undo.db`. Undo execution is an external orchestrator's job — recording only.\n- High-risk tools (`snapshot_delete`, `snapshot_revert`) require a `dry_run` preview + double confirmation at the CLI. `XCPNG_AUDIT_APPROVED_BY` / `XCPNG_AUDIT_RATIONALE` are optional annotations recorded on the audit row — never required, never blocking.\n\nFile v0.8.4:references/cli-reference.md\n\n# xcpng-aiops — CLI reference\n\nGlobal pattern: `xcpng-aiops [args] [--target ]`.\n`--target/-t` selects a Xen Orchestra target from `~/.xcpng-aiops/config.yaml`\n(default: the first one). Write commands support `--dry-run` (prints the API\ncall, changes nothing) and destructive ones require **double confirmation**.\n\n## Setup & health\n\n```bash\nxcpng-aiops init # onboarding wizard: XO URL, TLS verify (default yes), encrypted token\nxcpng-aiops doctor [--skip-auth] # config + secret store + XO reachability + pool count\nxcpng-aiops overview [-t xo1] # one-shot fleet health summary (JSON)\nxcpng-aiops mcp # start the MCP server (stdio)\n```\n\n## VMs\n\n```bash\nxcpng-aiops vm list [--state Running|Halted|Paused|Suspended] [--pool ] [--limit 200]\nxcpng-aiops vm get \nxcpng-aiops vm stats [--granularity seconds|minutes|hours|days]\nxcpng-aiops vm health-rca [] # RCA (fleet-wide when uuid omitted)\nxcpng-aiops vm start [--dry-run] # governed; undo = stop\nxcpng-aiops vm stop [--force] [--dry-run] # double confirm; undo = start\nxcpng-aiops vm reboot [--force] [--dry-run] # double confirm; no undo\nxcpng-aiops vm migrate [--dry-run] # double confirm; undo = migrate back\n```\n\n`--force` = hard power operation (no guest tools needed); default is a clean\nguest shutdown/reboot.\n\n## Hosts\n\n```bash\nxcpng-aiops host list [--pool ]\nxcpng-aiops host get \nxcpng-aiops host missing-patches \n```\n\n## Pools\n\n```bash\nxcpng-aiops pool list\nxcpng-aiops pool get \nxcpng-aiops pool posture [] # RCA: patches / reboots / version skew / HA\n```\n\n## Storage (SRs / VDIs)\n\n```bash\nxcpng-aiops sr list [--pool ] [--limit 200]\nxcpng-aiops sr get \nxcpng-aiops sr vdis [--sr ] [--orphaned-only] [--limit 200]\nxcpng-aiops sr usage-rca # RCA: near-full / overcommit / orphaned VDIs\nxcpng-aiops sr rescan [--dry-run]\n```\n\n## Snapshots\n\n```bash\nxcpng-aiops snapshot list [--vm ] [--limit 200]\nxcpng-aiops snapshot create [--dry-run]\nxcpng-aiops snapshot delete [--dry-run] # double confirm, IRREVERSIBLE\nxcpng-aiops snapshot revert [--dry-run] # double confirm, IRREVERSIBLE\n```\n\n## Backups & tasks\n\n```bash\nxcpng-aiops backup jobs [--limit 200]\nxcpng-aiops backup logs [--limit 50]\nxcpng-aiops backup failure-rca [--limit 50] # RCA: vdi-chain / quiesce / transport / storage-full\nxcpng-aiops task list [--status pending|success|failure] [--limit 200]\n```\n\n## Secrets (encrypted store)\n\n```bash\nxcpng-aiops secret set [--value ] # omit --value to be prompted (hidden)\nxcpng-aiops secret list # names only\nxcpng-aiops secret rm \nxcpng-aiops secret migrate # import legacy plaintext .env\nxcpng-aiops secret rotate-password # re-encrypt under a new master password\n```\n\n## Environment variables\n\n| Variable | Purpose |\n|----------|---------|\n| `XCPNG_AIOPS_MASTER_PASSWORD` | Unlock `secrets.enc` non-interactively (MCP/CI). |\n| `XCPNG_AIOPS_HOME` | Relocate `~/.xcpng-aiops` (audit.db, undo.db). |\n| `XCPNG_AIOPS_CONFIG` | Alternate config.yaml path for the MCP server. |\n| `XCPNG_AUDIT_APPROVED_BY` / `XCPNG_AUDIT_RATIONALE` | Optional approver/rationale annotations recorded on the audit row (never required). |\n| `XCPNG_MAX_TOOL_CALLS` / `XCPNG_MAX_TOOL_SECONDS` | Budget ceilings. |\n| `XCPNG_RUNAWAY_MAX` / `XCPNG_RUNAWAY_WINDOW_SEC` | Runaway-loop circuit breaker. |\n| `XCPNG__TOKEN` | Legacy plaintext token fallback (deprecated). |\n\n## Truncation\n\nListing commands cap their output at `--limit` (default 200) and print\n`… showing N of more … — truncated, re-run with a higher --limit` when there\nwas more; the JSON itself carries `\"truncated\": true`.\n\nFile v0.8.4:references/setup-guide.md\n\n# xcpng-aiops — Setup & security guide\n\n## Prerequisites\n\n- A **Xen Orchestra instance** (XO from sources or the Xen Orchestra\n Appliance, 5.x) with the REST API at `/rest/v0`. XO is the management plane\n this tool talks to; your XCP-ng hosts/pools must already be connected to it\n (XO UI → Settings → Servers). **Per-host XAPI access is out of scope.**\n- Python ≥ 3.11 (`uv tool install xcpng-aiops` handles the rest).\n\n## 1. Create an XO authentication token\n\nIn the XO UI: user menu (top-right) → **Personal tokens** → create. Or from a\nshell: `xo-cli --createToken`. Use a dedicated XO user with the least\nprivilege you can (admin is required for some collections; a read-mostly user\nworks for triage-only setups).\n\n## 2. Onboard\n\n```bash\nxcpng-aiops init\n```\n\nThe wizard prompts for:\n\n1. **Master password** — encrypts `~/.xcpng-aiops/secrets.enc`. Never stored;\n export `XCPNG_AIOPS_MASTER_PASSWORD` for non-interactive use.\n2. **Target name** (e.g. `xo1`) and the **XO URL** (e.g.\n `https://xo.example.com` — the same origin as the XO web UI).\n3. **TLS verification** — default **yes**; answer no only for self-signed lab\n certificates.\n4. **The token** (hidden input) — stored encrypted, never in config.yaml.\n\n## 3. Verify\n\n```bash\nxcpng-aiops doctor\n```\n\nChecks: config present, encrypted store present + permissions (600), token\npresent per target, XO reachable, token valid (a 401/403 fails the check), and\nhow many XCP-ng pools the XO instance manages.\n\n## Files & permissions\n\n| Path | Content | Mode |\n|------|---------|:----:|\n| `~/.xcpng-aiops/config.yaml` | non-secret connection details | 700 dir |\n| `~/.xcpng-aiops/secrets.enc` | Fernet-encrypted token map | 600 |\n| `~/.xcpng-aiops/audit.db` | SQLite audit log (every tool call) | — |\n| `~/.xcpng-aiops/undo.db` | recorded inverse descriptors | — |\n\nRelocate everything with `XCPNG_AIOPS_HOME`.\n\n## Security notes\n\n- The token is sent per request as `Authorization: Bearer ` **and**\n `Cookie: authenticationToken=` (compatibility across XO 5.x\n releases); held in memory only, never logged.\n- Secret encryption: Fernet (AES-128-CBC + HMAC-SHA256), key derived from the\n master password via scrypt (N=2^15, r=8, p=1) with a random per-store salt.\n- High-risk writes (`snapshot_delete`, `snapshot_revert`) require a `dry_run`\n preview + double confirmation at the CLI, and carry a `high` risk tier as a\n descriptive audit label — it gates nothing. `XCPNG_AUDIT_APPROVED_BY` /\n `XCPNG_AUDIT_RATIONALE` are optional annotations recorded on the audit row,\n never required.\n- Budget guard: `XCPNG_MAX_TOOL_CALLS` (default ceiling on calls per process)\n and `XCPNG_MAX_TOOL_SECONDS` (cumulative wall-time), plus a runaway breaker\n for tight poll loops.\n- No outbound traffic except the configured XO endpoint. No telemetry.\n\n## MCP client setup\n\n```json\n{\n \"mcpServers\": {\n \"xcpng-aiops\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"xcpng-aiops\", \"xcpng-aiops-mcp\"],\n \"env\": { \"XCPNG_AIOPS_MASTER_PASSWORD\": \"your-master-password\" }\n }\n }\n}\n```\n\nMCP clients do **not** inherit your shell environment — the master password\n(and any `XCPNG_*` overrides) must be in the `env` block.\n\nFile v0.8.4:skill-card.md\n\n## Description:\n\nxcpng-aiops helps agents inspect and operate XCP-ng fleets through Xen Orchestra, covering fleet health, VM, host, pool, storage, snapshot, backup, and task views plus RCA workflows and governed writes.\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 triage and operate XCP-ng environments managed by Xen Orchestra. It is intended for fleet health checks, VM and storage RCA, backup failure analysis, patch and HA posture review, and guarded operational changes.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill may run external package code with Xen Orchestra credentials.\n\nMitigation: Pin and verify the xcpng-aiops package where possible, run it under a dedicated local account, and connect with a least-privilege XO user until write access is explicitly needed.\n\nRisk: VM, migration, and snapshot write actions can affect a live XCP-ng fleet, and snapshot delete or revert actions are irreversible.\n\nMitigation: Start from read-only XO permissions for triage, require operator review before writes, use dry-run previews, and rely on CLI double confirmation for destructive actions.\n\nRisk: XO tokens and the master password can be exposed if placed in command lines or persistent configuration files.\n\nMitigation: Use the encrypted secret store, keep secrets out of command arguments and durable config, and provide the master password only through controlled runtime environment handling.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/zw008/skills/xcpng-aiops)\n- [Project homepage](https://github.com/AIops-tools/XCPng-AIops)\n- [xcpng-aiops - Capabilities](references/capabilities.md)\n- [xcpng-aiops - Setup & security guide](references/setup-guide.md)\n- [xcpng-aiops - CLI reference](references/cli-reference.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 and structured command guidance, with JSON returned by CLI and MCP operations]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May produce dry-run previews, RCA findings, audit-oriented guidance, and configuration snippets for Xen Orchestra connectivity.]\n\n## Skill Version(s):\n\n0.8.4 (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.8.3: 7 files, 21099 bytes\n\nFiles: references/agent-guardrails.md (7975b), references/capabilities.md (6380b), references/cli-reference.md (4010b), references/setup-guide.md (3226b), skill-card.md (2608b), SKILL.md (21953b), _meta.json (130b)\n\nFile v0.8.3:SKILL.md\n\n---\nname: xcpng-aiops\nslug: xcpng-aiops\ndisplayName: \"XCP-ng AIops\"\nsummary: \"Governed XCP-ng ops via Xen Orchestra — 29 MCP tools with audit, budget, undo guards.\"\nlicense: MIT\nhomepage: https://github.com/AIops-tools/XCPng-AIops\ntags: [aiops, mcp, governance, xcpng]\ndescription: >\n Use this skill whenever the user needs to operate an XCP-ng virtualization fleet through Xen Orchestra — a one-shot fleet health overview; VMs (list/get/RRD stats), hosts, pools, storage repositories (SRs) and VDIs, VM snapshots, backup jobs and run logs, XO tasks; four RCA analyses (VM health, SR usage, backup-job failures, pool patch & HA posture); and governed writes (VM start/stop/reboot/migrate, snapshot create/delete/revert, SR rescan).\n Always use this skill for \"xcp-ng vm\", \"xen orchestra\", \"xo backup failed\", \"sr full\", \"orphaned vdi\", \"xcp-ng snapshot\", \"migrate vm to another host\", \"xcp-ng patches\", or \"pool HA\" when the context is explicitly XCP-ng / Xen Orchestra / a Xen-based fleet.\n Do NOT use when the target is not an XCP-ng fleet managed by Xen Orchestra — other hypervisors (Do NOT use for Proxmox VE — use proxmox-aiops), NAS/storage appliances, backup software suites, container clusters, and network devices are out of scope (negative routing hints only).\n Common XCP-ng-via-XO operations with a built-in governance harness (audit, policy, token budget, undo, risk-tiers).\ninstaller:\n kind: uv\n package: xcpng-aiops\nargument-hint: \"[vm/sr/snapshot uuid or describe your XCP-ng task]\"\nallowed-tools:\n - Bash\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"xcpng-aiops\",\"uvx\"]},\"optional\":{\"env\":[\"XCPNG_AIOPS_CONFIG\",\"XCPNG_AIOPS_MASTER_PASSWORD\"]},\"homepage\":\"https://github.com/AIops-tools/XCPng-AIops\",\"emoji\":\"🖥️\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n Standalone, self-governed XCP-ng operations via Xen Orchestra's REST API /rest/v0. REQUIRES a Xen Orchestra instance (XO from sources or the Xen Orchestra Appliance, 5.x) — XO is the management plane; direct per-host XAPI access is out of scope for v0.1. The governance harness (audit, policy, token/runaway budget, undo, risk-tiers) is bundled in the package — no external skill-family dependency.\n All write operations are audited to a local SQLite DB under ~/.xcpng-aiops/ (relocatable via XCPNG_AIOPS_HOME).\n Credentials: Each XO target's personal authentication token is stored ENCRYPTED in ~/.xcpng-aiops/secrets.enc (Fernet/AES-128 + scrypt-derived key) — never plaintext on disk. Run 'xcpng-aiops init' to onboard, or 'xcpng-aiops secret set ' to add one (create the token in the XO UI: user menu → Personal tokens, or `xo-cli --createToken`). The store is unlocked by a master password from XCPNG_AIOPS_MASTER_PASSWORD (non-interactive/MCP/CI) or an interactive prompt (CLI on a TTY). A legacy plaintext env var XCPNG__TOKEN is still honoured as a fallback with a deprecation warning (migrate with 'xcpng-aiops secret migrate'). The token is sent in headers (Authorization: Bearer + authenticationToken cookie) at request time and held only in memory; tokens are never logged or echoed.\n Destructive operations (snapshot delete/revert, vm stop/reboot/migrate) require double confirmation at the CLI layer and support --dry-run; every write MCP tool takes a dry_run preview. A dry_run MAY read (that is how it can tell you the call would be refused) but never writes, records no undo, and is audited like any other governed call. All write tools pass through the @governed_tool decorator (budget guard + audit + risk-tier labelling). vm_start↔vm_stop record each other as inverses; vm_migrate records migrating back to the captured source host; snapshot_create records deleting the REAL snapshot id XO returned; snapshot_delete and snapshot_revert are high-risk and irreversible (capture BEFORE state, record no undo). vm_stop refuses the VM declared as running Xen Orchestra (xo_self_vm_uuid on the target) because stopping XO removes the API vm_start would travel over; that guard is opt-in and fails open when undeclared, since XO's REST API exposes no self endpoint.\n Webhooks: none — no outbound network calls beyond the configured Xen Orchestra REST API endpoint.\n SSL: verify_ssl defaults to true; disable only for self-signed lab certificates.\n Transitive dependencies: httpx (HTTP client) and the MCP SDK. No post-install scripts or background services.\n Verification status: mock-validated; no recorded end-to-end run against a live Xen Orchestra instance yet. Endpoint paths are modelled against the documented Xen Orchestra REST /rest/v0 API and need live verification — action names may differ across XO releases. See docs/VERIFICATION.md.\n---\n\n# XCP-ng AIops\n\n> **Disclaimer**: This is a community-maintained open-source project and is **not affiliated with, endorsed by, or sponsored by Vates, the XCP-ng project, or the Xen Orchestra project.** \"XCP-ng\", \"Xen Orchestra\", and \"Xen\" are trademarks of their owners. Source code is publicly auditable at [github.com/AIops-tools/XCPng-AIops](https://github.com/AIops-tools/XCPng-AIops) under the MIT license.\n\nGoverned XCP-ng operations via **Xen Orchestra's REST API** — **29 MCP tools**, every one wrapped with the bundled `@governed_tool` harness: a local unified audit log under `~/.xcpng-aiops/`, policy engine, token/runaway budget guard, undo-token recording, and descriptive risk tiers. The XO authentication token is stored **encrypted** (`~/.xcpng-aiops/secrets.enc`, Fernet + scrypt) — never plaintext on disk.\n\n> **Requires a Xen Orchestra instance** (5.x with `/rest/v0`) — XO is the management plane; per-host XAPI is out of scope for v0.1. **Standalone**: the governance harness is bundled in the package (`xcpng_aiops.governance`) — xcpng-aiops has no external skill-family dependency. Coverage is common operations, not exhaustive; verification status and the live-run checklist are in `docs/VERIFICATION.md`.\n\n## What This Skill Does\n\n| Category | Tools | Count | Read or Write |\n|----------|-------|:-----:|:-------------:|\n| **Overview** | fleet health overview | 1 | 1 read |\n| **VMs** | list, get, RRD stats, health RCA | 4 | 4 read |\n| | start, stop, reboot, migrate | 4 | 4 write (medium) |\n| **Hosts** | list, get | 2 | 2 read |\n| **Pools** | list, get, patch & HA posture RCA | 3 | 3 read |\n| **SRs / VDIs** | list, get, VDI list (orphan filter), usage RCA | 4 | 4 read |\n| | rescan | 1 | 1 write (medium) |\n| **Snapshots** | list | 1 | 1 read |\n| | create (medium), delete (high), revert (high) | 3 | 3 write |\n| **Backups** | jobs, run logs, failure RCA | 3 | 3 read |\n| **Tasks** | list | 1 | 1 read |\n\n## Quick Install\n\n```bash\nuv tool install xcpng-aiops\nxcpng-aiops init # interactive wizard: XO URL + encrypted token\nxcpng-aiops doctor # XO reachability + token validity + pool count\n```\n\nOr as an OpenClaw plugin, which installs this skill and its MCP server together:\n\n```bash\nopenclaw plugins install clawhub:@zw008/xcpng-aiops\nopenclaw skills info xcpng-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- Triage an XCP-ng fleet (`overview`): pools, hosts, VMs by state, SRs near full, recent backup failures\n- Root-cause an unhealthy VM (`vm health-rca`): halted unexpectedly, paused, guest tools missing, CPU/memory pressure\n- Root-cause storage pressure (`sr usage-rca`): SRs ranked near-full, thin-provision overcommit, orphaned VDIs with reclaimable bytes\n- Root-cause backup failures (`backup failure-rca`): vdi-chain / quiesce / transport / storage-full classification\n- Check patch & HA posture (`pool posture`): missing patches, pending reboots, version skew, HA state\n- Snapshot a VM before a risky change; start/stop/reboot/migrate VMs under governance\n\n**Do NOT use when** the target is not an XCP-ng fleet managed by Xen Orchestra — other hypervisors (Do NOT use for Proxmox VE — use proxmox-aiops), NAS/storage appliances, backup software suites, Kubernetes/containers, and network devices are out of scope for this skill.\n\n## Related Skills — Skill Routing\n\n| If the user wants… | Use |\n|--------------------|-----|\n| XCP-ng VMs / hosts / pools / SRs / snapshots / XO backups | **xcpng-aiops** (this skill) |\n| Proxmox VE operations | **proxmox-aiops** |\n| NAS/storage appliance operations | a storage-appliance ops skill |\n| Backup-software suite job/restore operations | a backup-software ops skill |\n| Container/cluster lifecycle | a cluster ops skill |\n\n## Common Workflows\n\nEach recipe starts from a read or an RCA and ends in a governed write. Every\nwrite accepts `--dry-run`; destructive ones also double-confirm.\n\n### 1. \"Patch a pool without breaking live migration\"\n\n1. `xcpng-aiops overview` → fleet snapshot: pools, hosts, VMs by state, SRs near full, recent backup failures.\n2. `xcpng-aiops pool posture` → the RCA: hosts missing patches, hosts pending reboot, **version skew** across the pool's hosts, and multi-host pools without HA.\n3. `xcpng-aiops host missing-patches ` → what exactly is outstanding on the host you plan to take first.\n4. `xcpng-aiops vm list --state Running` → the VMs that must move off that host.\n5. For each: `xcpng-aiops vm migrate --dry-run`, then re-run for real (double confirm; the REAL source host is captured before the move and the inverse \"migrate back\" is recorded).\n6. `xcpng-aiops undo list` → confirm a migrate-back token exists for every VM you moved, before you touch the host.\n7. Patch and reboot the host in XO, then `xcpng-aiops pool posture` again to confirm the skew cleared.\n\n**Failure branch**: if `pool posture` reports version skew *before* you start, stop — live migration between mismatched host versions can be refused or unsafe. Bring the hosts to a common version first. If a migration fails mid-run, do not retry blindly: `xcpng-aiops vm get ` to see where the VM actually landed, and `xcpng-aiops task list` for the failing XO task, since a half-finished migrate leaves the VM on one side or the other.\n\n### 2. \"This VM keeps going unhealthy\"\n\n1. `xcpng-aiops vm health-rca` → findings with cause + action: halted unexpectedly (auto-poweron / HA restart priority set), paused or suspended VMs, running VMs without guest tools, CPU/memory pressure from RRD stats.\n2. `xcpng-aiops vm get ` → the VM's configuration and current power state.\n3. `xcpng-aiops vm stats ` → the RRD series behind a pressure finding, so you confirm sustained pressure rather than one spike.\n4. If it is halted and should be running: `xcpng-aiops vm start ` (the inverse `vm_stop` is recorded).\n5. If it is wedged and needs a bounce: `xcpng-aiops vm reboot --dry-run`, then for real (double confirm; add `--force` only for a hard reboot — **no undo** either way).\n6. `xcpng-aiops vm health-rca` again to confirm the finding cleared.\n\n**Failure branch**: if a clean shutdown or clean reboot hangs, the finding \"no guest tools\" is usually the real cause — clean actions need the guest agent. Do not escalate straight to `--force`; a hard action risks filesystem damage. Snapshot first (recipe 3), then use `--force` deliberately.\n\n### 3. \"Snapshot before a risky change, and roll back cleanly\"\n\n1. `xcpng-aiops vm list` → confirm the exact VM uuid.\n2. `xcpng-aiops sr usage-rca` → make sure the SR has room; snapshots grow it, and a snapshot on a near-full SR is how you take the pool down.\n3. `xcpng-aiops snapshot create pre-change` → XO returns the new snapshot's id, and an inverse `snapshot_delete` for **that** id is recorded.\n4. `xcpng-aiops snapshot list --vm ` → confirm the snapshot exists before you change anything.\n5. Make your change. If it went wrong: `xcpng-aiops snapshot revert ` (double confirm — replaces current state, **IRREVERSIBLE**, no undo).\n6. When you are satisfied: `xcpng-aiops snapshot delete --dry-run`, then without `--dry-run` (double confirm — **IRREVERSIBLE**, BEFORE state captured for the audit record, no undo).\n\n**Failure branch**: if `sr usage-rca` flags the SR as near-full or thin-provision overcommitted, do not snapshot — reclaim first (recipe 4). If a revert is refused or leaves the VM halted, check `xcpng-aiops task list` for the XO task; and never leave snapshots stacked long-term, because unmerged chains are the usual root cause of the vdi-chain backup failures in recipe 4.\n\n### 4. \"Backups have been failing every night and storage is filling up\"\n\n1. `xcpng-aiops backup failure-rca` → failed/skipped/interrupted runs grouped by job and classified: **vdi-chain** (coalesce not finished), **quiesce** (guest VSS), **transport** (remote unreachable), **storage-full**, unknown.\n2. `xcpng-aiops backup logs -n 20` → the raw recent runs behind that classification.\n3. `xcpng-aiops sr usage-rca` → SRs ranked by physical fullness, thin-provision overcommit, and **orphaned VDIs** (attached to no VM) with reclaimable bytes per SR.\n4. `xcpng-aiops sr vdis --sr --orphaned-only` → the specific orphaned VDIs worth reclaiming on that SR.\n5. For a **vdi-chain** classification: let the coalesce finish, stop stacking snapshots (`xcpng-aiops snapshot list`), then `xcpng-aiops sr rescan --dry-run` and for real (lowest-impact write) so XO re-reads the SR.\n6. For **storage-full**: reclaim space, then re-run `sr usage-rca` to confirm the SR dropped below the near-full threshold.\n7. `xcpng-aiops backup logs -n 20` after the next scheduled run to confirm it went green.\n\n**Failure branch**: a **transport** classification is not an XCP-ng problem — the backup remote is unreachable, so fix the remote in the XO UI (Settings → Remotes); rescanning the SR will not help. A **quiesce** classification means the guest agent could not freeze the filesystem: fix guest tools on that VM rather than disabling quiesce fleet-wide. If `sr rescan` does not shrink the chain, the coalesce is still running — wait rather than rescanning in a loop, which will trip the runaway budget guard.\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 (29 — 19 read, 8 write, 2 undo)\n\n| Category | Tools | R/W |\n|----------|-------|:---:|\n| Overview | `overview` | Read |\n| VMs | `vm_list`, `vm_get`, `vm_stats`, `vm_health_rca` | Read |\n| | `vm_start`, `vm_stop`, `vm_reboot`, `vm_migrate` | Write |\n| Hosts | `host_list`, `host_get` | Read |\n| Pools | `pool_list`, `pool_get`, `pool_patch_ha_posture` | Read |\n| SRs / VDIs | `sr_list`, `sr_get`, `vdi_list`, `sr_usage_rca` | Read |\n| | `sr_rescan` | Write |\n| Snapshots | `snapshot_list` | Read |\n| | `snapshot_create`, `snapshot_delete`, `snapshot_revert` | Write |\n| Backups | `backup_job_list`, `backup_log_list`, `backup_failure_rca` | Read |\n| Tasks | `task_list` | Read |\n| Undo | `undo_list`, `undo_apply` | Read + replay |\n\n**Harness features that light up**: `vm_start`↔`vm_stop` record each other as inverses (with `_undo_id`); `vm_migrate` captures the REAL source host BEFORE moving and records \"migrate back\"; `snapshot_create` captures the REAL snapshot id from the XO response and records \"delete THAT snapshot\". `snapshot_delete` and `snapshot_revert` are `risk_level=high`, capture BEFORE state, and declare no undo (irreversible). Every write takes `dry_run=True` (may read, never writes; no undo; audited). All 29 tools are audit-logged under `~/.xcpng-aiops/` and pass through the budget/runaway guard, each carrying a descriptive risk tier into its audit row. Start any triage with `overview`.\n\n## CLI Quick Reference\n\n```bash\nxcpng-aiops init # onboarding wizard (encrypted XO token)\nxcpng-aiops overview [--target ] # fleet health summary\nxcpng-aiops vm list [--state Running] [--pool ]\nxcpng-aiops vm get \nxcpng-aiops vm stats [-g minutes]\nxcpng-aiops vm health-rca [] # RCA: cause + action\nxcpng-aiops vm start [--dry-run]\nxcpng-aiops vm stop [--force] [--dry-run] # double confirm; refuses the declared XO VM\nxcpng-aiops vm reboot [--force] [--dry-run] # double confirm\nxcpng-aiops vm migrate [--dry-run] # double confirm\nxcpng-aiops host list / get / missing-patches \nxcpng-aiops pool list / get \nxcpng-aiops pool posture [] # RCA: patches / reboots / skew / HA\nxcpng-aiops sr list / get \nxcpng-aiops sr vdis [--sr ] [--orphaned-only]\nxcpng-aiops sr usage-rca # RCA: near-full / overcommit / orphans\nxcpng-aiops sr rescan [--dry-run]\nxcpng-aiops snapshot list [--vm ]\nxcpng-aiops snapshot create [--dry-run]\nxcpng-aiops snapshot delete [--dry-run] # double confirm, IRREVERSIBLE\nxcpng-aiops snapshot revert [--dry-run] # double confirm, IRREVERSIBLE\nxcpng-aiops backup jobs / logs [-n 50]\nxcpng-aiops backup failure-rca [-n 50] # RCA: vdi-chain / quiesce / transport\nxcpng-aiops task list [--status failure]\nxcpng-aiops secret set / list / rm / migrate / rotate-password\nxcpng-aiops doctor # XO reachability + token + pool count\nxcpng-aiops mcp # start MCP server (stdio)\n```\n\nSee `references/cli-reference.md` for the full command list, and\n`references/agent-guardrails.md` when driving these tools with a smaller /\nlocal model (the guardrails the tool enforces for you, and a ready system prompt).\n\n## Troubleshooting\n\n### \"Config file not found\"\nRun `xcpng-aiops init` to set up your first target (writes `~/.xcpng-aiops/config.yaml` and stores the XO token encrypted).\n\n### \"No XO authentication token for target ''\"\nAdd it to the encrypted store: `xcpng-aiops secret set ` (prompts hidden), or run `xcpng-aiops init`. Create the token in the XO UI (user menu → Personal tokens) or with `xo-cli --createToken`. For non-interactive use (MCP/CI), also export `XCPNG_AIOPS_MASTER_PASSWORD` so the store can be unlocked without a prompt.\n\n### \"Master password not set\" / \"Wrong master password\"\nThe encrypted store `~/.xcpng-aiops/secrets.enc` is unlocked by `XCPNG_AIOPS_MASTER_PASSWORD` (or an interactive prompt). If you forgot it, delete `secrets.enc` and re-run `xcpng-aiops init`. Rotate it with `xcpng-aiops secret rotate-password`.\n\n### \"Authentication/authorization failed (401/403)\"\nThe XO token is wrong, expired, or revoked, or the XO account lacks permission. Regenerate the token in the XO UI (user menu → Personal tokens) and update it: `xcpng-aiops secret set `.\n\n### \"Could not reach Xen Orchestra … check the XO URL\"\nConfirm the XO web UI is reachable at the configured `url` and that `api_path` is `/rest/v0` (XO 5.x). For self-signed certificates set `verify_ssl: false` on the target (lab only).\n\n### \"Resource not found (404)\"\nThe VM/SR/snapshot uuid is stale, or this XO release lacks the endpoint. List the parent collection first (`vm list`, `sr list`, `snapshot list`) to get a current uuid.\n\n### Doctor says \"manages no pools yet\"\nYour XO instance is reachable but has no XCP-ng servers connected — add them in the XO UI (Settings → Servers).\n\n## Audit & Safety\n\nThe skill delivers reads and writes and records them; it does **not** decide\nwhether a write is permitted. That is your agent's judgement, or the permission\nof the Xen Orchestra account whose token you connect it with (give that XO user\na read-only ACL or scope its token down — writes then fail at Xen Orchestra).\nThere 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 `~/.xcpng-aiops/audit.db` (relocatable via `XCPNG_AIOPS_HOME`): params (secrets redacted), result, status, duration, and the risk tier. The CLI writes the same row the MCP path does.\n- The XO token is stored **encrypted** in `~/.xcpng-aiops/secrets.enc` (Fernet/AES-128 + scrypt key derivation; chmod 600) — never plaintext on disk; the master password is never stored, only a per-store salt + ciphertext.\n- `XCPNG_AUDIT_APPROVED_BY` / `XCPNG_AUDIT_RATIONALE` are optional annotations recorded on the audit row (who/why); they are never required and never block.\n- **Budget / runaway guard** — a safety backstop, not authorization: caps cumulative tool calls and wall-time, and trips on tight task-poll loops.\n- Writes support `--dry-run` / `dry_run=True` and double confirmation at the CLI; CLI writes execute through the same governed tools, so they are audited + undo-recorded.\n- Reversible writes (`vm_start`/`vm_stop`/`vm_migrate`/`snapshot_create`) capture the real before-state and record a replayable inverse descriptor; `snapshot_delete`/`snapshot_revert` are `risk=high`, irreversible, and declare no undo.\n- **Risk tier** is a descriptive label on the audit row derived from `risk_level`; it gates nothing.\n\nThe harness is bundled in the package — no external dependency, no manual setup. See `references/setup-guide.md` for security details.\n\n## Contributing & feature requests\n\nCoverage is intentionally focused. **Missing a capability you need, or hit an endpoint that differs on your Xen Orchestra version?** Open an issue or pull request at [github.com/AIops-tools/XCPng-AIops](https://github.com/AIops-tools/XCPng-AIops/issues) — feature requests, contributions, and comments are all welcome.\n\n## License\n\nMIT — [github.com/AIops-tools/XCPng-AIops](https://github.com/AIops-tools/XCPng-AIops)\n\nFile v0.8.3:_meta.json\n\n{\n \"ownerId\": \"kn7b067awq2s97bn3d7p5qfhw5827pxc\",\n \"slug\": \"xcpng-aiops\",\n \"version\": \"0.8.3\",\n \"publishedAt\": 1789453466794\n}\n\nFile v0.8.3:references/agent-guardrails.md\n\n# Agent guardrails — running xcpng-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## Authorization is not this tool's job — decide it where it belongs\n\nWhether a write should happen is your decision, or the account's. The tool does\nnot gate it — there is no read-only switch and no approval prompt to configure.\nThe two right places to control read vs write:\n\n- **The Xen Orchestra account whose token you connect with.** Give that XO user\n a read-only ACL, or scope its personal token down. A write then fails at Xen\n Orchestra, which is the only place the permission actually lives — a revoked\n permission cannot be argued around by a model, but a skill-side flag can.\n- **Your agent's system prompt.** If you want an observe-only session, tell the\n model not to call the write tools (they are clearly tagged `[WRITE]`).\n\nWhat the tool *does* guarantee is that you can always see what happened:\n\n## What the tool 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 Xen Orchestra did not return comes back as `null`, never as `\"\"`. A VM with no `name_label`, a task with no `properties.name`, an SR with no `content_type` — all report `null`. Absent and empty are distinguishable in the payload. |\n| \"Tell me if the output was cut off\" | Every listing returns `{\"vms\": [...], \"returned\": N, \"limit\": L, \"truncated\": true/false}` (same shape with `srs`, `vdis`, `snapshots`, `tasks`, `jobs`, `logs`, `undos`). Truncation is **measured** — the full collection length client-side, or one over-fetched record for `backup_log_list` — never guessed from the row count matching the limit. The RCA tools report `inputTruncated` when the listing they correlated over was itself capped. |\n| \"Preserve the ordering / tell me what's most urgent\" | RCA findings carry an explicit `severity` (`high`/`medium`/`low`) and are already sorted worst-first, each with the measured number in `evidence` and a concrete `action`. Priority is in the payload, not implied by list position. |\n| \"Confirm before anything destructive\" | Destructive operations (`snapshot_delete`, `snapshot_revert`, `vm_stop`/`reboot`/`migrate`) require a `dry_run` preview + double confirmation at the CLI. Reversible writes capture the prior state so the undo token can restore it. |\n| \"Never stop the Xen Orchestra VM itself\" | **Only if the operator declared it.** Set `xo_self_vm_uuid` on the target and `vm_stop` refuses exactly that uuid on both the MCP and CLI paths. Undeclared, nothing is refused — XO exposes no self endpoint and its token carries no claims, so the tool cannot work this out and fails open rather than guess. Keep a prompt line for this if you cannot declare the uuid. |\n| \"Log what you did\" | Every governed call is audited to `~/.xcpng-aiops/audit.db` regardless of what the model says it did — and the CLI writes the same row the MCP path does, so there is no unaudited entry point. |\n| \"Don't get stuck retrying\" | The runaway guard trips a circuit breaker if the same call is hammered in a tight loop — a stuck agent is stopped rather than left to burn calls and time. |\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 an XCP-ng environment through the xcpng-aiops MCP tools. They talk\nto Xen Orchestra's REST API; there is no direct per-host XAPI access.\n\nTOOL USE\n- Before answering any question about the current XCP-ng 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- Start broad triage with \"overview\" — it fans out over pools, hosts, VMs, SRs\n and recent backup runs in one call.\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- Listings come back as an envelope, not a bare list: read the items under\n \"vms\" / \"srs\" / \"vdis\" / \"snapshots\" / \"tasks\" / \"jobs\" / \"logs\".\n- If \"truncated\" is true, say so and re-run with a higher limit instead of\n treating the partial result as complete. If an RCA reports \"inputTruncated\",\n its conclusion covers only a subset — state that.\n- A null field means Xen Orchestra 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 power states, SR types, statuses, or uuids.\n- When an RCA result has findings, work in the order given (worst first) and\n cite the measured number in each finding's \"evidence\".\n\nIDENTIFIERS\n- Every object is addressed by its XO uuid: a VM uuid (vm_list), a host uuid\n (host_list), a pool uuid (pool_list), an SR uuid (sr_list), a VDI uuid\n (vdi_list), a snapshot uuid (snapshot_list). They are NOT interchangeable —\n do not pass a host uuid where a VM uuid is expected.\n- A name_label is a label, not an identifier: it is not unique and must never\n be used in place of a uuid. Resolve the name to a uuid with a list tool first.\n- An XO task id (task_list) identifies an async job, not the object it acted on.\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```\n\n## Recommended setup for a local model\n\nStart with a connection that *cannot* write, verify, and widen the account's\npermission only when you trust the setup — snapshot delete/revert are\nirreversible, and stopping the wrong VM can be the one XO itself runs on:\n\n```bash\n# Give the Xen Orchestra account a read-only ACL, or scope its personal token\n# down, so writes fail at XO rather than depending on a skill-side flag. Then:\nxcpng-aiops doctor\n```\n\nOptionally annotate the audit trail with who is operating and why — recorded on\nevery row, never required:\n\n```bash\nexport XCPNG_AUDIT_APPROVED_BY=\"your.name@example.com\"\nexport XCPNG_AUDIT_RATIONALE=\"scheduled maintenance window 2026-07-20\"\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 `overview` and the four RCA\n tools (`vm_health_rca`, `sr_usage_rca`, `backup_failure_rca`,\n `pool_patch_ha_posture`) — they do the multi-step correlation inside one call,\n so the model does not have to chain reads and keep uuids straight.\n- **The model ignores later tool results in a long context.** Ask narrower\n questions and use `limit` (plus the `pool` / `sr` / `power_state` / `status`\n filters) deliberately rather than pulling whole inventories. `vdi_list` in\n particular is the longest listing in a real fleet.\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/XCPng-AIops](https://github.com/AIops-tools/XCPng-AIops/issues)\nwith the model, runtime, and what went wrong.\n\nFile v0.8.3:references/capabilities.md\n\n# xcpng-aiops — Capabilities (29 MCP tools: 19 read, 8 write, 2 undo)\n\nAll tools go through the bundled `@governed_tool` harness (audit / policy /\nbudget / undo / risk-tier). XO object ids are uuids; get them from the matching\n`*_list` tool first. Every tool takes an optional `target` (XO target name\nfrom config; omit for the default).\n\n**Listing envelopes.** `vm_list`, `sr_list`, `vdi_list`, `snapshot_list`,\n`task_list`, `backup_job_list`, `backup_log_list` and `undo_list` return\n`{: [...], \"returned\": N, \"limit\": L, \"truncated\": bool}` — read the\nitems under the named key (`vms`, `srs`, `vdis`, `snapshots`, `tasks`, `jobs`,\n`logs`, `undos`). `truncated` is measured, not guessed: filters run first, the\ncap after, and `backup_log_list` over-fetches one record. When it is true,\nre-run with a higher `limit`. The RCA tools report `inputTruncated` when the\nlisting they correlated over was itself capped.\n\n**Absent vs empty.** A field XO did not return is `null`, never `\"\"` — do not\ninfer a value for it.\n\n**Authorization.** The tool records; it does not gate. Whether a write may run\nis the agent's decision or the connecting Xen Orchestra account's permissions —\nthere is no read-only switch or approval gate. See `agent-guardrails.md`.\n\n## Overview\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `overview` | low | One-shot fleet health: pools, hosts (disabled / reboot-required / versions), VMs by power state + running-without-tools, SRs near full, recent backup failures. Start any triage here. |\n\n## VMs\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `vm_list(power_state?, pool?, limit?)` | low | VMs with power state, host, guest-tools status, sizing. |\n| `vm_get(vm_id)` | low | One VM: state, host, OS, tools, tags, start time. |\n| `vm_stats(vm_id, granularity?)` | low | Recent RRD averages: cpuAvgPercent, memoryUsedPercent. |\n| `vm_health_rca(vm_id?)` | low | **RCA**: halted-unexpectedly (auto-poweron/HA set), paused, suspended, guest-tools-missing, cpu-pressure (≥90%), memory-pressure (≥90%). Cause + severity + evidence + action per finding. Fleet mode caps stats pulls at 5 running VMs. |\n| `vm_start(vm_id, dry_run?)` | medium | Start a VM. **Undo: vm_stop** (recorded). |\n| `vm_stop(vm_id, force?, dry_run?)` | medium | Clean shutdown (hard with force). **Undo: vm_start** — only recorded if the VM was Running before. Refuses the VM declared as running XO (`xo_self_vm_uuid` on the target); with none declared there is **no** such guard — XO has no self endpoint, so it fails open rather than guess. `dry_run` refuses the declared uuid too, and returns `selfVmHint` (a possible IP coincidence, never a verdict, never a block — on either path). |\n| `vm_reboot(vm_id, force?, dry_run?)` | medium | Clean/hard reboot. Prior power state captured; **no undo**. |\n| `vm_migrate(vm_id, host_id, dry_run?)` | medium | Live-migrate. Captures the REAL source host before moving; **undo: migrate back to it**. |\n\n## Hosts\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `host_list(pool?)` | low | Hosts: version, enabled, reboot-required, memory %, resident VMs. |\n| `host_get(host_id)` | low | One host: version, build, memory, tags. |\n\n## Pools\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `pool_list()` | low | Pools with master, HA state, default SR. |\n| `pool_get(pool_id)` | low | One pool detail. |\n| `pool_patch_ha_posture(pool_id?)` | low | **RCA**: patches-missing, reboot-required, version-skew (high — breaks live migration), ha-disabled. Per-host rows + per-pool findings. |\n\n## SRs / VDIs\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `sr_list(pool?, limit?)` | low | SRs: capacity, physical usage %, virtual allocation. |\n| `sr_get(sr_id)` | low | One SR detail. |\n| `vdi_list(sr?, orphaned_only?, limit?)` | low | VDIs; `orphaned_only=true` → disks attached to no VM (reclaim candidates). |\n| `sr_usage_rca()` | low | **RCA**: sr-critical (≥95%), sr-near-full (≥85%), sr-overcommitted (allocation > capacity), orphaned-vdis with reclaimable bytes per SR. ISO SRs excluded. |\n| `sr_rescan(sr_id, dry_run?)` | medium | Metadata refresh; no data change, no undo. Lowest-impact write, but still a write. |\n\n## Snapshots\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `snapshot_list(vm_id?, limit?)` | low | VM snapshots with time and parent VM. |\n| `snapshot_create(vm_id, name, dry_run?)` | medium | Snapshot a VM. Captures the REAL new snapshot id from XO's response; **undo: delete THAT snapshot**. |\n| `snapshot_delete(snapshot_id, dry_run?)` | **high** | IRREVERSIBLE. Captures BEFORE state (name/time/VM); no undo. |\n| `snapshot_revert(snapshot_id, dry_run?)` | **high** | IRREVERSIBLE — replaces the VM's current state. Captures snapshot state; no undo. Take a fresh snapshot first. |\n\n## Backups\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `backup_job_list(limit?)` | low | VM backup jobs (id, name, mode). |\n| `backup_log_list(limit?)` | low | Recent run logs: status + failed-task messages. |\n| `backup_failure_rca(limit?)` | low | **RCA**: failures per job classified — vdi-chain (coalesce), quiesce (guest VSS), transport (remote unreachable), storage-full, unknown. Counts + sample findings + action per class. |\n\n## Tasks\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `task_list(status?, limit?)` | low | XO tasks (pending / success / failure). |\n\n## Write semantics\n\n- `dry_run=true` → preview dict (`{\"dryRun\": true, \"would...\": {...}}`). A dry-run **may\n read** — resolving ids and evaluating guards is what lets it tell you the call would be\n refused — but **never writes** and records **no undo**. It runs through `@governed_tool`\n like any other call, so it is audited and it can be refused. The CLI `--dry-run` routes\n through the same governed function, so both entry points behave identically.\n- Successful reversible writes return `_undo_id` referencing the recorded inverse descriptor in `~/.xcpng-aiops/undo.db`. Undo execution is an external orchestrator's job — recording only.\n- High-risk tools (`snapshot_delete`, `snapshot_revert`) require a `dry_run` preview + double confirmation at the CLI. `XCPNG_AUDIT_APPROVED_BY` / `XCPNG_AUDIT_RATIONALE` are optional annotations recorded on the audit row — never required, never blocking.\n\nFile v0.8.3:references/cli-reference.md\n\n# xcpng-aiops — CLI reference\n\nGlobal pattern: `xcpng-aiops [args] [--target ]`.\n`--target/-t` selects a Xen Orchestra target from `~/.xcpng-aiops/config.yaml`\n(default: the first one). Write commands support `--dry-run` (prints the API\ncall, changes nothing) and destructive ones require **double confirmation**.\n\n## Setup & health\n\n```bash\nxcpng-aiops init # onboarding wizard: XO URL, TLS verify (default yes), encrypted token\nxcpng-aiops doctor [--skip-auth] # config + secret store + XO reachability + pool count\nxcpng-aiops overview [-t xo1] # one-shot fleet health summary (JSON)\nxcpng-aiops mcp # start the MCP server (stdio)\n```\n\n## VMs\n\n```bash\nxcpng-aiops vm list [--state Running|Halted|Paused|Suspended] [--pool ] [--limit 200]\nxcpng-aiops vm get \nxcpng-aiops vm stats [--granularity seconds|minutes|hours|days]\nxcpng-aiops vm health-rca [] # RCA (fleet-wide when uuid omitted)\nxcpng-aiops vm start [--dry-run] # governed; undo = stop\nxcpng-aiops vm stop [--force] [--dry-run] # double confirm; undo = start\nxcpng-aiops vm reboot [--force] [--dry-run] # double confirm; no undo\nxcpng-aiops vm migrate [--dry-run] # double confirm; undo = migrate back\n```\n\n`--force` = hard power operation (no guest tools needed); default is a clean\nguest shutdown/reboot.\n\n## Hosts\n\n```bash\nxcpng-aiops host list [--pool ]\nxcpng-aiops host get \nxcpng-aiops host missing-patches \n```\n\n## Pools\n\n```bash\nxcpng-aiops pool list\nxcpng-aiops pool get \nxcpng-aiops pool posture [] # RCA: patches / reboots / version skew / HA\n```\n\n## Storage (SRs / VDIs)\n\n```bash\nxcpng-aiops sr list [--pool ] [--limit 200]\nxcpng-aiops sr get \nxcpng-aiops sr vdis [--sr ] [--orphaned-only] [--limit 200]\nxcpng-aiops sr usage-rca # RCA: near-full / overcommit / orphaned VDIs\nxcpng-aiops sr rescan [--dry-run]\n```\n\n## Snapshots\n\n```bash\nxcpng-aiops snapshot list [--vm ] [--limit 200]\nxcpng-aiops snapshot create [--dry-run]\nxcpng-aiops snapshot delete [--dry-run] # double confirm, IRREVERSIBLE\nxcpng-aiops snapshot revert [--dry-run] # double confirm, IRREVERSIBLE\n```\n\n## Backups & tasks\n\n```bash\nxcpng-aiops backup jobs [--limit 200]\nxcpng-aiops backup logs [--limit 50]\nxcpng-aiops backup failure-rca [--limit 50] # RCA: vdi-chain / quiesce / transport / storage-full\nxcpng-aiops task list [--status pending|success|failure] [--limit 200]\n```\n\n## Secrets (encrypted store)\n\n```bash\nxcpng-aiops secret set [--value ] # omit --value to be prompted (hidden)\nxcpng-aiops secret list # names only\nxcpng-aiops secret rm \nxcpng-aiops secret migrate # import legacy plaintext .env\nxcpng-aiops secret rotate-password # re-encrypt under a new master password\n```\n\n## Environment variables\n\n| Variable | Purpose |\n|----------|---------|\n| `XCPNG_AIOPS_MASTER_PASSWORD` | Unlock `secrets.enc` non-interactively (MCP/CI). |\n| `XCPNG_AIOPS_HOME` | Relocate `~/.xcpng-aiops` (audit.db, undo.db). |\n| `XCPNG_AIOPS_CONFIG` | Alternate config.yaml path for the MCP server. |\n| `XCPNG_AUDIT_APPROVED_BY` / `XCPNG_AUDIT_RATIONALE` | Optional approver/rationale annotations recorded on the audit row (never required). |\n| `XCPNG_MAX_TOOL_CALLS` / `XCPNG_MAX_TOOL_SECONDS` | Budget ceilings. |\n| `XCPNG_RUNAWAY_MAX` / `XCPNG_RUNAWAY_WINDOW_SEC` | Runaway-loop circuit breaker. |\n| `XCPNG__TOKEN` | Legacy plaintext token fallback (deprecated). |\n\n## Truncation\n\nListing commands cap their output at `--limit` (default 200) and print\n`… showing N of more … — truncated, re-run with a higher --limit` when there\nwas more; the JSON itself carries `\"truncated\": true`.\n\nFile v0.8.3:references/setup-guide.md\n\n# xcpng-aiops — Setup & security guide\n\n## Prerequisites\n\n- A **Xen Orchestra instance** (XO from sources or the Xen Orchestra\n Appliance, 5.x) with the REST API at `/rest/v0`. XO is the management plane\n this tool talks to; your XCP-ng hosts/pools must already be connected to it\n (XO UI → Settings → Servers). **Per-host XAPI access is out of scope.**\n- Python ≥ 3.11 (`uv tool install xcpng-aiops` handles the rest).\n\n## 1. Create an XO authentication token\n\nIn the XO UI: user menu (top-right) → **Personal tokens** → create. Or from a\nshell: `xo-cli --createToken`. Use a dedicated XO user with the least\nprivilege you can (admin is required for some collections; a read-mostly user\nworks for triage-only setups).\n\n## 2. Onboard\n\n```bash\nxcpng-aiops init\n```\n\nThe wizard prompts for:\n\n1. **Master password** — encrypts `~/.xcpng-aiops/secrets.enc`. Never stored;\n export `XCPNG_AIOPS_MASTER_PASSWORD` for non-interactive use.\n2. **Target name** (e.g. `xo1`) and the **XO URL** (e.g.\n `https://xo.example.com` — the same origin as the XO web UI).\n3. **TLS verification** — default **yes**; answer no only for self-signed lab\n certificates.\n4. **The token** (hidden input) — stored encrypted, never in config.yaml.\n\n## 3. Verify\n\n```bash\nxcpng-aiops doctor\n```\n\nChecks: config present, encrypted store present + permissions (600), token\npresent per target, XO reachable, token valid (a 401/403 fails the check), and\nhow many XCP-ng pools the XO instance manages.\n\n## Files & permissions\n\n| Path | Content | Mode |\n|------|---------|:----:|\n| `~/.xcpng-aiops/config.yaml` | non-secret connection details | 700 dir |\n| `~/.xcpng-aiops/secrets.enc` | Fernet-encrypted token map | 600 |\n| `~/.xcpng-aiops/audit.db` | SQLite audit log (every tool call) | — |\n| `~/.xcpng-aiops/undo.db` | recorded inverse descriptors | — |\n\nRelocate everything with `XCPNG_AIOPS_HOME`.\n\n## Security notes\n\n- The token is sent per request as `Authorization: Bearer ` **and**\n `Cookie: authenticationToken=` (compatibility across XO 5.x\n releases); held in memory only, never logged.\n- Secret encryption: Fernet (AES-128-CBC + HMAC-SHA256), key derived from the\n master password via scrypt (N=2^15, r=8, p=1) with a random per-store salt.\n- High-risk writes (`snapshot_delete`, `snapshot_revert`) require a `dry_run`\n preview + double confirmation at the CLI, and carry a `high` risk tier as a\n descriptive audit label — it gates nothing. `XCPNG_AUDIT_APPROVED_BY` /\n `XCPNG_AUDIT_RATIONALE` are optional annotations recorded on the audit row,\n never required.\n- Budget guard: `XCPNG_MAX_TOOL_CALLS` (default ceiling on calls per process)\n and `XCPNG_MAX_TOOL_SECONDS` (cumulative wall-time), plus a runaway breaker\n for tight poll loops.\n- No outbound traffic except the configured XO endpoint. No telemetry.\n\n## MCP client setup\n\n```json\n{\n \"mcpServers\": {\n \"xcpng-aiops\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"xcpng-aiops\", \"xcpng-aiops-mcp\"],\n \"env\": { \"XCPNG_AIOPS_MASTER_PASSWORD\": \"your-master-password\" }\n }\n }\n}\n```\n\nMCP clients do **not** inherit your shell environment — the master password\n(and any `XCPNG_*` overrides) must be in the `env` block.\n\nFile v0.8.3:skill-card.md\n\n## Description:\n\nXCP-ng AIops helps agents operate XCP-ng virtualization fleets through Xen Orchestra, including fleet health, VM, host, pool, storage, snapshot, backup, task, RCA, and governed write workflows.\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 and administer XCP-ng fleets managed by Xen Orchestra, triage common VM, storage, backup, pool, and host issues, and perform guarded VM, snapshot, migration, and storage-rescan actions.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can perform disruptive infrastructure changes, including VM power, migration, snapshot, and storage-rescan operations.\n\nMitigation: Use a dedicated least-privilege Xen Orchestra account, prefer read-only access for triage, require dry-run previews for writes, and reserve write permissions for approved maintenance work.\n\nRisk: The skill relies on stored Xen Orchestra credentials and a master password for non-interactive use.\n\nMitigation: Avoid plaintext master passwords in shared MCP configuration, protect ~/.xcpng-aiops/ files, and treat audit and encrypted token files as sensitive operational data.\n\nRisk: The release can be installed through mutable package tooling such as uv or uvx.\n\nMitigation: Pin and verify the package source before execution.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/zw008/skills/xcpng-aiops)\n- [Project homepage](https://github.com/AIops-tools/XCPng-AIops)\n- [xcpng-aiops - Capabilities](references/capabilities.md)\n- [xcpng-aiops - CLI reference](references/cli-reference.md)\n- [xcpng-aiops - Setup & security guide](references/setup-guide.md)\n- [Agent guardrails - running xcpng-aiops with a smaller / local model](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 and configuration snippets]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May guide an agent to invoke CLI or MCP tools that return structured operational data and audit records.]\n\n## Skill Version(s):\n\n0.8.3 (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.8.2: 7 files, 21266 bytes\n\nFiles: references/agent-guardrails.md (7975b), references/capabilities.md (6380b), references/cli-reference.md (4010b), references/setup-guide.md (3226b), skill-card.md (2990b), SKILL.md (21953b), _meta.json (130b)\n\nFile v0.8.2:SKILL.md\n\n---\nname: xcpng-aiops\nslug: xcpng-aiops\ndisplayName: \"XCP-ng AIops\"\nsummary: \"Governed XCP-ng ops via Xen Orchestra — 29 MCP tools with audit, budget, undo guards.\"\nlicense: MIT\nhomepage: https://github.com/AIops-tools/XCPng-AIops\ntags: [aiops, mcp, governance, xcpng]\ndescription: >\n Use this skill whenever the user needs to operate an XCP-ng virtualization fleet through Xen Orchestra — a one-shot fleet health overview; VMs (list/get/RRD stats), hosts, pools, storage repositories (SRs) and VDIs, VM snapshots, backup jobs and run logs, XO tasks; four RCA analyses (VM health, SR usage, backup-job failures, pool patch & HA posture); and governed writes (VM start/stop/reboot/migrate, snapshot create/delete/revert, SR rescan).\n Always use this skill for \"xcp-ng vm\", \"xen orchestra\", \"xo backup failed\", \"sr full\", \"orphaned vdi\", \"xcp-ng snapshot\", \"migrate vm to another host\", \"xcp-ng patches\", or \"pool HA\" when the context is explicitly XCP-ng / Xen Orchestra / a Xen-based fleet.\n Do NOT use when the target is not an XCP-ng fleet managed by Xen Orchestra — other hypervisors (Do NOT use for Proxmox VE — use proxmox-aiops), NAS/storage appliances, backup software suites, container clusters, and network devices are out of scope (negative routing hints only).\n Common XCP-ng-via-XO operations with a built-in governance harness (audit, policy, token budget, undo, risk-tiers).\ninstaller:\n kind: uv\n package: xcpng-aiops\nargument-hint: \"[vm/sr/snapshot uuid or describe your XCP-ng task]\"\nallowed-tools:\n - Bash\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"xcpng-aiops\",\"uvx\"]},\"optional\":{\"env\":[\"XCPNG_AIOPS_CONFIG\",\"XCPNG_AIOPS_MASTER_PASSWORD\"]},\"homepage\":\"https://github.com/AIops-tools/XCPng-AIops\",\"emoji\":\"🖥️\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n Standalone, self-governed XCP-ng operations via Xen Orchestra's REST API /rest/v0. REQUIRES a Xen Orchestra instance (XO from sources or the Xen Orchestra Appliance, 5.x) — XO is the management plane; direct per-host XAPI access is out of scope for v0.1. The governance harness (audit, policy, token/runaway budget, undo, risk-tiers) is bundled in the package — no external skill-family dependency.\n All write operations are audited to a local SQLite DB under ~/.xcpng-aiops/ (relocatable via XCPNG_AIOPS_HOME).\n Credentials: Each XO target's personal authentication token is stored ENCRYPTED in ~/.xcpng-aiops/secrets.enc (Fernet/AES-128 + scrypt-derived key) — never plaintext on disk. Run 'xcpng-aiops init' to onboard, or 'xcpng-aiops secret set ' to add one (create the token in the XO UI: user menu → Personal tokens, or `xo-cli --createToken`). The store is unlocked by a master password from XCPNG_AIOPS_MASTER_PASSWORD (non-interactive/MCP/CI) or an interactive prompt (CLI on a TTY). A legacy plaintext env var XCPNG__TOKEN is still honoured as a fallback with a deprecation warning (migrate with 'xcpng-aiops secret migrate'). The token is sent in headers (Authorization: Bearer + authenticationToken cookie) at request time and held only in memory; tokens are never logged or echoed.\n Destructive operations (snapshot delete/revert, vm stop/reboot/migrate) require double confirmation at the CLI layer and support --dry-run; every write MCP tool takes a dry_run preview. A dry_run MAY read (that is how it can tell you the call would be refused) but never writes, records no undo, and is audited like any other governed call. All write tools pass through the @governed_tool decorator (budget guard + audit + risk-tier labelling). vm_start↔vm_stop record each other as inverses; vm_migrate records migrating back to the captured source host; snapshot_create records deleting the REAL snapshot id XO returned; snapshot_delete and snapshot_revert are high-risk and irreversible (capture BEFORE state, record no undo). vm_stop refuses the VM declared as running Xen Orchestra (xo_self_vm_uuid on the target) because stopping XO removes the API vm_start would travel over; that guard is opt-in and fails open when undeclared, since XO's REST API exposes no self endpoint.\n Webhooks: none — no outbound network calls beyond the configured Xen Orchestra REST API endpoint.\n SSL: verify_ssl defaults to true; disable only for self-signed lab certificates.\n Transitive dependencies: httpx (HTTP client) and the MCP SDK. No post-install scripts or background services.\n Verification status: mock-validated; no recorded end-to-end run against a live Xen Orchestra instance yet. Endpoint paths are modelled against the documented Xen Orchestra REST /rest/v0 API and need live verification — action names may differ across XO releases. See docs/VERIFICATION.md.\n---\n\n# XCP-ng AIops\n\n> **Disclaimer**: This is a community-maintained open-source project and is **not affiliated with, endorsed by, or sponsored by Vates, the XCP-ng project, or the Xen Orchestra project.** \"XCP-ng\", \"Xen Orchestra\", and \"Xen\" are trademarks of their owners. Source code is publicly auditable at [github.com/AIops-tools/XCPng-AIops](https://github.com/AIops-tools/XCPng-AIops) under the MIT license.\n\nGoverned XCP-ng operations via **Xen Orchestra's REST API** — **29 MCP tools**, every one wrapped with the bundled `@governed_tool` harness: a local unified audit log under `~/.xcpng-aiops/`, policy engine, token/runaway budget guard, undo-token recording, and descriptive risk tiers. The XO authentication token is stored **encrypted** (`~/.xcpng-aiops/secrets.enc`, Fernet + scrypt) — never plaintext on disk.\n\n> **Requires a Xen Orchestra instance** (5.x with `/rest/v0`) — XO is the management plane; per-host XAPI is out of scope for v0.1. **Standalone**: the governance harness is bundled in the package (`xcpng_aiops.governance`) — xcpng-aiops has no external skill-family dependency. Coverage is common operations, not exhaustive; verification status and the live-run checklist are in `docs/VERIFICATION.md`.\n\n## What This Skill Does\n\n| Category | Tools | Count | Read or Write |\n|----------|-------|:-----:|:-------------:|\n| **Overview** | fleet health overview | 1 | 1 read |\n| **VMs** | list, get, RRD stats, health RCA | 4 | 4 read |\n| | start, stop, reboot, migrate | 4 | 4 write (medium) |\n| **Hosts** | list, get | 2 | 2 read |\n| **Pools** | list, get, patch & HA posture RCA | 3 | 3 read |\n| **SRs / VDIs** | list, get, VDI list (orphan filter), usage RCA | 4 | 4 read |\n| | rescan | 1 | 1 write (medium) |\n| **Snapshots** | list | 1 | 1 read |\n| | create (medium), delete (high), revert (high) | 3 | 3 write |\n| **Backups** | jobs, run logs, failure RCA | 3 | 3 read |\n| **Tasks** | list | 1 | 1 read |\n\n## Quick Install\n\n```bash\nuv tool install xcpng-aiops\nxcpng-aiops init # interactive wizard: XO URL + encrypted token\nxcpng-aiops doctor # XO reachability + token validity + pool count\n```\n\nOr as an OpenClaw plugin, which installs this skill and its MCP server together:\n\n```bash\nopenclaw plugins install clawhub:@zw008/xcpng-aiops\nopenclaw skills info xcpng-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- Triage an XCP-ng fleet (`overview`): pools, hosts, VMs by state, SRs near full, recent backup failures\n- Root-cause an unhealthy VM (`vm health-rca`): halted unexpectedly, paused, guest tools missing, CPU/memory pressure\n- Root-cause storage pressure (`sr usage-rca`): SRs ranked near-full, thin-provision overcommit, orphaned VDIs with reclaimable bytes\n- Root-cause backup failures (`backup failure-rca`): vdi-chain / quiesce / transport / storage-full classification\n- Check patch & HA posture (`pool posture`): missing patches, pending reboots, version skew, HA state\n- Snapshot a VM before a risky change; start/stop/reboot/migrate VMs under governance\n\n**Do NOT use when** the target is not an XCP-ng fleet managed by Xen Orchestra — other hypervisors (Do NOT use for Proxmox VE — use proxmox-aiops), NAS/storage appliances, backup software suites, Kubernetes/containers, and network devices are out of scope for this skill.\n\n## Related Skills — Skill Routing\n\n| If the user wants… | Use |\n|--------------------|-----|\n| XCP-ng VMs / hosts / pools / SRs / snapshots / XO backups | **xcpng-aiops** (this skill) |\n| Proxmox VE operations | **proxmox-aiops** |\n| NAS/storage appliance operations | a storage-appliance ops skill |\n| Backup-software suite job/restore operations | a backup-software ops skill |\n| Container/cluster lifecycle | a cluster ops skill |\n\n## Common Workflows\n\nEach recipe starts from a read or an RCA and ends in a governed write. Every\nwrite accepts `--dry-run`; destructive ones also double-confirm.\n\n### 1. \"Patch a pool without breaking live migration\"\n\n1. `xcpng-aiops overview` → fleet snapshot: pools, hosts, VMs by state, SRs near full, recent backup failures.\n2. `xcpng-aiops pool posture` → the RCA: hosts missing patches, hosts pending reboot, **version skew** across the pool's hosts, and multi-host pools without HA.\n3. `xcpng-aiops host missing-patches ` → what exactly is outstanding on the host you plan to take first.\n4. `xcpng-aiops vm list --state Running` → the VMs that must move off that host.\n5. For each: `xcpng-aiops vm migrate --dry-run`, then re-run for real (double confirm; the REAL source host is captured before the move and the inverse \"migrate back\" is recorded).\n6. `xcpng-aiops undo list` → confirm a migrate-back token exists for every VM you moved, before you touch the host.\n7. Patch and reboot the host in XO, then `xcpng-aiops pool posture` again to confirm the skew cleared.\n\n**Failure branch**: if `pool posture` reports version skew *before* you start, stop — live migration between mismatched host versions can be refused or unsafe. Bring the hosts to a common version first. If a migration fails mid-run, do not retry blindly: `xcpng-aiops vm get ` to see where the VM actually landed, and `xcpng-aiops task list` for the failing XO task, since a half-finished migrate leaves the VM on one side or the other.\n\n### 2. \"This VM keeps going unhealthy\"\n\n1. `xcpng-aiops vm health-rca` → findings with cause + action: halted unexpectedly (auto-poweron / HA restart priority set), paused or suspended VMs, running VMs without guest tools, CPU/memory pressure from RRD stats.\n2. `xcpng-aiops vm get ` → the VM's configuration and current power state.\n3. `xcpng-aiops vm stats ` → the RRD series behind a pressure finding, so you confirm sustained pressure rather than one spike.\n4. If it is halted and should be running: `xcpng-aiops vm start ` (the inverse `vm_stop` is recorded).\n5. If it is wedged and needs a bounce: `xcpng-aiops vm reboot --dry-run`, then for real (double confirm; add `--force` only for a hard reboot — **no undo** either way).\n6. `xcpng-aiops vm health-rca` again to confirm the finding cleared.\n\n**Failure branch**: if a clean shutdown or clean reboot hangs, the finding \"no guest tools\" is usually the real cause — clean actions need the guest agent. Do not escalate straight to `--force`; a hard action risks filesystem damage. Snapshot first (recipe 3), then use `--force` deliberately.\n\n### 3. \"Snapshot before a risky change, and roll back cleanly\"\n\n1. `xcpng-aiops vm list` → confirm the exact VM uuid.\n2. `xcpng-aiops sr usage-rca` → make sure the SR has room; snapshots grow it, and a snapshot on a near-full SR is how you take the pool down.\n3. `xcpng-aiops snapshot create pre-change` → XO returns the new snapshot's id, and an inverse `snapshot_delete` for **that** id is recorded.\n4. `xcpng-aiops snapshot list --vm ` → confirm the snapshot exists before you change anything.\n5. Make your change. If it went wrong: `xcpng-aiops snapshot revert ` (double confirm — replaces current state, **IRREVERSIBLE**, no undo).\n6. When you are satisfied: `xcpng-aiops snapshot delete --dry-run`, then without `--dry-run` (double confirm — **IRREVERSIBLE**, BEFORE state captured for the audit record, no undo).\n\n**Failure branch**: if `sr usage-rca` flags the SR as near-full or thin-provision overcommitted, do not snapshot — reclaim first (recipe 4). If a revert is refused or leaves the VM halted, check `xcpng-aiops task list` for the XO task; and never leave snapshots stacked long-term, because unmerged chains are the usual root cause of the vdi-chain backup failures in recipe 4.\n\n### 4. \"Backups have been failing every night and storage is filling up\"\n\n1. `xcpng-aiops backup failure-rca` → failed/skipped/interrupted runs grouped by job and classified: **vdi-chain** (coalesce not finished), **quiesce** (guest VSS), **transport** (remote unreachable), **storage-full**, unknown.\n2. `xcpng-aiops backup logs -n 20` → the raw recent runs behind that classification.\n3. `xcpng-aiops sr usage-rca` → SRs ranked by physical fullness, thin-provision overcommit, and **orphaned VDIs** (attached to no VM) with reclaimable bytes per SR.\n4. `xcpng-aiops sr vdis --sr --orphaned-only` → the specific orphaned VDIs worth reclaiming on that SR.\n5. For a **vdi-chain** classification: let the coalesce finish, stop stacking snapshots (`xcpng-aiops snapshot list`), then `xcpng-aiops sr rescan --dry-run` and for real (lowest-impact write) so XO re-reads the SR.\n6. For **storage-full**: reclaim space, then re-run `sr usage-rca` to confirm the SR dropped below the near-full threshold.\n7. `xcpng-aiops backup logs -n 20` after the next scheduled run to confirm it went green.\n\n**Failure branch**: a **transport** classification is not an XCP-ng problem — the backup remote is unreachable, so fix the remote in the XO UI (Settings → Remotes); rescanning the SR will not help. A **quiesce** classification means the guest agent could not freeze the filesystem: fix guest tools on that VM rather than disabling quiesce fleet-wide. If `sr rescan` does not shrink the chain, the coalesce is still running — wait rather than rescanning in a loop, which will trip the runaway budget guard.\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 (29 — 19 read, 8 write, 2 undo)\n\n| Category | Tools | R/W |\n|----------|-------|:---:|\n| Overview | `overview` | Read |\n| VMs | `vm_list`, `vm_get`, `vm_stats`, `vm_health_rca` | Read |\n| | `vm_start`, `vm_stop`, `vm_reboot`, `vm_migrate` | Write |\n| Hosts | `host_list`, `host_get` | Read |\n| Pools | `pool_list`, `pool_get`, `pool_patch_ha_posture` | Read |\n| SRs / VDIs | `sr_list`, `sr_get`, `vdi_list`, `sr_usage_rca` | Read |\n| | `sr_rescan` | Write |\n| Snapshots | `snapshot_list` | Read |\n| | `snapshot_create`, `snapshot_delete`, `snapshot_revert` | Write |\n| Backups | `backup_job_list`, `backup_log_list`, `backup_failure_rca` | Read |\n| Tasks | `task_list` | Read |\n| Undo | `undo_list`, `undo_apply` | Read + replay |\n\n**Harness features that light up**: `vm_start`↔`vm_stop` record each other as inverses (with `_undo_id`); `vm_migrate` captures the REAL source host BEFORE moving and records \"migrate back\"; `snapshot_create` captures the REAL snapshot id from the XO response and records \"delete THAT snapshot\". `snapshot_delete` and `snapshot_revert` are `risk_level=high`, capture BEFORE state, and declare no undo (irreversible). Every write takes `dry_run=True` (may read, never writes; no undo; audited). All 29 tools are audit-logged under `~/.xcpng-aiops/` and pass through the budget/runaway guard, each carrying a descriptive risk tier into its audit row. Start any triage with `overview`.\n\n## CLI Quick Reference\n\n```bash\nxcpng-aiops init # onboarding wizard (encrypted XO token)\nxcpng-aiops overview [--target ] # fleet health summary\nxcpng-aiops vm list [--state Running] [--pool ]\nxcpng-aiops vm get \nxcpng-aiops vm stats [-g minutes]\nxcpng-aiops vm health-rca [] # RCA: cause + action\nxcpng-aiops vm start [--dry-run]\nxcpng-aiops vm stop [--force] [--dry-run] # double confirm; refuses the declared XO VM\nxcpng-aiops vm reboot [--force] [--dry-run] # double confirm\nxcpng-aiops vm migrate [--dry-run] # double confirm\nxcpng-aiops host list / get / missing-patches \nxcpng-aiops pool list / get \nxcpng-aiops pool posture [] # RCA: patches / reboots / skew / HA\nxcpng-aiops sr list / get \nxcpng-aiops sr vdis [--sr ] [--orphaned-only]\nxcpng-aiops sr usage-rca # RCA: near-full / overcommit / orphans\nxcpng-aiops sr rescan [--dry-run]\nxcpng-aiops snapshot list [--vm ]\nxcpng-aiops snapshot create [--dry-run]\nxcpng-aiops snapshot delete [--dry-run] # double confirm, IRREVERSIBLE\nxcpng-aiops snapshot revert [--dry-run] # double confirm, IRREVERSIBLE\nxcpng-aiops backup jobs / logs [-n 50]\nxcpng-aiops backup failure-rca [-n 50] # RCA: vdi-chain / quiesce / transport\nxcpng-aiops task list [--status failure]\nxcpng-aiops secret set / list / rm / migrate / rotate-password\nxcpng-aiops doctor # XO reachability + token + pool count\nxcpng-aiops mcp # start MCP server (stdio)\n```\n\nSee `references/cli-reference.md` for the full command list, and\n`references/agent-guardrails.md` when driving these tools with a smaller /\nlocal model (the guardrails the tool enforces for you, and a ready system prompt).\n\n## Troubleshooting\n\n### \"Config file not found\"\nRun `xcpng-aiops init` to set up your first target (writes `~/.xcpng-aiops/config.yaml` and stores the XO token encrypted).\n\n### \"No XO authentication token for target ''\"\nAdd it to the encrypted store: `xcpng-aiops secret set ` (prompts hidden), or run `xcpng-aiops init`. Create the token in the XO UI (user menu → Personal tokens) or with `xo-cli --createToken`. For non-interactive use (MCP/CI), also export `XCPNG_AIOPS_MASTER_PASSWORD` so the store can be unlocked without a prompt.\n\n### \"Master password not set\" / \"Wrong master password\"\nThe encrypted store `~/.xcpng-aiops/secrets.enc` is unlocked by `XCPNG_AIOPS_MASTER_PASSWORD` (or an interactive prompt). If you forgot it, delete `secrets.enc` and re-run `xcpng-aiops init`. Rotate it with `xcpng-aiops secret rotate-password`.\n\n### \"Authentication/authorization failed (401/403)\"\nThe XO token is wrong, expired, or revoked, or the XO account lacks permission. Regenerate the token in the XO UI (user menu → Personal tokens) and update it: `xcpng-aiops secret set `.\n\n### \"Could not reach Xen Orchestra … check the XO URL\"\nConfirm the XO web UI is reachable at the configured `url` and that `api_path` is `/rest/v0` (XO 5.x). For self-signed certificates set `verify_ssl: false` on the target (lab only).\n\n### \"Resource not found (404)\"\nThe VM/SR/snapshot uuid is stale, or this XO release lacks the endpoint. List the parent collection first (`vm list`, `sr list`, `snapshot list`) to get a current uuid.\n\n### Doctor says \"manages no pools yet\"\nYour XO instance is reachable but has no XCP-ng servers connected — add them in the XO UI (Settings → Servers).\n\n## Audit & Safety\n\nThe skill delivers reads and writes and records them; it does **not** decide\nwhether a write is permitted. That is your agent's judgement, or the permission\nof the Xen Orchestra account whose token you connect it with (give that XO user\na read-only ACL or scope its token down — writes then fail at Xen Orchestra).\nThere 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 `~/.xcpng-aiops/audit.db` (relocatable via `XCPNG_AIOPS_HOME`): params (secrets redacted), result, status, duration, and the risk tier. The CLI writes the same row the MCP path does.\n- The XO token is stored **encrypted** in `~/.xcpng-aiops/secrets.enc` (Fernet/AES-128 + scrypt key derivation; chmod 600) — never plaintext on disk; the master password is never stored, only a per-store salt + ciphertext.\n- `XCPNG_AUDIT_APPROVED_BY` / `XCPNG_AUDIT_RATIONALE` are optional annotations recorded on the audit row (who/why); they are never required and never block.\n- **Budget / runaway guard** — a safety backstop, not authorization: caps cumulative tool calls and wall-time, and trips on tight task-poll loops.\n- Writes support `--dry-run` / `dry_run=True` and double confirmation at the CLI; CLI writes execute through the same governed tools, so they are audited + undo-recorded.\n- Reversible writes (`vm_start`/`vm_stop`/`vm_migrate`/`snapshot_create`) capture the real before-state and record a replayable inverse descriptor; `snapshot_delete`/`snapshot_revert` are `risk=high`, irreversible, and declare no undo.\n- **Risk tier** is a descriptive label on the audit row derived from `risk_level`; it gates nothing.\n\nThe harness is bundled in the package — no external dependency, no manual setup. See `references/setup-guide.md` for security details.\n\n## Contributing & feature requests\n\nCoverage is intentionally focused. **Missing a capability you need, or hit an endpoint that differs on your Xen Orchestra version?** Open an issue or pull request at [github.com/AIops-tools/XCPng-AIops](https://github.com/AIops-tools/XCPng-AIops/issues) — feature requests, contributions, and comments are all welcome.\n\n## License\n\nMIT — [github.com/AIops-tools/XCPng-AIops](https://github.com/AIops-tools/XCPng-AIops)\n\nFile v0.8.2:_meta.json\n\n{\n \"ownerId\": \"kn7b067awq2s97bn3d7p5qfhw5827pxc\",\n \"slug\": \"xcpng-aiops\",\n \"version\": \"0.8.2\",\n \"publishedAt\": 1789224592307\n}\n\nFile v0.8.2:references/agent-guardrails.md\n\n# Agent guardrails — running xcpng-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## Authorization is not this tool's job — decide it where it belongs\n\nWhether a write should happen is your decision, or the account's. The tool does\nnot gate it — there is no read-only switch and no approval prompt to configure.\nThe two right places to control read vs write:\n\n- **The Xen Orchestra account whose token you connect with.** Give that XO user\n a read-only ACL, or scope its personal token down. A write then fails at Xen\n Orchestra, which is the only place the permission actually lives — a revoked\n permission cannot be argued around by a model, but a skill-side flag can.\n- **Your agent's system prompt.** If you want an observe-only session, tell the\n model not to call the write tools (they are clearly tagged `[WRITE]`).\n\nWhat the tool *does* guarantee is that you can always see what happened:\n\n## What the tool 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 Xen Orchestra did not return comes back as `null`, never as `\"\"`. A VM with no `name_label`, a task with no `properties.name`, an SR with no `content_type` — all report `null`. Absent and empty are distinguishable in the payload. |\n| \"Tell me if the output was cut off\" | Every listing returns `{\"vms\": [...], \"returned\": N, \"limit\": L, \"truncated\": true/false}` (same shape with `srs`, `vdis`, `snapshots`, `tasks`, `jobs`, `logs`, `undos`). Truncation is **measured** — the full collection length client-side, or one over-fetched record for `backup_log_list` — never guessed from the row count matching the limit. The RCA tools report `inputTruncated` when the listing they correlated over was itself capped. |\n| \"Preserve the ordering / tell me what's most urgent\" | RCA findings carry an explicit `severity` (`high`/`medium`/`low`) and are already sorted worst-first, each with the measured number in `evidence` and a concrete `action`. Priority is in the payload, not implied by list position. |\n| \"Confirm before anything destructive\" | Destructive operations (`snapshot_delete`, `snapshot_revert`, `vm_stop`/`reboot`/`migrate`) require a `dry_run` preview + double confirmation at the CLI. Reversible writes capture the prior state so the undo token can restore it. |\n| \"Never stop the Xen Orchestra VM itself\" | **Only if the operator declared it.** Set `xo_self_vm_uuid` on the target and `vm_stop` refuses exactly that uuid on both the MCP and CLI paths. Undeclared, nothing is refused — XO exposes no self endpoint and its token carries no claims, so the tool cannot work this out and fails open rather than guess. Keep a prompt line for this if you cannot declare the uuid. |\n| \"Log what you did\" | Every governed call is audited to `~/.xcpng-aiops/audit.db` regardless of what the model says it did — and the CLI writes the same row the MCP path does, so there is no unaudited entry point. |\n| \"Don't get stuck retrying\" | The runaway guard trips a circuit breaker if the same call is hammered in a tight loop — a stuck agent is stopped rather than left to burn calls and time. |\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 an XCP-ng environment through the xcpng-aiops MCP tools. They talk\nto Xen Orchestra's REST API; there is no direct per-host XAPI access.\n\nTOOL USE\n- Before answering any question about the current XCP-ng 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- Start broad triage with \"overview\" — it fans out over pools, hosts, VMs, SRs\n and recent backup runs in one call.\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- Listings come back as an envelope, not a bare list: read the items under\n \"vms\" / \"srs\" / \"vdis\" / \"snapshots\" / \"tasks\" / \"jobs\" / \"logs\".\n- If \"truncated\" is true, say so and re-run with a higher limit instead of\n treating the partial result as complete. If an RCA reports \"inputTruncated\",\n its conclusion covers only a subset — state that.\n- A null field means Xen Orchestra 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 power states, SR types, statuses, or uuids.\n- When an RCA result has findings, work in the order given (worst first) and\n cite the measured number in each finding's \"evidence\".\n\nIDENTIFIERS\n- Every object is addressed by its XO uuid: a VM uuid (vm_list), a host uuid\n (host_list), a pool uuid (pool_list), an SR uuid (sr_list), a VDI uuid\n (vdi_list), a snapshot uuid (snapshot_list). They are NOT interchangeable —\n do not pass a host uuid where a VM uuid is expected.\n- A name_label is a label, not an identifier: it is not unique and must never\n be used in place of a uuid. Resolve the name to a uuid with a list tool first.\n- An XO task id (task_list) identifies an async job, not the object it acted on.\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```\n\n## Recommended setup for a local model\n\nStart with a connection that *cannot* write, verify, and widen the account's\npermission only when you trust the setup — snapshot delete/revert are\nirreversible, and stopping the wrong VM can be the one XO itself runs on:\n\n```bash\n# Give the Xen Orchestra account a read-only ACL, or scope its personal token\n# down, so writes fail at XO rather than depending on a skill-side flag. Then:\nxcpng-aiops doctor\n```\n\nOptionally annotate the audit trail with who is operating and why — recorded on\nevery row, never required:\n\n```bash\nexport XCPNG_AUDIT_APPROVED_BY=\"your.name@example.com\"\nexport XCPNG_AUDIT_RATIONALE=\"scheduled maintenance window 2026-07-20\"\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 `overview` and the four RCA\n tools (`vm_health_rca`, `sr_usage_rca`, `backup_failure_rca`,\n `pool_patch_ha_posture`) — they do the multi-step correlation inside one call,\n so the model does not have to chain reads and keep uuids straight.\n- **The model ignores later tool results in a long context.** Ask narrower\n questions and use `limit` (plus the `pool` / `sr` / `power_state` / `status`\n filters) deliberately rather than pulling whole inventories. `vdi_list` in\n particular is the longest listing in a real fleet.\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/XCPng-AIops](https://github.com/AIops-tools/XCPng-AIops/issues)\nwith the model, runtime, and what went wrong.\n\nFile v0.8.2:references/capabilities.md\n\n# xcpng-aiops — Capabilities (29 MCP tools: 19 read, 8 write, 2 undo)\n\nAll tools go through the bundled `@governed_tool` harness (audit / policy /\nbudget / undo / risk-tier). XO object ids are uuids; get them from the matching\n`*_list` tool first. Every tool takes an optional `target` (XO target name\nfrom config; omit for the default).\n\n**Listing envelopes.** `vm_list`, `sr_list`, `vdi_list`, `snapshot_list`,\n`task_list`, `backup_job_list`, `backup_log_list` and `undo_list` return\n`{: [...], \"returned\": N, \"limit\": L, \"truncated\": bool}` — read the\nitems under the named key (`vms`, `srs`, `vdis`, `snapshots`, `tasks`, `jobs`,\n`logs`, `undos`). `truncated` is measured, not guessed: filters run first, the\ncap after, and `backup_log_list` over-fetches one record. When it is true,\nre-run with a higher `limit`. The RCA tools report `inputTruncated` when the\nlisting they correlated over was itself capped.\n\n**Absent vs empty.** A field XO did not return is `null`, never `\"\"` — do not\ninfer a value for it.\n\n**Authorization.** The tool records; it does not gate. Whether a write may run\nis the agent's decision or the connecting Xen Orchestra account's permissions —\nthere is no read-only switch or approval gate. See `agent-guardrails.md`.\n\n## Overview\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `overview` | low | One-shot fleet health: pools, hosts (disabled / reboot-required / versions), VMs by power state + running-without-tools, SRs near full, recent backup failures. Start any triage here. |\n\n## VMs\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `vm_list(power_state?, pool?, limit?)` | low | VMs with power state, host, guest-tools status, sizing. |\n| `vm_get(vm_id)` | low | One VM: state, host, OS, tools, tags, start time. |\n| `vm_stats(vm_id, granularity?)` | low | Recent RRD averages: cpuAvgPercent, memoryUsedPercent. |\n| `vm_health_rca(vm_id?)` | low | **RCA**: halted-unexpectedly (auto-poweron/HA set), paused, suspended, guest-tools-missing, cpu-pressure (≥90%), memory-pressure (≥90%). Cause + severity + evidence + action per finding. Fleet mode caps stats pulls at 5 running VMs. |\n| `vm_start(vm_id, dry_run?)` | medium | Start a VM. **Undo: vm_stop** (recorded). |\n| `vm_stop(vm_id, force?, dry_run?)` | medium | Clean shutdown (hard with force). **Undo: vm_start** — only recorded if the VM was Running before. Refuses the VM declared as running XO (`xo_self_vm_uuid` on the target); with none declared there is **no** such guard — XO has no self endpoint, so it fails open rather than guess. `dry_run` refuses the declared uuid too, and returns `selfVmHint` (a possible IP coincidence, never a verdict, never a block — on either path). |\n| `vm_reboot(vm_id, force?, dry_run?)` | medium | Clean/hard reboot. Prior power state captured; **no undo**. |\n| `vm_migrate(vm_id, host_id, dry_run?)` | medium | Live-migrate. Captures the REAL source host before moving; **undo: migrate back to it**. |\n\n## Hosts\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `host_list(pool?)` | low | Hosts: version, enabled, reboot-required, memory %, resident VMs. |\n| `host_get(host_id)` | low | One host: version, build, memory, tags. |\n\n## Pools\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `pool_list()` | low | Pools with master, HA state, default SR. |\n| `pool_get(pool_id)` | low | One pool detail. |\n| `pool_patch_ha_posture(pool_id?)` | low | **RCA**: patches-missing, reboot-required, version-skew (high — breaks live migration), ha-disabled. Per-host rows + per-pool findings. |\n\n## SRs / VDIs\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `sr_list(pool?, limit?)` | low | SRs: capacity, physical usage %, virtual allocation. |\n| `sr_get(sr_id)` | low | One SR detail. |\n| `vdi_list(sr?, orphaned_only?, limit?)` | low | VDIs; `orphaned_only=true` → disks attached to no VM (reclaim candidates). |\n| `sr_usage_rca()` | low | **RCA**: sr-critical (≥95%), sr-near-full (≥85%), sr-overcommitted (allocation > capacity), orphaned-vdis with reclaimable bytes per SR. ISO SRs excluded. |\n| `sr_rescan(sr_id, dry_run?)` | medium | Metadata refresh; no data change, no undo. Lowest-impact write, but still a write. |\n\n## Snapshots\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `snapshot_list(vm_id?, limit?)` | low | VM snapshots with time and parent VM. |\n| `snapshot_create(vm_id, name, dry_run?)` | medium | Snapshot a VM. Captures the REAL new snapshot id from XO's response; **undo: delete THAT snapshot**. |\n| `snapshot_delete(snapshot_id, dry_run?)` | **high** | IRREVERSIBLE. Captures BEFORE state (name/time/VM); no undo. |\n| `snapshot_revert(snapshot_id, dry_run?)` | **high** | IRREVERSIBLE — replaces the VM's current state. Captures snapshot state; no undo. Take a fresh snapshot first. |\n\n## Backups\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `backup_job_list(limit?)` | low | VM backup jobs (id, name, mode). |\n| `backup_log_list(limit?)` | low | Recent run logs: status + failed-task messages. |\n| `backup_failure_rca(limit?)` | low | **RCA**: failures per job classified — vdi-chain (coalesce), quiesce (guest VSS), transport (remote unreachable), storage-full, unknown. Counts + sample findings + action per class. |\n\n## Tasks\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `task_list(status?, limit?)` | low | XO tasks (pending / success / failure). |\n\n## Write semantics\n\n- `dry_run=true` → preview dict (`{\"dryRun\": true, \"would...\": {...}}`). A dry-run **may\n read** — resolving ids and evaluating guards is what lets it tell you the call would be\n refused — but **never writes** and records **no undo**. It runs through `@governed_tool`\n like any other call, so it is audited and it can be refused. The CLI `--dry-run` routes\n through the same governed function, so both entry points behave identically.\n- Successful reversible writes return `_undo_id` referencing the recorded inverse descriptor in `~/.xcpng-aiops/undo.db`. Undo execution is an external orchestrator's job — recording only.\n- High-risk tools (`snapshot_delete`, `snapshot_revert`) require a `dry_run` preview + double confirmation at the CLI. `XCPNG_AUDIT_APPROVED_BY` / `XCPNG_AUDIT_RATIONALE` are optional annotations recorded on the audit row — never required, never blocking.\n\nFile v0.8.2:references/cli-reference.md\n\n# xcpng-aiops — CLI reference\n\nGlobal pattern: `xcpng-aiops [args] [--target ]`.\n`--target/-t` selects a Xen Orchestra target from `~/.xcpng-aiops/config.yaml`\n(default: the first one). Write commands support `--dry-run` (prints the API\ncall, changes nothing) and destructive ones require **double confirmation**.\n\n## Setup & health\n\n```bash\nxcpng-aiops init # onboarding wizard: XO URL, TLS verify (default yes), encrypted token\nxcpng-aiops doctor [--skip-auth] # config + secret store + XO reachability + pool count\nxcpng-aiops overview [-t xo1] # one-shot fleet health summary (JSON)\nxcpng-aiops mcp # start the MCP server (stdio)\n```\n\n## VMs\n\n```bash\nxcpng-aiops vm list [--state Running|Halted|Paused|Suspended] [--pool ] [--limit 200]\nxcpng-aiops vm get \nxcpng-aiops vm stats [--granularity seconds|minutes|hours|days]\nxcpng-aiops vm health-rca [] # RCA (fleet-wide when uuid omitted)\nxcpng-aiops vm start [--dry-run] # governed; undo = stop\nxcpng-aiops vm stop [--force] [--dry-run] # double confirm; undo = start\nxcpng-aiops vm reboot [--force] [--dry-run] # double confirm; no undo\nxcpng-aiops vm migrate [--dry-run] # double confirm; undo = migrate back\n```\n\n`--force` = hard power operation (no guest tools needed); default is a clean\nguest shutdown/reboot.\n\n## Hosts\n\n```bash\nxcpng-aiops host list [--pool ]\nxcpng-aiops host get \nxcpng-aiops host missing-patches \n```\n\n## Pools\n\n```bash\nxcpng-aiops pool list\nxcpng-aiops pool get \nxcpng-aiops pool posture [] # RCA: patches / reboots / version skew / HA\n```\n\n## Storage (SRs / VDIs)\n\n```bash\nxcpng-aiops sr list [--pool ] [--limit 200]\nxcpng-aiops sr get \nxcpng-aiops sr vdis [--sr ] [--orphaned-only] [--limit 200]\nxcpng-aiops sr usage-rca # RCA: near-full / overcommit / orphaned VDIs\nxcpng-aiops sr rescan [--dry-run]\n```\n\n## Snapshots\n\n```bash\nxcpng-aiops snapshot list [--vm ] [--limit 200]\nxcpng-aiops snapshot create [--dry-run]\nxcpng-aiops snapshot delete [--dry-run] # double confirm, IRREVERSIBLE\nxcpng-aiops snapshot revert [--dry-run] # double confirm, IRREVERSIBLE\n```\n\n## Backups & tasks\n\n```bash\nxcpng-aiops backup jobs [--limit 200]\nxcpng-aiops backup logs [--limit 50]\nxcpng-aiops backup failure-rca [--limit 50] # RCA: vdi-chain / quiesce / transport / storage-full\nxcpng-aiops task list [--status pending|success|failure] [--limit 200]\n```\n\n## Secrets (encrypted store)\n\n```bash\nxcpng-aiops secret set [--value ] # omit --value to be prompted (hidden)\nxcpng-aiops secret list # names only\nxcpng-aiops secret rm \nxcpng-aiops secret migrate # import legacy plaintext .env\nxcpng-aiops secret rotate-password # re-encrypt under a new master password\n```\n\n## Environment variables\n\n| Variable | Purpose |\n|----------|---------|\n| `XCPNG_AIOPS_MASTER_PASSWORD` | Unlock `secrets.enc` non-interactively (MCP/CI). |\n| `XCPNG_AIOPS_HOME` | Relocate `~/.xcpng-aiops` (audit.db, undo.db). |\n| `XCPNG_AIOPS_CONFIG` | Alternate config.yaml path for the MCP server. |\n| `XCPNG_AUDIT_APPROVED_BY` / `XCPNG_AUDIT_RATIONALE` | Optional approver/rationale annotations recorded on the audit row (never required). |\n| `XCPNG_MAX_TOOL_CALLS` / `XCPNG_MAX_TOOL_SECONDS` | Budget ceilings. |\n| `XCPNG_RUNAWAY_MAX` / `XCPNG_RUNAWAY_WINDOW_SEC` | Runaway-loop circuit breaker. |\n| `XCPNG__TOKEN` | Legacy plaintext token fallback (deprecated). |\n\n## Truncation\n\nListing commands cap their output at `--limit` (default 200) and print\n`… showing N of more … — truncated, re-run with a higher --limit` when there\nwas more; the JSON itself carries `\"truncated\": true`.\n\nFile v0.8.2:references/setup-guide.md\n\n# xcpng-aiops — Setup & security guide\n\n## Prerequisites\n\n- A **Xen Orchestra instance** (XO from sources or the Xen Orchestra\n Appliance, 5.x) with the REST API at `/rest/v0`. XO is the management plane\n this tool talks to; your XCP-ng hosts/pools must already be connected to it\n (XO UI → Settings → Servers). **Per-host XAPI access is out of scope.**\n- Python ≥ 3.11 (`uv tool install xcpng-aiops` handles the rest).\n\n## 1. Create an XO authentication token\n\nIn the XO UI: user menu (top-right) → **Personal tokens** → create. Or from a\nshell: `xo-cli --createToken`. Use a dedicated XO user with the least\nprivilege you can (admin is required for some collections; a read-mostly user\nworks for triage-only setups).\n\n## 2. Onboard\n\n```bash\nxcpng-aiops init\n```\n\nThe wizard prompts for:\n\n1. **Master password** — encrypts `~/.xcpng-aiops/secrets.enc`. Never stored;\n export `XCPNG_AIOPS_MASTER_PASSWORD` for non-interactive use.\n2. **Target name** (e.g. `xo1`) and the **XO URL** (e.g.\n `https://xo.example.com` — the same origin as the XO web UI).\n3. **TLS verification** — default **yes**; answer no only for self-signed lab\n certificates.\n4. **The token** (hidden input) — stored encrypted, never in config.yaml.\n\n## 3. Verify\n\n```bash\nxcpng-aiops doctor\n```\n\nChecks: config present, encrypted store present + permissions (600), token\npresent per target, XO reachable, token valid (a 401/403 fails the check), and\nhow many XCP-ng pools the XO instance manages.\n\n## Files & permissions\n\n| Path | Content | Mode |\n|------|---------|:----:|\n| `~/.xcpng-aiops/config.yaml` | non-secret connection details | 700 dir |\n| `~/.xcpng-aiops/secrets.enc` | Fernet-encrypted token map | 600 |\n| `~/.xcpng-aiops/audit.db` | SQLite audit log (every tool call) | — |\n| `~/.xcpng-aiops/undo.db` | recorded inverse descriptors | — |\n\nRelocate everything with `XCPNG_AIOPS_HOME`.\n\n## Security notes\n\n- The token is sent per request as `Authorization: Bearer ` **and**\n `Cookie: authenticationToken=` (compatibility across XO 5.x\n releases); held in memory only, never logged.\n- Secret encryption: Fernet (AES-128-CBC + HMAC-SHA256), key derived from the\n master password via scrypt (N=2^15, r=8, p=1) with a random per-store salt.\n- High-risk writes (`snapshot_delete`, `snapshot_revert`) require a `dry_run`\n preview + double confirmation at the CLI, and carry a `high` risk tier as a\n descriptive audit label — it gates nothing. `XCPNG_AUDIT_APPROVED_BY` /\n `XCPNG_AUDIT_RATIONALE` are optional annotations recorded on the audit row,\n never required.\n- Budget guard: `XCPNG_MAX_TOOL_CALLS` (default ceiling on calls per process)\n and `XCPNG_MAX_TOOL_SECONDS` (cumulative wall-time), plus a runaway breaker\n for tight poll loops.\n- No outbound traffic except the configured XO endpoint. No telemetry.\n\n## MCP client setup\n\n```json\n{\n \"mcpServers\": {\n \"xcpng-aiops\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"xcpng-aiops\", \"xcpng-aiops-mcp\"],\n \"env\": { \"XCPNG_AIOPS_MASTER_PASSWORD\": \"your-master-password\" }\n }\n }\n}\n```\n\nMCP clients do **not** inherit your shell environment — the master password\n(and any `XCPNG_*` overrides) must be in the `env` block.\n\nFile v0.8.2:skill-card.md\n\n## Description:\n\nxcpng-aiops helps agents operate and triage XCP-ng virtualization fleets through Xen Orchestra, covering fleet health, VM, host, pool, storage, snapshot, backup, and task workflows with RCA analyses and governed writes.\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, SREs, and virtualization administrators use this skill to inspect, diagnose, and operate XCP-ng fleets managed by Xen Orchestra. It supports read workflows, RCA summaries, and guarded write actions such as VM lifecycle operations, migration, snapshots, and SR rescans.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: High-impact infrastructure write actions can affect production VMs, snapshots, storage repositories, and migration workflows.\n\nMitigation: Use a dedicated least-privilege Xen Orchestra account, prefer read-only tokens for triage, run dry-run previews before write tools, and reserve production writes for reviewed maintenance windows.\n\nRisk: Mutable package execution can change behavior if the installed executable is not pinned or verified.\n\nMitigation: Pin and verify the xcpng-aiops package version before using write tools on production infrastructure.\n\nRisk: Weak built-in authorization controls mean the skill records actions but does not decide whether a write is allowed.\n\nMitigation: Enforce authorization through Xen Orchestra ACLs or scoped tokens, and protect local MCP configuration and ~/.xcpng-aiops permissions.\n\nRisk: Credential exposure could allow unintended access to Xen Orchestra.\n\nMitigation: Avoid storing XCPNG_AIOPS_MASTER_PASSWORD in synced or version-controlled configuration, and protect the encrypted secret store and MCP client config.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/zw008/skills/xcpng-aiops)\n- [Project homepage](https://github.com/AIops-tools/XCPng-AIops)\n- [Project issues](https://github.com/AIops-tools/XCPng-AIops/issues)\n- [Capabilities reference](artifact/references/capabilities.md)\n- [CLI reference](artifact/references/cli-reference.md)\n- [Setup and security guide](artifact/references/setup-guide.md)\n- [Agent guardrails](artifact/references/agent-guardrails.md)\n\n## Skill Output:\n\n**Output Type(s):** [Analysis, Guidance, Shell commands, Configuration]\n\n**Output Format:** [Markdown with inline commands and structured tool results]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include Xen Orchestra object identifiers, RCA findings, dry-run previews, and audit-oriented operational guidance.]\n\n## Skill Version(s):\n\n0.8.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.8.1: 7 files, 21035 bytes\n\nFiles: references/agent-guardrails.md (7975b), references/capabilities.md (6380b), references/cli-reference.md (4010b), references/setup-guide.md (3226b), skill-card.md (2441b), SKILL.md (21959b), _meta.json (130b)\n\nFile v0.8.1:SKILL.md\n\n---\nname: xcpng-aiops\nslug: xcpng-aiops\ndisplayName: \"XCP-ng AIops\"\nsummary: \"Governed XCP-ng ops via Xen Orchestra — 29 MCP tools with audit, budget, undo guards.\"\nlicense: MIT\nhomepage: https://github.com/AIops-tools/XCPng-AIops\ntags: [aiops, mcp, governance, xcpng]\ndescription: >\n Use this skill whenever the user needs to operate an XCP-ng virtualization fleet through Xen Orchestra — a one-shot fleet health overview; VMs (list/get/RRD stats), hosts, pools, storage repositories (SRs) and VDIs, VM snapshots, backup jobs and run logs, XO tasks; four RCA analyses (VM health, SR usage, backup-job failures, pool patch & HA posture); and governed writes (VM start/stop/reboot/migrate, snapshot create/delete/revert, SR rescan).\n Always use this skill for \"xcp-ng vm\", \"xen orchestra\", \"xo backup failed\", \"sr full\", \"orphaned vdi\", \"xcp-ng snapshot\", \"migrate vm to another host\", \"xcp-ng patches\", or \"pool HA\" when the context is explicitly XCP-ng / Xen Orchestra / a Xen-based fleet.\n Do NOT use when the target is not an XCP-ng fleet managed by Xen Orchestra — other hypervisors (Do NOT use for Proxmox VE — use proxmox-aiops), NAS/storage appliances, backup software suites, container clusters, and network devices are out of scope (negative routing hints only).\n Common XCP-ng-via-XO operations with a built-in governance harness (audit, policy, token budget, und\n\nArchive v0.8.0: 7 files, 21210 bytes\n\nFiles: references/agent-guardrails.md (7975b), references/capabilities.md (6380b), references/cli-reference.md (4010b), references/setup-guide.md (3226b), skill-card.md (3193b), SKILL.md (21649b), _meta.json (130b)\n\nArchive v0.7.0: 7 files, 21145 bytes\n\nFiles: references/agent-guardrails.md (7975b), references/capabilities.md (6380b), references/cli-reference.md (4010b), references/setup-guide.md (3226b), skill-card.md (2881b), SKILL.md (21751b), _meta.json (130b)\n\nArchive v0.6.0: 7 files, 20960 bytes\n\nFiles: references/agent-guardrails.md (7975b), references/capabilities.md (6380b), references/cli-reference.md (4010b), references/setup-guide.md (3226b), skill-card.md (2718b), SKILL.md (21751b), _meta.json (130b)\n\nArchive v0.5.0: 7 files, 21001 bytes\n\nFiles: references/agent-guardrails.md (7975b), references/capabilities.md (6380b), references/cli-reference.md (4010b), references/setup-guide.md (3226b), skill-card.md (2733b), SKILL.md (21751b), _meta.json (130b)\n\nArchive v0.4.0: 7 files, 21104 bytes\n\nFiles: references/agent-guardrails.md (7975b), references/capabilities.md (6380b), references/cli-reference.md (4010b), references/setup-guide.md (3226b), skill-card.md (2973b), SKILL.md (21751b), _meta.json (130b)\n\nArchive v0.3.0: 7 files, 20504 bytes\n\nFiles: references/agent-guardrails.md (6982b), references/capabilities.md (6218b), references/cli-reference.md (4151b), references/setup-guide.md (3351b), skill-card.md (2976b), SKILL.md (21177b), _meta.json (130b)","readmeExcerpt":"Skill: xcpng-aiops Owner: zw008 Summary: Use this skill whenever the user needs to operate an XCP-ng virtualization fleet through Xen Orchestra — a one-shot fleet health overview; VMs (list/get/RRD stats), hosts, pools, storage repositories (SRs) and VDIs, VM snapshots, backup jobs and run logs, XO tasks; four RCA analyses (VM health, SR usage, backup-job failures, pool patch & HA posture); and governed writes (VM st","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"uv tool install xcpng-aiops\nxcpng-aiops init # interactive wizard: XO URL + encrypted token\nxcpng-aiops doctor # XO reachability + token validity + pool count"},{"language":"bash","snippet":"openclaw plugins install clawhub:@zw008/xcpng-aiops\nopenclaw skills info xcpng-aiops # expect: Visible to model: yes"},{"language":"bash","snippet":"xcpng-aiops init # onboarding wizard (encrypted XO token)\nxcpng-aiops overview [--target ] # fleet health summary\nxcpng-aiops vm list [--state Running] [--pool ]\nxcpng-aiops vm get \nxcpng-aiops vm stats [-g minutes]\nxcpng-aiops vm health-rca [] # RCA: cause + action\nxcpng-aiops vm start [--dry-run]\nxcpng-aiops vm stop [--force] [--dry-run] # double confirm; refuses the declared XO VM\nxcpng-aiops vm reboot [--force] [--dry-run] # double confirm\nxcpng-aiops vm migrate [--dry-run] # double confirm\nxcpng-aiops host list / get / missing-patches \nxcpng-aiops pool list / get \nxcpng-aiops pool posture [] # RCA: patches / reboots / skew / HA\nxcpng-aiops sr list / get \nxcpng-aiops sr vdis [--sr ] [--orphaned-only]\nxcpng-aiops sr usage-rca # RCA: near-full / overcommit / orphans\nxcpng-aiops sr rescan [--dry-run]\nxcpng-aiops snapshot list [--vm ]\nxcpng-aiops snapshot create [--dry-run]\nxcpng-aiops snapshot delete [--dry-run] # double confirm, IRREVERSIBLE\nxcpng-aiops snapshot revert [--dry-run] # double confirm, IRREVERSIBLE\nxcpng-aiops backup jobs / logs [-n 50]\nxcpng-aiops backup failure-rca [-n 50] # RCA: vdi-chain / quiesce / transport\nxcpng-aiops task list [--status failure]\nxcpng-aiops secret set / list / rm / migrate / rotate-password\nxcpng-aiops doctor # XO reachability + token + pool count\nxcpng-aiops mcp # start MCP server (stdio)"},{"language":"text","snippet":"You operate an XCP-ng environment through the xcpng-aiops MCP tools. They talk\nto Xen Orchestra's REST API; there is no direct per-host XAPI access.\n\nTOOL USE\n- Before answering any question about the current XCP-ng 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- Start broad triage with \"overview\" — it fans out over pools, hosts, VMs, SRs\n and recent backup runs in one call.\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- Listings come back as an envelope, not a bare list: read the items under\n \"vms\" / \"srs\" / \"vdis\" / \"snapshots\" / \"tasks\" / \"jobs\" / \"logs\".\n- If \"truncated\" is true, say so and re-run with a higher limit instead of\n treating the partial result as complete. If an RCA reports \"inputTruncated\",\n its conclusion covers only a subset — state that.\n- A null field means Xen Orchestra 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 power states, SR types, statuses, or uuids.\n- When an RCA result has findings, work in the order given (worst first) and\n cite the measured number in each finding's \"evidence\".\n\nIDENTIFIERS\n- Every object is addressed by its XO uuid: a VM uuid (vm_list), a host uuid\n (host_list), a pool uuid (pool_list), an SR uuid (sr_list), a VDI uuid\n (vdi_list), a snapshot uuid (snapshot_list). They are NOT interchangeable —\n do not pass a host uuid where a VM uuid is expected.\n- A name_label is a label, not an identifier: it is not unique and must never\n be used in place of a uuid. Resolve the name to a uuid with a list tool first.\n- An XO task id (task_list) identifies an async job, not the object it acted on.\n\nSCOPE\n- Separate observation from interpretation. State what the tools "},{"language":"bash","snippet":"# Give the Xen Orchestra account a read-only ACL, or scope its personal token\n# down, so writes fail at XO rather than depending on a skill-side flag. Then:\nxcpng-aiops doctor"},{"language":"bash","snippet":"export XCPNG_AUDIT_APPROVED_BY=\"your.name@example.com\"\nexport XCPNG_AUDIT_RATIONALE=\"scheduled maintenance window 2026-07-20\""}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: xcpng-aiops\nslug: xcpng-aiops\ndisplayName: \"XCP-ng AIops\"\nsummary: \"Governed XCP-ng ops via Xen Orchestra — 29 MCP tools with audit, budget, undo guards.\"\nlicense: MIT\nhomepage: https://github.com/AIops-tools/XCPng-AIops\ntags: [aiops, mcp, governance, xcpng]\ndescription: >\n Use this skill whenever the user needs to operate an XCP-ng virtualization fleet through Xen Orchestra — a one-shot fleet health overview; VMs (list/get/RRD stats), hosts, pools, storage repositories (SRs) and VDIs, VM snapshots, backup jobs and run logs, XO tasks; four RCA analyses (VM health, SR usage, backup-job failures, pool patch & HA posture); and governed writes (VM start/stop/reboot/migrate, snapshot create/delete/revert, SR rescan).\n Always use this skill for \"xcp-ng vm\", \"xen orchestra\", \"xo backup failed\", \"sr full\", \"orphaned vdi\", \"xcp-ng snapshot\", \"migrate vm to another host\", \"xcp-ng patches\", or \"pool HA\" when the context is explicitly XCP-ng / Xen Orchestra / a Xen-based fleet.\n Do NOT use when the target is not an XCP-ng fleet managed by Xen Orchestra — other hypervisors (Do NOT use for Proxmox VE — use proxmox-aiops), NAS/storage appliances, backup software suites, container clusters, and network devices are out of scope (negative routing hints only).\n Common XCP-ng-via-XO operations with a built-in governance harness (audit, policy, token budget, undo, risk-tiers).\ninstaller:\n kind: uv\n package: xcpng-aiops\nargument-hint: \"[vm/sr/snapshot uuid or describe your XCP-ng task]\"\nallowed-tools:\n - Bash\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"xcpng-aiops\",\"uvx\"]},\"optional\":{\"env\":[\"XCPNG_AIOPS_CONFIG\",\"XCPNG_AIOPS_MASTER_PASSWORD\"]},\"homepage\":\"https://github.com/AIops-tools/XCPng-AIops\",\"emoji\":\"🖥️\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n Standalone, self-governed XCP-ng operations via Xen Orchestra's REST API /rest/v0. REQUIRES a Xen Orchestra instance (XO from sources or the Xen Orchestra Appliance, 5.x) — XO is the management plane; direct per-host XAPI access is out of scope for v0.1. The governance harness (audit, policy, token/runaway budget, undo, risk-tiers) is bundled in the package — no external skill-family dependency.\n All write operations are audited to a local SQLite DB under ~/.xcpng-aiops/ (relocatable via XCPNG_AIOPS_HOME).\n Credentials: Each XO target's personal authentication token is stored ENCRYPTED in ~/.xcpng-aiops/secrets.enc (Fernet/AES-128 + scrypt-derived key) — never plaintext on disk. Run 'xcpng-aiops init' to onboard, or 'xcpng-aiops secret set ' to add one (create the token in the XO UI: user menu → Personal tokens, or `xo-cli --createToken`). The store is unlocked by a master password from XCPNG_AIOPS_MASTER_PASSWORD (non-interactive/MCP/CI) or an interactive prompt (CLI on a TTY). A legacy plaintext env var XCPNG__TOKEN is still honoured as a fallback with a deprecation warning (migrate with 'xcpng-aiops secret migrate'). The token is sent in headers (Authorization: Bear"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7b067awq2s97bn3d7p5qfhw5827pxc\",\n \"slug\": \"xcpng-aiops\",\n \"version\": \"0.8.4\",\n \"publishedAt\": 1789535956634\n}"},{"path":"references/agent-guardrails.md","content":"# Agent guardrails — running xcpng-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## Authorization is not this tool's job — decide it where it belongs\n\nWhether a write should happen is your decision, or the account's. The tool does\nnot gate it — there is no read-only switch and no approval prompt to configure.\nThe two right places to control read vs write:\n\n- **The Xen Orchestra account whose token you connect with.** Give that XO user\n a read-only ACL, or scope its personal token down. A write then fails at Xen\n Orchestra, which is the only place the permission actually lives — a revoked\n permission cannot be argued around by a model, but a skill-side flag can.\n- **Your agent's system prompt.** If you want an observe-only session, tell the\n model not to call the write tools (they are clearly tagged `[WRITE]`).\n\nWhat the tool *does* guarantee is that you can always see what happened:\n\n## What the tool 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 Xen Orchestra did not return comes back as `null`, never as `\"\"`. A VM with no `name_label`, a task with no `properties.name`, an SR with no `content_type` — all report `null`. Absent and empty are distinguishable in the payload. |\n| \"Tell me if the output was cut off\" | Every listing returns `{\"vms\": [...], \"returned\": N, \"limit\": L, \"truncated\": true/false}` (same shape with `srs`, `vdis`, `snapshots`, `tasks`, `jobs`, `logs`, `undos`). Truncation is **measured** — the full collection length client-side, or one over-fetched record for `backup_log_list` — never guessed from the row count matching the limit. The RCA tools report `inputTruncated` when the listing they correlated over was itself capped. |\n| \"Preserve the ordering / tell me what's most urgent\" | RCA findings carry an explicit `severity` (`high`/`medium`/`low`) and are already sorted worst-first, each with the measured number in `evidence` and a concrete `action`. Priority is in the payload, not implied by list position. |\n| \"Confirm before anything destructive\" | Destructive operations (`snapshot_delete`, `snapshot_revert`, `vm_stop`/`reboot`/`migrate`) require a `dry_run` preview + double confirmation at the CLI. Reversible writes capture the prior state so the undo token can restore it. |\n| \"Never stop the Xen Orchestra VM itself\" | **Only if the operator declared it.** Set `xo_self_vm_uuid` on the target a"},{"path":"references/capabilities.md","content":"# xcpng-aiops — Capabilities (29 MCP tools: 19 read, 8 write, 2 undo)\n\nAll tools go through the bundled `@governed_tool` harness (audit / policy /\nbudget / undo / risk-tier). XO object ids are uuids; get them from the matching\n`*_list` tool first. Every tool takes an optional `target` (XO target name\nfrom config; omit for the default).\n\n**Listing envelopes.** `vm_list`, `sr_list`, `vdi_list`, `snapshot_list`,\n`task_list`, `backup_job_list`, `backup_log_list` and `undo_list` return\n`{: [...], \"returned\": N, \"limit\": L, \"truncated\": bool}` — read the\nitems under the named key (`vms`, `srs`, `vdis`, `snapshots`, `tasks`, `jobs`,\n`logs`, `undos`). `truncated` is measured, not guessed: filters run first, the\ncap after, and `backup_log_list` over-fetches one record. When it is true,\nre-run with a higher `limit`. The RCA tools report `inputTruncated` when the\nlisting they correlated over was itself capped.\n\n**Absent vs empty.** A field XO did not return is `null`, never `\"\"` — do not\ninfer a value for it.\n\n**Authorization.** The tool records; it does not gate. Whether a write may run\nis the agent's decision or the connecting Xen Orchestra account's permissions —\nthere is no read-only switch or approval gate. See `agent-guardrails.md`.\n\n## Overview\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `overview` | low | One-shot fleet health: pools, hosts (disabled / reboot-required / versions), VMs by power state + running-without-tools, SRs near full, recent backup failures. Start any triage here. |\n\n## VMs\n\n| Tool | Risk | Description |\n|------|------|-------------|\n| `vm_list(power_state?, pool?, limit?)` | low | VMs with power state, host, guest-tools status, sizing. |\n| `vm_get(vm_id)` | low | One VM: state, host, OS, tools, tags, start time. |\n| `vm_stats(vm_id, granularity?)` | low | Recent RRD averages: cpuAvgPercent, memoryUsedPercent. |\n| `vm_health_rca(vm_id?)` | low | **RCA**: halted-unexpectedly (auto-poweron/HA set), paused, suspended, guest-tools-missing, cpu-pressure (≥90%), memory-pressure (≥90%). Cause + severity + evidence + action per finding. Fleet mode caps stats pulls at 5 running VMs. |\n| `vm_start(vm_id, dry_run?)` | medium | Start a VM. **Undo: vm_stop** (recorded). |\n| `vm_stop(vm_id, force?, dry_run?)` | medium | Clean shutdown (hard with force). **Undo: vm_start** — only recorded if the VM was Running before. Refuses the VM declared as running XO (`xo_self_vm_uuid` on the target); with none declared there is **no** such guard — XO has no self endpoint, so it fails open rather than guess. `dry_run` refuses the declared uuid too, and returns `selfVmHint` (a possible IP coincidence, never a verdict, never a block — on either path). |\n| `vm_reboot(vm_id, force?, dry_run?)` | medium | Clean/hard reboot. Prior power state captured; **no undo**. |\n| `vm_migrate(vm_id, host_id, dry_run?)` | medium | Live-migrate. Captures the REAL source host before moving; **undo: migrate back to it**. |\n\n## Hosts\n\n| Tool | Risk | D"},{"path":"references/cli-reference.md","content":"# xcpng-aiops — CLI reference\n\nGlobal pattern: `xcpng-aiops [args] [--target ]`.\n`--target/-t` selects a Xen Orchestra target from `~/.xcpng-aiops/config.yaml`\n(default: the first one). Write commands support `--dry-run` (prints the API\ncall, changes nothing) and destructive ones require **double confirmation**.\n\n## Setup & health\n\n```bash\nxcpng-aiops init # onboarding wizard: XO URL, TLS verify (default yes), encrypted token\nxcpng-aiops doctor [--skip-auth] # config + secret store + XO reachability + pool count\nxcpng-aiops overview [-t xo1] # one-shot fleet health summary (JSON)\nxcpng-aiops mcp # start the MCP server (stdio)\n```\n\n## VMs\n\n```bash\nxcpng-aiops vm list [--state Running|Halted|Paused|Suspended] [--pool ] [--limit 200]\nxcpng-aiops vm get \nxcpng-aiops vm stats [--granularity seconds|minutes|hours|days]\nxcpng-aiops vm health-rca [] # RCA (fleet-wide when uuid omitted)\nxcpng-aiops vm start [--dry-run] # governed; undo = stop\nxcpng-aiops vm stop [--force] [--dry-run] # double confirm; undo = start\nxcpng-aiops vm reboot [--force] [--dry-run] # double confirm; no undo\nxcpng-aiops vm migrate [--dry-run] # double confirm; undo = migrate back\n```\n\n`--force` = hard power operation (no guest tools needed); default is a clean\nguest shutdown/reboot.\n\n## Hosts\n\n```bash\nxcpng-aiops host list [--pool ]\nxcpng-aiops host get \nxcpng-aiops host missing-patches \n```\n\n## Pools\n\n```bash\nxcpng-aiops pool list\nxcpng-aiops pool get \nxcpng-aiops pool posture [] # RCA: patches / reboots / version skew / HA\n```\n\n## Storage (SRs / VDIs)\n\n```bash\nxcpng-aiops sr list [--pool ] [--limit 200]\nxcpng-aiops sr get \nxcpng-aiops sr vdis [--sr ] [--orphaned-only] [--limit 200]\nxcpng-aiops sr usage-rca # RCA: near-full / overcommit / orphaned VDIs\nxcpng-aiops sr rescan [--dry-run]\n```\n\n## Snapshots\n\n```bash\nxcpng-aiops snapshot list [--vm ] [--limit 200]\nxcpng-aiops snapshot create [--dry-run]\nxcpng-aiops snapshot delete [--dry-run] # double confirm, IRREVERSIBLE\nxcpng-aiops snapshot revert [--dry-run] # double confirm, IRREVERSIBLE\n```\n\n## Backups & tasks\n\n```bash\nxcpng-aiops backup jobs [--limit 200]\nxcpng-aiops backup logs [--limit 50]\nxcpng-aiops backup failure-rca [--limit 50] # RCA: vdi-chain / quiesce / transport / storage-full\nxcpng-aiops task list [--status pending|success|failure] [--limit 200]\n```\n\n## Secrets (encrypted store)\n\n```bash\nxcpng-aiops secret set [--value ] # omit --value to be prompted (hidden)\nxcpng-aiops secret list # names only\nxcpng-aiops secret rm \nxcpng-aiops secret migrate # import legacy plaintex"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":2256,"uniquenessScore":38,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T20:02:06.388Z","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-10T20:02:06.388Z","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-10T23:48:32.340Z","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"}]}}}