Getting Started with the HiveMQ Platform

HiveMQ is an MQTT-based industrial AI platform.
Use HiveMQ to bring operational data from the edge into the enterprise.

This guide helps you choose a deployment method and run your first HiveMQ broker instance.

Sign Up and Log In to HiveMQ

To start your journey, navigate to hivemq.com:

On the HiveMQ homepage, click Start Free.

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 to sign up and log in. HiveMQ automatically sends a confirmation email to the email address you provided.
If you signed up with your email address, use the link in the confirmation email to verify your email address. After you click the verify link, refresh your browser to continue.

If you selected email for your sign-in method and forget your password, you can use the Don’t remember your password option to create a new password. After a verification email, a Change Password dialog opens where you can create a new password. A notification window confirms that your password is successfully updated.

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

When you use your GitHub, Google, or LinkedIn account to sign up, the provider supplies your login data.

Once you sign up, you can log in to HiveMQ directly.

Choose a HiveMQ Deployment Path

After your sign-up is complete, a welcome page opens to choose how to run HiveMQ:

Option	Description
Cloud	Run your HiveMQ broker on HiveMQ Cloud. Managed service hosted by HiveMQ on AWS. No infrastructure required. Free tier available.
Software	Run your HiveMQ broker on your own infrastructure. Download and deploy on premises or in your cloud. Evaluation mode with limited functionality is available without a license.

Option

Description

Cloud

Run your HiveMQ broker on HiveMQ Cloud.

Managed service hosted by HiveMQ on AWS.
No infrastructure required. Free tier available.

Software

Run your HiveMQ broker on your own infrastructure.

Download and deploy on premises or in your cloud.
Evaluation mode with limited functionality is available without a license.

For details and configuration information, jump to the appropriate section of this start-up guide.

HiveMQ Cloud

HiveMQ Cloud is a full-featured, cloud-native MQTT messaging platform that delivers dependable, scalable IoT device connectivity with just a few clicks.

When you select the Cloud deployment option, a page to select the HiveMQ Cloud plan you need opens:

To see a full comparison of plan features, click Compare Plans. To exit, click Close. You can also click Ask Bea, then prompt Bea to compare the Serverless and Starter plans side-by-side.

The Starter package is the recommended way to explore the key features of HiveMQ Cloud. Take advantage of the HiveMQ Cloud Starter package 15-day free trial. No credit card is required, and you can cancel anytime.

To begin immediately, see Getting Started with HiveMQ Cloud for step-by-step instructions on how to set up and test a HiveMQ Cloud cluster.

Next Steps

When you are ready to scale up, learn more about how HiveMQ Cloud provides the reliability and scalability you need for business-critical solutions:

Explore the HiveMQ Cloud console to learn more about topics such as Access Management and pre-built HiveMQ Cloud integrations.

HiveMQ Software

The HiveMQ Platform powers data streaming, intelligence, and agentic AI to turn industrial data into trusted insights and autonomous action at scale.

When you select the Software deployment option, a page to select how you want to deploy your HiveMQ software opens:

You can follow deployment steps online, or jump to the appropriate section of this guide:

Option	Best for	Action
Docker	Quick local testing and development	Run now
Kubernetes	Container orchestration environments	Deploy
Download	Local deployment and testing on a server or computer of your choice	Install
Cloud Providers	AWS and Azure infrastructure	Launch

Option

Best for

Action

Docker

Quick local testing and development

*Run now*

Kubernetes

Container orchestration environments

*Deploy*

Download

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

*Install*

Cloud Providers

AWS and Azure infrastructure

*Launch*

HiveMQ Software Licenses

When no valid license is installed, HiveMQ starts in evaluation mode (also known as a Trial License). Evaluation mode is for testing purposes only and supports up to 25 client connections with 25 messages per second. Tests of Enterprise Extensions must be restarted every 5 hours.

To remove all limitations and enable production-ready features with a license, select Licenses in the side navigation. On the Broker Licenses overview, click + Add License.

Currently, HiveMQ offers two preconfigured HiveMQ license packages for purchase online:

Package	Description
Launch Package	Best for early deployments and low-risk production up to 10,000 connections. 500 messages per second throughput (5KB normalized messages). Community support level.
Run Package	Best for steady-state production workloads that require higher throughput. 1,000 messages per second throughput (5KB normalized messages). Silver support level.

Package

Description

Launch Package

Best for early deployments and low-risk production up to 10,000 connections. 500 messages per second throughput (5KB normalized messages). Community support level.

Run Package

Best for steady-state production workloads that require higher throughput. 1,000 messages per second throughput (5KB normalized messages). Silver support level.

