Installation
matter-bridge is one static Linux binary. Pick one of the ways below, then configure it.
Release binaries
Section titled “Release binaries”Each release has
statically linked binaries with no runtime dependencies, and a SHA256SUMS
file:
| File | For |
|---|---|
matter-bridge-x86_64-linux-musl |
PCs and servers |
matter-bridge-aarch64-linux-musl |
Raspberry Pi 3, 4, 5 and other 64-bit ARM boards with a 64-bit OS |
matter-bridge-mipsel-linux-musl |
MT7621 and MT7628 routers (little-endian MIPS) |
Download, verify and install (this is the README’s quick start; CI runs it):
VERSION=0.1.0ARCH=$(uname -m) # x86_64 or aarch64BASE=https://github.com/pulzar-net/matter-bridge/releases/download/v$VERSIONcurl -fsSLO "$BASE/matter-bridge-$ARCH-linux-musl"curl -fsSLO "$BASE/SHA256SUMS"sha256sum --check --ignore-missing SHA256SUMSsudo install -m 0755 "matter-bridge-$ARCH-linux-musl" /usr/local/bin/matter-bridgematter-bridge --versionFrom source
Section titled “From source”With Rust 1.92 or newer:
cargo install --locked --git https://github.com/pulzar-net/matter-bridge matter-bridgeOr from a clone, cargo build --release -p matter-bridge. No system
packages are required. Bluetooth commissioning (feature ble, on by
default) is built in; --no-default-features leaves it out.
Network requirements
Section titled “Network requirements”Matter runs over IPv6 on the local network, and finds devices with DNS-SD (mDNS):
- the machine needs IPv6 on the interface that reaches the devices, with an
address beyond link-local (a ULA or global address, as most home networks
with a Thread border router or IPv6 router have); set
matter.interfacewhen it has several; - UDP port
matter.port(5541 by default) and mDNS (UDP 5353) must not be blocked by a firewall; - mDNS does not cross routers or VLANs without a reflector; keep the bridge on the devices’ network.
As a systemd service
Section titled “As a systemd service”The repository has a hardened unit in
contrib/systemd/matter-bridge.service.
It runs the bridge as an unprivileged dynamic user and keeps the fabric in
/var/lib/matter-bridge.
sudo mkdir -p /etc/matter-bridgesudo cp config.example.toml /etc/matter-bridge/config.toml # then edit itsudo install -m 0644 contrib/systemd/matter-bridge.service /etc/systemd/system/sudo systemctl daemon-reloadsudo systemctl enable --now matter-bridgejournalctl -u matter-bridge -fFor Bluetooth commissioning, the unit needs
CAP_NET_ADMIN and AF_BLUETOOTH; the commented lines in it show how.
On OpenWrt
Section titled “On OpenWrt”Needs real hardware: this procedure has not been tested on a router yet.
The mipsel binary runs on MT7621 and MT7628 routers with OpenWrt.
- Copy the binary to
/usr/bin/matter-bridgeand make it executable. - Write
/etc/matter-bridge/config.toml. Set[data] dirto a directory on flash, such as/etc/matter-bridge/data:/varis in RAM on OpenWrt, and the fabric’s keys would be lost at reboot, orphaning every device. - Allow UDP 5541 and 5353 from the LAN zone in the firewall.
- Install the procd script from
contrib/openwrt/matter-bridge.init:
cp matter-bridge.init /etc/init.d/matter-bridgechmod +x /etc/init.d/matter-bridge/etc/init.d/matter-bridge enable/etc/init.d/matter-bridge startlogread -f -e matter-bridgeCommand line
Section titled “Command line”matter-bridge [--config FILE] run the bridgematter-bridge parse CODE say what a QR code or manual pairing code holdsmatter-bridge --versionFILE defaults to /etc/matter-bridge/config.toml; without it every
default applies. parse prints the code’s discriminator, vendor and product
ids and how the device can be found, as JSON (never the passcode).
The log goes to standard error. RUST_LOG sets its level, for example
RUST_LOG=debug.