# home-assistant-matter-hub: publishing Home Assistant to Matter controllers > This project simulates Matter bridges so that entities from a Home Assistant instance appear in Apple Home, Google Home, Alexa, SmartThings and Aqara Home over local communication, with no port forwarding needed. The current maintainers took it over as a community fork after the original was discontinued in January 2026, and they run three release channels from three branches. **RiDDiX/home-assistant-matter-hub** — Publish your Home-Assistant Instance using Matter. - Repository: https://github.com/RiDDiX/home-assistant-matter-hub - Stars: 1,345 · Forks: 74 - Language: TypeScript - License: Apache-2.0 - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/riddix-home-assistant-matter-hub ## Local communication, and why that is the point The project simulates bridges to publish your entities from Home Assistant to any Matter-compatible controller like Alexa, Apple Home, Google Home, SmartThings or Aqara Home. Using Matter, those can be connected easily using local communication without the need for port forwarding and similar tricks. That last clause is the reason the project exists, and it is worth expanding. Exposing a Home Assistant instance to a cloud voice assistant or a phone app usually means one of two things: you open a port on your router and deal with the security consequences, or you run a relay in the cloud and accept that your traffic leaves your house. A local Matter bridge avoids both, because the controller and the hub speak to each other over the local network. The mechanism is bridge simulation. Matter controllers expect to find bridges, and the hub creates the appearance of one, mapping Home Assistant entities onto the device types that the controller understands. The mapping is the hard part, and it is where most of the project's work goes. A light has to become a Matter On/Off Light, a binary sensor has to become the right kind of contact sensor, and a vacuum has to report a finished clean in a vocabulary the controller recognises. The documentation site has a page of supported device types, and it is the page to read before buying hardware. ## A fork that exists because the original stopped The README carries a note about the project's own history, and it is the kind of note that tells you a lot about the state of a project. This is a community fork, the actively maintained fork and successor of the original t0bst4r home-assistant-matter-hub, which was discontinued in January 2026 and has since been archived. The note thanks the original author, @t0bst4r, for the original work, and says the fork continues with bug fixes, new features and community support. For users, the message is that the project did not die, it changed hands. The README points at a migration guide and says the important thing for existing users: your paired devices will continue to work. That is a significant claim, since re-pairing a smart home device is a chore that involves a controller app and often physical interaction with a button on the device. The add-on slugs are the practical detail for anyone installing this. They are hamh for the stable channel, hamh-alpha and hamh-testing, so the same Home Assistant instance can have all three installed side by side, which is what makes the fork comparison page possible and what lets an early adopter run the alpha while the rest of the household stays on stable. The documentation site also has a fork comparison page listing features side by side, which is the sensible way to check whether the fork has caught up with anything the original had planned. ## Three channels, three branches, and how to choose The releases and branches table is the clearest statement of how the project is run. The Stable channel sits on the main branch at v2.0.58 and is described as production-ready and recommended for most users. The Alpha channel is on the alpha branch at v2.1.0-alpha.937, ahead of stable, and carries the additions listed under Alpha Features. The Testing channel is on the testing branch at v4.1.0-testing.x, marked with a warning that it is highly unstable, experimental, and may break. The guidance that follows is a simple three-way split. Most users should use stable, which is thoroughly tested. Early adopters should use alpha, which gets every fix and feature first. Developers and testers should use testing, which is bleeding edge and where breakage is expected. Two things follow from the table. First, the alpha line is versioned 2.1.0 while the testing line is 4.1.0, so the numbering jump between channels is large, and a channel switch is not a version bump but a different line of work. Second, the release list shows alpha builds shipping several times a day, v2.1.0-alpha.936, .937 and .938 all on 2026-10-14 and 2026-10-15, which tells you how the alpha channel is used: it is a rolling release of whatever is on the branch, and the stable channel is the one that gets the careful treatment. The repository carries a semantic-release configuration, so the version numbers in the table are produced by the release tooling rather than by hand. ## The upgrade that makes some devices re-pair The README documents one upgrade in detail, and it is the kind of note that saves a support thread. When upgrading from 2.0.46, a few entities re-pair once on the first start after the update and lose their room assignment in the controller. The list of affected cases is specific: leak and freeze binary sensors, which are now contact sensors by default, and any entity using the On/Off Switch override; and a light may drop its automatic power and energy readout, which you re-add by mapping the sensor by hand. The fix is manual but bounded. You re-assign the affected devices to their rooms after they reconnect, and the documentation's supported device types page has the detail. Two things about this note are worth noting. It is a device type change rather than a bug, the binary sensors became contact sensors because that is the better Matter mapping, and the consequence is that an existing pairing no longer matches the new type. And the note names the exact versions involved, 2.0.46 to the current stable, so an operator can decide whether to plan the re-pairing for a maintenance window or to stay on their current version. The same caution appears elsewhere in the README, in the feature list, where the stable release notes describe a light that can be set to an On/Off Plug-in Unit because Apple only shows wattage on outlets, and where the port 80 check in the Health Dashboard exists because freeing that port helped two users pair Alexa. ## The release notes read like a support log The stable feature list for v2.0.58 is long, and reading it tells you what kind of project this is. Several entries are bug fixes that only make sense if you have lived with the bug. Old backups get deleted again, because the automatic backup only runs while the add-on shuts down and the add-on gets a few seconds to stop, so the backup could be cut off before it reached the cleanup, leaving one more half-written backup in the list on every restart. Backups now keep a temporary name until they are complete, so a cut-off one never shows up. The backup settings are checked as well, with a keep count between 1 and 100 and a failed write failing that backup instead of crashing the app. Other entries are interoperability gaps. A bridge that went quiet comes back on its own, because a subscription that died while starting left every device offline until a restart. Dishwashers understand Home Connect and SmartThings states, and washers and dryers on a power switch show their real state. Every paired controller shows on the bridge card, where it previously showed only Google and Alexa, and 4448 now shows as Sengled. And a few are quality of life. No flash when Alexa dims a light that is off, because it now turns on straight at the new level instead of at its old brightness first. Vacuum rooms reset when a clean finishes on its own. Every one of these has an issue number attached. For a project that is largely one maintainer's work on top of someone else's, that is a good sign of how the fixes are tracked. ## The workspace, the session rotation and the release pipeline The repository is a pnpm workspace with the package manager pinned at pnpm 10.33.0 and Node 24 required. The root package is private and named @home-assistant-matter-hub/root, with workspaces for apps, packages and docs. The build and test scripts are conventional for a pnpm monorepo. The lint step is biome check, the test step runs across the workspace with a pretest that builds the common package first, and there are separate build targets for the minimal common build and for the app packages. The release pipeline uses semantic-release, and the publish step is worth looking at: ```json "release:publish": "pnpm publish apps/home-assistant-matter-hub/package.tgz --provenance --no-git-checks --access public --loglevel verbose --tag ${CHANNEL:-latest}" ``` The provenance flag means the published tarball carries a build attestation, and the channel tag comes from an environment variable, which is how one repository publishes to a stable channel, an alpha channel and a testing channel with the same command. The environment sample shows the configuration surface, and one line is worth understanding: ```yaml HAMH_HOME_ASSISTANT_URL="http://192.168.178.111:8123/" HAMH_HOME_ASSISTANT_ACCESS_TOKEN="" HAMH_STORAGE_LOCATION=~/.hamh-development HAMH_LOG_LEVEL=debug HAMH_MATTER_SESSION_MAX_AGE_HOURS=4 ``` The session age setting rotates Matter sessions older than a number of hours so that iPhone clients re-subscribe and Apple Home unsticks tiles that are stuck on Updating. The comment gives the range as 1 to 168 with 0 disabling it. That is a workaround for a real interoperability problem between Apple's controller and Matter session lifetimes, and it is the sort of detail that only appears after months of field reports. The repository also carries an examples/ directory with three plugin examples, one of them deliberately broken, a showcase/ directory, a docs-site/ built from the same workspace, and a patches/ directory. ## Where a Matter bridge is the wrong choice The first wrong-tool case is an ecosystem that speaks Matter natively. If your devices are already Matter, the hub is a translation layer with no reach to add, and it introduces a second thing to maintain between you and the devices. The second is a household that does not want a bridge at all. The hub runs continuously, holds a Home Assistant access token, and simulates bridges on the local network. For a system where the smart home platform already has a working path to the voice assistant or the phone app, that is an extra service to keep updated for no gain. The third is a deployment where the entity mapping does not fit. Every device in Home Assistant has to be mapped onto a Matter device type, and the mapping is not always natural. The release notes give a glimpse of how much work the edge cases are, with dishwashers and washers on power switches, vacuums reporting a finished clean, lights that can be presented as plug-in units so that Apple shows wattage, and binary sensors that became contact sensors with a consequence for existing pairings. The fourth is a user who needs a supported product. The project is a fork of a fork, in alpha, with a testing branch that is explicitly unstable, and with the original already archived. Nothing here is wrong, and a self-hosted hobby project is exactly the right shape for that risk, but an organisation that needs a support contract has to weigh that differently. ## Conclusion Adopt the stable channel of this hub if you want your Home Assistant entities in the Apple Home, Google Home, Alexa or SmartThings apps and you would rather not open ports to the internet for it. Do not adopt it if your ecosystem is Matter-native already, since the hub then adds a translation layer without adding reach, and do not run the testing branch on a house you live in, since the README marks it as highly unstable and experimental. Before you install, read the migration notes if you are coming from the original project, and check the supported device types page, because the mapping from Home Assistant entities to Matter device types is where the incompatibilities live. ## FAQ ### What does the Home Assistant Matter Hub do? It simulates Matter bridges to publish your entities from Home Assistant to any Matter-compatible controller such as Alexa, Apple Home, Google Home, SmartThings or Aqara Home. Using Matter, those connect over local communication without the need for port forwarding. ### Which version of the Home Assistant Matter Hub should I install? Most users should use the stable channel on the main branch, at v2.0.58, which is production-ready. Early adopters can use the alpha branch, which gets fixes and features first, and developers and testers can use the testing branch, which the README marks as highly unstable and experimental. The add-on slugs are hamh, hamh-alpha and hamh-testing. ### Do I have to re-pair my devices after upgrading the Matter Hub? Only a few, and only once. When upgrading from 2.0.46, leak and freeze binary sensors, which are now contact sensors by default, and any entity using the On/Off Switch override re-pair on the first start and lose their room assignment, and a light may drop its automatic power and energy readout. You re-assign the affected devices to their rooms after they reconnect. ### What does the HAMH_MATTER_SESSION_MAX_AGE_HOURS setting do? It rotates Matter sessions older than the given number of hours so that iPhone clients re-subscribe and Apple Home unsticks tiles stuck on Updating. The comment in the environment sample gives the range as 1 to 168 with 0 disabling the behaviour. ### What licence is the Home Assistant Matter Hub released under? Apache-2.0, with the LICENSE file at the repository root. The project is a community fork of t0bst4r's original, which was discontinued in January 2026, and the alpha builds ship several times a day, with the most recent listed at v2.1.0-alpha.938 on 2026-10-15. ## Sources - [Issues](https://github.com/RiDDiX/home-assistant-matter-hub/issues) - [License: Apache-2.0](https://github.com/RiDDiX/home-assistant-matter-hub/blob/main/LICENSE) - [README](https://github.com/RiDDiX/home-assistant-matter-hub/blob/main/README.md) - [Releases](https://github.com/RiDDiX/home-assistant-matter-hub/releases) - [RiDDiX/home-assistant-matter-hub on GitHub](https://github.com/RiDDiX/home-assistant-matter-hub) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/riddix-home-assistant-matter-hub