Skip to content
vmctl

The workbench — provision, revive, prove it runs

The autopsy tells you what a work is and what it needs. The workbench (rvmc — the research-vm-controller) is where you act on that: it builds the machine the work asks for, installs the artwork, drives it, and — the part that matters most — proves the work actually runs before anyone trusts it. Only then is a proven build handed off toward exhibition.

Everything below is organised around a single per-artwork project. A project owns its own drive (a tidy on-disk home: artwork/ unpacked/ helpers/ analysis/ work/ exhibition/), its own VM instances, its own captures and save-points. Nothing bleeds between works.

From verdict to a machine

Provisioning a project is one idempotent step: run it, re-run it, and the project ends up fully correct either way. It reads the autopsy verdict off the drive — work kind, entry point, runtime, network endpoints, a suggested base VM — and stands up an isolated VM for that project.

The VM is never built from scratch. It’s a clone of a golden base image: a clean, licensed, agent-equipped base machine of the right era. Cloning is a copy-on-write overlay on top of the read-only golden, so it’s near-instant and costs almost no disk, and resetting a VM to pristine is just “throw the overlay away and clone again”. You pick the base the autopsy suggested (or override it), and the workbench boots a machine of the work’s own time — legacy Windows for a legacy work, classic Mac OS for a classic-Mac work.

See Golden base images & the in-guest agent for the full span of supported systems.

Getting the artwork into the guest

Old guests have no working file share, no USB, often no usable network path. The workbench solves this with a generated data-link CD: the original artwork bundle plus any helper runtimes are burned to an ISO and inserted into the VM’s CD-ROM — no hand-copying into the machine. Inside the guest the same files are also served over a local HTTP address, and files can be pulled back out the same way.

Helper runtimes come from a curated tools library. The autopsy’s runtime suggestions map to library candidates; you stock the drive’s helpers/ folder from those, and they ride the data-link CD into the guest alongside the art.

Revival techniques — a catalog, not a script

Reviving a broken work is a set of recurring problems: a host it phones home to is gone; a runtime it needs isn’t installed; it makes raw socket calls that bypass the guest’s proxy setting; its GUI can’t be driven the usual way on this OS. The workbench does not encode these as one long monolithic playbook. It ships a data-driven technique catalog — each technique a named, reusable recipe with a when to use, the exact problem it addresses, the tools it drives, ordered steps, and honest fidelity caveats.

The current techniques cover, among others:

  • diagnose-wont-run — the work launched but didn’t come up healthy; find the cause before reaching for a fix.
  • dead-host-archive-replay — the work fetches a URL that is gone, and any period-correct response will do; serve it from the archive.
  • live-endpoint-reshim — the source still exists but drifted (an http→https redirect, a moved URL, a changed format) so the period client can’t read it.
  • raw-socket-transparent-intercept — a period net client makes raw socket calls that bypass the guest’s HTTP proxy (Director net Xtras, Flash, Java applets, bare Winsock).
  • supply-the-missing-runtime — the entry point won’t launch because a required runtime or library isn’t in the guest.
  • legacy-file-delivery — get files into an old guest with no working share.
  • drive-the-gui-per-os — operate the work’s GUI where the standard input tools don’t behave the same on this OS.
  • freeze-known-good — the work runs; make the state durable.
  • build-guest-autoheal — the work must survive unattended for months; build the self-healing so internal faults recover on their own.

Why a catalog beats a playbook: a technique is a pure data entry. Adding one is an edit to the catalog file, not a code change. The set the agent (or you) chooses from is filtered by the work’s own capabilities — the analysis and the guest OS decide which techniques are even relevant — so you see the fixes that fit this work, not a wall of everything. And when nothing named fits, there’s a generic open-world fallback technique rather than a dead end. The design deliberately mirrors the autopsy’s runtime catalog: a generic engine plus per-case data.

Watching what the work actually does

