Matter over Thread in Home Assistant, end to end
Matter is the smart home's peace treaty — one standard that Apple, Google, Amazon and Samsung all speak — and Thread is its low-power mesh radio. Together they promise devices that pair once and work everywhere, locally. In Home Assistant the setup has three moving parts and one famous gotcha. Here is the whole path, from border router to first device, including the Docker way to run the Matter Server.
Published Nov 17, 2026
The three pieces, in plain language
- Thread border router — the translator between your Wi-Fi/LAN and the Thread mesh. You may already own one: recent Apple TVs and HomePods, many eero routers, and some smart-home hubs are border routers. One is enough; several cooperate.
- Matter Server — the controller software Home Assistant talks to. If you run Home Assistant OS it is a one-click add-on; in a Docker install it is one more container (below).
- Your phone — new devices are commissioned (paired) through the Home Assistant app, which uses Bluetooth for the first handshake, then hands the device its Thread credentials.
The gotcha, up front: IPv6. Matter over Thread rides on IPv6. If your router has IPv6 disabled, or your Docker network hides it, devices will fail to pair with unhelpful errors. Before troubleshooting anything else, confirm IPv6 is on in your router and that the Matter Server container uses host networking.
Step 1 — run the Matter Server (Docker installs)
services:
matter-server:
image: ghcr.io/home-assistant-libs/python-matter-server:stable
container_name: matter-server
restart: unless-stopped
network_mode: host # required: Matter needs LAN + IPv6 visibility
security_opt:
- apparmor=unconfined # needed on some NAS/container hosts
volumes:
- ./matter-server/data:/data
command: --storage-path /data --paa-root-cert-dir /data/credentials
Then in Home Assistant: Settings → Devices & Services → Add Integration → Matter, and point it at ws://YOUR-NAS-IP:5580/ws. (Home Assistant OS and Supervised users skip all of this — the add-on wires itself.) The integration connecting is the milestone; device pairing comes next and is deliberately boring.
Step 2 — commission your first device
- Put the device in pairing mode (usually: power it on fresh, or hold its button per the manual) and find its Matter QR code or 11-digit setup code — it is on the device and in its box, and worth photographing into your password manager.
- In the Home Assistant phone app: Settings → Devices & Services → Add Device → Add Matter device. Scan the code. The phone talks Bluetooth to the device, hands it your Thread network's credentials, and the Matter Server adopts it.
- Name it, place it in a room, and test from Home Assistant — not the vendor app. From here the device is a local citizen: automations run it without any cloud account.
Already paired a device to Apple Home or Google Home first? You do not start over: open the device in that app and generate a new pairing/share code, then add it in Home Assistant with that code. Matter devices can belong to several controllers at once — that multi-admin trick is the standard's best feature, and it is also how you keep a voice assistant's app working alongside Home Assistant during a migration.
What Thread does behind the scenes
Thread is a mesh like Zigbee's — mains-powered devices route for sleepy ones — with two differences that matter. It speaks IP natively (every device has an IPv6 address), which is why border routers are simple translators rather than protocol converters; and your phone already knows how to hand out its credentials, because Apple and Google bake Thread into their home platforms. Practically: keep at least one border router reasonably central, add mains-powered Thread devices (plugs and bulbs are the mesh's backbone) before relying on far-flung battery sensors, and expect the mesh to self-heal routes over the first day. If you know Zigbee, the mental model transfers — including the part where placement beats protocol arguments, which our radios chapter covers.
Troubleshooting
- Pairing fails at 'connecting to device': Bluetooth range or the phone's own Thread credentials are stale — stand next to the device, and on iPhone check that the app could sync credentials (the app walks you through it).
- 'Device is not on the same network': the IPv6 gotcha — router IPv6 off, or the Matter Server not on host networking, or the border router on a different VLAN than the server.
- Device pairs to Apple/Google but not HA: you need a fresh share code from the first controller, not the code printed on the device — printed codes work exactly once.
- Devices go unavailable overnight: usually a border router that sleeps or a mesh with no mains-powered routers near the device. Add a smart plug as a repeater before blaming Matter.
Matter over Wi-Fi, and Thread vs Wi-Fi devices
Not every Matter device uses Thread. Matter is the language; Thread and Wi-Fi are two transports it rides. Matter over Wi-Fi devices (many plugs, bulbs and appliances) join your normal wireless network — easy, but each one is another always-on Wi-Fi client, and cheap ones are not kind to crowded routers. Matter over Thread devices sip power on the mesh and keep Wi-Fi out of it, at the cost of needing the border router this guide set up. When shopping, the box tells you which you are getting — 'Matter over Thread' and 'Matter over Wi-Fi' are different products wearing the same logo. For battery sensors, Thread is almost always the right answer; for a mains-powered appliance that already lives on Wi-Fi happily, either works. The healthy end-state for most homes looks like this site's whole philosophy: heavy, chatty things on wires or Wi-Fi, small quiet things on low-power meshes, everything speaking locally to one hub.
Official documentation and references
- Home Assistant documentation — the Matter integration
- Home Assistant documentation — the Thread integration
- Connectivity Standards Alliance — the official Matter standard pages
- Thread Group — what Thread is and how it works
Frequently asked questions
Do I need a special radio stick for Matter over Thread?
No — unlike Zigbee, Home Assistant does not talk Thread directly. Your border router (Apple TV, HomePod, eero, etc.) owns the Thread radio; Home Assistant talks to the Matter Server over your LAN. A combined radio stick only matters if you want it to BE a border router via OpenThread Border Router, a more advanced setup.
Matter over Thread or Zigbee — which for new devices?
Both are local, low-power meshes with years of life in them. Zigbee has the deeper, cheaper device catalogue today and one controller (yours). Matter has the multi-ecosystem future and no single-vendor app lock-in. Most homes will run both for a long while; buy the device you like and check it speaks one of them locally.
Does Matter need the internet?
No. Commissioning uses Bluetooth and your LAN; control is local. Vendor clouds only enter if you add the vendor's own app — which this setup deliberately avoids.

