podmac: Giving a macOS guest manager its own home

Running a macOS virtual machine from a Linux workstation can turn into a tangle of container commands, disk paths, remote host conventions, and browser console details. In its original home, the guest manager was a set of scripts inside the much larger harnez repository. That made a useful tool harder to understand and tied harnez's build and install steps to a specialized workload.

podmac gives that workload a standalone Go command line. It manages macOS guests in Podman on Linux hosts with KVM, locally or over SSH. A user can start and inspect a guest, check boot progress, open its noVNC interface, take screenshots, send keyboard input, prepare the guest, synchronize sparse disk storage, and save or restore snapshots. Cobra provides the command structure; Podman, QEMU's monitor interface, SSH, rsync, and the guest image form the operational edges.

The extraction landed on September 14, 2026, as commit 22edde9. It moved 1,371 lines into a new main.go, added a module and Makefile, and made podmac responsible for its own guest management and integration issues. The next day's work made the boundary more explicit: f920aac documented storage and runtime behavior, and 28d5ad6 added AGPL licensing metadata. The six-week history contains seven commits, all from this initial two-day burst; this is a young project, not a long-running release train.

One useful debugging episode is captured in the runtime guide. The noVNC page's favicon stayed blue even though the guest started successfully. The implementation had tried to fetch an SVG from a path the served noVNC container did not provide. The fix described in the guide generates an SVG data URL and colors it from the browser host, including its port. The title patch also targets noVNC's actual document.title assignment, because later connection updates could overwrite a simpler title change. This is a small example of an important engineering habit: a successful compile does not prove that a running container serves the expected page. The guide records checks against representative HTML and JavaScript and confirms the served page, while a follow-up ticket asks the CLI to report future customization failures instead of silently ignoring them.

The first extraction also exposed operational boundaries that had been implicit. Relative storage defaults depend on the caller's working directory. An existing container retains the bind mounts from when it was created. A status command can therefore print the paths from today's invocation even when the running container uses different paths. The storage guide explains those distinctions and the tracker turns them into actionable follow-ups. Tickets 005–007 go further, specifying safety requirements for destructive cleanup, snapshot path traversal, and shell quoting during remote synchronization. Those are open risks, not completed fixes, and should be treated as such.

Harnez's contribution here is visible in the shape of the repository: issue files carry status, priority, severity, and acceptance criteria; the scaffold adds shared agentic-loop, coding, release, and documentation conventions; and the storage guide preserves migration and verification knowledge. There is no evidence in this repository of a multi-agent build or a mature sprint history, so the strongest lesson is not that agents produced an impossible volume of code. It is that a structured harness can make a small extraction legible: boundaries are written down, follow-up work is concrete, and tricky external behavior has a place to be recorded.

The scale remains modest and the quality picture is mixed. The main implementation is a single 1,371-line Go file, and the repository has no tracked Go test files. The README and runtime guide are unusually candid about paths, migration, and what verification can establish. Seven open tickets cover real integration and safety gaps. That combination makes podmac a promising standalone tool and a useful case study in disciplined agent-assisted development, while also making clear what remains: tests, safer path handling, accurate inspection of existing containers, and observable failure reporting.

Facts