Help & Getting Started

Installation

MQTT-JS is distributed as a native Linux package. Download the appropriate package for your distribution from the Download section.

Debian / Ubuntu (.deb)

sudo dpkg -i mqtt-js_*.deb

Then launch MQTT-JS from your application menu or run mqtt-js in a terminal.

Fedora / RHEL (.rpm)

sudo rpm -i mqtt-js-*.rpm

Connecting to a Broker

MQTT-JS can connect to any standard MQTT broker (Mosquitto, HiveMQ, EMQX, AWS IoT, and others) over plain MQTT (port 1883) or encrypted MQTTS (port 8883).

1. Click the + button in the top-left Connections panel.
2. Enter a friendly Name, the broker Host, and Port.
3. Choose mqtt for plain or mqtts for TLS.
4. Optionally set a Username and Password.
5. Click Add, then click the connection row and press Connect.

New connections automatically subscribe to # (all topics). You can narrow this in the connection settings.

TLS / Secure Connections

Select mqtts as the protocol to enable TLS. You can then provide certificate files from your filesystem:

• CA Certificate — the Certificate Authority that signed the broker's certificate. Required for self-signed broker certs.
• Client Certificate — your client's public certificate, for mutual TLS (mTLS).
• Client Key — your client's private key, paired with the client certificate.

Enable Allow self-signed certificates to disable strict certificate verification, useful for local development brokers.

Protobuf Decoding

If your MQTT messages carry binary protobuf payloads, MQTT-JS can decode them automatically using your schema files.

Step 1 — Load a .proto file

Open the Proto Files tab in the right-hand panel and click Load .proto file. Browse to your .proto schema. MQTT-JS will parse it and list all available message types.

Step 2 — Map a topic pattern to a message type

Switch to the Mappings tab. Enter a topic pattern (MQTT wildcards + and # are supported), select the proto file and message type, then click Add Mapping. Messages arriving on matching topics will be decoded automatically.

Filtering Messages

The filter bar at the top of the message list lets you focus on specific topics in real time.

• Type a topic substring and press Enter to add a filter chip.
• MQTT wildcards (+, #) are supported in filter patterns.
• Multiple active filters are ANDed — messages must match every active filter to appear.
• Save a filter by clicking the bookmark icon to reuse it across sessions.
• Click any chip to remove that filter.

Persistent Configuration

MQTT-JS automatically saves all connections, proto files, topic mappings, and filters to your local user data directory. Everything is restored the next time you launch the app — including re-loading all .proto files so your mappings continue to work without any extra steps. Your data never leaves your machine.