The most valuable research affordance is watching the running work with your own eyes and on the wire:

  • The screen. Open the VM over noVNC and drive it directly — mouse, keyboard, resolution. Per-OS input quirks (an offset cursor on an old display, absolute-mouse handling on classic Mac) are handled for you.
  • Network capture. Start a capture, run the work, and inspect the requests it actually makes. This confirms or corrects the autopsy’s static network findings with live behaviour — a dead host seen here is a concrete restoration target.
  • The wayback-cache proxy. For a work that expects a server that no longer exists, the guest’s proxy is pointed at an archive so the work is revived against archived responses instead of the live (dead) internet. This is the runtime companion to the analysis-time wayback lookups (see The autopsy).

Prove it runs — the gate

Nothing is trusted on a hunch. The workbench extracts hard revival signals and asks you (or the agent) to make the call from them — it never declares victory on its own:

  • Is the guest alive and running the work? Confirm the guest agent answers, the expected process is up, and the network reached what the autopsy predicted.
  • Is the screen actually painting? A framebuffer-and-run-state check that works even on an agentless guest (a bare DOS machine, or when the in-guest agent is wedged).
  • What does the OS say? Read the screen as text (most failures are written on screen — a missing-DLL dialog, a licence or date error), and read the guest’s own logs (Windows event log, Mac OS 9 lifecycle logs, the Linux journal).
  • Why did the entry point fail? Launch it and report whether it spawned, its exit code, and the stderr or dialog that names a missing runtime.

These compose into a single promote gate: a promotable judgment plus the reasons against it. A work only advances when that gate is satisfied. You then record the revival outcome — runs / doesn’t, what still needs work, the good snapshot — onto the drive as evidence.

Save-points and freezing state

When a work runs correctly — loaded, positioned, behaving — freeze it. Two mechanisms:

  • Save-points are git commits of the project workspace (the plugin, notes, analysis), so a bundle is always traceable back to an exact, reproducible workspace state.
  • A ready snapshot captures the running VM state, so the exact known-good machine can be returned to without a fresh boot.

Together they are the raw material a future exhibition instance is built from.

Plugins — binding a work as a managed unit

Some works need more than a base machine and a runtime; they need a small piece of conservation logic that travels with them. That’s a plugin: a self-describing unit that binds a specific kind of work as a managed VM. A plugin is a directory — a manifest, a plugin.py with a setup(registry) entry point, and optional web assets — and it registers exactly what the work needs against the controller.

The common case is a backend shim: a plugin that impersonates a network host the recovered client still calls. The controller routes that host to the plugin first, ahead of the archive backends, so a work whose original server is gone talks to a faithful stand-in instead. Plugins can also expose a bring-up plan, live state, a small web UI, or restart hooks for a set-and-forget installation. The plugin contract is machine-readable and derived from the live code, so it can’t drift from what the loader accepts — which is what makes authoring one a first-class task, whether a human or the chat agent writes it.

Crucially, the same plugin file runs unchanged in the exhibition controller. A plugin built and proven in the workbench is exactly what ships.

The hand-off toward exhibition

Once a work passes the gate and you’ve captured a good state, promotion exports a self-contained exhibition bundle onto the drive: the plugin verbatim, the VM overlay as a thin delta over its golden base (resolved later by hash), the ready snapshot reference, provenance, and a save-point commit. Thin by default (the importer rebases onto its own copy of the golden); optionally fat (ships the golden too) for an institution that doesn’t already hold it.

That bundle is the substance the exhibition stage locks into a long-running gallery instance. As the project notes elsewhere, the fully automatic hand-off is the direction rather than a finished feature — today you produce a reproducible, documented, proven research build and a bundle ready to be imported.

Driving it by hand or by agent

Every capability above is available two ways: directly, as an operator, through the workbench UI and API; and to an LLM agent over MCP, so an analyst can drive a VM the way a researcher would — read the autopsy, clone the right base, insert the data-link CD, run the entry point, watch the network, diagnose a failure against the technique catalog, and prove the result. The agentic layer is the current area of active refinement; the underlying controls it calls are stable. You supply the agent’s model — see Bring your own AI.