Home Assistant Matter Setup Guide (2026)

Disclosure: Some links in this article are affiliate links. We may earn a commission on qualifying purchases at no extra cost to you.

Matter was supposed to be the protocol that ended smart home fragmentation, and on paper it does exactly that: one certification logo, one commissioning flow, devices that talk to Home Assistant, Apple Home, Google Home and Alexa at the same time. In practice, the experience splits cleanly into two halves. Getting a Wi-Fi Matter device onto Home Assistant takes under five minutes and rarely goes wrong. Getting a Thread Matter device onto the same instance is where most setups stall — vague error codes, a missing border router, or a commissioning button that simply isn't where the last tutorial said it would be.

This guide is built around that split. It walks through installing the Matter Server correctly for your specific Home Assistant install type, verifying the network requirements that quietly block commissioning, and choosing hardware for the Thread half of the equation — because as of mid-2026, Matter now runs in 38% of Home Assistant instances, ranking as the 12th most-used integration on the platform. This isn't a niche feature anymore; it's infrastructure most Home Assistant users will touch sooner or later.

What follows assumes no prior Matter experience, but does assume a working Home Assistant instance. If you haven't set one up yet, that's a separate project — this one starts the moment you're ready to add your first Matter device.

What You'll Need

A running Home Assistant instance (HAOS strongly recommended — see below)
A phone with the Home Assistant Companion app installed (iOS 16+ or Android 8.1+, Android 12+ recommended)
A Matter-certified device to commission (look for the Matter logo specifically, not just "Thread" or "Zigbee")
For Thread devices only: a Thread Border Router (hardware options covered in Step 5)
A router/network that supports IPv6 multicast

Before You Start — Confirm Your Installation Type Supports Matter

Home Assistant's Matter Server isn't equally available across every installation method, and this is the single most common reason a setup stalls before it even starts.

Installation type	Matter Server support
Home Assistant OS (HAOS)	Fully supported — one-click install via the UI
Container (Docker)	Supported, but manual — you run the `python-matter-server` image yourself and expose it on port 5580
Supervised	Supported via the add-on, same path as HAOS
Core	Not supported

If you're on HAOS, the rest of this guide is close to plug-and-play. If you're on Container, budget extra time for the networking step — that's where nearly all Container-specific friction shows up. If you're on Core, you'll need to migrate to a supported install type before Matter is an option at all.

One more prerequisite that's easy to miss: Thread-based Matter (as opposed to Wi-Fi Matter) requires Home Assistant OS version 10 or later. Wi-Fi-only Matter devices don't have this requirement.

Step 1 — Install the Matter Server

On HAOS or Supervised installs, this is genuinely a one-click operation:

Go to Settings > Devices & Services
Click Add Integration
Search for Matter
Click Submit

Home Assistant installs and starts the Matter Server for you, and it registers as a controller certified by the Connectivity Standards Alliance — both Home Assistant and the Open Home Foundation's Matter Server received official CSA certification in 2025, which matters less for day-to-day use and more as a sign the implementation is taken seriously at the standards level.

On Container installs, you're running the python-matter-server image directly and connecting Home Assistant Core to it over WebSocket. The default port needs to be exposed as 5580 (toggle "Show disabled ports" if you don't see it), and the connection URL in Home Assistant needs to point at the actual host IP — not localhost. This is the single most common Container-specific failure: pointing the integration at ws://localhost:5580/ws when it needs the machine's real address on the network.

A quick note on versioning: the Matter Server underwent a significant rebuild in mid-2026. The older python-matter-server implementation has been replaced by a new engine built on matter.js, shipped as version 9.0, supporting the Matter 1.5.1 specification (with 1.6 already in development). If you're following an older tutorial that references an "add-on" running Matter 1.4.x, the screens and terminology have moved on slightly — the concepts below still apply.

Step 2 — Get Your Network Ready

This is the step tutorials skip, and it's responsible for a disproportionate share of "device not found" and generic error-code failures.

IPv6 multicast must be enabled and set to "Automatic" in your network settings. Matter's device discovery relies on it. If your router or VLAN configuration blocks IPv6 or doesn't reflect mDNS traffic, commissioning will fail with unhelpful, generic messages — "Error code 1" is a common one, and it almost always traces back to this.

If you're running Home Assistant behind VLANs or a segmented network (common in more advanced setups), confirm mDNS is being reflected across segments. This is a self-inflicted failure mode for anyone who's already invested in network segmentation for security reasons — Matter's discovery layer doesn't route across VLAN boundaries without help.

Step 3 — Commission Your First Matter-over-Wi-Fi Device

If your first device is Matter-over-Wi-Fi, no additional hardware is required — this is the "happy path" and it's genuinely fast:

In Home Assistant, go to Settings > Devices & Services, click Add Device under the Matter integration
Open the Home Assistant Companion app on your phone — this step only works from the mobile app, the "Commission using Companion app" option does not exist in the browser dashboard
Scan the device's QR code or enter its setup code manually
Grant Bluetooth permission when prompted — the phone's Bluetooth is the commissioning transport, not the server's

