Getting Started with the HiveMQ Enterprise MQTT Broker
The HiveMQ Enterprise MQTT Broker is part of the HiveMQ Platform, an MQTT-based industrial AI platform.
This guide shows you how to create a free HiveMQ account on the HiveMQ Platform, run your first broker, and send and receive MQTT messages.
The guide uses the self-managed HiveMQ software option with a HiveMQ Lab License.
The Lab license is a free 30-day license for running a self-hosted HiveMQ Enterprise Broker in non-production environments.
During the license period, enterprise extensions run without a runtime limit. The Lab license also includes free access to Data Intelligence functionality, up to the free allowance.
More ways to get started:
-
To learn about all the features that the HiveMQ Platform offers, including ways to operationalize your data for AI-driven actions, see Getting Started with the HiveMQ Platform.
-
To connect your existing HiveMQ brokers to the HiveMQ Platform, see Connect Your Existing HiveMQ Broker or Edge Instance.
-
To start on HiveMQ Cloud, see Getting Started with HiveMQ Cloud.
Sign up and log in to HiveMQ
-
Navigate to hivemq.com:
-
On the HiveMQ homepage, click Try HiveMQ.
-
The first time you use HiveMQ, select a login method and sign up. You can use your GitHub, Google, or LinkedIn account, or your email address:
-
Email: HiveMQ sends a verification code to your email address. Enter the code and click Verify email. If you do not receive the code, click Resend code. Then set a secure password and click Create account.
-
GitHub, Google, or LinkedIn: The provider supplies your login data.
-
-
To complete your sign-up, enter basic contact details for your user profile and click Continue:
Your account opens in the HiveMQ Platform at app.hivemq.com.
For future visits, log in directly with the method you selected.
| The legacy HiveMQ console (console.hivemq.cloud) closed on November 4, 2026. All HiveMQ accounts now open in the HiveMQ Platform. |
Get HiveMQ running on your infrastructure
After you complete your sign-up, a welcome screen shows the ways to start with HiveMQ.
-
On the Download HiveMQ Software card, click Continue.
Next, a page to select the license that fits your workload opens. This guide uses the free Lab Package. To continue, review the Subscription Agreement, then click Select on the Lab Package card.
When you select the free Lab Package option, a page to choose how to deploy your self-managed HiveMQ Enterprise MQTT broker opens:
-
Click the method you prefer.
-
Follow the steps shown on the HiveMQ Platform interface, or go to the matching section of this guide:
| Option | Best for | Action |
|---|---|---|
Quick local testing and development |
||
Container orchestration environments |
||
Local deployment and testing on a server or computer of your choice |
||
AWS and Azure infrastructure |
| Expand the Requirements and License details options on each broker deployment page to view additional information such as the broker name and entitlements. Use the Release notes link to learn about HiveMQ features and improvements. |
Run HiveMQ on Docker
Docker is one of the simplest ways to try HiveMQ and MQTT. To learn more about HiveMQ clustering with Docker and using Docker and HiveMQ in production, see HiveMQ on Docker Hub and the HiveMQ User Guide.
Requirements
-
A running Docker installation.
-
A Bash shell to run the sample data script.
Start Your Broker on Docker
-
On the How to deploy your broker page, select Docker.
-
Use the version drop-down menu to select the latest version of HiveMQ or the most recent Long Term Support (LTS) version. This guide uses the latest HiveMQ version.
-
If you selected the Lab Package, HiveMQ automatically generates a license key for a free Lab license.
-
In the Run HiveMQ on Docker section, click the copy icon next to the command.
The command sets your license key as an environment variable and starts the broker. The command contains the license key information for the currently selected license. You do not need to manually edit the command. -
Open a terminal window and run the command you copied.
-
When your broker starts, click View broker.
On your new broker page, a Broker connected! notice confirms your broker is connected to the platform with Data Intelligence enabled. To continue the platform onboarding flow, select Next, get data flowing.
|
After your HiveMQ broker starts, you can connect any MQTT client to it on port 1883. This guide shows you how to turn on simulated telemetry for your new broker. Simulated telemetry is sample device data, such as machine states and throughput values. The script uses the HiveMQ MQTT CLI to generate the data. The MQTT CLI is part of the HiveMQ software bundle. You only need a Bash shell to run the script. With sample data, you can try Contextualize in the HiveMQ Platform before you connect your own devices. |
Send Sample Data to Your Broker
-
On the Get data flowing page, select the Use simulated data option and switch to the Docker tab, if it is not already open.
-
Click the copy icon next to the provided script.
-
Open a new terminal window and run the script you copied. It can take a minute for your broker to register the traffic. Leave the script running.
After a minute, a Data is flowing! notice confirms that data reaches your broker.
To continue the platform onboarding flow, go to Explore Your Data.
Deploy HiveMQ on Kubernetes with the HiveMQ Platform Operator for Kubernetes
The HiveMQ Platform Operator for Kubernetes is a tool for managing your HiveMQ broker deployments in a Kubernetes environment. The operator makes it easy to install, scale, configure, and monitor HiveMQ Enterprise MQTT Brokers and HiveMQ Enterprise Extensions in a versatile, adaptable manner.
Requirements:
-
Kubernetes 1.24.x or higher.
-
Helm 3.10.x or higher.
-
Kubernetes command line tool Kubectl.
-
On the How to deploy your broker page, select Kubernetes.
-
If you selected the Lab Package, HiveMQ automatically generates a license key for a free Lab license.
-
To add the HiveMQ Helm repository to your local Helm setup and install the HiveMQ Platform Operator, click Install the HiveMQ Platform Operator. In the expanded section, click the copy icon to copy the first command.
-
Open a terminal window, run the command you copied, and press Enter.
-
To deploy the broker in your cluster, click Install the broker. In the expanded section, click the copy icon to copy the next command. The command enables Data Intelligence for the platform pods. This feature requires HiveMQ Platform Helm chart 0.3.0 or later.
-
Open a terminal window, run the command you copied, and press Enter.
For additional setup options, see the configuration guide.
-
To reach the platform from your machine, use the copy icon next to the command to create a port-forward.
-
Open a terminal window, run the command you copied, and press Enter.
The Control Center is then available athttp://localhost:8080with the default login credentialsadmin/hivemq. MQTT clients can connect on port 1883. To connect MQTT clients, also use the copy icon next to the command to forward the MQTT service. -
Open a second terminal window, run the command you copied, and press Enter. Clients can then connect on
localhost:1883.Your broker is now connected to the HiveMQ Platform with Data Intelligence enabled.
-
Next Steps
Learn more about the HiveMQ Platform Operator for Kubernetes and how to use the Helm package manager to bootstrap the deployment and management of your HiveMQ Enterprise MQTT broker.
Install HiveMQ Locally on a Server or Computer of Your Choice
Use this option to run a self-managed HiveMQ Enterprise MQTT Broker from a convenient ZIP download package.
Requirements
-
Windows, Linux, or macOS.
-
OpenJDK JRE 21.x.x or 25.x.x.
-
4 GB RAM, 4 CPUs, and 100 GB disk (900+ IOPS). For more information, see HiveMQ System Requirements.
Start Your Broker Locally
-
On the How to deploy your broker page, select Install locally.
-
If you selected the Lab Package, HiveMQ automatically generates a license key for a free Lab license.
-
In the Download section, click Download the HiveMQ ZIP.
-
Use the version drop-down menu to select the latest version of HiveMQ or the most recent Long Term Support (LTS) version. This guide uses the latest HiveMQ version.
-
In the Install and start the broker section, select Install on Linux/macOS or Install on Windows.
-
Click the copy icon to copy the provided installation command. The command includes your license key and does not need to be edited.
-
Open a terminal window and run the command you copied.
-
When your broker starts, click View broker. The startup can take a few minutes.
On your new broker page, a Broker connected! notice confirms your broker is connected to the HiveMQ Platform with Data Intelligence enabled.
By default, the HiveMQ broker starts on the localhost IP address (127.0.0.1) and listens on port 1883.
To learn more about HiveMQ broker installation, see General HiveMQ Broker Installation Information.
To continue the platform onboarding flow, select Next, get data flowing.
|
After your HiveMQ broker starts, you can connect any MQTT client to it on port 1883. This guide shows you how to turn on simulated telemetry for your new broker. Simulated telemetry is sample device data, such as machine states and throughput values. The script uses the HiveMQ MQTT CLI to generate the data. The MQTT CLI is part of the HiveMQ software bundle. You only need a Bash shell to run the script. With sample data, you can try Contextualize in the HiveMQ Platform before you connect your own devices. |
Send Sample Data to Your Broker
-
On the Get data flowing page, select the Use simulated data option and switch to the Local installation tab.
-
In the Publish Sample data section, click the copy icon next to the provided script.
-
Open a new terminal window and go to your HiveMQ installation folder. The ZIP file extracts to a folder named
hivemq-<version>. The installation folder contains thebinandtoolsfolders. The script finds the MQTT CLI only when it runs from this folder. -
Save the script from your clipboard to a file:
-
macOS: Run
pbpaste > simulate-data.sh. -
Linux and WSL: Run
cat > simulate-data.sh, paste the script, press Enter, and then press Ctrl+D.
-
-
Run the script, and leave it running:
bash simulate-data.sh
The script prints status messages such as 40 topics under DemoCorp/Site01/Production/#.
After a minute or two, a Data is flowing! notice confirms that data reaches your broker. To continue the platform onboarding flow, go to Explore Your Data.
Explore Your Data
After MQTT traffic reaches your broker, you can work with the data in the Contextualize layer of the HiveMQ Platform.
The simulated data appears as Ungoverned MQTT Traffic on the Discovery tab of Contextualize.
-
On your broker page, click Govern data.
-
Follow the online tour to see how Discovery, Namespace, and Data Models work.
Act on Your Data
| Act is in public preview. Features and behavior can change before general availability. |
After you generate and explore your data, you can use the Act layer of the HiveMQ Platform to turn your data into AI-driven actions.
-
Follow the online tour to see how agents work.
The tour introduces the Marketplace, Templates, Deployed Agents, and Networks areas of the Act layer.
Connect Your Own MQTT Clients to Your HiveMQ Broker
After you explore the sample data, you can connect your own MQTT clients to the broker on port 1883.
This section uses the MQTT CLI, an open-source MQTT client that is part of the HiveMQ software bundle.
The commands assume that the MQTT clients and the broker run on the same machine.
If they run on different machines, replace localhost with the address of your broker.
|
Start the MQTT CLI
-
Open a terminal window, and start the MQTT CLI in shell mode (
mqtt shell). The specific command depends on how you run HiveMQ:-
Install locally (Linux/macOS): In your HiveMQ installation folder, run
./tools/mqtt-cli/bin/mqtt shell. -
Install locally (Windows): Install the Windows MQTT CLI. In the extracted folder, run
.\mqtt-cli.exe shell. -
Docker: Run
docker exec -it hivemq /opt/hivemq/tools/mqtt-cli/bin/mqtt shell. -
Kubernetes: Keep the port forward running, and use any MQTT client on your machine, such as a local installation of the MQTT CLI.
-
Connect an MQTT Client
-
To connect an MQTT client with the identifier
testClient1to your HiveMQ broker, open a terminal window and enter the following command:con --host localhost --identifier testClient1The MQTT CLI shows information about the connection. This client is your first connected MQTT client.
-
To create a second MQTT client, open a second terminal window and keep the first window open.
-
In the second window, enter
mqtt shelland then connect a client with the identifiertestClient2:con --host localhost --identifier testClient2This client is your second connected MQTT client.
Publish/Subscribe Test
-
In the second window, subscribe
testClient2to the topictestTopic:sub --topic testTopic --stayThe
--stayoption keeps the console open, so incoming messages appear in the window. -
In the first window, use
testClient1to publish the messageHelloto the topictestTopic:pub --topic testTopic --message "Hello"The message
"Hello"appears immediately in the terminal window of the second client. -
To publish another message, enter the following command in the first window:
pub --topic testTopic --message "Goodbye"
The MQTT CLI also accepts short options.
In the con command, -s is short for --secure.
In the sub command, -s is short for --stay.
|
View Your MQTT Clients and Topics
-
HiveMQ Platform: On the Discovery tab of Contextualize, the topic
testTopicappears next to the sample data topics. -
HiveMQ Control Center: Go to http://localhost:8080/v2, and log in with the username
adminand the passwordhivemq. To see the two clients, open the Clients view. For more information, see Monitor Client Activity on the HiveMQ Control Center.
Monitor Client Activity on the HiveMQ Control Center
The HiveMQ Control Center provides a wide range of metrics that help you manage and analyze your HiveMQ installation.
Navigate with your browser to http://localhost:8080/v2.
If you see the login dialog for the HiveMQ Control Center, HiveMQ is up and running.
The default login credentials are: user: admin, password: hivemq.
The detailed information the control center provides helps you maintain a clear overview of your HiveMQ installation and quickly identify irregular client behavior.
-
Check the Control Center Dashboard to see the client activity that you just created:
-
To view more information on the two MQTT clients that you just connected, switch to the Clients overview:
Next Steps
-
To learn more about the HiveMQ Control Center, see HiveMQ Control Center.
-
To learn more about the MQTT CLI, see MQTT CLI.
Launch HiveMQ on Your Own AWS or Azure Infrastructure
-
HiveMQ on Amazon Web Services (AWS):
-
HiveMQ on Microsoft Azure:
Deploy HiveMQ on Amazon Web Services (AWS EC2 Quick-Launch)
Our pre-built Amazon Machine Images (AMI) let you deploy a HiveMQ trial instance on AWS EC2 with ease.
The HiveMQ Quick-Launch installation sets up a fully operational HiveMQ AWS EC2 instance in your AWS account.
-
Follow the Quick-Launch HiveMQ on an AWS EC2 instance guide to select your AMI, pick an instance type, configure settings and security, and launch your broker.
-
If you selected the Lab Package, HiveMQ automatically generates a license key for a free Lab license.
-
Visit
http://<host>:8080with the public address of your installation. -
Log in to the HiveMQ Control Center with the default username admin and password hivemq.
-
Connect MQTT clients on port 1883.
-
In the Log in and apply your license section, click the copy icon next to the provided license key.
-
In the Control Center, go to Licenses → License Key → Add license key, and paste your license key.
-
In the Enable Data Intelligence section, click the copy icon next to the provided environment variable.
-
Set the Log-Based Cluster Transport variable on your broker.
-
Restart your broker.
Next Steps
To learn how to launch a production-ready HiveMQ cluster on AWS EC2, see Build an Elastic High-Availability HiveMQ Cluster on AWS EC2.
Deploy HiveMQ on Azure with an ARM Quickstart Template
Azure Resource Manager is the deployment and management service for Azure.
The HiveMQ Virtual Machines Cluster ARM template deploys a cluster of HiveMQ virtual machines to Azure with the number of HiveMQ instances you select. Each HiveMQ instance (node) is one virtual machine. The template installs the HiveMQ Azure Cluster Discovery Extension on each node. The extension enables HiveMQ cluster nodes to discover each other dynamically through regular information exchange via Azure blobs in an Azure blob-storage container.
Deploy Your HiveMQ Cluster with an ARM Quickstart Template
| Before you start, ensure the sign-in information for your Microsoft account is available. |
-
Go to the HiveMQ Azure Cluster Discovery repository on GitHub and select
arm-quickstart-templates/hivemq-vm-cluster. -
On the HiveMQ Virtual Machine Cluster page, click Deploy to Azure. Then, follow the Deploy Your HiveMQ Cluster with an ARM Quickstart Template to complete the deployment.
-
If you selected the Lab Package, HiveMQ automatically generates a license key for a free Lab license.
-
Visit
http://<host>:8080with the public address of your installation. -
Log in to the HiveMQ Control Center with the default username admin and password hivemq.
-
Connect MQTT clients on port 1883.
-
In the Log in and apply your license section, click the copy icon next to the provided license key.
-
In the Control Center, go to Licenses → License Key → Add license key, and paste your license key.
-
In the Enable Data Intelligence section, click the copy icon next to the provided environment variable.
-
Set the Log-Based Cluster Transport variable on every broker node.
-
Restart every broker node.
Next Steps
-
Learn more about ways to deploy HiveMQ on Azure. To discuss your specific use case with one of our experts, contact us. We are happy to talk with you about setting up HiveMQ to meet your needs.