106 lines
5.0 KiB
Markdown
106 lines
5.0 KiB
Markdown
# Electron desktop runtime
|
|
|
|
The primary application is now Hermes Desktop. The root `electron/` directory
|
|
contains the main process, sandboxed metadata preload, and utility-process entry.
|
|
The retired `packages/desktop` implementation is not restored.
|
|
|
|
## Install and run
|
|
|
|
```bash
|
|
npm ci --ignore-scripts
|
|
npm run electron:setup
|
|
npm run dev
|
|
```
|
|
|
|
`electron:setup` downloads the pinned Electron binary and rebuilds `node-pty`
|
|
for Electron's ABI. `dev` builds the server/main/preload and starts Electron
|
|
with a Vite renderer on loopback, with hot reload. Restart `dev` after editing
|
|
server, main, or preload code. `HERMES_WEB_UI_FRONTEND_PORT` changes Vite's
|
|
default port (8649).
|
|
|
|
```bash
|
|
npm run build
|
|
npm start
|
|
npm run pack # unpacked application under release/
|
|
npm run dist # native installers under release/
|
|
```
|
|
|
|
Build installers on their target OS: DMG/ZIP on macOS, NSIS EXE on Windows,
|
|
AppImage/DEB on Linux. The manual Electron packages workflow covers all three.
|
|
Signing/notarization credentials must be supplied for public distribution.
|
|
No updater endpoint is supplied: install a new desktop package to upgrade.
|
|
Web npm self-update and version-preview installation are disabled in Electron.
|
|
|
|
## Process and request boundaries
|
|
|
|
1. Electron acquires a single-instance lock for its Chromium user-data directory.
|
|
2. The utility process validates `node:sqlite` and `node-pty`, then starts the
|
|
bundled Koa server on `127.0.0.1`.
|
|
3. A private parent port reports readiness and the actual HTTP origin. The first
|
|
launch uses an OS-assigned port; subsequent launches reuse it. If occupied,
|
|
another free port is selected. A port change also changes browser storage
|
|
origin, so users may need to sign in again; server data stays intact.
|
|
4. A sandboxed BrowserWindow loads that origin (or loopback Vite in development).
|
|
Node integration is disabled, context isolation enabled, and preload exposes
|
|
only platform/Electron metadata. Existing API and Socket.IO contracts remain.
|
|
5. External HTTP/HTTPS/mailto links open in the system browser. Other schemes
|
|
and webview attachment are blocked. Downloads use the native save dialog.
|
|
6. Quit sends a private shutdown message and waits for the existing bridge,
|
|
gateway, Socket.IO, HTTP and DB cleanup, with an 18-second final kill cap.
|
|
Closing the last macOS window keeps the app running until Quit.
|
|
|
|
The local service checks Host and browser Origin and retains the existing login
|
|
and API authorization. LAN discovery is off for the desktop. Desktop packaging
|
|
uses ordinary files (`asar: false`) because Python, MCP and terminal executables
|
|
must be accessible outside Electron's virtual filesystem.
|
|
|
|
## Data and external runtime
|
|
|
|
Chromium settings, login storage, saved window geometry and service port live in
|
|
Electron's `userData`. Service data defaults to `userData/state`; logs are in
|
|
`state/logs`. The Help menu opens these directories. Existing
|
|
`HERMES_WEB_UI_HOME` / `HERMES_WEBUI_STATE_DIR` overrides take priority. Point
|
|
one of them at an existing Web UI directory to reuse its data (stop the old
|
|
server first). No existing data is copied or deleted automatically.
|
|
|
|
`HERMES_ELECTRON_USER_DATA` overrides the Chromium profile for isolated testing.
|
|
Hermes Agent/Python are user-installed, and their state stays separate. Use
|
|
`HERMES_BIN`, `HERMES_HOME`, or `HERMES_AGENT_BRIDGE_PYTHON` as needed. Common
|
|
GUI-launch PATH locations are added to the service environment. POSIX bridge
|
|
sockets are scoped by service data directory. MCP uses the app executable in
|
|
`ELECTRON_RUN_AS_NODE` mode, so installed users do not need a separate Node.js.
|
|
|
|
The optional standalone web commands are `dev:web`, `build:web`, `start:web`.
|
|
Docker/systemd remain separate web deployment paths.
|
|
|
|
## Validation
|
|
|
|
```bash
|
|
npm run harness:check
|
|
npm run test:coverage
|
|
npm run test:e2e
|
|
npm run build
|
|
npm run electron:setup
|
|
npm run test:electron
|
|
npm run pack
|
|
```
|
|
|
|
Local verification on 2026-10-25 (macOS arm64): coverage suite passed (2,139
|
|
tests, 2 skipped), all 69 browser tests passed, and focused additions passed.
|
|
All three source Electron smoke tests passed; the packaged app passed both
|
|
production smoke tests. DMG checksums and ZIP integrity were verified. Windows
|
|
and Linux installers are configured but were not built on this Mac. The local
|
|
macOS artifacts are unsigned and not notarized.
|
|
|
|
The native smoke test launches the real Electron executable with temporary
|
|
Chromium, service and Hermes homes, verifies local health and renderer isolation,
|
|
and confirms the service exits when the app quits. It does not call a model.
|
|
Set `HERMES_ELECTRON_EXECUTABLE` to a packaged executable to repeat the test
|
|
against the installer contents. Linux runners require Xvfb and Electron's
|
|
system libraries. After Electron ABI rebuilds, run `npm rebuild node-pty` before
|
|
using the standalone Node server if its ABI differs.
|
|
|
|
References: [Electron utility processes](https://www.electronjs.org/docs/latest/api/utility-process),
|
|
[Electron security](https://www.electronjs.org/docs/latest/tutorial/security),
|
|
[native modules](https://www.electronjs.org/docs/latest/tutorial/using-native-node-modules).
|