On Android specifically, location permission needs to be set to "Allow all the time," not just "while using the app," or commissioning can silently fail in the background. Some users also report needing the Google Home app installed alongside the Companion app for Thread-adjacent pairing to behave correctly, even when Google Home itself isn't the target platform.

Most Wi-Fi Matter commissioning completes in under five minutes. If it doesn't, revisit Step 2 before troubleshooting further — IPv6 is the most common root cause even for Wi-Fi devices.

Step 4 — Understand What You're Trading With Matter

Before adding Thread devices, it's worth setting expectations, because Matter is not a strict upgrade over a device's native integration.

Bringing a device in through Matter often means losing functionality that the native integration exposed. Philips Hue bulbs added via Matter get basic on/off and brightness control, but lose dynamic scenes and entertainment sync. TP-Link Kasa devices added via Matter lose energy monitoring and scheduling, leaving on/off only. If a device already has a solid native Home Assistant integration and you're not specifically trying to share it across ecosystems (Apple Home, Google Home, Alexa, Home Assistant simultaneously), keeping the native integration is usually the better call. Matter's real value shows up when multi-platform access matters more than feature depth.

Step 5 — Add a Thread Border Router

Thread devices need one thing that Wi-Fi devices don't: a Thread Border Router (TBR) — a piece of hardware that bridges the low-power Thread mesh to your regular IP network. Without one, Home Assistant will tell you the device "requires a Thread border router," even if you're sure your setup already has one.

If you're building a Home Assistant-first setup and don't already have Thread coverage from another ecosystem, these are the options worth considering:

Home Assistant Connect ZBT-2 — the current recommendation for a Home Assistant-native Thread Border Router. Built around a Silicon Labs MG24 chip, it quadruples the internal communication speed compared to its predecessor and runs as either a Zigbee coordinator or a Thread radio (not both at once — pick one function per dongle). It becomes a Thread Border Router through the OpenThread Border Router add-on.
Pros: officially maintained by the Home Assistant team, straightforward setup path, current hardware.
Cons: USB-only — needs a host machine with a spare port, and you'll want a second dongle if you also need Zigbee.
Perfect for: anyone building a dedicated, local Thread network for Home Assistant without leaning on Apple or Google hardware.
Check Price on Amazon

Home Assistant Connect ZBT-1 — the previous generation, now discontinued but still fully supported in software, including as a Thread Border Router via the same OTBR add-on. A reasonable pickup if found cheap, though new buyers should default to the ZBT-2.
Pros: proven, still works.
Cons: discontinued, slower internal communication than the ZBT-2, market listings are thinner.
Perfect for: filling a second radio slot (e.g., dedicated Thread while a ZBT-2 handles Zigbee) rather than a primary purchase.
Check Price on Amazon

Apple TV 4K (3rd gen), Wi-Fi + Ethernet, 128GB — doubles as a Thread Border Router, but only in this exact configuration. The 64GB Wi-Fi-only model supports Matter but not Thread. If you already own an Apple TV and are checking whether it qualifies, confirm the model and storage tier before assuming it will work.
Important limitation: OTA firmware updates for Thread devices don't work through an Apple TV border router — it doesn't relay the mDNS traffic those updates rely on. If you need Thread devices to receive updates reliably, pair this with a Home Assistant-native TBR rather than relying on Apple TV alone.
Perfect for: households already invested in Apple Home who want Thread coverage without buying dedicated hardware.
Check Price on Amazon

Google Nest Hub (2nd Gen) — functions as a Thread Border Router and Matter controller through Google Home, and is explicitly listed by Home Assistant's own documentation as a compatible option, particularly for Android users.
Caveat: its Thread network is opaque — there's no dataset export — so sharing credentials into Home Assistant relies on the Google Home / Home Assistant integration path rather than a portable Thread dataset.
Perfect for: Google Home households that want a display alongside their Thread coverage.
Check Price on Amazon

Aqara Hub M3 — a genuine three-in-one: Matter controller, Thread Border Router, and Zigbee 3.0 hub, with capacity for 64 devices connected directly and up to 127 when bridging through routers or mesh extenders.
Caveat: some Aqara Zigbee devices can't be exposed through Matter due to spec gaps between the ecosystems — don't assume every Aqara sensor will show up on the Matter side.
Perfect for: buyers standardizing on Aqara hardware who want Zigbee and Thread handled by one box.
Check Price on Amazon

Aqara Hub M200 — Aqara's newer, more focused release: Matter controller, Thread Border Router, and Matter Bridge, supporting up to 40 Aqara Zigbee devices and 40 Thread devices, with the ability to join an existing Thread network rather than only running its own.
Perfect for: extending Thread mesh coverage into a new area of the house without duplicating an existing Thread network.
Check Price on Amazon

One hub deliberately isn't on this list for Thread purposes: the Aqara Hub M2. It's a capable Zigbee 3.0 hub with IR blaster and siren functionality, and it can now expose some Aqara features as virtual Matter devices through Advanced Matter Bridging — but it is neither a Matter controller nor a Thread Border Router. That functionality only arrived with the M3 and M200. If you already own an M2 and are wondering why Thread commissioning isn't working through it, that's why.