If your use case requires more flexibility, click Configure a custom package to access advanced license configuration options:

HiveMQ Software Custom License Configuration

Use the Maximum connections and Messages per second sliders to adjust the software package parameters to fit your needs. The pricing summary information and package details adjust to match your configuration.

Once you review the pricing and package details, click Continue to add a payment method and confirm your license details.

To complete your purchase and begin your monthly subscription, agree to the HiveMQ Individual Use Terms and Privacy Policy, and click Subscribe.

Your HiveMQ license key is available immediately and valid from the License Start Date listed in the License Details.

If your configuration exceeds the self-service pricing limit, click Talk to Sales to open a form on which to request a personalized quote.

Run HiveMQ on Docker

Running HiveMQ with Docker is one of the simplest ways to experiment with HiveMQ and MQTT.

To download and start a single HiveMQ node in evaluation mode, enter:
$ docker run -p 8080:8080 -p 1883:1883 hivemq/hivemq4
(Make sure Docker is installed and running before you execute this command.)
Navigate with your browser to http://localhost:8080. If you see the login dialog for the HiveMQ Control Center, you know that HiveMQ is up and running.

The HiveMQ Control Center is part of the standard HiveMQ distribution and is a web application that you can access from your browser. You do not need to install any additional software on your computer to use the control center.
To log in, use the default credentials: user: admin, password: hivemq.

Next Steps

Once the HiveMQ MQTT broker is running, use any MQTT client to connect to your HiveMQ MQTT broker on port 1883.

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.

Deploy HiveMQ on Kubernetes with the HiveMQ Platform Operator for Kubernetes

The HiveMQ Platform Operator for Kubernetes is a tool for managing your HiveMQ deployments in a Kubernetes environment. The operator makes it easy to install, scale, configure, and monitor your HiveMQ Platform deployments in a versatile, adaptable manner.

Follow our HiveMQ Platform Operator for Kubernetes Quick Start Guide to use the Helm package manager to bootstrap the deployment and management of your HiveMQ Platform.

We provide specific installation instructions for the following Kubernetes distributions.

The following examples provide step-by-step instructions for a few popular Kubernetes distributions:

Install HiveMQ Locally on a Server or Computer of Your Choice

Use this option to begin your HiveMQ trial from a convenient ZIP download package.

Requirements

Windows, Linux, or macOS with OpenJDK JRE 21.
For a more detailed list of requirements, see HiveMQ System Requirements.

Download and Install HiveMQ

Download the HiveMQ ZIP archive.
Install HiveMQ for your platform:
- Linux, macOS, Unix: see HiveMQ Platform Installation on Unix-based systems.
- Windows Server: see HiveMQ Platform Installation on Windows Server.

By default, the HiveMQ broker starts on the localhost IP address (127.0.0.1) and listens on port 1883.

Verify that HiveMQ is running

Navigate with your browser to http://localhost:8080. If you see the login dialog for the HiveMQ Control Center, you know that HiveMQ is up and running. The default login credentials are: user: admin, password: hivemq.

Test your newly-installed HiveMQ broker

The following steps show you how to get started with some MQTT basics:

Connect MQTT clients to your HiveMQ Enterprise MQTT broker
Start publishing MQTT messages and subscribing to MQTT topics
Monitor the activity of your MQTT clients on the HiveMQ Control Center

Once HiveMQ is running, you can use any MQTT client to connect to your MQTT broker on port 1883.

In the following procedure, we use the MQTT CLI to connect MQTT clients and test the HiveMQ broker. The MQTT CLI is an open-source, Java-based MQTT client tool that enables you to interact quickly and easily with any MQTT broker in various ways. The MQTT CLI is included in the tools directory of HiveMQ version 4.4.0 or higher.

Preparation

Make sure your HiveMQ instance is currently running.
If desired, review the introductory tutorial for the MQTT CLI on YouTube.

The following instructions assume that HiveMQ and the MQTT clients run on the same machine. If the MQTT clients and the HiveMQ broker run on separate systems, replace 'localhost' with your broker address in the example commands.

Connect MQTT clients to HiveMQ

Open a terminal window and go to the tools directory of your HiveMQ 4.4 or higher installation. In the tools directory, go to the mqtt-cli/bin folder and enter mqtt sh to start the MQTT CLI in shell mode.
The MQTT CLI starts and lists useful options and commands.
To connect your first MQTT client to your HiveMQ broker on localhost and give it a custom identifier,
enter con -h localhost -i testClient1
This command creates the first MQTT client with the custom identifier testClient1 and connects the client to your MQTT broker on localhost.
To connect another MQTT client that you can use to test your installation, open a second terminal window and
enter mqtt sh (keep your original terminal window open).
In the second terminal window, enter con -h localhost -i testClient2
This command creates a second MQTT client with the custom identifier testClient2 and connects the client to your MQTT broker on localhost.

