Skip to content
vmctl

Golden base images & the in-guest agent

Two things make the workbench able to boot a work on the machine of its own time and then act inside that machine: the golden base images it clones, and the in-guest agent every golden carries. This page is the reference for both.

Golden base images

A golden is a clean, licensed, fully prepared base virtual machine that the workbench clones — never boots directly. Each golden is:

  • Clean and conservation-grade. A single passwordless administrator with autologon, no named user profile, temp and recycle cleared, force-off-safe (a clone that loses power doesn’t disk-scan on next boot). The goal is a neutral era-correct machine, not someone’s working desktop.
  • Immutable. A clone is a copy-on-write overlay on top of the read-only golden. Cloning is instant and near-zero-disk; resetting a clone to pristine is delete-and-re-clone.
  • Agent-equipped. Every usable golden ships a reachable in-guest agent (see below). This is a hard requirement — a golden that can’t carry an agent for its OS is not considered done, and that gap is called out rather than hidden.

Each golden also records the hardware hints needed to boot that guest correctly — disk bus, NIC model, display, clock, and so on — because a 2001 Windows guest and a modern Linux guest want very different virtual hardware. The workbench renders those hints into each clone’s VM definition automatically.

The span of supported systems

The catalog reaches deliberately far back, because born-digital art does. Broadly:

  • Modern Windows — Windows 11, Windows 10, Windows 8.1. Modern user-account and driver model; the agent runs elevated.
  • Legacy Windows — Windows 7, Windows XP, Windows 2000, down to Windows 98 SE. The further back you go, the more the machine constrains what’s possible — see the transport and capability notes below.
  • Classic and early Mac — Mac OS 9.2.2 (PowerPC) and early Mac OS X: Mac OS X 10.4 Tiger (PowerPC) and Mac OS X 10.6 Snow Leopard (Intel). The PowerPC guests run under a QEMU fork; the Intel macOS guest boots via an OpenCore loader.
  • Linux — modern virtio-based guests.

Some of these are more finished than others, and the catalog is honest about it. A few goldens are production-solid; a few are works in progress where, for example, period networking or a fully working agent transport is still being finalised. Treat the catalog’s own per-base notes and the agent flag as the source of truth for what a given base can actually do today.

The in-guest agent

The agent (the “agentbox”) is a small program that runs inside the guest and lets the controller — and an AI driving it — operate the machine from the outside. It speaks newline-delimited JSON-RPC and is baked into every agent-capable golden, autostarted into an interactive desktop session at boot.

What it does

Depending on what the guest OS allows, the agent can:

  • Files — read, write, delete, and list files inside the guest.
  • Run a program — launch the entry point or an installer, and walk an installer’s Next / Next / Finish wizard.
  • Screenshot — capture the guest’s screen from inside (GDI), catching layered windows a host-side capture can miss.
  • Shell and Python — run a shell command or a Python snippet in the guest, where the OS supports it.
  • Inspect and drive — list processes and windows, send keystrokes, click, read and write the registry, kill a process, read the event log.

On the oldest guests some of these degrade honestly rather than pretending to work. Windows 98, for instance, has no tasklist/taskkill, no reg.exe, and a broken subprocess path, so process control and registry tools return clean errors while file, screenshot, and system-info tools keep working. The workbench exposes a per-instance capability list so you (or the agent) can check what a given guest actually supports before assuming a tool works.

Reachability — three transport tiers

The controller reaches the agent over a tiered transport, chosen so that even a very locked-down or very old guest stays reachable:

  1. virtio-serial (primary). A host-only serial channel between the host and the guest — there’s no listener the artwork or its network can see. It works even with the guest’s networking turned completely off, which is the safe default for reviving a work that phones home. On capable guests this is a multi-lane pool, so a heavy operation (say, driving an installer) can’t head-of-line-block a health check or a log read.
  2. Legacy TCP (fallback). A plain TCP listener over an isolated control NIC. This is the automatic fallback if the primary channel wedges — the host detects a wedged channel versus a dead guest and fails over without flapping. It is also the only transport on guests that have no virtio-serial driver at all (Windows 2000, Windows 98, Windows 8.1, and the early-macOS guests), where the host simply dials the guest’s address directly.
  3. Guest-initiated outbound poll (last resort). For a guest so locked down that the host can’t dial in at all, the agent can instead dial out: it polls an address at its own gateway for work and posts results back. This rung is armed in the goldens but stays inert until a deployment explicitly enables it, so it never changes behaviour by surprise.

Because every tier is connect-per-call with no session state, “failover” is purely a host-side choice of which endpoint to dial — the guest needs no switch protocol.

One agent, ported across the ages

The agent isn’t one binary. It’s one wire contract with per-OS forks, because the interpreters available shrink dramatically as you go back in time. The mainline agent runs on Python 3.4 and up (Windows XP is the 3.4 ceiling) through modern Python on current Windows. Below that:

  • Windows 2000 runs a Python 2.7 fork.
  • Windows 98 SE runs a Python 2.5 fork with a vendored JSON library (98 has no installer for a newer Python).
  • Classic Mac OS 9 runs a MacPython 2.3 fork — the last classic-Mac Python — over the same JSON contract; that vintage forbids conveniences as basic as the X if C else Y conditional expression, so its code is written to a strict 2.3 dialect.
  • Mac OS X Tiger and Snow Leopard run their own MacPython/TCP forks.

All of them answer the same commands over the same wire, so the controller drives a 1998 machine and a 2023 machine through one interface. The oldest guests simply advertise a smaller set of capabilities — which the workbench respects rather than working around.