NanoMQ: an edge MQTT broker for IIoT and software-defined vehicles

What NanoMQ solves on an edge device

A cloud MQTT broker assumes a stable network and a machine with memory to spare. An edge gateway does not have either. NanoMQ targets that gap: the README describes it as an "all-around Edge Messaging Platform" with an MQTT broker for IoT/IIoT and a messaging bus for software-defined vehicles. The intended user is someone deploying on an embedded board or a vehicle computer who wants MQTT 3.1.1, 3.1 and 5.0 without pulling in a JVM or a large runtime. The README states the implementation is pure C and fully based on native POSIX, which is the reason it can be cross-compiled to ARM with what the project calls minor migration efforts. That portability claim is the product's core pitch, not a feature list item. If you are running a broker on a Raspberry Pi class device, an industrial controller or a vehicle head unit, the constraint set NanoMQ is designed around matches yours. If you are running a broker in a data center, the same constraint set does not apply, and the trade-offs below matter more than the footprint.

The NNG actor architecture and what it implies

NanoMQ is built on NNG, which appears as a top-level directory in the repository (nng) and is pulled in as a git submodule. The README says NanoMQ's embedded Actor architecture extends NNG's internal asynchronous I/O with an enhanced message passing and scheduling system. In practical terms, that means the broker is not a thread-per-connection design: connections are handled asynchronously and work is dispatched across threads, which is why the README lists good SMP support alongside low latency. The repository layout supports this reading. The nanomq/ directory holds the broker, nanomq_cli/ holds the client tools, and extern/ holds third-party code. The build system is CMake at the top level, with a cmake/ directory for modules and a build.sh script. One consequence worth stating plainly: because NNG is vendored as a submodule, the build depends on network access to fetch it, and the README's build instructions include git submodule update --init --recursive for that reason. A second consequence is that NNG's abstractions leak into how you extend the broker. This is not a broker you fork and patch casually in an afternoon.

Running NanoMQ with Docker and starting the broker

The fastest path in the README is the published Docker image. The command below maps three ports: 1883 for plain MQTT, 8083 for the HTTP/WebSocket side and 8883 for TLS. The README gives exactly this invocation.

docker run -d --name nanomq -p 1883:1883 -p 8083:8083 -p 8883:8883 emqx/nanomq:latest

After it starts, the container runs in the background under the name nanomq. You should then be able to connect an MQTT client to localhost on port 1883. The README does not include a client command in this section, so the first real use is simply pointing an existing MQTT client at that port.

If you prefer a native binary, the README points to nanomq.io/downloads for the latest version. Once installed, the broker starts with a bare command, or with a configuration file passed explicitly.

nanomq start
## or run nanomq with a specified configuration file
nanomq start --conf <config_file>

The README shows --conf taking a path but does not print the schema of that file. That is the first thing you will have to read the docs/ directory or the repository config examples to learn. Building from source follows the standard CMake flow, and the README recommends Ninja.

git clone https://github.com/emqx/nanomq.git
cd nanomq
git submodule update --init --recursive
mkdir build && cd build
cmake -G Ninja ..
ninja

A make-based variant is also given, with cmake .. followed by make. Building requires a C99-compatible compiler and CMake 3.13 or newer, per the README.

Build flags you have to opt into

The README lists CMake defines that change what you get. None of them are on by default, which matters because the Docker image and a default source build are not the same product. TLS support requires -DNNG_ENABLE_TLS=ON and mbedTLS installed in advance. QUIC bridging requires -DNNG_ENABLE_QUIC=ON. The client tool suite (pub, sub, conn) is built unless you pass -DBUILD_CLIENT=OFF. There are flags for a ZeroMQ gateway, an NFTP client, a DDS proxy, a benchmark tool, JWT for the HTTP server, SQLite support, static and shared library builds, and debug, ASAN and ptrace tracing options. The DDS proxy is relevant if you are in the connected-vehicle space, since the README links a dds2mqtt directory and CycloneDDS. If your deployment needs TLS and you take the default Docker image without checking, you may assume encryption is handled when the flag that enables it is a build-time choice. That is a real configuration trap, and the README does not state which flags the published image was built with.

Where NanoMQ is the wrong choice

The README is explicit about MQTT 5.0 gaps: Auth and Server Redirection are listed as unsupported features, with links to the OASIS specification sections. If your architecture relies on enhanced authentication in MQTT 5.0, NanoMQ will not provide it. The README also does not document clustering, and the related search terms show people asking about NanoMQ clusters and Helm charts, which suggests demand the README does not answer. There is no dashboard documented in the README either, despite search interest in a NanoMQ dashboard. The test report linked from the README carries its own caveat: the benchmark is for version 0.2.5, with an updated one for 0.3.5 described as coming soon. So the performance numbers the project points to are not from the current release line. Finally, the README does not document rollback or downgrade procedures between releases, which is worth knowing before you upgrade a fleet of gateways. If you need a broker with a documented cluster mode, a management UI and a current published benchmark, look elsewhere first.

How it compares with Mosquitto and EMQX

Mosquitto is the obvious comparison, and the related searches confirm people make it. Both are C MQTT brokers. Mosquitto is the long-standing reference implementation with a wide package footprint across Linux distributions. NanoMQ's difference is the NNG actor layer underneath and its stated focus on embedded and vehicle targets, plus the bundled client tools and gateway proxies (ZeroMQ, DDS, NFTP) that Mosquitto does not ship in the same repository. EMQX is the other comparison, and it is a different class of product: it comes from the same organization, and the README points at EMQX's blog and a shared Slack workspace. EMQX is aimed at larger-scale cloud deployments with clustering and a management interface. NanoMQ is the edge counterpart. Choosing between them is mostly about where the broker sits, not about protocol support, since both handle MQTT 5.0. If you need to run on a device with limited memory and no JVM, NanoMQ is the one in this family designed for that.

Licence and upgrade cost

The repository is MIT licensed, and the licence file is LICENSE.txt at the top level. MIT is permissive, so embedding NanoMQ in a product does not by itself impose source disclosure. That is a statement about the licence text, not legal advice; check LICENSE.txt yourself and confirm the licences of the vendored dependencies under extern/ and nng, since those are separate projects with their own terms. On upgrade cost: releases 0.25.2-2, 0.25.3 and 0.25.6 landed between 2026-06-30 and 2026-08-19, and the last push to master was on 2026-09-22. That is a fast cadence, and the README's own test report lagging behind the release line is a sign that documentation does not always move at the same speed as the code. There is a CHANGELOG.md at the top level, which is where you should read before upgrading. A build from source with custom flags means every upgrade requires you to re-verify which defines you passed, because the README does not record defaults per release.

Editorial conclusion

Adopt NanoMQ when you need a small MQTT 3.1.1/5.0 broker on a POSIX edge device or vehicle gateway, and you are comfortable building from source with CMake 3.13 or newer. Do not adopt it if you depend on MQTT 5.0 Auth or Server Redirection, both listed as unsupported in the README, or if you want a broker with a documented clustering story out of the box. Before committing, verify the license text in LICENSE.txt and confirm the exact build flags you need, since TLS and QUIC are opt-in CMake defines rather than defaults.

Frequently asked questions

Official sources

1. License: MIT
2. nanomq/nanomq on GitHub
3. Project website
4. README
5. Releases