Per-App channels (stable/beta/dev) — share /data across pre-release variants

[agners]

Problem statement

There is an obvious, ongoing need for Apps (formerly add-ons) to ship pre-release builds alongside their stable release so users can opt into testing without losing their existing setup. The problem is that Supervisor has no first-class concept of an "App channel" — so the ecosystem implements this with three distinct workarounds, all of which have significant downsides:

Workaround A: option flag inside a single App. One slug, one container image that bundles both runtimes; a config option (commonly beta: true) switches behavior at startup.

• OpenThread Border Router (home-assistant/addons, openthread_border_router) — has a beta: false option in its schema.
• Matter Server (home-assistant/addons, matter_server) — has beta: false. Its run script inspects the flag and, if true, npm installs matter-server@latest and execs the JavaScript Matter Server; otherwise it runs the Python Matter Server. The stable image therefore ships both the Python runtime and a full Node.js + npm toolchain so beta can be activated by toggling a checkbox. There are also escape-hatch options (matter_server_version, matter_sdk_wheels_version, matter_server_args, matter_server_env_vars) so power users can pin a specific upstream version — each of which is essentially a workaround for not being able to install a different image.

Tradeoffs: same /data and options survive switching, which is the property authors actually want — but the stable image carries a beta runtime, the schema is polluted with channel-control fields, and switching back/forth happens via config edits with no safety net.

Workaround B: separate Apps with distinct slugs in the same repo. Technically cleaner image separation, allows parallel install in theory, but the App's persistent state is tied to the slug, so users either lose state when migrating or the project has to push state out of /data into shared folders.

