Profile
Back to NewsBack
GitHub Trending 40 min
Reader Mode
kaishi00/hermes-conduit-notifier: Hermes plugin for Hermes Conduit push notifications

kaishi00/hermes-conduit-notifier: Hermes plugin for Hermes Conduit push notifications

18 hours ago

Hermes Conduit Notifier

Hermes Conduit Notifier is the open-source Hermes plugin that connects a Hermes host to the Hermes Conduit iPhone, iPad and Apple Watch app. It started as the notification sender and now carries most of what Conduit needs from the host:

  • Notifications and calls: approval, input, reply, failure and background-task notifications, Hermes calling you (CallKit on the phone and Watch), and Lock Screen progress while a turn runs, all delivered through the Conduit push relay in relay/, end-to-end encrypted where APNs allows.
  • Live voice: single-use Gemini Live tokens, temporary Qwen Live credentials, GPT-Live sessions on the host's ChatGPT subscription or API key, Grok Live relayed with the host's xAI sign-in, Local Live and Classic voice through your own speech server, voice web lookups, memory and personality for voice, and saved call transcripts.
  • Apple Watch: short-lived grants that let a Watch call run lookups and Hermes jobs, answer what Hermes waits on in a call from Hermes, and stream GPT-Live, Grok and Local Live audio, through the relay, sealed end to end.
  • Phone data the user opts into: Apple Health, location, maps, calendar, reminders, Focus, phone status, contacts, alarms and the Shortcuts Hermes may run, sent by the phone straight to this host and sealed end to end, with the conduit_health, conduit_location, conduit_maps, conduit_calendar, conduit_phone and conduit_contacts tools for the agent, and events from the user's Shortcuts automations through conduit_inbox.
  • Conduit extras: rich cards and on-screen cards during calls, Artifacts and the chat's Folder, group pictures, chat takeover, cron notification settings, Conduit settings the agent can change, and one-tap pairing and updates from the app.
Every route sits behind the Hermes dashboard's own auth. The plugin holds no Apple Push Notification service key and no dashboard credentials: Apple credentials stay on the push relay, so self-hosted users never need to copy a shared signing key onto their gateway, and provider keys and sign-ins never leave this host. What each party can see is in the privacy policy.

Install

Run these commands on the machine where Hermes is installed:

hermes plugins install kaishi00/hermes-conduit-notifier --enable
hermes gateway restart

The plugin follows the current Hermes release, and every change is checked against Hermes' own install scan. A Hermes from before v0.21.6 (the date-numbered releases, v2026.9.24 and older) has an older scan that reads the plugin's test fixtures as live code, and it refuses the install as dangerous or asks you to confirm it. Run hermes update first, then install.

In Hermes Conduit, open Settings > Notifications, enable notifications, and create a pairing code. Claim it from the matching Hermes profile:

hermes conduit-push pair XXXXX-XXXXX

Pair additional profiles independently. Turn the plugin on for the profile, restart the main gateway, whose copy of the plugin links the profile to it, then restart the profile's own gateway if it runs one, so its chats load it:

hermes -p coder plugins enable conduit_push
hermes gateway restart
hermes -p coder gateway restart
hermes -p coder conduit-push pair YYYYY-YYYYY

plugins enable finds only a plugin in the profile's own plugins/ folder. A profile made without --clone has none until the dashboard links it, which it does only for a profile that turned the plugin on, so for such a profile add conduit_push to plugins.enabled in its config.yaml instead (and take it out of plugins.disabled if it is there), then restart as above. Until then Hermes answers that profile's plugin requests with "Plugin not found", and Conduit says so on the screen that asked.

Conduit can do this for you (plugin 0.181.0+): a bot made with Conduit's New Bot gets the plugin turned on, and Edit Bot shows Turn On for a bot that has it off. The dashboard links the profile to the main install and runs hermes -p plugins enable conduit_push for it (POST /api/plugins/conduit_push/profiles/plugin). Hermes' enable has the running gateway load the plugin, so no restart is needed.

A profile's chats load plugins from that profile's own plugins/ folder only, so with plugin 0.122.2+ the dashboard links every profile that turns the plugin on to the main install (~/.hermes/plugins/conduit_push) when it starts, and again when Conduit updates the plugin; the main gateway does the same when it loads the plugin. Every profile then runs the version you updated to. A profile with its own gateway runs it once that gateway restarts, and until then may fail or mix versions, so restart it after an update. As the profile's folder is a link, hermes -p plugins remove conduit_push removes only the link, and plugins update updates the main install. A copy a profile had of its own (hermes profile create --clone copies the plugins folder) is moved to the profile's plugins-backup/ folder, never deleted, unless it's newer than the main install, which leaves the profile alone. Where the host can't make a link, the main install is copied in instead and replaced at the next update.

A host that manages the plugin (plugin 0.146.0+)

When something other than Conduit installs and upgrades the plugin (an image that bakes a pinned version, a configuration manager), set CONDUIT_PUSH_MANAGED in the dashboard's environment: 1 (or true, yes, on) for a plain "managed", or a short text naming who manages it, such as CONDUIT_PUSH_MANAGED="Family farm". The capabilities route then reports "managed": true (and "managed_by" for a text), Conduit asks nobody to update the plugin on that host and says who keeps it up to date, and POST /self/update pulls nothing: it answers 409, or, when the copy the host put on disk waits for its restart (plugin 0.147.2+), runs only the gateway's and the dashboard's restarts, as an update would. Leave it unset (or 0) for a plugin you update from Conduit.

