Release 2026.1.1

Author: Luligu

.gitattributes

@@ -1,2 +1,2 @@
-# Auto detect text files and perform LF normalization
-* text=auto
+# Ensure all text files use LF line endings
+* text=auto eol=lf

.github/FUNDING.yml

@@ -1,14 +1,5 @@
-# These are supported funding model platforms
+# .github/FUNDING.yml
 
-github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
-patreon: # Replace with a single Patreon username
-open_collective: # Replace with a single Open Collective username
-ko_fi: # Replace with a single Ko-fi username
-tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
-community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
-liberapay: # Replace with a single Liberapay username
-issuehunt: # Replace with a single IssueHunt username
-lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
-polar: # Replace with a single Polar username
-buy_me_a_coffee: 'luligugithub'
-custom: # ['https://www.buymeacoffee.com/luligugithub']
+# This file is used to specify funding options for the GitHub project.
+
+custom: ['https://www.buymeacoffee.com/luligugithub']

CHANGELOG.md

@@ -2,15 +2,28 @@
 
 All notable changes to this project will be documented in this file.
 
-If you like this project and find it useful, please consider giving it a star on GitHub at https://github.com/Luligu/matterbridge-home-assistant-addon and sponsoring it at https://buymeacoffee.com/luligugithub.
+If you like this project and find it useful, please consider giving it a star on [GitHub](https://github.com/Luligu/matterbridge-home-assistant-addon) and sponsoring it.
 
-If you have problems updating the add-on after installing the new Supervisor, I suggest you uninstall the add-on, remove the add-on and install it fresh. No data will be lost.
-Remeber to enable **Start on boot**, **Auto update** and **Show in sidebar**.
-
-In the future, the add-on will be updated with each important new release of Matterbridge. This is to avoid that a full restart (like for a blackout) or a supervisor update downgrades the Matterbridge version with the latest built image of the add-on.
+<a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/assets/bmc-button.svg" alt="Buy me a coffee" width="120"></a>
 
 # Changelog
 
+## 2026.1.1 - 2026-01-29
+
+The add-on has been entirely redesigned:
+
+- added a configuration page where you can set the binding address for the matterbridge frontend and choose whether to install the latest dev or the latest stable release of matterbridge
+
+![Configuration](https://github.com/user-attachments/assets/5038dba2-438d-4984-bfb7-f76329fe3324)
+
+- added a welcome message with information about the image (from the Home Assistant frontend navigate to Settings -> System -> Logs and select Matterbridge Home Assistant Add-on)
+
+![Welcome message](https://github.com/user-attachments/assets/e4e6c245-125c-4c52-a14d-e720e677f787)
+
+- the add-on always updates matterbridge with the latest stable or the latest dev on restart or rebuild
+
+- the plugins are reinstalled with the latest dev or the latest stable, depending on what was running before the restart or rebuild
+
 ## 2.0.19 - 2026-01-25
 
 - Updated matterbridge to [3.5.1](https://matterbridge.io/CHANGELOG.html#351-2026-01-24).

Dockerfile

@@ -1,18 +1,15 @@
 # Base image
-FROM node:22-bookworm-slim
+FROM node:22-slim
 
 # Set working directory
 WORKDIR /app
 
 # Cache bust: change this value to force a fresh install
-ARG CACHEBUST=20260125
+ARG CACHEBUST=20260129
 
 # Clean the cache to force the latest version of matterbridge and all the plugins
 RUN echo "Cache bust: $CACHEBUST" && npm cache clean -f
 
-# Globally install Matterbridge
-RUN npm install -g matterbridge --omit=dev
-
 # Copy the run script to the container
 COPY run.sh /app/run.sh
 RUN chmod +x /app/run.sh

LICENSE

@@ -1,44 +1,52 @@
-# ![Matterbridge Logo](https://raw.githubusercontent.com/Luligu/matterbridge-home-assistant-addon/main/logo.png)    Matterbridge Home Assistant Add-on
+# <img src="https://matterbridge.io/assets/matterbridge.svg" alt="Matterbridge Logo" width="64px" height="64px"> &nbsp;&nbsp;&nbsp;Matterbridge Home Assistant Add-on
 
 [![npm version](https://img.shields.io/npm/v/matterbridge.svg)](https://www.npmjs.com/package/matterbridge)
 [![npm downloads](https://img.shields.io/npm/dt/matterbridge.svg)](https://www.npmjs.com/package/matterbridge)
-[![Docker Version](https://img.shields.io/docker/v/luligu/matterbridge?label=docker%20version&sort=semver)](https://hub.docker.com/r/luligu/matterbridge)
-[![Docker Pulls](https://img.shields.io/docker/pulls/luligu/matterbridge.svg)](https://hub.docker.com/r/luligu/matterbridge)
+[![Docker Version](https://img.shields.io/docker/v/luligu/matterbridge/latest?label=docker%20version)](https://hub.docker.com/r/luligu/matterbridge)
+[![Docker Pulls](https://img.shields.io/docker/pulls/luligu/matterbridge?label=docker%20pulls)](https://hub.docker.com/r/luligu/matterbridge)
 ![Node.js CI](https://github.com/Luligu/matterbridge/actions/workflows/build.yml/badge.svg)
 ![CodeQL](https://github.com/Luligu/matterbridge/actions/workflows/codeql.yml/badge.svg)
 [![codecov](https://codecov.io/gh/Luligu/matterbridge/branch/main/graph/badge.svg)](https://codecov.io/gh/Luligu/matterbridge)
 
-[![power by](https://img.shields.io/badge/powered%20by-matter--history-blue)](https://www.npmjs.com/package/matter-history)
-[![power by](https://img.shields.io/badge/powered%20by-node--ansi--logger-blue)](https://www.npmjs.com/package/node-ansi-logger)
-[![power by](https://img.shields.io/badge/powered%20by-node--persist--manager-blue)](https://www.npmjs.com/package/node-persist-manager)
+[![powered by](https://img.shields.io/badge/powered%20by-matter--history-blue)](https://www.npmjs.com/package/matter-history)
+[![powered by](https://img.shields.io/badge/powered%20by-node--ansi--logger-blue)](https://www.npmjs.com/package/node-ansi-logger)
+[![powered by](https://img.shields.io/badge/powered%20by-node--persist--manager-blue)](https://www.npmjs.com/package/node-persist-manager)
 
 ---
 
 If you like this project and find it useful, please consider giving it a star on [GitHub](https://github.com/Luligu/matterbridge-home-assistant-addon) and sponsoring it.
 
-<a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/bmc-button.svg" alt="Buy me a coffee" width="120"></a>
+<a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/assets/bmc-button.svg" alt="Buy me a coffee" width="120"></a>
 
 # Matterbridge Home Assistant Add-on
 
 This repository contains the Matterbridge Official Home Assistant Add-on.
 
-It allows you to run Matterbridge as a Home Assistant Add-on.
+It allows you to run [Matterbridge](https://matterbridge.io) as a Home Assistant Add-on.
 
-All Matterbridge features are correctly working in the official add-on (e.g. you can update Matterbridge itself or the plugins without issues).
+All Matterbridge features work correctly in the official add-on (e.g. you can update Matterbridge itself or the plugins without issues).
 
-The Matterbridge storage and the Matterbridge plugins storage persist when you update the Add-on, rebuild or restart it.
+The Matterbridge storage and the Matterbridge plugins storage persist when you update, rebuild or restart the Add-on.
 
-When you build/rebuild the add-on, Matterbridge will reload all plugins that were registered (it takes time so be patient).
+When you build/rebuild the add-on, Matterbridge will reload all plugins that were previously registered (it takes time so be patient).
 
-The Add-on can run on arm64, amd64 archs (armv7 is [deprecated](https://www.home-assistant.io/blog/2025/05/22/deprecating-core-and-supervised-installation-methods-and-32-bit-systems) by Home Assistant). The image is built on Debian 12 (bookworm-slim) with Node.js 22.
+The Add-on can run on arm64, amd64 archs (armv7 arch is [deprecated](https://www.home-assistant.io/blog/2025/05/22/deprecating-core-and-supervised-installation-methods-and-32-bit-systems) by Home Assistant).
+
+The image is built on Debian 12 (bookworm-slim) with Node.js 22.
+
+# Changelogs
+
+[Add-on Changelog](https://github.com/Luligu/matterbridge-home-assistant-addon/blob/main/CHANGELOG.md)
+
+[Matterbridge Changelog](https://matterbridge.io/CHANGELOG.html)
 
 # YouTube
 
-There is this nice video on https://www.youtube.com/watch?v=06zzl7o_IqQ.
+Here’s a nice video: https://www.youtube.com/watch?v=06zzl7o_IqQ.
 
 # Matterbridge Home Assistant plugin
 
-The ideal companion of the add-on is the [Official Matterbridge Home Assistant plugin](https://github.com/Luligu/matterbridge-hass/blob/main/README.md)
+The ideal companion to the add-on is the [Official Matterbridge Home Assistant plugin](https://github.com/Luligu/matterbridge-hass/blob/main/README.md)
 
 ## How to install the add-on
 
@@ -48,7 +56,7 @@ Click here
 
 or from your **Home Assistant** web page, go to **Settings**, select **Add-ons** and click on the **ADD-ON STORE** button.
 
-In the upper right corner click on the **three dots menu**, select **Repositories** and paste this link
+In the upper-right corner, click on the **three dots menu**, select **Repositories** and paste this link
 
 ```
 https://github.com/Luligu/matterbridge-home-assistant-addon
@@ -66,21 +74,27 @@ The Watchdog is not used because Matterbridge always restarts with docker.
 
 Click on **Build** or **Rebuild**.
 
-The building process on a Home Assistant Green takes around 2-3 minute.
+The building process on a Home Assistant Green takes around 2-3 minutes.
 
 Starting Matterbridge the first time after a rebuild takes time too because it will reload all plugins that were already registered.
 
 To open the Matterbridge frontend click on **Open web UI**.
 
 You may be asked to install the Home Assistant Matter Server: confirm the default installation.
 
-This add-on has no configuration.
+The add-on works perfectly with the beta of Matter Server (we use the same matter library).
+
+This add-on has a configuration page where you can set the binding address for the matterbridge frontend and select to install the latest dev or the latest stable release of matterbridge.
+
+![Configuration page](https://github.com/user-attachments/assets/5038dba2-438d-4984-bfb7-f76329fe3324)
 
 ## Supervisor behavior
 
-When the supervisor gets updated, or the host machine (like a Home Assistant Green) makes a full reboot, the supervisor recreates the matterbridge container with the last built image. This can lead to having a very old version of matterbridge and plugins.
+To avoid having any old version of matterbridge and plugins, always update the add-on and rebuild the container when you are prompted to.
 
-To avoid this, update the add-on and rebuild the container when you are prompted to.
+A restart or reboot of Home Assistant will update the Matterbridge version.
+
+A restart or rebuild of the add-on will update the Matterbridge version.
 
 After updating the add-on or rebuilding it, in the log you will see messages like this:
 
@@ -91,30 +105,20 @@ After updating the add-on or rebuilding it, in the log you will see messages lik
 [18:16:18.973] [Matterbridge] Plugin matterbridge-example-dynamic-platform reinstalled.
 ```
 
-This is normal in this context and means that Matterbridge detected that in the new image the plugins are not present and will install them from npm using the latest version.
+This is normal in this context and means that Matterbridge detected that the plugins are not present in the newly created container and will install them from npm using the latest stable version or the latest dev version.
 
 If you were using a plugin installed from a tarball, you need to reinstall it manually.
 
-If you were using a dev version of plugin, it will be reinstalled with the latest dev version.
-
-## Home Assistant restart and reboot
-
-A simple restart of Home Assistant doesn't change the Matterbridge version.
-
-A restart (more correctly a recreate) of the Add-on will recreate the image with the Matterbridge version it was originally built with. So it can be an **old version**.
-
-A full reboot (or a power outage) has the effect that the original add-on image is loaded with the Matterbridge version it was originally built with. So it can be an **old version**.
-
-In this cases rebuild the add-on to get the latest versions of Matterbridge and plugins.
+If you were using a dev version of a plugin, it will be reinstalled with the latest dev version.
 
-## How to configure the mdns
+## How to configure the Matter mDNS
 
-Since Home Assistant exposes a lot of interfaces to the containers, is mandatory to set the matter mdns interface in the Matterbridge Settings page.
+Since Home Assistant exposes a lot of interfaces to the containers, it is mandatory to set the **matter mdns interface** in the Matterbridge Settings page.
 
-![image](https://github.com/user-attachments/assets/bdaa91ea-4c87-4aeb-9cec-dd99be0ec8dc)
+![Matterbridge settings](https://github.com/user-attachments/assets/50f89b9c-f450-4702-95cf-ee5359e2af31)
 
-You can get the correct interface name from the Network page in the settings of Home Assistant.
+You can get the correct interface name from the **Network Adapter** panel. From the Home Assistant frontend navigate to Settings -> System -> Network.
 
-In this case the correct name is end0.
+In this case the correct name is end0 but your system can have a different interface.
 
-![image](https://github.com/user-attachments/assets/1c09c1a4-41b5-41ed-924e-1f1086140b50)
+![Network configuration](https://github.com/user-attachments/assets/3217ed7c-f5ae-49d9-8155-10966fd05609)

README.md

@@ -1,25 +1,30 @@
 {
     "name": "Matterbridge Home Assistant Add-on",
-    "version": "2.0.19",
+    "version": "2026.1.1",
     "slug": "matterbridge",
-    "hostname": "matterbridge",
     "description": "Official Matterbridge Home Assistant Add-on",
     "url": "https://github.com/Luligu/matterbridge-home-assistant-addon",
     "changelog": "https://github.com/Luligu/matterbridge-home-assistant-addon/blob/main/CHANGELOG.md",
-    "startup": "application",
-    "boot": "auto",
+    "arch": [
+        "amd64",
+        "aarch64"
+    ],
+    "panel_title": "Matterbridge",
+    "panel_icon": "mdi:bridge",
     "ingress": true,
     "ingress_port": 8283,
-    "panel_icon": "mdi:bridge",
-    "panel_title": "Matterbridge",
     "map": [
         "addons:rw",
         "share:rw"
     ],
-    "arch": [
-        "amd64",
-        "aarch64"
-    ],
     "host_network": true,
-    "restart": "always"
+    "restart": "always",
+    "schema": {
+        "frontend_bind": "str",
+        "branch": "list(main|dev)"
+    },
+    "options": {
+        "frontend_bind": "0.0.0.0",
+        "branch": "main"
+    }
 }

config.json

@@ -2,10 +2,5 @@
     "name": "Matterbridge Home Assistant Add-on",
     "url": "https://github.com/Luligu/matterbridge-home-assistant-addon",
     "maintainer": "https://github.com/Luligu",
-    "description": "Official Home Assistant Add-on for Matterbridge",
-    "arch": [
-        "amd64",
-        "aarch64",
-        "armv7"
-    ]
-}
+    "description": "Official Matterbridge Home Assistant Add-on"
+}

repository.json

@@ -3,21 +3,66 @@
 # Define the base directory for Matterbridge
 HOME_DIR=/addons/matterbridge
 
+# Read addon options from /data/options.json (written by Supervisor)
+# If a key is missing, fall back to defaults.
+FRONTEND_BIND="$(node -p "try{require('/data/options.json').frontend_bind ?? '0.0.0.0'}catch(e){'0.0.0.0'}")"
+BRANCH="$(node -p "try{require('/data/options.json').branch ?? 'main'}catch(e){'main'}")"
+
 # Define the subdirectories for Matterbridge
 MATTERBRIDGE_PLUGINS=$HOME_DIR/Matterbridge   # For matterbridge plugins
 MATTERBRIDGE_STORAGE=$HOME_DIR/.matterbridge  # For matterbridge storage
 MATTERBRIDGE_CERT=$HOME_DIR/.mattercert       # For matterbridge certification
 
+# Welcome message
+echo " "
+echo " "
+echo "Welcome to the Matterbridge Home Assistant Add-on"
+echo " "
+DISTRO=$(awk -F= '/^PRETTY_NAME=/{gsub(/"/, "", $2); print $2}' /etc/os-release)
+CODENAME=$(awk -F= '/^VERSION_CODENAME=/{print $2}' /etc/os-release)
+echo "🖥️ Distro: $DISTRO ($CODENAME)"
+echo "🧱 Architecture: $(uname -m)"
+echo "🧩 Kernel Version: $(uname -r)"
+echo "🟢 Node.js version: $(node -v)"
+echo "🟣 Npm version: $(npm -v)"
+echo "👤 Hostname: $(hostname)"
+echo "👤 User: $(whoami)"
+echo "📅 Date: $(date)"
+echo " "
+
 # Create directories if they don't exist
+echo "Creating matterbridge directories..."
 mkdir -p $HOME_DIR
 mkdir -p $MATTERBRIDGE_PLUGINS
 mkdir -p $MATTERBRIDGE_STORAGE
 mkdir -p $MATTERBRIDGE_CERT
 
+# Install Matterbridge based on selected branch
+case "$BRANCH" in
+  dev)
+    echo "Branch = dev → installing matterbridge@dev from npm..."
+    echo "This can take up to 3 minute on a Home Assistant Green..."
+    npm install matterbridge@dev --no-fund --no-audit --global --omit=dev
+    ;;
+  main|*)
+    echo "Branch = main → installing matterbridge@latest from npm..."
+    echo "This can take up to 3 minute on a Home Assistant Green..."
+    npm install matterbridge --no-fund --no-audit --global --omit=dev
+    ;;
+esac
+
+# Base args
+ARGS="--docker --homedir $HOME_DIR"
+
+# Add frontend bind
+if [ -n "$FRONTEND_BIND" ]; then
+  ARGS="$ARGS --bind $FRONTEND_BIND"
+fi
+
 # Start Matterbridge in a loop to handle restarts internally in the same container
 while true; do
-    echo "Starting Matterbridge..."
-    matterbridge -docker -ingress -homedir $HOME_DIR
+    echo "Starting Matterbridge with args: $ARGS"
+    matterbridge $ARGS
     echo "Matterbridge process exited. Restarting in 2 seconds..."
     sleep 2
-done
+done