# HiveMQ CE: a full MQTT 3 and MQTT 5 broker you can embed or run as a container

> HiveMQ Community Edition is the Apache 2 licensed Java broker that forms the technical core of HiveMQ's commercial platform, supporting every MQTT 3.1, 3.1.1 and 5.0 feature over TCP, TLS, WebSocket and Secure WebSocket, with a Java Extension SDK for authentication and authorisation. It ships as a binary package, a Docker image, a Gradle or Maven artifact for embedding, and the source builds with Gradle.

**hivemq/hivemq-community-edition** — HiveMQ CE is a Java-based open source MQTT broker that fully supports MQTT 3.x and MQTT 5. It is the foundation of the HiveMQ Enterprise Connectivity and Messaging Platform

- Repository: https://github.com/hivemq/hivemq-community-edition
- Website: https://www.hivemq.com
- Stars: 1,214 · Forks: 287
- Language: Java
- License: Apache-2.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/hivemq-hivemq-community-edition

## The broker that became the open source product

HiveMQ CE is a Java-based open source MQTT broker that fully supports MQTT 3.x and MQTT 5.

The interesting part of the story is in the second sentence of the README. HiveMQ CE is the foundation of the HiveMQ enterprise-connectivity and messaging platform, and it implements all MQTT features. This project is the technical core of many large MQTT deployments and is now available as open source software under the Apache 2 license.

That is a different proposition from a hobby broker or a from-scratch implementation. The code that runs the community edition is the same code that runs the commercial product, and the commercial platform is built on top of it. For an adopter, that means the broker itself is not the risky part of the platform decision, because it is the part that is already in production elsewhere.

The intended user is an engineer standing up an MQTT broker, which in practice means someone connecting devices to an application. The feature list says the broker supports all MQTT 3.1, 3.1.1 and MQTT 5.0 features, and it runs on Windows, Linux and macOS with Linux recommended.

The compatibility statement is worth reading closely, because MQTT 3 and MQTT 5 clients mix in the field for years. HiveMQ CE is compatible with all MQTT 3 and MQTT 5 clients, including Eclipse Paho and the HiveMQ MQTT Client.

The project is Apache 2 licensed, which for a server component that many organisations run in production is a practical licence with no copyleft obligation on your own code, and the repository carries the `LICENSE` file and the `CONTRIBUTING.md` alongside a `CLAUDE.md`, a `CODE_OF_CONDUCT.md` and a `renovate.json5` for dependency updates. The last push to the default branch `master` was on 2026-10-18, and the repository is not archived.

## Four transports and the Java Extension SDK

Two things define what the broker can do: how clients connect, and what the operator can change about their behaviour.

On the transport side, HiveMQ CE speaks MQTT over TCP, TLS, WebSocket and Secure WebSocket. That last pair is what makes the broker usable from a browser, since a browser client cannot open a raw TCP socket, and it is also how you reach the broker through an HTTP reverse proxy without inventing a translation layer.

On the behaviour side, the Java Extension SDK is the more consequential item. The list of what it covers is: authentication, authorization, client initializers, MQTT packet interceptors, and interacting with publishes, retained messages, clients and subscriptions.

Read that list as the answer to the classic broker problem. A stock broker can authenticate clients and enforce topic permissions, but it decides for you what those decisions look like. With an extension SDK written in Java, you can implement authentication against your own user store, write authorisation rules that depend on the payload or the client identity, run an initializer that assigns defaults to every connecting client, intercept packets on their way through, and read or write retained messages and subscriptions programmatically. In an environment where devices come from several vendors and the topic hierarchy encodes business rules, that is the difference between configuring a broker and programming one.

The combination of these two features is what makes the embedded mode interesting later on, and it is worth holding both in mind while reading the rest of the documentation. The SDK is a normal Java library, and the broker is a Java process, so the code that decides who may publish to what can be deployed either as a plugin beside a standalone broker or inside your own application.

## Running the binary package in three commands

The quick start is a download, an unzip and a script.

Download the latest HiveMQ CE binary package, unzip it, and run the `run.sh` on Linux and macOS or `run.bat` on Windows from the `bin` folder of the package. The shell form of the same thing is:

```bash
cd hivemq-ce-<version>
bin/run.sh
```

After that, you can connect MQTT clients to `<ip address>:1883`. Port 1883 is the default unencrypted MQTT port, and it is the port the Docker example also maps.

The runtime requirements are stated precisely. At least Java version 11 is required to run HiveMQ CE, and to compile the project and run tests at least Java version 21 is required. The README suggests checking with `java -version` on the command line if you are in doubt. That split is worth internalising, because a developer machine on Java 8 will not run the broker at all, and a build machine on Java 11 will not build the project.

