Skip to main content
Glama
olvm-aiops

olvm-aiops

Official

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.

Related MCP server: proxmox-monitor

What it answers

Question

Tool

CLI

Is the engine itself healthy — certificates, backups, clock?

engine_health_rca

olvm-aiops engine health

What is wrong with my hosts?

host_health_rca

olvm-aiops host health

Is storage about to stop the engine creating disks?

storage_capacity_rca

olvm-aiops storage capacity

Why is this VM paused / not responding?

vm_health_rca

olvm-aiops vm health

How many VMs and configured vCPUs are on this engine, and what is their ratio to host cores?

vm_capacity_summary

olvm-aiops vm capacity

What happened recently? What is new since I last looked?

event_list

olvm-aiops event list

What long-running operations failed?

job_list

olvm-aiops job list --status failed

Inventory

datacenter_list, cluster_list, host_list/host_get, storage_domain_list/storage_domain_get, vm_list/vm_get, vm_stats

datacenter, cluster, host, storage, vm

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-aiops
openclaw 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-aiops
olvm-aiops init        # wizard: engine URL, username with profile, CA file, encrypted password
olvm-aiops doctor      # verify config, encrypted store, login and engine version
olvm-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 password
olvm-aiops secret list                 # names only, values never shown
olvm-aiops secret rm engine1
olvm-aiops secret rotate-password      # re-encrypt under a new master password
olvm-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

Area

Read

Write

Engine

health diagnosis (health check, clock, certificates, backups)

—

Hosts

list / get / health diagnosis

—

Storage domains

list / get (data-center-scoped status, capacity) / capacity diagnosis

—

VMs

list / get / statistics / health diagnosis

—

Data centers, clusters

list

—

Events, jobs

list (severity, paging, after_index, since_minutes; job status)

—

