0.2.0 early release

A lightweight MQTT broker for the edge

A lightweight MQTT broker that remembers.

Sagüin is a single-node MQTT 3.1.1 and 5 broker that adds a replayable event stream, a latest-value state store and a work queue to ordinary MQTT topics, in a single binary under 20 MB with one SQLite store.

MQTT 5 + 3.1.1One SQLite storeSingle node

The gap

MQTT moves messages.
Edge systems need memory.

A truck parks in a basement for nine days. A substation’s cellular modem sulks through a storm. A vessel crosses open ocean. If the broker kept only a bounded queue of what each device missed, and that queue overflowed on day one, the readings are gone.

That is not a bug in MQTT. MQTT defines how clients and brokers exchange messages, including through persistent sessions. But when edge data becomes business data, “the link dropped, so the readings are gone” is not a sentence you can put in a billing dispute.

The usual fix stacks a streaming platform, a cache and a job queue beside the broker: four systems, four client libraries, four failure modes. Sagüin provides the same semantics in one binary, keeping MQTT as the interface devices and applications already use.

Three durable primitives

One protocol.
Three channel types.

A channel is a named, typed log holding the topics its MQTT filter matches. Channels are configured at the broker; devices and clients publish and subscribe as usual.

01

Replayable event stream

Keep the history

Store each record once and keep a position for every consumer, stored for durable sessions. Replay after an outage, or seek back by offset, duration or time.

Versus plain MQTT. An MQTT persistent session keeps the messages a client missed only as far as the broker keeps them. Here every record is stored once and a week offline costs one position, the same as a minute, bounded by the channel’s retention.

iot/+/devices/telemetry/#
02

Latest-value state

Know what is true now

Keep one current value per topic, sent on subscribe and available through point reads. An empty payload deletes a value and leaves a tombstone for readers that were away.

Versus plain MQTT. A retained message is a flag a publisher sets, and it arrives only on subscribe. A latest channel is declared by the operator, its deliveries to MQTT 5 clients carry their offset and timestamp, and one value can be read without subscribing.

iot/+/devices/state
03

Work queue

Finish the job

Give each job to one worker at a time. The worker answers ack or return; failed attempts are retried after a fixed, linear or exponential wait, and exhausted jobs move to a dead-letter channel.

Versus plain MQTT. In MQTT, PUBACK means the bytes arrived, not that the job was done. A queue adds an application acknowledgement, a visibility timeout, an attempt count and dead letters.

iot/+/work/+
+
Everything else follows MQTT. A topic no channel claims goes to $broadcast, a reserved append channel: every message is stored, whatever its QoS, and each session keeps one position on it. Retained messages are a flag on those records, with their own size limit and lifetime.
How the three channel types differ, and how to use them

The one idea worth stealing

A position,
not a copy.

Sagüin stores every message once, in its channel’s log, and keeps a position per consumer, stored for durable sessions: the same idea as a Kafka consumer group’s committed offset, without the cluster.

A week offline costs the same as a minute: one number either way. Nothing fills per client, because there is no per-client copy. Retention still removes old records; when it passes records a consumer was owed, the consumer continues from the oldest surviving record and the loss is counted. A seek to a time retention has already passed answers below-floor.

Read the delivery rules

One rule shapes the broker

Stored before acknowledged.
A reply confirming a change waits until that change is committed to the store. Where Sagüin cannot honour a request, it refuses rather than accepting and quietly doing less, with a reason code wherever MQTT allows one.

What makes it different

Bounded, and honest about it.

Every resource the broker holds has a limit, set by configuration or by the disk. Where a promise meets a limit, the design says what happens.

01

Restart keeps what was stored

A restart recovers what its storage mode kept: durable sessions, positions, in-flight messages, Wills, retained flags and queue attempt counts. A damaged database stops the broker rather than serving from it.

02

Three storage modes

full syncs every commit; normal syncs every sync_interval, 1 second by default; memory runs from a RAM copy, snapshotted to disk every 30 minutes by default and at a graceful stop.

03

Overload slows admission

When the broker falls behind on delivery work for consumers that have caught up, it pauses new publications while that work catches up, and separate budgets bound message bytes in transit. Slow, disconnected and replaying consumers remain subject to retention.

04

Access shaped by the data

One acl_file grants each role write, read and seek on a stream, consume on a queue, write and read on a latest value, with rules that follow the client, such as events/%u/#.

05

Losses are counted

When retention passes records a consumer was owed, the consumer continues from the oldest surviving record and the loss is counted in saguin_missed_total and the position-lost route.

06

Low client lock-in

Devices speak MQTT 3.1.1 or MQTT 5. Sagüin’s own operations use standard packets, properties, response topics and ordinary subscriptions.

What Sagüin is not

Small on purpose.

The useful boundary of a system is part of the product. Sagüin does not hide its trade-offs behind broad claims.

01

One node

One node and one process. No clustering or automatic failover.

02

At-least-once

At-least-once delivery at QoS 1 and 2. No exactly-once processing and no deduplication by message id. Workers must be idempotent.

03

Edge scale

Thousands of connections rather than millions. limits.max_connections defaults to 10,000.

04

