Set up Thread & Matter in Home Assistant with Docker

Attention smart home fans! If you want to network your devices in a future-proof way, there's no way around Thread and Matter over. In this article, I'll show you step by step how to do both directly in Home Assistant in Docker set up. In the end, you can control your smart devices reliably and across platforms.

Setting up a thread network in a completely dockerized smart home setup is terribly complex and took me months to get it right myself and would now like to offer you a guide so that you can get it right away!

For detailed instructions and an explanation of all configuration options, I recommend the YouTube video linked below. In this video, every single setting is explained in detail so that you receive comprehensive instructions for the exact setup. You can find any code from the video in this article so that you can use it directly without having to type it in.

Many smart home users often confuse Thread and Matter or think they are the same thing. In fact, they are two different but closely cooperating technologies.

What is Thread?

Thread is a modern mesh network protocol that was specially developed for smart home devices. Unlike classic WLAN or Bluetooth Low Energy, Thread has some decisive advantages:

1. Mesh network: All devices (nodes) connect to each other. If a device fails, the data still finds another route.
2. Energy efficiency: Ideal for battery-operated sensors, as Thread consumes very little power.
3. Fast & reliable: Devices communicate directly with each other without overloading a central hub.
4. Safe: Thread uses modern encryption and authenticated device connections.

Thread self-defined onlyhow devices talk to each other. It does not say what the devices do or how to control them - for that you need a protocol like Matter.

Practical example:
You have several lights and sensors distributed throughout the house. With Thread, a motion sensor in the basement can control a light on the first floor, even if the central gateway is briefly offline. The network automatically finds the fastest route.

What is Matter?

Matter is an open standard that makes devices from different manufacturers compatible. The aim is to ensure that a smart home device can be integrated "out-of-the-box" into any compatible system.

Important points about Matter:

• Manufacturer-independent: Philips Hue, Ikea Tradfri, Nanoleaf and others can be controlled together.
• Platform-independent: Apple HomeKit, Google Home and Amazon Alexa support Matter.
• Safe: Matter uses Thread, Wi-Fi or Ethernet with strong encryption.
• Easy to set up: Pairing via QR code or NFC.

Matter thus defines the languagein which devices speak, while Thread speaks the Means of transportation is a reliable means of transmitting this language.

Practical example:
You buy a new smart socket from another manufacturer. With Matter, all you have to do is scan it and you can immediately integrate it into automations without a separate app.

Interaction of thread and matter

You can imagine Thread and Matter as follows:

• Thread = street
• Matter = Car

Matter is the protocol that gives the "commands" to devices - e.g. "Switch on the light". Thread is the network via which these commands are transported.

Thanks to Thread, Matter messages can be forwarded between devices particularly quickly, stably and energy-efficiently. The interaction has three decisive advantages:

1. Reliability: Even with many devices in the house, automations work smoothly because Thread forms a self-healing mesh network.
2. Energy efficiency: Battery-operated devices such as sensors last much longer.
3. Manufacturer-independent control: Matter ensures that you can control devices from different manufacturers centrally via Home Assistant or other platforms.

Feature	Thread	Matter
Type	Network protocol	Application protocol / device standard
Task	Transport data	Control & standardize devices
Operation	Mesh, energy efficient	Via Thread, Wi-Fi or Ethernet
Device control	None (transportation only)	Yes (control, automations, scenes)
Example	Motion sensor sends signal	Matter switches light based on signal

Thread and Matter are not competitors, but complement each other perfectly. Thread ensures stable, fast and energy-efficient communication between devices, while Matter ensures that all devices work together in a compatible way, regardless of manufacturer. In combination, they form the basis for a smart home that Robust, flexible and future-proof is.

Differences: Thread vs Zigbee vs Matter over Wi-Fi

Feature	Thread	Zigbee	Matter over Wi-Fi
Network type	Mesh	Mesh	Client-Server (Wi-Fi)
Energy consumption	Very low	Low	High (Wi-Fi)
Reach	Medium (expandable with mesh)	Medium (mesh)	Depending on WLAN
Compatibility	Matter, only compatible devices	Manufacturer-dependent	Matter, only compatible devices
Stability & latency	High, self-healing	Medium	Medium, depending on WLAN
Advantage	Efficient, self-healing	Many devices available	Easy to install

