One governor, three paths

A homelab that alerts by SMS needs a phone number. The fleet’s answer is a gateway: one small service, sitting between a consumer mobile line and everything that wants to use it — an operator replying to a message, a critical alert with nowhere else to go, someone texting in from outside the lab entirely. All three go through the same code, for a reason that has nothing to do with code reuse.

Drafted by an AI agent (claude-opus-5) from this lab’s own runbooks, deployment log and errata. Reviewed before publication by the site owner. How this site is written →

What it actually does

Three paths, one direction each:

PathDirectionHow
Email to SMSan operator replies from a mail clientpoll a catch-all inbox, relay to the handset
SMS to emailsomeone texts the numberpoll the handset for new messages, relay by mail
Alert to SMSa critical alert firesa local, LAN-only endpoint, straight to the handset

Two of those cross the public internet — mail does, both directions. The third does not, on purpose: the alert path exists specifically to survive a WAN outage, so making it depend on the WAN it’s meant to route around would defeat the point.

Why one governor for all three

The handset is a real, consumer mobile line, not an API with a quota. Send too fast and a carrier doesn’t return a 429 — it flags the number and the line stops working, silently, with no error either system was watching for. If the alert path and the reply path each tracked their own rate independently, both could look healthy by their own accounting while together they’d already spent the line’s entire budget. So every outbound message — a reply, an alert, anything — passes through one rate governor and one dispatch ledger, regardless of which of the three paths it came from. There is exactly one place in the code that decides whether a message goes out right now, and every path answers to it.

Why an address alone doesn’t get to send anything

The reply path accepts email from an operator and turns it into an SMS. That sounds simple until the question becomes: whose email. A bare reply-to address is trivially spoofable, and carrier email-to-SMS gateways becoming a spam vector is exactly what happens when an address alone is treated as proof of who’s asking. The reply address here carries an HMAC over the sender and the original message, minted by the gateway itself when it sends the first leg. Nothing external can construct a valid one, so nothing external can originate an SMS by simply emailing the right-looking address.

What “ask the process” means here

Every deploy ends by asking the running service what it actually loaded, not by reading a log line or checking that the process is up. systemctl is-active says a process exists; it says nothing about whether that process is running the code that was just shipped, or whether the thing it depends on to reach a real carrier is actually wired in. The gateway answers both questions itself, live, on every deploy — which turned out to matter the first time a deploy skipped a restart it didn’t need and the old way of checking broke in a way nobody had anticipated. That failure, and the fix, is its own post.

The shape of it
email (operator reply)  --IMAP poll-->   \
SMS (someone texts in)  --device poll--> | one governor, one ledger --> handset
Grafana (critical alert)--LAN only----> /

Deploy is pull, not push: the host fetches its own code, runs the test suite on itself, swaps, restarts, and then asks the running process what it loaded before calling the deploy done. A drop in how many tests pass against the last deployed count refuses the deploy outright — a stale branch is green and simply has fewer tests, which passing alone can’t distinguish from a healthy one.

What it costs

Nothing here proves a message reaches a phone. Every guard in this design — the rate governor, the HMAC, the live-process check — verifies that the gateway did its part correctly. None of them can see past the handset’s own API to the tower, the carrier, or the recipient’s signal. That gap is a property of using a real consumer line rather than a dedicated business SMS API, and it’s accepted rather than solved: the design optimizes for not getting the number flagged or spoofed, not for end-to-end delivery proof.

What would change the decision

If the lab ever needed guaranteed delivery receipts — proof a specific message reached a specific phone, not just that the gateway handed it to the handset — that would argue for a dedicated carrier API instead of a consumer line behind a local relay. Nothing today calls for that; the alert path exists to survive outages, not to produce an audit trail.