Aedes MQTT Broker: Stream-Based Deployment and Persistence

Aedes for Node.js Stream-Based MQTT

Aedes addresses the case where an MQTT broker should be a JavaScript component rather than a separate daemon. It is intended for applications and services built around Node.js streams, especially systems that already use stream servers for networking. The package description calls it a stream-based MQTT broker, while the README describes it as a barebone MQTT server that can run on any stream server.

The project is not limited to plain TCP. Its feature list includes standard TCP support, SSL and TLS, WebSocket support, authentication and authorization, `$SYS` support, dynamic topics, and pluggable middleware. The core package is useful when the application needs MQTT behavior inside its own event-driven runtime. It is a library for composing a broker, not a documented all-in-one command-line server. The repository contains `aedes.js`, `aedes.d.ts`, `lib/`, `examples/`, and documentation files, but the README does not provide a complete first-server command or configuration file for this purpose.

Aedes supports MQTT 3.1 and MQTT 3.1.1. MQTT 5.0 support is explicitly marked as not supported yet, which makes the protocol boundary important. The Bridge Protocol supports incoming connections only. Those limits narrow the set of deployments for which Aedes is appropriate, even though its network and plugin choices are broad.

MQTT Message Flow and Broker State

The README presents Aedes as a broker that handles MQTT clients, subscriptions, publishing, retained messages, and `$SYS` information. Its stream-oriented design means that the broker can be attached to a compatible stream server rather than requiring one particular network listener inside the core package. The listed API references separate the `Aedes` class from the `Client` class, which indicates that broker behavior and individual connected clients are represented as distinct abstractions.

Persistence and message distribution are separated into extension points. The persistence plugins include in-memory, MongoDB, Redis, SQLite, LevelDB, and NeDB implementations. MQEmitter implementations include the default in-memory queue plus Redis, MongoDB, child-process, client/server, peer-to-peer, and Aerospike variants. This separation matters for a single process and for multiple nodes. A single-node setup can use the basic package without an external database. A cluster needs an on-disk database according to the README, and it needs an MQEmitter capable of sharing events between nodes.

The bridge connection behavior is a concrete example of broker-specific state handling. On an ordinary publish, Aedes consumes the `retain` flag and then sends the packet with `retain` set to `false`. The README cites MQTT-3.3.1-9 for this behavior and explains that, in a cluster, only one Aedes node should store the packet. When a client connects using the Bridge Protocol, subscriptions behave normally, but the incoming packet's `retain` flag is propagated as-is. This distinction matters for systems that compare local broker state with an upstream or downstream broker.

Installing Aedes and Running the Documented Check

The documented installation path is npm. The package is published as `aedes`, and the package metadata identifies the current listed version as `1.2.0` with ES module exports. The install command below is copied from the README. After it completes, the local project should contain the Aedes package in its npm dependencies.

npm install aedes

The README does not document a complete broker startup command, listener port, or server configuration. It points to `aedes-server-factory` for creating a TCP, HTTP, or TLS server instance, and to `aedes-cli` for running a broker from the command line. The project also links to `examples/` and `docs/Examples.md`, so those are the correct places to find a runnable application-level example.

For an already running broker on the standard MQTT endpoint used by the documented benchmark, the README gives this client-load command. It sends 5,000 QoS 1 messages from each of 1,000 clients. The command requires the benchmark client and a broker listening at `tcp://localhost:1883`; neither prerequisite is installed by the Aedes package command above.

mqtt-benchmark --broker tcp://localhost:1883 --clients 1000 --qos 1 --count 5000

Do not treat that benchmark as a startup example. The README gives benchmark output for an in-memory configuration, but it does not specify the server code needed to reproduce that listening endpoint.

Clustered Aedes Requires Persistence and an Emitter

Aedes has a deliberate cluster story, but that story is not limited to running several copies of the same process. The README states that clustered operation needs on-disk databases such as MongoDB or Redis. It also identifies `aedes-persistence-mongodb` paired with `mqemitter-redis` as the combination that reached the best performance and stability in the project's tests and user reports.

