Skip to content
Homelab Infrastructure

Matter Server

Overview

Section titled “Overview”

The Matter Server provides a standardized bridge for Matter-compatible devices (lights, plugs, sensors) to interact with Home Assistant. It supports both Matter-over-IP (Wi-Fi/Ethernet) and Matter-over-Thread.

Ports

Section titled “Ports”
ServicePortProtocolDescription
API5580TCPMatter WebSocket API

Architecture

Section titled “Architecture”

The service runs as a Podman container using the ghcr.io/home-assistant-libs/python-matter-server image. It uses --network=host to ensure seamless discovery of Matter devices on the local network.

Multi-Admin Strategy (Alexa/Eero Bridge)

Section titled “Multi-Admin Strategy (Alexa/Eero Bridge)”

In this homelab, we use a Multi-Admin approach for Thread devices:

  1. Primary Fabric: Devices are initially paired to the Alexa/Eero network using their mobile apps.
  2. Secondary Fabric (Home Assistant): We “share” the device from the Alexa app using a Commissioning Code (11 digits).
  3. Matter Server: Acts as the secondary controller, communicating with the devices via the Eero Border Router.

[!IMPORTANT] For commissioning to work, the Homelab server MUST be on the same network segment (Eero LAN) as the Alexa devices.

Troubleshooting

Section titled “Troubleshooting”

Commissioning Timeout

Section titled “Commissioning Timeout”

If you get a “Discovery timed out” error when adding a device:

  1. Ensure the server is connected to the Eero LAN port.
  2. Verify that nixos.local is reachable.
  3. Check if the device is advertising its commissioning service:
    Terminal window
    avahi-browse -rt _matterc._udp
    If this returns nothing, regenerate the code in the Alexa app.

Restarting the service

Section titled “Restarting the service”
Terminal window
sudo systemctl restart podman-matter-server

Checking Logs

Section titled “Checking Logs”
Terminal window
sudo journalctl -u podman-matter-server -f