Abstract violet and amber illustration representing Mosquitto, an open-source MQTT message broker distributing messages between connected clients

Mosquitto

Mosquitto

Mosquitto is the reference implementation of an MQTT broker: the piece of software that sits in the middle of a publish/subscribe network and makes sure a message published by one device reaches every service that subscribed to it. If you’re running Zigbee2MQTT, using Home Assistant’s MQTT integration, or building anything with ESPHome that talks MQTT instead of Home Assistant’s native API, Mosquitto is very likely the broker doing the actual message routing behind the scenes.

It doesn’t automate anything itself. No dashboard, no rules engine, no concept of "devices." It just moves small text or binary payloads between topics — home/livingroom/temperature, zigbee2mqtt/frontdoor/state — as fast as possible, to as many subscribers as are listening. That narrow job is exactly why it shows up in almost every self-hosted home automation stack. It’s the nervous system, not the brain.

Why a broker instead of direct connections

Without a broker, every device that wants to talk to every other service needs its own point-to-point connection and protocol. MQTT flips that: devices and services only ever talk to the broker, publishing to topics they care about and subscribing to topics they want to hear. Add a new consumer — a logging service, a second automation platform, a dashboard — and it just subscribes to the existing topics. Nothing else in the stack needs to know it exists. That decoupling is the entire value proposition, and it’s why MQTT brokers stay relevant even in stacks built around a single hub like Home Assistant.

Mosquitto’s license: two options, not one

Mosquitto is an Eclipse Foundation project, and its LICENSE.txt is explicit about the terms: it’s dual-licensed under the Eclipse Public License 2.0 (EPL-2.0) or the Eclipse Distribution License 1.0 (EDL-1.0), confirmed directly from the eclipse-mosquitto/mosquitto GitHub repository. That’s more permissive than it first looks. Per Mosquitto’s own SPDX identifier, the EDL-1.0 option is functionally equivalent to the BSD-3-Clause license. In practice, you can pick whichever license suits how you’re using or redistributing it: EPL-2.0 for compatibility with other Eclipse-licensed code, or the effectively-BSD EDL-1.0 for the most permissive option with the fewest conditions.

Mosquitto shares this Eclipse Foundation lineage with openHAB, also licensed under EPL-2.0. It’s an unusually concentrated presence of one foundation’s licensing in the self-hosted home automation space, where most tools default to MIT, Apache-2.0, or GPL.

Installing Mosquitto with Docker

The official eclipse-mosquitto image is the simplest way to run it. A minimal setup mounts a config directory, a data directory for message persistence, and a log directory, then exposes port 1883 for standard MQTT and 9001 for MQTT over WebSockets:

docker run -d --name mosquitto \
  -p 1883:1883 -p 9001:9001 \
  -v /path/to/mosquitto/config:/mosquitto/config \
  -v /path/to/mosquitto/data:/mosquitto/data \
  -v /path/to/mosquitto/log:/mosquitto/log \
  eclipse-mosquitto

Run it with no configuration file at all, and Mosquitto defaults to anonymous, unauthenticated access. That’s fine for a five-minute local test, not something to leave running on a network with more than one device on it.

Locking it down

A production mosquitto.conf should, at minimum, disable anonymous access and require a username and password, generated with the bundled mosquitto_passwd utility. Beyond that, Mosquitto supports access control lists (ACLs) to restrict which clients can publish or subscribe to which topics, and TLS for encrypting traffic if your broker is reachable from outside your LAN. None of this is enabled by default. That’s a deliberate choice, since Mosquitto doesn’t guess at your security requirements, but it’s also the single most common misconfiguration in self-hosted MQTT setups.

Mosquitto and Home Assistant

Home Assistant’s MQTT integration connects to any standards-compliant broker, Mosquitto included, and supports MQTT discovery: devices and services that publish a specific discovery payload appear in Home Assistant automatically, without manual YAML entity definitions. This is how Zigbee2MQTT devices show up in Home Assistant with almost no extra configuration once both containers point at the same broker: Zigbee2MQTT publishes discovery messages, Mosquitto routes them, Home Assistant listens. ESPHome devices default to Home Assistant’s native API instead, but can be switched to publish over MQTT when you want them visible to a broker-based stack rather than tied directly to one hub.

Alternatives to Mosquitto

Mosquitto is the most common self-hosted choice because it’s lightweight and has been the de facto reference broker for over a decade, but it isn’t the only option. EMQX, HiveMQ Community Edition, and VerneMQ are all open-source brokers built for higher throughput and clustering. Overkill for a homelab, but worth knowing about if you’re ever running MQTT at a scale beyond a single house.

For the full picture of where Mosquitto fits next to Zigbee2MQTT, Home Assistant, and the rest of a self-hosted automation stack, see our self-hosted home automation stack guide.