A host without direct internet access (plugin 0.172.0+)

On a network where only this plugin should reach the internet, set CONDUIT_PUSH_PROXY in the gateway's and the dashboard's environment to an HTTP proxy and restart them, such as CONDUIT_PUSH_PROXY=http://proxy.internal:3128 (an https:// proxy and a user:password@ in the URL work too). The plugin's own HTTPS and WSS traffic then goes through it: the relay (notifications, calls, Lock Screen progress, pairing), the Watch's relay socket, the rooms mailbox, Apple Maps lookups, and the voice providers the host calls (Gemini, Qwen, GPT-Live, Grok, an https:// Local Live front model or wss:// speech server). The rest of Hermes doesn't use it, unlike a process-wide HTTPS_PROXY, which the plugin also follows when this is unset.

Plain HTTP and WS never go through it (loopback, a LAN or Tailscale pairing claim, a speech server on your LAN), and a host named in NO_PROXY is reached directly. SOCKS proxies aren't supported; most proxy clients also offer an HTTP port. A value that isn't an http:// or https:// proxy URL is ignored with a warning in the log, and hermes conduit-push status shows the proxy in use (without its password) or why it was ignored. WSS through the proxy needs websockets 15 or newer in Hermes' environment. Proposed by aminrpg (#746).

Pairing codes expire after ten minutes and can only be claimed once.

With plugin 0.24+ Conduit pairs the active dashboard's profile by itself: it creates the code and hands it to POST /api/plugins/conduit_push/pair?profile= over your signed-in dashboard connection (see Pairing from Conduit).

Manage the pairing

# Show status without printing the credential
hermes conduit-push status

Send a local test event through the relay

hermes conduit-push test

Redact chat text from pushes (see Privacy and security)

hermes conduit-push redact on

Revoke this profile's credentials, on every device it notifies

hermes conduit-push unpair

Update the plugin and restart Hermes:

hermes plugins update conduit_push
hermes gateway restart

The dashboard imports the plugin's routes once, so restart the dashboard as well (or let Conduit do it: Settings > Conduit plugin > Update runs Hermes' own plugin update, the gateway restart and the dashboard restart).

On the Hermes dashboard (plugin 0.74+)

The dashboard's Sessions page shows a Conduit card at the top, once Conduit has used this host. Hermes' own Connected Platforms card lists only the gateway's messaging adapters (Matrix, the API server), and Conduit talks to the dashboard instead, so it gets its own card:

  • App: Connected while a Conduit gateway socket that opened a chat is
open, or within 5 minutes of Conduit's last request to this plugin; Idle after that, with when it was last seen.
  • Push notifications: Delivering (with the last push's time), Failing
(with a short reason: the relay unreachable, its answer, a certificate), Refused or Blocked (the same marks status reports), Paired with nothing sent yet, or Not paired.

It reads GET /api/plugins/conduit_push/link-status every 30 seconds. The times live in conduit-link-status.json in the profile's Hermes home, written at most once a minute each; it holds no credential or relay address.

Events

The plugin currently emits notifications for:

  • approval needed
  • clarification or other input needed
  • response ready, once the turn has ended: a turn that failed sends only its failure notice, not Hermes' error text as a reply (plugin 0.35+)
  • failed turns
  • completed background tasks: a delegated task that ends while the turn that started it is still running is part of that turn's reply and sends nothing of its own (plugin 0.35+)
  • calendar and reminder changes Hermes asks your phone to make (see Calendar, Reminders, Focus and phone status): a notification to approve, or a silent wake for adds you let Hermes make without asking
  • call requests: a job you asked to be called about has ended, Hermes asked to call you, or (alert calls) Hermes has waited a minute on your approval or answer, or a turn failed (see Hermes calls you)
  • room invites, to a Conduit that shows them: someone you've linked invited you to a room (plugin 0.105+, relay 0.21+; see Rooms with people you've linked). Your agents' turns in a room someone else hosts send no reply or failure notification, since the room shows them. In a room this Hermes hosts, a turn's reply, failure, finished background task and approval open the room, titled with its name, not the bot's hidden chat there (plugin 0.150.1+), and a lead's pick of who answers sends nothing.
A turn in a session Hermes doesn't list as a conversation sends no reply, failure or background-task notification and shows no Lock Screen progress (plugin 0.153.7+): a script's hermes chat --source tool, a one-shot hermes chat -q or -z, and a Kanban worker. Their answers go to whoever ran them, and Conduit's chat lists hide those sessions. An approval or question from one still notifies, and so do a call you asked for and a notification the run wrote with conduit_notify.

A fork of a chat never notifies as the chat (plugin 0.119.1+): Conduit's predictions (/predict), a step summary's /btw and the self-improvement review each answer from a fork that runs under the chat's session id, and on a Hermes that runs plugin hooks for forks (0.21 among them) the plugin keeps the fork's answer from going out as a reply and off the chat's Live Activity. An exact [Silent] assistant response does not emit a completion notification. Reply and task bodies are sent as plain text: Markdown fences, emphasis, headings, link targets and table rules are dropped (plugin 0.35+). No notification shows a file's path on the host (plugin 0.71.2+): a MEDIA: tag in a reply, a question, an approval, a call or a phone change, and in the answer card or call screen that comes with it, reads as 📎 and the file's name, or its type (📎 PPTX) when the name is only a hash, and [[audio_as_voice]] and [[as_document]] are dropped. A Hermes Desktop directive reads the same way (plugin 0.120.4+): a page shown with ::preview{file="…"} as its file, and a Desktop plugin's card, such as hermes-rich-ui's ::richui{id="…"}, as 🗂 hermes-rich-ui card. Code in a reply's fenced block stays as written.

