What Matter Hub actually does, and which direction the arrow points
Before you install anything, it helps to know what Matter Hub is actually for. This chapter sets up the vocabulary the rest of the guide leans on — bridge, endpoint, fabric, node, controller — then draws the line between Matter Hub and the Home Assistant Matter integration, because the two point in opposite directions and mixing them up is the single most common misunderstanding new readers bring to this project. It closes with the boundary between release channel, feature maturity and controller support, three facts Stable 2.0.55 keeps carefully separate.
Start with the traffic, not the product
Home Assistant Matter Hub — Matter Hub from here on — takes entities you already have inside Home Assistant and turns them into Matter devices, then offers those devices to Apple Home, Google Home, Amazon Alexa or any other Matter-compatible controller. It fits one specific situation: 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 today by the Home Assistant Zigbee integration, and you would like to switch it from an iPhone's Home app without opening Home Assistant at all. Matter Hub sits in the middle and translates state and commands both ways.
The direction is the whole point, and it is worth stating plainly because it is easy to assume the opposite: 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. What it does is emulate one or more Matter bridges and expose 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 to match.
Think of it as an interpreter standing between two people at a meeting who do not share a language. One side speaks in Home Assistant's terms — entities, states, service calls. The other speaks in Matter's terms — endpoints, clusters, commands. The interpreter repeats what one side says in the other side's words. It does not decide what gets said, and it does not run the meeting. If you want to bring a third person into the room who only speaks Matter, that is a different job — onboarding, not interpreting — and it belongs to a different part of Home Assistant.
By the end of this chapter you should be able to draw your own data flow, pick a deployment shape that actually fits it, and stop collapsing three separate facts — release channel, feature maturity and controller support — into one impression of “does it work.”
Five parts, and a sync that runs in both directions
The Stable 2.0.55 backend is built from a small number of parts, each with one job. HomeAssistantClient connects over the Home Assistant WebSocket API and reads states, entities and the device registry. HomeAssistantActions turns an external control command into a Home Assistant service call. BridgeService handles creating, updating, starting, stopping and refreshing a bridge. BridgeStorage keeps the bridge configuration and its metadata. BridgeEndpointManager creates, updates or removes Matter endpoints according to your filter and your entity mapping — the two subjects Chapters 5 and 7 cover in depth.
| 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 inside Apple Home, Google Home, Alexa and similar apps |
flowchart LR A["Home Assistant
entities and states"] --> B["Matter Hub backend:
filter, map, sync,
manage the bridge"] B --> C["Matter Server Node:
bridge + aggregator +
device endpoints"] C --> D["External controller:
Apple Home, Google Home,
Amazon Alexa..."]
State sync then runs in both directions across that same line. In one direction, a state changes in Home Assistant, Matter Hub updates the matching Behavior and cluster attributes, and a Matter subscription carries the change out to the controller. In the other, 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, not by Matter Hub itself.
sequenceDiagram participant H as Home Assistant participant M as Matter Hub participant C as External controller H->>M: a tracked entity's state changes M->>M: update the matching cluster attributes M->>C: the Matter subscription carries the change out C->>M: controller writes an attribute or sends a command M->>H: Matter Hub calls the matching HA service
Ten words the rest of this guide assumes you know
Agree on these before you read any further chapter. Every one of them shows up again, usually without a reminder of what it means.
| 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 itself | You tap “add accessory” in a phone app |
| Node | One node on the Matter network, with its own identity and its own network services | One standard bridge is a single node to the controller |
| Bridge | A Matter node that uses an aggregator to gather several bridged endpoints; 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 carry | 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 under it | The controller finds several child devices under the bridge's 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 the Matter Level Control cluster |
A bridge is an apartment building. The building has one street address — that is the node identity a controller commissions. The lobby directory that lists every unit is the aggregator. Each apartment is an endpoint, with its own number and its own function. And a fabric is the set of people who hold a key to the front door — several management companies can each hold their own key at the same time, which is exactly what letting one bridge join several controller fabrics means.
“One Home Assistant entity equals one physical device” is not a guarantee. Some sensors split temperature, humidity and battery level into several separate entities, and Stable 2.0.55 can compose them back into a single endpoint — the subject of Chapter 8. The other way round, one complex entity may need several endpoints before it can show all of its functions to a controller. So plan your scale from the endpoint count after mapping, not from the raw Home Assistant device count.
Matter Hub and the Home Assistant Matter integration point opposite ways
| 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 already 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 inside HA |
flowchart LR
subgraph MH ["Matter Hub's direction"]
A1["HA entity"] --> A2["Matter Hub"] --> A3["External controller"]
end
subgraph HM ["HA Matter integration's direction"]
B1["Matter accessory"] --> B2["HA Matter integration"] --> B3["Home Assistant"]
end
The two can coexist, but avoid exposing the same entity through both paths at once — that creates duplicate devices and command loops that are hard to trace back to their source. There is one chaining case worth naming: if a native Matter accessory is first onboarded by the Home Assistant Matter integration and then exposed by Matter Hub to a second controller, what the outside sees is an endpoint remapped by Matter Hub — not Matter Hub taking over the original accessory's fabric relationship. That kind of bridging can be useful, but its compatibility rests on three layers stacked on top of each other: the HA entity's capabilities, the Matter Hub mapping, and the target controller. “The original device supports Matter” is not, on its own, enough to conclude that every control survives the trip.
Three facts that do not guarantee each other
This guide is pinned to Stable v2.0.55, commit 6c8e8403d488fb06d2ac02d9199b92a0b8e8dccf. Keep three separate facts apart when you read anything about a feature: which release channel it ships in, how mature that feature actually is, and whether your particular controller recognizes it. None of the three tells you the other two.
| 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 remains 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 all exist in Stable, and all of them still need to be treated as experimental or verified against your own target controller |
| Controller support | Apple, Google, Alexa, Aqara and SmartThings each support different device types; unknown is not the same as unsupported, and “not listed” is not proof it will fail |
A passport, a visa and a border agent are three different facts, and mixing them up gets travelers turned around at the gate. The passport's issuing country is the release channel — it tells you which line of documents this one belongs to, nothing about where you can go. The visa is maturity — provisional paperwork attached to that passport, valid for some purposes and not others. Whether the border agent on duty actually accepts it is controller support, decided on the other side, one desk at a time. A stable-looking passport does not make every visa valid, and a valid visa does not make every border agent recognize it.
A standard bridge works reliably in Stable 2.0.55, but that does not mean every mapping inside it is presented the same way by every controller. Camera has a built-in plugin in Stable, yet its maturity is still experimental: the v2.0.55 documentation limits it to the SmartThings direction specifically, and flags the media path as something still to be verified. Server Mode is in Stable too, but a multi-device node on it is explicitly experimental — a node dedicated to a single robot vacuum is the more conservative way to use it.
Six shapes to choose from, and a decision worth drawing first
| 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; still needs a correct LAN, IPv6 and mDNS — see Chapter 2 for the pinned install details |
| Docker, host network | Readers who already manage their own containers, backups and updates | You persist /data, inject the HA URL and token correctly, and maintain host networking and IPv6 yourself |
| Global npm | Advanced readers 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; not the default recommendation for most readers |
| Several standard bridges | You want to split devices by room, by domain, or by controller-specific limits | Each bridge needs its own port; more bridges, endpoints and sync work add memory and network load |
| Multi-Fabric | You want the same bridge to join several controllers at once | Does not mean every controller supports the same device types; plan managing and removing fabrics separately |
| Server Mode | A specific device that has to appear standalone, such as a vacuum under one particular controller | Experimental limits still apply inside Stable: at most ten endpoints per node, and several entities on one node is especially experimental |
Matter itself depends on IPv6, mDNS and UDP. A page that loads in your browser only proves HTTP is reachable — it says nothing about whether a controller can discover or operate the Matter node behind it. Any of these can break commissioning, or turn into a “No Response” later: a VLAN between the host and the controller, AP or client isolation on the Wi-Fi, the wrong mDNS interface selected, a Docker-internal network interface standing in for the real one, or an IPv6 address with no return route. Before you deploy anything, sketch the actual network path between the Matter Hub host and the controller or home hub.
Scale is not a fixed number either. The endpoint count, how complex the device types are, the controller's own implementation, and the host's resources all affect stability together. The upstream project suggests considering a split once a bridge grows large; the low-resource guidance recommends planning conservatively from RAM and entity count. Treat both as operating guidance, not as a hard protocol ceiling that fails the instant you cross it.
flowchart TD A["What do you actually
want to expose?"] -->|"HA entities, out to
an external controller"| B["Good fit.
Start with one small
standard bridge"] A -->|"Matter accessories,
into Home Assistant"| C["Wrong tool.
Use the official HA
Matter integration instead"]
-
Step 1
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 into it.
-
Step 2
Mark the target controllers, and what is still unverified
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 checked. Do not fill unknown in as supported.
-
Step 3
Confirm the direction, then set one small boundary
Confirm that what you need really is exposure out of Home Assistant. Then plan one small standard bridge, with easy-to-verify, non-sensitive devices on it first — not everything you own at once.
-
Step 4
Define what “working” means before you start
Split success into four checkpoints: the dashboard shows Home Assistant connected, the bridge is running, the endpoint count looks right, and the controller can read and write one test device. A failure then points you at one layer, instead of sending you straight to a reset.
Good fit: a stable set of HA devices at home, where a handful of everyday lights, plugs, covers or sensors should appear in an external controller too; a small office that wants one bridge per area while HA stays the single center for automation and state; the same standard bridge joining several controller fabrics, accepted with the understanding that each controller will present it a little differently.
Pilot it first: anything leaning on newer Matter 1.4 types, complex audio and video, the experimental Camera or Security plugins, Server Mode with several entities on one node, or a case that needs different controllers to treat one complex endpoint identically. All of these sit inside the Stable channel, but their maturity label is separate — verify them against non-critical devices before you depend on them.
Do not put this on Matter Hub: the full duties of a general-purpose Matter controller, port forwarding across the open internet, enterprise identity governance, multi-account RBAC or SSO, or the only control path to a safety-critical device. The HTTP Basic Auth Matter Hub offers is one optional, shared set of credentials — not a complete multi-user permission system.
HTTP Basic Auth here is a doorbell code, not a keycard system. One shared code either lets a visitor in or it does not, and it has no memory of who used it or when. A keycard system is a different thing entirely: it tells you who came in, and it can be set to open some doors and not others. If your plan needs to know who did what, or to limit different people to different rooms, a shared doorbell code was never going to be the right fixture.
Before you install anything
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?
Where to go from here
You have the vocabulary and the direction. Chapter 2 gives you something running.
Three install methods exist for Stable 2.0.55 — the Home Assistant OS add-on, Docker, and a global npm package — and none of them is a “more complete” upgrade to the others. Chapter 2 walks through choosing one, the network and storage prerequisites they all share, and the backup-and-upgrade order that keeps a rollback possible.
Open the full guidePart 1 of the Home Assistant Matter Hub Complete Guide series on the Apporo blog.
Adapted from the Home Assistant Matter Hub Complete Guide, produced by WoowTech and released under CC BY 4.0. This adaptation is published by Apporo under the same licence.
Light · Air · Water · Control · apporo