Moquette MQTT Broker: Embedding an MQTT 5 Broker in a Java Application

What Moquette is, and the case it actually fits

Moquette is a Java MQTT broker that the README describes as "lightweight" and "easily encapsulated in other applications." That second phrase is the whole design brief. This is not aimed at teams who want to install a broker, point a dashboard at it, and hand it to an operations group. It is aimed at developers who already have a JVM application and want MQTT sessions to live inside that process rather than beside it. The README lists the implemented MQTT 5 features explicitly: session and message expiry, shared subscriptions, request/response, topic alias, flow control, subscription options, will delay, server disconnects, and payload format indicator. It states that QoS 0, QoS 1 and QoS 2 are supported and that the MQTT 5 specification is "almost fully supported." That word "almost" is doing real work, and the README does not say which parts are missing. If your design depends on a specific corner of the MQTT 5 spec, treat the feature list as a starting point for verification rather than a guarantee. The protocol encoding and decoding is delegated to Netty, and the README describes the broker as evented. So the audience is narrow and identifiable: Java teams building device gateways, test harnesses, edge services, or any component where spawning a separate broker process is the thing you are trying to avoid.

How the broker is put together

Two facts in the README define the architecture. First, Netty handles protocol encoding and decoding, so Moquette is not hand-rolling MQTT frame parsing. Second, the broker is "designed to be evented." The repository layout backs this up: the top level carries a broker/ directory, a distribution/ directory, an embedding_moquette/ directory, and a metrics_prometheus/ directory. That split tells you the project is organised around the idea that the broker core is a library, the distribution is one way to run it, and embedding is a first-class supported path rather than an afterthought. The metrics_prometheus/ directory indicates a Prometheus metrics integration exists as a separate module, though the README does not document how to wire it up. The MQTT 5 features listed (session expiry, will delay, server disconnects, flow control) are all stateful behaviours that require the broker to track per-session state over time, which is consistent with an evented design where connection lifecycle events drive state transitions. What the README does not give you is a data flow diagram, a threading model, or a description of where session state is persisted. If you need to know whether sessions survive a broker restart, the README is silent.

Adding Moquette to a Maven build and starting a broker

The README documents embedding through JitPack. You add the JitPack repository to the repositories section of your pom.xml, then declare the moquette-broker artifact. The README's example pins version 0.18.0, which is worth noting because the release list shows 0.18.1 as the newest release, published on 2026-08-01. The README example has not been updated to match.

<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

With the repository declared, add the dependency. The groupId is com.github.moquette-io.moquette and the artifactId is moquette-broker.

<dependency>
  <groupId>com.github.moquette-io.moquette</groupId>
  <artifactId>moquette-broker</artifactId>
  <version>0.18.0</version>
</dependency>

If you would rather run the broker as a standalone process than embed it, the README gives a build path from a git clone. After cloning, cd into the sources and run ./gradlew package. The README states that the distribution package ends up at distribution/target/distribution-0.19-SNAPSHOT-bundle.tar.gz, and that the same directory holds "the selfcontained file for the broker with all dependencies and a running script." Note the version in that path: 0.19-SNAPSHOT, not 0.18.x. The build produces a snapshot bundle whose version does not match the newest tagged release.

./gradlew package

What the README does not provide is the next step: it never shows the command line for launching the running script, never lists configuration keys, and never states a default port. The reference guide at moquette-io.github.io is where that material is said to live, but it is not reproduced in the README.

Where Moquette is the wrong choice

The most concrete limitation is documentation coverage. The README is a feature list plus two build recipes. It does not document configuration keys, default ports, persistence behaviour, authentication, authorisation, or how to shut the broker down cleanly. The reference guide is linked but its contents are not summarised here, so a reader cannot tell from the README alone how much of that ground it covers. For a broker, configuration and access control are not optional details; they are the operational surface. A second limitation is the version story. The README's dependency example says 0.18.0, the newest release is 0.18.1, and the build path produces a 0.19-SNAPSHOT bundle. Three different versions appear across a single README. That is not a defect in the software, but it does mean you should not copy the snippets without deciding which version you actually want. Third, the README's own claim that MQTT 5 is "almost fully supported" is an admission of gaps it does not enumerate. If you are building against a specific MQTT 5 behaviour, you have to test it. Finally, Moquette is the wrong tool if you need a broker that non-Java operators can install, configure and monitor without touching a build file. Nothing in the README suggests a management console, a declarative config format documented in the repository, or a packaged installer.

Moquette against a full broker distribution

The obvious alternative is a standalone MQTT broker that ships as a service you install and configure, rather than as a library you embed. The difference in approach is not about protocol support; it is about where the broker lives. Moquette's README frames the project around encapsulation: the broker is something your application contains. A standalone broker is something your application connects to over the network, separately deployed, separately upgraded, separately monitored. That changes your failure model. With an embedded broker, the broker's lifetime is your process's lifetime, and a crash takes both down together. With a standalone broker, the broker can outlive any single client process, and you can restart your application without dropping the broker's session state. The trade-off runs the other way too: embedding removes a network hop and a deployment artifact, and it lets you configure the broker in the same code that uses it. Moquette also exposes a distribution bundle for the standalone case, so the project is not purely embed-only. But the README's emphasis, and the existence of the embedding_moquette/ directory, make clear which path is the intended one. If your team's operational model assumes a broker is infrastructure rather than a dependency, Moquette is fighting your model.

Maintenance, licensing and what an upgrade costs

The repository is not archived, and the last push was on 2026-08-31. The release cadence is uneven: 0.17.0-RC1 landed on 2023-08-02, 0.18.0 on 2024-12-27, and 0.18.1 on 2026-08-01. That is roughly a year and a half between 0.18.0 and 0.18.1, and a two-year gap before that. Plan for a project that moves in steps rather than a steady stream. The gap matters for upgrade planning: if you embed Moquette and a bug affects you, the fix may arrive on that kind of schedule. The licence is Apache-2.0, which is permissive and generally compatible with commercial embedding. The repository also carries license.txt, license-eplv10-aslv20.html, and license-eplv10-aslv20.html-style dual-licence artifacts at the top level, which suggests the dependency tree includes components under EPL-1.0/ASL-2.0 dual terms. That is not legal advice, and if you redistribute a bundle rather than depend on an artifact, the licence obligations you inherit are the ones attached to everything in distribution/target, not just to Moquette itself. Check the assembled bundle's contents before you ship it.

Editorial conclusion

Adopt Moquette if you need an MQTT 5 broker inside a JVM process and you are willing to read the source when the reference guide is thin. Do not adopt it if you need a turnkey, externally administered broker with documented operations, or if you cannot accept that the README's dependency example pins 0.18.0 while the newest release is 0.18.1. Before committing, resolve the JitPack artifact for the version you actually intend to ship, build the distribution with ./gradlew package, and confirm the MQTT 5 features you depend on behave as the README lists them.

Frequently asked questions

Official sources

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