Creating your first Matter bridge

Decide the bridge boundaries before you press Create

A standard Matter bridge is one Matter node that holds an aggregator and several device endpoints. Decide first which set of HA entities it serves and which external controllers. Stable 2.0.55 supports several bridges, and multi-fabric on a single bridge; but controller device type support, product maturity and the Stable release channel are three different facts.

For your first bridge, pick a small number of devices that are not safety-critical and are easy to watch. A large bridge can be unstable on some controllers, and the interface will suggest splitting it when that is needed. You can split by area, by domain, or around a controller-specific workaround; no single approach suits every home.

All ten Stable 2.0.55 templates

A template is a starting point with the filter, icon and some feature flags prefilled; it is not a guarantee of controller support. After you pick a template in the Wizard you still go through the controller profile and the review; the full Create Bridge page can also start from a template, which you then edit in the form or in JSON. The ten templates are:

Security & Locks is only a standard entity filter template, and not the Security Plugin, which Stable still marks as experimental. Similar names do not mean the same feature. The Google Home Optimized wildcard covers "all devices" by default, which may be wider than you expect; after choosing the template, narrow it in the full editor, or switch to an area or a label instead.

Build a small standard bridge with the Bridge Wizard

The Wizard has six stages: Template, Controller, Bridge Info, Entity Filter, Feature Flags, Review. Template and Controller can be skipped; Bridge name is required; the filter must not be left as an empty include; Review shows a configuration summary and the network preflight, and ends with Create Bridge or Add Another.

1. Open the Wizard and pick a template

   On the Dashboard, press "Bridge Wizard". Choose whichever of the ten templates is closest to your goal, or press Skip Template and start from a blank configuration. Do not infer that every device is supported just because a controller's name appears in the template name.

2. Pick a controller profile

   Choose one of Apple Home, Google Home, Amazon Alexa or Multi-Controller, or skip. A profile only merges in recommended feature flags; it does not commission anything for you and it does not verify device types.

3. Fill in Bridge Info

   Enter a name you can recognize that carries no sensitive location information. Keep the next free port the Wizard fetched for you; if the target is Alexa, plan 5540 for your first bridge. Leave Server Mode unchecked on an ordinary bridge.

4. Set an explicit filter

   The Wizard lets you edit Pattern, Domain, Area, Label and exclude only when you chose Skip Template; with any non-Server Mode template, the template filter is read-only inside the Wizard and you change it in the full editor after the bridge exists. A blank configuration can use Pattern, Domain, Area or Label. For a first test, pick a single area or domain, or an explicit pattern; add an exclude for entities you do not need to expose. Label needs at least one selection, and the other types need at least one value.

5. Review the four Wizard flags

   Adjust Auto Compose Devices, Auto Force Sync, Invert Cover Direction and Include Hidden Entities to suit what you need. Flags the controller profile already recommends are merged into the display; do not switch them all on in pursuit of "the most features".

6. Review and preflight

   Cross-check the name, port, include, exclude, Server Mode and flags. Expand the network remediation and deal with every fail and warn first; when the Alexa port warning is showing, go back to Bridge Info and fix it.

7. Create or Add Another

   Press Create Bridge only when the summary and the preflight match your plan. In v2.0.55, Add Another resets the form even when the create failed, so go back to Bridges every time and confirm the bridge really exists; the next suggested port is derived from the nextPort fetched at the start plus the number queued, and is not necessarily the port you typed by hand plus one.

The four controller profiles are recommended settings, not a support matrix

A profile's flags override and merge into the template's current values. If you deselect the profile, the Wizard does not restore every earlier flag; read the final result on Review. For workarounds that exclude each other, such as Alexa-only brightness behavior, isolate them on a controller-specific bridge instead of assuming Multi-Controller can satisfy both at once.

Empty filters, the label guard and remediation

In the backend semantics, an empty include can mean include everything, so the Wizard blocks an accidentally empty list outright. When Pattern, Domain or Area has no value it shows "enter at least one value"; when no label is selected it tells you to select at least one label or change the type. Switching filter type also clears pattern strings that no longer apply, so a leftover value cannot leak into the Domain or Area matcher.

