Flotilla — Push Notifications

Flotilla Push arrives in Flotilla 1.1 — it does not exist in the current 1.0 release. This page documents how it will work when it ships; it's opt-in (off by default) and requires Flotilla Pro.

Flotilla Push is an optional, paid feature that sends alerts from your Unraid or Proxmox VE server to your iPhone even when the app isn't open. It's the one part of Flotilla that isn't a direct connection from your device to your server — turning it on adds a relay in the middle. This page explains exactly what that relay does and doesn't see. See also the privacy policy.

How it works

In plain words: your server → the relay → Apple → your phone.

• On Unraid, the Flotilla Agent plugin hooks into Unraid's own notification system. Each event is encrypted on the server, locally, with a key that only your paired iPhone has, then sent to the relay. A heartbeat every 60 seconds tells the relay the server is alive.
• On Proxmox VE, the same thing happens via flotilla-beacon, a small daemon you install with a one-line script — it receives Proxmox's native webhook locally, encrypts it, and forwards it. If you skip the beacon, Proxmox's webhook can instead post straight to the relay with no local encryption step; see the plaintext exception below.
• The relay's job is to hold your device's Apple Push token, enforce a few abuse caps, run a dead-man's-switch off your heartbeats, and forward whatever it received — encrypted or not — to Apple's Push Notification service (APNs).
• Apple delivers the push to your phone, where a Notification Service Extension decrypts it (if it was encrypted) before you see it.

What the relay can and cannot see

Can see:

• Your pairing ID — a random UUID, not tied to your name, email, or Apple ID.
• Your device's Apple Push token(s) — up to 10 per pairing.
• Timing: when your server sends events and heartbeats, and how often.
• For encrypted events, the size of the ciphertext — not its contents.
• A one-time cryptographic proof, checked at enrollment, that your device has an active Flotilla Pro purchase — not your Apple ID, not payment details, just a signed Apple transaction the relay verifies and discards. That signed transaction does technically carry a couple of other fields alongside the purchase proof itself — a stable-but-pseudonymous originalTransactionId (Apple's own purchase identifier, not tied to your Apple ID or name) and a storefront (your App Store country) — but the relay never reads, logs, or persists either one; it verifies the signature and discards the whole transaction on the spot.
• For the beacon-less Proxmox path only (Proxmox's webhook posting straight to the relay, without flotilla-beacon installed): the actual event title, message, and severity, in plaintext. There's no local encryption step in that path, so this is the one place in Flotilla Push where your server's event content genuinely isn't private from the relay operator.
• The relay runs on Cloudflare. Like any hosted service, that means the network layer sees the source IP address of requests reaching it — from your server and from your phone — simply to deliver them; our own code neither logs nor stores it.

Cannot see (Unraid via the plugin, and Proxmox via flotilla-beacon — both take the encrypted path):

• What your alert says. The event's subject and description are sealed (ChaCha20-Poly1305) on your server before they ever leave your network, with a key that exists only in your server's local config and your phone's Keychain. The relay only ever handles ciphertext it cannot decrypt — even the placeholder text it puts in the outgoing push ("Flotilla" / "New server event") is a fixed dummy string, never your real content.
• Your server's address, hostname, or any credential. Your Unraid API key and Proxmox API token never leave your LAN — the relay never receives them and never asks for them. Your server's name is embedded in the pairing QR code for the app to display locally; it's never sent to the relay.
• Who you are. There's no account, login, email, or personal identifier — only a random pairing ID and a Push token.

Apple sits downstream of the relay and necessarily sees whatever is in a push's visible alert text, the same as any app that sends notifications: for encrypted events that's the inert placeholder above; for the beacon-less Proxmox path it's your real title and message, same as the relay. Apple also sees ordinary delivery metadata (device token, timestamp) for every push — that's inherent to how APNs works, not specific to Flotilla.

Self-hosting & continuity

Both halves of this feature — flotilla-agent (the Unraid plugin and the Proxmox beacon) and flotilla-relay (the relay itself) — are MIT-licensed and will be published as open source on GitHub at launch. The relay URL isn't hardcoded: it's a config value in the Unraid plugin's settings page, in the beacon's config file, and in the iOS app itself, so you can point any of them at a different relay.

Honesty note on where the bits come from: the Proxmox beacon's install script and its binary releases are fetched directly from the flotilla-agent GitHub repo (raw.githubusercontent.com and GitHub Releases), not proxied through the relay. The relay only ever handles the pairing/push traffic described above.

To be honest about what that actually buys you: repointing the URL alone doesn't get you a fully independent setup. Delivering to Apple requires the relay to hold its own Apple Push Notification service credentials and its own App Store transaction verification, both tied to a specific app bundle ID — credentials that can't be shared between deployments. So a self-hosted relay only delivers push for a build of the app registered under its own operator's Apple Developer account, not for the official App Store build of Flotilla. If the official relay ever goes away, the realistic continuity path is a community fork: someone stands up their own relay and publishes their own signed build of the app, and anyone who wants to keep using Push moves to that fork — not a simple settings change. Every other part of Flotilla (your direct connections to Unraid and Proxmox VE) needs none of this and keeps working regardless of what happens to Push.

Reset / revoke

"Reset pairing" (the Unraid plugin's settings page) and re-running Proxmox push setup for an already-paired server (Flotilla → Settings → Notifications) both revoke the old pairing at the relay — every key it holds (device tokens, heartbeat state, everything) — before the new one takes over, rather than leaving it to linger there unused. This revoke is best-effort: it never blocks the reset/re-pair itself, which always completes locally regardless, so if the relay happens to be unreachable at that exact moment, the old pairing may persist there rather than being cleanly wiped. Unpairing a single device (swiping it away in that same screen) is narrower and unaffected by this: it only removes that one device's Push token from the relay, the same best-effort way.

Caps

Per pairing, to keep a misbehaving script or a flapping server from turning into a notification storm:

• 60 event pushes/hour and 500/day.
• "Server unreachable" alerts capped at 3/day — the dead-man's switch isn't a periodic check: every heartbeat rearms a roughly 3-minute timer at the relay, and it pages you only if that timer is ever allowed to expire (your server goes quiet). It won't spam you if a connection flaps all day.
• At most one "notification cap reached" notice per day, so you know when you've hit the ceiling instead of alerts silently vanishing.
• Heartbeats themselves don't count against any cap.
• Up to 10 paired devices per server.

Contact

livinmathew99@gmail.com