Getting Started

Prerequisites

• macOS 15 or later (USB accessory passthrough requires macOS 27)
• Apple Silicon Mac

Installation

Homebrew (recommended)

brew install ingmarstein/havm/havm

Verify the installation:

havm version

Run in the foreground

havm run

The VM boots and stays attached to your terminal. Press Ctrl+C to stop.

Run as a background service

brew services start havm

The VM starts at login and restarts automatically if it exits. View logs with:

brew services info havm

When running as a service, havm uses separate paths to avoid conflicts with foreground runs:

First Run

On first run, havm handles everything automatically:

1. Download — fetches the latest stable Home Assistant OS release for generic aarch64 (.img.xz)
2. Decompress — decompresses the XZ archive using the built-in libzma wrapper
3. Copy & resize — copies the raw disk image to ~/Library/Application Support/havm/vm/haos.img and resizes it (default 32 GiB, configurable)
4. Boot — boots via UEFI from the GPT disk image

The download is cached in ~/Library/Caches/havm/, so subsequent installs or re-runs skip the fetch.

Next Steps

• Configure CPU, memory, disk, and network settings
• Set up SSH access for debug shell and graceful shutdown
• Enable Prometheus metrics for monitoring
• Attach USB accessories like Zigbee coordinators

Updating HA OS

HA OS updates are handled from within Home Assistant itself (Settings → System → Updates). havm only manages the VM; it doesn’t re-download HA OS after the initial setup unless you run havm cleanup first to clear the cache.