Those statements are project documentation, not an independent capacity guarantee. The README includes benchmark sections for in-memory operation, Redis persistence, MongoDB persistence, and several emitter combinations, but the excerpt does not provide enough configuration or complete results to derive a sizing recommendation. The visible benchmark command uses 1,000 clients and 5,000 QoS 1 messages per client, while the excerpt reports one in-memory result. It should be treated as an example workload, not a promise about a particular machine or deployment.

The persistence choice affects what survives process or node failure. The in-memory implementation is suitable only when loss of broker state is acceptable or an external component supplies equivalent behavior. Redis, MongoDB, SQLite, LevelDB, and NeDB are offered as separate plugins. The MQEmitter choice determines how events reach processes or nodes. A cluster design therefore has two decisions that cannot safely be collapsed into one: where MQTT state is stored and how broker events are distributed.

The repository includes `examples/clusters/`, but its contents are not shown in the repository entry list. Engineers examining clustering should inspect that example and the `aedes-tests` repository linked by the README before choosing versions or service topologies.

Protocol and Network Boundaries in Aedes

Aedes supports MQTT 3.1 and MQTT 3.1.1, but it does not yet support MQTT 5.0. That is the clearest functional limitation for adoption. A deployment whose clients require MQTT 5 capabilities should not select Aedes solely because its transport list includes TCP, TLS, and WebSocket. The missing protocol version is a compatibility boundary, not a configuration detail that can be solved by a persistence plugin.

The bridge restriction is narrower. Aedes can act as a destination for incoming Bridge Protocol connections, and retained flag handling differs for those connections. The README does not document outgoing Bridge Protocol support. This makes the project easier to evaluate when the required direction is inbound, but it requires care when designing a broker-to-broker topology.

The available extensions also define the operational surface. `aedes-logging` adds Pino-based logging, `aedes-stats` provides statistics, `aedes-protocol-decoder` provides a protocol decoder, and `aedes-server-factory` creates a server instance. Authentication and authorization are listed as supported features, but the README does not show the exact API or a complete configuration example for either. The API links to `docs/Aedes.md` and `docs/Client.md` are therefore essential references for implementing those controls.

Aedes can be a good fit for a Node.js service that owns its networking lifecycle and wants MQTT components in the same process. It is the wrong fit when MQTT 5 is mandatory, when an incoming-only bridge is insufficient, or when an operator wants a self-contained broker package with all deployment choices already selected.

Aedes Maintenance, Releases, and MIT Licensing

The repository is not archived, and its last push was on 2026-10-13. The listed releases include `v1.2.0` on 2026-09-16, `v1.1.3` on 2026-09-15, and `v1.1.2` on 2026-08-31. This indicates recent repository activity, but the README does not promise a particular release cadence or long-term support window. Version upgrades should be checked against the plugin versions selected for persistence and MQEmitter.

The package metadata declares `"type": "module"`, so the JavaScript examples and integration code should account for ES modules. The root export points to `aedes.js`, with TypeScript declarations at `aedes.d.ts`. The repository also includes type tests through `tsd`, and its test script runs linting, unit tests, and TypeScript checks.

The repository uses the MIT license. The README and package metadata do not provide legal interpretation beyond that identifier, so license compatibility and redistribution obligations should be checked separately for the complete application and its plugins. The presence of an MIT license for Aedes does not by itself establish the licensing terms of every persistence package, emitter, or server factory used alongside it.

The package also defines a `license-checker` script that permits MIT, ISC, BSD-3-Clause, BSD-2-Clause, and 0BSD dependencies. That is a project maintenance check for allowed dependency licenses, not a substitute for reviewing the terms of operational databases or services such as Redis and MongoDB.

Editorial conclusion

Adopt Aedes when the application needs an MQTT broker integrated with Node.js streams and can accept its plugin-based persistence model. Do not choose it for MQTT 5.0 clients or a cluster without selecting suitable on-disk persistence. Verify the supported protocol versions, the persistence plugin, the MQEmitter, authentication behavior, and the stream-server integration before deployment; Aedes 1.2.0 was released on 2026-09-16, and the last push was on 2026-10-13.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. moscajs/aedes on GitHub
4. README
5. Releases