Commission Matter with a Bluetooth proxy

A hosted Home Assistant has no Bluetooth, and ESPHome proxies should be able to do the pairing instead. The plumbing is in place; we have not yet watched it carry a commissioning.

Updated 26 August 2026 matterthreadbluetoothhow-to

Turn on ble_proxy on the Matter Server add-on and put the device next to an ESPHome Bluetooth proxy. Where it works, the phone's Bluetooth is unused, so is Google Play Services, and so is a radio on the border-router box.

Standing up Bluetooth on the border-router box also works and is the harder answer. Commissioning from the phone works today and is what the software steers you towards.

If Thread and Matter are still one blur, start at how Thread and Matter actually work. Pairing is Bluetooth; day-to-day is Thread. This page is only the Bluetooth hop.

Before you start

• Home Assistant 2026.06 or later. The option exists in the add-on on older versions and does nothing useful until Core can drive it.
• The official Matter Server add-on, not a copy running on the border-router box.
• At least one ESPHome Bluetooth proxy on the house LAN, close enough to hear the device. Eight around a house beat one good radio in a cupboard.
• A border router already visible in the Thread panel. If it is not, that is a different page: Thread and Matter with a hosted Home Assistant.

Steps

1. In Supervisor, open the Matter Server add-on, set ble_proxy on, save, restart the add-on.
2. If Home Assistant had previously been pointed at a Matter Server somewhere else, run the Matter integration's config flow again and answer yes, use the add-on. The API may claim that entry cannot be reconfigured. The config-flow route still updates it in place.
3. Put the device into pairing mode next to a proxy, not next to you on the sofa.
4. In Home Assistant (the web interface, not the companion app) add a Matter device and type the setup code from the QR label. If the web interface refers you to the companion app, that is the current behaviour and this path is not available to you yet.

Working, this shows up as Bluetooth activity in the Matter Server logs within a few seconds of submitting the code, then the device joining Thread, with the phone still in your pocket. What we have seen instead, commissioning from the companion app, is Skipping NetworkCommissioning steps because the device is already on IP network (udp) — the phone had done the Bluetooth part before Home Assistant was involved.

A device that pairs this way still becomes a Thread router, so the next one can mesh through it. The proxy is finished with it the moment credentials have been handed over.

When it goes wrong

The add-on has no ble_proxy option, or it is on and nothing happens. Core is older than 2026.06. Update Home Assistant, then restart the add-on.

Fails instantly on the QR scan / setup code. The proxy cannot hear the device. Move them together. Confirm the proxy is up in ESPHome and that Home Assistant's Bluetooth integration lists it. Pairing from the companion app on Android still goes through Google's stack even with ble_proxy on — use the web interface.

"Your device requires a Thread border router". You used the phone. This path is meant to skip that check. Go back to step 4 and add the device from the Home Assistant UI.

Hangs on "checking connectivity to Thread network". Bluetooth succeeded. IPv6 forwarding on the border-router host did not. See build a Thread border router.

The four lookalike failures, including the ones this path avoids, are spelled out in adding a Matter-over-Thread device.

We spent a day giving the Orange Pi Bluetooth and standing up a Matter Server next to the radio. Zero connection attempts ever reached it. ble_proxy was in the add-on options list the whole time.