--- title: hermes-hq-push (Hermes HQ iPhone app plugin) type: system status: active created: 2026-11-04 updated: 2026-11-04 verified_on: 2026-11-04 review_after: 2026-12-04 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.27**, author *Hermes HQ*) living at `~/.hermes/plugins/hermes-hq-push/` (tree mtime **2026-11-03 11:06**). 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). ## 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.