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_phoneandconduit_contactstools for the agent, and events from the user's Shortcuts automations throughconduit_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.
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 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 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
- Push notifications: Delivering (with the last push's time), Failing
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.
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](orSILENT/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/notificationslists them ({"ok": true, "muted": [...], "act": [...], "shows_reports": true}) andPUTwith{"job_id": "...", "notify": false}changes one. Capabilitycron-notifications.
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.jsonwith mode0600on 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,429or a5xxfrom 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 ase2e_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'sDategives it. Other refusals are not retried. A401means the relay no longer knows this gateway (Conduit removed it, or the relay lost its data): the pairing is kept, andstatussays to pair again from Conduit until a delivery is accepted again. A401or403also 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 acceptedtest) ends the pause; a clarify question asked meanwhile uses the native prompt at once (Live Activity reports pause 30 minutes on their own). A403with no JSON body comes from something in front of the relay (a firewall or rate limiter) blocking this host's address:statussays so instead of telling you to pair again, since a pairing claim meets the same block, and Conduit's pairing status reports it asrelay_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 statusshows whether it's on; Conduit turns it on by itself when it connects to this host. Runhermes conduit-push test --corruptto 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 afterhermes conduit-push e2e rotateon 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 --nowskips that overlap; the current key still seals notifications until Conduit next connects, sohermes conduit-push unpairis 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 statussays which kind of key is in use. ML-KEM needscryptographywith 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 onkeeps 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.statusshows the current setting;redact offrestores 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 ondrops 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.
.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 , 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= 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)