2026-03-18 — Stable 2.40.5
2.40.5 is the stable checkpoint where the March 18 Home Assistant packaging and release-engineering changes finally lined up with the shipped runtime and docs.
What shipped
Section titled “What shipped”Manual port overrides without breaking HA ingress
Section titled “Manual port overrides without breaking HA ingress”Operators can now set top-level WEB_PORT and BASE_LISTEN_PORT overrides from the web UI, raw config, and Home Assistant add-on options.
In add-on mode the installed track keeps its fixed ingress port (8080 stable, 8081 RC, 8082 beta). Setting WEB_PORT opens an additional direct host-network listener only when it differs from that track default.
Safer side-by-side HA add-on tracks
Section titled “Safer side-by-side HA add-on tracks”The add-on packaging now treats stable, rc, and beta as distinct install tracks with different defaults:
| Track | Directory | Default ingress | Default player port base | Startup |
|---|---|---|---|---|
| Stable | ha-addon/ | 8080 | 8928 | auto |
| RC | ha-addon-rc/ | 8081 | 9028 | manual |
| Beta | ha-addon-beta/ | 8082 | 9128 | manual |
That makes it practical to keep stable on the main HAOS node while testing RC/Beta side by side. The caveat is operational, not technical: do not point multiple variants at the same Bluetooth speaker, adapter, or manually overridden port.
Changelog-driven GitHub releases
Section titled “Changelog-driven GitHub releases”The Create GitHub Release workflow now treats CHANGELOG.md as the canonical release source:
- resolve the target tag and channel
- sync
ha-addon/,ha-addon-rc/, andha-addon-beta/onmainfrom the latest known channel tags - build the release body from the matching changelog section
- append GitHub-generated notes only when they add useful context
This made release notes predictable again and kept HA packaging sync in the same release motion.
Installed track vs update_channel
Section titled “Installed track vs update_channel”March 18 also clarified a long-standing source of confusion:
- the installed track is the add-on variant you installed from the HA store
update_channelis only the bridge’s preferred lane for update checks and warning copy
Saving rc or beta in the UI no longer implies that Home Assistant has already switched the installed add-on.
HA-facing fixes found on live systems
Section titled “HA-facing fixes found on live systems”Live HAOS validation also produced the fixes that rounded out the stable release:
- album artwork stays on the active add-on origin through ingress
- solo-player MA queue commands keep working even when syncgroup discovery is empty
- optional manual add-on port overrides no longer fail Supervisor validation when left unset
Why this release matters
Section titled “Why this release matters”2.40.5 was less about a single runtime feature and more about making the whole delivery story coherent:
- the runtime, add-on manifests, and docs now describe the same track model
- changelog entries now drive release narratives instead of being reconstructed after the fact
- stable / RC / beta testing on one HAOS host is safer and easier to explain
- operators have explicit port/track semantics instead of hidden Supervisor behavior
Follow-up
Section titled “Follow-up”This entry is the baseline for later notes about Starlight doc refreshes, further add-on channel evolution, and the runtime architecture work that continues after the 2.40.5 stabilization wave.