evmctl published exhibition-vm-controller

Chapter 2 · 2 of 6

Self-healing by snapshot

Freeze the whole machine at a moment the work is known to run correctly — a “snapshot”. Let the work prove it is alive with a steady signal. The instant that signal stops, return to the frozen moment within seconds.

A virtual machine — a complete software re-creation of an old computer, running inside a modern one — lets a vanished environment live on: a period operating system, its browser, its plugins, the artwork. And because the whole computer is now software, it can be frozen as a complete, verified state. A snapshot — a frozen copy of the machine’s entire memory and disk at one instant — preserves not a pile of installation files but the working configuration itself: the moment the work runs correctly.

Artwork in the guest VM heartbeat every ~1 s Host controller watches health Ready snapshot tested, known-good heartbeat · alive on failure revert to the ready snapshot in 2–5 s Triggers: heartbeat timeout · VM shutdown detected · guest-agent ping fails · application error signal
Figure 1. The self-healing loop. The guest proves it is alive with a periodic heartbeat; the moment that stops — or the VM is shut down, or the guest agent stops answering — the host reverts to the tested “ready” snapshot within seconds. No diagnosis, no repair: just a return to a known-good state.
The conservation object (guest) Host controller Tested snapshot

The mechanism

Once a work is brought up and verified, evmctl captures that whole-machine state as a “ready” snapshot. From then on, small scripts inside the guest — the artwork’s virtual machine — send a periodic heartbeat, an “I am alive” signal, to the host controller, the program on the real computer that supervises the virtual machine. When the heartbeat stops, the host does not try to diagnose or repair anything; it simply reverts to the ready snapshot, and within two to five seconds the work is running again from its known-good state. Configuration never drifts, because every recovery returns to the same captured moment.

What can trigger a recovery

  • Heartbeat timeout — no signal from the guest for a configurable window (default ~10–15 s).
  • VM-shutdown detection — if someone shuts the virtual machine down (even with the virtualization software’s own virsh destroy command), the host notices within a fraction of a second and restarts it into the ready state.
  • Guest-agent ping — a liveness check built into the virtualization software itself (the QEMU guest agent), independent of the network (optional).
  • Application error signals — a guest script can report a crashed process, an idle timeout, or any artwork-specific failure immediately.
On startup, too When the controller starts, it brings the VM up and reverts it to the ready snapshot — so an installation always begins from a clean, verified state, not from however it was left.
Terminal output of evmctl-import bringing a baked artwork bundle onto an exhibition computer: the disk image is placed, the virtual machine is defined, and the 'ready' snapshot — the known-good moment every automatic reset returns to — is created, ending in 'imported: true'.
One command turns a baked bundle into a running-ready machine: the import places the disk, registers the virtual machine, and creates the ready snapshot that every automatic reset returns to.

This is the system that proves a work can run. The exhibition it was built for is the next chapter.