Server Mode forces an entity ID pattern, the screen warns you to narrow it to exactly one entity, and the first entity is the primary. The upstream bridge schema allows one Server Mode node up to ten device endpoints, but more than one is experimental-in-Stable; the Wizard's "exactly one" guidance is the safer product path.

The full Manual Editor shows the Filter Preview and reminds you how labels are meant to be used. The preview is an important guard before you create: confirm the expected entity count, the vacuum, large-match and unsupported-domain warnings, and whether a sensitive device slipped in. If the result is zero, do not blank the include and hope for the best; go back to the area, label or pattern identifiers and fix them one at a time.

Automatic ports, network preflight and Alexa 5540

The Wizard calls api/matter/next-port when it opens, and falls back to 5540 if that fails. The Manual Create Page scans the used ports from 5540 upwards and takes the first free port. Area Setup fetches the next port once and then increments it for every area it creates. Every bridge port has to be unique; the full editor blocks Save when the port is already used by another bridge.

PreflightPanel calls api/network and sorts the diagnostic results into passed, warnings and failed. Every problem expands into a How to fix: where an add-on option exists, it shows that option and the matching container flag, and reminds you to restart the add-on after changing a start option; everything else has to be fixed on the host or the network. Preflight is advisory and does not block Create on its own, so treating a fail as something to fix first is your own decision.

1. Allocate 5540 first

   If any bridge is meant for Alexa, create it first and give it 5540. Let every other bridge take the automatic free port.

2. Read the pass/warn/fail summary

   Wait for the network preflight to finish on the Wizard's Review stage. No data, or a server you cannot reach, must not be read as everything passing.

3. Expand every How to fix

   Use the advice to tell an add-on option, a container flag and a host or network problem apart; do not copy an example interface name blindly.

4. Rerun Review after you fix it

   When a start option is involved, restart the service completely, then go back to the Wizard and fetch the diagnostics again. Create only once you confirm the errors are gone.

Area Setup: create several bridges in bulk by HA area

Area Setup loads from api/matter/areas/summary every area holding at least one entity that is "enabled, not currently unavailable, and in a domain the API supports"; the entity count on each card uses the same eligibility rule, and up to four main domains are shown. You can Select All or Clear, tick areas one by one, and pick one of the four controller profiles. Areas that fail the eligibility rule are left out.

On create, each area becomes one area matcher with no exclude, with auto battery/humidity/pressure mapping enabled by default, and then the controller profile flags merged in. The program creates them in order, with ports counting up from the next free port; even if one fails, the remaining areas still go ahead, and the end shows separate success and error entries plus a partial summary.

1. Tidy your Home Assistant areas first

   In HA, confirm that the entities you want to expose are in the right area, and that the area holds no sensitive device that should stay private. Area Setup has no per-entity exclude of its own.

2. Pick a controller profile

   Choose your main controller or leave it unselected; remember that this only merges flags. If Alexa needs 5540, do not create a batch of bridges that all expect to be commissioned to Alexa first.

3. Select a small number of areas

   Tick one or two to begin with and read the entity and domain summary. Select All can create a lot of bridges at once, which a low-resource host especially has to avoid.

4. Press Create Bridges and watch the progress

   The progress bar updates per area. Do not leave the page or click again; each result is listed as a success or an error.

5. Handle partial results

   Record the failed areas and a redacted error summary; go back to Bridges and cross-check the ones that succeeded, so you do not create duplicates. After fixing the port or the filter, redo only the failed items.

The full form and JSON: icon, country, priority, suffix and session

The Manual Create Page can also start from one of the ten templates, and then hands over to BridgeConfigEditor. It opens on the Fields Editor and you can switch to the JSON Editor; both validate against the same schema. The page also shows the Filter Preview and Bridge Icon Upload. The icon can be a built-in type, or a custom image handled through the admin interface; never use an image that carries a street address or identifying information.

