--- title: hermes-hq-push (Hermes HQ iPhone app plugin) type: system status: active created: 2026-11-04 updated: 2026-11-08 verified_on: 2026-11-08 review_after: 2026-12-08 confidence: medium tags: [push, notifications, plugins, ios, desktop, device-access] sources: [live-hermes-plugins-list, live-plugin-manifest, live-config] --- # hermes-hq-push (Hermes HQ iPhone app plugin) ## What it is `hermes-hq-push` is a **standalone Hermes plugin** (`kind: standalone`, **v0.9.42**, author *Hermes HQ*) living at `~/.hermes/plugins/hermes-hq-push/` (tree mtime **2026-11-07 06:42**, reinstalled 0.9.27 → 0.9.42). It is the host-side half of the **Hermes HQ iPhone app**: Apple push, phone device access, the desktop-app theme, the app's Terminal page, and Grok Live voice token minting. Its own manifest states it **replaces `dispatch-push`**, and that *"its registered phones carry over."* ## Verified state (2026-11-04) | Check | Result | |---|---| | `hermes plugins list` | `hermes-hq-push` — **enabled**, `0.9.27`, state `user` | | `config.yaml` → `plugins.enabled` | line **7556**: `- hermes-hq-push` | | `~/.hermes/plugins/dispatch-push/` | **absent** — and no `dispatch-push` reference survives in `config.yaml` | | live tree | `~/.hermes/plugins/hermes-hq-push/` (module files + `dashboard/` subdir + its own test suite) | | README | none — the manifest `description` is the only prose | The replacement is therefore **clean**: nothing references the retired plugin, and the new one is explicitly enabled. Enablement and version are config-verified; individual hook firing was not separately captured. ## Surfaces (grouped from the plugin manifest) **Push / approvals** - Finished turns — who replied and what they said. - Approvals with the command shown, **Approve / Deny from the lock screen**. - A bot waiting for a password, login, code or answer — the site or the question, **never the value**. - **Live Lock Screen cards:** every step the bot takes (e.g. *Running npm test…*, the two before it, how many) is pushed to the card, *sealed so only the phone can read it*; the card says **Done** when the turn ends. - Tells the app which scheduled jobs a bot is still working on. **Device access** (app *Settings › Device Access*) — contacts lookup, location, reminders and events, alarms and timers, photos, Health, motion, music, and leaving an email or text for Anthony to send. This is what backs the Conduit-style phone sharing on the Hermes HQ app. **Desktop app** — adds the **Hermes HQ theme**; opens a shell on the host for the app's Terminal page (the login shell, as an SSH login would; `plugin-data`'s `terminal.off` disables it); lets a Nous sign-in delete, archive and rename the chats it created (Hermes refuses them otherwise) and lets the desktop app open chats the app made (Hermes answers `not_found` otherwise); keeps a bot's **Sessions list fast** on a host that has run many scheduled jobs; lets the app send into a chat the desktop app has open; page previews; and keeps the app's performance log on this computer at **`~/.hermes/hq-logs`**. **Voice** — mints the app's **Grok Live** voice session a short-lived xAI token (subscription sign-in or `XAI_API_KEY`; the bearer itself never reaches the phone). **Restart guard** — stops a bot's one-off macOS launchd restart job from looping (those jobs are KeepAlive, so a one-time restart re-runs forever and locks the app out), and tells a restart script which in-app chats are mid-reply so a restart can wait. **Cross-posting** — on request, posts the bot's answer back to the Telegram or Discord chat a conversation came from. ## Interface - **Tools:** `device_contacts_search`, `device_request_result`. - **Hooks:** `pre_approval_request`, `post_approval_response`, `pre_tool_call`, `on_human_input_request`, `on_human_input_resolved`, `pre_llm_call`, `on_session_end`. ## Configuration All environment variables are optional. `DISPATCH_*` spellings of the APNs/relay names still work. | Variable | Purpose | |---|---| | `HERMES_HQ_APNS_KEY_PATH`, `HERMES_HQ_APNS_KEY_ID`, `HERMES_HQ_APNS_TEAM_ID` | **Direct APNs mode** — path to the app's `.p8` auth key, its Key ID, and the Apple Developer Team ID that owns the app. *Only the app's developer has these.* | | `HERMES_HQ_PUSH_RELAY_URL` | Another push relay's HTTPS URL, or `off` to send nothing. **Unset = alerts go through the public Hermes HQ relay, sealed so it cannot read them.** | | `HERMES_HQ_PUSH_RELAY_KEY` | Only for a private relay that asks for a key. | No key material is recorded on this page and none appears in the manifest — the relay key is declared `password: true` and is supplied by environment only. ## Relationship to the other push stacks - [[systems/push-notifications]] documents the **Cadu/Vory** bridge (`hermes-push`, `vory-push`, `~/.hermes/push/hermes_push.py`) — a **separate** stack, untouched by this plugin and still `degraded`. - `dispatch-push`, the previous relay plugin for the same app, is **retired and fully removed** (see the verification table above). ## 2026-11-07 — reinstalled to v0.9.42, routes picked up by a gateway restart - The plugin was **reinstalled to `v0.9.42`** in this window (from `v0.9.27`) and the **gateway was restarted at 11:11:44 → 11:11:55 AWST** so the new tool routes were registered (live process then `pid 3109529`). A plugin's routes are only registered at gateway start, so a reinstall without a restart changes nothing on the wire — the restart is the delivery step, not a symptom ([[systems/hermes-agent]]). - Same night, the plugin tree's mtime moved from **2026-11-03 11:06** (the mtime this page recorded on 2026-11-04) to **2026-11-07 06:42**; `hermes plugins list` on 2026-11-07 reports `hermes-hq-push` **0.9.42** enabled (`plugin.yaml` agrees). Installed from `mrcharlesiv/hermes-hq-plugins`, upstream **`d26850e7`**, verified complete at **60/60 files**. Order of events that made the restart necessary: `hermes-dashboard` started **05:43:04** and `hermes-gateway` **05:37:34** (the 0.22.5 → 0.23.0 update) — *before* the 06:42 reinstall, so neither running process had the new routes. A verification pass at 10:00:46 confirmed the plugin files were newer than both service starts, and the single restart followed at 11:11:44 → 11:11:55 (`pid 3109529`). - No app-side fault was recorded on 2026-11-07. Push delivery, device access and Grok Live minting were not re-exercised end-to-end by this audit — the version/route claim is the verified part. ## Open - `~/.hermes/hq-logs` retention is not documented anywhere yet — check its growth before it becomes a disk item. - The plugin carries a very large surface under one name; if it misbehaves the manifest `description` is the only capability index. - **Operational note:** the plugin's `pre_tool_call` guard rejects any tool call whose arguments contain the literal text of a launchd one-off-restart command — writing *about* that command into a file is blocked too. Describe it, don't quote it.