• ESPHome (esphome/home-assistant-addon) — three slugs: esphome, esphome-beta, esphome-dev. URLs differ (esphome.io / beta.esphome.io / next.esphome.io). All three map config:rw (Home Assistant's main config/ folder) and store device configs there rather than in /data — that's how migration works in practice. Default port 6052 is not exposed by default, so parallel install doesn't collide unless exposed manually.
• Zigbee2MQTT (zigbee2mqtt/hassio-zigbee2mqtt) — zigbee2mqtt (stable) and zigbee2mqtt-edge. Different images (ghcr.io/zigbee2mqtt/zigbee2mqtt-{arch} vs …-edge-{arch}), shared state via share:rw + homeassistant_config:rw. Identical port mapping for 8485 (socat), exposed by default, so parallel install collides by default.
• Frigate (blakeblackshear/frigate-hass-addons) — six variant slugs: frigate, frigate_beta, frigate_fa, frigate_fa_beta, frigate_oldcpu, frigate_proxy. Same image with different tags; many overlapping ports (WebRTC running on 8555 tcp and udp), exposed by default.
• Music Assistant (music-assistant/home-assistant-addon) — four slugs: music_assistant (stable 2.8.7), music_assistant_beta (2.9.0b13), music_assistant_dev (1.5.2 — a different upstream branch), music_assistant_nightly. No port configuration, host network, tries to bind at least port 8097 by default which collide.
• Room Assistant (mKeRix/hassio-repo) — separate dev slug published alongside stable, same pattern as the other Workaround B examples.

Tradeoffs: clean image and per-channel options schema, no runtime is conflated. But state doesn't carry over: communities steer users to keep config in HA's config/ or share/ (fragmenting backups and Supervisor's data model), and parallel install — the supposed benefit — usually doesn't work without manual port surgery because every variant ships the same defaults.

Workaround C: a whole store repository per channel. Each channel is shipped as its own store repo; the same app is then maintained in parallel across multiple repositories under the same in-repo slug. Users add each repository they want access to. From Supervisor's perspective these are still independent apps because the store key is namespaced by repository (<repo>_<slug>).

• Community Add-ons (hassio-addons), the largest single source of apps in the ecosystem — three repos:

  • Stable — added by default in Home Assistant.
  • Beta
  • Edge

  Every app exists in all three. Notably, the beta and edge repositories contain more apps than stable — new apps are commonly iterated on in beta/edge first and only promoted to stable once they're proven (some never reach stable). The patterns Frenck established here have been widely copied, so a number of other smaller stores follow this same model.

Tradeoffs: cleanest from an authoring perspective — each repository has its own release branch, release cadence, and build pipeline. But users must subscribe to multiple stores, and Supervisor sees the same app three times under three different slug keys with no relationship between them, so state doesn't carry over and the user has no way to "switch" — they install, configure, migrate manually.

Why this matters for OHF. App quality depends on getting more users onto pre-release builds before stable cuts. All three workarounds make opting-in friction-heavy or risky:

• Workaround A asks users to flip a hidden checkbox with no rollback, and pushes the stable image to permanently ship a beta runtime.
• Workaround B asks users to reinstall and lose their setup, then re-onboard devices/credentials in the beta variant.
• Workaround C asks users to manually subscribe to multiple stores and re-install the app in each one to migrate between channels.

None of them encourages broad testing. The result is fewer testers, fewer pre-release bug reports, and bugs that land in stable.

Community signals

The strongest signal today is the breadth of the workarounds themselves — the most-installed Apps in the ecosystem (Matter Server, OTBR, ESPHome, Z2M, Frigate, Music Assistant, Room Assistant, plus the entire Community Add-ons catalog) have all independently invented a channel mechanism, and none of them are quite the same.

From Supervisor repository:

• Beta & Stable Addons using the same image, uninstalling one results in the image for the other being removed home-assistant/supervisor#5244: Direct, concrete evidence of the cross-slug coupling problems that arise from workaround B (separate-slug channels). Strong signal to cite.
• RFC: Add-on downgrade/upgrade home-assistant/supervisor#1843: Related lifecycle discussion; talks about version pinning / downgrade flows that overlap with the channel-switch motion. Comments mention the lack of channels.

Scope & Boundaries

In scope

• Allow one App to declare multiple channel variants (stable / beta / dev) from a single repo directory, sharing slug, /data, options, ingress route, and discovery.
• Supervisor-side channel switching with a safety net (automatic per-App backup before switch).
• API and frontend surface to view and select an installed App's channel.
• Full backward compatibility — existing single-config.yaml Apps behave exactly as today.

Not in scope

• Cross-channel /data migration logic — remains the App author's responsibility, like any major-version upgrade.
• Automatic channel upgrades — switching is always user-initiated.
• Replacing the existing standalone pre-release Apps on day one. This is opt-in for App authors; existing duplicated slugs can keep working.
• Parallel install of multiple channels of the same App — explicitly not supported (the whole point is one logical App).
• Channel variants of the same App living in different store repositories. All variants must live in one repository directory; users should not have to subscribe to multiple stores to access channels (this would contradict the unified-App approach).

Foreseen solution

App authors place additional manifests in the same directory of their store repo, with a channel suffix derived from the filename:

my-app/
├── config.yaml          ← stable
├── config.beta.yaml     ← beta
└── config.dev.yaml      ← dev (optional)

All variants share the same slug: and (typically) most of the manifest, but declare a different image: and version:. No new manifest field is introduced.

The set of recognized channels is fixed by Supervisor — stable, beta, dev (mirroring Home Assistant Core's own update channels). Free-form author-chosen channel names were considered and rejected: a fixed vocabulary keeps the UI consistent, the strings translatable, and prevents the channel mechanism from being repurposed as a generic "app variant" system (e.g. capability splits like full-access vs. minimal, or hardware splits like oldcpu).

Supervisor groups these into a single logical App. The user-visible model:

• The Store lists one App with an available_channels set. available_channels is not an authored field — Supervisor derives it from which config.<channel>.yaml files exist in the repo, so no new metadata file is needed.
• An installed App carries a persisted channel. On a fresh install, default = the highest-stability channel the App currently offers (stable > beta > dev). Apps may exist without a stable variant — common during early development, and confirmed in practice by Community Add-ons where new apps iterate purely in beta/edge before promotion. Supervisor handles this naturally because the channel set is ordered.
• Switching channel is a single Supervisor operation: take a partial backup of just this App, swap the image (re-using the existing update path which already handles image-name changes), and start the new variant against the existing /data and options. On failure, roll back and surface a restore suggestion.
• New endpoint: POST /addons/{slug}/channel. Info responses gain channel and available_channels.

Conceptually the same as Home Assistant Core's own update channel, but per-App.

Risks & open questions

• Options-schema divergence across channels. If beta tightens or renames an option, stable's stored options can fail validation on switch. Mitigation: validate current options against the target schema before pulling the image; abort early with a suggestion to reset options if invalid.
• /data layout differences. Not handled by Supervisor — author responsibility, same as a major version upgrade today. The pre-switch backup is the safety net. Should apps have options to prevent downgrade/force backup restore? We don't really deal with that with Core either (manual downgrade is possible). Apps also don't need to use the channel feature.
• App author migration cost. Frigate's frigate_fa (full-access) variant is a capability split, not a channel split — it shouldn't be folded into channels. We should document clearly what channels are and are not for so authors don't try to model unrelated forks (e.g. oldcpu) as channels.
• Frontend UX. How prominent is the channel selector? Always visible per App, or hidden behind "advanced"? How do we signal beta risk without being alarmist?
• Naming. Core already uses "channel" for the Supervisor/OS/Core update stream. Reusing the term for Apps is intuitive but could be confused; consider whether "App channel" is sufficiently distinct in UI copy.
• Discovery/migration for existing duplicated Apps. What is the recommended path for projects with already-deployed foo + foo-beta slugs (Workaround B) or three separate store repos (Workaround C) to consolidate without breaking existing installs? Likely needs a migration tool or documented one-time backup-restore-into-stable flow.
• Pull-failure mid-switch. The old container is stopped before the new image pulls. On failure, the App stays stopped until the user restores. Needs clear UX.

Appetite

Small–medium.

• Supervisor: contained — store scanner change, one new state field on installed Apps, one new operation that reuses the existing update path, one API endpoint.
• Frontend: per-App selector + an info pill + a confirmation dialog highlighting the auto-backup.
• Docs + author guidance: the longer tail — how to structure repos, schema-compat guidance, recommended migration story for existing duplicated Apps.

Roughly 1–2 cycles of focused work across Supervisor, frontend, and developer docs.

Decision log

Date	Decision	Outcome

[github-actions]

Hi @agners,

Thank you for your interest in the Home Assistant roadmap!

This repository is restricted to Open Home Foundation staff and authorized contributors only. Community members cannot directly create roadmap opportunities.

How to influence the roadmap:

1. 🚀 Submit your ideas to the Feature Requests
2. 🗳️ Vote and discuss on existing feature requests
3. 👀 The product team regularly reviews popular requests and creates roadmap opportunities based on community needs

Your input is valuable and helps shape Home Assistant's future! Please share your ideas in the Feature Requests where they can be properly discussed and evaluated by the community and product team.

If you believe you should have access to create roadmap opportunities, please contact the Open Home Foundation team.

This issue will now be automatically closed.

[mdegat01]

Yea we've been talking about this for a very long time. By the way there is one rather large example missing, Frenck's:

1. Stable Community Add-ons (github) - This is the one added by default to HA
2. Beta Community Add-ons (github)
3. Edge Community Add-ons (github)

Every app in the community add-on store has a beta and edge version as well, Frenck just always chose to manage by making each channel its own repo. The patterns Frenck established for this repository are copied and reused a lot since people liked the idea of each app in its own github repo so I expect there's a number of others following this pattern. So this should probably be added as a Workaround C.

Can also add room assistant (github) as a popular app with a separately published dev channel. It's following the same pattern as those in Workaround B.

I don't know any others off the top of my head but perhaps others can add them as they read this.

App authors place additional manifests in the same directory of their store repo, with a channel suffix derived from the filename:

Should we force the names? available_channels doesn't have to be an enum, it could be just a set[str] and then require for each channel you list there is a corresponding config.<channel>.yaml without requiring specific names. Default could either be stable, first one in the list or a separate default_channel option in app config.

An installed App carries a persisted channel (defaults to stable).

On this, an interesting note is if you look through the Beta and Edge Community Add-ons you'll notice that there are more in beta and edge then in stable. I don't know if he still does this but it seems Frenck used to iterate on add-ons purely in beta/edge channels before eventually promoting them to stable (or not if they didn't make it). Others may want to do this too. It seems valid and supportable easily enough as long as we don't assume there is always a stable.

The Store lists one App with an available_channels set.

The proposal shows a config.yaml per channel. But this particular config option is not channel specific. It feels like there's a missing metadata file in the picture above that should hold this. Perhaps this should be in repository.yaml? Or if we're specifically avoiding using that since its long-term future is murky then perhaps a new app.yaml file that holds channel independent metadata. Such as available_channel, slug, probably name and I'm sure some others if we went through.

We should also documentation per channel to the In-scope list. Currently the following assets are pulled from current version in store rather then the actually installed version:

• README (the details on the overview page)
• Documentation
• Icon
• Logo
• Changelog

All of these can change per version (and now per channel) and probably would prefer a way to list them per channel like with config.yaml. However the most important one by far is Documentation as developers need to document the current features as they work in each version. Changelog would also be a good one to have a way for developers to publish a separate one per channel if they wish but not as necessary as documentation. The others feel more like nice to haves.

[agners]

Wrt community add-ons and room assistant: Good point, I'll add them to the main description!

I guess with Workaround C the question becomes do we support different app channels living in different store repositories (stable in one, beta in another). I think I'd say no to this, it seems to contradict the approach we are taking.

Should we force the names? available_channels doesn't have to be an enum, it could be just a set[str] and then require for each channel you list there is a corresponding config.<channel>.yaml without requiring specific names. Default could either be stable, first one in the list or a separate default_channel option in app config.

Hm, yeah it seems cheap, but I wonder if it adds a lot of value. Quickly the question becomes what does this channel even mean? And it could be "miss-used" for apps variants, which we probably don't want? 🤔

With a fixed set of channels we can also translate and make the UI consistent.

An installed App carries a persisted channel (defaults to stable).

On this, an interesting note is if you look through the Beta and Edge Community Add-ons you'll notice that there are more in beta and edge then in stable. I don't know if he still does this but it seems Frenck used to iterate on add-ons purely in beta/edge channels before eventually promoting them to stable (or not if they didn't make it). Others may want to do this too. It seems valid and supportable easily enough as long as we don't assume there is always a stable.

Hm good point. Maybe we'd just select the most "stable" then (stable > beta > dev). That only works though if we have a clear set of channels with known order. But I think I agree, we should support missing stable, for new apps.

The Store lists one App with an available_channels set.

The proposal shows a config.yaml per channel. But this particular config option is not channel specific. It feels like there's a missing metadata file in the picture above that should hold this. Perhaps this should be in repository.yaml? Or if we're specifically avoiding using that since its long-term future is murky then perhaps a new app.yaml file that holds channel independent metadata. Such as available_channel, slug, probably name and I'm sure some others if we went through.

In my mind available_channels is a hardcoded Supervisor thing, essentially the channels we have today. I'd rather avoid a new metadata file, the current suggested design tries to avoid exactly this to make adoption easier and keep the impact minimal.

We should also documentation per channel to the In-scope list. Currently the following assets are pulled from current version in store rather then the actually installed version:

* README (the details on the overview page)
* Documentation
* Icon
* Logo
* Changelog

All of these can change per version (and now per channel) and probably would prefer a way to list them per channel like with config.yaml. However the most important one by far is Documentation as developers need to document the current features as they work in each version. Changelog would also be a good one to have a way for developers to publish a separate one per channel if they wish but not as necessary as documentation. The others feel more like nice to haves.

Hm, this is a very good point, and complicates things a bit 😢 . Besides the listed, for those without an image the Dockerfile itself would need to exist per channel 🤔 . As for the others, only supporting CHANGELOG.<channel>.md and DOCS.<channel>.md might be indeed good enough and would keep the complexity somewhat low.

What we also could consider is using directory: my-app.beta/. With that we could maybe also support the same app (different channel) living in different stores 🤔 .

Update: I've updated the main description according to some of my comments here. The per-channel docs as well as the idea using directories instead needs a bit more discussion I guess.

[mdegat01]

With a fixed set of channels we can also translate and make the UI consistent.

This is a good point. Fixed set of channels preferred then.

In my mind available_channels is a hardcoded Supervisor thing, essentially the channels we have today.

Hm I get it. With channels hard-coded you're thinking we'd be looking for the config.<channel>.yaml file (or now potentially an app.<channel> folder) to tell us whether a channel is in use. And then not need this metadata.

Ok that's fine. But changes are required to leverage this, its not going to be free for app developers. A small new metadata file doesn't seem like much work to ask for if it makes everything easier to implement and understand imo. But I suppose that can be left for implementation details anyway.

Besides the listed, for those without an image the Dockerfile itself would need to exist per channel 🤔

You're right with how it works today. However I should probably point out neither of us really likes the build option and would prefer linked images for all apps since then apps all start from a predictable state. This new feature is not required to support this setup. It doesn't seem like a good idea to complicate things to support what we consider to be a suboptimal setup.

I think any app making use of a multi-channel setup is likely to be a well-known app that is pretty far along the production pathway. Making image a required field in this setup doesn't seem likely to prevent any potential consumers from being able to use it imo. The kinds of apps doing multi-channel all publish images to a public repository already anyway. The build option could be left as something only available for single channel apps.