In short:

• Thread is ideal for battery-powered, energy-efficient mesh devices and also the future.
• Zigbee is widely used, but is manufacturer-dependent and less standardized, although it is currently still the standard.
• Matter over Wi-Fi is simple, but consumes more energy and depends on the Wi-Fi quality.

What is Home Assistant?

Home Assistant is an open source platform for home automation that aims to connect and centrally control all devices in the home. It is designed to provide a unified user interface and simple, flexible control for a variety of smart home devices from different ecosystems. Here are some points in favor of Home Assistant:

1. CompatibilityHome Assistant supports thousands of devices and services from various manufacturers, including lighting, air conditioning, heating, cameras, weather sensors, voice assistants and more.
2. Local controlUnlike many commercial smart home platforms that rely on cloud services, Home Assistant runs locally on your network. This means increased privacy and reliability, as your smart home devices work even without an active internet connection.
3. Automation and scenesOne of the main features of Home Assistant is the ability to create complex automations and scenarios. For example, you can have lights switch on automatically when it gets dark or turn on the heating when the temperature falls below a certain level.
4. Simple user interfaceHome Assistant offers a user-friendly interface that makes it easy to monitor and control devices. This interface is fully customizable.
5. Integration with voice assistantsHome Assistant can be integrated with voice assistants such as Amazon Alexa or Google Assistant to enable voice-controlled control of your smart home devices.
6. Open source and community-drivenSince Home Assistant is open source, it is supported by an active community that is constantly developing new integrations and improving existing ones.
7. Data protection and securityAs a locally running platform, Home Assistant has the advantage that the data remains within its own network. This protects privacy and increases security compared to cloud-based solutions.

In summary, Home Assistant is a powerful and flexible solution for those who want to design their own smart home and control their devices centrally, regardless of the manufacturer or ecosystem.

Our setup: Home Assistant, Docker & Matter with Thread

For this setup we use Home Assistant on a server in one Docker container. This allows Home Assistant to run not as supervised versionwhich means:

• We have No integrated add-ons like the official Matter add-on.
• Everything we need, we have to do ourselves in own Docker containers provide.

Therefore we need in our setup:

1. A Matter Server Container
   This container provides the Matter functionality that enables Home Assistant to control Matter devices.
2. An OpenThread Border Router Container
   This container connects the Thread mesh network with Home Assistant and ensures that Matter can run via Thread.
3. A thread-compatible USB stick
   The USB stick acts as an interface between the thread devices in the mesh and the OpenThread Border Router Container.

Which USB stick do we use?

For our example, we use the Home Assistant ZBT-1 (formerly known as SkyConnect).

• This stick is Thread-compatible and works reliably in Docker.
• Note: A stick can only be used for one radio protocol at a time.
  • This means: If you run threads about Matter, you can use the same stick not simultaneously for Zigbee use.
  • If you want to use Zigbee in parallel, you need a second sticke.g. a Zigbee USB dongle.

Overview: How it all comes together

1. Home Assistant Container
   • Runs on your server
   • Does not contain any add-ons
   • Controls automations and devices via the Matter API
2. Matter Server Container
   • Translates the Matter commands into thread-compatible messages
   • Connects Home Assistant to the thread mesh
3. OpenThread Border Router Container
   • Communicates directly with the thread USB stick
   • Establishes the thread mesh and forwards messages between Matter Server and threaded devices
4. Thread-compatible USB stick (ZBT-1 / SkyConnect)
   • Used exclusively for thread
   • Establishes the connection between physical devices and the OpenThread Router Container

Requirements

To set up our setup successfully, you should fulfill the following requirements:

1st Docker & Home Assistant in Docker

