OLVM AIops

OLVM AIops

Audit availability: Real writes require a committed pending audit row and stop before contacting the platform if storage is unavailable. Reads and previews may continue with a warning; new audit rows store outcome summaries rather than full responses.

Disclaimer: Community-maintained open-source project. Not affiliated with, endorsed by, or sponsored by Oracle or the oVirt project. "Oracle", "Oracle Linux" and "oVirt" are trademarks of their owners. MIT licensed.

AI-powered operations for Oracle Linux Virtualization Manager (OLVM) and oVirt 4.5, over the engine REST API, with a built-in governance harness — an audit log that MCP and CLI calls both write to, a token/runaway budget guard, and descriptive risk tiers. Built for teams that run OLVM (often next to another hypervisor platform) and want an agent to answer "what needs attention?" with evidence from the engine, not guesses. Built on httpx and the MCP SDK, not on the pycurl-based engine SDK.

Read-only in this release: inventory, health, capacity and diagnosis. Engine actions are asynchronous — the engine answers complete long before a VM or host reaches its target state — so write tools are held back until each can confirm its own outcome. Do NOT use for XCP-ng — use xcpng-aiops. Do NOT use for Proxmox VE — use proxmox-aiops.

What this tool does, and does not, decide

It reads an OLVM / oVirt engine accurately and records every call. It does not decide what an agent may change — that belongs to the engine account you connect it with. Give that account a read-only role (such as ReadOnlyAdmin) and the engine itself enforces it.

The one thing the tool guarantees is that nothing is silent: every call, over MCP and over the CLI alike, lands an audit row in ~/.olvm-aiops/audit.db.

Running a smaller / local model? See agent-guardrails.md for what the tool already guarantees and a ready-made system prompt for the rest.

What it answers

18 MCP tools: 16 reads and diagnoses, plus the harness's undo_list / undo_apply (which have nothing to undo in a read-only release).

vm_list accepts a one-based page (CLI: olvm-aiops vm list --page 2). Keep the same limit and search, then follow nextPage until it is null. Each response includes page, returned, limit, truncated, and total: null: the engine has no atomic total-count field. The tool orders by VM name unless the search already specifies sortby; it adds an explicit asc direction to bare sorts because live OLVM 4.5.5 engines returned an empty page without it. Agents should request no more than 20 rows per call: a large MCP response can be clipped before the model sees its continuation metadata. oVirt paging is stateless, so concurrent VM changes can still duplicate or omit rows across requests; do not claim an exact fleet total from a changing inventory.

vm_capacity_summary walks VM pages within the server and returns only aggregates: VM count, configured vCPUs, physical host cores and assignment ratio. If a page limit, duplicate ID, missing CPU topology or truncated host inventory prevents a supported total, complete is false and affected totals are null. snapshotConsistent is always false: a completed walk is not an atomic engine snapshot.

Each diagnosis ranks findings worst first; every finding carries the measured signal, a cause, an action and an explicit rank. Transient states are not reported as failures: a host the engine is installing or rebooting is "in progress", alert 9000 on a host without fencing hardware is informational, and an event the host, VM or data center has since recovered from is marked superseded. Events older than 24 hours (events_window_hours) are history, not findings, and every warning-or-worse event inside the window lands in exactly one diagnosis — engine-wide alerts such as certificate expiry and missing backups included.

Built from a live engine, not from the docs

Every read was written against, and every fixture captured from, a live Oracle Linux Virtualization Manager 4.5.5-1.73.el9 engine with Keycloak enabled. Things that engine does, which this tool accounts for:

• counts, sizes and flags arrive as JSON strings, timestamps as epoch-ms numbers;
• an attached storage domain has no status in /storagedomains — status is read from each data center's storage-domain collection;
• /jobs refuses any search and returns jobs oldest first, so jobs are sorted here;
• the time search on events is unusable (formats return all or nothing), while from=<index> is an exact cursor — hence after_index and a client-side since_minutes;
• the cursor sorted newest first returns the newest events above it and skips the rest, so after_index reads oldest first;
• /ovirt-engine/services/health answers without a login, and a data center's old status alerts stay in the log after it recovers;
• login events print the SSO session id, which is redacted before events are returned.

Quick start

As a Claude Code plugin

One install gives an agent both the skill and the MCP server:

/plugin marketplace add AIops-tools/marketplace/plugin install olvm-aiops@aiops-tools

The MCP server is fetched with uv and pinned to the package version this plugin declares, so an audit row can be traced back to the code that wrote it. Credentials are still configured with olvm-aiops init — see below.

As an OpenClaw plugin

The same bundle is published on ClawHub, where one install delivers the skill and its MCP server together:

openclaw plugins install clawhub:@zw008/olvm-aiopsopenclaw skills info olvm-aiops          # expect: Visible to model: yes