Cron runs (plugin 0.33+)

A cron run notifies like any other turn, with two exceptions:

  • A run whose reply is Hermes' cron silence marker doesn't notify, by the same rule Hermes uses to skip delivering it: [SILENT] (or SILENT / NO_REPLY) as the whole reply, on its own first or last line, or opening the reply ([SILENT] No changes since yesterday). A marker mid-sentence is real content and still notifies.
  • You can turn a job's notifications off in Conduit's Cron tab. Its runs then send no reply or failure notification (and no automatic alert call; a call you asked for on the job still rings). The muted job ids live in the profile's conduit-cron.json; GET /api/plugins/conduit_push/cron/notifications lists them ({"ok": true, "muted": [...], "act": [...], "shows_reports": true}) and PUT with {"job_id": "...", "notify": false} changes one. Capability cron-notifications.
The plugin tells a cron run by its task id (cron::…) or its classic session id (cron___).

Cron jobs delivered to a Bot Chat

Hermes delivers a job set to deliver: bot-chat (or bot-chat:) as a turn: the bot reads the report, acts on what needs action and summarizes it, a model call every run. With the plugin, such a job just shows its report in that bot's Bot Chat instead: it's written into the chat as a note, the way Hermes writes a cron result into a local chat, with no turn and no model call, and the bot sees it as context on its next turn. Pick Let the bot act on it for a job in Conduit's job editor to keep Hermes' turn for it. The choice is kept in the job's profile's conduit-cron.json beside the muted jobs: GET /api/plugins/conduit_push/cron/notifications lists the jobs that let the bot act under act, and PUT with {"job_id": "...", "act": true} changes one. Capability cron-bot-chat-reports; the route's shows_reports says whether this Hermes can write the note (Hermes v0.22.5 can't, its canary from late October can), and without it every job keeps Hermes' turn and Conduit offers no choice. A report shows only in a Bot Chat that exists. A picture or file the report delivers on a line of its own (MEDIA:/path) is written as @image:/path or @file:/path, which Hermes Desktop and Conduit show in a note as the picture or the file, and the Artifacts list shows as the run's deliveries; a tag inside a sentence or in a code block stays as written.

Beside notifications, the plugin keeps a Live Activity up to date while a turn you sent from Conduit runs (see Lock Screen progress).

Each notification is titled with the session's title when it has one (for example a Telegram topic name), so you can tell which chat it came from: a reply shows the session title, and the others prefix it (Approval needed · Infra). A Conduit Bot Chat, whose title is always Bot Chat, is titled with its bot's name instead, as Conduit's Bots list shows it (its Bot Mode title, else its display name, else its profile id capitalized, and Hermes for the main bot), so you can tell which bot replied. Conduit shows a name you gave the main bot on the phone instead. Every push also carries that name, so a call from the bot names it too. Untitled sessions keep the generic copy. How much shows is Conduit's Settings > Notifications > Show in notifications: Generic shows neither the title nor the text, Chat names shows the session's title and the profile without Hermes' words, and Full previews shows both, with the profile as the subtitle. redact on or end-to-end encryption keeps the title from reaching the relay.

