Matter Server

Overview

The Matter Server is the Matter controller behind the Home Assistant matter integration. The integration is only a client: it connects over WebSocket to this server, which owns the Matter fabric, the controller credentials, and the commissioned nodes. Home Assistant runs as a container (no Supervisor), so the server is not available as an add-on and runs as a separate service.

The homelab runs matter.js Server (ghcr.io/matter-js/matterjs-server), the official drop-in replacement for the archived python-matter-server. It exposes the same WebSocket API and ships a built-in OTA provider, which enables device firmware updates from Home Assistant.

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

Ports

Port	Protocol	Purpose
5580	TCP	Matter WebSocket API (ws://127.0.0.1:5580/ws), consumed by Home Assistant

External Access

This service is only accessible on the local network. It has no web UI, so it is intentionally omitted from homelab.proxies and the portal.

Architecture

The service runs as a Podman container (podman-matter-server.service) with --network=host, which Matter requires for mDNS, IPv6, and Thread routing through the OpenThread Border Router. The container image runs unprivileged as UID/GID 1000, so the unit’s preStart ensures /var/lib/matter-server is owned by 1000:1000.

The image tag is pinned to a stable release and updated by Renovate through the generic image = "..."; regex manager in renovate.json5. Nightly -alpha tags are not proposed because the pinned version is stable.

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.

Secrets

This service does not require authentication credentials. Fabric credentials are generated by the server and stored in its state directory.

Backup

Data is backed up daily to Backblaze B2 via Restic. The backup path is:

/var/lib/matter-server

Files matching /var/lib/matter-server/*.backup are excluded. Retention follows the global policy described in Backups.

Configuration

Vendor ID (--vendorid 4939)

The existing fabric was created by python-matter-server with vendor ID 0x134B (Nabu Casa, decimal 4939). matter.js defaults to the test vendor ID 0xFFF1, so the container is started with --vendorid 4939. This flag is required: without it, matter.js cannot match the existing fabric and starts with an empty one, leaving every Matter device unavailable. The former nixpkgs services.matter-server module passed the same flag implicitly.

Migration from python-matter-server

The migration to matter.js was completed in October 2026. On first start with the correct vendor ID, matter.js imported the legacy chip.json and <compressed-fabric-id>.json files into its native storage (server-1-* directory). The legacy files have since been removed from the state directory and remain only in older Restic snapshots.

Troubleshooting

All Matter devices unavailable after a container change

Symptom: Every Matter entity in Home Assistant is unavailable and the logs show Found 0 nodes.

Cause: matter.js did not match the existing fabric (typically a wrong or missing --vendorid) and created a new, empty fabric.

Solution:

1. Check the logs for No fabric found matching vendorId=....
2. Fix the vendor ID in modules/nixos/services/matter-server.nix and rebuild.
3. If an empty fabric was already created, stop the service, move the new server-1-* and config directories out of /var/lib/matter-server, restore the legacy files from Restic if needed, and start the service again.

Device firmware update fails

Symptom: Installing a Matter firmware update from Home Assistant fails.

Cause: OTA is provided by the matter.js server itself and is enabled by default. Failures usually mean OTA was disabled (DISABLE_OTA) or the DCL is unreachable.

Solution: Check the logs for OTAUpdateService and SoftwareUpdateManager entries.

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:

   avahi-browse -rt _matterc._udp

   If this returns nothing, regenerate the code in the Alexa app.

Diagnostics

Use the specialized MCP tools for diagnosis:

• service_logs(service="podman-matter-server", lines=50)
• service_status(service="podman-matter-server")
• manage_service(action="restart", service="podman-matter-server")

Or manually on the server:

sudo journalctl -u podman-matter-server -f
sudo systemctl restart podman-matter-server