The Hermes Desktop application is a native, cross-platform shell built on Electron that provides a high-performance graphical interface for the Hermes Agent. It manages the lifecycle of the underlying agent gateway, handles complex multi-profile authentication (OAuth), and provides a rich React-based environment for chat, tool execution, and session management.
The desktop application follows a tiered architecture that separates low-level system management from the user interface. It utilizes a "Bootstrap" model to ensure the Hermes environment is provisioned correctly on the host machine.
The application is split between the Electron Main process (Node.js) and the Renderer process (React).
| Process | Role | Key Code Entities |
|---|---|---|
| Main Process | Shell management, local gateway spawning, native OS integration, and secure storage. | apps/desktop/electron/main.ts apps/desktop/electron/main.ts11-31 bootstrap-runner.ts apps/desktop/electron/main.ts42 |
| Renderer Process | UI state management, WebSocket communication with the gateway, and user interaction. | GatewaySettings apps/desktop/src/app/settings/gateway-settings.tsx147 apps/desktop/src/app/ |
| Bootstrap Installer | Lightweight Tauri-based utility for provisioning dependencies (uv, Python). | apps/bootstrap-installer/package.json apps/bootstrap-installer/package.json2 |
The following diagram illustrates how the desktop shell bridges native OS capabilities to the Hermes core, utilizing the Electron IPC bridge for secure communication.
"Desktop Entity Relationship"
Sources: apps/desktop/electron/main.ts11-31 apps/desktop/electron/main.ts85 apps/desktop/electron/main.ts133 apps/desktop/src/app/settings/gateway-settings.tsx147-154
The Electron shell acts as a supervisor for the Hermes backend. It can connect to a locally managed gateway instance or a remote instance via WebSocket. The main process handles the complex logic of detecting environment specifics, such as WSL or remote displays apps/desktop/electron/main.ts41
connection-config.ts, which supports local profiles, SSH overrides, and remote URL normalization apps/desktop/electron/main.ts44-68probeGatewayWebSocket to verify gateway availability before handing off to the renderer apps/desktop/electron/main.ts85For details, see Electron Shell and Gateway Connection.
Hermes Desktop supports a sophisticated multi-profile system. Users can switch between different agent identities and connection modes.
local, remote, cloud, and ssh modes apps/desktop/src/app/settings/gateway-settings.tsx33The UI is a React application that leverages nanostores for state management and modern components for the chat experience.
@assistant-ui/react and @streamdown/code for high-performance markdown and code rendering apps/desktop/package.json67-68 apps/desktop/package.json85cmdk for a fast, keyboard-driven interface for switching profiles and executing commands apps/desktop/package.json100For details, see Desktop UI Components.
This map associates high-level UI features with their primary code entities and store management.
"UI Component to Code Mapping"
Sources: apps/desktop/src/app/settings/gateway-settings.tsx27 apps/desktop/src/app/settings/gateway-settings.tsx39-53 apps/desktop/electron/zoom.ts9 apps/desktop/electron/zoom.ts43 apps/desktop/electron/main.ts130
The apps/bootstrap-installer is a specialized Tauri application designed to handle the "Day 0" experience. It provisions the environment by installing necessary tools like uv and python before the main Electron application is launched apps/bootstrap-installer/package.json27-38
The application uses electron-builder to produce native installers for macOS (DMG, Zip), Windows (MSI, NSIS), and Linux (AppImage, deb, rpm) apps/desktop/package.json32-39
@electron/rebuild to ensure native modules like node-pty are compiled correctly for the target Electron version apps/desktop/package.json113 apps/desktop/package.json137Sources: apps/desktop/package.json1-135 apps/desktop/electron/main.ts1-180 apps/desktop/src/app/settings/gateway-settings.tsx1-150
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.