How to Set Up a Thread Border Router in Home Assistant

Before you click Install on anything, decide which Home Assistant Thread border router setup you are actually building. A fresh Home Assistant Thread network, a Home Assistant border router joining an existing Apple or Google Thread network, and a migration from older Zigbee-oriented hardware look similar in the UI, but they fail in different places.

A Thread border router is the bridge between the IPv6 Thread mesh used by Thread devices and the rest of your home network. For Matter-over-Thread, that bridge is only one part of commissioning: Home Assistant needs a working border router, the OpenThread Border Router add-on needs the right radio settings, your network needs IPv6, and the phone doing the pairing needs the Thread credentials through the Home Assistant Companion App. Home Assistant’s Thread integration is the piece that manages and shares those Thread network credentials inside Home Assistant’s setup flow. [1]

If you only need the protocol overview, start with this Thread, Zigbee, Z-Wave, and Matter primer. This guide stays on the installation path: hardware, OTBR, credentials, first pairing, and the checks that prevent the usual floor-with-a-phone-in-one-hand failure.

Choose the Setup Path First

That first choice matters because the wrong assumption can make every later screen look broken. A fresh Home Assistant Thread network is usually the cleanest path for a first install. Joining or coexisting with an existing Apple or Google Thread network is a credential problem first and a radio problem second. Migrating from Zigbee is mostly a hardware-role problem: a radio that was a Zigbee coordinator yesterday may need different firmware, a different baudrate, or a replacement entirely.

Pick Hardware That Matches the Job

The simple default in 2026 is the Home Assistant Connect ZBT-2. It is the official adapter, priced at $49 or €45, and Home Assistant describes it as plug-and-play with automatic firmware handling for its Thread use case. [2] That does not make it magical; it just removes one of the most common early mistakes, which is flashing or selecting the wrong radio firmware.

Cheaper third-party MG24 dongles can work well once they are flashed with OpenThread RCP firmware. The trade is labor, not capability: devices such as the Sonoff Dongle Plus MG24, often discussed around the $25–30 range, or SMLight’s SLZB-07MG24 need the correct firmware path before OTBR can use them as Thread radios. Third-party comparisons are useful here, but treat them as hardware shopping context and cross-check final settings against Home Assistant’s OTBR documentation. [3]

A GL-S20 is a different category. It is a dedicated LAN Thread border router that runs OTBR itself, then integrates with Home Assistant over the network. GL.iNet documents a Home Assistant integration path for that model, so it is not the same as plugging in a USB RCP radio and letting the Home Assistant OTBR add-on talk to it directly. [4]

The PoE/LAN point deserves a pause because it is where neat rack layouts tempt people into a fragile design. The Spinel RCP link used by OTBR was designed for a low-latency direct connection. Home Assistant’s OTBR documentation warns against TCP/IP for RCP connections because stale routes can leave devices unreachable for up to 30 minutes. [5] That does not mean every LAN-attached Thread device is bad. It means a dedicated border router that runs OTBR itself is not the same risk profile as a remote RCP radio tunneled over TCP.

If you are still deciding between USB and PoE-style placement, the same physical trade-offs discussed in this USB vs. PoE coordinator guide apply here too: radio placement helps, but the transport between Home Assistant and the radio still matters. For a broader hardware decision tree, use the Home Assistant Matter dongle guide.

Prepare the Adapter Before OTBR

Plug the radio into a short USB extension cable before you start. Thread uses the same crowded 2.4 GHz neighborhood as Zigbee and Wi-Fi, and placing a radio directly against a server, mini PC, or USB 3.0 port is a reliable way to create a problem that looks like a software bug.

Then confirm the adapter’s actual role. A ZBT-2 should be treated as the straightforward Thread radio path. A third-party dongle should not be handed to OTBR until OpenThread RCP firmware is installed. A ZBT-1 or SkyConnect that was previously used for Zigbee needs an explicit migration decision; Nabu Casa documents a switching procedure from Zigbee to Thread for Home Assistant Connect ZBT-1. [6] If you still depend on Zigbee, compare replacement coordinators before repurposing the only working radio in the house with this Zigbee coordinator comparison.

Skip old Multiprotocol or MultiPAN guides. That path, where one dongle tried to serve Zigbee and Thread at the same time, is deprecated in current Home Assistant guidance. For a stable setup, dedicate the radio to the role you actually need.

Install and Configure the OpenThread Border Router Add-on

For a USB RCP radio, install the OpenThread Border Router add-on from Home Assistant. The add-on needs the correct serial device and the correct baudrate for the radio. Guessing here is not harmless; the add-on may start, fail, or behave inconsistently depending on the mismatch.

The OTBR add-on configuration also exposes the RCP port and related radio options. Use the device path Home Assistant shows for the adapter, not a copied path from someone else’s guide. If the adapter disappears after a reboot, prefer a stable by-id style device path where available rather than a generic USB path that can change when devices enumerate in a different order.

If you are flashing a third-party dongle, do that before this step. Community guides for devices such as the Sonoff Zigbee 3.0 USB Dongle Plus V2 show the manual firmware route, but the important boundary is simple: OTBR needs OpenThread RCP firmware, not Zigbee coordinator firmware. [7]

Check IPv6 Before You Blame Matter

IPv6 is the failure multiplier in this setup. Home Assistant’s OTBR documentation calls out IPv6 requirements for the Home Assistant host, Docker daemon, and network router. On Home Assistant OS, the Docker daemon setting can require the CLI command ha docker options --enable-ipv6=true. [5]

