Background prefetching for Home Assistant updates

[carlhye]

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

---

Problem statement

When a new Home Assistant release is available, applying an update is a two-step sequential process: first the update downloads, then it applies. On slower connections — or simply on a busy home network — users must wait through the full download before the update begins installing. This makes the update experience feel slow and unpredictable, and may discourage users from staying current.

There is currently no mechanism to pre-fetch a pending update in the background so it is ready to apply immediately when the user chooses to.

This affects Core updates, OS updates, and potentially Supervisor updates. The problem is not exclusive to onboarding — it is a general update experience issue that applies throughout the lifetime of a running Home Assistant installation.

Community signals

• #110 — original opportunity — prefetching was identified in this thread as useful beyond onboarding
• @frenck in #110: "prefetching is a logic that is useful beyond onboarding (for example, when clicking update on the upcoming release). Part of the storage changes in our OS will make this possible. Prework for such thing has been done."
• @frenck in #110: "the prefetching could be a cool opportunity on its own as well"
• @agners in #110: distinguishes between onboarding prefetch (unproblematic — download is happening anyway) and runtime prefetch (requires rate-limiting to avoid infrastructure load)

Scope & Boundaries

In scope

• Background pre-fetching of Core and OS updates after a new release is announced / detected
• Making update application near-instant for users on healthy connections (download already complete when user clicks "Update")
• Rate-limited or staggered rollout strategy to protect OHF infrastructure from DDoS-like load spikes post-release
• Opt-in mechanism for initial release (given infrastructure risk)
• User-facing indication that a pre-fetched update is ready to apply

Not in scope

• Forced or automatic update application — the user still explicitly triggers the install
• Background prefetch during onboarding — this is part of the "flash now" bundling opportunity (A)
• Fixing or diagnosing networking issues
• Prefetching add-on updates (out of scope for initial opportunity; could follow)

Foreseen solution

1. Release detection — when Supervisor detects a new Core or OS release is available (as it does today for the update notification), begin silently pre-fetching the update package in the background.
2. Hold, don't apply — the downloaded update is held on disk and not applied until the user explicitly triggers it.
3. Instant apply — when the user clicks "Update", the download is already complete. The update applies immediately with no download wait.
4. Rollout strategy — to avoid a spike in downloads immediately post-release (which would stress ghcr.io / GitHub release infrastructure), rollout should be staggered. Options: time-based jitter after release detection, after db-clean-up at night (would place downloads around 04:00-05:00 at any local time), opt-in toggle in system settings, gradual percentage rollout.
5. Storage indication — clearly surface that pre-fetched update data is occupying disk space, with the ability to release it if needed.
   Engineering prework is already underway in HAOS OS storage changes (@frenck).

Risks & open questions

• Infrastructure load — naive simultaneous prefetch for all users at release time would create a DDoS-like spike on download infrastructure. @agners: "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 an opt-in feature." The rollout strategy is the critical design decision here.
• Storage on device — pre-fetching requires holding the full update package on disk. On lower-storage devices (e.g. 32 GB eMMC on Green) this may be a concern. What is the minimum free space threshold before prefetch is disabled?
• Supervisor update model — does the current Supervisor support "download now, apply later"? Prework is underway in OS storage changes; exact readiness needs confirmation with @agners/@frenck.
• Partial / interrupted downloads — what happens if the device reboots or loses power mid-prefetch? Resumable downloads? Clean restart?
• Superseded pre-fetches — if a new release ships before the user applies the pre-fetched one, how is the stale pre-fetch handled?

Appetite

Medium — prework exists in the HAOS OS storage changes. The core technical path is de-risked. The main design work is the rollout/rate-limiting strategy and the storage management UX. Likely starts as opt-in.

Execution issues

No response

Decision log

Date	Decision	Outcome
2026-06-10	Split from #110 following performance review feedback from @frenck and @agners	Scoped as a standalone runtime update experience improvement, separate from onboarding and hardware concerns

[jlpouffier]

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