Hermes can write a reply's notification itself with the conduit_notify tool (plugin 0.112+), when you asked to be told something is done or a scheduled job reports: a title of a few words and a sentence or two, sent instead of the reply's opening when the turn ends (plugin 0.177.30+ shortens a title past 60 characters or text past 300 with "…" rather than refusing it). It sends no push of its own, so the turn still sends one, under the same settings, and a reply that sends none ([SILENT], a muted job, a Bot Chat's answer to a work update that only says a workstream waits on you) sends none with it. The title rides as headline, sealed with the rest, and Conduit shows it only with Full previews; Chat names and Generic never show it. To update a notification instead of adding another ("Report in progress", later "Report ready"), Hermes gives both the same key (plugin 0.123+): the profile's chats and scheduled jobs share it, and quiet sends the update without a sound or banner (relay 0.26+). Each scheduled job also keeps one notification of its own, so a new run replaces the last one.

The iOS app controls which categories are enabled, how much a notification shows, whether completion sounds play, and whether approval and input-needed notifications play a sound (on by default).

Privacy and security

  • Pairing creates a revocable, profile-scoped credential.
  • The credential is stored in the profile-aware Hermes home as conduit-push.json with mode 0600 on supported systems.
  • Authorization credentials are never written to logs or printed by status.
  • Hook callbacks enqueue bounded events; HTTPS delivery runs on a background worker and does not block the agent loop. Two waits are bounded instead (plugin 0.81.2+), for a process that exits right after its turn, such as a restart-safe cron job's worker: a turn end that sends a call request waits up to 3 seconds for it to reach the relay, and the process's exit waits up to 3 seconds for queued notifications and up to 10 for call requests still retrying (call requests first, so a fallback push they queue is among those notifications).
  • A delivery that fails on the way (no connection, a timeout, 408, 429 or a 5xx from the relay) is sent again with the same event ID after 1, 2 and 4 seconds, for at most about 30 seconds per event; the relay drops the repeats it already accepted. One thread delivers the queue (up to 256 events, one per device a profile notifies), approvals and questions ahead of everything else, so they don't wait behind retries of finished-turn notices (plugin 0.177.15+). A queued event goes out only under the pairing that accepted it: pairing again drops what was queued before, and a key rotation doesn't. A sealed push the relay refuses as e2e_clock_ahead (this host's clock more than an hour ahead of the relay's) is sealed again once by the relay's clock, which that refusal's Date gives it. Other refusals are not retried. A 401 means the relay no longer knows this gateway (Conduit removed it, or the relay lost its data): the pairing is kept, and status says to pair again from Conduit until a delivery is accepted again. A 401 or 403 also parks notifications for that pairing (plugin 0.55.1+): events are dropped for 1 minute, doubling with each refusal in a row up to 30 minutes, then the next event goes out as the probe and an accepted one (or an accepted test) ends the pause; a clarify question asked meanwhile uses the native prompt at once (Live Activity reports pause 30 minutes on their own). A 403 with no JSON body comes from something in front of the relay (a firewall or rate limiter) blocking this host's address: status says so instead of telling you to pair again, since a pairing claim meets the same block, and Conduit's pairing status reports it as relay_blocked.
  • Disabling or reloading the plugin (on a Hermes with plugin unload callbacks) stops its background work: notifications still queued and replies waiting for their turn's end are dropped, the delivery and Lock Screen threads end, and a call held until your call ends is kept for the next load instead of going out.
  • The health, location, maps, calendar, phone, contacts, calls, display and inbox (conduit_inbox) tools refuse delegated subagents, including one whose session id a compaction replaced (compression.in_place: false): the plugin asks Hermes' delegation flag (Hermes 0.22+) and follows the compaction links in Hermes' session store back to the subagent it was (plugin 0.51.6+).
  • Event titles and bodies are length-limited before delivery.
  • Lock Screen previews are disabled by default in Hermes Conduit.
  • End-to-end encryption (plugin 0.5+, relay 0.5+, a Conduit build with encrypted notifications): Conduit creates a secret for each pairing on the phone and hands it to this profile over your Hermes dashboard connection, so it never passes through the relay. From then on every notification's title, body, profile (and the bot's name), session and decision card is sealed with it (ChaCha20-Poly1305, keys derived with HKDF-SHA256), the phone decrypts it in a Notification Service Extension, and clarify answers come back sealed for this profile. The relay and APNs see only routing data: the event type, opaque ids, a keyed thread token and timing. Each sealed notification carries when it was sealed, and the phone opens one for a day; dated more than an hour ahead of the phone, it shows only generic text. A host whose clock runs ahead of the relay's seals by the relay's clock instead (plugin 0.127.5+, relay 0.26.1+), which the relay's answers give it, and logs how far off it is; set the host's time (NTP) to fix it. A pairing that has a key never sends plaintext content again, and only accepts clarify answers sealed by the phone: an answer it refuses ends the question at once, and Hermes is told the refused answer didn't count, so it can ask again; a form's other answers that the phone did seal still stand (plugin 0.177.32+). hermes conduit-push status shows whether it's on; Conduit turns it on by itself when it connects to this host. Run hermes conduit-push test --corrupt to check that the phone shows only generic text for a push it can't verify. The secret is only as private in transit as your dashboard connection (HTTPS or a private tunnel is recommended). Keys rotate (plugin 0.71+ and a Conduit build that rotates): Conduit hands over a new secret when the key is 30 days old (7 days with plugin 0.72+), when you tap Rotate in Conduit's Settings > Notifications, or after hermes conduit-push e2e rotate on this host, the next time it connects to the dashboard. Pushes are sealed with the new key at once; the old one still opens clarify answers for 7 days, so nothing in flight is lost. For a key that may have leaked, hermes conduit-push e2e rotate --now skips that overlap; the current key still seals notifications until Conduit next connects, so hermes conduit-push unpair is the way to cut it off at once. A key copied from a backup then stops opening new notifications, though it can still open ones captured while it was in use. From plugin 0.72 Conduit rotates inline instead, every 7 days (POST /e2e/rotate): its request, sealed with the current key, carries a fresh X25519 share and, on iOS 26 and later, an ML-KEM-768 encapsulation key; this profile answers with its share and the ML-KEM ciphertext, and both derive the new secret from the exchange mixed with the old secret (HKDF-SHA256). The new secret never crosses the dashboard connection, so only a pairing's first key depends on it, and with ML-KEM even a recording of that first handover can't open notifications after the first rotation. hermes conduit-push status says which kind of key is in use. ML-KEM needs cryptography with ML-KEM support (version 47 or later, built against OpenSSL 3.5); without it the profile offers X25519 only. To make the first handover quantum-safe too, let your HTTPS front end offer the hybrid TLS group X25519MLKEM768 (nginx 1.25+ with OpenSSL 3.5+: ssl_ecdh_curve X25519MLKEM768:X25519:secp256r1:secp384r1;); iOS 26 uses it automatically.
  • hermes conduit-push redact on keeps chat content from leaving the gateway: events carry no title or body text, approval cards say "Hermes needs your approval. Open Conduit for details.", and clarify cards replace question text with generic copy. The fields needed to answer stay (session key or request id, question ids, choice labels), so cards raised while the app is backgrounded remain recoverable and answerable. Clarify choice labels still transit the relay because the answer is one of them. status shows the current setting; redact off restores full content, including for events still waiting in the local delivery queue.
  • Besides notifications, the relay carries call pushes (sealed like notifications, except the "stopped ringing" notice), Lock Screen progress (phase, a tool category from a fixed list, tool count and context percentage, never chat text; redact on drops the category), Apple Watch grants and audio (sealed per call), the one-time codes that prove a phone holds its APNs token, and short-lived Apple Maps tokens for the host maps engine (the relay never sees the lookups). Health, location, calendar, phone and contacts data never pass through it.
