Zigbee2MQTT Cloud Broker Setup: Control Zigbee Devices from Anywhere over TLS

Using a Zigbee2MQTT cloud broker lets you read sensors and switch Zigbee devices from anywhere, with no port forwarding or VPN on your home network. In this guide you will point an existing Zigbee2MQTT installation at a TLS-secured broker on port 8883, test it on a public broker first, and then move to private credentials for daily use.

Why Use a Zigbee2MQTT Cloud Broker?

Most Zigbee2MQTT installs talk to a Mosquitto container on the same Raspberry Pi. That works well until you want something outside the house to see the data: a phone app on mobile data, a dashboard at the office, a second site such as a holiday home, or a backend service that logs energy use. Exposing a local broker to the internet means port forwarding, dynamic DNS and certificates, and every one of those is a new way to get it wrong.

A broker in the cloud flips the direction of the connection. Zigbee2MQTT opens an outbound TLS connection to the broker, exactly like a browser opening a website, so nothing on your router needs to change. Any authorised client anywhere can then subscribe to the same topics. If you are new to the role the broker plays in this picture, the short explainer on what an MQTT broker does is a good primer.

The trade-off is honest: your device states now pass through a service on the internet, so encryption and private credentials are not optional. The rest of this guide treats them as the default.

What You Need

• A working Zigbee2MQTT installation (1.x or 2.x) with a paired coordinator. If you are starting from scratch, follow the Zigbee2MQTT setup guide first and come back here.
• Access to Zigbee2MQTT's configuration.yaml (in the data folder, or the add-on configuration page in Home Assistant).
• For testing: nothing else, because the public broker accepts anonymous connections.
• For production: a broker with its own username, password and client ID, for example a ConnectMQ broker created from the portal.

Step 1: Test on the Public Broker

Before touching credentials, prove that Zigbee2MQTT can reach the internet and publish over TLS. The public MQTT test broker at broker.connectmq.com accepts anonymous clients with any non-empty, unique client ID. Everything published there is readable by anyone, so use a random topic prefix and only harmless test devices.

Edit the mqtt section of configuration.yaml:

mqtt:
  base_topic: connectmq/demo/z2m-7f3k9q/zigbee2mqtt
  server: mqtts://broker.connectmq.com:8883
  client_id: z2m-7f3k9q
  version: 5
  keepalive: 60
  reject_unauthorized: true

A few notes on these values:

• mqtts:// and port 8883 enable TLS. The broker uses a Let's Encrypt certificate, which Node.js already trusts, so you do not need a ca entry.
• base_topic with your random ID keeps your messages separate from everyone else's. Zigbee2MQTT appends the device friendly name and suffixes such as /set, so the full topic here is six levels deep, inside the public broker's limit of eight.
• version: 5 selects MQTT 5. Version 4 (MQTT 3.1.1) works too.
• reject_unauthorized: true is the default; leave it on. Turning it off accepts any certificate and defeats the point of TLS.

Restart Zigbee2MQTT and check the log for a line similar to Connected to MQTT server. Then subscribe from any machine:

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -i watcher-7f3k9q -t 'connectmq/demo/z2m-7f3k9q/zigbee2mqtt/#' -v

You should see bridge/state, bridge/info, bridge/devices and one topic per device. Switch a lamp from the other side:

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -i sender-7f3k9q -t 'connectmq/demo/z2m-7f3k9q/zigbee2mqtt/living_lamp/set' \
  -m '{"state":"TOGGLE"}'

On Windows or macOS, replace --capath /etc/ssl/certs with --cafile pointing at a CA bundle that contains ISRG Root X1.

Public broker limits to keep in mind

The public area allows 64 KB per message and 10 messages per second per client. A large Zigbee network can hit both: bridge/devices lists every device with its full definition and can exceed 64 KB on a big mesh, and a burst of sensor reports can exceed the rate limit. For a test with a handful of devices this is not an issue, but it is another reason to move to a private broker for the real installation.

Step 2: Move to a Private Zigbee2MQTT Cloud Broker

Once the test works, create a private broker. In ConnectMQ you choose a plan, create a broker and receive a generated username, password and client ID. Client IDs are bound to the issued credentials, so use the exact client ID from the portal.

Keep secrets out of the main file with Zigbee2MQTT's !secret syntax. Create secret.yaml next to configuration.yaml:

mqtt_user: YOUR_USERNAME
mqtt_password: YOUR_PASSWORD
mqtt_client_id: YOUR_CLIENT_ID

Then reference it:

mqtt:
  base_topic: home/zigbee2mqtt
  server: mqtts://broker.connectmq.com:8883
  user: '!secret mqtt_user'
  password: '!secret mqtt_password'
  client_id: '!secret mqtt_client_id'
  version: 5
  keepalive: 60
  reject_unauthorized: true
  include_device_information: false

frontend:
  enabled: true
  port: 8080

advanced:
  last_seen: ISO_8601

Replace the host with the one shown for your broker in the portal if it differs. Restart, and confirm the connection in the log and in the portal's live topic explorer, where home/zigbee2mqtt/bridge/state should appear as soon as Zigbee2MQTT starts.

