Boot a QEMU VM headless and register it under name.

name identifies this VM in all later calls (qemu_screenshot, qemu_stop, etc.) - it must be non-empty and contain no "/" or "" (it also names a temp directory and is passed to QEMU's -name flag). Provide at least one of: iso (bootable CD image), kernel (multiboot/bzImage, optionally with append/initrd), or disk (raw or qcow2 disk image, auto-detected; qcow2 is required for qemu_snapshot_save/qemu_snapshot_load). append/initrd require kernel to also be given - QEMU itself rejects -append/-initrd without -kernel, so this is checked up front with a clear ValueError. Each of iso, kernel, initrd, and disk, if given, must already exist on disk - qemu_boot checks with a clear FileNotFoundError naming the param and path before any QEMU process starts, rather than letting a typo surface later as an opaque "QEMU exited immediately" failure; qemu_boot never creates a disk image for you, so disk must point at an existing image file. memory_mb must be positive. arch picks the qemu-system- binary (x86_64, i386, aarch64, riscv64...) and, like name, must contain no "/" or "" and not be "." or "..". machine is passed as QEMU's -M and is required on some archs - aarch64 and riscv64 have no default machine and need e.g. machine="virt". smp sets the number of virtual CPUs (QEMU -smp), for testing SMP-aware guest code; must be positive when given. smp_cores/smp_threads/smp_sockets/smp_maxcpus add QEMU's -smp CPU-topology qualifiers (cores=/threads=/sockets=/maxcpus=) onto the same -smp flag instead of a flat count - for guest code that cares about socket/core/thread shape (ACPI MADT entries, CPUID topology leaves, per-socket vs. per-core scheduling), not just a total vCPU number. Each must be positive when given; any of them (with or without smp itself) causes -smp to be emitted. accel is passed as QEMU's -accel (e.g. "kvm", "kvm:tcg" to fall back to software emulation if KVM isn't available, "hvf"/"hvf:tcg" on macOS, "whpx:tcg" on Windows) to opt into hardware acceleration; left unset, QEMU defaults to TCG (software emulation), which is correct but slow for anything beyond a trivial kernel. There's no host-capability probe for this - if the requested accelerator isn't available, QEMU itself fails immediately and that failure (including QEMU's own explanation) is surfaced the same way any other immediate boot failure is, in the raised error. cpu is passed as QEMU's -cpu (e.g. "qemu64,+avx", "max", "host" when accel="kvm"/"hvf") to select or customize the emulated CPU model - useful for testing guest code against a specific feature set (SSE4, AVX, a particular vendor's quirks) rather than whatever QEMU defaults to for the arch. extra_args is passed to QEMU verbatim, e.g. "-netdev user,id=n0 -device rtl8139,netdev=n0" (must be valid shell-style quoting, e.g. no unbalanced quotes). extra_args may not contain a flag qemu_boot already sets itself: -name, -m, -display, -qmp always; -M/-machine, -cdrom/-boot, -kernel, -append, -initrd, -smp, -accel, -cpu when the corresponding param above is also given (-smp collides when smp or any of the smp_* topology params is given). -drive is exempt from this check even when disk is given - QEMU allows repeated -drive flags, so extra_args can add further disks, e.g. extra_args="-drive file=data.img,format=raw" for a second drive alongside disk (pointing extra_args's -drive at the same file as disk will still fail, but as a QEMU image-locking error at boot, not a pre-flight one). -chardev/-serial are similarly exempt except for the exact chardev qemu_boot's own serial console uses (id=serial0 / chardev:serial0) - extra_args can add an unrelated -chardev or a second -serial (e.g. a COM2 backed by another chardev) freely, but reusing id=serial0 or pointing another -serial at chardev:serial0 is rejected, since that's the pair qemu_serial/qemu_serial_send depend on. hostfwd is a convenience for reaching a guest service (SSH, a web server under test) from the host, without needing QEMU-specific NIC/chipset knowledge: give it QEMU's hostfwd rule, e.g. hostfwd="tcp::2222-:22" to forward host port 2222 to guest port 22, and qemu_boot adds the "-netdev user,id=net0,hostfwd=..." / "-device e1000,netdev=net0" pair for you (the guest needs its own driver for an e1000 NIC - most general-purpose OSes, Linux included, have one built in). Must look like [tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport. -netdev/-device are similarly exempt from the extra_args conflict check except for the exact netdev hostfwd's own NIC uses (id=net0 / netdev=net0) - extra_args can add an unrelated NIC (e.g. for testing a guest driver) freely, but reusing id=net0 or pointing a -device at netdev=net0 is rejected. hostfwd's host port is probed pre-flight (a bind attempt on that exact port/address) so a collision - two VMs sharing a hostfwd port, or an unrelated process already bound to it - raises a clear ValueError naming the port instead of surfacing as QEMU's own confusing bind-failure output through the generic "QEMU exited immediately" path. qmp_connect_timeout_s bounds how long to retry connecting to QEMU's QMP socket after launch (raise it on a slow/loaded host where QEMU's first launch is slow, e.g. under AV scanning). qmp_read_timeout_s bounds how long any single QMP command (including ones issued by other qemu_* tools for this VM, like qemu_qmp or qemu_snapshot_save) waits for a response - raise it if you expect a command that can legitimately run long. Both timeouts must be positive. The VM keeps running until qemu_stop; serial output is captured continuously.

Capture the VM's display as a PNG image.

Works headless - the guest's VGA framebuffer is captured via QMP screendump. Use it to see boot screens, kernel panics, GUIs, or a text console that doesn't write to serial. Raises a clear error (instead of an opaque image-decoding failure) if the VM exits while the screendump is in flight.

Type text into the guest as keyboard input. "\n" presses Enter.

Handles US-layout characters including shifted symbols. delay_ms is the gap between keystrokes - raise it (e.g. 80) if the guest drops characters during early boot. Must be non-negative.

Press a key or chord: "enter", "esc", "f12", "ctrl-alt-f2", "ctrl-c"...

Parts are joined with "-" and pressed together. A literal "-" key is written "--" (e.g. "ctrl--" for ctrl + minus). Use qemu_type for plain text. "sysrq" sends the Linux Magic SysRq key (e.g. "alt-sysrq-s" to sync disks, "alt-sysrq-c" to force a crash dump on a guest kernel built with CONFIG_MAGIC_SYSRQ).

Move the absolute pointer and optionally click.

x and y are fractions of the screen width/height (0.0 = left/top, 1.0 = right/bottom) - read them off a qemu_screenshot. button is "left", "right", or "middle" for a full click at that position; "wheel-up", "wheel-down", "wheel-left", or "wheel-right" to scroll a scrollable widget under the pointer instead; or "side"/"extra" for a 5-button mouse's extra side buttons (needs the guest's PS/2 mouse driver in IMEX mode to see them). Omit button to just move the pointer. Needs the guest to have an absolute pointer (USB tablet or PS/2 mouse) to track it - most GUIs have one by default.

Pause the VM's execution (QMP stop) without exiting QEMU.

The guest's CPUs stop running - RAM and device state stay exactly as they are until qemu_resume. Useful for inspecting a VM (qemu_screenshot, qemu_qmp query-*) without guest time advancing while you look, or for pairing with qemu_snapshot_save to get a guaranteed-consistent snapshot instead of one taken mid-instruction. qemu_stop still works on a paused VM.

Resume a VM previously paused with qemu_pause (QMP cont).

A no-op (still returns success) if the VM wasn't paused.

Save a full VM snapshot (RAM + device state) under tag.

Uses QEMU's internal savevm mechanism, which stores the snapshot inside the disk image itself - the VM's disk must be qcow2 (raw images do not support internal snapshots). Saving again with the same tag overwrites it. tag may only contain letters, digits, '.', '_', '-'.

Restore a VM to a snapshot previously saved with qemu_snapshot_save.

Requires the same qcow2 disk the snapshot was taken on.

Delete a snapshot previously saved with qemu_snapshot_save.

Frees the space it used inside the qcow2 disk. Reports failure if QEMU's delvm rejects it (e.g. an unknown tag) instead of claiming success.

List internal snapshots saved on the VM's qcow2 disk.

Wraps QEMU's HMP info snapshots so you can see what tags already exist before calling qemu_snapshot_load or qemu_snapshot_delete, instead of finding out only from a failure afterward. Returns QEMU's raw table output as-is (its exact column layout isn't parsed here).

Swap the medium in a removable drive (e.g. a CD-ROM) without rebooting.

device is the block backend's id or QOM path, as shown by qemu_qmp(name, "query-block")'s "qdev" field - qemu-mcp can't guess it for you, since it depends on the machine type/QEMU version and whether the drive was given an explicit id (qemu_boot's iso/disk params don't set one). path must already exist. format defaults to auto-probing the new image. force=True ejects even a drive the guest has locked (its tray "closed" on the medium); the default refuses in that case instead of surprising the guest. Wraps QMP blockdev-change-medium.

Read the tail of the VM's serial console output (COM1).

Works even after the VM has exited (guest crash, or quit via qemu_qmp) so you can see what it printed right before dying - the exited VM stays visible here until qemu_list's next call reaps it. tail_lines must be positive.

Write text to the guest's serial console (COM1).

For guests that only expose a shell over serial (no VGA console, or a kernel with a serial-only debug shell) - the bidirectional counterpart to qemu_serial's read-only tail. Sent exactly as given; include "\n" yourself for Enter. Kept on one persistent connection for the VM's lifetime - disconnecting and reconnecting would hang up the serial line. If the connection drops (e.g. the guest is mid-reboot) this reconnects once automatically; if that also fails, raises with a message saying so

• retry the call once the guest's serial socket is back up.

Block until text appears on the serial console, or time out.

The reliable way to know a guest reached a boot stage ("login:", "kernel ready", a shell prompt) before typing or screenshotting. Each wait searches only output after the previous successful wait's match, so waiting for "$ " after typing a command finds the NEW prompt, not the one already on screen. The first wait searches from the start of the log (so a marker printed before the call is still found); from_start=True searches the whole log again. Returns the serial tail either way, prefixed FOUND or TIMEOUT. Always checks at least once, even if timeout_s is 0 or negative. poll_interval_s (default 0.25s) must be positive. Each poll reads only the serial log bytes written since the previous poll, not the whole file, so a long wait against a chatty guest doesn't cost ever-more I/O per poll. text must be non-empty.

Block until the VM's display stops changing, or time out.

Polls screendumps every poll_interval_s and waits for stable_polls consecutive frames that each differ from the previous one by at most max_changed_pixels pixels (default 64: a blinking text-mode cursor flips about 18, so identical frames never happen on a text console, while boot output changes hundreds; use 0 to require identical frames) - the reliable way to know a VGA-only guest (no serial output) has finished a BIOS splash or boot animation before you screenshot or type. For guests with serial output, prefer qemu_wait_serial - it doesn't need a fixed number of polls to decide. Always polls at least once, even if timeout_s is 0 or negative. poll_interval_s must be positive.

Report qemu-system-<arch> --version's own output, without booting a VM.

Useful when a QMP command or machine type behaves unexpectedly and you need to know what's actually installed - arch picks the same qemu-system- binary qemu_boot would use.

Create a fresh disk image via qemu-img create, ready for qemu_boot's disk param.

qemu_boot never creates a disk image itself - disk must already point at an existing file. This closes that gap: create one here, then boot straight into it.

size looks like qemu-img's own size grammar: a number optionally suffixed with k/K/M/G/T/P/E, e.g. "10G" or "512M". format must be "qcow2" (default - needed for qemu_snapshot_save/qemu_snapshot_load) or "raw" - qemu_boot's disk_format() auto-detection only tells these two apart, so any other qemu-img format would silently be treated as raw. Fails if path already exists, rather than overwriting it.

List all VMs managed by this server, with arch, machine, hostfwd, pid, uptime, and state.

A VM that exited on its own (guest panic, or quit via qemu_qmp) is shown here once as exited(...), then reaped - its workdir and handles are freed before this call returns, so it won't reappear next time.

Stop a VM. Tries graceful ACPI powerdown first; force=True kills it.

Guests without ACPI handling (most hobby kernels) will need force=True or will be killed after the graceful_timeout_s grace period anyway. graceful_timeout_s (default 10 s) bounds how long to wait for the guest to shut down after ACPI powerdown before falling back to a kill; raise it for a guest that legitimately needs longer (large RAM, a slow ACPI handler). kill_timeout_s (default 3 s) bounds how long to wait for the QEMU process to exit after quit/kill before it's force-killed. Both must be positive.

Escape hatch: run a raw QMP command on the VM.

Examples: query-status, system_reset, memsave, device_add. See the QEMU QMP reference for commands and their arguments.