Home Assistant Community Add-on: EMQX

The most scalable open-source MQTT broker for IoT, IIoT, and connected vehicles.

About

EMQX is an Open-source MQTT broker with a high-performance real-time message processing engine, powering event streaming for IoT devices at massive scale. As the most scalable MQTT broker, EMQX can help you connect any device, at any scale (including your home).

The EMQX MQTT broker is an advanced alternative to the Mosquitto MQTT broker/add-on that is generally used in Home Assistant. It has a UI to configure, manage, and debug your MQTT broker, clients, and traffic.

While EMQX sells their product mainly as a cloud hosted product on their website, this add-on runs EMQX in a fully local, self-hosted environment.

📚 Read the full add-on documentation

Key Features & Enhancements

This fork of the EMQX Add-on provides an upgraded, reliable, and production-ready experience:

• EMQX Enterprise 5.10.5 (Final 5.x Release):
  • Security hardening: Resolves path-traversal vulnerabilities and protects sensitive API endpoints.
  • Complete modern IoT feature suite: AI/LLM integration in Flows, NATS protocol gateway, TLS 1.3 session tickets, and powerful Rule Engine data sinks.
• Latest Debian 13 Base Image:
  • Built on ghcr.io/hassio-addons/debian-base:9.5.2 (Debian 13.7 Trixie).
  • Uses S6-Overlay 3.2.3.0 and the latest bashio library for enhanced supervisor compatibility.
• Persistent Log Storage:
  • Automatically redirects and stores EMQX logs under /data/emqx/log, ensuring logs survive container restarts and add-on updates.
• Home Assistant Configuration UI:
  • Tune standard ports (mqtt_port, mqtts_port, websocket_port, wss_port) and log_level directly from the Home Assistant add-on configuration tab.
  • Securely bootstrap the Dashboard admin password via a masked password field.
• SSL / TLS Certificate Integration:
  • Direct integration with Home Assistant SSL certificates (e.g., Let's Encrypt fullchain and private key via /ssl).
  • Safe existence verification: Gracefully falls back to self-signed test certificates if custom certificates are not found on disk, preventing startup failures.
• Privacy & Traffic Tuning:
  • Built-in telemetry_enable toggle (defaults to false for complete privacy).
  • Configurable max_packet_size to handle large payloads or IoT telemetry streams.
• Advanced Environment Variable Overrides:
  • Fully supports overriding any EMQX HOCON configuration parameter via the env_vars option.

Configuration

You can configure the EMQX add-on directly from the Home Assistant Configuration tab or via YAML.

Note: Remember to restart the add-on when configuration changes are made.

Example Configuration

default_admin_password: "mySecretPassword"
mqtt_port: 1883
mqtts_port: 8883
websocket_port: 8083
wss_port: 8084
log_level: warning
ssl_certfile: "/ssl/fullchain.pem"
ssl_keyfile: "/ssl/privkey.pem"
ssl_cacertfile: ""
telemetry_enable: false
max_packet_size: "1MB"
retainer_storage_type: disc
retainer_delivery_rate: "100000/s"
retainer_max_publish_rate: "100000/s"
env_vars: []

Configuration Options

• default_admin_password (optional): Bootstraps the initial password for the EMQX Dashboard admin account.
• mqtt_port: TCP port for standard MQTT traffic (default: 1883).
• mqtts_port: TCP port for encrypted MQTT SSL/TLS traffic (default: 8883).
• websocket_port: TCP port for MQTT over WebSocket (default: 8083).
• wss_port: TCP port for MQTT over secure WebSocket (default: 8084).
• log_level: Console log level for EMQX (debug, info, warning, error, critical). Default: warning.
• ssl_certfile (optional): Path to the SSL certificate or fullchain file (e.g., /ssl/fullchain.pem). Automatically applied to the MQTTS listener when present.
• ssl_keyfile (optional): Path to the SSL private key file (e.g., /ssl/privkey.pem).
• ssl_cacertfile (optional): Path to the CA certificate file if mutual/client certificate verification is required.
• telemetry_enable: Enables or disables anonymous telemetry reporting to EMQX (default: false).
• max_packet_size: Maximum allowed MQTT packet size (default: 1MB, e.g., 5MB, 10MB).
• retainer_storage_type: Storage backend for retained messages (disc or ram, default: disc). Note: upstream EMQX defaults to ram, which loses retained messages on broker restart; this add-on defaults to disc so they persist across restarts. Set to ram for upstream behaviour.
• retainer_delivery_rate: Max rate retained messages are delivered to a subscriber (default: 100000/s). Note: upstream EMQX uses 1000/s, which can drop retained messages on a large wildcard subscription (e.g. Home Assistant discovery), leaving entities missing; this add-on raises it. Set to 1000/s for upstream behaviour.
• retainer_max_publish_rate: Max rate retained messages can be published/stored (default: 100000/s). Note: upstream EMQX uses 1000/s; raised here so restart-time bursts of retained publishes are not throttled. Set to 1000/s for upstream behaviour.
• env_vars: Custom environment variables for advanced HOCON configuration. Each entry must start with EMQX_ (e.g., EMQX_NODE__DATA_DIR).

Support

Got questions?

You have several options to get them answered:

• The Home Assistant Community Add-ons Discord chat server for add-on support and feature requests.
• The Home Assistant Discord chat server for general Home Assistant discussions and questions.
• The Home Assistant Community Forum.
• Join the Reddit subreddit in /r/homeassistant

You could also open an issue here GitHub.

Contributing

This is an active open-source project. We are always open to people who want to use the code or contribute to it.

We have set up a separate document containing our contribution guidelines.

Thank you for being involved! 😍

Authors & contributors

The original setup of this repository is by Franck Nijhof.

For a full list of all authors and contributors, check the contributor's page.

We have got some Home Assistant add-ons for you

Want some more functionality to your Home Assistant instance?

We have created multiple add-ons for Home Assistant. For a full list, check out our GitHub Repository.

License

MIT License

Copyright (c) 2023-2025 Franck Nijhof

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.