Tutorial on how to make home-assistant-matter-hub work on nas rpi5  in docker manager.

 

In this article, I’m sharing a way to expose devices you have paired in Home Assistant as a Matter device.

I'm using it to control HomeAssistant devices via Homepod mini.

source:https://smarthomescene.com/wp-content/uploads/2024/06/exposing-home-assistant-devices-as-matter-devices-matterbridge-featured-image.jpg.webp

Project Information

Project on github:https://github.com/t0bst4r/home-assistant-matter-hub

Latest version：https://github.com/t0bst4r/home-assistant-matter-hub/releases

Supported entities:https://github.com/t0bst4r/matterbridge-home-assistant?tab=readme-ov-file#supported-entities

Installation Guide

1.Addon：https://t0bst4r.github.io/home-assistant-matter-hub/installation#id-1-native-home-assistant-addon

2.Docker image:https://t0bst4r.github.io/home-assistant-matter-hub/installation#id-2-1-docker-image

docker pull ghcr.io/t0bst4r/home-assistant-matter-hub:3.0.0-alpha.95
docker pull ghcr.io/t0bst4r/home-assistant-matter-hub:3.0.1

 

History

https://github.com/t0bst4r/matterbridge-home-assistant-addon

2024-11-27，This addon should not be used anymore! It will be replaced with home-assistant-matter-hub.

https://github.com/t0bst4r/home-assistant-matter-hub

 

How it work

To use a Matterbridge with Home Assistant:

install the Matterbridge Add-on,

Communication configure between Matterhub and Home Assistant,Matterbridge to connect to home assistant with url.

Create a new bridge,

Add device "pattern: switch.air_con" in new bridge

start it to generate a pairing QR code

 

Connect accessory to Apple Home

 

use a Matter-compatible app like Google Home to scan the code and link it. This process connects your Home Assistant devices to other Matter ecosystems

 

 

The project is build on top of https://github.com/project-chip/matter.js.

 

There are several advantages actually:

1. Works completely locally over Matter

2. Much easier setup process (one pairing code for all devices)

3. Do not need to do it indivudlaly for Google Home, Alexa, Apple Home.

4. Great for exposing unsupported devices e.g. DIY Devices

 

 

For HassOS User

 

Step 1.Installing the Matter Bridge HA Add-on

To install the Matter Bridge Add-on, you need to add the custom repository in Home Assistant first. Navigate to Settings > Add-ons > Add-on store > Three dots in corner > Repositories and add the following repo:

https://github.com/t0bst4r/matterbridge-home-assistant-addon （Note:DEPRECATION）

https://github.com/t0bst4r/home-assistant-matter-hub

2024-11-27，This addon should not be used anymore! It will be replaced with home-assistant-matter-hub.

https://github.com/t0bst4r/home-assistant-matter-hub

 

For Ha Docker User

Before you start, you will need:

Installing home-assistant-matter-hub Docker by t0bst4r  on a Raspberry Pi

Installing Home Assistant Docker on a Raspberry Pi

 

Note

If you're using Home Assistant Core without add-on support, deploying home-assistant-matter-hub in a Docker container is a convenient alternative.

 

step 1. Install Matterbridge 

Install Matterbridge docker by t0bst4r

docker-compose.yml

services:
  matter-hub:
    image: ghcr.io/t0bst4r/home-assistant-matter-hub:3.0.0-alpha.95
    restart: unless-stopped
    network_mode: host
    environment: # more options can be found in the configuration section
      - HAMH_HOME_ASSISTANT_URL=http://192.168.2.125:8123/
      - HAMH_HOME_ASSISTANT_ACCESS_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhZjZkYTc5YTk5ODU0YWYwYjMyMzZhYTZmZTI2ZDA0MyIsIhdCI6MTc2MjAwMzQyNiwiZXhwIjoyMDc3MzYzNDI2fQ.kMJne4WMlEgozsWux6sNlYEb5cYf4I4juc0DaTRvVlI
      - HAMH_LOG_LEVEL=info
      - HAMH_HTTP_PORT=8482
    volumes:
      - /datadocker/home-assistant-matter-hub:/data

Configuration

Communication  between MatterhubHA and Home Assistant.

      - HAMH_HOME_ASSISTANT_URL=http://192.168.2.125:8123/
      - HAMH_HOME_ASSISTANT_ACCESS_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhZjZkYTc5YTk5ODU0YWYwYjMyMzZhYTZmZTI2ZDA0MyIsIhdCI6MTc2MjAwMzQyNiwiZXhwIjoyMDc3MzYzNDI2fQ.kMJne4WMlEgozsWux6sNlYEb5cYf4I4juc0DaTRvVlI

 

output

@raspberrypi:/datadocker/home-assistant-matter-hub# docker compose up
[+] Running 1/1
 ✔ Container home-assistant-matter-hub-matter-hub-1  Created                                                          
Attaching to matter-hub-1
matter-hub-1  | 2025-11-01 13:40:30.148 INFO   HomeAssistantClient  Waiting for Home Assistant to be up and running - 
matter-hub-1  | 2025-11-01 13:40:35.153 INFO   HomeAssistantClient  Home assistant reported to be up and running
matter-hub-1  | 2025-11-01 13:40:35.164 INFO   WebApi               HTTP server (API & Web App) listening on port 848

How to use

step 2.Open WebUI

click Open WebUI from the add-on's page to access the Matterbridge interface

http://192.168.2.125:8482/bridges/create

step 3. create matter hub bridge

http://192.168.2.125:8482/bridges/create

 

step 4. create matter hub bridge configuration

Example

light

Type:pattern

value:

vacuum

Type:pattern

value:

 

more Example configuration

https://t0bst4r.github.io/home-assistant-matter-hub/bridge-configuration/

 

useful links

https://smarthomescene.com/guides/exposing-home-assistant-entities-as-matter-devices/

https://github.com/Luligu/matterbridge

https://github.com/t0bst4r/home-assistant-matter-hub/issues/846