Tool reference

The full tool surface, generated from the running server so it matches the code exactly. Descriptions are the text the calling model sees. Parameters marked required have no default; everything else may be omitted.

Sandboxes

One call to a working disposable VM, and one to remove every trace of it.

sandbox_vm

Spin up a disposable sandbox VM from a base disk image, in one call: creates a copy-on- write overlay (the base image is never modified), launches the VM, and waits for the guest agent to come up so guest_exec / guest_file_* are immediately usable. By default a free host port is forwarded to guest port 22 (pass port_forwards=[] to disable, or your own list). If no name is given, sandbox / sandbox-2 / … is chosen. Tear everything down later with sandbox_destroy. Outbound networking is OFF by default: the guest cannot reach the internet or any service on the host, which is what makes it a sandbox. Inbound port forwards still work. Pass allow_network=True when the guest legitimately needs to fetch packages. Note that the guest agent answers well before the guest finishes booting, so this returns while services like networking are still starting. If a command depends on one, wait for it inside the guest (e.g. poll ‘systemctl is-active NetworkManager’) rather than assuming it is up.

Parameter	Type	Default
base_image	string	required
name	string	null
memory_mb	integer	2048
cpus	integer	2
port_forwards	array	null
allow_network	boolean	false
wait_agent_s	integer	90

sandbox_destroy

Destroy a sandbox created with sandbox_vm: force-stop the VM, remove it from the registry, and delete its overlay disk and logs. The base image is untouched. Refuses to operate on VMs that were not created by sandbox_vm — use stop_vm / forget_vm for those (they never delete disks). If the VM cannot be killed, nothing is deleted and the call fails.

Parameter	Type	Default
name	string	required

Lifecycle

Starting, stopping and tracking virtual machines.

launch_vm

Launch a new QEMU virtual machine and register it for management. Use disks for existing image files (create them first with image_create); use iso to boot an installer or live CD. With both, the VM boots the ISO once then the disk afterwards. port_forwards maps host ports to guest ports (user-mode networking): “2222:22” is explicit, “auto:22” (or just “22”) picks a free host port — the result reports what was chosen. KVM acceleration is used automatically when the guest arch matches the host. The VM keeps running even if this MCP server restarts; stop it with stop_vm. restrict_net=True drops all guest-initiated traffic (no internet, and no reaching services on the host) while keeping port_forwards working inbound — use it when running untrusted software. no_net=True removes the NIC entirely. extra_args passes raw flags to qemu-system-* and is an operator escape hatch: only use values you wrote yourself, never values derived from untrusted input. Flags that would breach VM isolation (host filesystem passthrough, host block devices, spawning chardevs) are rejected.

Parameter	Type	Default
name	string	required
arch	string	"x86_64"
disks	array	null
iso	string	null
memory_mb	integer	2048
cpus	integer	2
machine	string	null
firmware	string	"bios"
port_forwards	array	null
no_net	boolean	false
restrict_net	boolean	false
extra_args	array	null

stop_vm

Stop a VM. By default sends a graceful ACPI power-button press and waits for the guest to shut down; if the guest ignores it (no OS booted, or OS without ACPI handling), the call fails with advice to retry with force=True, which terminates QEMU immediately (like pulling the power cord).

Parameter	Type	Default
name	string	required
force	boolean	false
timeout	integer	30

pause_vm

Pause (freeze) a running VM’s virtual CPUs. The VM stays in memory; resume it with resume_vm.

Parameter	Type	Default
name	string	required

resume_vm

Resume a VM previously frozen with pause_vm.

Parameter	Type	Default
name	string	required

attach_vm

Register an externally launched QEMU process so the other tools can manage it. Point qmp_socket at its QMP unix socket (the QEMU process must have been started with e.g. -qmp unix:/path,server=on,wait=off). Optionally provide qga_socket for guest-agent tools and pid for liveness tracking.

Parameter	Type	Default
name	string	required
qmp_socket	string	required
qga_socket	string	null
pid	integer	null

forget_vm

Remove a VM from the registry WITHOUT stopping it — the QEMU process is left untouched. Refuses to forget a running VM this server spawned unless force=True (to avoid orphaning processes by accident).

Parameter	Type	Default
name	string	required
force	boolean	false

Inspection

What exists and what state it is in.

list_vms

List every registered VM with its live status (running, paused, shutdown, stopped, or unreachable). Includes both VMs launched by this server and externally attached ones. Returns {“vms”: […], “registry_warnings”: […]}. A non-empty registry_warnings means bookkeeping was damaged and some VMs may be running but untracked — report it rather than assuming the list is complete.

vm_info

Detailed information about one VM: its launch configuration, log file paths, and — when running — live QMP state (status, vCPUs, block devices).

Parameter	Type	Default
name	string	required

See and drive

Watching a VM’s display and injecting input, with no guest software required.

vm_screenshot

Capture the VM’s current display as a PNG image. Works on any running VM with a display device (the default for launched x86 VMs) — no guest software needed. Use this to watch installers, read console output, or verify GUI state before sending keys with vm_send_keys / vm_type_text.

Parameter	Type	Default
name	string	required

vm_send_keys

Press keys or key combos in the VM. Each list entry is one press: a single key (“ret”, “esc”, “f2”, “a”) or a chord pressed together (“ctrl-alt-f2”, “ctrl-c”). Entries are sent in order with delay_ms between them. Aliases like “enter”, “space”, “escape” work. To type prose, use vm_type_text instead.

Parameter	Type	Default
name	string	required
keys	array	required
hold_ms	integer	100
delay_ms	integer	50

vm_type_text

Type a string into the VM, character by character (US keyboard layout; printable ASCII plus tab and newline). Set enter=True to press Enter at the end — handy for shell commands at a console login or terminal.