• DockerDocker must be installed on your server, as both Home Assistant and the required additional containers (Matter Server, OpenThread Border Router) run in it.
• Home Assistant in Docker:
  • We use Home Assistant as Container solution.
  • Advantage: simple updates, backups and portability.
  • Note: If you a non-Docker version of Home Assistant, the setup also works in principle, but the integration of the additional services then runs slightly different

2. thread-compatible USB stick

• A Thread USB stick is required to connect the Thread mesh network to Home Assistant.
• Example: Home Assistant ZBT-1 (formerly SkyConnect).
• Important: A stick can only ever be a radio protocol operate. If you want to use Zigbee at the same time, you need a second USB stick.

3rd Matter-capable device

• You need at least a device that supports Matter via Threadto be able to test the integration.
• Examples: Philips Hue lamps (latest generation), Nanoleaf Shapes, Eve Energy sockets.
• These devices form the basis for automations, scenes and smart home control via Home Assistant.

4. access to your router

• For the correct setup of Thread & Matter Access to your router required.
• Reasons:
  • Checking the network connection and activating IPv6
  • Ensure that Docker containers can access the network (e.g. host network mode or port shares)
  • Required communication between Matter devices, Border Router and Home Assistant

Step-by-step instructions

Step 1: Prepare threaded USB stick (Home Assistant ZBT-1)

Before you can use Matter via Thread, your Thread-compatible USB stick and flashed with the correct firmware. This step is crucial so that the stick can be used as a OpenThread Border Router works.

Notes on the firmware

• The firmware update via the web flasher is Only for Home Assistant SkyConnect and Home Assistant ZBT-1 devices available.
• The following are supported only devices purchased after October 20, 2024.

Important: Without the correct firmware, the stick Do not create a thread mesh and Matter devices do not respond correctly.

Provide USB stick:

• Use the Home Assistant ZBT-1 Stick (formerly SkyConnect).
• Connect the stick to a PC or laptop which is accessible via USB.

Select firmware:

• Open the page: https://home-assistant-skyconnect.netlify.app/firmware-update/
• Select the Current firmware version for the ZBT-1.

Use Web Flasher:

• The firmware is installed via the Silicon Labs Web Flasher written directly to the stick in the browser.
• To do this, the stick must be connected to the computer.
• Select the desired firmware and start the flash process.

Step 2: Insert the USB stick into the server and determine the path

After the Home Assistant ZBT-1 Stick was prepared with the thread firmware, plug it into the Serveron which Home Assistant is also running. In order for the containers to be able to access the stick later, you must set the Exact device name/path find out.

How to find the USB stick on Linux

Change to the corresponding directory:

cd /dev/serial/by-id

Display content:

ls -l

You will then see all the connected serial devices. In our case, for example, it looks like this:

usb-Nabu_Casa_Home_Assistant_Connect_ZBT-1_fe6994e0f338ef119e76e3d154516304-if00-port0 -> ../../ttyUSB0

• usb-Nabu_Casa_Home_Assistant_Connect_ZBT-1_fe6994e0f338ef119e76e3d154516304-if00-port0 is the Name of the device.
• ../../ttyUSB0 points to the actual Linux device.

You should follow this path for the subsequent Docker configuration as the OpenThread Border Router Container needs exactly this USB port to communicate with the stick.

If you have several USB sticks, check carefully which stick should be used for Thread.

Step 3: Activate IPv6 on the Linux server

So that Thread and Matter work correctly, IPv6 support is required on your server. Thread based internally to IPv6more precisely on 6LoWPAN over IEEE 802.15.4. Matter uses these IPv6 addresses to reliably address devices and route data packets in the mesh.

Why IPv6 is necessary:

• Each Thread device requires a Unique 64-bit addresswhich is provided via IPv6.
• Matter communication takes place via thread via IPv6 multicast for device discovery and automatic configuration.
• Without IPv6, the OpenThread Border Router cannot recognize devices and Matter cannot deliver commands correctly.

sysctl: What is that?

sysctl is a Linux tool with which you can Kernel parameters at runtime can change.

• Example: You can Activate forwardingi.e. the forwarding of packets between networks.
• You can switch IPv6 on or off, accept router advertisements or set maximum prefix lengths.
• Changes with sysctl apply immediately, but can be lost when restarting, which is why many users use a start script.

