Bundle Core with HAOS to eliminate download wait and unblock users with restrictive networking

[jlpouffier]

Problem statement

First-time HAOS users face two compounding problems at the worst possible moment — during initial setup:

1. Long wait before onboarding begins. After flashing HAOS on official hardware (Green, Yellow, Raspberry Pi), the system must download Home Assistant Core before onboarding can start. This download can take up to 20 minutes depending on connection speed, leaving users staring at a progress screen with no way to proceed.

2. Users with restrictive networking never reach onboarding at all. A meaningful portion of users run non-standard network configurations (split DNS, strict firewall rules, VLANs, captive portals, corporate proxies). For these users the Core download fails silently or times out, leaving them completely blocked — they cannot reach onboarding even once. This is a hard blocker with no obvious recovery path.

Both problems share the same root cause: onboarding is gated on a network download that happens after flashing, rather than shipping a usable system image from the start. This creates a poor first impression and generates significant support burden.

Community signals

Scope & Boundaries

In scope

• Bundling a pinned version of Home Assistant Core inside the HAOS image at build time
• Starting the onboarding experience immediately from the bundled version, with no download required
• Background pre-fetching of the latest Core version in parallel with onboarding
• Applying the pre-fetched update automatically after onboarding completes (via a "Wrapping up" transition screen)
• Surfacing a repair suggestion when the background update fetch fails, so users are informed they are running an older version and prompted to update when networking is fixed

Not in scope

• Fixing or diagnosing the underlying networking issues (DNS, VLAN, proxy, etc.)
• Changing the flashing or provisioning flow itself
• 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 prefetch — In parallel, HAOS silently attempts to download the latest Core update.
   • ✅ 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 "Wrapping up" screen — Once the user completes onboarding, a brief transition screen applies the pre-fetched update before landing on the main UI. If no update was fetched, this step is skipped entirely.
4. Repair notification — If the prefetch failed, surface a repair card explaining that the system is running the version bundled with the image and that an update could not be downloaded automatically, with guidance on how to resolve the networking issue and retry.

This approach means virtually all users get a fast, successful onboarding. Users with networking issues get a working Home Assistant rather than a broken setup. And users on healthy networks still benefit from running an up-to-date version within minutes of completing onboarding.

Risks & open questions

