TBMQ: a Kafka-backed MQTT broker from the ThingsBoard team

A broker built for the ThingsBoard ecosystem

TBMQ is the MQTT broker from the ThingsBoard organisation, and the repository description calls it the ultimate distributed MQTT broker, handling 100M+ connections and 10M msg/sec with ease, built on Kafka to provide industrial-grade persistence and eliminate data loss.

Those numbers are the project's own claims, stated in the repository description, and the README does not publish the test conditions behind them. That is not a reason to dismiss them, but it is a reason to treat them as a direction rather than a planning input. The architectural claim is the more useful part: Kafka as the persistence layer behind MQTT is a real design choice with real consequences.

The protocol story is unambiguous. TBMQ is fully compliant with the MQTT v3.1, v3.1.1 and v5.0 protocols, delivering complete support for all core MQTT features across both single-node and clustered environments. That spans the range of device clients in the field, from old embedded libraries that speak only 3.1.1 to new ones using v5 features.

The intended users are platform teams running connected device fleets, and the repository topics list covers the expected territory: broker, iot, mqtt, kafka, postgresql and thingsboard, which tells you this is designed to sit beside a ThingsBoard platform rather than to replace one.

Why Kafka sits under the broker

The persistence architecture is the defining technical decision, and it is what separates TBMQ from a broker that keeps its state in a single database.

A conventional MQTT broker keeps sessions, subscriptions and the queue of undelivered messages in its own store, often a relational database. That is simple to operate, and the write path is short. The cost is that the broker process is on the critical path for every message, and the store is a component you have to size, back up and reason about.

Putting Kafka underneath changes the shape of the write path. Messages land in a log that is designed to be durable and replayable, and the broker is a consumer of that log. The README summarises the intent as industrial-grade persistence and the elimination of data loss. The trade-off is operational: you now run a second distributed system, and the broker depends on it.

That is a good trade when a device fleet cannot afford to lose telemetry, because a Kafka log gives you a durable record that survives broker restarts and can be replayed. It is a poor trade for a small deployment, where the extra infrastructure costs more than the durability is worth. The repository layout supports the reading that this is a serious platform: there is a netty-mqtt module for the protocol layer, a dao directory for data access, an application directory for the service logic, a common directory, an api directory, an integration directory, a k8s directory, an msa directory for the microservice deployment, a packaging directory and a ui-ngx directory holding the web interface.

The project is built with Maven, with a pom.xml at the root, and it is written in Java.

Running the single-node Docker install on Linux and macOS

For a first look, the README gives a one-command path for Linux and macOS users who want a single-node Docker setup. The script is downloaded, made executable and run:

wget https://raw.githubusercontent.com/thingsboard/tbmq/release-2.4.1/msa/tbmq/configs/tbmq-install-and-run.sh &&
sudo chmod +x tbmq-install-and-run.sh &&
./tbmq-install-and-run.sh

Note the branch name embedded in that URL. It points at release-2.4.1, so the script is version-pinned to the current release line rather than tracking the default branch. That is a sensible thing for a vendor to publish, and it is worth noticing if you intend to read the script before running it.

When the installation completes, the web UI is reachable on the default port 8083 at your host address:

http://localhost:8083

The default credentials are given in the README as the username [email protected] with the password sysadmin. Change them before this instance is reachable by anything else, because a broker UI with default administrative credentials is a well known failure mode.

The README points to a fuller Docker guide for comprehensive instructions, troubleshooting guidance and advanced configuration details.

Cluster installation on Kubernetes and with Helm

Beyond the single-node script, the README lists the installation options it supports. Docker is for quick local or on-premise setups. Kubernetes deployments are documented for AWS, Azure and GCP. Helm charts are offered for streamlined Kubernetes installation.

The distinction between these paths is more than a packaging detail. The Docker compose path gives you one broker node, which is fine for evaluation and for a small deployment. The Kubernetes paths imply the clustered environment the project describes, with the nodes communicating and the persistence tier behind them.

For anything beyond a single node, the operational question is what has to be operated. A clustered broker with a Kafka tier and, judging from the repository topics, PostgreSQL in the picture is three distributed systems to run and monitor, not one. The Helm chart route means you get a declarative install, but the cluster still needs a Kafka deployment that the chart does not create for you.

The documentation set is organised by installation type, with the Docker compose setup, the AWS, Azure and GCP cluster setups, and a Helm-specific section. The README also says the project offers flexible installation options tailored for both development and large-scale production environments, which is the honest way to describe the difference between the script above and the cluster guides.

The public demo broker and what read-only means

TBMQ runs a public MQTT broker for evaluation, and the README gives the connection details as a table: host demo.tbmq.io, TCP port 1883, TLS and SSL port 8883, WSS port 443 with the WSS path /mqtt, username demo and a password to be left empty.

The limitations are stated in the same section, and they are specific. The live dashboard provides read-only access to the Professional Edition features. You can monitor active sessions and throughput in real time, but configuration is locked. To deploy a fully configurable cluster with administrative rights, the README directs you to install the Professional Edition.

That distinction matters when you evaluate the project. The demo shows you the broker under load, with real client sessions and real throughput numbers on a dashboard, which is a genuine way to see what the thing does. What it does not show you is the administration surface, the multi-tenant configuration, or the parts of the product that the Professional Edition unlocks.

The README frames the demo as a way to validate an IoT fleet against a public MQTT broker, visualise real-time throughput, explore the management UI and test connectivity with no infrastructure of your own. It is a reasonable first step, and it is also a way of evaluating a subset of the product.

Open source core, Professional Edition and the release cadence

The repository is licensed under Apache-2.0, and the tree carries the usual ThingsBoard markers: a license-header-template.txt at the top level and a security.md file, which tells you the project expects contributions and coordinated disclosure.

The open source and commercial split runs through the product. The demo is described as offering the observability and control of the Professional Edition, and the README links to separate installation documentation for TBMQ PE. In practice, the repository is the broker and its open source core, and some management capabilities sit in the commercial edition.

The release history gives a picture of the cadence. v2.3.0 shipped on 2026-05-12, v2.4.0 on 2026-08-27 and v2.4.1 on 2026-10-08. The last push to the repository was on 2026-10-14, and the repository is not archived, so work is continuing between releases rather than the project sitting still.

One thing a reader should notice in the layout is the ui-ngx directory. A broker with its own web front end in the same tree, alongside a common directory, an api directory and an application directory, tells you this is a platform rather than a library, and it changes what adopting it involves: you are taking on a running system with a user interface, not a jar you call from your own code.

If you need programmatic access, the api directory is where the HTTP interface lives, and the integration directory is where integrations with the rest of a ThingsBoard deployment would sit.

Editorial conclusion

Use TBMQ if you are running an industrial IoT fleet that needs MQTT traffic to survive a broker restart, that already runs ThingsBoard, or that needs the clustering and Helm options the project provides. Do not adopt it on the strength of the headline figures, because the connection and throughput numbers in the repository description carry no stated test conditions, and do not expect the demo deployment to be more than a read-only sandbox. Before deploying, read the installation guide for your target, confirm that the Kafka tier and the PostgreSQL dependency match your operations, and note that the open source core is separate from the Professional Edition, with the most recent release being v2.4.1 on 2026-10-08 and the last push on 2026-10-14.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. thingsboard/tbmq on GitHub