Matterbridge Home Assistant Add-on

The Matterbridge Home Assistant Application (formerly known as an add-on) enables running Matterbridge within the Home Assistant Supervisor environment.

Key features include:

• Full Feature Parity: All Matterbridge features are supported within the application.
• Persistent Storage: Matterbridge storage and plugin storage persist through application updates, restarts, or uninstalls/reinstalls.
• Automatic Plugin Reloading: Upon starting or restarting, Matterbridge automatically reloads all previously registered plugins (note: this process may take some time).
• Architecture Support: Compatible with arm64 and amd64 architectures. Note that armv7 is deprecated and not supported.
• Runtime Environment: The luligu/matterbridge:s6-rc image is built on Debian 13 (trixie-slim) using Node.js 24 and utilizes the s6-rc overlay system.

When you update or restart the Matterbridge add-on, Matterbridge may automatically reinstall plugins from npm. This is expected behavior because plugins are not persisted within the container image itself, though the Matterbridge storage and plugin registration data are preserved.

If you see logs indicating a plugin is being reinstalled, it is working as intended:

[18:16:13.122] [Matterbridge] Error parsing plugin matterbridge-example-accessory-platform. Trying to reinstall it from npm...
[18:16:16.167] [Matterbridge] Plugin matterbridge-example-accessory-platform reinstalled.

Important Considerations:

• Tarball Plugins: If you installed a plugin manually via a .tar.gz file, you must reinstall it manually after an update.
• Dev Versions: If you were using a development version of a plugin, it will be reinstalled as the latest available dev version.
• Updates: Always update the add-on when prompted to ensure you are running the latest version of Matterbridge and its dependencies.

To install the Matterbridge application as a Home Assistant add-on, follow these steps:

1. Open your Home Assistant instance.
2. Navigate to Settings -> Add-ons (or Apps in some versions).
3. Click the Install app button (or the three dots menu in the upper-right corner).
4. Select Repositories.
5. Paste the following URL and click ADD: https://github.com/Luligu/matterbridge-home-assistant-addon
6. Locate the Matterbridge app in the add-on store and click Install.
7. Once installed, it is recommended to enable Start on boot, Autoupdate, and Show in sidebar.
8. Click Start.

Note: The initial startup can take several minutes (approximately 2-3 minutes on Home Assistant Green) because Matterbridge reloads and reinstalls all previously registered plugins.

To access the interface, click Open Web UI or use the Matterbridge icon in the sidebar. If prompted to install the Home Assistant Matter Server, confirm the default installation.