The public relay URL is part of the client protocol. APNs signing material (the .p8 key) is never committed — see the relay directory below for how to deploy your own.

Push relay

The push relay is the server component that receives events from Hermes gateways and delivers them to iOS devices via APNs. The source lives in relay/.

Architecture: Hermes plugin → HTTPS → relay → APNs → Conduit app

The relay handles device registration, pairing codes, per-installation preferences, rate limiting, and idempotent event delivery. It uses only the Node.js standard library (no npm dependencies).

Self-hosting

A self-hosted relay only works with a Conduit build you sign yourself. APNs only accepts notifications for the App Store app (com.milim.relay) when they are signed with a key from its developer team, so a relay running anyone else's key can't reach the App Store build, even if you enter its address under Settings > Notifications > Push relay. To self-host end to end you need your own Apple Developer account, a build of Hermes Conduit under your own bundle id, and an APNs key for that bundle id in the relay below (APNS_TOPIC must be your bundle id). If you only want the relay operator to stop seeing your content, you don't need to self-host: with end-to-end encryption on (see Privacy and security) the shared relay only sees routing data.

cd relay/deploy

1. Copy and fill in environment

cp .env.example .env

Edit .env with your PUBLIC_URL and Apple developer credentials

2. Place your APNs signing key

mkdir -p secrets cp /path/to/AuthKey_XXXXXX.p8 secrets/apns-production.p8

3. Create the data directory, owned by the image's node user (uid 1000)

mkdir -p data sudo chown 1000:1000 data

4. Build and run

docker compose up -d

Skip step 3 and Docker creates data/ owned by root on a Linux host. The relay runs as node, can't write there, and exits at startup naming the directory. Docker Desktop on macOS maps ownership through its file sharing, which hides this.

The relay listens on port 9120. Put it behind an HTTPS reverse proxy (the relay validates that PUBLIC_URL uses HTTPS). If the proxy sends X-Forwarded-For, set TRUST_PROXY to the number of proxies in front of the relay (1 for one): the relay rate-limits by the address the outermost trusted proxy appended, never by an entry the client sent itself. That holds only when every request comes through the proxy, so don't publish port 9120 or share its network with anything else. APNS_MODE, APNS_CAPTURE_PATH and APNS_VOIP_FAILURE are test settings; a relay refuses to start with them.

The plugin sends relay credentials only over HTTPS with a trusted certificate (plain HTTP only to the same machine), and never follows a redirect. You can pair over plain HTTP against a LAN or Tailscale address, for example hermes conduit-push pair XXXXX-XXXXX --relay-url http://100.x.y.z:9120: the relay answers with its HTTPS PUBLIC_URL, and the plugin saves and uses that from then on. Pair that way only on a network you trust: whatever answers on that address chooses the HTTPS relay this host uses from then on.

What stays secret:

