Skip to content

havm 1.0.0

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 10 Sep 20:45
· 1 commit to main since this release
v1.0.0
47b23d3
This commit was signed with the committer’s verified signature.
IngmarStein Ingmar Stein
SSH Key Fingerprint: A78kgoOJXyRlkKh2lNHVnt+1RgWZcXbbHKaYJU9GosQ
Verified
Learn about vigilant mode.

The first stable release of havm — a zero-config CLI for running Home Assistant OS on Apple Silicon using Apple's native Virtualization framework.

The 0.x series was the public preview; 1.0.0 marks the CLI, config schema, and data layout as stable. havm run is still one command from download to boot, and this release does not touch your existing disk image, NVRAM, or machine identifier.

Highlights

  • Zero-config first boot — downloads the HA OS image, decompresses it (statically linked liblzma; no xz binary needed), copies it to a 32 GiB sparse APFS disk, and boots over UEFI. No kernel extraction, no initrd, no hand-tuned command line.
  • Persistent and headless — the EFI variable store and a stable machine identifier survive reboots, so your MAC address doesn't move. Built to run under brew services and start at login.
  • Bridge networking by default — the VM gets its own LAN address so Home Assistant discovery works; falls back to NAT at runtime if the binary lacks the com.apple.vm.networking entitlement.
  • Graceful shutdown — on SIGTERM/Ctrl+C: Supervisor API → debug SSH on 22222 → ha host shutdown, with force-stop only as a last resort.
  • USB accessory passthrough (macOS 27+) — attach coordinators and other USB devices from a menu bar item; they hot-attach to the running VM.
  • SSH access — an optional virtual CONFIG disk carries your authorized_keys, imported on boot for root SSH on port 22222.
  • Prometheus metrics — a built-in HTTP endpoint for VM and USB state.
  • havm import-utm — bring an existing UTM Home Assistant VM over.
  • --console — attach to the guest's virtio console (hvc0) for debugging.

Requirements

  • macOS 15 or later on Apple Silicon
  • USB accessory passthrough requires macOS 27 or later
  • Bridge networking requires the com.apple.vm.networking entitlement (Apple approval); prebuilt releases are signed with it, self-compiled ad-hoc builds fall back to NAT

Install

brew install ingmarstein/havm/havm
havm run

Or build from source (Xcode 27+, Swift 6.4) with ./scripts/build.sh release.

Known limitations

  • Shutdown is SSH/API-driven. HA OS on aarch64 uses PSCI, so the ACPI power button is ignored. With neither ha.api_token nor ssh.authorized_keys configured, havm can only force-stop the VM.
  • ha host shutdown needs the SSH add-on on port 22; the debug SSH on 22222 runs shutdown -h now directly and is the more reliable path.
  • USB passthrough needs macOS 27 — on macOS 15–26 discovery is skipped with a log message.
  • UTM import is partial — QEMU-based VMs (UTM's default for x86 guests) can't be imported, and SSH keys configured in UTM don't carry over.

Full documentation: https://ingmarstein.github.io/havm/

Assets 3
Loading