Getting Started with Agentic VM Management

Overview

This tutorial walks you through installing and configuring the rh-virt agentic skill pack, connecting it to your OpenShift cluster through a containerized MCP server, and verifying the setup by listing your virtual machines with the vm-inventory skill.

After completing this tutorial, you will have a fully configured agentic environment where you can manage OpenShift Virtualization VMs using natural language prompts in Claude Code or Cursor IDE.

Prerequisites

OpenShift 4.18+ cluster with the OpenShift Virtualization operator installed
Claude Code CLI or Cursor IDE installed and authenticated
Podman 4.0+ installed and accessible in your shell
KUBECONFIG pointing to a kubeconfig file with access to the cluster
Cluster admin or a ServiceAccount with RBAC permissions to list and manage VirtualMachine resources

Verify cluster access before continuing:

oc get virtualmachines -A

What is Agentic VM Management

Agentic VM management replaces manual oc command sequences with natural language prompts. You describe what you want to do, and the AI agent selects the correct skill, calls the appropriate API operations through the Model Context Protocol (MCP), and asks for your confirmation before any destructive action.

The rh-virt skill pack is the component that teaches the agent how to manage OpenShift Virtualization VMs. It contains 10 skills (vm-inventory, vm-create, vm-lifecycle-manager, vm-clone, vm-delete, vm-snapshot-create, vm-snapshot-list, vm-snapshot-restore, vm-snapshot-delete, vm-rebalance) and an AGENTS.md routing table that maps user intent to the correct skill.

The OpenShift MCP server is the component that executes the actual Kubernetes API calls inside a Podman container. It exposes the core toolset (generic Kubernetes CRUD) and the kubevirt toolset (vm_create, vm_lifecycle) to the agent over the Model Context Protocol.

Architecture Overview

The following components work together:

Claude Code or Cursor IDE — the AI interface where you type natural language prompts.
AGENTS.md — the skill routing table that maps intent phrases to specific skills.
Skill files (SKILL.md per skill) — detailed instructions the agent follows for each operation.
OpenShift MCP Server — a containerized server that executes Kubernetes and KubeVirt API calls.
KUBECONFIG — the credential file mounted read-only into the MCP container for cluster access.

When you type "List all VMs", the agent reads AGENTS.md, selects the vm-inventory skill, calls resources_list on the MCP server, and formats the results as a table in your IDE.

Installing the rh-virt Skill Pack

Install Lola

The rh-virt collection is installed using Lola, a skill pack manager for Claude Code and Cursor.

Follow the Lola installation instructions in the upstream repository. After installation, verify Lola is available:

lola --version

Clone the agentic-plugins Repository

git clone https://github.com/RHEcosystemAppEng/agentic-plugins.git

cd agentic-plugins

Add the rh-virt local module to lola

lola mod add rh-virt

Install the rh-virt Collection for the selected assistant

Install the pack for Claude Code:

lola install -f rh-virt -a claude-code

Install for Cursor IDE instead:

lola install -f rh-virt -a cursor

Lola copies the skill files and MCP configuration to the appropriate IDE configuration directory.

Configuring the MCP Server

Understanding mcps.json

The rh-virt collection includes an mcps.json file that defines the openshift-virtualization MCP server. This server runs as a Podman container and provides the Kubernetes and KubeVirt API tools that the skills use.

The configuration mounts your KUBECONFIG file as a read-only volume inside the container and passes the KUBECONFIG environment variable so the server binary knows where to find it.

Download mcps.json

{
  "mcpServers": {
    "openshift-virtualization": {
      "command": "podman",
      "args": [
        "run",
        "--rm",
        "-i",
        "--network=host",
        "--userns=keep-id:uid=65532,gid=65532",
        "-v", "${KUBECONFIG}:/kubeconfig:ro,Z",
        "--entrypoint", "/openshift-mcp-server",
        "quay.io/redhat-user-workloads/crt-nshift-lightspeed-tenant/openshift-mcp-server@sha256:2f52c860f91ab3c8a5129b727bdef0d620e733013f073b10355866c45eafd053",
        "--kubeconfig", "/kubeconfig",
        "--toolsets", "core,kubevirt"
      ],
      "env": {
        "KUBECONFIG": "${KUBECONFIG}"
      }
    }
  }
}

Key configuration details:

--userns=keep-id:uid=65532,gid=65532 maps the container user namespace for rootless Podman security.
,Z on the volume mount applies an SELinux context label so the container can read the kubeconfig file.
--entrypoint /openshift-mcp-server specifies the MCP server binary inside the image.
--toolsets core,kubevirt enables both the generic Kubernetes toolset and the KubeVirt-specific toolset.
--network=host is required for the container to reach local or remote Kubernetes API endpoints.

The image is pinned by SHA256 digest for supply chain security. No local build is required; the image is pulled automatically from quay.io on first use.

