Operate

Notifications

Omnesis keeps notification text on your gateway. Apple's and Google's push services, and the hosted relay, carry only a content-free wake; the phone then fetches the notification from the gateway itself. This page lists what sends a notification, explains that privacy boundary, and covers delivery setup and repair for operators. With the official iOS app, installed through TestFlight, there is nothing to set up beyond approving notifications on the phone. If you built and signed the app yourself, see Configure direct delivery.

What sends a notification

Notifications go to your paired phones. Each one is about something waiting for you on the gateway:

The two kinds of reminder repeat until the problem is fixed. Re-auth needed is sent once per account per device when its sign-in lapses, then again after 1 day, 2 days, 4 days and 7 days, and weekly after that, until that device signs in again; tune the schedule with gateway.reauthReminders (initialDelay, multiplier, maxDelay).

A permission reminder names the source, the affected phone and how to fix it. If the phone simply stops reporting, the reminder says Source check overdue instead, because silence does not prove a permission was revoked; for a source several phones contribute to, that happens only when all of them are quiet.

Permission reminders repeat after 1 day and then at doubling intervals capped at a week, until the source recovers; overdue reminders stop after four. The schedule is gateway.mobilePermissionReminders. Turning the source off, removing it, or revoking the phone clears the reminder. Any of your phones can show it, but only the affected phone opens the repair controls; another phone names the device where Omnesis must be opened.

The privacy boundary

A carrier wake contains a generic Omnesis placeholder and no notification kind, title, body, document identifier, conversation identifier, or collapse key. All wakes for a platform have the same carrier-visible shape. If the phone cannot reach the gateway, iOS leaves the generic placeholder; Android can show a fixed local connection notice. Neither reveals why the notification was sent.

Wakes arrive wherever the phone is, but the notification text still requires the phone to reach its paired gateway. Nothing carries the text off your network. If the phone was paired to a LAN address, set up remote access and pair it again using an address it can reach away from home.

Delivery flow

Each phone can fetch only its own notifications. A notification is marked delivered only after the phone has shown it, so a dropped connection loses nothing. A newer notification about the same thing replaces an older one that has not been shown yet. When the app has a live connection to the gateway, the wake travels over it instead of the push service.

Failed wakes are retried with growing delays — from 5 seconds, doubling up to 5 minutes — for about an hour. Undelivered notifications expire after a week, and the phone fetches any still waiting the next time the app opens or reconnects, wake or no wake. omnesis push status shows attempts and the last outcome.

Choose a notification transport

The correct transport depends on who signed the app. Every choice keeps notification content on your gateway; only the fixed, content-free wake crosses APNs, FCM, or the hosted relay.

What counts is the app identity, not how the app was installed. An app built from source with the official iOS identity and signed by a team authorized for it can use the relay, provided its APNs environment matches. A contributor using an unrelated Apple team needs their own app identity and uses direct APNs delivery.

Allow the hosted relay for an official app

Your own APNs or FCM credentials cannot cover an official build, because they belong to a different app identity. When the paired phone needs the hosted relay, it explains the boundary and asks you to allow relay notifications for that phone. Nothing is enabled for another phone, and no push token leaves the phone before its gateway records that approval.

During enrollment, the relay receives the phone platform, its device push token, the public Omnesis app identifier and, on iOS, the APNs environment. The phone makes that request itself, so the relay also sees the phone's network address at enrollment. Afterward, the gateway sends the relay an authenticated request with an empty body so APNs or FCM can deliver the fixed wake. The relay never receives notification text, the gateway address, an Omnesis account, or which notification fired.

Review each phone's transport under Settings → Devices in the portal. Withdrawing relay access there stops relay delivery immediately and leaves every other phone unchanged. The affected phone may ask for approval again later.

The default endpoint is https://push.omnesis.app. Operators of a compatible relay can select another HTTPS origin with omnesis config set /gateway/pushRelay/url https://push.example.com. A self-built app whose identity is not supported by that relay should use direct delivery.

What the hosted relay is, and is not

The relay is a dependency of the official apps. A background wake for one of them, while the app holds no live connection to the gateway and no direct credential covers it, goes through the relay. It is run by the Omnesis maintainer. The gateway sends it wakes for exactly the two official app identities, the iOS app and the Android app on Google Play, and never for any other. Pointing the gateway at another relay URL changes where wakes go, never which apps the gateway will wake; phones registered against the previous URL register again the next time the app opens.

Beyond the enrollment data above, what the relay learns is what any server learns from a connection. Payload minimization keeps the content, the notification kind and the gateway's address out of every request. It does not hide that a wake happened, when it happened, or the network address the gateway's request came from; the relay's hosting and network providers see those as they see any request. A gateway on a private network reaches the relay through whatever address that network presents to the Internet.

