63 tools for managing virtual machines.
Every tool except libvirt_connection_list takes a connectionId. It names the host a call acts on; for libvirt_connection_create it names the new connection, and libvirt_connection_drop requires it. Left out, a call uses the implicit default connection unless the service requires an explicit one. This page lists the tools that matter for each job; the full parameter lists, including every template option, are in the tools reference, and 12 runbooks for the long procedures are described in the prompts reference.
Open connections and adopt what exists.
| Tool | Use it to | Key parameters |
|---|---|---|
libvirt_connection_create | Open a named connection to a virtualization host and connect at once. Use it first: every other call names the host it acts on through this connection. | uri (required; scheme qemu, qemu+ssh, qemu+tls, qemu+tcp, qemu+unix, lxc or test), connectionId, name, tags |
libvirt_connection_list / libvirt_connection_drop | List the connections this session has open, or disconnect one and release what the session tracked on it. Dropping deletes nothing on the host. | none; connectionId (required) |
libvirt_resource_adopt / libvirt_resource_unadopt | Bring an existing machine, network, pool, volume, snapshot or checkpoint into this session's working set so you can change it, or release it again without deleting it. | resourceType and resourceId (required), tags, domain_id |
list_by_tags | Find the resources that carry any of the tags you gave them, across everything any session of the server tracks. | tags (required) |
Why: each session tracks what it created or adopted. Changes and ownership-checked reads need that tracking; without it a machine is reported as "not found" even though it exists. Pass includeUnmanaged to a read to look at the rest. Dropping a connection or ending a session releases tracking only and deletes nothing.
Hardware, capabilities and free memory.
| Tool | Use it to | Key parameters |
|---|---|---|
host_node_info | Read the host's processor, topology and free memory, to see what will fit before you place a machine on it. | none |
host_capabilities | Read what the host can run: its CPU features, the guest architectures and its domain types. | none |
host_domain_capabilities | See the devices and processor models the host offers for one kind of guest, so you can pick settings that will work. | emulatorbin, arch, machine, virttype (all optional) |
Why: read the host before placing a machine on it: memory and processor count decide what fits.
Templates, installation and disposable clones.
| Tool | Use it to | Key parameters |
|---|---|---|
domain_create_from_template | Create a disk and define a new machine from a ready-made template in one step. The templates cover Ubuntu, Debian, Fedora, Arch, RHEL, Windows and macOS guests, all x86_64 under KVM, and the install phase boots the installation media. | template (required: ubuntu, debian, fedora, arch, rhel, windows or macos) and name (required), phase (install boots installation media), iso, memory_gib, vcpus, disk_size_gib, pool, network_mode, vnc_listen, tags |
domain_advance_phase | Switch an installed machine from its installer devices to its runtime devices in place. The machine must be shut off, and its name, identity, address, disk and firmware state are kept. | name and template (required) |
domain_set_role | Record a machine as a base, a clone or unspecified. A machine recorded as a base is protected from being started by mistake. | id and role (required: base, clone or unspecified) |
domain_branch | Create a linked clone of a shut-off base machine. The clone is a thin layer on top of the base disk, so it is quick and small, but the base disk must stay in place for as long as the clone exists. | base_id and name (required), memory_gib, vcpus, tags |
domain_delete_clone | Remove a machine recorded as a clone, along with its firmware state, and its disk too if this session created it. | id (required) |
domain_define / domain_create | Define a persistent machine, or create and start a transient one, from definition XML you supply. XML that names an existing machine replaces that machine's definition, so be careful with names. | xml (required), tags |
domain_delete | Remove a machine's definition. Its disks are kept unless you ask for them to go, and it does not stop a running machine, so stop it first. | id (required), keep_nvram, delete_disks, delete_snapshot_metadata, delete_checkpoint_metadata |
Why: a template builds the right device set for the guest, and the libvirt_*_install runbooks give the procedure for each system. Creation is not transactional: a failure can leave a disk or a firmware file behind, so inspect before retrying under the same name. Set vnc_listen to 127.0.0.1 to keep a console local.
Start, stop, read and tune machines.
| Tool | Use it to | Key parameters |
|---|---|---|
domain_action | Start, shut down, reboot, pause, resume or destroy a machine, one at a time or as a batch of 1 to 50 items. One malformed item rejects the whole batch before anything runs. | id and action, force; or actions |
domain_get / domain_get_info | Read a machine's name, identity, state, vCPUs, memory and settings. The first of the two can also read a batch of machines in one call. | id (required; ids for a batch with domain_get), includeUnmanaged |
domain_list | List the machines this session manages, or every machine on the host when you ask for the unmanaged ones too. | includeUnmanaged |
domain_get_xml | Read a machine's full definition as XML, for details the summary does not show. | id (required) |
domain_get_vnc_info / domain_get_console_devices | Find where a machine's graphical console listens, and which console devices it has. | id (required) |
domain_set_vcpus / domain_set_memory / domain_set_max_memory | Change a machine's number of virtual processors, its memory, or its memory ceiling, on the running machine, in its saved definition or both. | id and count or memory_kb, live, config |
domain_send_key | Press keys inside the guest, for example to get past a boot prompt before the system is up. | id and keycodes (required), codeset, holdtime |
domain_interface_stats | Read the traffic and error counts of one of a machine's network interfaces. | id and interface (required) |
Why: shutdown only asks the guest to power off, so read the state until it is Shutoff; destroy powers off at once and can lose unsaved guest data. A machine recorded as a base will not start unless you pass force: true. A batch returns a result per item, so read the failed count: the call itself succeeds even when items fail.
Pools, volumes and virtual networks.
| Tool | Use it to | Key parameters |
|---|---|---|
pool_list / pool_get / pool_create / pool_start / pool_stop / pool_delete / pool_refresh / pool_list_volumes | Manage storage pools: list and inspect them, create, start, stop, delete or refresh one, and see the volumes inside. | id (required), xml to create |
volume_list / volume_get / volume_create / volume_resize / volume_delete / volume_clone | Manage disk volumes: list, inspect, create, resize, clone and delete them. Deleting is refused for a volume that a defined machine still lists as a disk. | pool_id, id, name, capacity (bytes), format, source_id and target_name for a clone |
network_list / network_get / network_create / network_start / network_stop / network_delete / network_batch_get | Manage virtual networks: list, inspect, create, start, stop and delete them, or read several at once. Stopping or deleting a network affects every machine attached to it. | id (required), xml to create, ids for a batch read |
Why: adopting a pool does not adopt its volumes; adopt each volume you intend to change. A clone's base disk must stay in place while the clone exists.
Points to return to and change tracking.
| Tool | Use it to | Key parameters |
|---|---|---|
snapshot_create | Record a point you can return to. It is an external snapshot by default; you can also save the running memory, which is refused on a machine with a 3D display. | domain_id and name (required), description, mode, memory, tags |
snapshot_revert | Return a machine to a recorded point, choosing whether it ends up running or stopped. | id (required), domain_id, run_state, force |
snapshot_list / snapshot_tree / snapshot_get / snapshot_delete / snapshot_annotate | Read, remove and describe a machine's snapshots, as a list or as a tree. Deleting an external snapshot merges its layer into the chain unless you say otherwise. | domain_id (required), id, merge, children |
snapshot_branch | Return to a recorded point and start a new disk-only timeline from it on the same machine, so you can try a different path. | domain_id, from_snapshot, new_name (required) |
checkpoint_create / checkpoint_list / checkpoint_get / checkpoint_delete | Track which parts of a machine's disks change over time, for a backup system. A checkpoint copies no data and cannot be reverted to. | domain_id and name (required) |
Why: a snapshot lives with the machine, so it is not an off-host backup. Snapshot names are unique only per machine, so name the machine when a name could match several.
A classified passthrough to virsh.
| Tool | Use it to | Key parameters |
|---|---|---|
virsh | Run one virsh subcommand on a connection when no typed tool covers what you need. Each subcommand is classified as a read, a write or denied, and a write needs its first target in this session's working set. | args (required), as a list such as ["dominfo", "my-vm"] |
Why: the result carries exit_code, stdout and stderr, and a non-zero exit still arrives as a successful call, so check the code. The typed tools' guards, such as the base-start protection, do not apply to virsh. The service owner can turn it off.
What to expect when a call fails.
A tool failure comes back as a tool error with a message. The limits that matter:
| Limit | Value |
|---|---|
| One call | 30 seconds; host work can continue after the deadline, so inspect before retrying |
| Call rate | Per tool family, per minute: domain_ 50, snapshot_ 20, volume_ 40, pool_ 40, network_ 30; a batch counts as one call |
| Batch | 1 to 50 items for domain_action, domain_get and network_batch_get |
| Guests | x86_64 machines under KVM; no arm64 template |
| XML | At most 1 MB; document type declarations are refused |
| Ownership | Changes need the machine in this session's working set; ending a session deletes nothing |
Creation, deletion and cloning are not transactional, so a failure can leave a disk, a firmware file or a definition behind: inspect them before you retry. See Troubleshooting.