Script for IPv6 & Docker

In my case, I have created a script that starts my Unraid Servers is executed. It activates IPv6 and configures the network interfaces correctly for Docker, Thread and Matter. It also outputs the configuration again to check whether it has been applied.

#!/bin/bash
#description=This script applies sysctl settings to allow Docker to use IPv6.
#arrayStarted=true
#name=Docker Enable IPv6

# Delay before starting
sleep 10

apply_sysctl_settings() {
echo "Applying sysctl settings..."
sysctl -w net.ipv4.conf.all.forwarding=1
sysctl -w net.ipv6.conf.all.disable_ipv6=0
sysctl -w net.ipv6.conf.all.forwarding=1 # Activate IPv6 forwarding
sysctl -w net.ipv6.conf.br0.accept_ra=2 # br0 accepts Router Advertisements
sysctl -w net.ipv6.conf.br0.accept_ra_rt_info_max_plen=64 # Route information from the RAs can be processed

#Check user script log for info
echo "Verifying sysctl settings..."
sysctl net.ipv4.conf.all.forwarding
sysctl net.ipv6.conf.all.disable_ipv6
sysctl net.ipv6.conf.all.forwarding
sysctl net.ipv6.conf.br0.accept_ra
sysctl net.ipv6.conf.br0.accept_ra_rt_info_max_plen
}

#Execute script after delay...
apply_sysctl_settings

Explanation of the most important parameters

Parameters	Function
net.ipv4.conf.all.forwarding=1	Activates IPv4 forwarding between interfaces
net.ipv6.conf.all.disable_ipv6=0	Switch on IPv6
net.ipv6.conf.all.forwarding=1	Activate IPv6 packet forwarding
net.ipv6.conf.br0.accept_ra=2	The interface br0 Accepts Router Advertisements (RA) for automatic configuration
net.ipv6.conf.br0.accept_ra_rt_info_max_plen=64	Maximum prefix length for route information from RA

• Set the script so that it is executed automatically when the server is startede.g. via /boot/config/go for Unraid or systemd-Unit for other Linux servers.
• Works without correct IPv6 Matter about thread notDevices do not appear and automations fail.

Explanation: What is br0 and why do we need it?

• br0 is a Bridge interface under Linux.
• It connects several network interfaces with each other and is often used by Docker to integrate containers into the network.
• In the context of Thread & Matter serves br0 as an interface through which the OpenThread Border Router Container and the Matter Server Container communicate with your local network.
• IPv6 must be set to br0 must be activated so that the container Receive and send IPv6 packets which are necessary for thread and matter communication.

In short:
br0 acts as a bridge between your server (Docker host), the containers and the rest of your home network. Without correct IPv6 on br0 Thread devices could not be recognized via the border router.

Activate IPv6 in the router

So that Thread about IPv6 works, IPv6 must also be activated in your home network. Otherwise, the border router containers cannot use IPv6 addresses and Matter devices cannot be found.

Example: FRITZ!Box 6690 Cable

1. Open the FRITZ!Box interface:
   • Open browser, 192.168.178.1 and log in.
2. Activate IPv6:
   • Go to Internet → Access data → IPv6.
   • Check the box next to "Activate IPv6 support".
3. Check prefix assignment:
   • Make sure that the FRITZ! an IPv6 prefix distributed.
   • Optional: Check under Home network → Network → Network settingsthat your server receives an IPv6 address from the router.
4. Activate Router Advertisements (RA):
   • Thread requires Router Advertisements to obtain network information automatically.
   • In the FRITZ!Box, RAs are automatically distributed with activated IPv6.
5. Testing:
   • After activation you can check on your server:
     • ip -6 addr show br0
   • You should see an IPv6 address, e.g. fdxx:xxxx:xxxx::xxxx.

However, you will only see the IPv6 address if your server also has IPv6 enabled! With Unraid, we also have to do this manually

Note: For detailed visual steps there are also Video tutorialsin which the IPv6 activation on the FRITZ!Box is shown. This is particularly helpful if you are unsure exactly which settings are required.

