Setting up Zigbee2MQTT on Home Assistant OS
What you need

Raspberry Pi running HAOS
Zigbee USB dongle plugged in
Mosquitto broker (MQTT) installed

Step 1 — Install Mosquitto broker
Settings → Apps → Install app → search Mosquitto broker → Install → Start

Step 2 — Add the Z2MQTT repository
Settings → Apps → Install app → three-dot menu (⋮) top right → Repositories → add:
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt

Step 3 — Install Zigbee2MQTT
Search for Zigbee2MQTT → install the non-Edge, non-Proxy version

Step 4 — Configure the dongle
Go to Zigbee2MQTT → Configuration → expand serial:

Port: /dev/serial/by-id/ — use the full path of your dongle (it'll appear in the onboarding screen)
Adapter: ember (for SONOFF dongles)

Save.

Step 5 — Start it
Info tab → Start → check Log tab for successful connection

Step 6 — Open the web UI
Info tab → Open Web UI → this is your Z2MQTT control panel

Step 7 — Pair devices
Click Enable join in the Z2MQTT sidebar, then put each device into pairing mode. They'll appear automatically.

Notes

Don't run ZHA and Z2MQTT at the same time — they'll fight over the dongle
If starting fresh, just never install ZHA at all
The Z2MQTT web UI is your main tool for managing devices