The Hermes desktop application is an Electron-based shell that orchestrates the lifecycle of the Hermes Agent backend and manages secure connections to either local or remote messaging gateways. It provides a robust authentication layer using both static session tokens and OAuth2 flows, while adapting its rendering and execution model to the host environment.
The Electron main process acts as the privileged controller, managing window creation, native system integrations, and the inter-process communication (IPC) bridge. The shell is designed to detect environment constraints, such as remote displays (SSH X11 forwarding or VNC), and automatically disable hardware acceleration to prevent flickering apps/desktop/electron/main.ts41
The desktop app follows a hierarchical resolution strategy to establish a connection to a Hermes gateway. It supports local execution, remote backends, and "Hermes Cloud" managed agents apps/desktop/src/global.d.ts68-76
HERMES_DESKTOP_USER_DATA_DIR and sandbox fallback markers apps/desktop/electron/main.ts161-168connection-config module apps/desktop/electron/main.ts44-68The following diagram illustrates how a request from the UI travels through the Electron shell to reach the gateway using the JSON-RPC protocol.
Request Dispatch Architecture
Sources: <FileRef file-url="https://github.com/NousResearch/hermes-agent/blob/af8d698b/apps/desktop/src/hermes.ts#L222-L228" min=222 max=228 file-path="apps/desktop/src/hermes.ts">Hii</FileRef>, <FileRef file-url="https://github.com/NousResearch/hermes-agent/blob/af8d698b/hermes_cli/web_server.py#L103-L110" min=103 max=110 file-path="hermes_cli/web_server.py">Hii</FileRef>, <FileRef file-url="https://github.com/NousResearch/hermes-agent/blob/af8d698b/apps/desktop/electron/main.ts#L85-L85" min=85 file-path="apps/desktop/electron/main.ts">Hii</FileRef>, <FileRef file-url="https://github.com/NousResearch/hermes-agent/blob/af8d698b/apps/desktop/electron/oauth-net-request.ts#L1-L10" min=1 max=10 file-path="apps/desktop/electron/oauth-net-request.ts">Hii</FileRef>
The application manages connection states through the HermesGateway class, which extends the JsonRpcGatewayClient to handle the low-level WebSocket handshake and request/response matching apps/desktop/src/hermes.ts222-225
probeGatewayWebSocket to verify endpoint availability and authentication status apps/desktop/electron/main.ts85revalidateConnection function in the IPC bridge allows the renderer to recover from wake-from-sleep events by checking if remote backends are still reachable apps/desktop/src/global.d.ts19-25The desktop app implements a complex OAuth net-request handler to bridge Electron's net module with the gateway's authentication requirements apps/desktop/electron/main.ts131
device_code, pkce, and external flows apps/desktop/src/types/hermes.ts56index.html by the web_server.py and subsequently used by the SPA in X-Hermes-Session-Token headers web/src/lib/api.ts28-37| Auth Component | Implementation |
|---|---|
| OAuth Handler | oauth-net-request.ts handles JSON serialization and headers apps/desktop/electron/main.ts131 |
| Token Refresh | native-oauth.ts manages token expiry and refresh logic apps/desktop/electron/main.ts123-129 |
| Ticket Exchange | Uses one-shot tickets for WebSocket upgrades when gated mode is active web/src/lib/api.ts30-34 |
Sources: <FileRef file-url="https://github.com/NousResearch/hermes-agent/blob/af8d698b/apps/desktop/src/hermes.ts#L81-L92" min=81 max=92 file-path="apps/desktop/src/hermes.ts">Hii</FileRef>, <FileRef file-url="https://github.com/NousResearch/hermes-agent/blob/af8d698b/apps/desktop/electron/main.ts#L122-L131" min=122 max=131 file-path="apps/desktop/electron/main.ts">Hii</FileRef>, <FileRef file-url="https://github.com/NousResearch/hermes-agent/blob/af8d698b/web/src/lib/api.ts#L28-L37" min=28 max=37 file-path="web/src/lib/api.ts">Hii</FileRef>, <FileRef file-url="https://github.com/NousResearch/hermes-agent/blob/af8d698b/apps/desktop/src/types/hermes.ts#L56-L56" min=56 file-path="apps/desktop/src/types/hermes.ts">Hii</FileRef>
The main.ts file (compiled to main.cjs) serves as the privileged orchestrator for the desktop environment.
installWindowsSystemCaTrust ensures that the backend can communicate over networks with SSL-inspecting proxies apps/desktop/electron/main.ts206powerSaveBlocker and a custom createKeepAwake utility to prevent the system from sleeping during long-running agent tasks apps/desktop/electron/main.ts22-132The web_server.py contains a specialized _start_desktop_cron_ticker for when it is running inside the desktop app. Since the desktop app spawns a dashboard backend rather than a full gateway, this ticker ensures that user-defined cron jobs still fire by manually ticking the cron scheduler provider hermes_cli/web_server.py149-167
Backend Initialization Flow
Sources: <FileRef file-url="https://github.com/NousResearch/hermes-agent/blob/af8d698b/hermes_cli/web_server.py#L149-L187" min=149 max=187 file-path="hermes_cli/web_server.py">Hii</FileRef>, <FileRef file-url="https://github.com/NousResearch/hermes-agent/blob/af8d698b/apps/desktop/electron/main.ts#L42-L42" min=42 file-path="apps/desktop/electron/main.ts">Hii</FileRef>, <FileRef file-url="https://github.com/NousResearch/hermes-agent/blob/af8d698b/apps/desktop/electron/backend-ready.ts#L1-L10" min=1 max=10 file-path="apps/desktop/electron/backend-ready.ts">Hii</FileRef>
The desktop shell maintains a mapping between user profiles and their respective connection configurations.
The connection-config.ts module manages how the app connects to different backends. It distinguishes between the "Primary" connection (the local or default remote) and "Pool" connections used for background profiles apps/desktop/electron/main.ts44-68
The desktop interface supports multiple languages (en, zh, zh-hant, ja, ar) for its boot sequences and system notifications apps/desktop/src/i18n/types.ts8 These strings cover critical connection states such as connectingGateway and gatewaySignInRequired apps/desktop/src/i18n/en.ts68-80
Sources: <FileRef file-url="https://github.com/NousResearch/hermes-agent/blob/af8d698b/apps/desktop/electron/main.ts#L44-L68" min=44 max=68 file-path="apps/desktop/electron/main.ts">Hii</FileRef>, <FileRef file-url="https://github.com/NousResearch/hermes-agent/blob/af8d698b/apps/desktop/electron/main.ts#L41-L155" min=41 max=155 file-path="apps/desktop/electron/main.ts">Hii</FileRef>, <FileRef file-url="https://github.com/NousResearch/hermes-agent/blob/af8d698b/apps/desktop/src/i18n/types.ts#L8-L8" min=8 file-path="apps/desktop/src/i18n/types.ts">Hii</FileRef>, <FileRef file-url="https://github.com/NousResearch/hermes-agent/blob/af8d698b/apps/desktop/src/i18n/en.ts#L68-L80" min=68 max=80 file-path="apps/desktop/src/i18n/en.ts">Hii</FileRef>
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.