The editor shows warnings for Server Mode, for several entities, for Vacuum OnOff, and for Auto Force Sync combined with Auto Composed Devices. None of these is forbidden outright, but read the warning through before you save. The icon is held by a separate component when you switch between Fields and JSON; while editing JSON, still avoid pasting any secret, and BridgeConfig itself should never contain an HA token or pairing data.

Importing an existing bridge: preview first, then decide about overwrite

Besides the three create workflows, the Import dialog on the Bridges page reads a bridge export JSON. Once you pick the file, the frontend parses the JSON and calls the preview API first; if parsing or the preview fails it only shows an error and imports nothing. The preview lists the export time, the format version, each bridge name, port and filter rule count, and Already exists.

Every previewed item is ticked by default, and you can Select All, Select None or clear them one at a time. overwriteExisting defaults to false; while it is off, an item that already exists is skipped rather than quietly overwritten. Before you turn overwrite on you need a current full backup, and you should first compare the port, the filter, the identity suffix and the feature flags. An older format is shown as migrated together with its source version, which means it was converted to the current format on import, not that every difference in meaning has been checked by a person.

1. Verify where the file came from

   Use only an export JSON that you control and have scanned. Do not import a configuration handed to you in a chat or on a forum, and do not attach an export to anything public.

2. Read the whole preview

   Cross-check the exported time, the source format, the bridge names, ports and filter rules. When you see an older version migration, save a separate backup first and compare item by item.

3. Untick what you do not need

   Untick any bridge that already exists or does not fit your port plan. Select None takes you safely back to zero selected, and the Import button is disabled at that point.

4. Choose overwrite carefully

   Keep the default off, so existing items are skipped. Turn it on only when you mean to replace them, have a backup, and understand the effect on identity and on the filter.

5. Cross-check the result after the import

   The dialog summarizes how many were imported, skipped and failed. Open each bridge's details and check the status and the device count; a partial success is not a reason to press Import on the whole batch again.

Common bridge-creation pitfalls

1. The Wizard will not let you leave the filter stage

   Check for an empty include: Label needs at least one selection, and Pattern, Domain or Area needs at least one value. Do not use an empty JSON array to get around the guard; decide on an explicit scope first.

2. The Alexa preflight shows a port warning

   Go back to Bridge Info and change it to 5540; if another bridge already holds it, first decide whether to reassign a bridge that has not been commissioned. Do not carry on with a port other than 5540 and expect it to correct itself later.

3. Port already used

   Look at the used ports and the bridge holding the port, then take the next free port. If the holder is a bridge that is already commissioned, do not just change its port; assess the controller outage and the cost of commissioning it again first.

4. Area Setup partly succeeded

   Use the results to separate succeeded from failed, and rebuild only the areas that failed. Check the successful ones on the Bridges page, so a Select All rerun does not create duplicates.

5. The preview shows zero entities, or far too many

   Cross-check the area ID, the label, the domain and the include/exclude order. Do not empty the include when the result is zero; when it is too large, narrow it to a single area or an explicit pattern first.

6. The network preflight will not load

   Treat it as diagnostics that did not finish, not as all passed. Confirm the backend api/network is reachable and that there is no global WebSocket or HTTP warning, then run Network Diagnostics from Health.

7. The import reports skipped or failed

   Read the summary and Already exists first; do not turn overwrite on and rerun straight away. Compare the ID, the port and the existing configuration, back up, and then deal with one conflict at a time.

FAQ

Pinned-version official and source-code references

• v2.0.55 Bridge Wizard: the six stages, the guards and multiple bridges
• All ten v2.0.55 bridge templates
• The four v2.0.55 controller profiles
• v2.0.55 network preflight and the Alexa 5540 warning
• The v2.0.55 Area Setup bulk workflow
• v2.0.55 Manual editor, port validation, preview and warnings
• v2.0.55 BridgeConfig schema, priority, suffix and session
• v2.0.55 Import preview, selection and overwrite