The CAUTION in the quick start is the operational part that most deployments get wrong. If you want to connect devices on external networks to HiveMQ CE, you have to make sure your server is reachable from those networks and that the required ports, default 1883, are accessible through your firewall. A broker that listens and cannot be reached produces a device fleet that appears to connect and then goes quiet, and the fix is always the same firewall rule.

There is one documentation wrinkle to be aware of, and it matters if you follow the links literally. The quick start points at a release download for version 2026.6, while the most recent published release in the project history is 2026.5 from 2026-05-27, preceded by 2025.5 in November 2025 and 2025.4 in July 2025.

## Docker, the log level variable, and the nightly builds

The container route is the shortest path to a running broker, and the README gives both the release image and the branch image.

All releases as well as the current state of the `master` branch are available in the `hivemq/hivemq-ce` repository on Docker Hub. The run command is:

```bash
docker run --name hivemq-ce -d -p 1883:1883 hivemq/hivemq-ce
```

The `-d` flag detaches the container and the `-p 1883:1883` mapping publishes the broker's MQTT port on the host, which is the step that is easy to omit and then puzzling to debug, since the broker is running and nothing outside the container can see it.

The one configuration knob the README documents for the container is the log level, set through an environment variable:

```bash
docker run --name hivemq-ce -e HIVEMQ_LOG_LEVEL=INFO -d -p 1883:1883 hivemq/hivemq-ce
```

That is a small surface, and it is worth naming as a limitation rather than hiding: the container's runtime configuration in this documentation is one environment variable. Anything beyond log level, such as changing the listener ports, the persistence settings or the security configuration, belongs in the configuration files that the package ships, mounted into the container.

For people who want to test a change before it is released, the README points at just in time builds for current branches and for specific commits, published on a nightly builds page. That is a genuinely useful facility for a broker, because broker changes are the kind that need a soak test before they touch production devices.

The documentation itself lives in the repository wiki rather than in the tree, with the community forum as the place for questions, and the README links to two external resources for the protocol itself, MQTT Essentials and MQTT 5 Essentials.

## Embedded mode: the broker inside your application

HiveMQ Community Edition offers an embedded mode and a programmatic API for integrating with Java and Java EE software.

This is the feature that changes the deployment model. Instead of a broker process that your application connects to over TCP, the broker runs inside your application's JVM, and your application talks to it through a Java API. The artefact is `com.hivemq:hivemq-community-edition-embedded`, published to Maven Central with javadoc, and the build snippet for Gradle is:

```java
dependencies {
    implementation("com.hivemq:hivemq-community-edition-embedded:2026.6")
}
```

The entry point is `com.hivemq.embedded.EmbeddedHiveMQBuilder`, and the builder takes folders rather than a configuration file:

```java
public class Main {

    public static void main(final String[] args) {
        final EmbeddedHiveMQBuilder embeddedHiveMQBuilder = EmbeddedHiveMQ.builder()
                .withConfigurationFolder(Path.of("/path/to/embedded-config-folder"))
                .withDataFolder(Path.of("/path/to/embedded-data-folder"))
                .withExtensionsFolder(Path.of("/path/to/embedded-extensions-folder"));
        ...
    }
}
```

The lifecycle is then ordinary Java, with a try-with-resources block and a start that returns something you join:

```java
public class Main {

    public static void main(final String[] args) {
        final EmbeddedHiveMQBuilder embeddedHiveMQBuilder = EmbeddedHiveMQ.builder();
        ...

        try (final EmbeddedHiveMQ hiveMQ = embeddedHiveMQBuilder.build()) {
            hiveMQ.start().join();
            ...
        } catch (final Exception e) {
            e.printStackTrace();
        }
    }
}
```

A running EmbeddedHiveMQ can be stopped with `stop()`. The README notes you must set the compiler version to 11 or higher.

Two things follow from the shape of this API. The broker's configuration, data and extensions live in directories you choose, which is the same layout as the standalone package, so a deployment that starts embedded can be moved to a standalone broker later without redesigning its configuration. And because the broker is inside the JVM, the extension code and the application code share a process, which is a genuine simplification for a service that wants to react to MQTT events directly.

## Building from source with the Gradle wrapper

The build is Gradle, and the wrapper is committed, so no local Gradle installation is needed.

To build the binary package:

```bash
git clone https://github.com/hivemq/hivemq-community-edition.git

cd hivemq-community-edition

./gradlew hivemqZip
```

The resulting `hivemq-ce-<version>.zip` is created in the sub-folder `build/distributions/`, which is the same artefact shape as the download in the quick start, so the two paths produce the same thing.

To build the Docker image instead:

```bash
git clone https://github.com/hivemq/hivemq-community-edition.git

cd hivemq-community-edition

./gradlew loadOciImage
```

That produces the image `hivemq/hivemq-ce:snapshot` locally. The naming difference between the two tags is worth noticing, because `snapshot` is not a release and should not be what you run in production, while the Docker Hub tag without a suffix is the release stream.

