Fast, up-to-date first boot for pre-installed HA hardware (Green, Yellow)

[carlhye]

Spun out of: #110 — see original issue for additional community signals

---

Problem statement

Home Assistant Green and Yellow ship with HAOS pre-installed but without Home Assistant Core. On first boot, Core must be downloaded before onboarding can begin. This creates three compounding problems unique to pre-installed hardware:

1. Slow first boot. The Core download on first boot has been observed to take approximately one hour on HA Green. The root cause of this — whether download source, image size, network conditions, or something else — is not yet fully understood and requires dedicated investigation.
2. Shelf-time staleness. Hardware can spend months in transit, warehouses, and on retailer shelves before a user unboxes it. Any Core version bundled at manufacturing time will be significantly stale by the time it runs. This is a fundamentally different constraint from the "flash now" case: the image cannot be refreshed at download time.
3. Networking failures. Users on restrictive or managed networks (hotel WiFi, corporate environments, captive portals) cannot complete the Core download and are hard-blocked from reaching onboarding.
   The combination of slow download and version staleness makes it impractical to simply apply the "bundle Core at build time" approach used for the "flash now" case — the shelf-time gap creates real compatibility risks between OS, Supervisor, and Core versions.

Community signals

• #110 — original opportunity — full thread including feedback from @agners and @jlpouffier
• @agners in #110: "Hardware can be in transit and storage for months. Downloading the latest Core on first setup makes sure users don't start with a stale version" — this was the original deciding factor against pre-bundling for hardware
• @agners in #110: identified ~1 hour install time on HA Green as worth dedicated investigation
• @jlpouffier in #110: "This is not possible today for NC hardware because these hardware devices could sit on a shelf for a very long time, and would lead to incompatibilities between OS, Supervisor, and Core versions"

Scope & Boundaries

In scope

• HA Green and HA Yellow (Nabu Casa hardware product line)
• Root cause investigation of the ~1 hour first-boot install time on HA Green
• Research and solution design for the shelf-time staleness problem
• Update policy: acceptable maximum lag, long-term upgrade path compatibility (how many Core versions can we safely span with auto-update?)
• Coordination with Nabu Casa on hardware manufacturing and image refresh cadence

Not in scope

• User-flashed HAOS installations — tracked in a separate opportunity
• Generic networking fixes (DNS, VLAN, proxy, etc.)
• Software-only HAOS installations (VM, container)
• Background prefetching for runtime updates — tracked in a separate opportunity

Foreseen solution

This is a research-first opportunity. The shelf-time constraint means the "bundle Core at build time" approach used for "flash now" images cannot be applied directly. The following options are under investigation (from @agners' analysis in #110):

Option A — Download Core during onboarding (parallel with user steps)
Run the Core download in parallel with the user completing onboarding steps, then auto-apply at the end. Onboarding steps (account creation, location, integrations) provide natural "dead time" during which the download can complete. Key open question: how many Core releases can we safely span using auto-update? Compatibility across a large version gap is not guaranteed.

Option B — Pre-install a minimal onboarding Core
Ship a special, minimal Core build that contains only the onboarding flow — effectively replacing the current go-based landing page. This aligns the landing page UX with how Core behaves (mDNS announcements, etc.) and eliminates the blank-slate wait. After onboarding, update to full Core. Requires a maintained "onboarding Core" build variant.

Option C — Hardware image refresh cadence policy
Define and implement a cadence for refreshing hardware images, reducing the maximum staleness window. Would require changes to manufacturing and logistics process in coordination with Nabu Casa.

These options are not mutually exclusive and the eventual solution may combine elements of each.

Risks & open questions

• Version compatibility across a large span — auto-update from a much older bundled version to current may not be safe. Needs investigation with @agners and @frenck on how many major/minor Core versions can be spanned reliably.
• Nabu Casa coordination — any solution that affects hardware image manufacturing or refresh cadence requires alignment with Nabu Casa. This is a commercial product with logistics dependencies.
• Root cause of ~1 hour install time — the download duration on HA Green is significantly longer than expected. This may be a separate issue from the bundling question (download source speed, image size, device I/O) and needs its own investigation track.
• "Onboarding Core" build variant — Option B would require a new, maintained build artefact. Scope of ongoing maintenance needs to be understood before committing to this path.
• Update model compatibility — does Supervisor support holding and deferring a large Core update through an extended onboarding flow? What are the failure modes?

Appetite

Large — this opportunity requires research before execution can be scoped. It spans HAOS engineering (@agners), Supervisor architecture (@frenck), and Nabu Casa hardware product coordination. Execution appetite will be defined once the research phase is complete and a solution approach is selected.

Execution issues

No response

Decision log

Date	Decision	Outcome
2026-06-10	Split from #110 following performance review feedback from @frenck, @agners, and @jlpouffier	Isolated as a separate research track; shelf-time constraints make this fundamentally different from the "flash now" case

[jlpouffier]

@carlhye please make sure you correctly add proejct fields such as Product area and Main Project otherwise we could overlook your opportunities