last_seen adds a timestamp to every device message, which makes it much easier to spot a sensor that has gone silent when you are looking at the data remotely. Leave include_device_information off unless a consumer needs it, because it adds a block of metadata to every single payload.

Step 3: Control Zigbee Devices Remotely

With Zigbee2MQTT on a cloud broker, any MQTT client with credentials can act on your devices. The topic contract is the same as on a local broker:

The bridge/state topic is retained and set as the Last Will, so a remote dashboard can tell the difference between "the lamp is off" and "the whole Zigbee gateway is offline". Use that in your UI instead of trusting the last device state forever.

A minimal remote controller in Python, using paho-mqtt 2.x, looks like this:

import json
import paho.mqtt.client as mqtt

BASE = "home/zigbee2mqtt"

def on_connect(client, userdata, flags, reason_code, properties):
    print("connected:", reason_code)
    client.subscribe(f"{BASE}/bridge/state")
    client.subscribe(f"{BASE}/living_lamp")
    client.publish(f"{BASE}/living_lamp/set", json.dumps({"state": "ON", "brightness": 120}))

def on_message(client, userdata, msg):
    print(msg.topic, msg.payload.decode())

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="YOUR_CLIENT_ID")
client.username_pw_set("YOUR_USERNAME", "YOUR_PASSWORD")
client.tls_set()
client.on_connect = on_connect
client.on_message = on_message
client.connect("broker.connectmq.com", 8883, keepalive=60)
client.loop_forever()

Note that this script needs its own client ID. Running it with the same ID as Zigbee2MQTT would disconnect the gateway every time the script connects, because a broker allows only one session per client ID. Give each application its own credentials.

Home Assistant and Other Consumers

If Home Assistant should discover the Zigbee devices, enable homeassistant: enabled: true in Zigbee2MQTT and point Home Assistant's MQTT integration at the same broker and credentials. The step-by-step version, including TLS settings in the Home Assistant UI, is in the guide to using Home Assistant with an external MQTT broker. Discovery messages are retained, so they arrive even if Home Assistant starts after Zigbee2MQTT.

Other systems integrate the same way: Node-RED, Telegraf or a small script connects as an MQTT client, subscribes to home/zigbee2mqtt/# and writes to whatever storage you use. The broker itself just routes messages, which keeps the architecture simple and replaceable.

Troubleshooting Checklist

1. Connection refused: Not authorized - check the username and password, and that client_id matches the one issued for those credentials exactly.
2. Gateway keeps reconnecting every few seconds - another client is using the same client ID. Search your scripts, Node-RED flows and old containers.
3. self signed certificate or unable to verify - you are behind a TLS-intercepting proxy or the system clock is wrong. Fix the clock (common on a Pi without network time) before anything else.
4. Nothing arrives on the subscriber - confirm the base_topic is spelled identically on both sides; MQTT topics are case-sensitive.
5. bridge/devices missing on the public broker - the message is probably larger than the 64 KB public limit. Test with fewer devices or move to a private broker, where the Free plan allows 256 KB.
6. Connection limit reached - every Zigbee2MQTT instance, dashboard and script counts as one connection. The Free plan allows up to 25.

For a broader review of TLS, credentials and topic design, see the MQTT security best practices guide.

Choosing a Hosted Broker for Zigbee2MQTT

Zigbee2MQTT does not need much from a broker: MQTT 3.1.1 or 5, TLS, retained messages and a Last Will. What matters more for a remote setup is that the broker is reachable, encrypted and isolated from other tenants. A managed MQTT broker such as ConnectMQ handles certificates, uptime and upgrades so your Raspberry Pi only has to run Zigbee2MQTT. Free Serverless brokers are QoS 0 and 1, which covers Zigbee2MQTT's default QoS 0 publishing without changes. For a wider look at hosting choices, read the cloud MQTT broker guide, and for more automation projects that build on the same broker, browse the IoT automation guide.

Put Your Zigbee Network on ConnectMQ

Create a free Serverless broker at app.connectmq.com (no credit card), paste the generated credentials into secret.yaml, and watch your Zigbee devices appear in the live topic explorer within a minute of restarting Zigbee2MQTT.

Frequently Asked Questions

Can Zigbee2MQTT connect to a cloud broker over TLS?

Yes. Set server to mqtts://host:8883 in the mqtt section of configuration.yaml. For brokers using publicly trusted certificates such as Let's Encrypt, no extra CA file is required.

Is it safe to use a public broker for Zigbee2MQTT?

Only for short tests with harmless devices. Anyone can read and publish to topics on a public broker, so a door lock or alarm must never be connected that way; use private credentials for anything real.

Do I still need a local Mosquitto broker?

No. Zigbee2MQTT can publish directly to the cloud broker. Some people keep a local broker for local-only automations that must work during an internet outage, which is a valid design choice.

Why does my Zigbee2MQTT gateway disconnect when I open another app?

The other app is almost certainly using the same client ID. A broker keeps one session per client ID and drops the older connection, so give every client its own ID and credentials.