If Home Assistant OS runs in a VM, add one more layer to the check: the hypervisor. Proxmox, ESXi, and similar hosts can break or filter IPv6 in a way the OTBR warning does not fully diagnose from inside Home Assistant. A setup can look correct in the add-on while the underlying VM network still blocks what Thread needs.

• Home Assistant host has IPv6 enabled.
• Docker IPv6 is enabled where Home Assistant’s install type requires it.
• The home router is not disabling or filtering IPv6 on the LAN.
• A VM or hypervisor bridge is not silently dropping IPv6 traffic.
• The OTBR add-on log is clean after a restart with the radio attached.

Fresh Network or Existing Network: Do Not Mix the Flows

For a fresh Home Assistant Thread network, start the OTBR add-on, open the Thread integration, and let Home Assistant create and manage the Thread network. At this point, the goal is not to pair a sensor yet. The goal is to see Home Assistant, OTBR, and the radio agree that there is a usable Thread network.

For an existing Apple or Google Thread network, slow down. The working setup is not “install OTBR and hope the networks merge.” Home Assistant needs access to the existing Thread credentials through the Thread integration’s supported flow, and the phone used for commissioning needs to know which Thread network it is handing to the new Matter device. The official Thread integration documentation is the authority for the credential management path inside Home Assistant. [1]

This is also why two homes with the same radio can have different results. In one home, Home Assistant is creating the first Thread network. In another, an Apple TV, HomePod, Nest Hub, or similar device may already have established a Thread network. Those are not better or worse setups; they just require different credential handling.

Sync Thread Credentials to the Phone

This is the step many quick guides skip: open the Home Assistant Companion App on the phone that will commission the Matter-over-Thread device and make sure Thread credentials are synchronized there. Without that sync, the phone may reach the Matter commissioning step and still be unable to give the new device the Thread network credentials it needs.

The OTBR add-on can be running perfectly and still not save you from this failure. Matter commissioning is phone-mediated in common Home Assistant flows. The phone scans the setup code, talks to the device during commissioning, and supplies the Thread network information. If the Companion App does not have the credentials, the device can sit there blinking while Home Assistant looks “ready” on the laptop.

1. Install or update the Home Assistant Companion App on the phone you will use for pairing.
2. Sign in to the same Home Assistant instance where the Thread integration and OTBR add-on are configured.
3. Open the app while on the local network so it can receive the Thread credential state from Home Assistant.
4. Use that same phone for Matter-over-Thread commissioning instead of switching to another handset halfway through.

If you have multiple phones, do not assume they all have the same Thread state. The one in your hand during commissioning is the one that matters.

Pair the First Matter-Over-Thread Device

Once OTBR is healthy and the phone has credentials, add the device through Home Assistant’s Matter flow. Keep the first device close to the Thread border router for commissioning. This is not because Thread can only work at short range; it is because the first pairing should prove the software chain before you test mesh placement at the far end of the house.

1. Put the Matter-over-Thread device into pairing mode.
2. In Home Assistant, start the Matter device add flow.
3. Scan the Matter QR code or enter the setup code from the phone running the Companion App.
4. Wait for commissioning to complete before moving the device to its final location.
5. Confirm the entity appears in Home Assistant and updates state at least once.

For the broader Matter side of the process, use the Home Assistant Matter setup guide. This article is deliberately narrower: it gets the Thread border router and credential chain into a known-good state before the rest of Matter setup becomes the main variable.

If It Fails Here, Check This First

If the problem is no longer obviously Thread-specific, move to the Matter troubleshooting checklist. Do that after you have checked credentials, IPv6, serial settings, and radio placement, not before.

Do Not Chase Thread 1.4 Beta During a First Install

The OTBR add-on includes an experimental Thread 1.4 beta toggle. The add-on documentation exposes that option, and outside coverage has noted the beta’s expected credential-sharing direction. [8][9] For a normal first install, leave it alone unless you are intentionally testing beta behavior.

The practical limitation is that the credential-sharing features people expect from Thread 1.4 are not yet exposed through the REST API path Home Assistant uses. [9] Turning on a beta does not remove the need to get today’s credential flow working through the Thread integration and Companion App.

Verify the Setup and Stop Changing Things

A successful Home Assistant Thread border router setup has four visible signs: the OTBR add-on starts cleanly, the Thread integration shows a usable network, the Companion App on the commissioning phone has the credentials, and a Matter-over-Thread device can be added and report state in Home Assistant.

Once those are true, stop changing radio firmware, baudrates, and Thread network ownership. Move the first device to its intended location, confirm it still updates, and then add the next device through the same Matter flow. If you want to understand how this border router fits into the larger Matter ecosystem, use the Matter hub guide for Home Assistant.

References

1. Thread Integration Page — Home Assistant
2. Home Assistant Connect ZBT-2 Product Page — Home Assistant
3. Best Thread Border Routers for Home Assistant 2026 — SmartHomeScene
4. GL-S20 HA Integration Guide — GL.iNet Docs
5. OpenThread Border Router Page — Home Assistant
6. Switching from Zigbee to Thread support on Home Assistant Connect ZBT-1 — Nabu Casa Support
7. Modern Guide to Thread on Sonoff Zigbee 3.0 USB Dongle Plus V2 — Home Assistant Community
8. OTBR Add-on Docs — GitHub
9. Thread 1.4 Beta in Home Assistant — Matter Alpha