<img src="https://matterbridge.io/assets/matterbridge.svg" alt="Matterbridge Logo" width="64px" height="64px">   Matterbridge

---

Matterbridge is a Matter plugin manager.

It creates a Matter device (of type bridge) that can be paired with any ecosystem, such as Apple Home, Google Home, Amazon Alexa, Home Assistant, or any other platform supporting Matter.

You don't need a hub or a dedicated new machine.

No complex setup: just copy paste the installation scripts (available for Docker, Nginx, Linux systemctl and macOS launchctl).

Matterbridge is lightweight and also runs on slow Linux machines with as little as 512MB of memory.

It is fully supported on Linux, macOS, and Windows.

It allows you to have all your Matter devices up and running in a couple of minutes without having to deal with the pairing process for each individual device.

Developers can focus solely on device development by extending the provided classes.

Simply pair Matterbridge once, and it will load all your registered plugins.

This project aims to enable porting Homebridge plugins to Matterbridge plugins without having to recode everything (Development).

The easiest way to start create a new plugin is to clone the Matterbridge Plugin Template which has Dev Container support for instant development environment and all tools and extensions (like Node.js, npm, TypeScript, ESLint, Prettier, Jest and Vitest) already loaded and configured.

If you like this project and find it useful, please consider giving it a star on GitHub and sponsoring it.

<a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/assets/bmc-button.svg" alt="Buy me a coffee" width="120"></a>

Acknowledgements

The project is build on top of matter.js.

A special thanks to Apollon77 for his incredible work.

Discord

Join us in the Matterbridge Discord group created by Tamer.

Videos

https://www.youtube.com/watch?v=goNB9Cgh_Fk

https://www.youtube.com/watch?v=06zzl7o_IqQ

Reviews

https://www.matteralpha.com/how-to/how-to-configure-an-open-source-matter-bridge-at-home

Press

https://matter-smarthome.de/en/interview/an-alternative-to-the-official-matter-sdk/

https://blog.adafruit.com/2025/11/03/matterbridge-a-matter-plugin-manager/

Prerequisites

To run Matterbridge, you need either a Node.js environment or Docker installed on your system.

If you don't have Node.js already installed, please use this method to install it on a Debian system: https://github.com/nodesource/distributions.

The supported versions of Node.js are >=20.19.0, >=22.13.0, and 24. Please install Node.js 24 LTS. Don't use Node.js Current; always use the Node.js LTS releases.

Node.js 21, 23, 25, like all odd-numbered versions, are not supported.

To verify which Node.js version is currently LTS (Active), check Node.js Releases.

Nvm is a development tool and is not supported for production.

If you don't have Docker already installed, please use this method to install Docker Engine on a Debian system: https://docs.docker.com/engine/install.

If you don't have Docker already installed, please use this method to install Docker Desktop on Windows or macOS: https://docs.docker.com/get-started/introduction/get-docker-desktop/.

After that, follow the guidelines for the Docker configurations.

I suggest using Docker for its simplicity.

Since Matter is designed as "a universal IPv6-based communication protocol for smart home devices" (per the Matter specifications), IPv6 must be enabled on your local network (LAN).

Important: You only need IPv6 on your local network - it doesn't matter if your internet provider doesn't provide IPv6 on the internet side (WAN).

Avoid VLANs, VMs, and firewalls that block communication between the controllers and Matterbridge.

To pair Matterbridge, you need a Matter-enabled controller (Apple Home, SmartThings, Google Home, Alexa, Home Assistant, etc.).

Installation with Node.Js

Follow these steps to install Matterbridge:

npm install -g matterbridge --omit=dev

on Linux or macOS you may need the necessary permissions:

sudo npm install -g matterbridge --omit=dev

Test the installation with:

matterbridge

Now it is possible to open the frontend at the link provided in the log (e.g. http://MATTERBRIDGE-IPV4-ADDRESS:8283).

You can then change the bridge mode and other parameters from the frontend.

Usage

mode bridge

matterbridge --bridge

This force Matterbridge to load in bridge mode.

Matterbridge only exposes itself, and you have to pair it scanning the QR code shown in the frontend or in the console.

mode childbridge

matterbridge --childbridge

This force Matterbridge to load in childbridge mode.

Matterbridge exposes each registered plugins, and you have to pair each one by scanning the QR code shown in the frontend or in the console.

Use matterbridge --help to see the command line syntax

matterbridge --help

Use matterbridge --version to see the current version

matterbridge --version

Frontend

Matterbridge has a frontend available on IPv4 http://localhost:8283 or http://MATTERBIDGE-IPV4-ADDRESS:8283 and IPv6 http://[::1]:8283 or http://[MATTERBIDGE-IPV6-ADDRESS]:8283.

You can change the default port by adding the frontend parameter when you run it.

Here's how to specify a different port number:

matterbridge --frontend [port number]

The frontend binds, by default, to all IPv4 and IPv6 addresses. You can override this and bind to a specific address:

matterbridge --bind [address]

To use the frontend with SSL, see below.

From the frontend you can do all operations in an easy way.

Home page

Devices page

Logs page

Config editor

Advanced configurations

Run matterbridge as a daemon with systemctl (Linux only)

Traditional configuration: configuration

or with local global node_modules and npm cache (no sudo required): configuration

or with user matterbridge and with private global node_modules and npm cache (no sudo required): configuration

Run matterbridge as a system service with launchctl (macOS only)

Launchctl configuration

Run matterbridge with docker and docker compose

Docker configuration

Run matterbridge with podman

Podman configuration

Run matterbridge with nginx

Nginx configuration

Run matterbridge as an home assistant add-on with the official add-on

Home assistant application (formerly known as add-on) configuration

Other Home Assistant Community Add-ons

The other Home Assistant Community Add-ons and plugins are not verified to work with Matterbridge. I strongly advise against using them. If you do use them and encounter an issue (which is likely because some do not meet the Matterbridge guidelines), please do not open an issue in any of the Matterbridge repositories.

Development

Development

Plugins

Shelly

<a href="https://github.com/Luligu/matterbridge-shelly"> <img src="./screenshots/Shelly.svg" alt="Shelly plugin logo" width="100" /> </a>

Matterbridge shelly plugin allows you to expose all Shelly Gen 1, Gen 2, Gen 3 and Gen 4 and BLU devices to Matter.

Features:

• Shellies are autom