No UI inside

Sagüin viewer is a separate client you run beside the broker.

05

Explicit durability

full keeps everything acknowledged through a crash or a power cut. normal keeps it through a broker crash; a power cut or an operating-system crash loses at most the commits since the last sync. memory restarts from its last snapshot.

06

Early release

0.2.0 is an early release: run it where you can watch it, and tell us what breaks.

If plain publish/subscribe and retained messages are all you need, any mature MQTT broker will serve you well. Sagüin earns its place when you also need the replayable log, the state store or the work queue. If you outgrow one node, a clustered streaming platform such as Kafka is the natural next step.

Sagüin viewer dashboard showing broker and channel activity
Companion viewerLive broker data

Inspect the claim

Run the system,
not the slide deck.

The repository publishes its design, configuration, metrics and storage documents, the MQTT standards it is tested against, its measurements and runnable examples.

  • Guided tourBroadcast, append, latest, queue and storage, with a broker of its own; the full tour adds security, partitioning, refusals, retries and dead letters.
  • Home automationTwo stock gateways, zigbee2mqtt and rtl_433, publishing through Sagüin from emulated radio hardware.
  • Bento connectorsTwo Bento pipelines moving readings from 200 simulated devices through Sagüin into Kafka.

Measured

100 publishers and 100 durable subscribers at QoS 1, each record going to 10 subscribers, 256-byte payloads, half the publishers at QoS 0 and half at QoS 1, over loopback with the load tool on the same machine. The store in full mode, every commit synced before it is acknowledged. The checks reported no lost, duplicated or reordered messages in those runs. They do not establish behaviour under every failure.

MachineDriveAs fast as the clients can, deliveries/sTen minutes at a fixed rate, publications/s kept upBroker memory at peak
AMD Ryzen 7 260, 16 logical cores, 56 GBconsumer NVMe, ext4165,62812,400, every second40-60 MiB
AMD A10, 4 cores, 13 GBSATA SSD, Btrfs, copy-on-write off31,7942,000, every second47-91 MiB
Raspberry Pi 4 Model B, 4 ARM cores, 4 GBSSD over USB, ext414,9751,100, every second47-54 MiB

On the two four-core machines the broker shared its cores with the load tool, and one store writer’s CPU was the limit. On the Ryzen, a backlog of 1,000,000 QoS 1 publications for away subscribers drained at 83,424 to 86,898 a second when they returned. What it does not establish is a capacity. These are single runs of one recipe, on these machines; make load runs the same recipe on your own hardware.

Get started

From clone to working demo.

Build the broker from source, then run the guided tour or one of the two stack demos, which pull the Sagüin and viewer images from GitHub’s container registry. Run the stacks one at a time: both publish MQTT port 1883.

  • The guided tour. Broadcast, append, latest, queue and storage, against a broker the tour starts itself. make demo-full adds every deep dive.
  • Home automation. zigbee2mqtt and rtl_433, two stock gateways, publishing through Sagüin from emulated radio hardware. No radio needed.
  • Bento to Kafka. Two Bento pipelines move readings from 200 simulated devices through Sagüin into Kafka, with Prometheus and Grafana. The first build downloads source, dependencies and images and can take several minutes.
GitGo 1.27.2+Makegcc, static glibcPython 3 with venvDocker Compose, for the stacks

0.2.0 is an early release. Run it where you can watch it, and tell us what breaks. The quick start starts a broker of your own with one channel of each type. Release binaries are built for Linux on 64-bit x86 (amd64) and 64-bit ARM (arm64), with a container image for both at ghcr.io/ifnesi/saguin. Sagüin is 64-bit: a Raspberry Pi needs a 64-bit operating system (a Pi Zero 2 W, a Pi 3 or later). On macOS or Windows, run the container image, or on Windows the Linux binary under WSL2.

shell
# Build the broker; the stack demos pull the
# Sagüin and viewer images from ghcr.io
git clone https://github.com/ifnesi/saguin.git
cd saguin
make build

# 1. The guided tour, with its own broker
python3 -m venv .venv
. .venv/bin/activate
pip install -r examples/requirements.txt
make demo

# 2. Home automation, viewer on localhost:4001
cd examples/home-automation
docker compose up -d --build
docker compose down

# 3. Bento to Kafka, viewer on localhost:4000
cd ../bento-connectors
docker compose up -d --build
docker compose down
$ Each stack runs until docker compose down in its folder.

Companions, not dependencies

Use the pieces you need.

Sagüin remains a broker speaking MQTT. The viewer and client libraries are separate projects in repositories of their own. No SDK is required.

Visual client0.2.0

Sagüin viewer

A browser dashboard and a terminal screen for a live broker: channels, topics, payloads through their registered schemas, queues and dead letters, read from outside the broker.

Python0.2.0

saguin-python

Optional conveniences over Eclipse Paho. The wire remains standard MQTT; the library is not required.

JavaScript0.2.0

saguin-js

The same channel operations for MQTT.js, with matching verbs across the Python and JavaScript clients.

Contact

A personal project,
for now.

If you need more information about Sagüin, you can reach out to its maintainer on LinkedIn.

Connect on LinkedIn