Welcome to rstmqtt
rstmqtt turns MQTT traffic into a live topic tree. See what your broker is up to, inspect messages and send your own. It runs on Linux, Windows and macOS, with MQTT 3.1.1 and 5.
What you can do
- Browse topics with live counters, change highlights and filtering.
- Inspect payloads as text, JSON, hex or Base64; browse history and compare changes.
- Publish messages with QoS, retain and MQTT 5 properties, or clear retained messages.
- Connect over TLS using system certificates or your own CA.
Install and connect
Grab your binary from the latest release: rstmqtt-linux-x86_64, rstmqtt-windows-x86_64.exe or rstmqtt-macos-aarch64.
On Linux and macOS, make it executable with chmod +x before launching it.
For source builds and Linux installation, see the README.
Click the pencil in the top bar, enter your broker settings and choose Connect.
Defaults: localhost:1883, MQTT 3.1.1, and subscriptions to # and $SYS/# at QoS 0.
Topics appear as messages arrive. See Connecting for the settings.
Connecting
The top bar shows host:port, TLS status and the MQTT version.
Click the pencil to edit settings or the plug to connect or disconnect.
The plug’s colour shows the connection state; hover for details or an error.
| Colour | State |
|---|---|
| Green | Connected |
| Yellow | Connecting or reconnecting |
| Red | Failed |
| Grey | Disconnected |
Dropped connections retry every second. Failed stops retries for errors that would recur, such as an oversized packet.
Connection settings
Connect saves settings and starts a new connection, ending any existing one.
Cancel or Esc discards edits.
| Setting | Default | Notes |
|---|---|---|
| Host, Port | localhost, 1883 | TCP only; no WebSockets. |
| TLS | off | See TLS. |
| MQTT version | 3.1.1 | Choose 5 for MQTT 5 properties. |
| Client id | rstmqtt- + 8 random hex digits | Reusing another client’s id disconnects it. |
| Username, Password | empty | Passwords are never saved, and clear when the broker, TLS setting or username changes. |
| Keep alive | 30 s | MQTT 5 uses at least 5 s. |
| Clean session | on | See Persistent sessions. |
Client id, username and password cannot contain null characters or exceed 65,535 bytes. Errors name the offending field.
TLS
Enable TLS for an encrypted connection with certificate and hostname verification.
Set the port yourself, usually 8883.
System root certificates are trusted by default. For a private CA, set CA file to a PEM file containing its certificates; this replaces the system roots. Client certificates and skipping verification are not supported.
Subscriptions
Each Subscriptions row pairs a topic filter with a QoS level.
The defaults, # and $SYS/# at QoS 0, cover all topics, including broker statistics.
Use Add subscription or the minus button to add or remove rows.
Wildcards occupy whole levels: + matches one, and a final # matches the rest, as in home/+/temperature or home/#.
Invalid filters turn red; hover for the reason. Broker rejections appear in the status bar.
Retained messages fill the tree with the broker’s last known values when you subscribe.
Persistent sessions
Uncheck Clean session to keep subscriptions and queued QoS 1 and 2 messages on the broker while disconnected. Reuse the client id to resume. MQTT 5 sessions never expire unless the broker caps them; an empty client id always uses a clean session.
rstmqtt remembers the last persistent session’s filters and unsubscribes removed filters when you reconnect to that session.
Topics
The left panel groups received topics into a tree with topic and message counters and previews of the latest payloads.
Binary previews show a size, such as <12 bytes>; empty topic levels, as in /a, appear as (empty).
Rows flash on arrival; collapsed branches flash for changes below them.
Click a row to inspect its messages and fill in the publish topic. Click its arrow or double-click to expand or collapse it. See keyboard shortcuts for navigation and copying.
Filter
Press Ctrl+F (Cmd+F on macOS) to search topic paths and latest values, ignoring case.
Matches and their ancestors stay visible and expanded.
Clear the filter to restore your previous expansion.
Context menu
Right-click a row to:
- Copy topic or Copy value (the latest payload in the chosen view).
- Publish here without changing the selection.
- Clear retained or Clear retained below…; see clearing retained messages.
- Remove from view to hide a topic and its descendants. Messages on the broker are unaffected; topics reappear when new messages arrive.
Status bar
The bottom bar shows connection state, message and topic counts, messages per second and tree memory usage. The graph tracks the last minute’s message rate.
Brief notes report actions and broker rejections.
A dropped count means some messages exceeded the storage limits; hover for details.
Messages
Select a topic to inspect it in the resizable right panel. Levels without messages show counts for the topics and messages below them.
Click a level in the topic path to select it, or the copy button to copy the full path. Below the payload: QoS, retained flag, local receipt time and size. The time records arrival, since MQTT provides no message timestamp.
Payload views
Choose a view above the payload; rstmqtt remembers your choice.
| View | Shows |
|---|---|
| Auto | JSON for objects and arrays, text for other UTF-8, hex for binary. JSON scalars such as 42 stay text. |
| Text | UTF-8 with invalid bytes replaced. |
| JSON | Pretty-printed JSON with sorted keys; text if invalid. |
| Hex | A hexdump -C style dump. |
| Base64 | Standard padded Base64. |
The copy button beside the views copies the full payload in the chosen format, even when the display is truncated.
JSON tree
Auto and JSON show objects and arrays as expandable trees, with the first two levels open.
Right-click a member to Copy path or Copy value.
Paths look like detections[0].score; keys with spaces use brackets, as in ["x y"].
History
History lists recent messages, newest first, with receipt time, size and a preview. Pick an older entry to pause on it; pick the newest to follow live traffic again.
Diff with the previous message
Enable Diff with previous to compare the selected message with its predecessor.
Added lines show a green +, removed lines a red -; unchanged lines stay in place.
Both messages use the same view. JSON keys are sorted, so key order alone creates no diff.
MQTT 5 properties
v5 properties appears below payloads with MQTT 5 properties: content type, response topic, correlation data, expiry, UTF-8 flag and user properties.
Large payloads
Text rendering is limited to about 64 KiB until you choose Show all. Hex and Base64 fit fewer payload bytes into that space. Payloads over 64 KiB initially skip JSON parsing; choose Show all for the JSON view. Truncated messages are not diffed until shown in full.
Publishing
Send a message back from Publish at the bottom of the right panel.
- Enter a Topic, select one in the tree, or right-click a row and choose Publish here.
- Enter the Payload; Format JSON tidies valid JSON or reports
Not JSONwithout changing it. - Choose QoS and Retain, then Send.
Send requires a connection.
Queued to <topic> confirms queuing, not delivery; MQTT 5 broker rejections appear in the status bar.
The message appears in the tree when the broker delivers it to a matching subscription.
Topics cannot be empty or contain + or #.
Errors below the form explain rejected input, including messages over the packet limit.
MQTT 5 properties
Set Content type or choose Add user property for a key/value pair; the minus button removes a pair. These fields are hidden and ignored on MQTT 3.1.1.
Recent messages
Recent keeps up to 20 distinct queued messages within 64 KiB of text; larger entries are skipped. Choose one to restore its topic, payload, QoS, retain flag and properties.
Uncheck Remember publish history to keep it only until the app closes, or choose Clear history to empty it.
Clear retained messages
To clear a retained message, rstmqtt publishes an empty retained payload on its topic. While connected, right-click a topic and choose:
- Clear retained for that topic.
- Clear retained below… for that topic and its descendants, with a count and confirmation first.
The status bar reports what was queued.
Subtree clearing only includes topics this client has seen with a retained flag. On MQTT 3.1.1, retained publishes received after subscribing lack that flag and may be missed. Unsubscribed topics stay untouched.
Keyboard shortcuts
Use Cmd instead of Ctrl on macOS.
| Action | Shortcut |
|---|---|
| Filter topics and values | Ctrl+F |
| Select the previous or next row | Up, Down |
| Expand the selected level | Right |
| Collapse it, or select its parent if collapsed | Left |
| Expand or collapse | Enter |
| Copy the displayed value | Ctrl+C |
| Copy the topic | Ctrl+Shift+C |
| Close a dialog | Esc |
Navigation and topic/value copying pause while a text field has focus or a dialog is open. Copy shortcuts respect selected text, so your selection gets the clipboard.
For mouse actions, see Topics and Messages.
Saved data and limits
Saved data
rstmqtt saves connection settings, payload view, publish history and window size and position.
On Linux, these live in $XDG_DATA_HOME/rstmqtt, or ~/.local/share/rstmqtt by default.
Passwords and received messages are never saved. Enter your password again after restarting. Received history clears when you close the app or start a new connection.
make uninstall removes the app, launcher entry and saved settings.
Limits
History has a budget. On a busy broker, older messages make room for new ones.
| What | Limit |
|---|---|
| Messages per topic | Last 100 |
| Memory for topics and messages | About 256 MiB; oldest messages across all topics are evicted first |
| Topic levels | 100,000 |
| Packet size | 16 MiB; outgoing MQTT 5 packets also respect the broker’s announced limit |
| Messages waiting to be sent | 1,024 |
| Topics, filters, client id, username, password, MQTT 5 property strings | 65,535 bytes each |
| Rendered text in the details panel | About 64 KiB, until Show all; see large payloads |
Messages that exceed the topic-level limit or cannot fit after eviction count as dropped in the status bar.
Hover for the reason.
An oversized incoming packet ends the session as Failed to avoid repeatedly fetching it on reconnect. If a retained message caused it, remove that message from the broker before reconnecting.