Install and Run EMQX Edge on Windows

This guide helps you install and run EMQX Edge on Windows. It also covers the features available in the Windows version and instructions to run EMQX Edge as a Windows Service.

You can download the EMQX Edge Windows distribution from the EMQX website.

Installation Steps

Assuming you have downloaded emqx-edge-1.1.0-windows-x86_64.zip:

1. Extract the ZIP archive to your preferred directory.

2. Open PowerShell and navigate to the extracted directory containing nanomq.exe:

   cd path\to\emqx-edge-1.1.0-windows-x86_64

3. Start EMQX Edge:

   ./nanomq start

4. Open your browser and visit http://localhost:8081 to access the Dashboard.

   For more information on accessing and using the EMQX Edge Dashboard, refer to: Access the EMQX Edge Dashboard.

Start EMQX Edge as a Windows Service

EMQX Edge supports running as a Windows Service, allowing it to start automatically with the system. However, this setup currently requires manual configuration using Windows utilities instsrv and srvany.

Note: This method involves editing the Windows Registry. Please back up your registry before making changes. A more user-friendly solution may be provided in future versions.

Step 1: Download and Extract EMQX Edge

1. Download the latest Windows release of EMQX Edge (e.g., emqx-edge-1.1.0-windows-x86_64.zip).
2. Unzip it to C:\emqx-edge.

Your extracted folder should contain files similar to:

ls C:\emqx-edge
Directory: C:\emqx-edge
Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----         2025/9/25     11:14                dist
d-----         2025/9/25     11:14                etc
d-----         2025/9/25     11:14                tmp
-a----         2025/9/24     11:00          94325 libwinpthread-1.dll
-a----         2025/9/24     11:00           5405 nanomq.conf
-a----         2025/9/24     11:10        5920768 nanomq.exe
-a----         2025/9/24     11:00            191 nanomq.lic
-a----         2025/9/24     11:10        1961984 nanomq_cli.exe
-a----         2025/9/24     11:10             40 start.md

Step 2: Add instsrv and srvany

This step sets up the EMQX Edge service wrapper using two Windows utilities: instsrv.exe and srvany.exe. These tools allow a regular executable (nanomq.exe) to be run as a Windows Service.

1. Copy instsrv.exe and srvany.exe to the C:\emqx-edge directory.

   These tools are part of the Windows Server 2003 Resource Kit and may need to be downloaded separately from trusted sources.

2. Open PowerShell as Administrator.

3. Navigate to the folder:

   cd "C:\emqx-edge"

4. Register EMQX Edge as a service:

   .\instsrv.exe EMQX-Edge C:\emqx-edge\srvany.exe

Step 3: Configure the Registry

This step sets up the EMQX Edge Windows Service to run nanomq.exe start automatically in the correct directory. You’ll use the Windows Registry Editor to configure how the service should start and what executable it should run.

Warning

Editing the Windows Registry can affect system behavior. Be sure to follow the steps carefully, and back up the registry if needed.

1. Launch the Registry Editor by typing regedit in the PowerShell terminal or Start menu.

2. Enter the following in Registry Editor to locate EMQX-Edge Service:

   HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EMQX-Edge

3. From the Edit menu (or right-click on EMQX-Edge), select New -> Key. Type the following entries, and select OK:

   Key Name: Parameters
   Class: <leave blank>

4. Select the newly created Parameters key.

5. From the Edit menu (or right-click on the right pane), select New -> String Value. Type the following entries, and select OK:

   Value Name: Application
   Data Type: REG_SZ
   String: C:\emqx-edge\nanomq.exe

6. Repeat the process to add the next two string values:

   Value Name: AppDirectory
   Data Type: REG_SZ
   String: C:\emqx-edge\

   Value Name: AppParameters
   Data Type: REG_SZ
   String: start

These registry entries tell the Windows Service Manager to launch nanomq.exe start from the C:\emqx-edge\ directory when the EMQX-Edge service is started.

Step 4: Start and Stop the Service

To start the service:

net start EMQX-Edge

To stop the service:

net stop EMQX-Edge

You can also manage the service from the Windows Task Manager -> Services tab.

Feature Support on Windows

The following table outlines the features available in the EMQX Edge Windows version, along with notes on platform-specific support and limitations.

Note: This feature list is based on EMQX Edge v1.1.0.

The Linux version supports all listed features by default. On Windows, certain features are currently unavailable due to platform-specific constraints or dependencies.

Feature	Supported ✅ / ❌	Notes
MQTT Broker	✅	Supports MQTT v3.1, v3.1.1, v5.0
TCP Listener	✅	TCP-based MQTT connections
TLS Listener	✅	Static build, no extra dependencies
WS / WSS Listener	✅	WebSocket & Secure WebSocket support
MQTT Bridge	✅	MQTT bridge across brokers
TCP Bridging	✅	MQTT over TCP bridge
TLS Bridging	✅	MQTT over TLS bridge
Dashboard	✅	Web UI for configuration and monitoring
REST API	✅	Manage and interact with EMQX Edge via REST
Authentication & Authorization	✅	Supports config file, HTTP, and ACL-based control
Rule Engine	✅	Event processing and rule triggering
SQLite Caching	✅	Persist messages to SQLite
WebHook	✅	Trigger events with user-defined hooks
CLI Tool	✅	Command-line interface for quick debugging
JWT Authentication	✅	Supports JWT via HTTP
ZMQ Integration	❌	Currently only supported on Linux
QUIC Bridging	❌	MQTT over QUIC supported only on Linux
Dashboard: Download Full Logs	❌	Full log download available only on Linux