Configuration and file layout

Environment variables

Variable	Default	What it does
MCQEMU_STATE_DIR	$XDG_DATA_HOME/mcqemu, else ~/.local/share/mcqemu	Registry, per-VM logs, sandbox overlays, UEFI variable stores
MCQEMU_RUNTIME_DIR	$XDG_RUNTIME_DIR/mcqemu, else /tmp/mcqemu-$UID	QMP sockets, guest-agent sockets, pidfiles
MCQEMU_LOG_LEVEL	INFO	Log level for the server’s own stderr logging

Both directory variables are useful for tests and for running more than one independent instance. Sockets live under the runtime directory partly because unix socket paths are limited to about 107 bytes, and a short path leaves room for long VM names.

What lives where

$MCQEMU_STATE_DIR/
  vms.json                  registry (schema-versioned, atomically written)
  vms.json.lock             advisory lock held during read-modify-write
  vms/<name>/
    qemu.log                QEMU's own log, written after daemonizing
    serial.log              the guest's serial console
    overlay.qcow2           sandbox overlay disk (sandboxes only)
    uefi-vars.fd            per-VM UEFI variable store (firmware="uefi")

$MCQEMU_RUNTIME_DIR/<name>/
  qmp.sock                  QMP control socket
  qga.sock                  guest-agent channel
  pid                       pidfile written by QEMU

The registry is rewritten under an exclusive lock, re-reading first, so a second mcqemu instance sharing the same state directory merges rather than overwrites. If the file is ever unreadable it is quarantined as vms.corrupt.<epoch>.json and the server starts with an empty registry, reporting the damage in the registry_warnings field of list_vms. Running VMs are unaffected by that; they can be re-registered with attach_vm using the sockets above.

Launch defaults

launch_vm aims for a sensible modern machine and lets you override any of it.

Aspect	Default
Machine type	q35 on x86, virt on aarch64 and riscv64, QEMU’s own default elsewhere
Acceleration	KVM with -cpu host when the guest architecture matches the host and /dev/kvm is writable, otherwise TCG with -cpu max
Memory and CPUs	2048 MB, 2 vCPUs
Disks	virtio, with the format probed by qemu-img rather than guessed
Display	none, with a display device still present so screenshots work
Serial	written to serial.log
Pointer	virtio tablet, so vm_click can target exact pixels
Guest agent	virtio-serial channel wired on every launch
Networking	user-mode with virtio-net; restrict=on when restrict_net is set

The result of launch_vm reports which accelerator was used, so a VM that quietly fell back to software emulation is visible rather than merely slow.

Port forwarding

port_forwards accepts three spellings:

Form	Meaning
"2222:22"	Host port 2222 to guest port 22. The host port is bind-tested first, so a collision fails immediately with a clear message.
"auto:22"	A free host port is chosen. The launch result reports which one.
"22"	Shorthand for auto:22.

Duplicate host ports within one list are rejected rather than left for QEMU to fail on later.

Firmware

firmware="bios" is the default. firmware="uefi" uses the edk2 images installed on the host: on x86_64 that is a read-only OVMF_CODE pflash plus a writable per-VM copy of OVMF_VARS, so UEFI variables persist per VM without touching the shared firmware. On aarch64 and riscv64 the firmware is supplied with -bios instead.

Escape hatch

extra_args appends raw flags to the QEMU command line. It exists for tuning the tool surface does not cover, and it is for values you wrote yourself, never for values derived from untrusted input. Flags that would breach the isolation a VM is supposed to provide are rejected: host filesystem passthrough (-fsdev, -virtfs), host block devices, spawning chardevs, -runas, and flags that would collide with the sockets and pidfile mcqemu manages.