Guides August 30, 2026 5 min read

Getting Started with Matter in Home Assistant

Matter promises one setup flow for every smart-home brand. Here's what actually happens the first time you scan the code — and how to get a clean pairing on the first try.

HomeOS Lab
HomeOS Lab is an independent smart-home publication covering Home Assistant, Matter, Thread and Zigbee. Guides and buying advice researched from manufacturer docs and the HA community.
Glowing three-petal rosette above a highlighted device tile marked '1' — setting up your first Matter smart-home device.

By HomeOS Lab · Last updated 3 September 2026

Difficulty: Beginner · Time: ~20–30 min · You'll need: Home Assistant 2026.x, one Matter device, and either a Thread border router (for Thread devices) or a Wi-Fi Matter device.

Matter promised one thing above all: buy a device with the Matter logo and it just works, locally, with whatever smart-home platform you already run — Home Assistant included. Mostly, it delivers. But "just works" hides a few decisions (Thread vs Wi-Fi, which border router, how to commission a device that's already tied to Apple or Google) that trip up first-timers.

This guide walks through adding your first Matter device to Home Assistant end to end — what you actually need, the exact steps, the two or three pitfalls that cause 90% of the pain, and how to confirm you got true local control rather than a cloud round-trip.

First, the 60-second mental model

Matter is the application/language devices speak. It rides on top of a transport:

  • Matter-over-Wi-Fi / Ethernet — the device joins your normal network. No extra hardware.
  • Matter-over-Thread — the device speaks Thread, a low-power mesh (like Zigbee's cousin). Thread devices need a Thread border router to reach your IP network.

So the one question that determines your shopping list: is your device Thread or Wi-Fi?

  • Wi-Fi Matter device (many plugs, some bulbs) → you need nothing extra.
  • Thread Matter device (many sensors, locks, low-power gear) → you need a Thread border router. You may already own one: a Home Assistant Connect ZBT-1 running Thread firmware, an Apple HomePod/TV, a Google Nest Hub, or an Aqara/Eve hub can all serve as border routers.
Key point for HA users: Home Assistant can use border routers provided by other ecosystems. You don't have to buy Apple's or Google's hardware just for Home Assistant — but if you already have one, HA can share its Thread network.

What you'll need (checklist)

  • [ ] Home Assistant 2026.x (Matter support is built in; keep HA updated).
  • [ ] The Matter integration enabled in HA (it uses the Matter Server add-on / built-in service).
  • [ ] One Matter device with the Matter logo on the box.
  • [ ] The device's Matter setup code — an 11-digit numeric code and/or a QR code, on the device or in its manual. Guard this code; it's the pairing secret.
  • [ ] For a Thread device: a working Thread border router on the same network.
  • [ ] Your phone with the Home Assistant Companion app (the easiest way to scan the QR code).

Step 1 — Enable the Matter integration in Home Assistant

  1. In Home Assistant, go to Settings → Devices & Services → Add Integration.
  2. Search Matter and add it. HA runs a Matter Server (as an add-on on HA OS/Supervised, or a container elsewhere) — accept the default local server unless you have a specific reason not to.
  3. Confirm the Matter integration shows connected.

Step 2 — (Thread devices only) Confirm you have a Thread border router

  1. Go to Settings → Devices & Services → Thread. HA lists Thread networks it can see.
  2. If you have a Connect ZBT-1 on Thread firmware, an Apple or Google border router, or an Eve/Aqara hub, it should appear here. HA can commission Thread devices onto a preferred network.
  3. If the list is empty and your device is Thread, stop here and set up a border router first — a Thread device cannot be added without one.
Pitfall #1 — "no Thread networks found." This is the most common beginner wall. It almost always means you have a Thread device but no Thread border router yet. Wi-Fi Matter devices skip this entire step.

Step 3 — Put the device into pairing mode

Factory-fresh devices are usually ready to commission out of the box. If the device was previously paired to Apple Home, Google Home, or another controller, you must either:

  • Reset it to factory (check the manual — usually a button hold), or
  • Use multi-admin sharing: in the other app (e.g. Apple Home → device → Turn On Pairing Mode / Add to other platform), generate a new setup code and use that in Home Assistant.
Pitfall #2 — the device is already claimed. A Matter device can belong to several ecosystems at once (that's the point), but each controller needs its own setup code. If HA says the code is invalid, you're likely trying to reuse the printed code on a device another app already owns — generate a fresh pairing code from that app instead.

Step 4 — Commission the device into Home Assistant

  1. In HA: Settings → Devices & Services → Add Integration → Matter → Add Matter device (easiest from the Companion app so you can scan).
  2. Scan the QR code or enter the 11-digit setup code.
  3. For a Thread device, pick the Thread network to join when prompted.
  4. Wait for commissioning — this can take 1–3 minutes. The device joins your network, exchanges certificates, and appears in HA.
  5. Name it and assign it to an Area. Done.

Step 5 — Confirm you got local control (the part people skip)

The whole reason to run Home Assistant is local control. Prove you have it:

  1. Toggle the device from the HA dashboard — response should be effectively instant.
  2. Disconnect your internet (unplug the WAN, not your LAN) and toggle it again. If it still works, you have genuine local control. Matter devices are local by design, so this should pass — and it's a satisfying thing to verify on day one.
Pitfall #3 — expecting Matter to expose everything. Matter standardizes core functions (on/off, brightness, sensor readings). Some vendor-specific features (fancy effects, device settings) may only appear in the vendor's own app or via the device's other integration path (e.g. its Wi-Fi/cloud integration). For most people the Matter feature set is exactly what they want; just don't be surprised if one niche toggle is missing.

Troubleshooting the three things that go wrong

Symptom Most likely cause Fix
"No Thread networks found" No Thread border router on the network Set up a border router (Connect ZBT-1 / HomePod / Nest / Eve / Aqara) first
"Setup code invalid" Device already commissioned by another app Reset the device, or generate a new pairing code via multi-admin in the other app
Commissioning stalls / times out Weak Thread signal, or HA too far from device during pairing Commission near the border router; add a mains-powered Thread router device to strengthen the mesh
Device pairs but is laggy Cloud fallback / poor mesh Verify local control (Step 5); check border-router placement

Where to go next

FAQ

Do I need a hub for Matter with Home Assistant? For Wi-Fi Matter devices, no — Home Assistant is the controller. For Thread devices, you need a Thread border router (which you may already own via Apple/Google/Eve/Aqara, or add via a Connect ZBT-1).

Can a Matter device work with Home Assistant and Apple/Google at the same time? Yes — that's Matter's multi-admin feature. Each controller commissions the device with its own setup code.

Is Matter fully local with Home Assistant? Yes, Matter control is local by design. Verify it with the internet-off test in Step 5.