Skip to content

Make Home Assistant OS easier to install #58

New issue
New issue
Open
Opportunity
Open
Make Home Assistant OS easier to install#58
Opportunity
Assignees
frenck
@frenck

Description

@frenck
frenck
opened on Mar 11, 2026

Problem statement

Installing Home Assistant OS today is a fragmented experience that varies wildly depending on the target hardware or platform. There is no single, official tool that guides a user from "I want to run Home Assistant" to a working system.

For single board computers (Raspberry Pi, ODROID, etc.): users rely on the Raspberry Pi Imager or third party tools like Balena Etcher. While the Pi Imager works well for Raspberry Pi specifically, any other SBC requires a different tool and a different set of instructions.

For generic x86 hardware (mini PCs, NUCs, refurbished desktops): the current documented process requires the user to either remove the internal drive and flash it externally using a USB enclosure, or boot a live Linux environment from USB, then use command line tools to write the HAOS image to the internal drive. This is a multi step process involving at least two USB sticks, familiarity with Linux, and comfort with disk operations. It is the single biggest barrier to entry for users who want to run Home Assistant on dedicated, always on hardware.

For virtualization platforms (Proxmox, UTM, VirtualBox): each platform has its own procedure. The community has historically relied on third party helper scripts (most notably the tteck/community Proxmox VE Helper Scripts) to simplify VM creation, but these are not maintained by OHF and introduce trust and maintenance concerns.

This directly impacts the OHF goal of making Home Assistant more approachable. The installation step is the very first interaction a new user has with the project, and right now it filters out a significant portion of potential users before they ever see the onboarding screen. Users who do make it through often report confusion, frustration, and wasted time, as evidenced by years of community forum posts, guides, and workaround scripts.

Scope & Boundaries

In scope

  • A cross platform desktop application (macOS, Windows, Linux) that provides a single, guided installation experience for Home Assistant OS
  • Support for flashing single board computers (Raspberry Pi, and other supported SBCs) via SD card or USB
  • Support for installing on generic x86 hardware by creating a bootable USB installer that writes HAOS to the target machine's internal drive
  • Support for creating and configuring a VM on Proxmox (via API, no helper scripts)
  • Support for creating and configuring a VM on macOS via UTM, including making UTM an officially supported platform for Home Assistant OS (it is currently not officially supported despite significant community adoption)
  • Evaluate and propose dropping VirtualBox as a supported platform, given its persistent reliability issues and the availability of better alternatives
  • Download management with caching and checksum validation
  • Hardware detection and validation (minimum disk size, memory, CPU cores)
  • Clear guidance for HA hardware (Green, Yellow) with appropriate instructions and purchase links
  • Links to documentation for platforms not directly supported by the tool (e.g., VirtualBox, Hyper V, Synology)
  • Simplified and unified installation and setup documentation, including graphical walkthroughs that align with the installer flows

Not in scope

  • Replacing the onboarding flow inside Home Assistant itself (that is a separate concern starting after the first boot)
  • Network pre provisioning (setting static IP, Wi Fi credentials, SSH keys during flash); this is desirable for a future iteration but not required for the initial bet
  • Support for every virtualization platform; Proxmox and UTM are prioritized based on community adoption, others can follow later

Foreseen solution

A desktop application, tentatively called the Home Assistant Installer (working title; final name should avoid confusion with professional installation services), built as a cross platform tool that runs on macOS, Windows, and Linux.

The application presents a clear entry point: the user picks their target platform (SBC, generic PC, Proxmox, UTM, HA hardware) and is guided through a purpose built flow for that platform. Each flow handles downloading the correct image, validating it, and writing or deploying it to the target.

Key flows:

  • Single board computer flow: Select board, select target drive (SD/USB), download image, flash. Similar to the Raspberry Pi Imager experience but covering all supported SBCs.
  • Generic x86 flow: Download image, write to USB stick, creating a bootable installer. The user then boots the target machine from this USB stick, and the installer writes HAOS to the machine's internal drive. This eliminates the need for a live Linux environment and the two USB stick dance.
  • Proxmox flow: Connect to the Proxmox API directly, create a properly configured VM (host CPU type, appropriate memory/cores, correct disk setup), and start it. No reliance on third party shell scripts.
  • UTM (macOS) flow: Create and configure a UTM virtual machine with appropriate resources, suitable as a way to test drive Home Assistant on a Mac.
  • HA hardware flow: Official hardware (Green, Yellow, Blue) flows, provides specific instructions and links.

Platform support changes:

As part of this opportunity, we propose making UTM an officially supported virtualization platform for Home Assistant OS on macOS. UTM is already widely used by the community (especially on Apple Silicon Macs where VirtualBox is not a viable option), with extensive community guides and forum activity. However, users currently operate without official support, which means issues on UTM are not triaged by the OS team and the platform is not tested in CI. Officially supporting UTM aligns with the installer providing a first class flow for it.

