hyperbutler v0.1.0-preview.2

Second preview: no more Hyper-V Administrators. 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. The stock docker CLI and Compose talk to it through a hyperbutler docker context.

Preview: try it, report what breaks, don't run production on it yet. The release gates that are not met yet are listed below.

What's new since preview.1

• The HCS access broker ships. The MSI now installs a small Windows service, hyperbutler-broker, the only privileged part. It starts and stops your VM from a fixed template, on seven typed requests over a pipe only you can open. Daily use needs neither admin rights nor the Hyper-V Administrators group, and the installer no longer offers to add you to it. Design and eight rounds of adversarial review: ADR 0004.
• Data folder checks. The broker refuses a data folder another account could swap or read. hyperbutler doctor reports why, and hyperbutler doctor --fix repairs the permissions without following junctions or hard links.
• Sleep and resume. A VM no longer looks lost after the PC sleeps: the broker keeps the lease while the machine is asleep, and the client counts timeouts in awake time.
• Own Windows I/O layer. go-winio is gone; hvsock and named-pipe I/O are hyperbutler's own code, and the broker links only the Go standard library and x/sys.
• Compose tested end to end (bench/compose): builds, healthchecks, service names, named volumes, bind mounts and published ports, all through the broker.
• Upgrade from preview.1 keeps your settings and data.

Install

• hyperbutler-v0.1.0-preview.2-windows-amd64.msi (recommended). One UAC prompt. It installs to C:\Program Files\hyperbutler, installs the broker service, adds the folder and its bundled docker CLI to the end of PATH and turns on Virtual Machine Platform if needed. Restart if asked, then:

  hyperbutler start
  docker run --rm hello-world
  

• hyperbutler-v0.1.0-preview.2-windows-amd64.zip: no installer and no broker, so 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: Get-FileHash <file> -Algorithm SHA256 against SHA256SUMS, or gh attestation verify <file> --repo Higangssh/hyperbutler.

Measured against Docker Desktop (same laptop, defaults)

	hyperbutler	Docker Desktop 4.97 (WSL 2)
Needs WSL	no	yes
Start until a container runs	2.5 s	5.6 s
Idle memory, VM running	322 MiB	1.7–2.7 GB
Disk 5 min after deleting ~5 GB of images	1.5 GiB, given back	6.8 GiB, kept
Bind mount: read 2000 small files	0.4 s	3.4 s

Measured with preview.1's engine, before the broker; the broker's own memory is not in these numbers yet. Method and raw data: docs/compare-docker-desktop.md. One machine is not a general result.

Release gates not met yet

These block v0.1.0 (docs/release.md, status):

• The 24-hour soak with the broker.
• An install on a clean PC (install, upgrade from preview.1, repair and uninstall were tested on one machine, 15 steps).
• A real sleep test (S3 / Modern Standby); the fix is tested in unit tests only.
• Re-measuring idle memory with the broker included, and bench/noadmin.
• Integration tests on real hardware in CI, bench/net-vpn, bench/coexist, REQ-MEM-002 (12 GB guest) and the host-disk-full test.

Known gaps

• The broker runs as LocalSystem. Moving it to a less privileged virtual account is planned after v0.1.0.
• No Kubernetes, no Windows containers. Windows 11 only.
• Unsigned builds; the installer is English only (the app and window follow your language, Korean included).
• The app checks GitHub for a new version once a day; hyperbutler config set updateCheck false turns that off. hyperbutler sends no usage data or telemetry.

Assets

• .msi, .zip: the installer and the portable build.
• hyperbutler-v0.1.0-preview.2-guest-sources.tar: the corresponding source of the guest image's GPL components.
• hyperbutler-v0.1.0-preview.2-guest-inputs.tar: the signed Alpine packages the guest image was built from.
• .spdx.json: SBOM. SHA256SUMS: checksums. Build provenance is attested (Sigstore).

hyperbutler v0.1.0-preview.1

First public preview. hyperbutler is a Docker-compatible engine for Windows that runs Docker Engine in a small Hyper-V VM through the Host Compute Service, without WSL. It works on Windows 11 Home. The stock docker CLI and Compose talk to it through a hyperbutler docker context.

Preview: try it, report what breaks, don't run production on it yet. The release gates that are not met yet are listed below.

Install

• hyperbutler-v0.1.0-preview.1-windows-amd64.msi (recommended). One UAC prompt. It installs to C:\Program Files\hyperbutler, adds the folder and its bundled docker CLI to the end of PATH, turns on Virtual Machine Platform if needed, and, if you tick the box, adds your account to Hyper-V Administrators. Then sign out and back in (or restart if asked), and run:

  hyperbutler start
  docker run --rm hello-world
  

• hyperbutler-v0.1.0-preview.1-windows-amd64.zip: no installer. See the README's Quick start.

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

Measured against Docker Desktop (same laptop, defaults)

	hyperbutler	Docker Desktop 4.97 (WSL 2)
Needs WSL	no	yes
Download	116 MB	592 MB (+351 MB WSL)
Start until a container runs	2.5 s	5.6 s
Idle memory, VM running	322 MiB	1.7–2.7 GB
Disk 5 min after deleting ~5 GB of images	1.5 GiB, given back	6.8 GiB, kept
Bind mount: read 2000 small files	0.4 s	3.4 s

Method, raw data and what was not measured: docs/compare-docker-desktop.md. One machine is not a general result.

Release gates not met yet

These block v0.1.0 and are open for this preview (docs/release.md):

• The 24-hour soak (running now; the 1-hour soak passed with no leak).
• Integration tests on real hardware in CI, and the deferred-commit test under host memory pressure.
• bench/net-vpn, bench/coexist, bench/noadmin and the LAN registry pull.
• REQ-MEM-002 (12 GB guest) and the host-disk-full test with the release build.
• Re-measuring start and idle memory with this exact release image (the numbers above come from a local build of the same code).
• The installer's options page, a first-time Hyper-V Administrators add and the Virtual Machine Platform step have not run on a fresh PC yet (install, upgrade and uninstall were tested on one machine).

Known gaps

• Daily use needs your account in Hyper-V Administrators (the installer can add it, with your consent). A privileged broker service that removes this need is designed (ADR 0004) but not shipped.
• No Kubernetes, no Windows containers.
• Unsigned builds; the installer is English only (the app and window follow your language, Korean included).
• The app checks GitHub for a new version once a day; hyperbutler config set updateCheck false turns that off. hyperbutler sends no usage data or telemetry.

Assets

• .msi, .zip: the installer and the portable build.
• hyperbutler-v0.1.0-preview.1-guest-sources.tar: the corresponding source of the guest image's GPL components.
• hyperbutler-v0.1.0-preview.1-guest-inputs.tar: the signed Alpine packages the guest image was built from.
• .spdx.json: SBOM. SHA256SUMS: checksums. Build provenance is attested (Sigstore).