Step 4: Activate IPv6 on the (Unraid) server

So that Thread & Matter work correctly via IPv6, IPv6 must also be activated directly on your Unraid server. We will go through this step by step.

1. preparation: Stop Docker and VM service

• In Unraid, changes must be made to the network protocol, therefore Docker and VM service be stopped.
• Go to Settings → Docker → Stop Docker service and also Stop VM service.

Important: As long as these services are running, network changes cannot be applied correctly.

2. adapt the network interface

• In most cases, the main interface of your server is eth0.
• Go to Settings → Network → eth0.
• Position at Network protocol to IPv4 + IPv6.

3. optional: store static IPv6 DNS servers

• You can static IPv6 DNS servers enter, e.g. 2001:4860:4860::8888 (Google DNS).
• This is optional, but makes sense if IPv6 connections are to be reliable.

4. restart Docker and VM service

• After the change, you must Docker and VM service reactivate.
• Go back to Settings → Docker and click on Start.
• Likewise for VM service start.

5. check whether IPv6 is active

• Pro tip: On the Page on which Docker is activated/deactivatedyou can use the IP addresses for br0 see.
• Both the IPv4 as well as the IPv6 address are displayed.
• If an IPv6 address is available, the configuration has been successfully applied.

The Unraid server is now correctly configured for IPv6 and ready to receive the OpenThread Border Router Container and the Matter Server Container to operate.

Step 5: Install Matter Server Docker Container

Once the USB stick has been prepared and IPv6 has been activated on the server, we can now start the Matter Server install in Docker. For this we use docker-compose for easy administration.

docker-compose.yml for the Matter server

services:
  matter-server:
    container_name: matter-server
    image: ghcr.io/home-assistant-libs/python-matter-server:stable
    restart: unless-stopped
    network_mode: host
    security_opt:
      - apparmor:unconfined
    volumes:
      - /mnt/cache/appdata/smart-home/matter-server:/data
      - /run/dbus:/run/dbus:ro

Important notes

1. network_mode: host

• Why crucial:
  • Matter and Thread require direct access to the host's network, in particular to IPv6 multicast and local portsto discover and control devices in the thread mesh.
  • If the container is running in standard bridge mode, packets cannot be exchanged correctly between the host and threaded devices.
  • Therefore: All relevant containers (Home Assistant, Matter Server, OpenThread Border Router) must be in the host-mode run.
• Advantages of host for our setup:
  1. Full network access like the host itself
  2. IPv6 multicast works reliably
  3. Devices in the LAN/thread mesh are recognized correctly

2. volumes

• /mnt/cache/appdata/smart-home/matter-server:/data
  • Persistent data such as device pairings, certificates and configurations are stored here.
• /run/dbus:/run/dbus:ro
  • Access to the host's D-Bus, necessary for certain system interactions and Bluetooth.

3. safety

• apparmor:unconfined allows the container to perform all necessary network operations that would otherwise be restricted by AppArmor.

Summary

1. Create the file docker-compose.yml at a location of your choice, e.g. /mnt/cache/appdata/smart-home/matter-server/.
2. Paste the above content.
3. Start the container with :

docker-compose up -d

• The Matter server should then be running and able to access your network.
• Through the Host network mode it can correctly perform all IPv6 and multicast communications required for Matter over Thread.

Official documentation

For all details, additional configuration options and updates, see the official documentation of the Python Matter Server on GitHub:
Python Matter Server Docker Setup

Why network_mode: host is so important - mDNS

In addition to general network access host mode especially for mDNS (Multicast DNS) decisive.

• What is mDNS?
  • mDNS is a protocol with which devices in the local network can be automatically announce and discover their services can.
  • Devices need mDNS to find each other without having to enter IP addresses manually.
  • It works via Multicast to IPv4 and IPv6 so that all devices in the LAN receive the information.
• Why it is necessary for Matter/Thread:
  • Matter devices use mDNS to register in the network and to be recognized by the Matter server.
  • Without direct access to the host network, mDNS packets could not reach the container.
  • With network_mode: host the container can Receive and send multicast packetsso that devices are found automatically.

