hyperbutler v0.2.0

A sandbox for AI coding agents, BuildKit builds and loopback ports. hyperbutler is a Docker-compatible engine for Windows 11 that runs Docker Engine in a small Hyper-V VM through the Host Compute Service, without WSL.

What's new since v0.1.1

• hyperbutler sandbox (docs/sandbox.md, ADR 0009). Run a coding agent in its own throwaway VM on a copy of your project, then review its changes and apply them or throw them away. The VM's network is limited to the egress mode you pick, and headless Chromium works inside a session. The session image (about 270 MB) is a second MSI that hyperbutler sandbox install fetches and checks against a hash built into hyperbutler.exe. You don't need it to run Docker.
• docker build uses BuildKit. The buildx plugin ships with the bundled docker CLI.
• Ports published on a loopback address work. -p 127.0.0.1:8080:80 and -p [::1]:8080:80, which are common in Compose files, are now reachable from Windows. v0.1.x could not reach them.
• hyperbutler import brings containers too (REQ-UX-024). It offers the containers Docker Desktop started with docker run and shows everything each one needs before it creates it.
• Compatibility samples. bench/compat-tools runs nine Testcontainers and Docker SDK samples against hyperbutler (docs/compat.md).
• Fixes:
  • Every bind mount left part of its file-name cache behind. The 24-hour soak found this as about 3.6 MiB of memory a day; the cache now forgets the entries.
  • The broker refuses a data disk that is a differencing VHDX.
  • start and doctor name a data folder that Windows redirected for a packaged app.

Upgrading

Install the MSI over v0.1.x, then run hyperbutler restart so the engine and the VM use the new version. To use the sandbox, run hyperbutler sandbox install afterwards.

Install

• hyperbutler-v0.2.0-windows-amd64.msi (recommended). It asks for permission once (UAC). It installs to C:\Program Files\hyperbutler, installs the broker service, adds the folder and its bundled docker CLI to PATH and turns on Virtual Machine Platform if needed. Restart if asked, then:

  hyperbutler start
  docker run --rm hello-world
  

• hyperbutler-v0.2.0-windows-amd64.zip: no installer and no broker. It needs Hyper-V Administrators membership. See the install guide.

The builds are not code-signed yet. SmartScreen will say "Windows protected your PC": choose More info, then Run anyway. Check the download first, either with Get-FileHash <file> -Algorithm SHA256 against SHA256SUMS or with gh attestation verify <file> --repo Higangssh/hyperbutler.

Tested for this release

• 24-hour soak of v0.2.0-rc.1, installed from both MSIs. 283,947 docker commands ran, including bind mounts and a published port, and none failed. Handles, threads, goroutines and adjusted memory stayed flat. The Go heap grew by 3.6 MiB, which was the leak fixed above. A unit test covers the fix, and a 1-hour run of it passed (docs/release.md).
• Install tests. Both MSIs were installed, repaired, upgraded and removed in every order.
• Sandbox. A session ran through the installed broker service. Terminal use (keys, resize, Ctrl+C, leaving and coming back) was tested, and Playwright's Chromium was run in a session.
• The release build itself. Both MSIs of this release were installed over rc.1 and checked against their checksums and attestations. A second local standard account outside Hyper-V Administrators then ran the Quick Start through the broker service: first start 2.7 s, hello-world, a bind mount, -p 127.0.0.1:…, a BuildKit build, Compose and stop all passed. A sandbox session through the broker booted in 2.1 s, returned its exit code and showed its changes in sandbox diff.
• CI. The full suite ran: unit and race tests, guest tests, fuzzing, lint, govulncheck and the guest image build.

Known gaps

• The release tests that have not run yet are listed in docs/status.md. Among them are an install on a clean PC and a real sleep and resume.
• The next 24-hour soak runs against v0.2.0 itself.