Matter over Thread via Dirigera - HowTo
Hey all, I just spent a lot of time massaging my home network setup to get Thread/Matter over Dirigera to work, so that the Dirigera is just the border router and all devices are ultimately owned by HomeAssistant. To be honest, I'd never have succeeded in this without a LOT of guidance by Claude. And since this was all definitively unintiuitive, I had Claude write a lessons-learned guide to share with you. Hope it helps someone. So, for the rest of the post I'll hand it to the AI:
# Self-hosted Matter-over-Thread with Home Assistant + an IKEA Dirigera (the troubleshooting guide nobody wrote)
This is the guide I wish I'd had. The goal: **Home Assistant owns the Matter fabric** and commissions Matter-over-Thread devices directly, using an **IKEA Dirigera purely as a Thread Border Router (TBR)** β no IKEA cloud, no "IKEA integration," HA is the brain.
It applies to the **harder** setup:
- **Home Assistant Container** (the Docker image), *not* Home Assistant OS. So **no Supervisor and no add-on store** β you self-host the Matter server yourself. (HAOS hides almost everything below by running the Matter Server add-on and its own border router. If you're on HAOS, most of this is automatic; read it anyway for the IPv6 routing trap, which can still bite you.) - A **headless server** running the Matter server **with no Bluetooth** (mine is in a basement rack). This is the detail that breaks the "just commission it in the app" instructions everywhere.
> **A note on the addresses in this guide.** Every IPv6 address below is a **placeholder**. ULAs (the `fdβ¦` ones) are *randomly generated and globally unique* β even though they're not internet-routable, a real one effectively fingerprints a specific network, so don't copy mine (there are none) or anyone else's. Generate your own ULA prefix and substitute throughout.
The symptom that brings most people here: **commissioning fails with `Discovery timed out`, then loops on `PASESession timed out`, and nothing you try in the HA app fixes it.** The real causes are almost never where the error points. There are about five separate, individually-silent failure points. Here they all are.
---
## The setup this guide assumes (anonymized)
Yours will differ in brand and topology, but the IPv6 and routing principles are identical. The relevant pieces:
- **A hypervisor host** running a **container or VM** that hosts Home Assistant. (Mine: a Proxmox node with an unprivileged LXC. Could equally be a NUC, a plain VM, a Raspberry Pi.) - Inside it, **two Docker containers**: **Home Assistant Container** and **`python-matter-server`** β the latter on `--network host`, so it shares the host/container network namespace and its IPv6. *This is why the host's IPv6 routing table is what matters: the Matter server inherits it.* - **No Bluetooth** on that host (headless rack/basement). This single constraint is what shapes the commissioning method later. - **A LAN router/gateway** that can do **static IPv6 + Router Advertisements** (mine is a UniFi gateway; a FritzBox, OPNsense, EdgeRouter, MikroTik, etc. all work). - **An IKEA Dirigera** acting **only as a Thread Border Router** β its own app/cloud otherwise unused. - **One flat LAN/subnet** shared by HA, the Dirigera, and the Thread devices. (mDNS/multicast does not cross subnets β don't split them across VLANs.) - **No ISP/global IPv6.** Everything below uses a private **ULA**, which is all Matter/Thread need on the LAN.
---
## The mental model (read this first β half the battles are conceptual)
Three ideas that, once clear, make every error below obvious:
1. **A Matter *fabric* is not a Thread *network*.** Matter is the application/security layer (who is allowed to control the device); Thread is the IPv6 mesh radio network the device talks over. A device can be on **one Thread network** but in **several Matter fabrics at once** (this is *multi-admin*). Removing a device from one fabric does **not** kick it off Thread.
2. **A Thread Border Router is a *router*, literally.** The Dirigera puts your Thread devices on **their own IPv6 prefix** (a ULA like `fdee:ffff:1111:1::/64`), separate from your LAN. For anything on your LAN (your Matter server) to reach a Thread device, your LAN host must **have a route into that Thread prefix, via the border router.** Thread is an IPv6 network; if IPv6 routing isn't right, nothing works β and the errors won't say "routing."
3. **Commissioning a *brand-new* device needs Bluetooth; commissioning an *already-networked* device does not.** A factory-fresh Matter device only listens over **BLE** until it's on a network. Once it's on Thread, a second admin can join it **over IP** with no Bluetooth at all. This is your escape hatch for a headless/basement server.
Keep these in mind. Every failure below is one of these three biting you.
---
## Prerequisite that breaks everything silently: working LAN IPv6
Matter and Thread are **IPv6-native**. Most home LANs have *no usable IPv6* β either the ISP gives none, or it's only WAN-side. **You do not need ISP/global IPv6.** You need IPv6 *on your LAN*, and a **ULA** (Unique Local Address, `fc00::/7`, the IPv6 equivalent of `192.168.x.x`) is exactly right and never leaves your network.
If your LAN has no IPv6, the Matter server has no IPv6, mDNS-over-IPv6 discovery fails, and you'll chase ghosts for days. Fix the foundation first.
### Step 1 β Give your router/gateway a ULA and turn on Router Advertisements
On the LAN where HA + the Dirigera + the Thread devices live (they **must** share one L2 subnet β mDNS/multicast doesn't cross subnets):
- Set the gateway's **IPv6 interface type to *Static*** (not "none," not Prefix Delegation β PD depends on the ISP, which we're not relying on). - Give it a **ULA /64**. Generate a random ULA prefix (the placeholder here is `fdaa:bbbb:cccc::/64`, gateway address `fdaa:bbbb:cccc::1/64` β **make your own**, don't reuse this). Plenty of online "ULA generators," or just randomize the 40 bits after `fd`. - Enable **Router Advertisement (RA) / SLAAC** on that network. DHCPv6 is not required β SLAAC is enough.
> **UniFi specifics (UCG/UDM):** Settings β Networks β *(your LAN)* β IPv6 β **Interface Type: Static**, enter the ULA `β¦::1/64`, and enable **Router Advertisement**. That's it.
#### "Why does it show a `fe80::` link-local address too?"
Because every IPv6 interface always has a **link-local** address (`fe80::/10`), auto-derived from the MAC, separate from the ULA you set. That's normal and expected. In fact, **clients route through the gateway's link-local, not its ULA** β look at any client's default route and you'll see `default via fe80::β¦`. The ULA you configured is the gateway's *own* address; the `fe80::` is what neighbors actually use as the next hop. Both coexist by design.
### Step 2 β Confirm clients actually get IPv6
On a normal LAN client (or the HA host) after RA/SLAAC is on:
```bash ip -6 addr show # expect a global-scope fd⦠ULA address (SLAAC) ip -6 route # expect: default via fe80::⦠dev <iface> proto ra ```
If you see the ULA and a default route, SLAAC works. If not, RA isn't being received β fix that before going further.
> **Container/VM note:** your Matter-server host must itself get IPv6. If it's a container set to a *static* IPv4 with no IPv6, make sure IPv6 is on the interface β either **SLAAC** (simplest; let it autoconfigure from RA) or a static IPv6 **with the gateway set**. "Static IPv4 + SLAAC IPv6" is a perfectly valid mix. (In a Proxmox LXC the NIC's IPv6 mode can be "static" while still SLAAC-ing β verify with `ip -6 addr`.)
---
## The trap that wastes everyone's week: your host ignores the route into Thread
This is the big one. Even with perfect LAN IPv6, **commissioning still fails with `Discovery timed out`**, then falls back to BLE and loops `PASESession timed out` forever (because your server has no Bluetooth). It looks like a Bluetooth problem. **It is not.** It's a *routing* problem wearing a Bluetooth costume.
### What's actually happening
Your Thread devices are on the border router's **Thread prefix** (here `fdee:ffff:1111:1::/64`), *not* your LAN prefix. The Dirigera advertises a route to that prefix in its Router Advertisements using a **Route Information Option (RIO)** β essentially "I'm not your default router, but send traffic for `fdee:ffff:1111:1::/64` to me." With router-lifetime 0, it's purely a route hint, not a default route.
**Linux ignores RA Route Information Options by default.** The sysctl `net.ipv6.conf.*.accept_ra_rt_info_max_plen` defaults to **`0`**, meaning "accept route options up to prefix length 0" β i.e. none. So your host happily takes the LAN prefix and the default route from RAs, but **silently drops the route into the Thread mesh.** No route β can't reach the device β mDNS/commissioning "Discovery timed out" β BLE fallback β dead end.
### Diagnose it
See what your border router is actually advertising (install `ndisc6` for `rdisc6`):
```bash rdisc6 -m eth0 ```
In the output, look for a **`Route`** option from a router that *isn't* your main gateway β that's the TBR:
``` Route : fdee:ffff:1111:1::/64 β the Thread mesh prefix Route preference : medium Route lifetime : 1800 seconds Router lifetime : 0 seconds β "not a default router, just route THIS to me" from fe80::1a2b:3c4d:5e6f:7890 β the border router (Dirigera) ```
Now check your routing table β note the **absence** of that prefix:
```bash ip -6 route # fdaa:bbbb:cccc::/64 dev eth0 proto kernel ... β LAN, present # default via fe80::β¦ dev eth0 proto ra ... β default, present # β NO route for fdee:ffff:1111:1::/64 β that's the bug ```
### Fix it
Tell the kernel to accept route options up to /64:
```bash sysctl -w net.ipv6.conf.all.accept_ra_rt_info_max_plen=64 sysctl -w net.ipv6.conf.default.accept_ra_rt_info_max_plen=64 sysctl -w net.ipv6.conf.<iface>.accept_ra_rt_info_max_plen=64 # e.g. eth0 ```
Within an RA cycle the Thread route appears: