To add a Matter device to Home Assistant, set up the Matter integration, which installs the Matter Server app on Home Assistant OS. Then, in the companion app, open Settings > Connectivity > Matter > Add device and scan the device’s QR code. Home Assistant becomes the device’s Matter controller; Thread devices also need a border router.
Most failures happen before that scan, in IPv6, Bluetooth or Thread credentials. And if you searched for “Home Assistant Matter Hub”, that is a separate community app working in the opposite direction: it publishes Home Assistant entities to Apple Home, Google Home or Alexa. It has its own section further down.
How Matter works in Home Assistant
Home Assistant is a Matter controller, not a Matter bridge. The Matter integration, introduced in release 2022.12, controls Matter devices on your local Wi-Fi or Thread network with local push updates, and the documentation says it “only supports control of Matter devices”. The same page listed it as in use on 40.8% of active installations when checked in October 2026.
The work is split across a few pieces, and knowing which is which saves time when something breaks:
| Piece | Job | Where it lives |
|---|---|---|
| Matter integration | Creates devices and entities; talks to the server over a WebSocket | Settings > Devices & services |
| Matter Server app | Runs Home Assistant’s own Matter controller | Settings > Apps (Add-ons before 2026.2) |
| Companion app | Commissions new devices using the phone’s Bluetooth | iPhone or Android phone |
| Thread integration plus a border router | Routes Thread devices onto your IP network and stores Thread credentials | Settings > Devices & services, plus a HomePod, Nest hub or the OTBR app |
The server changed engines at version 9.0.0. The Matter Server app documentation says it now “runs the matter.js Matter Server exclusively”; the Python Matter Server was removed and existing data migrates with no user action. The app changelog warns the new server “needs roughly twice the RAM of the old one”, so check free memory on a small host before updating; Home Assistant hardware requirements by workload covers headroom. App 9.2.0, which bundles matter.js server 1.4.0, is the minimum for the integration’s interactive network map. Home Assistant 2026.2 renamed add-ons to apps, so older guides that say “Matter Server add-on” mean the same thing.
Who this is for, and who should stop here
You need Home Assistant OS. The Matter integration docs say running the Matter Server app on Home Assistant OS “is currently the only supported option”, and it is not supported on 32-bit platforms. Container installs can run the server image by hand, unsupported. Still choosing an install type? The HAOS versus Container comparison makes the case for HAOS, and Matter is one of the strongest reasons.
You also need a phone. Commissioning uses the companion app’s Bluetooth, and even if the host has an adapter, “Home Assistant does not use that adapter.”
The checklist before you scan anything
- IPv6 on the host. Settings > System > Network, set IPv6 to Automatic or static. The docs ask you to make sure “IPv6 (multicast) traffic travels freely from your network to the Home Assistant host.”
- The phone. Android 8.1 minimum, 12 or newer recommended, the full Play Store build, and Location set to “Allow all the time” so the app can read the Wi-Fi SSID. iPhone needs iOS 16 or newer; the docs’ troubleshooting section names iOS or iPadOS 16.4 as the minimum, so update past that.
- The right Wi-Fi. For a Wi-Fi device, the phone must be on the same 2.4 GHz network the device will join.
- The logos. The box needs the Matter logo plus a Wi-Fi or Thread logo. The docs put it bluntly: “Thread devices don’t necessarily support Matter.”
- Photograph the QR code. After a factory reset “you’ll need the QR code or numeric setup code to commission that device again.”
Setting up the Matter integration
- Go to Settings > Devices & services, add an integration and pick Matter.
- On Home Assistant OS, leave the official server option selected and select Submit. Home Assistant installs and starts the Matter Server app.
- Already running a Matter server elsewhere, such as the standalone Docker image? Deselect the checkbox and give the integration that server’s URL. The app docs use port 5580 for the server’s WebSocket, which by default is “only exposed internally”.
- Once the integration shows as set up, every new device goes through the phone, as below.
Adding a new Wi-Fi Matter device
On iPhone: Settings > Connectivity > Matter, Add device, “No, it’s new”, scan the QR code (or “More options” to type the 11-digit code), then Add to Home Assistant. An “uncertified accessory” prompt on a new product is fine to “Add Anyway”.
On Android: power the device up so it enters pairing mode. Android may offer a scan prompt on its own; pick Home Assistant. Otherwise go to Settings > Connectivity > Matter, Add device, Add Matter device, “No, it’s new”, then scan or choose “Setup without QR-code”. Either platform ends by asking for a name and an area.
Adding a Thread Matter device
A Thread device cannot reach your IP network on its own. It needs a border router, and your phone needs that border router’s Thread credentials before commissioning starts. Examples listed in the Matter documentation include HomePod mini or HomePod (2nd gen); Nest Hub (2nd gen) or Nest Wi-Fi Pro; or Home Assistant’s own OpenThread Border Router add-on on a Connect ZBT-1, ZBT-2, SkyConnect or Yellow. Thread needs HAOS version 10 or later. Still deciding whether a Thread mesh is worth building at all? Zigbee vs Z-Wave vs Thread weighs it against the alternatives.
The Thread integration appears automatically once a border router is detected and stores the credentials “similar to a Wi-Fi password”. On Android, open Settings > Companion app > Troubleshooting > Sync Thread credentials. On iPhone, open Settings > Connectivity > Thread, then select Send credentials to phone at the bottom of the preferred network box. Import credentials from an existing Apple or Google Thread network before choosing it as preferred; the Thread documentation gives the steps for each ecosystem.
One honest warning: the OTBR add-on docs say the radio must be on “a reliable link such as UART or SPI”; a network-attached radio will “leave stale routes in your network” when it drops, stranding every Thread device. The Thread border router guide covers placement. With credentials on the phone, the steps are identical to Wi-Fi.
Adding a device that already lives in Apple Home or Google Home
No factory reset needed. Multi-admin lets one device hold several fabrics, so Home Assistant can control a bulb Apple Home still owns. In the app, Add device, then “Yes, it’s already in use”, pick the controller it belongs to and follow the prompts.
The other side has to hand over a code. In Google Home, per Google’s Matter help page, open the device, go to Settings > Linked Matter apps & services > Link apps & services, or tap “Use pairing code” or “Share with QR code” for a temporary code. Apple Home does the same from the accessory’s settings.
It works in reverse. Settings > Connectivity > Matter > Devices, pick the device, Share device, and Home Assistant produces a code for another platform without touching the hardware. The same page’s Manage fabrics menu is how you evict a controller later; the controller explainer covers what a fabric is.
Home Assistant Matter Hub: sharing entities the other way
Home Assistant Matter Hub is a community app, not part of Home Assistant, that “simulates bridges to publish your entities from Home Assistant to any Matter-compatible controller”, per its GitHub repository. It fills a gap the official integration leaves on purpose: the Matter docs say Home Assistant “is not a bridge itself and it cannot turn existing devices within Home Assistant into Matter compatible devices.” Share device only works for real Matter hardware. A bulb paired through Zigbee2MQTT or an ESPHome sensor reaches Apple Home, Google Home or Alexa only through a bridge like this.
Pick the right repository. The original t0bst4r/home-assistant-matter-hub ended maintenance in January 2026 and was archived on March 11, 2026; its owner points users to the RiDDiX fork, which describes itself as the “actively maintained fork and successor”. Tutorials that link the t0bst4r repository install code that gets no more fixes. When checked in October 2026, the fork’s stable channel was v2.0.58, shipped as the hamh app alongside hamh-alpha and hamh-testing.
| Matter integration | Home Assistant Matter Hub | |
|---|---|---|
| Direction | Matter devices into Home Assistant | Home Assistant entities out to other platforms |
| Matter role | Controller | One or more bridges |
| Maintained by | Home Assistant project | Community (RiDDiX fork) |
| Installed from | Built-in integration plus official Matter Server app | Third-party app repository or Docker image |
| Ports | Server WebSocket 5580, internal by default | Web UI 8482; bridges from 5540 |
To install it on Home Assistant OS:
- In Settings, open Apps, then the app store, the three-dot menu and Repositories. Add
https://github.com/riddix/home-assistant-addons. The project’s installation guide still uses the pre-2026.2 Add-ons labels and notes this route “can only be used with Home Assistant OS”. - Install Home-Assistant-Matter-Hub (
hamh), start it and select Open Web UI. - On the Bridges page, open the Wizard, name the bridge and set entity filters by area, label, domain or pattern. The bridge configuration guide says ports are assigned from 5540 upward.
- Commission the bridge from the other platform’s app the way you would any Matter accessory.
Container users run ghcr.io/riddix/home-assistant-matter-hub:latest with --network host, a volume on /data, and HAMH_HOME_ASSISTANT_URL plus HAMH_HOME_ASSISTANT_ACCESS_TOKEN (a long-lived access token) set.
Each platform adds its own limits. The project documentation says Alexa pairs only on port 5540, needs at least one Amazon device that supports Matter, and “seems to have a limit of about 80-100 devices” per bridge; Google Home needs a Google hub. The controller compatibility matrix shows Apple Home without pressure sensors, speakers or water valves, and Google Home without water leak detectors. Keep IPv6 on: the README is blunt that “Matter requires IPv6, do not disable it.”
Doing it without a phone
The Matter Server add-on docs list a ble_proxy option that will “expose the BLE proxy endpoint so the Home Assistant Matter integration can drive BLE commissioning through Home Assistant’s bluetooth stack”, replacing the older bluetooth_adapter_id setting. That covers the host’s own adapter or an ESPHome Bluetooth proxy. The integration page still documents the companion app as the supported route, so treat it as opt-in.
When it fails, it is usually the network
“Matter is unavailable” on Android means Google Play Services is still pulling the Matter modules, which can take up to 24 hours. For “Checking network connectivity”, check the documented Android prerequisites and updated Google Play Services; for Thread, bring the phone close to both the device and border router. “Device requires a border router” means a Thread device with no reachable border router or credentials that never synced. Random failures point at blocked IPv6 or mDNS.
Matter needs local IPv6 and mDNS traffic to reach the host. The integration docs also say Matter “is designed for regular residential network setups” and may struggle across VLANs or with multicast filtering or IGMP snooping turned on. Check network filtering against Matter Homelab’s IPv6 requirements for Matter and Thread; use its pairing failures guide to identify the commissioning stage. Download diagnostics from Settings > Devices & services > Matter when collecting information for a support request.
When Matter is the wrong door
Philips Hue over Matter gives basic controls only; the native Hue integration keeps dynamic scenes and entertainment mode, both local. And Matter OTA updates “currently do not work for Thread devices on a Thread network with (any) Apple border routers”, so a HomePod-only mesh means firmware updates happen in the vendor app or not at all. Where Matter OTA does work, the integration’s update entity checks the CSA’s Distributed Compliance Ledger every 12 hours; the docs name Eve and Nanoleaf as vendors currently publishing updates that way.
Add the device, name it, then leave the network alone. Most of the pain here is clever networking, not Matter.
Related on this site
- Home Assistant hardware: what to run it on
- Home Assistant OS vs Container vs Core
- Write Home Assistant automations in YAML
Related across the network
- Thread border router guide — matterhomelab.com
- Matter multi-admin sharing explained — matterhomelab.com
FAQ
does home assistant support matter
Yes. Home Assistant has supported Matter natively since release 2022.12 through the built-in Matter integration, which acts as a Matter controller for Wi-Fi and Thread devices. On Home Assistant OS it installs the official Matter Server app when you add the integration; Container and Core installs can point it at a separately run server, but that is unsupported.
is home assistant a matter controller or a matter bridge
A controller. The official integration commissions and controls Matter devices, and the documentation says Home Assistant “is not a bridge itself”, so it cannot present its own Zigbee, Z-Wave or ESPHome entities to other platforms. For that, install the community Home Assistant Matter Hub app, which runs one or more virtual Matter bridges.
is home-assistant-matter-hub still maintained
The original is not: t0bst4r ended maintenance in January 2026 and archived the repository on March 11, 2026. Development continues in the RiDDiX fork, which its maintainer describes as the actively maintained successor. Its stable channel stood at v2.0.58 when checked in October 2026, installed from the riddix/home-assistant-addons repository.
do i need a thread border router for matter in home assistant
Only for Thread devices. Wi-Fi Matter devices join your 2.4 GHz network directly and need nothing extra. Thread devices need a border router such as a HomePod mini, a Nest Hub (2nd gen) or the OpenThread Border Router app on a Home Assistant Connect ZBT-1 or ZBT-2, plus Home Assistant OS 10 or later.
how many controllers can a matter device be paired with
The Matter standard says each device should support at least 5 fabrics at once, so a single plug can typically be controlled by Home Assistant, Apple Home, Google Home and Alexa simultaneously. Each extra controller takes a fabric slot; remove stale ones from the device’s Manage fabrics menu in Home Assistant.
