Matter Hub

Overview

The Matter Hub (RiDDiX Home Assistant Matter Hub) runs as a Podman container and exposes Home Assistant entities — including Zigbee devices bridged through Zigbee2MQTT — to Alexa, Apple Home, and Google Home over the local network using the Matter protocol.

It replaces the legacy emulated_hue integration, which was removed because it was limited to Alexa and only emulated bulbs. The Matter Hub exposes the full HA entity surface locally, supports multiple ecosystems simultaneously, and does not require any cloud dependency.

The service is defined in modules/nixos/services/matter-hub.nix.

Ports

Service	Port	Protocol	Description
Web UI	`<port>`	HTTP	RiDDiX Matter Hub admin / commissioning UI

The local port is declared in homelab.proxies.matter-hub and routed through Nginx. The Cloudflare Tunnel forwards https://matter-hub-home.javiersc.com to http://127.0.0.1:<port>.

External Access

Access Method	URL
Local network	`http://<homelab.ip>:<port>`
Cloudflare Tunnel	`https://matter-hub-home.javiersc.com`

The remote route is protected by Cloudflare Access and uses the standard Homelab credentials (same Homelab/username and Homelab/password items used across the stack).

The Nginx reverse proxy has WebSocket support enabled so the commissioning UI and real-time entity updates work correctly over the tunnel.

Architecture

graph LR
    Z2M[Zigbee2MQTT] -->|MQTT| MOSQ[Mosquitto]
    MOSQ --> HA[Home Assistant]
    HA -->|entity bridge| MH[Matter Hub - RiDDiX]
    MH -->|Matter / LAN| ALEXA[Alexa]
    MH -->|Matter / LAN| APPLE[Apple Home]
    MH -->|Matter / LAN| GOOGLE[Google Home]

The container image is ghcr.io/riddix/home-assistant-matter-hub:latest, launched as a native systemd/Podman unit. It connects to the local Home Assistant instance and advertises a Matter fabric on the LAN so that the three voice platforms can commission and control exposed entities without leaving the network.

Secrets

Credentials are managed via 1Password and injected at runtime by systemd. No secrets are stored in the Nix store.

Secret	1Password Item	Description
UI user	`op://Homelab/Homelab/username`	Admin username for the Matter Hub UI
UI pass	`op://Homelab/Homelab/password`	Admin password for the Matter Hub UI

Backup

Matter fabric state and commissioning data live in the Podman container volume declared by the service module. Verify the exact homelab.backupPaths entry in modules/nixos/services/matter-hub.nix before relying on a restore path. Runtime configs and injected secrets are stored in a tmpfs /run/... path and are regenerated on boot, so they are intentionally excluded.

Configuration

Container Environment Idempotency

The matter-hub-config.service renders the Podman environment file from 1Password secrets. A rm -f is issued before the redirect so that a stale environment file from a previous boot cannot block startup with a “file exists” / read-only error. This follows the same pattern as the ESPHome secrets regeneration.

Replacing `emulated_hue`

This service supersedes the deprecated emulated_hue integration:

Before: A single emulated_hue block in configuration.yaml exposed a limited subset of entities (lights) to Alexa only, over a Hue Bridge emulation.
Now: The Matter Hub exposes the full HA entity surface to all three major ecosystems locally.

The emulated_hue integration has been removed from modules/nixos/services/home-assistant.nix.

Troubleshooting

Devices not appearing in Alexa / Apple Home / Google Home

Symptom: A Home Assistant entity is exposed via the Matter Hub but the platform does not discover it.

Cause: The platform has not been commissioned into the Matter fabric, or the controlling device is on a different Layer 2 segment.

Solution:

Open the Matter Hub Web UI at https://matter-hub-home.javiersc.com.
Generate a commissioning code for the platform.
Commission the fabric from the Alexa / Apple Home / Google Home app using that code.
Ensure the controlling phone is on the Eero network (same segment as the Homelab server) for mDNS discovery.

Restarting the service

sudo systemctl restart podman-matter-hub

Checking Logs

sudo journalctl -u podman-matter-hub -f