Setting the KUBECONFIG Environment Variable

The MCP server uses the KUBECONFIG environment variable to locate your kubeconfig file. Set it in your shell before starting your IDE:

export KUBECONFIG="/path/to/your/kubeconfig"

Verify the variable is set correctly:

echo $KUBECONFIG

The mcps.json uses ${KUBECONFIG} as a placeholder. Your IDE substitutes the environment variable value at MCP server startup. Never commit a kubeconfig file or hard-coded credentials into mcps.json.

Verifying Podman Can Pull the Image

On first use, Podman pulls the MCP server image. Verify the pull succeeds before relying on it in the IDE:

podman pull quay.io/redhat-user-workloads/crt-nshift-lightspeed-tenant/openshift-mcp-server@sha256:2f52c860f91ab3c8a5129b727bdef0d620e733013f073b10355866c45eafd053

Verifying the Setup

Checking Cluster Connectivity

Before using the agentic skills, confirm that your KUBECONFIG provides access to VirtualMachine resources:

oc get virtualmachines -A

The output lists all virtual machines across namespaces:

NAMESPACE   NAME               AGE    STATUS    READY
default     fedora-quickstart  4d7h   Running   True

Verify that your user or ServiceAccount has the required RBAC permissions:

oc auth can-i list virtualmachines -A

Running the vm-inventory Skill

After installing the skill pack and setting KUBECONFIG, restart Claude Code or Cursor IDE to load the MCP server configuration.

In the IDE chat, type:

List all VMs

The agent routes the request to the vm-inventory skill, which calls resources_list on the MCP server and returns a formatted table:

## Virtual Machines (All Namespaces)

| Namespace | VM Name           | Status  | Age  | Resources    | Node      |
|-----------|-------------------|---------|------|--------------|-----------|
| default   | fedora-quickstart | Running | 4d7h | 2 vCPU, 4Gi  | worker-01 |

Summary:
- Total VMs: 1
- Running: 1
- Stopped: 0

If the MCP server is not reachable, the skill reports:

Cannot execute vm-inventory: MCP server not available.
Setup: Add openshift-virtualization to mcps.json, set KUBECONFIG, restart Claude Code.

Understanding the Safety Model

The rh-virt skill pack enforces a safety model across all operations:

Read-only operations (vm-inventory, vm-snapshot-list) run without confirmation because they make no changes to the cluster.

Lifecycle operations (vm-lifecycle-manager for start/stop/restart) require explicit user confirmation before execution to prevent accidental service disruption.

Destructive operations (vm-delete, vm-snapshot-restore, vm-snapshot-delete) use multiple confirmation steps. For VM deletion, the agent requires you to type the VM name exactly to confirm before proceeding.

Protection labels prevent accidental deletion. A VM with the label protected: "true" is refused for deletion by the vm-delete skill regardless of user confirmation.

The vm-create skill includes automatic error diagnosis. When a newly created VM enters an ErrorUnschedulable state, the skill reads the troubleshooting knowledge base, diagnoses the root cause (such as node taints or resource constraints), proposes a workaround, and applies it only after you confirm.

Troubleshooting

MCP Server Does Not Start

Verify that KUBECONFIG is set in the environment where your IDE was launched:

echo $KUBECONFIG

Confirm Podman is accessible:

podman info --format '{{.Host.Os}}'

Test that the image runs and the server binary is present:

podman run --rm --entrypoint /openshift-mcp-server quay.io/redhat-user-workloads/crt-nshift-lightspeed-tenant/openshift-mcp-server@sha256:2f52c860f91ab3c8a5129b727bdef0d620e733013f073b10355866c45eafd053 --help

Skills Do Not Activate

Verify the collection is installed by listing installed packs:

lola list

Restart the IDE after installing or updating the skill pack. The AGENTS.md and skill files are read at IDE startup.

Permission Denied on VM Operations

Verify your ServiceAccount or user has the required RBAC for VirtualMachine resources:

oc auth can-i create virtualmachines -A

oc auth can-i delete virtualmachines -A

Contact your cluster administrator if permissions are insufficient.

Cleanup

This tutorial creates no cluster resources. No cleanup is required.

Summary

The rh-virt skill pack provides 10 specialized skills for complete VM lifecycle management in OpenShift Virtualization.
The OpenShift MCP server runs as a rootless Podman container, mounting your KUBECONFIG read-only for secure cluster access.
Lola is the skill pack manager used to install rh-virt into Claude Code or Cursor IDE.
The AGENTS.md routing table maps natural language intent to the correct skill without direct MCP tool calls.
The safety model enforces human-in-the-loop confirmation for all lifecycle and destructive operations.
Running "List all VMs" in the IDE triggers the vm-inventory skill and confirms end-to-end connectivity.