Parameter	Type	Default
name	string	required
text	string	required
enter	boolean	false
delay_ms	integer	30

vm_click

Click at pixel coordinates (x, y) on the VM display — coordinates match what vm_screenshot shows. Requires the VM’s tablet device for absolute positioning (present on VMs launched by this server). button: left, right, or middle.

Parameter	Type	Default
name	string	required
x	integer	required
y	integer	required
button	string	"left"
double	boolean	false

vm_mouse_move

Relative mouse control for guests WITHOUT absolute-pointer (tablet) drivers — most pre-2010 OSes. Use this when vm_click has no visible effect. Motion goes to the emulated PS/2 mouse in small steps (<= step px per packet) because guests often desync or apply acceleration on large deltas. Recommended pattern: pass home=“bottom-right” (or another corner) to pin the cursor to a known position first, then dx/dy toward the target, then vm_screenshot to verify where the cursor actually landed (guest acceleration may scale motion), correct with further small moves, and finally click. click presses that button after moving; double=True double-clicks.

Parameter	Type	Default
name	string	required
dx	integer	0
dy	integer	0
home	string	null
click	string	null
double	boolean	false
step	integer	32

vm_serial_read

Read the last lines of the VM’s serial console log. Only useful when the guest writes to its serial port (kernel console=ttyS0, or text-mode installers); GUI-only guests log nothing here — use vm_screenshot for those.

Parameter	Type	Default
name	string	required
tail_lines	integer	50

Live snapshots

Point-in-time state of a running VM, including RAM. Requires qcow2 disks.

vm_snapshot_create

Save a live internal snapshot (RAM + device + disk state) of a running VM under tag. Requires the VM’s writable disks to be qcow2. The VM pauses briefly while state is written. Restore later with vm_snapshot_restore.

Parameter	Type	Default
name	string	required
tag	string	required

vm_snapshot_restore

Roll a running VM back to the internal snapshot tag (RAM, devices and disks all revert). Anything that happened after the snapshot is lost.

Parameter	Type	Default
name	string	required
tag	string	required

vm_snapshot_delete

Delete the internal snapshot tag from a running VM’s disks. The VM keeps running; only the saved snapshot is removed.

Parameter	Type	Default
name	string	required
tag	string	required

vm_snapshot_list

List internal snapshots visible to a running VM. For stopped VMs use image_snapshot_list on the disk file instead.

Parameter	Type	Default
name	string	required

Disk images

qemu-img operations on images that are not currently attached to a running VM.

image_create

Create a new disk image. size uses qemu-img suffixes, e.g. “20G”. qcow2 grows on demand, so a large virtual size costs almost nothing up front. With backing_file, the new image becomes a copy-on-write overlay — great for cheap disposable clones of a base image. Refuses to replace an existing file unless overwrite=True.

Parameter	Type	Default
path	string	required
size	string	required
format	string	"qcow2"
backing_file	string	null
overwrite	boolean	false

image_info

Inspect a disk image: format, virtual and on-disk size, internal snapshots, and (with backing_chain=True) the full copy-on-write chain.

Parameter	Type	Default
path	string	required
backing_chain	boolean	false

image_convert

Convert a disk image to another format (e.g. raw -> qcow2, vmdk -> qcow2). Conversion flattens any backing chain into a standalone image. compress=True enables qcow2 compression (smaller, slower).

Parameter	Type	Default
source	string	required
dest	string	required
format	string	"qcow2"
compress	boolean	false
overwrite	boolean	false

image_resize

Resize a disk image’s virtual size (e.g. size=“30G”, or “+10G” to grow relatively). Growing is safe; shrinking DESTROYS data beyond the new size and requires shrink=True as explicit confirmation (shrink the guest filesystem first!).

Parameter	Type	Default
path	string	required
size	string	required
shrink	boolean	false

image_snapshot_create

Create an internal disk-only snapshot in an offline qcow2 image. For running VMs use vm_snapshot_create instead (it also captures RAM).

Parameter	Type	Default
path	string	required
tag	string	required

image_snapshot_apply

Revert an offline qcow2 image to internal snapshot tag. Data written after the snapshot is lost.

Parameter	Type	Default
path	string	required
tag	string	required

image_snapshot_delete

Delete internal snapshot tag from an offline qcow2 image.

Parameter	Type	Default
path	string	required
tag	string	required

image_snapshot_list

List internal snapshots stored in a (not currently running) qcow2 image.

Parameter	Type	Default
path	string	required

Guest agent

Reaching inside a guest. Needs qemu-guest-agent installed and running in the guest OS.

guest_ping

Check whether the qemu-guest-agent inside the VM is alive and responding. A failure means the guest OS doesn’t have the agent installed or running — the other guest_* tools won’t work until it does.

Parameter	Type	Default
name	string	required

guest_info

Report the guest OS details (name, version, kernel) and the guest agent’s version and supported commands.

Parameter	Type	Default
name	string	required

guest_exec

Run a command inside the guest OS and return its stdout, stderr, and exit code. command is the executable path or name; pass arguments separately in args (this is exec, not a shell — for shell features use command=“/bin/sh”, args=[“-c”, “your | pipeline”]). Requires qemu-guest-agent in the guest.

Parameter	Type	Default
name	string	required
command	string	required
args	array	null
stdin	string	null
timeout	integer	30

guest_file_read

Read a text file from inside the guest (up to max_bytes, default 1 MiB, 8 MiB ceiling). Requires qemu-guest-agent in the guest.

Parameter	Type	Default
name	string	required
path	string	required
max_bytes	integer	1048576

guest_file_write

Write a text file inside the guest (mode ‘w’ truncates, append=True appends). Requires qemu-guest-agent in the guest.

Parameter	Type	Default
name	string	required
path	string	required
content	string	required
append	boolean	false