Quickstart

This guide completes one round trip through your own RunMQTT Broker. You need a RunMQTT account and, for the terminal check, Mosquitto 2.x client tools with --tls-use-os-certs support. Install the client tools for your operating system before continuing.

For a disposable check without private capacity, use the public MQTT broker with synthetic data only. Its credentials and topics are shared, and state may reset without notice.

1. Create a Broker

Open Dashboard, select the action to create a Broker, and choose a name, plan and billing cycle. Review the trial eligibility and payment terms shown at checkout. After checkout, return to RunMQTT and wait for the Broker to become active. If setup remains pending, follow troubleshooting before creating another subscription.

2. Grant one test topic

In the Broker's Templates tab, create a template named demo-client. Open it and add a Topic policy with these values:

This exact topic keeps the first test small. A publish-only policy will not let this client receive its own test message. Saving a policy does not subscribe a client; you still need to subscribe in the next steps.

3. Create a device and copy credentials

In Devices, create demo-client-1 using that template. Open its connection details and copy the TLS endpoint, MQTT username and password. The MQTT password is separate from your RunMQTT account login. Use the displayed values without hashing or signing them.

Each simultaneous client needs a different Client ID. The two terminal commands below deliberately use runmqtt-demo-sub and runmqtt-demo-pub.

4. Receive a message in the browser

In the Broker's MQTT client tab, select the device, connect, and subscribe to demo/hello. Wait for subscription success, then publish {"message":"hello"} to demo/hello with QoS 1. Confirm a received traffic entry with that topic and payload; a sent entry alone is insufficient.

This browser tool uses MQTT 3.1.1 and publishes at QoS 0 or 1. Use an SDK for MQTT 5, persistent sessions and advanced delivery tests.

5. Repeat over TLS in two terminals

In each terminal, set the following variables. Replace the placeholders with the device details. MQTT_HOST is only the hostname: omit mqtts:// and :8883. After read, paste the password and press Enter; input stays hidden. These commands use Bash or Zsh.

export MQTT_HOST='<broker>.tls-broker.runmqtt.com'
export MQTT_USERNAME='<broker-id>/<device-name>'
read -r -s MQTT_PASSWORD
export MQTT_PASSWORD

In terminal A, start the subscriber:

mosquitto_sub -h "$MQTT_HOST" -p 8883 --tls-use-os-certs \
  -u "$MQTT_USERNAME" -P "$MQTT_PASSWORD" -i runmqtt-demo-sub \
  -V mqttv311 -k 60 -q 1 -t 'demo/hello' -v -d

Wait for a successful SUBACK, then allow five seconds before the first publish. In terminal B, send:

mosquitto_pub -h "$MQTT_HOST" -p 8883 --tls-use-os-certs \
  -u "$MQTT_USERNAME" -P "$MQTT_PASSWORD" -i runmqtt-demo-pub \
  -V mqttv311 -k 60 -q 1 -t 'demo/hello' -m '{"message":"hello"}'

Terminal A should show demo/hello {"message":"hello"}. If SUBACK rejects the request, or no message arrives, check the template and use troubleshooting. Never disable certificate verification to make the example connect.

Stop the subscriber with Ctrl+C and run unset MQTT_PASSWORD in both terminals. -P is convenient for local testing but may expose the password to local process inspection; use a protected client configuration or secret manager for unattended clients.

Continue building

• Adapt the client integration examples to your application.
• Separate production publishers and subscribers with device policies.
• Distribute backend consumption with shared subscriptions.
• Test sessions and delivery before relying on offline recovery.
• Review plans and billing before increasing traffic.