To summarize: network_mode: host is crucial for IPv6, multicast and mDNSso that the Matter server can correctly detect and control all devices in the thread mesh.

Step 6: Install Open Thread Border Router Docker Container

In order for Home Assistant and the Matter server to be able to communicate with Thread devices at all, we need a OpenThread Border Router (OTBR). This takes on the role of a gateway between your local IP network (IPv6) and the thread mesh.

To this end, we are creating another docker-compose.yml:

services:
    openthread:
        image: openthread/border-router:latest
        container_name: openthread
        network_mode: host
        privileged: true
        environment:
            - TZ=Europe/Berlin
            - OT_RCP_DEVICE=spinel+hdlc+uart:///dev/ttyUSB0?uart-baudrate=460800
            - OT_LOG_LEVEL=7
            - OT_THREAD_IF=wpan0
            - OT_INFRA_IF=br0
            - OT_REST_LISTEN_ADDR=0.0.0.0
            - OT_REST_LISTEN_PORT=9212
        volumes:
            - /mnt/cache/appdata/smart-home/openthread:/data:rw
        devices:
            - /dev/serial/by-id/usb-Nabu_Casa_Home_Assistant_Connect_ZBT-1_fe6994e0f338ef119e76e3d154516304-if00-port0:/dev/ttyUSB0
            - /dev/net/tun:/dev/net/tun
        cap_add:
            - NET_ADMIN
        restart: always

Explanation of the most important parameters

Variable / setting	Meaning
network_mode: host	As with the Matter server, this is essential for multicast, IPv6 and mDNS. This is the only way the OTBR can be correctly visible in the network.
privileged: true	Allows direct access to network functions and kernel interfaces, e.g. for creating the wpan0 interface.
/dev/serial/by-id/...:/dev/ttyUSB0	Integrates the USB stick as an RCP (Radio Co-Processor). The path must match your stick exactly.
/dev/net/tun	Necessary for creating the virtual network interface for the thread mesh.
cap_add: NET_ADMIN	Gives the container additional network rights, for example to create wpan0 or route management.

Explanation of the important environment variables

Variable	Function
OT_RCP_DEVICE=spinel+hdlc+uart:///dev/ttyUSB0?uart-baudrate=460800	Defines the Thread radio module (RCP). Here we talk about UART + Spinel protocol the connection to the USB stick is established. 460800 baud is standard for the Home Assistant ZBT-1 stick. And actually also for all other sticks.
OT_LOG_LEVEL=7	Sets the log level to Debug. Very helpful when setting up, later you can reduce it to 3 or 4.
OT_THREAD_IF=wpan0	Name of the interface that the container uses as Thread-Mesh Interface created.
OT_INFRA_IF=br0	Specifies which interface the OTBR uses to communicate in the local network (LAN) - here our Linux Bridge br0 with IPv6 support.
OT_REST_LISTEN_ADDR=0.0.0.0	The REST API endpoint becomes accessible to all devices in the network.
OT_REST_LISTEN_PORT=9212	Port for REST API. Used later for diagnostics or integration with tools.

Official reference

Further possible variables, advanced options and debug tools can be found in the official documentation:
👉 https://openthread.io/guides/border-router/build-docker

Step 7: Set up thread network (Form Thread Network)

In order for your OpenThread Border Router to create a new thread network, use the ot-ctl-interface (OpenThread CLI) to execute the following commands:

Entering the ot-ctl console

• If your Border Router Container is already running, you can use docker exec open an ot-ctl session:

docker exec -it openthread ot-ctl

• If you run OpenThread natively (not in Docker), you can directly:

sudo ot-ctl

In the ot-ctl console you will receive a command prompt > .

Configure new thread network

1. Initialize new dataset

The dataset contains all network parameters (channel, network name, key, etc.):

dataset init new
Done

This creates an "empty" new dataset.

2. Show dataset

Once the new dataset has been created, you can view it:

