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.

This repository contains the Matterbridge Official Home Assistant Add-on.

It allows you to run Matterbridge 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).

The Matterbridge storage and the Matterbridge plugins storage persist when you update the Add-on, rebuild or restart it.

When you build/rebuild the add-on, Matterbridge will reload all plugins that were registered (it takes time so be patient).

The Add-on can run on arm64, amd64 armv7 archs. The image is built on Debian 12 (bookworm-slim) with Node.js 22.

The ideal companion of the add-on is the Official Matterbridge Home Assistant plugin

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

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

then click on ADD.

You should now see your Matterbridge add-on in the add-on store and be able to INSTALL it.

Be patient because it can take a few minutes.

Enable Start on boot, Auto update and Show in sidebar.

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 1 minute.

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.

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 this, update the add-on and rebuild the container when you are prompted to.

After updating the add-on or rebuilding it, in the log you will see messages like this:

[09:59:37.162] [PluginManager] Failed to parse package.json of plugin matterbridge-example-dynamic-platform: ENOENT: no such file or directory, open '/usr/local/lib/node_modules/matterbridge-example-dynamic-platform/package.json'

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:

[09:59:37.163] [Matterbridge] Error parsing plugin matterbridge-example-dynamic-platform. Trying to reinstall it from npm.
[09:59:40.762] [Matterbridge] Package matterbridge-example-dynamic-platform   installed correctly
[09:59:40.768] [Matterbridge] Plugin matterbridge-example-dynamic-platform reinstalled.

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, you need to reinstall the dev version manually.

A simple restart of Home Assistant doesn't change the Matterbridge 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 case rebuild the add-on to get the latest verrsions of Matterbridge and plugins.

Since Home Assistant exposes a lot of interfaces to the containers, is better to set the matter mdns interface in the Matterbridge Settings page.

You can get the correct interface name from the Network page in the settings of Home Assistant.

In this case the correct name is end0.