Publish an MQTT message / Subscribe to an MQTT topic

In the terminal window of the second MQTT client (testClient2), enter sub -t testTopic -s.
This command subscribes testClient2 to all messages that are published with the topic testTopic.
In the terminal window of the first MQTT client (testClient1), enter pub -t testTopic -m Hello.
This command publishes the message Hello from testClient1 with the topic testTopic.
The message Hello appears immediately in the terminal window of testClient2.

In shell mode, adding the -s command blocks the MQTT CLI console so that the incoming messages are printed out to the user.

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. The detailed information the control center provides helps you maintain a clear overview of your HiveMQ installation and quickly identify irregular client behavior.

To view the client activity that you just created, navigate with your browser to http://localhost:8080 and log in to the control center with the default credentials: user: admin, password: hivemq.
The control center Dashboard opens and shows you the current status of your HiveMQ installation (including notifications, license information, and key metrics):

HiveMQ Control Center v2 Overview Dashboard

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 information the latest version of the HiveMQ Control Center offers, see HiveMQ Control Center (v2).

Launch HiveMQ on Your Own AWS or Azure Infrastructure

HiveMQ on Amazon Web Services (AWS):
- AWS EC2 Quick-Launch
- AWS Windows Server 2022 Amazon EC2 Instance
HiveMQ on Microsoft Azure:
- Azure ARM Quickstart Template

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.

For complete step-by-step instructions from selecting the right AMI to launching your HiveMQ AWS EC2 instance, see Quick-Launch HiveMQ on an AWS EC2 instance.

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 an Amazon Web Services (AWS) Windows Server 2022 Amazon EC2 Instance

Requirements

Amazon Web Services account.
HiveMQ minimum hardware.
A remote desktop client, such as Microsoft Remote Desktop App for Mac.

Launch an Amazon EC2 Windows Instance

Log in to your AWS account and navigate to the EC2 console.
From the EC2 console dashboard, in the Launch instance box, click Launch instance.
Enter a descriptive name for your new instance. For example, HiveMQ Windows Server.
Select the Windows image:
Select an instance type that meets the minimum configuration requirements for a HiveMQ installation. In this guide, we use the t2.xlarge instance type with 4 vCPU and 16 GB RAM with at least 100 GB of available disk space.
Create and download a new key pair for use later to securely connect to your instance. Ensure you have access to the key pair before you launch the instance.

Do not choose Proceed without a key pair. If you launch your instance without a key pair, you cannot connect to the instance.
Select the RDP Client connection option to allow Remote Desktop Protocol (RDP) traffic to the server.
Replace Anywhere with a custom IP for increased security.
Add storage for your HiveMQ instance. In this example, the minimum value of 100 GB is used.

To complete your installation, click Launch Instance.
A confirmation page verifies that your instance is launching. Click View all instances to close the confirmation page and return to the console.

Connect to the Amazon EC2 Windows Instance

Open the Amazon EC2 console.
In the navigation pane, click Instances and find your instance.
Select the instance and click Connect.
On the Connect to instance page, switch to the RDP client tab and download the remote desktop file.
Enter the default username: Administrator and click Get Password.
Upload the private key from the last steps and note the password; this is your login password for Windows.
Double-click the remote desktop file and connect with your Windows password.
A confirmation message similar to the following verifies that Windows is up and running.

Next Steps

Download and install the latest version of the open source MQTT CLI tool for Windows and test your HiveMQ broker installation.

Deploy HiveMQ on Azure with an ARM Quickstart Template

Azure Resource Manager is the deployment and management service for Azure. A resource manager template is a JSON file that defines one or more resources to deploy to a resource group, subscription, management group, or tenant. The template can be used to deploy resources consistently and repeatedly.

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.

The hivemq-vm-cluster ARM quickstart template automates deployment of the following resources to Azure:

One or more virtual machines preinstalled with HiveMQ and the HiveMQ Azure Cluster Discovery Extension
An Azure Storage Account for the extension to use
An Azure Availability Set in which the virtual machines are located
An Azure load balancer to access the HiveMQ services
A virtual network in which the virtual machines and the load balancer are located
Network interfaces with public IP addresses for the virtual machines
A network interface with a public IP address for the load balancer

Requirements

Microsoft Azure account
GitHub account
HiveMQ License (optional)

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:

A window to sign in to your Microsoft account opens:

After you sign in to your Microsoft account, a page to edit the customized template you are about to deploy opens:

On the Custom deployment page, configure your Azure Resource Manager template to meet the needs of your individual use case. Required fields are marked with an asterisk (*):

Project details
Subscription *	Select the Microsoft Azure subscription in which the resource group is created. All resources in an Azure subscription are billed together.
Resource group *	Select the container Azure uses to hold the resources related to your HiveMQ ARM template. Click Create new to enter a name for your new resource group.

Project details

Subscription *

Select the Microsoft Azure subscription in which the resource group is created. All resources in an Azure subscription are billed together.

Resource group *

Select the container Azure uses to hold the resources related to your HiveMQ ARM template.
Click Create new to enter a name for your new resource group.

Instance details
Region *	Select the Azure region in which the virtual machine is deployed.
Admin Username	Define a name for the virtual machine. To complete the deployment, this name must be set.
Authentication Type *	Select the type of authentication the deployment requires. The following two options are possible: Password SSH Public Key
Admin password or SSH Key	Based on the authentication type you select, enter the password or SSH key of the virtual machine. For more information, see Create and use an SSH public-private key pair for Linux VMs in Azure.
VM Size *	Select the size of the virtual machine you want to deploy. The default VM size is Standard_F4s_v2.
HiveMQ Version	Enter the version of HiveMQ you want to deploy. The default version is 4.6.0.
Number of Instances	Enter the number of virtual machines you want to deploy in the cluster. The default value is 2.

Instance details

Region *

Select the Azure region in which the virtual machine is deployed.

Admin Username

Define a name for the virtual machine. To complete the deployment, this name must be set.

Authentication Type *

Select the type of authentication the deployment requires. The following two options are possible:

Password
SSH Public Key

Admin password or SSH Key

Based on the authentication type you select, enter the password or SSH key of the virtual machine. For more information, see Create and use an SSH public-private key pair for Linux VMs in Azure.

VM Size *

Select the size of the virtual machine you want to deploy. The default VM size is Standard_F4s_v2.

HiveMQ Version

Enter the version of HiveMQ you want to deploy. The default version is 4.6.0.

Number of Instances

Enter the number of virtual machines you want to deploy in the cluster. The default value is 2.

To save your changes and open a validation window, click Review + Create:

To confirm the template configuration and continue the deployment, review the Azure terms of service and click Create.

Microsoft Azure bills you for all resources you create. When you delete a template deployment, the resources you created are not affected. To remove resources, you must delete the resource group. Deletion of a resource group permanently removes all resources in the resource group and cannot be undone.

An overview window opens and shows the progress of your deployment:

To view progress information for each resource in the deployment as it is added, expand the Deployment details section.

The azuredeploy.json file of the hivemq-vm-cluster ARM template lists the parameter and variable configurations that the resource deploys.

Once your deployment is complete, a deployment overview for your template opens:

Since version 4.3, HiveMQ only allows MQTT clients to connect if a security extension is present. For testing purposes, HiveMQ includes a hivemq-allow-all-extension that authorizes all MQTT clients to connect to HiveMQ. Before you use HiveMQ in production, you must add an appropriate security extension and remove the hivemq-allow-all-extension. You can download security extensions from the HiveMQ Marketplace or develop your own security extension.

If you have a valid HiveMQ license, install the license information on each HiveMQ node in your cluster.
For more information, see Install a HiveMQ License. Skip this step if you are running HiveMQ in evaluation mode.
To verify that your HiveMQ cluster is running, check to see whether your HiveMQ Control Center is accessible:
- If you are using a load balancer, make sure to activate session persistence in your Azure load balancer configuration. Navigate with your browser to the public IP address of the load balancer: http://<your-load-balancer-public-IP-address>:8080.
- If you are not using a load balancer, navigate with your browser to the public IP address of one of the nodes in your HiveMQ cluster: http://<your-cluster-node-public-IP-address>:8080.

When you see the login dialog for the HiveMQ Control Center, you know that HiveMQ is up and running.

The HiveMQ Control Center is part of the standard HiveMQ distribution and is a web application that you can access from your browser for quick insights into your HiveMQ cluster.

By default, the HiveMQ broker starts on the localhost IP address (127.0.0.1) and listens on port 1883.

You do not need to install any additional software on your computer to use the control center. The default login credentials are: user: admin, password: hivemq. For more information, see HiveMQ Control Center.

When you no longer need your HiveMQ cluster on Azure, delete the Azure resource group that you created. Deletion of an Azure resource group permanently removes the resource group and all associated resources. This action cannot be undone. Deletion of an Azure deployment does not affect the Azure resource group or the associated resources.

Next Steps

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.