Step 6 — Commission a Matter-over-Thread Device

With a Thread Border Router running, the commissioning flow for a Thread device looks almost identical to the Wi-Fi flow in Step 3 — Companion app, QR/setup code scan, Bluetooth permission — with one difference: Home Assistant needs a Thread dataset shared with (or set as the preferred network on) whichever border router is handling the device.

If you get the "this device requires a Thread border router" error while a border router is clearly running, the dataset is almost always the culprit — either it hasn't been shared with Home Assistant's OpenThread Border Router instance, or the preferred network setting doesn't match what the device expects. Checking the OTBR REST API status page (http://[HA-IP]:8081) is a faster diagnostic than restarting the commissioning flow repeatedly.

Step 7 — Handle Multiple Border Routers Without Duplicating Networks

It's common to end up with more than one Thread Border Router on a network — an Apple TV, a Google Nest Hub, and a Home Assistant ZBT-2 can all technically run one. Matter devices support at least five simultaneous "fabrics" (this is the multi-admin capability that lets one device answer to Home Assistant, Apple Home, and Google Home at once), so overlap isn't fatal.

What it does create is duplicated or fragmented Thread networks if credentials aren't shared deliberately between border routers. Thread 1.4 improved credential sharing between ecosystems, but it's still not seamless — treat "one Thread network, multiple border routers sharing its dataset" as the goal, rather than letting each ecosystem spin up its own isolated mesh.

Common Mistakes to Avoid

Assuming a Thread logo means Matter support. They're separate certifications. A Thread radio doesn't guarantee Matter compatibility — check for the Matter logo specifically.
Treating the Aqara Hub M2 as a Thread Border Router. It isn't. Only the M3 and M200 (and newer) carry that capability.
Running Container on localhost instead of the host IP. The WebSocket connection needs the machine's actual network address.
Ignoring IPv6. Most "device not found" and generic error-code failures trace back to IPv6 multicast being disabled, not a device fault.
Expecting the commissioning button in the browser. "Commission using Companion app" only exists in the mobile app — there is no browser equivalent.
Assuming Apple TV Thread coverage handles firmware updates. It doesn't relay the mDNS traffic Thread OTA updates need — pair it with a native Thread Border Router if update reliability matters.
Expecting feature parity after switching to Matter. Hue loses scenes and entertainment sync; Kasa loses energy monitoring and scheduling. Matter buys you cross-platform access, not extra features.

Frequently Asked Questions

Q: Do I need a Thread Border Router if all my Matter devices are Wi-Fi based?

No. Matter-over-Wi-Fi devices commission directly without any additional hardware. A Thread Border Router is only required for Matter-over-Thread devices — check your device's documentation to see which transport it uses.

Q: Home Assistant says my device requires a Thread border router, but I already have one running. Why?

This almost always means the Thread dataset hasn't been shared with, or set as preferred on, the border router Home Assistant is using. Check the OpenThread Border Router status directly rather than repeating the commissioning flow.

Q: Can I use my Apple TV as a Thread Border Router for Home Assistant?

Only the Apple TV 4K 3rd generation, Wi-Fi + Ethernet, 128GB model supports Thread. The 64GB Wi-Fi-only model supports Matter but not Thread. Even with the right model, firmware OTA updates for Thread devices won't work through it, since it doesn't relay the required mDNS traffic.

Q: Is the Aqara Hub M2 a Thread Border Router?

No. The M2 is a Zigbee 3.0 hub with some retrofitted Matter bridging for its own devices, but it is not a Matter controller or Thread Border Router. That functionality starts with the Aqara Hub M3.

Q: Will I lose functionality by adding a device through Matter instead of its native integration?

Often, yes. Philips Hue bulbs lose dynamic scenes and entertainment sync through Matter; TP-Link Kasa devices lose energy monitoring and scheduling. If a strong native integration already exists and cross-platform access isn't a priority, keep the native integration.

Q: Can I run multiple Thread Border Routers on the same network?

Yes — Matter devices support at least five simultaneous fabrics, so multiple border routers and controllers can coexist. The practical challenge is making sure they share the same Thread dataset rather than each spinning up an isolated network, since credential sharing between ecosystems still isn't fully seamless even with Thread 1.4 improvements.

Conclusion

The gap between "Matter setup" and "Thread setup" is the whole story here. Wi-Fi Matter devices commission almost as fast as you can scan a QR code, and Home Assistant's one-click Matter Server install on HAOS makes that half of the equation close to friction-free. Thread is where a real decision has to be made — about hardware, about which ecosystem's border router you're trusting, and about whether the cross-platform convenience of Matter is worth losing some native features along the way.

For a Home Assistant-first household without existing Apple or Google Thread coverage, the ZBT-2 remains the straightforward pick, with the Aqara M3 or M200 as reasonable alternatives if Zigbee consolidation matters too. For a household already running Apple TV or Google Nest hardware, checking model compatibility before buying anything new is worth the five minutes it takes — getting caught by the Apple TV storage-tier trap, or mistaking an Aqara M2 for a Thread-capable hub, are still the two most common ways this setup goes sideways.

Home Assistant Matter Integration: Setup Guide (2026)