Conversely, we propose evaluating whether to drop VirtualBox as a supported platform. VirtualBox has a long history of reliability problems with Home Assistant OS: boot loops, ACPI shutdown failures, Bluetooth regressions, network drops after host updates, and general instability. The operating system repository carries a dedicated hypervisor/virtualbox label with a steady stream of issues. Users running VirtualBox regularly report crashes, freezes, and broken updates, and the community consistently recommends migrating to Proxmox or other hypervisors. Continuing to support, test, and build images for VirtualBox consumes engineering resources that could be better allocated to platforms with a healthier track record. Documentation should guide users toward Proxmox (or UTM on macOS) as the recommended virtualization path.

Documentation:

Alongside the installer, the existing installation and setup documentation will be simplified and unified. This includes graphical walkthroughs that mirror the installer flows, replacing the current fragmented set of per platform guides. The goal is that whether a user follows the documentation or uses the installer, they encounter the same steps and language.

The application includes safeguards such as minimum disk size enforcement (drives below 2 GB shown but not selectable), elevated permission handling (TouchID on macOS, UAC on Windows), and graceful error handling for scenarios like mid flash device removal.

A POC covering the SBC flow, generic PC flow, Proxmox flow, and UTM flow has been built and demonstrated internally. The core mechanics (image download, caching, checksum validation, disk writing, Proxmox API integration, UTM VM creation) are functional. Full walkthrough and discussion available in the project thread on Discord.

Image Image Image

Community signals

The installation experience is one of the most discussed pain points in the Home Assistant community. Signals span many years and multiple channels:

Forum posts about installation difficulty on x86 hardware:

Proxmox installation complexity:

  • Installing Home Assistant OS using Proxmox 8 (2022, 1000+ replies): the most popular community guide, relying entirely on third party helper scripts
  • Official supported install method for Proxmox? (2025): user explicitly asking for an official method since the current docs only provide a raw image with no guidance
  • The tteck Proxmox VE Helper Scripts became so essential that they were referenced in nearly every Proxmox installation guide. After the original maintainer passed away in late 2024, the project moved to community maintenance, highlighting the risk of depending on unofficial tooling

General approachability concerns:

  • Why is this so difficult? (2018, longstanding sentiment): user expressing frustration with overall complexity
  • Confused by the setup guide (2022): user unable to follow installation instructions
  • HASS Manager (2023): community member built a third party tool specifically to simplify HA installation on desktops, validating the need

Month of What The Heck:

UTM adoption without official support:

VirtualBox persistent reliability issues:

Risks & open questions

  • Naming: "Installer" may cause confusion with professional installation services (companies/people who install smart home systems). A different name may be needed. Working title for now.
  • Maintenance surface area: Supporting multiple platforms (macOS, Windows, Linux) and multiple target flows (SBC, x86, Proxmox, UTM) creates ongoing maintenance work. We should be intentional about which flows to ship first and which to defer.
  • Elevated permissions: Writing to disks and creating VMs requires elevated privileges on all platforms. The UX around permission prompts needs to be smooth (the POC already addresses this with TouchID on macOS; Windows and Linux need similar attention).
  • First boot experience: Even with a perfect flash, users currently face a waiting period on first boot while containers download. Work to bundle a full image (eliminating this wait) is already in progress separately and will complement the installer.
  • Proxmox API access: Requires the user to provide API credentials. The trust and security implications of this need to be clearly communicated in the UI.
  • Scope discipline: There is a strong temptation to also solve adjacent problems (network provisioning, backup restore during install, etc.). These are valuable but should be treated as future iterations to keep the initial bet focused.
  • UTM on macOS as production use: UTM does not support auto start on boot. The installer should set expectations that the UTM flow is primarily for trying out Home Assistant, not for production use.
  • UTM as officially supported platform: Making UTM officially supported means committing to CI testing, image builds, and triaging UTM specific issues. The scope of this commitment needs to be clearly defined.
  • VirtualBox deprecation communication: Dropping VirtualBox support will affect existing users. A clear migration path and communication plan are needed. Users should be guided toward Proxmox (or UTM on macOS) with documentation and tooling support.

Appetite

Large. This is a significant effort spanning desktop application development, platform specific integrations, and testing across multiple OS and hardware combinations.

Proposed phasing:

  1. Initial bet (this cycle): Ship the installer with the SBC flow, UTM flow, and Proxmox flow. These are functional and demonstrated in the POC. Simultaneously, simplify and unify installation and setup documentation with graphical walkthroughs that match the installer experience.
  2. Follow up bet (next cycle): Add the generic x86 USB installer flow, allowing users to create a bootable USB stick that writes HAOS directly to the target machine's internal drive. This eliminates the current painful process of booting a live Linux environment or removing the internal drive.

The POC has already validated the core technical approach for all flows, significantly de risking the initial bet. The SBC, Proxmox, and UTM flows are functional and have been demonstrated. The USB installer flow for generic x86 hardware has a clear technical path identified during POC work.

Execution issues

Populated once a bet is approved.

Decision log

Date Decision Outcome
2025-11-28 POC development started to validate technical feasibility of a unified installer tool Core mechanics proven: image download/caching/checksum, disk writing, Proxmox API, UTM VM creation all functional
2026-03-11 Roadmap opportunity created to formalize the installer as a bet candidate Captures the problem, POC findings, and community signals for the betting table

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

Opportunity

Projects

Home Assistant Roadmap

Status

Shaping

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions