Driving the VM

make run needs a local X or Wayland session. scripts/edos-vm boots the same ISO headless instead, and exposes two channels:

Channel	For	Transport
VNC	a human watching	127.0.0.1:5901
QMP	scripts	a unix socket speaking line-delimited JSON

QEMU is itself the VNC server. There is no X server and no software GL involved: QEMU already rasterises the guest framebuffer, and both VNC and screenshots read the buffer it owns.

make run-headless                  # or: scripts/edos-vm start
scripts/edos-vm shot desktop.png
scripts/edos-vm click 400 300
scripts/edos-vm type 'ls /bin' --enter
scripts/edos-vm key ctrl+c
scripts/edos-vm log -n 40
scripts/edos-vm stop

The video on the home page was recorded this way: pointer and keyboard events in, PNG frames out.

Three things about the guest

These are properties of the OS, not bugs in the script. Anything else driving the VM will hit all three.

The keyboard layout is Spanish ISO

programs/edos_lib/src/keymap.rs hard-codes a Spanish 105-key ISO layout, and QEMU delivers scancodes. A character arrives as whatever the guest’s layout says that physical key means.

Character	Key to send	Character	Key to send
/	shift+7	-	slash
?	shift+minus	'	minus
:	shift+dot	;	comma
|	altgr+1	@	altgr+2

Sending the US key for / types -, which turns ls /bin into ls -bin. scripts/edos-vm type does the translation for you.

The mouse is relative

The guest implements the HID boot mouse protocol only, so a usb-tablet and its absolute reports are silently ignored. Reaching an exact pixel means homing first: the guest clamps the cursor to the screen and applies no acceleration, so driving it hard into the top-left corner is a reliable origin to count from.

A boot-mouse report carries one signed byte per axis, capping a step at 127 pixels, and reports issued faster than the guest polls its interrupt endpoint are dropped. Motion that silently falls short is almost always that.

Focus follows clicks

The window manager focuses on click. Click into a window before typing, or the keystrokes go nowhere. A new terminal also spawns at the same geometry as the existing one, landing exactly on top, so never assume which window is frontmost. Raise the one you want by its taskbar button:

scripts/edos-vm launch     # click the "+ Term" launcher
scripts/edos-vm raise 0    # raise the first window, 0-based, left to right

Waiting for the desktop

The serial console goes to run_log.txt, truncated on every start. The kernel spawns only bin/edos-init, which starts the GUI itself, so wait for the shell rather than for a kernel line. Watch for the failure case too, or a panic costs you the whole timeout:

until grep -qE '\[Terminal\] Spawned shell|KERNEL PANIC' run_log.txt; do sleep 1; done

With KVM the whole boot takes about six seconds. Under TCG it is tens of seconds, which is the practical reason to care about acceleration here.

Host requirements

• Access to /dev/kvm. It is group-owned by kvm, and membership applies at login, so a pre-existing SSH session or tmux server keeps the old credentials.
• OVMF firmware, which the makefile fetches into ovmf/.
• sata-disk.img and the ISO, from make all and make sata-disk.img.