The repository also carries a `jitpack.yml` and a JitPack badge, which means the project can be pulled as a dependency straight from GitHub rather than only from Maven Central, and it has an `eclipse-formatter.xml` and a `.editorconfig` for consistent formatting, plus a `HEADER` file, which is the licence header applied to source files.

The build requires Java 21 to compile and run the tests, against the Java 11 runtime requirement for the broker itself. That gap between build and run requirements is a small operational detail that trips people up: you can build with a newer JDK and still run the resulting broker on a Java 11 runtime, which is the arrangement most production setups will want.

## Where the community edition ends and the platform begins

The honest framing of this project is that it is the open source core of a commercial product, and that cuts both ways.

In its favour: the broker is the part that is hardest to get right and most likely to be already running in production somewhere else, and it implements all MQTT features rather than a convenient subset. The Extension SDK means that the parts of an MQTT deployment that are usually improvised, authentication, authorisation, interception, retention handling, are programmable in a mainstream language. The embedded mode removes the process boundary when you want it gone. And the Apache 2 licence means you can read the code that handles your devices' traffic.

The limitation follows from the same fact. HiveMQ CE is the foundation of the HiveMQ enterprise-connectivity and messaging platform, and anything beyond a single broker's feature set is the platform's. The community edition is a single broker with a Java extension point.

For a team whose requirement is one broker for a few thousand devices with a custom authentication service, that is exactly enough, and the extension SDK is a better answer than configuring a broker that has no extension point. For a team that needs a cluster across three availability zones, or a bridge to a legacy system, this repository is not the product, and the sensible move is to evaluate the commercial platform with the knowledge that its core is the code you can read here.

The alternative approach, and the one to weigh it against, is a smaller broker with a plugin model of its own. The difference in approach is that a small broker tends to be more permissive about what it implements and easier to reason about as a whole, while HiveMQ CE gives you a specification-complete implementation with a Java SDK and a commercial path behind it, and correspondingly more surface area to configure and more of an upgrade conversation to have with a vendor.

Whichever way you go, the two checks that matter are the ones the README flags. Confirm the Java version on the host, and confirm the ports are reachable from the networks your devices live on, because an MQTT broker that is up but unreachable is the most common failure mode and it is entirely a network configuration problem.

## Conclusion

Adopt HiveMQ CE if you need a broker that implements the MQTT specification completely rather than a subset, if your clients are a mixed fleet of MQTT 3 and MQTT 5 devices, or if you want to write your own authentication and authorisation in Java rather than configure someone else's, since the Extension SDK and the embedded mode are the strongest parts of the project. Do not adopt it if you need a commercial offering with support around the broker, since this code is the foundation of the HiveMQ platform. Verify three things first: that the Java runtime on your broker host is 11 or newer, that the transport ports you need are reachable through your firewall, and that the artefact version you pin matches the release you have actually tested, because the README's quick start points at a 2026.6 package while the newest published release is 2026.5.

## FAQ

### What is HiveMQ Community Edition and what licence is it under?

It is a Java-based open source MQTT broker that fully supports MQTT 3.1, 3.1.1 and MQTT 5.0, and it is the technical core of the HiveMQ enterprise-connectivity and messaging platform. The source files are made available under the Apache License Version 2.0.

### How do I run HiveMQ CE from the binary package?

Download the latest HiveMQ CE binary package, unzip it, and run `bin/run.sh` on Linux and macOS or `run.bat` on Windows from the `bin` folder. Java version 11 or newer is required to run it, and clients then connect to `<ip address>:1883`.

### Which transports does HiveMQ CE support?

MQTT over TCP, TLS, WebSocket and Secure WebSocket. The WebSocket transports are what allow browser based clients to connect, and the README notes that clients on external networks need the server reachable and the required ports, default 1883, open through the firewall.

### What can the HiveMQ Java Extension SDK do?

It covers authentication, authorization, client initializers, MQTT packet interceptors, and interacting with publishes, retained messages, clients and subscriptions. The same SDK is what makes the embedded mode useful, since the broker can be started inside your own Java application with EmbeddedHiveMQBuilder.

### How do I build HiveMQ CE from source?

Clone the repository and run `./gradlew hivemqZip` for the binary package, which appears in `build/distributions/`, or `./gradlew loadOciImage` for a local Docker image tagged `hivemq/hivemq-ce:snapshot`. Compiling the project and running the tests requires at least Java 21.

## Sources

- [hivemq/hivemq-community-edition on GitHub](https://github.com/hivemq/hivemq-community-edition)
- [License: Apache-2.0](https://github.com/hivemq/hivemq-community-edition/blob/master/LICENSE)
- [Project website](https://www.hivemq.com)
- [README](https://github.com/hivemq/hivemq-community-edition/blob/master/README.md)
- [Releases](https://github.com/hivemq/hivemq-community-edition/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hivemq-hivemq-community-edition