Updated November 2026 for Home Assistant 2026.10. Menu names and the commissioning flow below match the current release and Companion app.
Matter is a shared language for smart home devices. It runs over your normal Wi-Fi or over Thread, a low power mesh network, and it is local by design: once a device is in Home Assistant, it does not need the manufacturer’s cloud. The other big feature is multi-admin, which means the same plug or light can be controlled by Home Assistant and Apple Home or Google Home at the same time, without one going through the other.
What you need
- Home Assistant OS on any hardware, or Home Assistant Container with a separately run Matter server.
- The Home Assistant Companion app on an Android phone or iPhone, with Bluetooth on. Commissioning (Matter’s word for adding a device) goes through the phone.
- IPv6 enabled on your network and on the Home Assistant host. IPv6 is the newer type of network address. Matter uses it inside your home even if your internet connection does not. Most routers have it on by default.
- For Thread devices: a Thread border router, which is a device that connects the Thread network to your normal home network. If you do not have an Apple TV, HomePod mini, Nest Hub or similar, a USB radio like the Home Assistant Connect ZBT turns Home Assistant itself into one.
- A Matter device. A Matter smart plug is a cheap and easy first test.
Home Assistant GreenPlug-and-play Home Assistant box. The easiest way to start, no SD card.Check price on AliExpress
SONOFF ZBDongle-E (Zigbee 3.0 USB)Cheap, well supported Zigbee coordinator for ZHA or Zigbee2MQTT.Check price on AliExpressWi-Fi or Thread: what is the difference
A Matter device talks over one of two networks. Matter over Wi-Fi devices (most plugs, many bulbs) join your Wi-Fi and are reachable right away. Matter over Thread devices (most battery sensors, locks, buttons) form their own mesh and reach your home network through a border router. The box usually says which one it is. If you want the deeper background on mesh health, see Zigbee and Thread mesh optimization.
Step 1: Add the Matter integration
- Go to Settings > Devices & services > Add integration and search for Matter.
- On Home Assistant OS, leave the option to use the official Matter Server app selected and submit. Home Assistant installs and starts it.
- On Container, run the Matter server container yourself (it needs host networking for IPv6) and enter its WebSocket address, usually
ws://localhost:5580/ws.
That is all for Wi-Fi devices. For Thread, do Step 2 first.
Step 2: Set up Thread (only for Thread devices)
You have two options, and you can mix them:
- Use an existing border router. An Apple TV 4K, HomePod mini, recent Google Nest hub or Amazon Echo with Thread already runs one. Home Assistant needs that network’s credentials to add devices to it. On Android, open the Companion app, go to Settings > Companion app > Troubleshooting and use Sync Thread credentials. On iPhone, the app can import the credentials from Apple Home during commissioning.
- Run your own. Plug in a Thread capable radio, install the OpenThread Border Router app, and Home Assistant creates its own Thread network. This keeps everything inside Home Assistant.
Then open Settings > Devices & services > Thread > Configure. You want one preferred network, with your border routers listed under it. Two separate Thread networks in one house is a common cause of devices that will not join or that drop off. If you have several, move your devices onto one preferred network.
Step 3: Commission a new Matter device
- Power the device and put it in pairing mode if it is not in it already.
- In the Companion app, go to Settings > Devices & services > Devices, tap Add device and choose Matter device. The flow only starts from the phone app, not a desktop browser.
- Scan the Matter QR code on the device or its box. If the code is hard to scan, type the 11 digit numeric code instead.
- Wait while the phone hands over the network details. Thread devices can take a minute.
- Pick an area and a name. The device shows up as normal entities: a plug becomes a switch, a bulb a light, a sensor a sensor or binary sensor.
Photograph the QR code before you mount the device. If you ever need to re-pair it, the sticker will be on the back of something screwed to a wall.
Step 4: Share a device from Apple Home or Google Home
A device that is already set up in another ecosystem does not need a factory reset. Ask that app for a pairing code and add the device to Home Assistant with it:
- Apple Home: open the device, go to its settings and choose Turn On Pairing Mode. Copy the setup code.
- Google Home: open the device settings, then Linked Matter apps & services and Link apps & services to get a code.
- Amazon Alexa: in the device settings, look for Other assistants and apps and add another.
Then start Add device > Matter device in the Home Assistant app and choose the option to use a setup code instead of a QR code. The code is only valid for a few minutes, so do this right away.
It also works the other way: on a Matter device’s page in Home Assistant, the three-dot menu has Share device, which creates a code for Apple Home, Google Home or Alexa. That only works for devices that are themselves Matter devices. To expose your Zigbee or Wi-Fi devices to those apps, see exposing Home Assistant devices to Apple, Google and Alexa.
Using Matter devices in automations
Once commissioned, Matter entities behave like any other entity. A Zigbee motion sensor can turn on a Matter light like this:
alias: Hallway light on motion
triggers:
- trigger: state
entity_id: binary_sensor.hallway_motion
to: "on"
actions:
- action: light.turn_on
target:
entity_id: light.hallway_ceiling
data:
brightness_pct: 80Because the command never leaves your network, it reacts fast and still works when the internet is down. When a manufacturer releases a Matter firmware update, it can show up on Home Assistant’s Updates page like any other update.
Troubleshooting
- Commissioning fails at “checking network connectivity”. Almost always IPv6 or multicast. Make sure IPv6 is enabled on the Home Assistant host (Settings > System > Network), that your phone, Home Assistant and the border router are on the same network and VLAN (a separate network segment some routers create, such as a guest or IoT network), and that the router does not filter multicast, the type of traffic devices use to find each other.
- Thread device will not join. Check that Home Assistant knows your Thread credentials (Step 2) and that only one preferred network exists.
- “Device already commissioned”. It is paired elsewhere. Use the sharing flow from Step 4, or factory reset it.
- Device goes unavailable after a while. For Thread, add more mains powered Thread devices (plugs, bulbs) to strengthen the mesh. For Wi-Fi, check signal strength and give it a DHCP reservation.
- Logs. The Matter Server app log shows commissioning errors in detail. Open it under Settings > Apps > Matter Server > Log.
Frequently Asked Questions
Do I need a Thread border router for Matter in Home Assistant?
Only for Matter over Thread devices. Matter over Wi-Fi devices join your Wi-Fi directly. For Thread, an Apple TV, HomePod mini, Nest hub or a USB radio with the OpenThread Border Router app all work.
Can I add Matter devices to Home Assistant from a computer?
No. Commissioning uses Bluetooth and the phone’s Matter support, so it has to start in the Home Assistant Companion app on Android or iOS.
Can a Matter device be in Apple Home and Home Assistant at the same time?
Yes, that is Matter multi-admin. Turn on pairing mode for the device in Apple Home, then add it in Home Assistant with the setup code. Both control it locally.
Why does Matter commissioning fail in Home Assistant?
The usual causes are IPv6 disabled on the host, the phone and Home Assistant being on different networks or VLANs, multicast filtering on the router, or missing Thread credentials for Thread devices.
Is Matter better than Zigbee for Home Assistant?
Not automatically. Zigbee is mature, cheap and fully local too. Matter is great for devices you want in several ecosystems at once. Many homes run both, and a single radio can cover Zigbee and Thread.
