--- sidebar_position: 7 title: "Gateway Internals" description: "How the messaging gateway boots, authorizes users, routes sessions, and delivers messages" --- # Gateway Internals The messaging gateway is the long-running process that connects Hermes to 20+ external messaging platforms through a unified architecture. ## Canonical group metadata and profile discovery The authenticated canonical WebSocket exposes `groups.capabilities`, `groups.list`, `groups.state`, and `groups.log` with `session:read`; `groups.create`, `groups.rename`, and `groups.disband` require `session:control`. These reuse the hosted-room metadata protocol in the owning authority's database. An explicit `profile` selector must resolve to that authority's home. Disband refuses rooms with unsettled driver work rather than bypassing Stop. This is **metadata management, not hosted-room inference**. The existing local hosted-room driver still uses legacy TUI session handlers; the canonical surface therefore reports `driver: false` and does not advertise send, retry, approval, or peer-grant operations. It never imports that driver to execute a group turn. `profiles.list` requires `session:read` and returns the authenticated profile first, with its display metadata and avatar presence, then the served siblings and hosted-room destinations as discovery metadata. `include_sessions` defaults to true: `canonical_session` resolves the exact `Bot Chat` title, not the most recent conversation, and `last_session` is the newest visible local conversation (a hidden row never wins). Both count only local chats the actor owns or reads as an operator: minted `local-*` chats, and pre-upgrade chats adopted under their durable binding (they keep their old id). A sibling's row carries the same fields only when this connection already routes session verbs to it (a host-scoped grant: the Desktop's shared socket, the dashboard), read from that sibling's own authority with this connection's subject and capabilities. A profile-bound ticket gets metadata alone, and so does a sibling that is retiring, listed under a name that routes elsewhere, or whose store doesn't answer; a sibling still starting is not listed yet. Rows are reused while a profile's store has not moved. Discovery does not create, restore, or unarchive sessions, open a database handle of its own or reopen one an unserve closed, or run inference. ## Canonical ancillary reads Desktop and Ink use authenticated `session.control.read`, `process.list`, `subagent.list`, and `subagent.tail` with `session_id`. They require `session:read` and the owning profile/session identity. These polls never restore a cold session: use `session.resume` first. A retired route binding returns `stale_generation` rather than exposing its replacement conversation. Control reads project the physical transcript's persisted goal, loop and heartbeat through the existing frontend field allowlists, without constructing managers or clearing wait barriers. Revisions hash the visible snapshot; timed wait barriers can disappear when their deadline passes without changing persisted state. Process reads use already-owned registry objects and include a bounded output tail; they do not recover processes, consume notifications or scan retained receipts. Subagent reads require the current parent's live object ancestry, not merely equal session IDs; tails are bounded to 16 KiB. Missing or retired children return `available: false`. These are reads, not child steering or stop controls. Managed-worker policies return `unsupported_projection` for process/subagent reads: the owner's process-local registry cannot truthfully describe another interpreter. Control mutations (`session.control`), process mutations and subagent steering are not enabled by these read projections. ## Shared authority pending-input snapshots `session.resume` returns each pending admission with its original `input_id` and committed public `text`, alongside the canonical `admission_id`, sequence and status. This includes native messaging inputs and local-client inputs. Snapshots do not expose private native routing, source, or authorization envelopes. Submission and receipt ACKs retain their existing shape. Clients must use `admission_id` for cancellation and receipt queries rather than assuming it equals the original input ID. Queue admission, claim, cancellation and settlement also publish `session.info` to attached viewers. Its `pending` rows use the same projection as resume. Settlement publishes this state before `message.complete`, retaining the terminal event as the last event of that turn. Desktop translates both paths into its existing `pending_submissions` queue store. A turn that was `started` when its owning gateway died is recovered by the next owner as `unknown`: Hermes cannot prove which side effects happened, so it neither replays the input nor lets the queued turns behind it run. `prompt.resolve_unknown` (`session:control`, params `session_id`, `admission_id`, `execution_generation`) acknowledges the loss: the row settles as `interrupted`, the session FIFO resumes and the follower runs exactly once. The generation must be the one stamped on the unknown row (visible in the resume/`session.info` projection), so a stale or already-resolved row is refused with `stale_generation`. Desktop shows such a row in the queue panel as "Turn lost during restart" with a **Discard** button; the gateway CLI exposes it as `/discard `. The lost input stays in the transcript for the user to resend; the discard closes it with a Hermes notice (like a failed turn), so it is never merged into the follower's model request. A messaging user (Telegram, Discord, ...) whose session is paused this way is told once per pause episode, through the adapter's ordinary reply path, that the conversation is paused and that `/reset` starts a fresh one; later messages onto the same pause are admitted silently and stay queued. Their delivery waiters are released with the pause reason instead of parking the adapter loop. `/reset` rotates the route to a new session (the lost turn and its followers stay on the old one); the operator can alternatively resolve the unknown row from Desktop or the CLI. ## Shared authority prompt attachments `prompt.submit` accepts an optional `attachments: [{path, mime}]` list beside `text`. The client stages image bytes in the profile image cache (`cache/images/` under the served `HERMES_HOME`, the same place messaging adapters stage downloads); paths must be regular files directly in that directory, `mime` must be an image type (`image/png`, `image/jpeg`, `image/gif`, `image/webp`), at most 10 per submission, each under `gateway.max_inbound_media_bytes`. The authority copies the bytes into its immutable `native-inputs` store at admission and stores the sha256-checked reference in the private payload, so later mutation or cache cleanup of the staging file cannot change what executes, including after an owner restart. Execution restores them onto `MessageEvent.media_urls`/`media_types`, and the ordinary image routing (`agent.image_input_mode`, native `image_url` parts vs. text pre-analysis) applies. Text-only submissions keep the `{text}` payload and fingerprint. The ACP transport agent uses this for image, image resource-link and embedded-image prompt blocks; Ink and Desktop still attach through the legacy `image.attach`/`file.attach` RPCs. ## Native admission startup recovery Ordinary gateway startup recovers accepted native inputs after adapter connection, route publication, and the startup restore gate. Only never-started queued work is eligible. Recovery uses the current routing index and connected adapter, rechecks sender authorization and the retained connector/profile binding, and leaves rows queued when a route, transport, or authorization is unavailable. Restoring that configuration permits recovery on a later startup. An interrupted started admission becomes `unknown` and pauses its session's FIFO; its followers do not automatically run. Legacy synthetic restart turns are excluded from sessions with canonical admission history, so they cannot race the durable queue or bypass an unknown pause. Completed inputs are not reinferred on restart. Under `gateway.multiplex_profiles` the bootstrap builds one session authority per served profile home (the default plus every directory under `profiles/`), each bound to that home's `state.db` and entered under that profile's runtime scope. Every admission path (bot message, `/p//` API and webhook, cron fire, kanban dispatch, native CLI/Desktop/ACP attach) resolves its authority from the routed profile's home, so recovery, FIFO order and exactly-once settlement hold per profile and a secondary's rows never land in the default's ledger. A served secondary's clients discover the multiplexer through the default home's descriptor (`served_profiles`) and attach to its control socket with their own `profile_id`. ## Shared authority local slash commands Authenticated local sessions accept `slash.exec({session_id, command})` and `command.dispatch({session_id, name, arg})`. Both use the existing command registry and gateway handlers, without a legacy slash worker or second execution runtime. An optional `profile` selector must match the owning daemon's profile. Caller source and routing overrides are rejected; another authenticated actor cannot operate the session. Supported read commands are `/help`, `/commands`, `/status`, `/context`, `/version`, and `/whoami` (`session:read`). `/title` requires `session:control`, even for a query, and retains the existing busy rejection. Registry aliases work. Handler results use `{type: "exec", output}`. Skill names and configured quick-command aliases to supported commands or skills are resolved in the owner's profile. Skill resolution requires `session:submit` and returns `{type: "skill", name, message, display}`. Desktop/Ink send the expanded message through their normal identified `prompt.submit`; resolution is not an admission ACK. The authority's durable FIFO owns retries and execution, and skill content remains a user message without changing the cached system prefix. `type: exec` quick commands and plugin slash commands require `session:control` and run through the messaging gateway's own quick/plugin dispatch (slash access policy, sanitized-env exec with a 30 s cap and redacted output, plugin session env). Other commands return `unsupported_command`: bundles, configuration/runtime changes, lifecycle commands, and approval/secret slash shortcuts are not exposed. Existing generation-bound approval and interrupt RPCs remain separate. Catalog discovery is broader than this reviewed execution set. ## Shared authority busy input and corrections `config.get({session_id, key: "busy"})` projects the session's frozen busy-input preference. `config.set({session_id, key: "busy", value})` accepts `interrupt`, `steer`, or `queue` and changes only that live session's preference, shared by its viewers until owner restart. Neither operation changes profile settings or the cached agent/system prompt. Other config keys are not handled by this adapter. `session.steer` and `session.redirect` require `session_id`, `text`, and the current `execution_generation`, plus authenticated session-control rights. Optional `profile` must match the authority. Controls target the existing running agent: steer uses the ordinary correction drain; redirect cancels an active model request and continues the same turn (or steers at a tool boundary). They never create a queued admission or silently fall back to a new turn. `queued` (steer) and `redirected` acknowledge runtime acceptance, not crash-durable delivery; do not automatically retry an ambiguous reply. `rejected` means the runtime missed the active correction window, while `stale_generation` rejects settled/replaced work. Managed-worker corrections currently return `unsupported_control`; normal durable queue submission and Stop remain separate controls. ## Shared authority setup readiness Authenticated local clients can call `setup.status` and `setup.runtime_check` before creating a session. Both require `session:create` and run against the daemon's owned profile; a selector for another profile is rejected. Runtime readiness reuses the existing provider resolver off the event loop and does not create a legacy session runtime. Missing provider credentials remain a failed readiness result, not a bypass of onboarding. ## Shared authority clarification protocol When the HTTP/WebSocket surface is bound to a `SessionAuthority`, attached authorized viewers receive `clarify.request` events and pending questions in the `session.resume` `prompts` snapshot. This is an authority API contract; it does not imply that every native frontend already renders the shared form or that ordinary bootstrap is complete. A response uses `clarify.respond` with `session_id`, `execution_generation`, `prompt_id`, and an `answer` string. The connected viewer must be subscribed and have `session:respond`. The authority checks the running generation and resolves the existing native clarify waiter by exact prompt ID, without adding a user prompt to the admission queue. The first response wins; detach does not cancel it. Native answers and timeouts retire the same prompt and emit `clarify.settled`; response text is not placed in the control replay stream, although the normal clarify tool result becomes part of the conversation. Questions and choice labels use the existing display redactor. Publication follows successful native card delivery. A failed native delivery does not create an actionable shared form. Ordinary approvals use the separate `approval.respond` permission path; sudo/secret prompts and durable control restoration after daemon restart are not implemented by this clarification path. ## Revision-checked session metadata The authority-bound WebSocket accepts `session.mutate` for a registered session. Parameters are `session_id`, `request_id`, `expected_revision`, `operation`, and `payload`. `rename` accepts only `{"title": "New title"}`; `archive` accepts only `{"archived": true}` or `{"archived": false}`. The caller needs `session:control`. The session handle in `session.resume` supplies the current revision. The edit and its retry receipt commit together. Repeating the same request returns the original result without incrementing the revision again; reusing its ID with different contents returns `admission_conflict`. A competing edit with a stale revision returns `revision_conflict`. Draining rejects new mutations and fresh session registration before routing or transcript creation. These edits do not interrupt a running turn. Canonical reset, delete, rewind, model, branch, and compression operations use the same receipt boundary. `branch` accepts an optional `title` and `through_message_id` (the row id of the last message to keep; tool results answering an assistant boundary come with it); without it the whole active transcript is copied. A request disconnect does not cancel its owner-held mutation: the commit, live projection and queue wakeup finish together, and profile retirement joins that work before releasing the store. An exact old receipt cannot evict a newer running agent. Canonical wire models live in `tui_gateway/contracts/canonical*.py` and generate `CanonicalRpcMethods` plus the OpenRPC `x-canonical-methods` catalog, separately from the standalone protocol. Both parameters and successful results are checked. ACP and finite CLI viewers detach with an explicit recovery notice if an accepted input becomes blocked behind an unknown execution. The accepted input remains queued: resolve the lost turn before continuing, rather than resending it. ## Private native HTTP authentication The authoritative daemon accepts a **fresh, one-use HTTP grant per request** from its same-user private control socket. Send `session-ticket` with exactly `profile_id` (the canonical served primary home), `instance_id` (the ready daemon's boot ID), and `purpose: "native-http"`. The returned ticket expires after 30 seconds and carries only `http:owner`; send it in `X-Hermes-Gateway-Ticket` from the native main process. Never place it in a URL, cookie, public descriptor, renderer config, or log, and never obtain a dashboard token by scraping the public page. The existing HTTP authentication seam redeems the grant only for the matching ready daemon and primary profile. It requires an actual loopback socket peer, captured before trusted-proxy rewriting, and **no Origin header at all** (even an empty Origin is refused). An invalid, duplicate, expired, replayed, or wrong-purpose header returns 401 without falling back to a supplied static token or OAuth cookie. Draining/unready listeners refuse admission; restart and shutdown revoke grants. HTTP grants do not authenticate WebSockets, and interactive/exposure/worker grants do not authenticate HTTP. Requests without this header keep the existing static session-token, OAuth bearer/cookie, Host, and route-specific token-provider gates. This local bootstrap is an explicit same-OS-user administrative boundary, not an OAuth bypass for remote clients. An exposure proxy must not replace remote callers' credentials with its own native grant. It is not a filesystem sandbox against code already running as the same OS user. A native grant does not retarget the daemon through a URL or JSON `profile` selector: each supplied selector must resolve to the served primary home. The existing config `current`/empty/default-name contracts are preserved rather than treating `default` as an alias for any arbitrary launch home. Cross-profile targets return 403 `profile_scope_mismatch`, including conflicting duplicate query selectors. `GET /api/profiles` and `GET /api/profiles/active` retain their discovery metadata contracts; discovery does not confer another profile's data authority. Aggregate session/sidebar routes require an explicit own-profile selector, and cron job routes require an explicit own-profile query. All-profile project/transcript aggregation, profile creation/import/activation, and profile rename/delete are not granted by this primary-profile credential. Native clients must not rewrite `all` to `current` or borrow the primary grant to hide a cross-profile failure. Creating a profile from native Desktop uses a separate, same-user `purpose: "native-profile-create"` grant carrying only `profiles:create`. It is accepted exclusively by `POST /api/profiles`; it does not authorize profile reads, import, activation, rename, deletion, or WebSocket access. The existing create handler validates the name and clone options. Optional `soul` content is written inside the staged profile before publication, so creation does not need a follow-up write or a running new-profile gateway; `soul_set` confirms it was applied. Older remote backends retain the separate, explicitly profile-scoped SOUL update. Desktop mints this grant per create request, never sends it to the renderer, and still uses ordinary profile-bound grants for subsequent requests. The same expiry, one-use, daemon, socket-peer and Origin checks apply. Ordinary `native-http` grants still receive 403 on creation. The native HTTP integration is covered by real ordinary-daemon/control-socket/TCP probes in `tests/gateway/test_native_http_auth.py`, alongside gated OAuth/cookie and actual non-loopback-peer controls. This does not establish native Desktop UI parity or platform-specific Windows/macOS bootstrap validation. ## Frozen local launch credentials Local `session.create` receipts retain the launch policy, not plaintext API keys. Inline credentials in the profile config are borrowed from that existing private source after restart: the canonical profile home, credential path, value fingerprint, and frozen policy identity must match. Provider endpoints and request settings still come from the frozen policy, not the current config. Missing or changed credentials fail closed rather than selecting a different key. No second secret store is created. Credential-bearing headers, environment maps, and terminal projections are redacted from durable policy JSON and hydrated privately through the same source checks. Retrying a creation request returns its original session and policy without binding current replacement credentials. An ad-hoc `--api-key` remains authority-lifetime-only; restart revokes that key, not config-based sessions. Older receipts that contain only an instance-bound credential reference cannot securely recover a lost value and remain fail-closed. Their history is still readable; create a new session to adopt current credentials. Credential fingerprints are private metadata, never public API responses. CLI cost/data-training consent runs before gateway discovery and session creation, including top-level one-shot launches. It does not become a process-wide option. ## Key Files | File | Purpose | |------|---------| | `gateway/run.py` | `GatewayRunner` facade — composes the `gateway/run_*.py` sibling mixins (startup, adapters, inbound, turn, busy, goals, notifications, shutdown, …) and `gateway/slash_commands_*.py` handlers | | `gateway/session.py` | `SessionStore` — conversation persistence and session key construction | | `gateway/delivery.py` | Outbound message delivery to target platforms/channels | | `gateway/pairing.py` | DM pairing flow for user authorization | | `gateway/channel_directory.py` | Maps chat IDs to human-readable names for cron delivery | | `gateway/hooks.py` | Hook discovery, loading, and lifecycle event dispatch | | `gateway/mirror.py` | Cross-session message mirroring for `send_message` | | `gateway/status.py` | Token lock management for profile-scoped gateway instances | | `gateway/builtin_hooks/` | Extension point for always-registered hooks (none shipped) | | `gateway/platform_registry.py` | Adapter registry, factories, and deferred (lazy) loaders for bundled platform plugins | | `plugins/platforms//` | Bundled messaging adapters (most platforms: `adapter.py` + `plugin.yaml`) | | `gateway/platforms/` | Shared `base.py` plus legacy/direct adapters (Signal, API server, webhooks, …) | ## Optional service installation A running gateway and an installed OS service are different things. `hermes gateway run` works without a service, including with no messaging platforms configured. `hermes setup`, quick setup, and `hermes gateway setup` ask interactive users once: > Install the gateway service so Hermes starts automatically at login and keeps scheduled jobs and messaging available? The profile's `gateway.service_install_choice` stores `null`, `install`, or `decline`. An unset value is not permission to install. Declining records `decline` without creating, enabling, or removing a service. In the gateway wizard, choosing **Start now** but declining service installation launches an unmanaged gateway; it does not create a disabled service. Without service persistence, messaging and scheduled work stop at logout/reboot. Jobs cannot run while the host is off. Noninteractive setup and imports do not install a missing service, even when the imported config says `install`. Existing installed services remain authoritative and can be started regardless of the saved preference. To opt in explicitly later, run `hermes gateway install`; the choice is recorded only after successful installation. To be asked again during setup, reset the choice with `hermes config set gateway.service_install_choice null`. Setup orchestration lives in `hermes_cli/gateway_setup_service.py`. Its `ensure_gateway_service` helper is not a general runtime discovery or auto-start API: ordinary calls never reinstall a missing service based only on stored preference. ## `hermes gateway ensure` Clients (Desktop, `hermes chat`, the TUI) discover or start the profile's session runtime with `hermes gateway ensure --json --timeout 60`; the summary is in the [CLI reference](../reference/cli-commands.md#local-runtime-discovery-and-startup). The timeout is a finite, positive total deadline in seconds (default `60`, enough for a cold daemon boot on a loaded host). An existing reservation or starting owner is waited for, not replaced. When absence is established, an existing service takes precedence; an unmanaged process is requested only when no service is found. This command never installs or rewrites service definitions, enables linger, elevates privileges, or clears update fences. Ambiguous or inaccessible ownership fails closed. Before requesting a service start, `ensure` checks its canonical profile directory and execution account, not just its unit/task name. Linux uses the manager's loaded command and environment (including effective drop-ins), macOS checks the loaded launchd job rather than assuming the on-disk plist is current, and Windows queries the actual task XML, principal, and installed launcher. - `profile_mismatch`: the installed service selects a different home or profile. Inspect the selected service's `HERMES_HOME` and command-line profile selector; use the matching profile or explicitly repair the service configuration. - `service_account_mismatch`: the service belongs to another account. Run the client as that account, or explicitly configure a service for the intended user. - `service_identity_unverified`: the manager did not expose enough identity data, or the definition uses unsupported dynamic configuration. Inspect it with `systemctl [--user] show --all`, `launchctl print /