What is Matterbridge?

Matterbridge is a plugin manager for the Matter smart home standard. It runs a Matter bridge that connects to platforms like Apple Home, Google Home, Alexa, SmartThings, and Home Assistant. Through plugins, it brings non-Matter hardware — such as Shelly relays, Zigbee2MQTT devices, Somfy blinds, Home Assistant entities, webhooks, BTHome sensors, and iRobot vacuums — into the Matter fabric. The program works on Linux, macOS, and Windows with modest resources (512 MB RAM). A built-in web UI on port 8283 lets you manage plugins, view devices, and inspect logs. You can deploy it via Docker, Docker Compose, a global npm install, systemd, launchctl, Windows Task Scheduler, Podman, or behind nginx. Two operating modes exist: bridge mode presents one bridge device, while childbridge mode makes each plugin its own bridge. The codebase is Apache-2.0 licensed and maintains a growing set of official and community plugins.

Should you self-host Matterbridge?

Matterbridge scores 59/100 on selfhost.directory (how scoring works) and ranks #34 of 104 in Home Automation. It has 997 GitHub stars.

It shipped 10 stable releases in the past year. The latest, 3.11.0, came out on 23 October 2026. New versions land roughly every 7 days.

Setup is moderate: expect some configuration beyond a single command. An official Docker image is available. It is Apache-2.0-licensed and written mostly in Typescript.

Its closest alternative on selfhost.directory is Home Assistant (91/100, 91 794 stars). It scores higher overall, so compare the two before you pick. See Matterbridge vs Home Assistant side by side.

Features

Backup and Restore
Bridge mode
Childbridge mode
Health Checks
HTTPS/mTLS support
IPv6 Support
mDNS discovery
Multi-Instance Support
Multi-platform
Plugin management via frontend
Plugin System
Web frontend

How to configure Matterbridge

--addAdd a plugin by path or name
Add a plugin by path or name
--bindBind frontend to a specific address (default: all IPv4 and IPv6)
Bind frontend to a specific address (default: all IPv4 and IPv6)
--bridgeForce Matterbridge to load in bridge mode (single bridge device)
Force Matterbridge to load in bridge mode (single bridge device)
--childbridgeForce Matterbridge to load in childbridge mode (each plugin as separate bridge)
Force Matterbridge to load in childbridge mode (each plugin as separate bridge)
--delayDelay startup on first boot after system reboot (5 min window)
Delay startup on first boot after system reboot (5 min window)
--disableDisable a registered plugin
Disable a registered plugin
--dockerRun in Docker mode (required when overriding Docker command)
Run in Docker mode (required when overriding Docker command)
--enableEnable a registered plugin
Enable a registered plugin
--factoryresetFactory reset - clear all storage and unregister plugins
Factory reset - clear all storage and unregister plugins
--fixed_delayAlways delay startup (for docker compose race conditions)
Always delay startup (for docker compose race conditions)
--frontend8283Specify frontend port number (default: 8283)
Specify frontend port number (default: 8283)
--helpShow command line help
Show command line help
--mtlsEnable mutual TLS (client certificate authentication)
Enable mutual TLS (client certificate authentication)
--no-ansiDisable ANSI colors in output
Disable ANSI colors in output
--port5540Starting Matter port (default: 5540)
Starting Matter port (default: 5540)
--profileProfile name for multi-instance setups
Profile name for multi-instance setups
--removeRemove a plugin by path or name
Remove a plugin by path or name
--resetReset commissioning info for bridge or specific plugin
Reset commissioning info for bridge or specific plugin
--sslEnable HTTPS for frontend using cert.pem/key.pem
Enable HTTPS for frontend using cert.pem/key.pem
--tlsAlias for --ssl
Alias for --ssl
--versionShow current version
Show current version

FAQ

Why does Apple Home show session errors after restart?

The controller may still use a session from the previous connection. This is normal and resolves automatically after some time.

How to disable Restart matterbridge and update matterbridge?

In the frontend settings page, set virtual devices to Disabled.

How to use regex search in the Log page?

Start and end search string with / (e.g., /^error/ matches lines starting with error, /timeout/ matches timeout anywhere, /disconnected$/ matches lines ending with disconnected).

How to avoid race condition on start/restart?

Use --delay parameter for boot race conditions (applies only in first 5 minutes after reboot) or --fixed_delay for Docker Compose (always delays startup).

How to pair a second controller?

Either use the first controller's share/pairing mode to get a new QR code, or use the Matterbridge frontend's 'Turn on pairing mode' in the Paired fabrics panel.

How to send debug log files?

Enable debug mode in the frontend settings, wait a few minutes for logs to accumulate, then use the three-dots menu to download matterbridge.log and matter.log files.

How to enable HTTPS for the frontend?

Place your certificates (cert.pem, key.pem, optional ca.pem) or PKCS#12 certificate (cert.p12 with cert.pass) in the .matterbridge/certs directory, then run matterbridge with --ssl (or --tls) parameter. For mutual TLS, use --mtls instead.