No availability, latency or support commitment is published for the relay. If it cannot be reached, the gateway retries the wake for about an hour, then stops trying; the notification itself waits on the gateway for a week and reaches the phone when the app next opens. The independent option is direct delivery with your own APNs or FCM credentials for an app you sign yourself, which depends on Apple's and Google's services instead of the relay.

Configure direct delivery for self-built apps

A self-built iOS app under your own App ID needs Apple Developer Program membership, an App ID under its signing team, Push Notifications enabled, and a matching provisioning profile. The gateway needs an APNs .p8 authentication key, its Key ID and Team ID, and the actual bundle identifier of the installed app. Android direct delivery uses a Firebase service account whose project id matches the build. The gateway selects credentials for the app identity each phone reports; a credential for another build is not used.

For iOS, have two distinct Apple keys ready: the APNs auth key used for delivery and an App Store Connect API key allowed to manage Certificates, Identifiers & Profiles. The wizard also asks for the management key's Key ID and issuer ID. It looks up the exact bundle id, verifies that its App ID carries Push Notifications, and enables the capability when missing. The management key is used for setup, not for every push. If the capability changes, refresh the provisioning profile and rebuild the app. Choose sandbox for a normal Xcode development build and production for distribution; the gateway setting must match the signed app's provisioning environment.

For Android, have the Firebase service-account file plus the Android package id and the four client values from the Firebase app configuration: application id, API key, project id, and sender id. The wizard writes the client values to local.push.properties in the Android project directory you give it (android/ from the repository root), on the machine running the CLI. That owner-only file is gitignored and Gradle reads it automatically, including the chosen package id. Rebuild the app after setup; the installed app's package id and Firebase registration must match the package id entered in the wizard. No shell exports or committed google-services.json are needed.

Tapping the test notification opens the app. When an all-phone test reaches some phones but not others, the command reports partial success and exits non-zero so scripts do not mistake it for complete delivery.

The APNs .p8 or Firebase service-account path you enter in the CLI is sent to the gateway, which reads the file on its own host and imports it into its configuration directory with owner-only permissions. A file on a laptop running the CLI is not uploaded, so for a remote or containerized gateway, first place the key at a path the gateway process can read. The App Store Connect key is read by the CLI itself and never sent to the gateway. Setup updates gateway.apns or gateway.fcm and switches to the new credential without restarting the gateway.

Open the app on each phone afterward so it picks up the new delivery path and registers its push token; there is no token to copy by hand. If notifications are off on the phone, turn them on from the app's setup flow or its Settings; the app does not prompt on its own. A notification that arrives while the app is open proves only the live connection, not background APNs or FCM delivery.

Status and repair

Status shows credential metadata without secret contents and counts phones by their transport. A phone without a usable transport is reported with the one thing that is missing; both omnesis push status and omnesis doctor name it. The push status lines read:

• relay notifications are not approved on this phone: an official app is waiting for the phone's owner to allow relay notifications. Open the app on that phone and review its disclosure.
• no push credential covers <app id>: the app is signed with an identity the gateway never sends to the relay. Add your own APNs or FCM credentials with omnesis push setup, confirm that the configured bundle or package id exactly matches the build, or use an official build. Changing the relay URL does not help.
• relay URL is unavailable: check gateway.pushRelay.url (omnesis config get /gateway/pushRelay/url).
• push registration is broken: the transport is fine but the phone's registration is not. Opening the app redoes it.

The apps also report whether they can show notifications, without any notification content, so status and doctor tell a missing transport apart from notification permission being undecided or denied, alerts being disabled, or iOS Scheduled Summary batching Omnesis notifications. The gateway queues no notification for a phone whose permission is undecided or denied, or whose alerts are disabled. Scheduled Summary still receives notifications but may delay the banner.

A phone that has not reported its state still receives ordinary notifications but not permission reminders; open the app once so it reports. If a pairing belongs to a phone you no longer use, remove it with omnesis devices revoke <device-id>.

On the phone, the iOS app shows the gateway's selected delivery path in Settings → Notifications. If its app identity has no matching direct credential, it shows that identifier and links to setup; this is a configuration warning, not a background-delivery test. The Android app shows missing Firebase build values or an uncovered package id in its app-wide warning and explains the problem in Settings → Notifications. Build values require a rebuild; gateway credentials can be configured with omnesis push setup and rechecked with Retry. A notification-permission warning opens Android notification settings; returning to Omnesis rechecks delivery and shows any notification that was held while alerts were disabled.