• Image size increase — Bundling Core adds weight to the HAOS image. How much does this impact download and flash times for the image itself? Is the trade-off worth it? (Likely yes — flashing is typically done on a fast connection once, whereas the post-boot download happens on the user's live network.)
• Bundled version staleness — The bundled Core version will inevitably lag behind the latest release. How do we communicate this to users and ensure they understand they will be updated? What is an acceptable maximum lag?
• HAOS release cadence alignment — How often do we rebuild HAOS images to refresh the bundled Core version? Does this need to be tied to Core release cadence?
• Supervisor / update architecture — Does the current Supervisor update model support "hold and apply later"? If not, what is the scope of that change?
• Failure UX — What exactly does the repair card say? How do we avoid alarming non-technical users while still giving actionable information?

Appetite

Medium to large — this spans HAOS image build pipeline (Core bundling), Supervisor (background prefetch + deferred apply logic), and frontend (post-onboarding "Wrapping up" screen + repair card). Rough estimate: 2–3 focused cycles across those teams. The frontend surface area is relatively small; the heavier lifting is in HAOS build and Supervisor.

Execution issues

Decision log

Date	Decision	Outcome

[agners]

Note that there was already efforts before roadmap opportunities were a thing earlier this year: https://github.com/home-assistant/operating-system-full-images. I've added an epic to track the effort home-assistant/epics#59.

• Image size increase — Bundling Core adds weight to the HAOS image. How much does this impact download and flash times for the image itself? Is the trade-off worth it? (Likely yes — flashing is typically done on a fast connection once, whereas the post-boot download happens on the user's live network.)

Container images as well as Home Assistant OS images are compressed, the overall download size would be quite comparable. The bigger difference is probably more the download source: We did have reports in the past that the GitHub Container Registry (ghcr.io) is slow at times. OS image downloads are part of the GitHub release download.

To speed up downloads we could consider host the files elswhere. It is easier to move an OS images to a CDN than the container registry.

• Bundled version staleness — The bundled Core version will inevitably lag behind the latest release. How do we communicate this to users and ensure they understand they will be updated? What is an acceptable maximum lag?

What we've started to build allows to create bundles almost instantly. So for HAOS installations done by user this is essentially a non-issue.

However, for hardware like Home Assistant Green, a stale Core version is the biggest downside of the bundled approach: It was the deciding factor HAOS went with the current approach: Hardware can be in transit and storage for months. Downloading the latest Core on first setup makes sure user don't start with a stale version.

There are other ideas with tradeoffs as well:

• Download latest Home Assistant Core during onboarding and auto-update at the end of onboarding (is this safe from Core perspective? How many Core releases can we span using this auto-update safely)?
• Pre-install a minimal Core which contains onboarding: Essentially a special build of Core which replaces the landing page. It would make the separate (go based) landing page obsolete, aligning the "landingpage" with how Core behaves better (mDNS announcements etc.)

[florian-asche]

One more thing to think about. If someone has a up to date version running, the drive breaks and he downloads OS again. He will probably try to import a config to up to date into a old OS version.

I suggest that a Info Dialog before starting the onboarding notices a newer version and the user can choose to wait or not.

Restoring or importing configuration needs to check for version.

I also face the same issue with the PiCompose image for the Linux-Voice-Assistant. I think I will also pre bundle the image in that.

For the tag I suggest that you use a timer. 10 days after release the used-in-os-image tag will be switched on the new image. Within that time all problems should probably be solved by a minor version.

One more idea, maybe a select for which version you want to use could also be a good idea. Just to make compability for older needed versions possible.

[frenck]

Especially considering from engineering it has been driven already as @agners pointed out, I like the opportunity.

Background prefetch — In parallel, HAOS silently attempts to download the latest Core update.
✅ 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.

Honestly I think this is a different opportunity, prefetching is a logic that is useful beyond onboarding (for example, when click update on the upcoming release). Part of the storage changes in our OS, will make this possible. Prework for such thing has been done.

After flashing HAOS on official hardware (Green, Yellow, Raspberry Pi), the system must download Home Assistant Core before onboarding can start.

This for me is a larger work, that needs research and can't be solved in this moment right now. As also given as feedback during our presentation; I think we should seperate this into shipping full images for people installing "right now" vs product that are on the shelve and storage for a while (like the green, yellow). As pointed out by @agners, they have a different world of concerns to take into account.

Post-onboarding "Wrapping up" screen — Once the user completes onboarding, a brief transition screen applies the pre-fetched update before landing on the main UI. If no update was fetched, this step is skipped entirely.

With the above suggestion, that wouldn't be in play. But we could signal an update be ready already at the end of onboarding. For me that could be added as a seperate opportunity (to reduce scope) and can be done today already actually (as we already have update handling).

../Frenck

                       

Blogging my personal ramblings at frenck.dev

[jlpouffier]

Same feedback as Frenck (almost)

This is possible when you flash a boot medium to install HAOS NOW (The OS installer story).

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.

@carlhye you should split this opportunity to make it actionable right now.
This could become a follow-up opportunity of the OS installer one (#58)
Just having the ability to bundle core since you are going to flash it now.

[frenck]

Yeah and adding to that... the prefetching could be a cool opportunity on its own as well 👍

../Frenck

[agners]

Honestly I think this is a different opportunity, prefetching is a logic that is useful beyond onboarding (for example, when click update on the upcoming release). Part of the storage changes in our OS, will make this possible. Prework for such thing has been done.

Yeah and adding to that... the prefetching could be a cool opportunity on its own as well 👍

I think we need to distinguish between prefetching during onboarding (if we ship HAOS with Core onboarding) and preefetching for regular updates. There are different challenges. Prefetching regular updates has the potential to DDoS our infrastructure. We already feel the pressure with Supervisor which is much smaller. If we'd just bluntly prefetch Core for all users, this will massively load our infrastructure. After a release we'd need to space it out quite a bit. This probably would be a opt-in feature.

However, prefetching during onboarding is probably quite unproblematic, as we download Core anyways already today. It is merely an optimization, essentially save time by making necessary user interactions (onboarding) and downloading operation run in parallel. The idea I brought up:

• Download latest Home Assistant Core during onboarding and auto-update at the end of onboarding (is this safe from Core perspective? How many Core releases can we span using this auto-update safely)?

I think we should seperate this into shipping full images for people installing "right now" vs product that are on the shelve and storage for a while (like the green, yellow). As pointed out by @agners, they have a different world of concerns to take into account.

Agreed, the different set of requirements and challenges make this worth splitting. I'd roughly see three opportunities

a) Users who install Home Assistant right now: Not sure if we still need an opportunity for this, we do have the epic home-assistant/epics#59
b) Users who get hardware with pre-installed Core: This should be a separate opportunity. Main challenge/question is here how we deal with devices being on the shelf for a long time. This can (and probably will) include prefetching for this particular case.
c) Prefetching at runtime.

[carlhye]

Thanks for the thorough feedback everyone — and thanks @agners for the detailed breakdown in your last comment. It maps closely to what we discussed in our 1:1, so I think we're aligned.

Based on the discussion here and that meeting, I'd like to propose splitting this into three separate opportunities:

A) Bundle Core in "flash now" images — Scope this to users who download and flash HAOS themselves today. Bundle a pinned Core version at build time so onboarding starts immediately. This builds directly on the existing work in [epics#59](home-assistant/epics#59) and is a natural follow-up to #58 (OS installer). Pre-installed hardware explicitly out of scope.

B) Pre-installed hardware (Green, Yellow) — The shelf-time staleness problem is a fundamentally different challenge. Needs its own research track, including @agners' ongoing investigation into the ~1 hour install time observed on HA Green. Update policy and long-term upgrade path compatibility are the key open questions here.

C) Background prefetching for runtime updates — Prefetching beyond the onboarding window, useful for regular updates too. As @frenck noted, prework is already done in the OS storage changes. Likely opt-in or release-spaced to avoid infrastructure load.

One thing worth noting: opportunities A and C connect naturally to #123 (Build your home while onboarding) — the extended onboarding steps give the system time to run background updates, effectively masking any remaining latency.

Does this split make sense to everyone? If we're aligned, I'll draft the three opportunities properly.

[jlpouffier]

@carlhye It makes sense to me!

[frenck]

Thanks, @carlhye, yes; makes sense 👍

../Frenck