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

Matter device→Border router→Matter Server→Home Assistant→Automations

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

  1. 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.
  2. 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.
  3. 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

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

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.

Related guides