dataset
Active Timestamp: 1
Channel: 15
Wake-up Channel: 16
Channel Mask: 0x07fff800
Ext PAN ID: 39758ec8144b07fb
Mesh Local Prefix: fdf1:f1ad:d079:7dc0::/64
Network Key: f366cec7a446bab978d90d27abe38f23
Network Name: OpenThread-5938
PAN ID: 0x5938
PSKc: 3ca67c969efb0d0c74a4d8ee923b576c
Security Policy: 672 onrc 0
Done

This gives you all the important settings at a glance and lets you know what your network will look like later.

We are still in the ot-ctl CLI of the container (docker exec -it openthread ot-ctl)

3. Actively adopt dataset

Now we need to activate and start the thread network.

After dataset init new has been executed, this dataset must be set to active:

dataset commit active
Done

This means that the Border Router saves the network configuration permanently (persisted in the container volume).

4. Activate interface

The network interface is now switched on:

ifconfig up
Done

Note: This creates the Thread interface wpan0 logically and brings it into the active state.

5. start thread network

thread start
Done

This will take a few seconds. You can then check the status:

state

Once everything is running correctly, you should see one of the following roles:

Role	Meaning
leader	Your border router is the central control device of the mesh network (expected with a fresh network)
router	Acts as a forwarding node / route manager
child	Subordinate node (common for additional nodes)

Important: If "detached" appears → IPv6 or dataset is not correct. Then check whether br0 IPv6 is active and the USB stick is correctly integrated.

6. thread interface (wpan0) on the host system

This step will not in the ot-ctl Terminalbut directly on the Linux host executed, i.e. in Unraid SSH or terminal. Enter the following:

ifconfig wpan0

If everything has been set up correctly, you will see an output similar to:

wpan0: flags=4305 mtu 1280
        inet6 fe80::3c98:89e8:ddec:bda7 prefixlen 64 scopeid 0x20
        inet6 fd4d:b3e5:9738:3193:0:ff:fe00:fc00 prefixlen 64 scopeid 0x0
        inet6 fd4d:b3e5:9738:3193:0:ff:fe00:f800 prefixlen 64 scopeid 0x0
        inet6 fd4d:b3e5:9738:3193:39c4:ee02:ca9e:2b1d prefixlen 64 scopeid 0x0
        unspec 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00 txqueuelen 500 (UNSPEC)
        RX packets 16 bytes 1947 (1.9 KiB)
        RX errors 0 dropped 3 overruns 0 frame 0
        TX packets 7 bytes 1152 (1.1 KiB)
        TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0

What does that mean?

✅ wpan0 is visible → OpenThread Border Router has successfully created a network interface
✅ Multiple IPv6 addresses visible → Thread mesh has received prefixes and local addresses
✅ RX/TX data → the interface actively sends and receives packets (e.g. multicast for mDNS, mesh communication)
✅ Prefix fdxx: → this is the mesh-local prefix of your thread network

Error check:

• Will none wpan0 Interface displayed → Container has no rights / privileged: true is missing or /dev/net/tun not bound
• Only inet6 fe80::... (Link-Local) but no fdxx:: Prefix → Network not started correctly → thread start or dataset commit active check

This means that your Thread network active at host level and IPv6-routed. It is precisely this visibility that is essential later on so that Home Assistant can automatically recognize the network as a "Border router available" recognizes.

Step 8: Connect integrations in Home Assistant

When all of this is fulfilled, Home Assistant automatically recognizes the services via mDNS & IPv6 Multicast. You must No manual configuration via files everything happens via the UI.

Add thread integration (without inputs)

1. Home Assistant → Settings → Devices & services → Add integration
2. Search for "Thread"
3. Important: Here do not enter anything, simple add/confirm.
4. The Home Assistant then appears under Settings → Network → Thread the entry, but without active border routeronly as generic thread management.

➡ This step only activates the Thread infrastructure within Home Assistant, but still No connection to OTBR.

Open Thread Border Router Integration (with URL input)

1. Add integration once again
2. This time "Open Thread Border Router" select
3. Here the REST-API address must be entered manually:

http://:9212
http://192.168.178.29:9212

