Skip to content

Configuration

matter-bridge reads one TOML file, /etc/matter-bridge/config.toml unless --config FILE names another. Every key has a default, and without the file every default applies. A typical file only names the broker:

[mqtt]
host = "broker.lan"

Unknown keys and wrong types are errors, so a typo stops the bridge at startup. The configuration reference lists every key; it is generated from the code, so it is always current.

A JSON Schema generated from the same code lets an editor with TOML schema support (Taplo, or VS Code’s Even Better TOML) complete and check the file. Point it at the schema with a first line of:

#:schema https://pulzar-net.github.io/matter-bridge/config.schema.json
Table What it sets
[mqtt] broker host and port, user name, password file, client id, base topic, keep-alive
[homeassistant] discovery on or off, the discovery prefix, Home Assistant’s status topic
[matter] the UDP port, the mDNS interface, the fabric id of a new fabric, the vendor id, attestation policy, subscription renewal, the discovery timeout; the Bluetooth controller and a Thread dataset source
[data] the data directory

config.example.toml in the repository sets every key to its default, with comments. CI checks that it parses.

# matter-bridge configuration. Every section is optional.
[mqtt]
host = "localhost"
port = 1883
# username = "matter"
# password_file = "/etc/matter-bridge/mqtt-password"
client_id = "matter-bridge"
base_topic = "matter"
keepalive = 30
[homeassistant]
enabled = true
discovery_prefix = "homeassistant"
status_topic = "homeassistant/status"
[matter]
# UDP port for Matter traffic (5540 is a device's; a controller uses another).
port = 5541
# Network interface for mDNS; the first with an IPv6 address if unset.
# interface = "eth0"
# Fabric id of a new fabric; random if unset. Ignored once the fabric exists.
# fabric_id = 1
# Vendor id the controller administers nodes as. 0xFFF1 is the CSA's test
# vendor id, for controllers that are not certified.
vendor_id = 0xFFF1
# Commission devices without verifying their attestation (DAC chain and
# certification declaration). Verification is not implemented yet, so this
# must stay on to commission anything.
allow_unverified_attestation = true
# Longest a subscription may stay silent before it is renewed, seconds.
max_report_interval = 60
# How long to look for a device to commission, seconds.
discovery_timeout = 30
# Bluetooth controller for commissioning devices over BLE: "hci0" (Linux HCI
# user channel; stop BlueZ on it first) or "tcp:host:port" (H4 over TCP).
# bluetooth = "hci0"
# A Thread border router's active dataset, for Thread devices (read when a
# device is commissioned; never stored).
# thread_dataset_url = "http://127.0.0.1:8081/node/dataset/active"
[data]
# The fabric (CA keys), the controller's identity and the node store. Keep it
# private: it holds the fabric's keys.
dir = "/var/lib/matter-bridge"

[data] dir (default /var/lib/matter-bridge) holds:

What Why it matters
the fabric’s CA: root and intermediate keys and certificates, the IPK, the next node id anyone with it can add nodes to the fabric and control every device on it
the controller’s identity: its node id, operational key and certificate
nodes.json: each node’s identity and interview rebuilt by interviewing again if lost

The files are written atomically and are readable by their owner only. Back up the whole directory, and protect the backups like a password. Without it, the bridge cannot reach its devices: they would have to be factory reset and commissioned again.

The bridge logs to standard error at info unless RUST_LOG says otherwise (debug, or per target such as info,matter_controller=debug). Wi-Fi passphrases and Thread datasets given at commissioning are never logged or stored.