Installation

Choose Your Installation Method

MQTT Explorer supports multiple installation methods to fit your environment and workflow.

Desktop App

Native application for Windows, macOS, and Linux

Docker

Container deployment with built-in web server

From Source

Build from source for development or customization

Desktop Application

The desktop application is the easiest way to get started with MQTT Explorer.

Download Pre-built Binaries

Download the latest release from the official website or GitHub:

Download MQTT Explorer

Get the latest version for Windows, macOS, or Linux

Alternative: Download from GitHub Releases

Platform-Specific Installation

Windows

Installer (Recommended)

Download MQTT-Explorer-Setup-{version}.exe
Run the installer
Follow the installation wizard
Launch from Start Menu or Desktop shortcut

Portable Version

Download MQTT-Explorer-{version}-win.zip
Extract to your preferred location
Run MQTT-Explorer.exe

Microsoft StoreSearch for “MQTT Explorer” in the Microsoft Store (Windows 10/11)

macOS

DMG Installer (Recommended)

Download MQTT-Explorer-{version}.dmg
Open the DMG file
Drag MQTT Explorer to Applications folder
Launch from Applications or Spotlight

macOS Security: First launch may show “MQTT Explorer cannot be opened because it is from an unidentified developer”Solution: Right-click the app → Open → Click “Open” in the dialog

Notarization: Builds are automatically notarized for macOS Catalina and later.

Linux

AppImage (Universal)

# Download AppImage
chmod +x MQTT-Explorer-{version}.AppImage
./MQTT-Explorer-{version}.AppImage

Debian/Ubuntu (.deb)

sudo dpkg -i mqtt-explorer_{version}_amd64.deb
sudo apt-get install -f  # Install dependencies

Red Hat/Fedora (.rpm)

sudo rpm -i mqtt-explorer-{version}.x86_64.rpm

Snap Package

sudo snap install mqtt-explorer

The Snap package includes automatic security confinement. Some features like custom certificate locations may require additional permissions.

Docker Container

Run MQTT Explorer as a web application in a Docker container.

Quick Start

Pull and run the pre-built image:

docker run -d \
  -p 3000:3000 \
  -e MQTT_EXPLORER_USERNAME=admin \
  -e MQTT_EXPLORER_PASSWORD=your_secure_password \
  -v mqtt-explorer-data:/app/data \
  --name mqtt-explorer \
  ghcr.io/thomasnordquist/mqtt-explorer:latest

Then open your browser to http://localhost:3000

Available Tags

latest - Latest stable version from master branch
master - Latest build from master branch
beta - Latest beta version
release - Latest release version
master-<sha> - Specific commit from master

Supported Platforms

Docker images are built for multiple architectures:

linux/amd64 - x86-64 (standard PCs, servers)
linux/arm64 - ARM 64-bit (Raspberry Pi 3/4/5, Apple Silicon)
linux/arm/v7 - ARM 32-bit (Raspberry Pi 2/3)

Environment Variables

Variable	Required	Default	Description
`MQTT_EXPLORER_USERNAME`	No	Generated	Username for web interface authentication
`MQTT_EXPLORER_PASSWORD`	No	Generated	Password for web interface authentication
`MQTT_EXPLORER_SKIP_AUTH`	No	`false`	Disable authentication (use only behind secure proxy)
`PORT`	No	`3000`	Port the server listens on
`NODE_ENV`	No	-	Set to `production` for production deployments

If credentials are not provided, they will be auto-generated on first startup and saved to /app/data/credentials.json. Check the container logs to retrieve them:

docker logs mqtt-explorer

AI Assistant Configuration (Optional)

Enable the AI Assistant feature by configuring an LLM provider:

docker run -d \
  -p 3000:3000 \
  -e MQTT_EXPLORER_USERNAME=admin \
  -e MQTT_EXPLORER_PASSWORD=secret \
  -e LLM_PROVIDER=openai \
  -e OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxx \
  ghcr.io/thomasnordquist/mqtt-explorer:latest

Supported Providers:

openai - OpenAI GPT models (requires OPENAI_API_KEY)
gemini - Google Gemini models (requires GEMINI_API_KEY)

API keys are stored server-side only and never sent to the frontend. All LLM requests are proxied through the backend via WebSocket RPC.

Build From Source

Build MQTT Explorer from source for development or customization.

Prerequisites

Node.js: Version 20 or higher
Yarn: Package manager
Git: For cloning the repository

Desktop Application

Build and run the Electron desktop app:

Clone the repository

git clone https://github.com/thomasnordquist/MQTT-Explorer.git
cd MQTT-Explorer

Install dependencies

npm install -g yarn
yarn

This installs dependencies for both the main project and the app subdirectory.

Build the application

yarn build

Compiles TypeScript and builds the React frontend.

Run MQTT Explorer

yarn start

Launches the Electron application.

