Bundle Home Assistant Core in HAOS images for users flashing today

[carlhye]

Spun out of: #110 — see original issue for additional community signals
Follows on from: #58 (OS Installer)
Related engineering track: epics#59

---

Problem statement

Users who download and flash HAOS themselves today must wait for Home Assistant Core to download post-boot before onboarding can start. On slow or congested connections this takes up to 20 minutes. Users on restrictive networks — strict firewalls, VLANs, corporate proxies, captive portals — may never reach onboarding at all: the Core download fails silently and there is no obvious recovery path.

This is the very first experience a new user has with Home Assistant. The wait, and the hard failure for restricted-network users, creates a poor first impression and generates significant support load.

Root cause: the HAOS image ships without Core. On first boot, Supervisor fetches Core from ghcr.io before onboarding can begin. For users flashing today — from the installer or directly from a downloaded image — there is no technical reason this download must happen post-boot rather than at build time.

This opportunity is scoped exclusively to the "flash now" case: users who download and flash HAOS themselves in the present moment. Pre-installed hardware (Green, Yellow) is a fundamentally different problem with different constraints and is tracked separately.

Community signals

• #110 — original opportunity — full community signal thread covering both the wait time and the restrictive-networking failure mode
• epics#59 — engineering investigation already underway into bundling Core with HAOS images, including prior work in the operating-system-full-images repo
• @agners in #110: "Container images as well as Home Assistant OS images are compressed, the overall download size would be quite comparable" — image size increase is not a meaningful blocker

Scope & Boundaries

In scope

• Bundling a pinned, tested version of Home Assistant Core inside the HAOS image at build time
• Starting the onboarding experience immediately from the bundled Core — no post-boot download required
• Signalling at the end of onboarding that a Core update is available (if the device has network access and a newer version exists)
• Surfacing a repair suggestion when the network check fails, so users are informed they are running the bundled version and prompted to update when networking allows

Not in scope

• Pre-installed hardware (Green, Yellow) — tracked in a separate opportunity
• Background prefetching for runtime updates beyond onboarding — tracked in a separate opportunity
• Fixing or diagnosing underlying networking issues (DNS, VLAN, proxy, etc.)
• Providing a full offline / air-gapped update path beyond the initial onboarding window

Foreseen solution

Bundle a specific, known-good version of Home Assistant Core directly into the HAOS image at release time, eliminating the mandatory post-boot download. The flow becomes:

1. Immediate onboarding — HAOS boots using the bundled Core. No download required. Users reach the onboarding UI in seconds.
2. Background network check — In parallel with onboarding, HAOS silently checks whether a newer Core version is available and, if so, begins downloading it.
   • ✅ If it succeeds: hold the update, wait for onboarding to complete.
   • ❌ If it fails: proceed anyway — the user has a working Home Assistant, just not the newest version.
3. Post-onboarding signal — Once onboarding is complete, if a newer version was pre-fetched, signal to the user that an update is ready to apply. If no update was fetched, this step is skipped entirely. (Frenck's note: this can be done with current update handling today.)
4. Repair notification — If the network check failed entirely, surface a repair card explaining the system is running the bundled version and guiding the user to apply an update once networking is resolved.
   This builds directly on the engineering work already underway in epics#59.

Risks & open questions

• Image size increase — Bundling Core adds weight to the HAOS image. Stefan notes the overall download size remains comparable due to compression. The trade-off (larger one-time flash vs. eliminated post-boot download) is likely favourable.
• Bundled version staleness — For "flash now" users this is less of a concern than for hardware: the image is downloaded today, not from a shelf. Acceptable staleness window needs definition (tied to HAOS release cadence).
• HAOS release cadence alignment — How often do we rebuild HAOS images to refresh the bundled Core version? Does this need to align with Core release cadence?
• Supervisor update model — Does the current Supervisor support "hold and apply later"? Engineering prework is underway (epics#59); this question should be confirmed with @agners.
• Repair card UX — What does the repair card say for non-technical users? How do we avoid alarm while still being actionable?

Appetite

Small to Medium — engineering prework exists (epics#59, operating-system-full-images). This is a natural follow-up to #58. The heavier lifting is in the HAOS build pipeline and Supervisor; the frontend surface (end-of-onboarding signal + repair card) is relatively small.

Execution issues

No response

Decision log

Date	Decision	Outcome
2026-06-10	Split from #110 following performance review feedback from @frenck, @agners, and @jlpouffier	Scoped to "flash now" users only; pre-installed hardware and runtime prefetching tracked separately