Restart the OpenClaw gateway afterwards so it loads the plugin. The MCP server is fetched with uv, pinned to this exact release, so uvx has to be on PATH — without it the skill still installs but reports Visible to model: no. Credentials are configured exactly as below.

As a CLI or standalone MCP server

uv tool install olvm-aiopsolvm-aiops init        # wizard: engine URL, username with profile, CA file, encrypted passwordolvm-aiops doctor      # verify config, encrypted store, login and engine versionolvm-aiops host health # first diagnosis

init writes ~/.olvm-aiops/config.yaml (non-secret connection details) and stores the password encrypted in ~/.olvm-aiops/secrets.enc. Example:

targets:  - name: engine1    url: https://olvm-engine.example.com     # the Administration Portal origin (FQDN)    username: admin@ovirt@internalsso        # admin@internal on engines without Keycloak    ca_file: /etc/pki/olvm-engine-ca.pem     # engine CA; keeps verify_ssl on    timeout: 30                              # seconds per request; raise for busy engines

The username includes its profile. Engine-setup enables Keycloak by default since 4.5.1, which makes the admin admin@ovirt@internalsso; engines without Keycloak use admin@internal. Download the engine CA from https://<engine>/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA and connect by FQDN — the engine certificate does not cover its IP address.

For non-interactive use (MCP server, CI, cron) export the master password so the store can be unlocked without a prompt:

export OLVM_AIOPS_MASTER_PASSWORD='your-master-password'

Where that password then lives: an exported variable is readable by every process this shell starts and is recorded by shell history. On a shared or long-lived host, prefer the interactive prompt, or inject it from a secret manager for the life of the one command that needs it.

MCP client config

{  "mcpServers": {    "olvm-aiops": {      "command": "uvx",      "args": ["--from", "olvm-aiops", "olvm-aiops-mcp"],      "env": { "OLVM_AIOPS_MASTER_PASSWORD": "your-master-password" }    }  }}

Env-block caveat: MCP clients launch the server with a minimal environment — your shell profile's exports are not inherited. Put OLVM_AIOPS_MASTER_PASSWORD (and, if you use them, OLVM_AIOPS_HOME / OLVM_AIOPS_CONFIG / OLVM_AUDIT_APPROVED_BY) in the env block above, or the encrypted store cannot be unlocked and every tool returns a teaching error.

Managing secrets

olvm-aiops secret set engine1          # prompts hidden for the account passwordolvm-aiops secret list                 # names only, values never shownolvm-aiops secret rm engine1olvm-aiops secret rotate-password      # re-encrypt under a new master passwordolvm-aiops secret migrate              # import a legacy plaintext .env, then retires it

A legacy plaintext env var OLVM_<TARGET_NAME_UPPER>_PASSWORD is still honoured as a fallback with a deprecation warning (migrate with olvm-aiops secret migrate).

Governance

Every MCP tool passes through @governed_tool, and every CLI command calls the MCP tool of the same name. It records; it does not authorize.

• Audit — every call (tool, params with secrets redacted, result, status, duration, risk tier, and any operator-supplied approver/rationale) lands in ~/.olvm-aiops/audit.db (relocate with OLVM_AIOPS_HOME).
• Budget / runaway guard — a safety backstop, not an authorization gate: cumulative call and wall-time caps plus a tight-loop circuit breaker (OLVM_MAX_TOOL_CALLS, OLVM_MAX_TOOL_SECONDS, OLVM_RUNAWAY_MAX).
• Risk tier — a descriptive label on the audit row derived from risk_level; it gates nothing.
• Output hygiene — all engine-returned text is sanitized and bounded before it reaches the agent; SSO session ids in login events are redacted.

支持范围 / Supported scope

缺功能？(Missing something?) Coverage is intentionally focused. Open an issue or PR at github.com/AIops-tools/OLVM-AIops — feature requests, contributions, and comments are all welcome.

Scope & caveats

• Verification status: every read and all four diagnoses were run end to end against a live OLVM 4.5.5 engine with one KVM host, an NFS data domain and one VM. A user has since run the read-only tools against a small production engine with 8 hosts and an FC data domain, and their results matched the engine's own API — including a second run under a ReadOnlyAdmin account, where every read and all four diagnoses worked and the figures matched the Administration Portal. Not yet verified: iSCSI / Gluster domains, self-hosted engine deployments, engines without Keycloak, or engines past the scan limits. See docs/VERIFICATION.md.
• Engine only: no direct host (vdsm) access. Hosts, storage and VMs are seen the way the engine sees them.
• No writes in this release. Start/stop/migrate, maintenance and snapshots are planned once each write can confirm its own outcome rather than the engine's immediate complete.

Not for

XCP-ng (use xcpng-aiops), Proxmox VE (use proxmox-aiops), other hypervisors, NAS/storage appliances, backup suites, container clusters, or network devices.

License

MIT — github.com/AIops-tools/OLVM-AIops