RunMQTT works with standard MQTT clients. Choose the SDK for your application language; you do not need a RunMQTT-specific SDK. These three short examples publish the same test topic over TLS with MQTT 3.1.1, QoS 1 and retain disabled.
Prepare credentials and a receiver
Complete the quickstart first. Keep its terminal A subscriber to demo/hello running, and wait for SUBACK plus five seconds before running an example. The publishing device needs publish permission on demo/hello; the receiver needs subscribe permission. Use a separate Client ID for every connection.
In the terminal that will run your example, set these variables using your RunMQTT device details. MQTT_HOST is only the TLS hostname, without mqtts:// or :8883. Paste the password after read and press Enter; input stays hidden. The setup 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
Keep credentials out of source control. Each example uses your runtime's trusted CA certificates and keeps hostname verification enabled. Make sure your runtime has an up-to-date trust store.
JavaScript / Node.js
Use Node.js 22 or later. In an empty directory, run npm init -y and npm install mqtt@5. Save as publish.mjs, then run node publish.mjs in the configured terminal:
import mqtt from "mqtt";
import { randomUUID } from "node:crypto";
const { MQTT_HOST, MQTT_USERNAME, MQTT_PASSWORD } = process.env;
if (!MQTT_HOST || !MQTT_USERNAME || !MQTT_PASSWORD) {
throw new Error("Set MQTT_HOST, MQTT_USERNAME and MQTT_PASSWORD");
}
const deadline = setTimeout(() => process.exit(1), 20000);
let client;
try {
client = await mqtt.connectAsync(`mqtts://${MQTT_HOST}:8883`, {
username: MQTT_USERNAME,
password: MQTT_PASSWORD,
clientId: `js-${randomUUID().slice(0, 12)}`,
protocolVersion: 4,
keepalive: 60,
connectTimeout: 10000,
reconnectPeriod: 0,
});
await client.publishAsync("demo/hello", '{"language":"javascript"}', {
qos: 1,
retain: false,
});
} finally {
if (client) await client.endAsync(true);
clearTimeout(deadline);
}
Python
Use Python 3.9 or later. Create a virtual environment with python3 -m venv .venv, activate it with source .venv/bin/activate, and install python -m pip install 'paho-mqtt>=2,<3'. Save as publish.py and run python publish.py:
import os
import ssl
import uuid
from paho.mqtt import publish
publish.single(
"demo/hello",
payload='{"language":"python"}', qos=1, retain=False,
hostname=os.environ["MQTT_HOST"], port=8883,
client_id="py-" + uuid.uuid4().hex[:12], keepalive=60,
auth={"username": os.environ["MQTT_USERNAME"],
"password": os.environ["MQTT_PASSWORD"]},
tls=ssl.create_default_context(),
)
This one-shot helper is useful for a first publish. Use Paho's Client API for long-running subscriptions, callbacks and reconnect handling.
Java
In an existing Java Maven project, add this dependency inside pom.xml's dependencies element:
<dependency>
<groupId>org.eclipse.paho</groupId>
<artifactId>org.eclipse.paho.client.mqttv3</artifactId>
<version>1.2.5</version>
</dependency>
Save this class as src/main/java/RunMqttExample.java. Build with mvn compile and run its main method from your IDE with the three environment variables above. Paho Java uses ssl:// to name the same TLS connection that MQTT.js calls mqtts://.
import java.nio.charset.StandardCharsets;
import org.eclipse.paho.client.mqttv3.MqttClient;
import org.eclipse.paho.client.mqttv3.MqttConnectOptions;
import org.eclipse.paho.client.mqttv3.persist.MemoryPersistence;
public class RunMqttExample {
public static void main(String[] args) throws Exception {
MqttConnectOptions options = new MqttConnectOptions();
options.setUserName(System.getenv("MQTT_USERNAME"));
options.setPassword(System.getenv("MQTT_PASSWORD").toCharArray());
options.setMqttVersion(MqttConnectOptions.MQTT_VERSION_3_1_1);
options.setConnectionTimeout(10);
options.setKeepAliveInterval(60);
options.setHttpsHostnameVerificationEnabled(true);
MqttClient client = new MqttClient(
"ssl://" + System.getenv("MQTT_HOST") + ":8883",
MqttClient.generateClientId(), new MemoryPersistence());
client.setTimeToWait(10000);
try {
client.connect(options);
client.publish("demo/hello",
"{\"language\":\"java\"}".getBytes(StandardCharsets.UTF_8),
1, false);
} finally {
try {
if (client.isConnected()) client.disconnectForcibly(1000, 1000);
} finally {
client.close();
}
}
}
}
Confirm receipt and adapt to your application
Your quickstart subscriber should receive demo/hello with {"language":"javascript"}, {"language":"python"} or {"language":"java"}. Check the receiver, not just a successful publisher exit: a publish acknowledgement does not confirm application receipt or processing. If no message arrives within 30 seconds, stop the test and follow troubleshooting. Clear the password with unset MQTT_PASSWORD when finished.
These are first-connection examples, not persistent workers. Add subscription acknowledgement checks, bounded retries, graceful shutdown and business deduplication when integrating them. See device policies, sessions and delivery and shared subscriptions.
Browser applications must use the complete WSS URL from RunMQTT, such as wss://<broker>.tls-broker.runmqtt.com/mqtt. Node.js environment variables and Java/Python code do not run directly in the browser. Do not bundle shared device credentials into public JavaScript.
Use a coding agent to integrate faster
Give Codex, Claude Code, OpenCode or another coding agent your project language, framework, intended publish/subscribe topics and this documentation page. Keep the actual password in your local environment or secret manager; use placeholders in the prompt. Adapt this request to your project:
Verify MQTT connectivity and message sending/receiving for this project.
TCP (unencrypted): <copy the TCP endpoint from RunMQTT>
TLS (encrypted): <copy the TLS endpoint from RunMQTT>
MQTT username: <device username>
Client ID: <device Client ID>
Password: read MQTT_PASSWORD from my local environment; ask me to configure it if missing.
Topic permissions: <copy the template's Topic filters and publish/subscribe permissions>
Choose a concrete topic allowed by these permissions and test actual message receipt.
Report the connection method and results; explain any missing permissions or configuration.
For Go, C#, C/C++ or another language, ask the agent to apply the same connection and permission requirements using a maintained client library. Review the diff and run the receive test before integrating business traffic. SDK references: MQTT.js, Paho Python, Paho Java.