| File | Contents | Gitignored | |------|----------|------------| | .env | APNs key ID, team ID, topic, public URL | Yes | | secrets/*.p8 | Apple Push Notification signing key | Yes | | data/relay.json | Installation records, gateway credentials | Yes | | data/crash-reports/ | Crash and freeze reports testers sent | Yes |

See relay/deploy/.env.example for all required environment variables.

Check retained installation capacity without changing the data file. From the repository root, pass the mounted JSON path directly:

node relay/src/storage-status.mjs relay/deploy/data/relay.json

Or, from relay/deploy, inspect the running Compose service:

docker compose exec conduit-push npm run --silent storage:status

The command prints only total, active, inactive, and maximum installation counts. Inactive installations remain in the store and still consume slots: automatic APNs deactivation and repeated uninstall/reinstall cycles count toward the installation limit (50,000 by default, RELAY_MAX_INSTALLATIONS), which the printed maximum reflects. Review counts before scheduling offline data maintenance. DELETE /v1/installations/:id deactivates an installation and does not free its slot right away. When the relay is full, a new registration takes the slot of the longest-inactive installation (with its pairing codes and parked decisions): an inactive installation can never be used again, since its credential no longer authenticates and its hosts' events are refused. Only a relay full of active installations refuses new ones.

Crash and freeze reports

After Conduit crashes or freezes, iOS hands it a MetricKit diagnostic on the next launch, and Conduit asks the user once whether to send it. Send posts the diagnostic (call stacks, exception and termination codes, version, build, iOS version and device model; never an exception's message text) to POST /v1/crash-reports on the developer's relay (push.milim.dev), even when the user's notifications use another relay. A report can also carry a chat trace (relay 0.25+): the lines Conduit's chat screen recorded just before (sizes, offsets, row counts and what moved the chat; never message text), at most 2,000 lines of at most 160 characters, each only letters, digits, spaces and ()._,:;+=<>/#%[]-. A user who sees a chat jump or stop responding sends the trace on its own from Settings > Connection > Diagnostics & logs (kind chat), and the trace says what saved it: jump, stall, storm, rebuild, blank (rows on screen that no cell drew, relay 0.27+) or manual. The relay answers a post whose trace it kept with "trace": true, so the app deletes its copy only then. A post holds at most 1,000,000 characters, and the relay keeps only the diagnostic keys it names (metadata codes, exception type and name, stack frames, 512 levels of a stack), at most 600,000 bytes of them, with the trace, so the folder stays under about 1 GB. The relay keeps each as a file under data/crash-reports/, at most 1,000 and for 90 days, and takes at most 10 an hour from one address and 500 a day in all. The route takes posts from anyone, so a flood from many addresses can spend the day's 500 or push the oldest reports past the 1,000; the stacks are what matter, and a crash that keeps happening comes back. It takes reports only when CRASH_REPORTS_TOKEN (32 characters or more; a shorter one leaves reports off) is set in .env; the same token reads them, in place of :

curl -H "Authorization: Bearer <token>" "$PUBLIC_URL/v1/crash-reports?build=236"
curl -H "Authorization: Bearer <token>" "$PUBLIC_URL/v1/crash-reports/<id>"

The list gives each report's id, build, device, kind and signature, a hash of its exception codes and top frames, so reports of one fault group. The stacks are unsymbolicated MetricKit frames (binary name and offset); match them to the build's dSYM with atos.

For offline reclamation, storage:prune-inactive previews the number of eligible records by default. It removes only installations that have been inactive and unchanged for at least 30 days, have no gateway credentials, and have no pairing or pending-decision references. Active, recent, legacy gateway-bound, and referenced records are preserved; other store sections are left unchanged. Malformed state causes a generic failure without writes.

From relay/deploy, stop every relay writer before previewing or applying:

docker compose stop conduit-push
docker compose run --rm --no-deps conduit-push npm run --silent storage:prune-inactive

Review the counts, then explicitly apply and restart:

docker compose run --rm --no-deps conduit-push npm run --silent storage:prune-inactive -- --apply --relay-stopped
docker compose start conduit-push

The command creates an exclusive, exact-byte relay.json.backup-* beside the data file before atomically replacing it. Backups contain credentials and private messages: protect them like the original data file. The --relay-stopped flag acknowledges the offline requirement; it does not stop running writers. A byte comparison detects changes before replacement, but cannot make concurrent maintenance safe. Preview and zero-eligible runs create no backup and change no files. For a direct Node invocation, use node relay/src/storage-prune-inactive.mjs PATH_TO_RELAY_JSON and the same explicit flags when applying. Reclamation is operator-run, never automatic; gateway-bound inactive records still require separately reviewed maintenance.

Relay API

| Method | Path | Purpose | |--------|------|---------| | GET | /healthz | Health check | | GET | /v1/meta | The relay's version and capabilities, and with a phone's credential each paired gateway's plugin version and capabilities; a gateway's credential reads only the first two (0.21+), which the plugin checks before sending an event an older relay refuses | | POST | /v1/token-challenges | Push a one-time registration nonce to device_token (bundle_id, environment as for registering); 0.16+ | | POST | /v1/installations | Register a device; token_proof carries the pushed nonce (see "Registration proof") | | PUT | /v1/installations/:id | Update device token (a new one needs token_proof), PushKit token (voip_token, null clears it), the paired Apple Watch's PushKit token (watch_voip_token, 0.10+), location push token (location_token, 0.12+) / preferences | | DELETE | /v1/installations/:id | Deactivate a device | | DELETE | /v1/installations/:id/gateways/:gateway_id | The device drops one of its pairings; Conduit does when a dashboard is removed, so its host is refused (401) whether or not it can be reached; 204 also for one already gone (0.28+, capability device-gateway-removal) | | POST | /v1/installations/:id/pairings | Create a pairing code | | POST | /v1/pairings/claim | Claim a pairing code (gateway side) | | POST | /v1/events | Deliver a notification event; a reply's level (passive, active or time-sensitive) sets its interruption level (0.20+, capability push-levels) | | DELETE | /v1/gateways/current | Revoke a gateway credential; ?replaced_by= names the phone a re-pair moved it to, so the Apple Watch's ring follows (0.23+) | | PUT / DELETE | /v1/installations/:id/live-activities | Register (push_token, session_ids) or remove (push_token) the Live Activity the phone started for a chat (0.15+) | | POST | /v1/live-activity | Report a running turn's progress (session_id, state, optional end); answers tracked (gateway side, 0.15+) | | POST | /v1/watch-tools/grants | Open a Watch tool grant for one call (gateway side) | | GET | /v1/watch-tools/grants/:id/calls | Long-poll for the grant's Watch tool calls (gateway side) | | POST | /v1/watch-tools/grants/:id/results/:rid | Answer one Watch tool call (gateway side) | | POST | /v1/watch-tools/grants/:id/calls | A Watch tool call, held open until the gateway answers (Watch side, the grant's relay key) | | DELETE | /v1/watch-tools/grants/:id | Close a grant (either side; always 204, so a wrong key learns nothing) | | GET (WebSocket) | /v1/watch-audio/:id/host | The gateway's side of a Watch call's audio (a grant opened with audio: true) | | GET (WebSocket) | /v1/watch-audio/:id/watch | The Watch's side of it (the grant's relay key) | | POST | /v1/rings/:id/settled | The phone or the Watch answered or declined a call that rings on both (0.10+; the ring's token from the call push) | | PUT | /v1/rings/:id/session | The phone stores the sealed session of a call the Watch answered (0.11+; the ring's token) | | GET | /v1/rings/:id/session | The Watch fetches it, waiting up to ?wait=20 seconds (0.11+; the ring's token as the bearer) | | POST | /v1/rings/:id/control | The phone or the Watch mutes, unmutes or ends a call the Watch answered that stays on the phone's headset (0.17+; the ring's token) | | GET | /v1/rings/:id/control | Either reads the other's change past ?after= its last seq, waiting up to ?wait=20 seconds (0.17+; the ring's token as the bearer) | | POST | /v1/crash-reports | A crash or freeze report from Conduit, or a chat trace on its own (0.25+), no credential (0.24+, capability crash-reports; see "Crash and freeze reports") | | GET | /v1/crash-reports, /v1/crash-reports/:id | List reports (?build=) or read one (CRASH_REPORTS_TOKEN as the bearer) |

Watch tool grants carry an Apple Watch call's lookups while the Watch can't reach Conduit on the iPhone. Calls and answers are sealed with a per-call key the relay never sees (ChaCha20-Poly1305, bound to the grant, call id and direction), so the relay only forwards ciphertext. Grants live in memory, last at most 30 minutes and 120 calls, and a restart drops them; the Watch then falls back to the iPhone. Revoking a gateway, or deactivating its installation, closes its grants at once, with their waiting calls, host polls and audio bridges. A relay holding its maximum of grants answers a new one with 503 watch_grant_capacity, and that call's lookups go through the iPhone.

A grant opened with audio: true (relay 0.7+) can also carry the call's live audio for GPT-Live and Grok on the Watch: the gateway and the Watch each open a WebSocket, and the relay copies binary messages between them. They are sealed end to end like the tool calls; the relay reads only a message's first byte, which is never 0 (its own two-byte notices to the gateway: Watch connected, Watch gone). Limits per socket: 64 KB a message, 96 KB/s averaged over 5 s, 60 s of silence; bridges are capped per gateway and per relay (see below).

A call rings on the Apple Watch too (relay 0.10+) when the phone registered the Watch's own PushKit token: iOS doesn't pass a calling app's call to the Watch, so the relay sends the call push to both, with topic APNS_WATCH_TOPIC (default .watchkitapp, then .voip). Both pushes carry the same ring: an id, a token that only those pushes hold, and the url to settle it at, since the Watch knows no relay address of its own. The device that answers or declines posts {token, by: "phone"|"watch", outcome: "answered"|"declined"} to /v1/rings/:id/settled, and the relay sends the other device a VoIP push {conduit: {ring: {id, settled, by}}} that expires after a minute, so it stops ringing. The first settle wins; a later one gets 409 with how the ring was settled, and an unknown ring or wrong token gets 404. Rings live in memory for 10 minutes, and a restart drops them: the other device then rings out. A Watch token APNs refuses as gone is forgotten, and the phone still rings. A Watch push refused with DeviceTokenNotForTopic keeps the token and logs check APNS_WATCH_TOPIC: the setting is wrong, not the token. The .p8 key must be allowed to push to the Watch app's bundle id as well as the iPhone app's: a team-scoped key is, but a topic-specific key that lists only the iPhone app gets TopicDisallowed for every Watch push. The relay then keeps the token and logs apns key not allowed for this topic. A Watch push that APNs accepts logs watch voip sent.

A stop push that doesn't land isn't sent again: the other device rings out on its own. The settle answer's notified says only that the other device has a PushKit token at the relay, so a stop push went to it, not that it arrived.

A call answered on the Watch starts through the relay too (0.11+): the Watch's link to the iPhone stays down under the system call screen, so it can't ask Conduit there for the call's session. Its settle carries a sealed start, which the relay forwards untouched in the phone's stop push (ring.start). Conduit builds the session as for any Watch call and stores it, sealed, with PUT /v1/rings/:id/session {token, sealed}; the Watch fetches it with GET /v1/rings/:id/session?wait=20 and the ring's token as the bearer (200 with sealed, or 204 when nothing came in time). Both are sealed with a key only the phone and the Watch hold, so the relay sees their size and nothing else. A session can be stored only for a ring the Watch answered (409 otherwise), lasts 2 minutes in memory, and is at most 96 KB; the relay holds 32 MB of them at most, dropping the oldest first, and a ring takes two waiting fetches at a time. An older relay ignores start, and the Watch then starts the call over its link to the iPhone, as before.

A call the Watch answers while the phone has a headset on (AirPods) stays on the phone, so its voice plays there as a phone call's does, and the Watch's call screen keeps Mute and End. The phone answers its own ring, says so in the session it stores (callOnPhone), and the two share the call's mute and end through /v1/rings/:id/control: either posts {token, by, muted?, ended?}, and each long-polls GET ?after=&wait=20 for the other's (200 with {seq, muted, ended, by}, or 204 when nothing changed in time). Only those flags go through. A control exists only for a ring the Watch answered (409 otherwise); a call once ended stays ended, and a ring takes four waiting reads at a time. Each read or write keeps the ring another 10 minutes, up to 4 hours after it rang. A restart drops rings, so a write with adopt: true brings an unknown ring back as a control alone, with the token of the first write: the id is what an adoption trusts. Only the call's two devices know a ring's id, which the relay's logs leave out. Each device whose read comes back 404 writes its state again with it and reads on from after=0 (an adopted ring counts from 1 again), and a change made while the relay was down is retried. Adopted rings are capped at 1,000, apart from ringing calls, which they never push out. On a relay older than 0.17 the control is 404, and the Watch takes the call as before.

Registration proof

A phone proves it holds the APNs device token it registers. It asks POST /v1/token-challenges for a challenge, the relay sends a silent push carrying a one-time nonce (conduit_token_challenge) to that token, and the phone sends the nonce back as token_proof with POST /v1/installations, or with a PUT that moves the installation to a new device token. A nonce lasts 10 minutes and works once. Without a proof the relay answers 403 token_proof_required; a wrong or expired one gets token_proof_invalid.

So a token that leaks (a data-file backup, a log) can't be bound to someone else's installation, and filling the relay's installation slots takes real phones running the app rather than a script. A proven registration retires the same phone's earlier installations for that token. PushKit and location tokens can't be challenged this way, so a registration or update naming one that another active installation already holds is accepted without it: a registration gets none (voip, watch_voip or location comes back false), and an update keeps the token the installation had.

A Watch moves to a new iPhone with its PushKit token, which the old phone's installation still holds (0.23+). The new installation's answer says watch_voip_elsewhere: true, and the relay remembers the token it asked for. When the host pairs a profile with the new phone, the plugin (0.113+) revokes the old pairing with ?replaced_by=, and the Watch token moves there if that installation asked for that very token. An old phone a re-pair leaves with no pairing lets its Watch token go anyway (nothing can ring it), and the phone that wants it takes it with its next update; an unpair keeps it, so pairing the same phone again rings the Watch too.

A challenge answers 400 invalid_device_token when APNs refuses the token, so it shows whether a token is currently live for the app. The nonce never reaches whoever asked, so that grants nothing else, and per-token, per-IP and relay-wide limits bound such probing.

RELAY_TOKEN_PROOF is required by default. optional still accepts registrations and token changes without a proof (a proof that is sent must be valid): use it only while app builds from before token proof still need to register. Installations registered before token proof keep working either way; they need a proof only to move to a new device token.

Capacity and admission limits

The defaults are sized for the shared public relay with thousands of installations. Each bound is a backstop against floods, not a quota ordinary traffic reaches. Every one can be changed with the environment variable next to it: unset or empty keeps the default, and anything other than a positive integer stops the relay at boot.

| Bound | Default | Variable | |-------|---------|----------| | Installations, inactive ones included | 50,000 | RELAY_MAX_INSTALLATIONS | | Gateways per installation | 64 | RELAY_MAX_GATEWAYS_PER_INSTALLATION | | Event IDs remembered per installation | 5,000 | RELAY_MAX_EVENT_IDS_PER_INSTALLATION | | Event IDs remembered across the relay | 250,000 | RELAY_MAX_EVENT_IDS | | Active clarify decisions across the relay | 1,024 | RELAY_MAX_ACTIVE_DECISIONS | | Retained clarify decisions across the relay | 4,096 | RELAY_MAX_RETAINED_DECISIONS | | Registrations per minute | 24 | RELAY_REGISTRATIONS_PER_MINUTE | | Registration challenges per minute (each is a push; also 5 per device token per 10 minutes and 12 per IP address per minute, fixed) | 240 | RELAY_TOKEN_CHALLENGES_PER_MINUTE | | Events per minute | 6,000 | RELAY_EVENTS_PER_MINUTE | | Device updates that change state, pairing creations, and valid claims per minute | 240 | RELAY_DEVICE_CHANGES_PER_MINUTE | | Decision answers and releases that change state per minute | 600 | RELAY_DECISION_ACTIONS_PER_MINUTE | | Installation deactivations and gateway revocations per minute | 24 | RELAY_REVOCATIONS_PER_MINUTE | | Live Watch tool grants across the relay | 2,048 | RELAY_MAX_WATCH_GRANTS | | Live Watch tool grants per gateway (a new one closes the oldest) | 4 | RELAY_MAX_WATCH_GRANTS_PER_GATEWAY | | Live Watch audio bridges across the relay (GPT-Live and Grok on the Watch) | 200 | RELAY_MAX_WATCH_AUDIO_BRIDGES | | Live Watch audio bridges per gateway | 2 | RELAY_MAX_WATCH_AUDIO_BRIDGES_PER_GATEWAY | | Watch tool calls per minute | 1,200 | RELAY_WATCH_CALLS_PER_MINUTE | | Hermes call requests per installation per day (each new request counts, even one that rings no device) | 60 | RELAY_CALLS_PER_INSTALLATION_PER_DAY | | Live Activities held in memory, relay-wide / per phone (the oldest is forgotten past either) | 50,000 / 8 | RELAY_MAX_LIVE_ACTIVITIES / RELAY_MAX_LIVE_ACTIVITIES_PER_INSTALLATION | | Live Activity registrations per minute, relay-wide | 3,000 | RELAY_LIVE_ACTIVITY_REGISTRATIONS_PER_MINUTE | | Live Activity reports for a watched turn per minute, relay-wide | 30,000 | RELAY_LIVE_ACTIVITY_UPDATES_PER_MINUTE | | Live Activity registrations and removals per phone / per IP address, per minute (fixed) | 60 / 120 | |

Event IDs only prevent a repeated delivery of the same event within 24 hours, so the relay keeps them in memory and never writes them to the data file. A restart forgets them, which costs at most one duplicate push; replaying an event after a restart needs that gateway's credential, which can send new events anyway. An event whose push fails in a way a retry can fix (APNs refused or unreachable, an hourly limit) gives its ID back, so the plugin's retry is sent; a push APNs took but whose answer was lost can therefore show twice. A clarify decision is the exception: it keeps its ID, because a retry can't re-park it, and the plugin falls back to Hermes' own clarify path. An installation at its event-ID bound forgets its own oldest ID, and at the relay-wide bound the installation holding the most IDs forgets its oldest, so neither bound rejects an event. A gateway's last-seen time and plugin version are written at most

... (README truncated for length)

Chat with me