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:

Sign up and log in to HiveMQ

  1. Navigate to hivemq.com:

    HiveMQ Homepage
  2. On the HiveMQ homepage, click Try HiveMQ.

  3. 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:

    HiveMQ Signup
    • 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.

  4. To complete your sign-up, enter basic contact details for your user profile and click Continue:

    HiveMQ Profile

    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.

  1. On the Download HiveMQ Software card, click Continue.

    HiveMQ broker deployment options

    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.

    Select a license

    When you select the free Lab Package option, a page to choose how to deploy your self-managed HiveMQ Enterprise MQTT broker opens:

    Choose how to run your broker
  2. Click the method you prefer.

  3. Follow the steps shown on the HiveMQ Platform interface, or go to the matching section of this guide:

Option Best for Action

Docker

Quick local testing and development

Run now

Kubernetes

Container orchestration environments

Deploy

Install locally

Local deployment and testing on a server or computer of your choice

Download

Cloud Providers

AWS and Azure infrastructure

Launch

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

  1. On the How to deploy your broker page, select Docker.

  2. 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.

  3. If you selected the Lab Package, HiveMQ automatically generates a license key for a free Lab license.

  4. 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.

  5. Open a terminal window and run the command you copied.

  6. 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

  1. On the Get data flowing page, select the Use simulated data option and switch to the Docker tab, if it is not already open.

  2. Click the copy icon next to the provided script.

  3. 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.

    1. On the How to deploy your broker page, select Kubernetes.

    2. If you selected the Lab Package, HiveMQ automatically generates a license key for a free Lab license.

    3. 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.

    4. Open a terminal window, run the command you copied, and press Enter.

    5. 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.

    6. Open a terminal window, run the command you copied, and press Enter.

      For additional setup options, see the configuration guide.

    7. To reach the platform from your machine, use the copy icon next to the command to create a port-forward.

    8. Open a terminal window, run the command you copied, and press Enter.
      The Control Center is then available at http://localhost:8080 with the default login credentials admin / 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.

    9. 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

  1. On the How to deploy your broker page, select Install locally.

  2. If you selected the Lab Package, HiveMQ automatically generates a license key for a free Lab license.

  3. In the Download section, click Download the HiveMQ ZIP.

  4. 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.

  5. In the Install and start the broker section, select Install on Linux/macOS or Install on Windows.

  6. Click the copy icon to copy the provided installation command. The command includes your license key and does not need to be edited.

  7. Open a terminal window and run the command you copied.

  8. 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

  1. On the Get data flowing page, select the Use simulated data option and switch to the Local installation tab.

  2. In the Publish Sample data section, click the copy icon next to the provided script.

  3. 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 the bin and tools folders. The script finds the MQTT CLI only when it runs from this folder.

  4. 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.

  5. 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.

  1. On your broker page, click Govern data.

  2. 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.

  1. 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

  1. 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

  1. To connect an MQTT client with the identifier testClient1 to your HiveMQ broker, open a terminal window and enter the following command:

    con --host localhost --identifier testClient1

    The MQTT CLI shows information about the connection. This client is your first connected MQTT client.

  2. To create a second MQTT client, open a second terminal window and keep the first window open.

  3. In the second window, enter mqtt shell and then connect a client with the identifier testClient2:

    con --host localhost --identifier testClient2

    This client is your second connected MQTT client.

Publish/Subscribe Test

  1. In the second window, subscribe testClient2 to the topic testTopic:

    sub --topic testTopic --stay

    The --stay option keeps the console open, so incoming messages appear in the window.

  2. In the first window, use testClient1 to publish the message Hello to the topic testTopic:

    pub --topic testTopic --message "Hello"

    The message "Hello" appears immediately in the terminal window of the second client.

  3. 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

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.

HiveMQ Control Center login dialog

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:

HiveMQ Control Center Overview Dashboard
  • To view more information on the two MQTT clients that you just connected, switch to the Clients overview:

Client Sessions Overview

Next Steps

Launch HiveMQ on Your Own AWS or Azure Infrastructure

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.

  1. 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.

  2. If you selected the Lab Package, HiveMQ automatically generates a license key for a free Lab license.

  3. Visit http://<host>:8080 with the public address of your installation.

  4. Log in to the HiveMQ Control Center with the default username admin and password hivemq.

  5. Connect MQTT clients on port 1883.

  6. In the Log in and apply your license section, click the copy icon next to the provided license key.

  7. In the Control Center, go to Licenses → License Key → Add license key, and paste your license key.

  8. In the Enable Data Intelligence section, click the copy icon next to the provided environment variable.

  9. Set the Log-Based Cluster Transport variable on your broker.

  10. 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.

Requirements

  • Microsoft Azure account

  • GitHub account

Deploy Your HiveMQ Cluster with an ARM Quickstart Template

Before you start, ensure the sign-in information for your Microsoft account is available.
  1. Go to the HiveMQ Azure Cluster Discovery repository on GitHub and select arm-quickstart-templates/hivemq-vm-cluster.

  2. 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.

  3. If you selected the Lab Package, HiveMQ automatically generates a license key for a free Lab license.

  4. Visit http://<host>:8080 with the public address of your installation.

  5. Log in to the HiveMQ Control Center with the default username admin and password hivemq.

  6. Connect MQTT clients on port 1883.

  7. In the Log in and apply your license section, click the copy icon next to the provided license key.

  8. In the Control Center, go to Licenses → License Key → Add license key, and paste your license key.

  9. In the Enable Data Intelligence section, click the copy icon next to the provided environment variable.

  10. Set the Log-Based Cluster Transport variable on every broker node.

  11. 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.