Quick start
git clone https://github.com/ctrlpi/matter-bridge.git cd matter-bridge npm install cp config.json.example config.json # name your agents and devices node bridge.js # prints Matter pairing codes (also saved to matter.json)
Commission the bridge from any Matter controller, the Home app, Google Home, Alexa, or Home Assistant, and every declared device appears as a bridged endpoint. Matter state persists in .matter/; node bridge.js -c resets pairing.
Declare devices, not code
The config schema is shared with homekit-bridge, same agents list, same device vocabulary:
{
"name": "MyBridge",
"agents": [{ "name": "garage", "ip": "192.168.1.20", "api-key": "..." }],
"devices": [
{ "id": "light1", "name": "Porch Light", "type": "light", "gpio": 17, "agent": "garage" },
{ "id": "lock1", "name": "Front Door", "type": "lock", "gpio": 27, "agent": "garage" },
{ "id": "door1", "name": "Garage Contact", "type": "contact", "gpio": 22, "agent": "garage", "pull": "up" }
]
}
What it exposes
- Outputs: lights, fans, plugs, shades, water valves, and door locks
- Input sensors: contact, motion, occupancy, smoke/CO, water leak, and generic switches, delivered in real time via each agent's webhook to the built-in listener
- Relay-friendly: active-low logic with the
reversedflag, applied by the bridge before each REST write - Pulse & auto-off: temporary activation for any output, using the agent's native auto-revert
- Platform independent: no local GPIO; runs the same on a Raspberry Pi, macOS, or Linux
🍏Apple-only home? The homekit-bridge sibling pairs natively over HAP with richer native categories (a real GarageDoorOpener, stateless buttons), and both bridges can run on one host.
In the family
Drives any mix of raspberry-pi-gpio-api and pico-gpio-api agents over their shared REST wire format, the agents do the electrical work, the bridge speaks Matter.