缺功能?(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

Available Tools

18 tools
cluster_listB
Read-only

[READ] Clusters with compatibility version, CPU type and memory over-commit policy.

Args: limit: Rows to return, 1-1000 (default 100). target: Engine target name from config; omit to use the default.

Inputs: limit, target.

datacenter_listA
Read-only

[READ] Data centers with status (up, uninitialized, maintenance…) and compat version.

Args: limit: Rows to return, 1-1000 (default 100); truncated says when more exist. target: Engine target name from config; omit to use the default.

Inputs: limit, target.

engine_health_rcaA
Read-only

[READ] Problems with the engine itself, ranked worst first, in one call.

Reads the engine's health check, its version, its clock against this machine and its summary counts, plus warning-or-worse events that name no host, VM or storage domain: engine or CA certificate expiry, missing or failed engine backups, a cluster failing its HA reservation. Those alerts appear in no other diagnosis, so call this first for "is anything wrong". Event 10803 (a storage-pool vdsm command failed) names no host and lands here: its cause names the command, which is the subject — not the engine — and its severity is the event's own. Event 2024 is a record that someone ran unlock_entity.sh by hand: it is low, and whatever the unlocked entity then did wrong is reported by its own event. Report findings in rank order and quote their signal.

Args: events_limit: Recent warning-or-worse events to correlate, 1-1000 (default 200). events_window_hours: Ignore events older than this many hours, 1-720 (default 24). target: Engine target name from config; omit to use the default.

Inputs: target, events_limit, events_window_hours.

event_listA
Read-only

[READ] Engine events at or above a severity, newest first.

To follow new events, pass the highest index you have already seen as after_index: events after it come back OLDEST first (order), so repeat with the highest index returned while truncated is true and nothing is skipped. since_minutes keeps events from the last N minutes and sets scanTruncated when older ones in the window may be missing. SSO session ids in login events are redacted.

Args: limit: Rows to return, 1-1000 (default 100); truncated says when more exist. min_severity: One of normal, warning, error, alert (default normal). page: Older pages of events (not combinable with since_minutes or after_index). after_index: Only events with a higher index than this, oldest first. since_minutes: Only events from the last N minutes (1-129600). target: Engine target name from config; omit to use the default.

Inputs: page, limit, target, after_index, +2 more.

host_getA
Read-only

[READ] One KVM host by id (see host_list).

Args: host_id: Host id. target: Engine target name from config; omit to use the default.

Inputs: host_id (required), target.

host_health_rcaA
Read-only

[READ] What needs attention on KVM hosts, ranked worst first, in one call.

Combines host status and status detail, reinstall/update flags and recent warning-or-worse events that name a host. Each finding has signal (what was measured), cause, action and rank. Hosts that the engine is installing or rebooting are reported as in progress, not failed; alert 9000 (power management not verifiable) is informational on hosts without fencing hardware. A failed guest-agent call (event 10802, a command starting with VmLogon or VmLogoff whose message names the guest agent) is a problem of a guest, not of the host that ran the call: it is reported low and carries vmCandidates, the VMs the engine reports on that host. The same command failing for another reason stays a host finding. The event names no VM, so present those as candidates to check, never as the affected VM; if that envelope has an error, or scanTruncated is true, say the candidate list is incomplete. Every event-10802 finding reports one vdsm command rather than the host's own state, so its cause names the command; do not restate it as "this host is failing" unless the host's status, external status or flags say so. It also carries relatedVmEvents: the VM-level failures the engine logged within windowSeconds on this host, which is where the operation's own failure is recorded (vm_health_rca reports that half). They are paired on time alone — say "possibly the same operation", never that the host finding is about a named VM; an empty list means none was logged, not that none was looked for. Report findings in rank order and quote their signal.

Args: events_limit: Recent warning-or-worse events to correlate, 1-1000 (default 200). events_window_hours: Ignore events older than this many hours, 1-720 (default 24); older ones are counted in eventsOutsideWindow. target: Engine target name from config; omit to use the default.

Inputs: target, events_limit, events_window_hours.

host_listA
Read-only

[READ] KVM hosts with status, SPM role, memory and VM counts.

A field the engine did not report is null, never 0. For "what is wrong with my hosts" use host_health_rca instead of reading this list yourself.

Args: limit: Rows to return, 1-1000 (default 100); truncated says when more exist. search: Engine query language, e.g. "status=up" or "status!=up". target: Engine target name from config; omit to use the default.

Inputs: limit, search, target.

job_listA
Read-only

[READ] Engine jobs (long-running operations) with status and duration.

Args: limit: Rows to return, 1-1000 (default 100). status: Only one status: started, finished, failed, aborted, unknown. target: Engine target name from config; omit to use the default.

Inputs: limit, status, target.

storage_capacity_rcaA
Read-only

[READ] Storage-domain problems ranked worst first, in one call.

Critical when free space is below the engine's critical blocker (the engine then refuses new disks and snapshots); medium below the low-space warning, or when thin disks are committed beyond capacity while space is low (low on its own); high when an attached domain is inactive, unknown or mixed. Warning-or-worse events naming a storage domain (for example "deactivated by system") are attached to it. Unattached domains such as the default image repository are skipped. A domain whose thresholds are unset (the engine reports 0) is reported low with its measured free space: nothing — not the engine, not this tool — will warn before it fills, and how full is too full is not recorded anywhere to read. Over-commit on its own is a planning limit, and its signal carries actual use next to it: do not report an over-committed domain as short of space unless a low-space or blocker finding says so. Report findings in rank order and quote their signal.

Args: events_limit: Recent warning-or-worse events to correlate, 1-1000 (default 200). events_window_hours: Ignore events older than this many hours, 1-720 (default 24). target: Engine target name from config; omit to use the default.

Inputs: target, events_limit, events_window_hours.

storage_domain_getA
Read-only

[READ] One storage domain by id, with its data-center-scoped status.

Args: domain_id: Storage domain id (see storage_domain_list). target: Engine target name from config; omit to use the default.

Inputs: domain_id (required), target.

storage_domain_listA
Read-only

[READ] Storage domains with status and capacity (free, used, committed bytes and %).

The status of an attached domain comes from its data center (statusSource); it is null — not guessed — when that could not be read (statusErrors).

Args: limit: Rows to return, 1-1000 (default 100); truncated says when more exist. target: Engine target name from config; omit to use the default.

Inputs: limit, target.

undo_applyA
Destructive

[WRITE][risk=medium] Apply a recorded undo by dispatching its inverse tool.

The inverse runs through its own governed tool, so it is audited under its own risk tier. Pass dry_run=True to preview the inverse call without executing it. A token can only be applied once.

Args: undo_id: The undoId from undo_list (or an _undo_id in a write result). dry_run: If True, preview the inverse tool + params without running it. target: Passed through to the inverse tool when it accepts a target.

Inputs: undo_id (required), target, dry_run.

undo_listA
Read-only

[READ] List recorded, not-yet-applied undo tokens (most recent first).

Each entry names the original tool, the inverse tool that undo_apply would run, and a human note. Use the undoId with undo_apply.

One extra row is read so truncated is measured rather than guessed from the row count matching the limit; when it is true, older tokens exist.

Each entry carries effectVerified. False means the original write lost its response, so the change it reverses is PROBABLE, not confirmed — check the live state before applying, and do not report the result as a restore of a state that may never have been reached.

Args: limit: Max rows to return (default 50, capped at 500). target: Unused (undo state is host-local); accepted for CLI uniformity.

Inputs: limit, target.

vm_capacity_summaryA
Read-only

[READ] Compact VM count, configured vCPUs, host cores and assignment ratio.

Walks VM pages inside the server; no VM rows enter the model context. A completed walk is not an atomic snapshot if the inventory changes during it. Missing CPU values, duplicate VM ids, or page/host limits make complete false and prevent unsupported totals.

Args: page_size: VM rows per engine request, 1-1000 (default 100). max_pages: Maximum VM pages to walk, 1-100 (default 100). target: Engine target name from config; omit to use the default.

Inputs: target, max_pages, page_size.

vm_getB
Read-only

[READ] One VM by id (see vm_list).

Args: vm_id: VM id. target: Engine target name from config; omit to use the default.

Inputs: vm_id (required), target.

vm_health_rcaA
Read-only

[READ] VM problems ranked worst first, in one call.

High for VMs stuck not_responding/unknown, paused (often storage I/O errors or a full domain — check storage_capacity_rca), or down with high availability; medium for image_locked; info for VMs mid-transition; low for config changes waiting for a restart. Recent warning-or-worse events naming a VM are attached to it, one finding per VM and code; an event is superseded (info) when the VM started after it, or when the engine reported it back up and it is up now. Down VMs without HA are normal. Report findings in rank order and quote their signal.

Args: events_limit: Recent warning-or-worse events to correlate, 1-1000 (default 200). events_window_hours: Ignore events older than this many hours, 1-720 (default 24); older ones are counted in eventsOutsideWindow. target: Engine target name from config; omit to use the default.

Inputs: target, events_limit, events_window_hours.

vm_listA
Read-only

[READ] VMs with status, host, vCPUs, memory and high-availability flag.

Args: limit: Rows per page, 1-1000 (default 100); agents should use 20 or fewer so the model sees the entire page and its continuation metadata. search: Engine criteria, e.g. "status=up" or "cluster=Default"; omit page. target: Engine target name from config; omit to use the default. page: One-based page number (default 1). Follow nextPage until null.

Inputs: page, limit, search, target.

vm_statsA
Read-only

[READ] A VM's current statistics: memory, CPU %, network and disk usage, with units.

Args: vm_id: VM id. target: Engine target name from config; omit to use the default.

Inputs: vm_id (required), target.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 18 tools

    Disambiguation5/5

    Each tool targets a distinct resource+action, and the descriptions actively steer the agent away from overlap (host_list explicitly says to use host_health_rca for 'what is wrong with my hosts'; the four *_rca tools are scoped to disjoint signal sources — engine-only events, host-named events, VM-named events, storage-domain findings). Lists vs. get vs. stats vs. capacity-summary vs. RCA are cleanly separated, and undo_list/undo_apply are unambiguous.

    Naming Consistency5/5

    Uniform snake_case with a resource-first, action-last pattern throughout: <resource>_list, <resource>_get, <resource>_health_rca, <resource>_capacity_rca, undo_apply. The only variation (storage_capacity_rca vs. storage_domain_list) is a resource qualifier, not a convention break, and it stays readable.

    Tool Count4/5

    18 tools is slightly above the ideal 3-15 band, but each earns its place across four inventory domains plus one diagnostic and one control path; there is no filler. It reads as reasonable-but-heavy rather than bloated.

    Completeness4/5

    Read/observability coverage is thorough — datacenter, cluster, host, VM, storage domain, events, jobs, capacity, and per-domain RCA — with undo providing a reversal path for writes made elsewhere. The obvious gap is direct remediation (no vm_start/migrate, host_activate/maintenance, storage operations), so agents can diagnose but must act through tools outside this set.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Read-only MCP server that allows AI assistants to query and monitor KVM Fleet devices, audit logs, and console sessions through the official REST API.
      5
      13 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides read-only Proxmox cluster oversight and configuration compliance checks through MCP, covering health, inventory, storage, backups, snapshots, and updates.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Provides authenticated read-only access to VMware Cloud Foundation Operations inventory, metrics, alerts, report definitions, targets, and skills via Streamable HTTP, with a durable audit trail and an admin UI.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to read Oracle Linux Virtualization Manager and oVirt inventory through the engine REST API, including VMs, hosts, and related details. It provides read-only tools for searching and retrieving VMs and KVM hosts.
      3
      Apache 2.0