What Matter Hub is
First understand where Home Assistant Matter Hub sits in a smart home, then plan your deployment with one consistent set of terms: bridge, controller, fabric, node and endpoint. You will also learn to tell its direction apart from the Home Assistant Matter integration, where the maturity limits of Stable 2.0.55 are, and which requirements you should not hand to Matter Hub.
First decide which problem you are solving
Home Assistant Matter Hub (Matter Hub from here on) turns entities you already have in Home Assistant into Matter devices and offers them to Apple Home, Google Home, Amazon Alexa or any other compatible external controller. It fits the case where "the devices are already in Home Assistant and you also want to control them from another home interface or voice assistant". Say a living-room light is managed by the Home Assistant Zigbee integration and you also want to operate it from an external controller: Matter Hub sits in the middle and translates state and commands in both directions.
The direction matters: Matter Hub is not a general-purpose controller for adding off-the-shelf Matter accessories to Home Assistant, and it does not replace the Home Assistant automation engine, its device integrations or the official Matter integration. It emulates one or more Matter bridges and exposes the Home Assistant entities that pass your filter. When an external controller sends a command to a Matter endpoint, Matter Hub calls the matching Home Assistant action; when a Home Assistant state changes, Matter Hub syncs the endpoint state.
By the end of this chapter you should be able to draw your own data flow, choose a deployment shape that fits, understand that controller support cannot be inferred from the Matter Hub version alone, and avoid the common mistake of collapsing Stable, maturity and compatibility into one thing.
Architecture: from HA state to a Matter endpoint
The Stable 2.0.55 backend is built from a few parts with clear responsibilities. HomeAssistantClient connects over the Home Assistant WebSocket API and reads states, entities and the device registry. HomeAssistantActions turns external control commands into Home Assistant service calls. BridgeService handles creating, updating, starting, stopping and refreshing a bridge. BridgeStorage keeps the configuration and its metadata. BridgeEndpointManager creates, updates or removes Matter endpoints according to the filter and the entity mapping.
| Layer | What Stable 2.0.55 is responsible for | What you see in the UI |
|---|---|---|
| Home Assistant | Holds the original entities, states, areas, labels and callable actions | Entity names, states and device capabilities are the mapping input |
| The Matter Hub backend | Filters entities, maps device types, keeps state in sync and manages the bridge lifecycle | The Bridge, Devices, Health and Settings pages |
| Matter Server Node | Each standard bridge is a ServerNode plus an aggregator endpoint that carries many device endpoints | An external controller commissions one bridge and sees the devices under it |
| External controller | Completes commissioning, stores the fabric relationship and presents the device types it supports | The controls in vendor apps such as Apple Home, Google Home and Alexa |
State sync runs in two directions. In the first, a state changes in Home Assistant, Matter Hub updates the matching Behavior and cluster attributes, and a Matter subscription carries the change to the controller. In the second, the controller writes an attribute or sends a command and Matter Hub turns it into a Home Assistant action; the real device is still managed by its original Home Assistant integration. If the Home Assistant connection drops, the bridge process may still be there, but it cannot reliably carry out actions on the original device.
Agree on node, bridge, endpoint, cluster and fabric first
| Term | What it means in this guide | Home example |
|---|---|---|
| Controller | The controlling end that commissions, manages and operates Matter nodes; the vendor decides how much it supports | The home hub and its phone app, taken together |
| Commissioner | The role that runs the first join into a fabric; usually the controller app | You choose to add a Matter accessory in a phone app |
| Node | One node on the Matter network, with an identity and network services of its own | One standard bridge is a single node to the controller |
| Bridge | A Matter node that uses an aggregator to gather several bridged endpoints; it is also the main unit of configuration in Matter Hub | Put the office lights and plugs on one bridge |
| Endpoint | A numbered unit inside a node that stands for one device function; one HA entity may map to a single endpoint or to a composed one | A dimmable light becomes a light endpoint |
| Device Type | Defines whether an endpoint is a light, a plug, a lock, a sensor and so on, and which clusters it must have | The same HA switch can appear as a plug or as another supported type, depending on the mapping |
| Cluster | A group of related attributes, commands and events, such as On/Off and Level Control | The controller switches a light through the On/Off cluster |
| Fabric | A Matter administrative domain formed by a shared trust root and operational credentials | The same bridge can join several controller fabrics |
| Aggregator | The special endpoint on a standard bridge that gathers the bridged devices | The controller finds several child devices from the bridge root node |
| Entity Mapping | The rule that turns an HA entity's state, capabilities and actions into a Matter device type and cluster | HA light brightness maps to Matter Level Control |
"One HA entity equals one physical device" is not a guarantee. Some sensors split temperature, humidity and battery level into several entities, and Stable can compose them into a single endpoint. The other way round, one complex entity may need several endpoints before it can show its different functions. So plan scale from the endpoints after mapping, not from the Home Assistant device count alone.
Matter Hub and the Home Assistant Matter integration point in opposite directions
| Question | Matter Hub | Home Assistant Matter integration |
|---|---|---|
| Main direction | Exposes HA entities to external Matter controllers | Onboards Matter accessories into Home Assistant |
| Main role | Matter bridge / Server Node | The Matter controller integration on the Home Assistant side |
| Is it a general-purpose controller | No; it does not onboard or fully manage arbitrary Matter accessories | The official path for managing Matter accessories in Home Assistant |
| Where the original state comes from | Entities you already have in Home Assistant | Matter devices that have been onboarded |
| Common use | Make lights, plugs or sensors that live in HA appear in an external ecosystem | Make native Matter lights or sensors appear in HA |
| Can they coexist | Yes, but avoid exposing the same entity through several paths at once: that creates duplicate devices and command loops that are hard to trace | |
If a native Matter accessory is first onboarded by the Home Assistant Matter integration and then exposed by Matter Hub to another controller, what the outside sees is an endpoint remapped by Matter Hub, not Matter Hub taking over the original device's fabric. That kind of bridging can be useful, but compatibility rests on three layers: the HA entity's capabilities, the Matter Hub mapping and the target controller. "The original device supports Matter" is not enough to conclude that every control survives.
Release channel, maturity and controller support are three separate things
This guide is pinned to Stable v2.0.55, commit 6c8e8403d488fb06d2ac02d9199b92a0b8e8dccf. A release channel only answers which release line the code came from. Product maturity answers whether a feature is still experimental. Controller support answers whether a particular vendor recognizes a given device type or cluster. Release channel, maturity and controller support guarantee nothing about each other.
| Kind of fact | How to read it for Stable 2.0.55 |
|---|---|
| Stable channel | The release line recommended for most users; every procedure in this guide follows this pinned version |
| Alpha channel | Upstream says it is level with Stable at this point in time, but it is still a separate release line; that is no reason to write future Alpha behavior into Stable |
| Testing channel | Highly unstable and meant for development testing; its architecture and behavior are out of scope for this guide |
| Experimental inside Stable | Server Mode with several entities, the Camera Plugin, the Security Plugin and some Matter 1.4 device types exist in Stable, and you must still treat them as experimental or as needing verification on the target controller |
| Controller support | Apple, Google, Alexa, Aqara and SmartThings each support different types; unknown is not support, and "not listed" is not proof that it will fail |
A standard bridge works in Stable, but that does not mean every mapping inside the bridge is presented by every controller. Camera has a built-in plugin in Stable, yet its maturity is still experimental, and the v2.0.55 documentation limits it to the SmartThings direction and flags the media path as still to be verified. The Server Mode route is in Stable too, but a multi-device node is explicitly experimental; a node dedicated to a single robot vacuum is the more conservative use.
Supported deployment shapes and their shared limits
| Shape | Who it suits | Main limits and responsibilities |
|---|---|---|
| Home Assistant OS Add-on | Most readers who run HA OS and want Supervisor to manage the lifecycle | HA OS only; the add-on still needs correct LAN, IPv6 and mDNS. For the pinned mirror details see Chapter 2 |
| Docker host network | Users who manage their own containers, backups and updates | You have to persist /data, inject the HA URL and token properly, and maintain host networking and IPv6 yourself |
| Global npm | Advanced users who can maintain a Node.js runtime, service management and a data directory | You handle the long-running service, restarts, permissions, version pinning and backups yourself; it is not the default recommendation for most readers |
| Several standard bridges | You want to split devices by room, by domain or by controller limits | Each bridge needs a different port; more bridges, endpoints and sync work add memory and network load |
| Multi-Fabric | You want the same bridge to join several controllers | It does not mean every controller supports the same device types; plan managing and removing fabrics separately |
| Server Mode | Specific devices that have to appear standalone, such as a vacuum under a particular controller | Experimental limits remain inside Stable; ten endpoints per node at most, and several entities is especially experimental |
Matter depends on IPv6, mDNS and UDP. A container that can open the Dashboard only proves HTTP is reachable; it does not mean a controller can discover or operate the Matter node. VLANs, AP isolation, the wrong mDNS interface, a Docker-internal interface or an IPv6 address with no return path can each break commissioning, or cause No Response later. Before you deploy, draw the layer-2 network path between the Matter Hub host and the controller or home hub.
Scale is not a guaranteed number either. The endpoint count, how complex the device types are, the controller implementation and the host resources all affect stability. The upstream interface prompts you to consider splitting a large bridge; the low-resource documentation recommends planning conservatively from RAM and entity count. These are operating guidance, not a hard protocol limit that says "above this number it must fail".
Hands-on: draw the data flow before you decide to install
List the authoritative sources
On paper, or in a document that holds no secrets, list the HA domains, areas and purposes you want to expose. Write down categories and rough counts only; do not copy access tokens, pairing data or on-site network identifiers.
Mark the target controllers
For each group of devices, mark Apple Home, Google Home, Alexa or another target, and record "does this controller support the device type I need" as a field still to be verified. Do not fill unknown in as supported.
Choose the direction of exposure
Confirm that what you need is exposure out of HA. If the goal is to onboard native Matter accessories into HA, move it to a Home Assistant Matter integration plan and do not install Matter Hub for it.
Set the bridge boundaries
Start by planning one small standard bridge with non-sensitive devices that are easy to verify. If different controllers need mutually exclusive workarounds, or one bridge grows too large, split it by controller, by room or by domain.
Check the network prerequisites
Confirm that the host supports IPv6, that the controller and Matter Hub have a working mDNS/UDP path, and that there is no client isolation. Record only "passed" or "to do" here; do not keep private addresses in your notes.
Define the success criteria
Split "the dashboard shows HA connected", "the bridge is running", "the endpoint count looks right" and "the controller can read and write one test device" into four checkpoints. A failure then tells you which layer to look at, instead of sending you straight to a reset.
Maturity limits for homes and small offices
Good fit: you already have a stable set of HA devices at home and want a handful of everyday lights, plugs, covers or sensors to appear in an external controller; a small office wants one bridge per area and keeps HA as the single center for automation and state; the same standard bridge joins several fabrics and you accept that each controller presents things differently.
Pilot it first: anything that leans on newer Matter 1.4 types, complex audio and video, the experimental Camera or Security plugins, Server Mode with several entities, or that needs different controllers to treat one complex endpoint identically. Even though these sit in the Stable channel, label their maturity separately and verify them with non-critical devices.
Do not put this on Matter Hub: the full duties of a general-purpose Matter controller, port forwarding across the internet, enterprise identity governance, multi-account RBAC / SSO, or the only control path to a safety-critical device. The HTTP Basic Auth in Matter Hub is also just one optional set of basic credentials, and should not be described as a complete multi-user permission system.
Common pitfalls and safe fallback points
Treating Matter Hub as a tool for adding accessories
Go back to the data flow: if you want to add Matter accessories to HA, stop building bridges in Matter Hub and read the official Home Assistant Matter integration instead. Do not expose the same device twice to paper over a wrong direction.
The Dashboard opens, but the controller cannot find the bridge
Judge HTTP and Matter networking separately. Check IPv6, mDNS, UDP, the LAN interface and the isolation settings first, then check whether the bridge is running. A reachable web page is no reason to declare the Matter network healthy.
You see an experimental feature inside Stable
That is not a contradiction. Stable is a release channel; Server Mode with several entities, or a plugin, can sit in Stable and still be experimental. Go back to the label on each individual feature; the channel does not override maturity.
One controller is missing a control
Cross-check in order: the HA entity's capabilities, the device type and cluster Matter Hub maps to, and what the controller publicly supports. Verify with a standard type or by splitting the bridge first; do not delete the fabric or reset the bridge straight away.
The same device shows up twice
Check whether it is exposed through two bridging paths at once, or whether the same entity is included by the filters of two bridges. Keep one authoritative path: stop the duplicate bridge and confirm the impact before you change any settings.
FAQ
Is Matter Hub a Matter controller?
If I use Matter Hub, do I still need the Home Assistant Matter integration?
Is every feature in Stable 2.0.55 production-ready?
Can one bridge join several controllers?
Should I split bridges by room or by device type?
Pinned-version official and source-code references
- v2.0.55 README: purpose, channels, install shapes and feature limits
- v2.0.55 Developer Overview: bridge architecture and component responsibilities
- v2.0.55 Bridge schema: bridge, fabric, Server Mode and configuration types
- v2.0.55 Bridge implementation
- The official Home Assistant Matter integration documentation
- Connectivity Standards Alliance: the official Matter description
Every GitHub URL above is pinned to commit 6c8e8403d488fb06d2ac02d9199b92a0b8e8dccf, so later changes on the branch cannot rewrite the facts in this chapter.