Read a host
Look at a host before touching it.
You are about to work on a server that runs virtual machines and want to know what it is and what your agent manages on it.
Capturedmcp-libvirt 0.11.4
YouConnect to the hypervisor and tell me what it is and what we already manage.
Tool calllibvirt_connection_create { "uri": "<the libvirt address of the host>", "connectionId": "guide-demo" }
What happensStatus connected: a slot named guide-demo.
Tool callhost_node_info { "connectionId": "guide-demo" }
What happensOne socket, 6 cores and 12 threads, an x86_64 processor, about 30 GiB of memory with about 5.4 GiB free.
Tool calldomain_list { "connectionId": "guide-demo" }
What happensAn empty list: this session manages no machines yet.
Tool calllibvirt_connection_drop { "connectionId": "guide-demo" }
What happensStatus dropped.
AgentThe host has 12 threads and about 30 GiB of memory, 5.4 GiB of it free. We manage no machines on it yet.
Adopt a VM
Take over a machine that already exists.
A machine was created by hand or by an earlier session that has ended, and you want your agent to look after it.
Illustrative conversation
YouTake over the machine called build-01 and tell me how it is doing.
Tool calldomain_get_info { "connectionId": "lab", "id": "build-01", "includeUnmanaged": true }
What happensReturns the state Running, the vCPU count, the memory, whether it is persistent and whether it starts automatically.
Tool calllibvirt_resource_adopt { "connectionId": "lab", "resourceType": "domain", "resourceId": "build-01" }
What happensStatus adopted: the machine is now in this session's working set.
Agentbuild-01 is running with 4 vCPUs and 8 GiB. I have adopted it, so I can change it if you want.
New machine
Install a new machine from a template.
You need a fresh Ubuntu desktop machine for a test, with its screen reachable only from the server itself.
Illustrative conversation
YouCreate an Ubuntu machine called test-ubuntu from the installer image, 8 GiB, console on localhost only.
Tool calllibvirt_resource_adopt { "connectionId": "lab", "resourceType": "storage_pool", "resourceId": "default" }
What happensStatus adopted: the pool is tracked by this session.
Tool calldomain_create_from_template { "connectionId": "lab", "template": "ubuntu", "name": "test-ubuntu", "iso": "/var/lib/libvirt/isos/ubuntu.iso", "memory_gib": 8, "vnc_listen": "127.0.0.1" }
What happensA disk named test-ubuntu.qcow2 and a machine definition are created, with the installer media attached.
Tool calldomain_action { "connectionId": "lab", "id": "test-ubuntu", "action": "start" }
What happensStatus started.
Tool calldomain_get_vnc_info { "connectionId": "lab", "id": "test-ubuntu" }
What happensReturns the console host and port, bound to the loopback address.
AgentThe machine is booting the installer. Its console is on localhost at the port above; I can connect a viewer and walk through the installation.
Disposable clone
Make a disposable clone of a base machine.
You keep a clean, prepared machine and want a copy for every test, thrown away afterwards.
Illustrative conversation
YouMake a clone of the base machine, run the test in it and delete it.
Tool calldomain_branch { "connectionId": "lab", "base_id": "ubuntu-base", "name": "test-clone-1" }
What happensA new machine with its own identity and a linked disk is defined and recorded as a clone of ubuntu-base.
Tool calldomain_action { "connectionId": "lab", "id": "test-clone-1", "action": "start" }
What happensStatus started.
What happensThe agent runs the test in the clone, for example through MCP Console on the machine, and reads the result.
Tool calldomain_action { "connectionId": "lab", "id": "test-clone-1", "action": "destroy" }
What happensStatus destroyed: the clone is powered off.
Tool calldomain_delete_clone { "connectionId": "lab", "id": "test-clone-1" }
What happensThe clone's definition and firmware state are removed, and its disk too, because this session created it.
AgentThe test passed in a clean clone, and I removed the clone. The base machine was not touched.
Snapshots
Take a risk and go back.
You want to try an upgrade or a risky change on a machine and be able to undo it.
Illustrative conversation
YouSnapshot the machine, apply the upgrade and revert if it breaks.
Tool callsnapshot_create { "connectionId": "lab", "domain_id": "build-01", "name": "before-upgrade", "description": "Before the system upgrade" }
What happensAn external snapshot is recorded for build-01.
What happensThe agent applies the upgrade and runs the checks; one of them fails.
Tool callsnapshot_revert { "connectionId": "lab", "domain_id": "build-01", "id": "before-upgrade" }
What happensThe machine returns to the recorded point.
AgentThe upgrade broke the build check, so I reverted build-01 to before-upgrade. It is back as it was.
Batch
Start or stop several machines at once.
A test needs a group of machines up, and down again afterwards.
Illustrative conversation
YouStart the three test machines and tell me which ones came up.
Tool calldomain_action { "connectionId": "lab", "actions": [{ "id": "test-1", "action": "start" }, { "id": "test-2", "action": "start" }, { "id": "test-3", "action": "start" }] }
What happensReturns a result per machine and a summary: 3 total, 2 succeeded, 1 failed; the failed one names the error.
Agenttest-1 and test-2 are running. test-3 did not start, and the error says why; I can look into it.
Other commands
Do something the tools do not cover.
You need something that the usual tools do not cover.
Illustrative conversation
YouShow me the block devices of build-01.
Tool callvirsh { "connectionId": "lab", "args": ["domblklist", "build-01"] }
What happensReturns exit code 0 and a table of the machine's disks and their source paths.
Agentbuild-01 has one system disk and one installer image attached; their paths are above.