Browser Mode

Build and run as a web application:

Clone and install

git clone https://github.com/thomasnordquist/MQTT-Explorer.git
cd MQTT-Explorer
npm install -g yarn
yarn

Build for browser mode

yarn build:server

Compiles TypeScript and creates the browser-optimized webpack bundle.

Start the server

yarn start:server

Starts the Node.js server on port 3000.

Access in browser

Open http://localhost:3000 in your web browser.

Docker Build

Build your own Docker image:

# Build the browser mode Docker image
docker build -f Dockerfile.browser -t mqtt-explorer:local .

# Run the local image
docker run -d \
  -p 3000:3000 \
  -e MQTT_EXPLORER_USERNAME=admin \
  -e MQTT_EXPLORER_PASSWORD=secret \
  mqtt-explorer:local

System Requirements

Desktop Application

Windows: Windows 10 or later (64-bit)
macOS: macOS 10.13 (High Sierra) or later
Linux:
- Ubuntu 18.04 or later
- Debian 10 or later
- Fedora 32 or later
- Or equivalent distributions

Browser Mode

Server: Node.js 20 or higher
Browser:
- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- Opera 76+

Docker

Docker: Version 20.10 or later
Docker Compose: Version 1.29 or later (for compose files)

Verification

Verify your installation:

Launch MQTT Explorer

Open the application (desktop) or navigate to http://localhost:3000 (browser/Docker)

Check version

Desktop: Help → About MQTT ExplorerBrowser: Check footer or console logs

Test connection

Try connecting to a public test broker:

Host: test.mosquitto.org
Port: 1883
No authentication required

Troubleshooting

Desktop Application Won’t Start

Windows - SmartScreen Warning

If Windows Defender SmartScreen blocks the app:

Click “More info”
Click “Run anyway”

This warning appears because the app is not commonly downloaded yet.

macOS - Unidentified Developer

# Remove quarantine attribute
xattr -d com.apple.quarantine /Applications/MQTT\ Explorer.app

Or right-click → Open → Open (as described above)

Linux - Permission Denied

# Make AppImage executable
chmod +x MQTT-Explorer-*.AppImage

# Or for installed package, check file permissions
ls -la /usr/bin/mqtt-explorer

Docker Container Issues

Container won't start

Check the logs:

docker logs mqtt-explorer

Common issues:

Port 3000 already in use
Invalid environment variables
Permission issues with mounted volumes

Can't access web interface

Verify container is running: docker ps
Check port mapping: docker port mqtt-explorer
Test connectivity: curl http://localhost:3000
Check firewall rules

Authentication issues

Check generated credentials: docker logs mqtt-explorer
Verify environment variables: docker inspect mqtt-explorer
Reset by removing data volume:

docker stop mqtt-explorer
docker rm mqtt-explorer
docker volume rm mqtt-explorer-data
# Then recreate container

Next Steps

Now that MQTT Explorer is installed, learn how to connect to your first broker:

Quick Start Guide

Connect to an MQTT broker and start exploring

Get Started

Deployment

Features

Guides

Advanced

Choose Your Installation Method

Desktop App

Docker

From Source

Desktop Application

Download Pre-built Binaries

Download MQTT Explorer

Platform-Specific Installation

Docker Container

Quick Start

Available Tags

Supported Platforms

Environment Variables

AI Assistant Configuration (Optional)

Build From Source

Prerequisites

Desktop Application

Browser Mode

Docker Build

System Requirements

Desktop Application

Browser Mode

Docker

Verification

Troubleshooting

Desktop Application Won’t Start

Docker Container Issues

Next Steps

Quick Start Guide

Build docs developers (and LLMs) love

Get Started

Deployment

Features

Guides

Advanced

​Choose Your Installation Method

Desktop App

Docker

From Source

​Desktop Application

​Download Pre-built Binaries

Download MQTT Explorer

​Platform-Specific Installation

​Docker Container

​Quick Start

​Available Tags

​Supported Platforms

​Environment Variables

​AI Assistant Configuration (Optional)

​Build From Source

​Prerequisites

​Desktop Application

​Browser Mode

​Docker Build

​System Requirements

​Desktop Application

​Browser Mode

​Docker

​Verification

​Troubleshooting

​Desktop Application Won’t Start

​Docker Container Issues

​Next Steps

Quick Start Guide

Build docs developers (and LLMs) love

Choose Your Installation Method

Desktop Application

Download Pre-built Binaries

Platform-Specific Installation

Docker Container

Quick Start

Available Tags

Supported Platforms

Environment Variables

AI Assistant Configuration (Optional)

Build From Source

Prerequisites

Desktop Application

Browser Mode

Docker Build

System Requirements

Desktop Application

Browser Mode

Docker

Verification

Troubleshooting

Desktop Application Won’t Start

Docker Container Issues

Next Steps