Confirm → Home Assistant connects and reads Dataset, status & role (leader/router) from the OTBR.

After that in the same thread menu under Network → Thread an active Border router entry with device details. Another network is then displayed with the name OpenThread-xxxx. Then you have to click on the button Make preferred network click to activate the network.

Matter Integration (with URL input)

1. Add integration once again
2. This time "Matter" select
3. Here the Address not be changed:

ws://localhost:5580/ws

What happens after installation?

• Under Settings → Devices & services → Matter Server you can see whether the connection has been established
• You get new options: "Add Matter device"
• As soon as you have a new Matter-capable device (e.g. via thread) is set to pairing mode, the option to enter a pairing mode appears in Home Assistant. Scan the setup code or enter it manually (e.g. XXX-XXX-XXX)
• Home Assistant uses Matter first → then automatic thread pickingif the device is thread-based → it asks you which thread network should be used (from the OTBR dataset)

Step 9: 📱 Synchronize thread access data with Home Assistant app (iOS & Android)

Matter about thread works only then completelywhen your smartphone the Thread network credentials received from Home Assistant.
Because: The smartphone takes on the role of commissioner during pairing and must know the thread network in order to bring in the device.

🔁 How to activate synchronization:

• Open the Home Assistant app on your smartphone (iOS or Android)
• Profile / Settings → Companion app settings
• You will find the item under "Troubleshooting / Developer tools":
  • 👉 "Synchronize thread access data" (English: "Sync thread credentials")
• Activate this button or start synchronization

Step 10: Pair Matter device via thread

Example Nanoleaf Essentials E27 (QR code / setup code). You need to use your smartphone with the Home Assistant app.

1. add Matter device in HA

• In Home Assistant → Settings → Devices & services → Add device
• Selection: "Add Matter device"
• Home Assistant opens a hint and shows the options:
  • Scan QR code
  • Enter setup code manually (XXX-XXX-XXX format)

👉 For the Nanoleaf Essentials you will find the code on the lamp holder or enclosed card. Alternatively, you can scan the QR code directly with the HA Companion App scan.

2. pair with smartphone (commissioning process)

• HA app opens camera / input field
• Scan the Matter QR code
• Confirm → Home Assistant starts the Matter picking

3rd device joint the Thread network

• The Nanoleaf lamp now automatically connects to the OTBR (via wpan0 / Border Router)
• Home Assistant shows the progress:
  • ✅ Matter connection established
  • ✅ Device added to the thread network
  • Services initialized

👉 After a successful join, the light appears Directly in Home Assistant as a new device with Matter integration

YouTube video implementation

Conclusion

With this setup, you have not only Matter and thread support integrated into Home Assistantbut at the same time the basis for a Stable, fast and future-proof smart home created - and that completely without supervisor and add-onspurely via Docker.

You know now:

• What Matter and Thread really mean and how they differ from Zigbee or WLAN
• Why IPv6 and mDNS are indispensable for Matter and how to activate them cleanly at server, Docker and router level
• How to create a Home Assistant ZBT-1 USB stick flashes correctly on Thread and integrates it into the system via OTBR
• Why the host network mode is essential is - not optional
• How to talk about Matter server, OTBR and thread integration link all building blocks together
• How pairing really works - including smartphone thread syncwhich is often forgotten
• And finally: How to integrate a real Matter device like the Nanoleaf Essentials lamp

👉 This means you are no longer reliant on manufacturer clouds, Your devices transmit locally, energy-efficiently and at lightning speedand you have full control - just like a real smart home deserves.

🔗 Useful links at a glance

Topic	Link
Thread Firmware Flash for HA ZBT-1	https://home-assistant-skyconnect.netlify.app/firmware-update/
Matter Server Docker Docs	https://github.com/matter-js/python-matter-server/blob/main/docs/docker.md
OpenThread Border Router Guide	https://openthread.io/guides/border-router/build-docker
Network setup with OTBR	https://openthread.io/guides/border-router/form-network

Interested, but lack time or knowledge?

No problem. Contact me and we will discuss your requirements. No matter if business or private.