mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-06-18 09:51:59 +00:00
705eaa054a
Converges the Windows packaged desktop installer onto a single canonical
install topology: drop the Electron shell only (~80MB instead of ~500MB),
clone Hermes Agent at a build-time-pinned commit on first launch via
install.ps1's stage protocol, and treat the resulting git checkout at
%LOCALAPPDATA%\hermes\hermes-agent\ as the canonical install location
(same path the CLI installer uses). Future updates flow through the
existing applyUpdates() git-pull path.
Replaces the previous fat-installer architecture where the .exe bundled
a pre-staged hermes-agent source tree under resources/hermes-agent/ that
was then sync'd into ACTIVE_HERMES_ROOT at launch -- a complicated
factory-vs-active dance with several footguns (FACTORY_HERMES_ROOT
mismatch on path resolve, isGitCheckout guard regressions, pyproject
hash drift detection inside the sync loop).
Architecture overview
---------------------
Build time
apps/desktop/scripts/write-build-stamp.cjs writes
apps/desktop/build/install-stamp.json with {commit, branch, builtAt,
dirty}. Honours $GITHUB_SHA / $GITHUB_REF_NAME in CI, falls back to
`git rev-parse HEAD` locally.
apps/desktop/scripts/stage-native-deps.cjs copies the runtime subset
of @homebridge/node-pty-prebuilt-multiarch from the workspace-root
node_modules into apps/desktop/build/native-deps/. Workspace dedup
hoists this dep to the root, out of reach of electron-builder's
`files:`-restricted collector; staging gives us a deterministic
path to extraResources.
electron-builder ships both into resources/install-stamp.json and
resources/native-deps/ respectively.
Boot resolver (electron/main.cjs)
Resolver order:
1. HERMES_DESKTOP_HERMES_ROOT override
2. SOURCE_REPO_ROOT (dev mode)
3. ACTIVE_HERMES_ROOT git checkout WITH .hermes-bootstrap-complete
marker -- the post-install fast path
4. `hermes` on PATH (CLI-installed user adding the desktop)
5. pip-installed hermes_cli via system Python
6. bootstrap-needed sentinel -> hand off to runBootstrap
Deletes the entire FACTORY_HERMES_ROOT / RUNTIME_MARKER /
syncTreeExcludingVenv machinery (-200 lines). The isGitCheckout
guard that bit us in the install.ps1 PR is gone.
First-launch bootstrap (electron/bootstrap-runner.cjs)
1. Resolve install.ps1: prefer SOURCE_REPO_ROOT/scripts (dev), else
download from GitHub raw at INSTALL_STAMP.commit (cached at
HERMES_HOME\bootstrap-cache\install-<sha>.ps1).
2. Fetch the stage manifest via install.ps1 -Manifest -Commit X
-Branch Y.
3. Iterate stages: install.ps1 -Stage <name> -NonInteractive -Json
-Commit X -Branch Y per stage.
4. On all stages green: write the .hermes-bootstrap-complete
marker with {schemaVersion, pinnedCommit, pinnedBranch,
completedAt, desktopVersion}.
Per-run log to HERMES_HOME\logs\bootstrap-<ts>.log. Cancellation
via AbortSignal. Manifest cache so retries don't re-download.
Install overlay (src/components/desktop-install-overlay.tsx)
Mounted alongside the existing onboarding overlay; flexbox card
with header (static) + middle (scrollable) + footer (failure-only,
static). Subscribes to hermes:bootstrap:event IPC + resyncs from
hermes:bootstrap:get on mount/reload. Renders:
- 14-stage checklist with per-stage state icons
- Overall progress bar + current-stage spotlight
- Auto-expanded installer-output panel on failure
- "Copy output" button (full ring buffer + error to clipboard)
- "Reload and retry" wired through hermes:bootstrap:reset to
clear main.cjs's latched failure
Synthetic empty-manifest event from main.cjs flips the overlay to
'active' immediately so the slow install.ps1 download doesn't
leave the user staring at the generic Preparing splash.
Failure latching (main.cjs)
bootstrapFailure module-scope variable holds the rejection after
install.ps1 fails. startHermes() throws the latched error
immediately when set, bypassing the entire ensureRuntime +
runBootstrap chain. Without this, the renderer's ensureGatewayOpen
retries would re-run install.ps1 in a 5-10 min hot loop while the
user was still reading the failure overlay. Cleared via
hermes:bootstrap:reset on user-driven retry.
Unsupported-platform overlay (1F)
macOS / Linux packaged builds (no install.sh stage protocol yet)
emit an unsupported-platform event with a copy-pasteable install
command + docs URL. Dedicated overlay branch with "Copy command"
+ "I've run it -- retry" buttons.
install.ps1 additions (Phase 1F.3 + 1F.5)
-----------------------------------------
New -Commit and -Tag string params. Precedence Commit > Tag >
Branch. Honoured by all three code paths (update / fresh clone /
ZIP fallback), with archive URL selection that handles each
ref-type variant. Detached-HEAD checkouts intentionally -- they're
pins, not branches the user pulls into.
EAP=Continue wrap around the new pin-step git invocations. `git
fetch origin <commit>` writes the routine 'From <url>' info line to
stderr; under the script's global EAP=Stop that terminates the
script even though fetch+checkout succeed. Matches the established
pattern in Install-Uv, Test-Python, _Run-NpmInstall.
Backend fix (hermes_cli/web_server.py)
--------------------------------------
CORS allow_origin_regex now accepts Origin: 'null'. Packaged
Electron loads index.html via file://; Chromium sets the WebSocket
upgrade Origin header to the opaque origin 'null', which the old
regex rejected with HTTP 403 before gateway_ws() ever ran. This
failure mode was masked in the older FACTORY_HERMES_ROOT
architecture because the resolver often found an existing hermes
on PATH with different binding behavior.
Security maintained: localhost-only bind keeps cross-machine pages
out; per-process session token still gates every authenticated
/api/ endpoint regardless of Origin.
Desktop QoL
-----------
DevTools is now enabled in packaged builds (F12 / Cmd+Opt+I).
Field-debugging trade-off: tiny attack surface increase versus
a much better support story when CSP / WS / theme issues surface.
NSIS prereq-check page deleted (-767 lines). The standard
Welcome -> License -> Directory -> InstallFiles -> Finish wizard
now installs without custom Python/Git/ripgrep detection -- those
prereqs are install.ps1's job at first launch.
Test infrastructure (Phase 1G)
------------------------------
apps/desktop/scripts/test-desktop.mjs rewritten as a cross-platform
bundle validator (was darwin-only and asserted on dead factory-
payload paths):
NEGATIVE: hermes_cli/main.py is NOT shipped (regression guard)
POSITIVE: install-stamp.json carries a real commit + branch
POSITIVE: node-pty native deps shipped under resources/native-deps
POSITIVE: renderer dist/index.html reachable (asar or unpacked)
New nsis mode and npm run test:desktop:nsis script.
Validated end-to-end on clean Win10 VM
--------------------------------------
Confirmed: NSIS installer drops Electron shell, app launches,
install overlay shows progress, install.ps1 clones the pinned
commit, 14 stages run to completion, marker written, backend
spawns, WebSocket connects, onboarding overlay asks for API key,
main UI loads, integrated terminal works.
Failures handled: bootstrap stays failed (no hot-loop retry),
"Copy output" gives actionable transcript, "Reload and retry"
explicitly re-runs install.ps1.
What's deferred
---------------
- MSIX wrapping (Phase 2): same Electron .exe under MSIX manifest
with runFullTrust, signed and submitted to Microsoft Store.
- install.sh stage protocol parity (Phase 2): once shipped, the
unsupported-platform overlay becomes drive-it-yourself and
macOS/Linux packaged installers gain feature parity with Windows.
284 lines
13 KiB
Markdown
284 lines
13 KiB
Markdown
# Hermes Desktop
|
||
|
||
Native Electron shell for Hermes. It packages the desktop renderer, a bundled Hermes source payload, and installer targets for macOS and Windows.
|
||
|
||
## Setup
|
||
|
||
Install workspace dependencies from the repo root so `apps/desktop`, `apps/dashboard`, and `apps/shared` stay linked:
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
For Python, you have two options:
|
||
|
||
**Option A — let the desktop provision it for you (recommended for first-time setup):** just run `npm run dev`. On first launch the desktop creates a venv at `HERMES_HOME/hermes-agent/venv` and runs `pip install -e .` against the resolved Hermes source automatically. Requires Python 3.11+ on `PATH`.
|
||
|
||
**Option B — share an existing CLI install:** if you already ran `scripts/install.ps1` / `scripts/install.sh`, that's the same layout the desktop uses. The desktop reuses your existing venv and editable install — no extra steps. See [Runtime Bootstrap](#runtime-bootstrap) below for details.
|
||
|
||
If you're hacking on Hermes from a clone outside `HERMES_HOME/hermes-agent`, point the desktop at it explicitly:
|
||
|
||
```bash
|
||
HERMES_DESKTOP_HERMES_ROOT=/path/to/your/clone npm run dev
|
||
```
|
||
|
||
### Runtime prerequisites
|
||
|
||
Hermes Desktop needs:
|
||
|
||
- **Python 3.11+** — for the agent runtime, dashboard backend, and tool execution. (required)
|
||
- **Git for Windows** (Windows only) — provides Git Bash, which Hermes' terminal tool calls directly. Linux and macOS already ship a system bash. (required)
|
||
- **ripgrep** — used by Hermes' `search_files` tool for fast `.gitignore`-aware file/content search. Recommended on all platforms; Hermes falls back to `grep`/`find` if missing (works but slower and noisier).
|
||
|
||
The packaged Windows installer (`Hermes-*.exe`) detects all three at install time. Required items missing are auto-installed via `winget install -e --id Python.Python.3.11 --scope user` and `winget install -e --id Git.Git`. The recommended ripgrep is offered as `winget install -e --id BurntSushi.ripgrep.MSVC --scope user`. If `winget` isn't available the installer shows manual download URLs and lets you continue. The MSI installer (`Hermes-*.msi`) doesn't run the prereq page — enterprise deploys are expected to handle prereqs out-of-band.
|
||
|
||
For dev (`npm run dev`) the Python and Git Bash checks happen at first launch via the Electron bootstrapper, which throws a clear error if either prereq is missing. Manual install commands you can run yourself:
|
||
|
||
```powershell
|
||
winget install -e --id Python.Python.3.11 --scope user
|
||
winget install -e --id Git.Git
|
||
winget install -e --id BurntSushi.ripgrep.MSVC --scope user
|
||
```
|
||
|
||
## Development
|
||
|
||
```bash
|
||
cd apps/desktop
|
||
npm run dev
|
||
```
|
||
|
||
`npm run dev` starts Vite on `127.0.0.1:5174`, launches Electron, and lets Electron boot the Hermes backend (`hermes dashboard --no-open --tui`) on an open port in `9120-9199`. This path is for UI iteration and may still show Electron/dev identities in OS prompts.
|
||
|
||
Useful overrides:
|
||
|
||
```bash
|
||
HERMES_DESKTOP_HERMES_ROOT=/path/to/hermes-agent npm run dev
|
||
HERMES_DESKTOP_PYTHON=/path/to/python npm run dev
|
||
HERMES_DESKTOP_CWD=/path/to/project npm run dev
|
||
HERMES_DESKTOP_IGNORE_EXISTING=1 npm run dev
|
||
HERMES_HOME=/tmp/throwaway-hermes-home npm run dev
|
||
HERMES_DESKTOP_BOOT_FAKE=1 npm run dev
|
||
HERMES_DESKTOP_BOOT_FAKE=1 HERMES_DESKTOP_BOOT_FAKE_STEP_MS=900 npm run dev
|
||
```
|
||
|
||
`HERMES_DESKTOP_IGNORE_EXISTING=1` skips any `hermes` CLI already on `PATH`, which is useful when testing the factory-image bootstrap path.
|
||
|
||
`HERMES_HOME` overrides the install root (default: `%LOCALAPPDATA%\hermes` on Windows, `~/.hermes` elsewhere) — handy for sandboxed dev runs that shouldn't touch your real config.
|
||
|
||
`HERMES_DESKTOP_BOOT_FAKE=1` adds deterministic per-phase delays to desktop startup so you can validate the startup overlay and progress bar. For convenience, `npm run dev:fake-boot` enables fake mode with defaults.
|
||
|
||
On a fresh Hermes profile, Desktop shows a first-run setup overlay after boot. The overlay saves the minimum required provider credential (for example `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, or `OPENAI_API_KEY`) to the active Hermes `.env`, reloads the backend env, and then lets the user continue without opening Settings manually.
|
||
|
||
## Dashboard Dev
|
||
|
||
Run the Python dashboard backend with embedded chat enabled:
|
||
|
||
```bash
|
||
hermes dashboard --tui --no-open
|
||
```
|
||
|
||
For dashboard HMR, start Vite in another terminal:
|
||
|
||
```bash
|
||
cd apps/dashboard
|
||
npm run dev
|
||
```
|
||
|
||
Open the Vite URL. The dev server proxies `/api`, `/api/pty`, and plugin assets to `http://127.0.0.1:9119` and fetches the live dashboard HTML so the ephemeral session token matches the running backend.
|
||
|
||
## Build
|
||
|
||
```bash
|
||
npm run build
|
||
npm run pack # unpacked app at release/mac-<arch>/Hermes.app
|
||
npm run dist:mac # macOS DMG + zip
|
||
npm run dist:mac:dmg # DMG only
|
||
npm run dist:mac:zip # zip only
|
||
npm run dist:win # NSIS + MSI
|
||
```
|
||
|
||
Before packaging, the desktop app no longer bundles a copy of the Hermes Agent Python source. Instead, the packaged Electron app will fetch and install Hermes Agent at first launch via `scripts/install.ps1`'s stage protocol (Windows) — see the bootstrap flow documented in `electron/main.cjs`. macOS and Linux packaged builds are temporarily non-functional until `install.sh` gains the same stage protocol; dev workflows on all three platforms continue to work since they resolve a sibling source checkout.
|
||
|
||
## Automated Releases
|
||
|
||
Desktop installers are published by [`.github/workflows/desktop-release.yml`](../../.github/workflows/desktop-release.yml) with two channels:
|
||
|
||
- **Stable:** runs on published GitHub releases and uploads signed artifacts to that release tag.
|
||
- **Nightly:** runs on `main` pushes and updates the rolling `desktop-nightly` prerelease.
|
||
|
||
The workflow injects a channel-aware desktop version at build time:
|
||
|
||
- stable: derived from the release tag (for example `v2026.5.5` -> `2026.5.5`)
|
||
- nightly: `0.0.0-nightly.YYYYMMDD.<sha>`
|
||
|
||
Artifact names include channel, platform, and architecture:
|
||
|
||
```text
|
||
Hermes-<version>-<channel>-<platform>-<arch>.<ext>
|
||
```
|
||
|
||
Each run also publishes `SHA256SUMS-<platform>.txt` so installers can be verified.
|
||
|
||
### Stable release gates
|
||
|
||
Stable builds fail fast if signing credentials are missing:
|
||
|
||
- macOS signing + notarization: `CSC_LINK`, `CSC_KEY_PASSWORD`, `APPLE_API_KEY`, `APPLE_API_KEY_ID`, `APPLE_API_ISSUER`
|
||
- Windows signing: `WIN_CSC_LINK`, `WIN_CSC_KEY_PASSWORD`
|
||
|
||
Stable macOS builds also validate stapling and Gatekeeper assessment in CI before upload.
|
||
|
||
## Icons
|
||
|
||
Desktop icons live in `assets/`:
|
||
|
||
- `assets/icon.icns`
|
||
- `assets/icon.ico`
|
||
- `assets/icon.png`
|
||
|
||
The builder config points at `assets/icon`. Replace these files directly if the app icon changes.
|
||
|
||
## Testing Install Paths
|
||
|
||
Use the package-local test scripts from this directory:
|
||
|
||
```bash
|
||
npm run test:desktop:all
|
||
npm run test:desktop:existing
|
||
npm run test:desktop:fresh
|
||
npm run test:desktop:dmg
|
||
npm run test:desktop:platforms
|
||
```
|
||
|
||
`test:desktop:existing` builds the packaged app and opens it normally. It should use an existing `hermes` CLI if one is on `PATH`, preserving the user’s real `~/.hermes` config.
|
||
|
||
`test:desktop:fresh` builds the packaged app and launches it in a throwaway fresh-install sandbox. It sets `HERMES_DESKTOP_IGNORE_EXISTING=1`, points Electron `userData` at a temp dir, points `HERMES_HOME` at a temp dir, and launches through the factory-image bootstrap path without touching your real desktop runtime or `~/.hermes`.
|
||
|
||
`test:desktop:dmg` builds and opens the DMG.
|
||
|
||
`test:desktop:platforms` runs platform bootstrap-path assertions, including:
|
||
- existing-CLI vs factory-image runtime path selection semantics
|
||
- WSL2 protection against Windows `.exe/.cmd/.bat/.ps1` overrides
|
||
- platform-specific runtime import checks (`winpty` vs `ptyprocess`)
|
||
|
||
For fast reruns without rebuilding:
|
||
|
||
```bash
|
||
HERMES_DESKTOP_SKIP_BUILD=1 npm run test:desktop:fresh
|
||
HERMES_DESKTOP_SKIP_BUILD=1 npm run test:desktop:existing
|
||
HERMES_DESKTOP_SKIP_BUILD=1 npm run test:desktop:dmg
|
||
```
|
||
|
||
## Installing Locally
|
||
|
||
```bash
|
||
npm run dist:mac:dmg
|
||
open release/Hermes-0.0.0-arm64.dmg
|
||
```
|
||
|
||
Drag `Hermes` to Applications. If testing repeated installs, replace the existing app.
|
||
|
||
## Runtime Bootstrap
|
||
|
||
Hermes Desktop shares its install layout with the CLI installers (`scripts/install.ps1`, `scripts/install.sh`) so a desktop-only user and a CLI-only user end up with the same files in the same places.
|
||
|
||
### Where things live
|
||
|
||
```text
|
||
HERMES_HOME/ # %LOCALAPPDATA%\hermes (Windows)
|
||
# ~/.hermes (macOS / Linux)
|
||
├── hermes-agent/ # ACTIVE_HERMES_ROOT — git checkout
|
||
│ ├── .git/ # canonical install is always a git checkout
|
||
│ ├── hermes_cli/, agent/, ... # Python source
|
||
│ ├── pyproject.toml # source of truth for deps
|
||
│ ├── venv/ # virtualenv (Scripts\python.exe on Windows,
|
||
│ │ # bin/python elsewhere)
|
||
│ └── .hermes-bootstrap-complete # marker: first-launch install.ps1 succeeded
|
||
├── git/ # PortableGit (Windows; installed by install.ps1)
|
||
├── config.yaml # user config
|
||
├── .env # API keys
|
||
└── logs/
|
||
├── desktop.log # Electron-side boot log
|
||
├── agent.log
|
||
├── errors.log
|
||
└── gateway.log
|
||
```
|
||
|
||
The packaged installer ships only the Electron app — Hermes Agent itself is fetched and installed at first launch by running `scripts/install.ps1` (Windows) against the git ref baked into the .exe at build time (see `apps/desktop/scripts/write-build-stamp.cjs`).
|
||
|
||
### Resolution order
|
||
|
||
The desktop resolves a Hermes backend in this order:
|
||
|
||
1. `HERMES_DESKTOP_HERMES_ROOT` — explicit dev override.
|
||
2. Repo source root — only when running `npm run dev` from a checkout. Takes precedence over `HERMES_HOME/hermes-agent` so devs always run their local edits.
|
||
3. `HERMES_HOME/hermes-agent` if the `.hermes-bootstrap-complete` marker is present. The marker attests that install.ps1 succeeded and the user finished initial configuration; we trust the install and skip the bootstrap flow on every launch after the first.
|
||
4. Existing `hermes` CLI on PATH (skipped when `HERMES_DESKTOP_IGNORE_EXISTING=1`).
|
||
5. Pip-installed `hermes_cli` module via system Python.
|
||
6. None of the above → bootstrap-needed sentinel. The desktop's first-launch wizard runs `scripts/install.ps1` stages, then writes the marker on success.
|
||
|
||
### First-launch flow on a packaged install
|
||
|
||
1. `resolveHermesBackend()` returns `kind: 'bootstrap-needed'`.
|
||
2. The renderer shows the install overlay; main fetches `scripts/install.ps1` from GitHub at the pinned commit (from `install-stamp.json`).
|
||
3. Main drives `install.ps1 -Manifest` to get the stage list, then iterates `install.ps1 -Stage <name> -NonInteractive -Json` with live progress events to the renderer.
|
||
4. On all stages succeeding, main writes `.hermes-bootstrap-complete` with `{ schemaVersion, pinnedCommit, pinnedBranch, completedAt, desktopVersion }`.
|
||
5. Renderer hands off to the existing onboarding overlay (API key / model / persona).
|
||
6. Subsequent launches see the marker and skip everything in steps 1-5.
|
||
|
||
### Updates
|
||
|
||
Once bootstrapped, the install is a real git checkout. Updates flow through the in-app update path (`applyUpdates()` → `git fetch && git pull --ff-only` against the configured branch) or `hermes update` from the CLI. Both check `pyproject.toml` drift and re-run `pip install -e .` only when needed.
|
||
|
||
A user who installed via `scripts/install.ps1` directly (so `HERMES_HOME/hermes-agent/.git` exists but no `.hermes-bootstrap-complete` marker) is detected via resolver step 4 (their `hermes` CLI on PATH) and the desktop reuses their install without re-running the bootstrap.
|
||
|
||
## Debugging
|
||
|
||
Desktop boot logs are written to:
|
||
|
||
```text
|
||
HERMES_HOME/logs/desktop.log # %LOCALAPPDATA%\hermes\logs\desktop.log on Windows
|
||
# ~/.hermes/logs/desktop.log on macOS / Linux
|
||
```
|
||
|
||
If the UI reports `Desktop boot failed`, check that log first. It includes the backend command output and recent Python traceback context.
|
||
|
||
To force a fresh first-launch bootstrap (rare — useful for development / dogfooding the install flow):
|
||
|
||
```bash
|
||
# macOS / Linux
|
||
rm "$HOME/.hermes/hermes-agent/.hermes-bootstrap-complete"
|
||
|
||
# Windows (PowerShell)
|
||
Remove-Item "$env:LOCALAPPDATA\hermes\hermes-agent\.hermes-bootstrap-complete"
|
||
```
|
||
|
||
For a full reset of just the Python venv (rare — usually only needed if the venv is broken):
|
||
|
||
```bash
|
||
# macOS / Linux
|
||
rm -rf "$HOME/.hermes/hermes-agent/venv"
|
||
|
||
# Windows (PowerShell)
|
||
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\hermes\hermes-agent\venv"
|
||
```
|
||
|
||
To reset stale macOS microphone permission prompts:
|
||
|
||
```bash
|
||
tccutil reset Microphone com.github.Electron
|
||
tccutil reset Microphone com.nousresearch.hermes
|
||
```
|
||
|
||
## Verification
|
||
|
||
Run before handing off installer changes:
|
||
|
||
```bash
|
||
npm run fix
|
||
npm run type-check
|
||
npm run lint
|
||
npm run test:desktop:all
|
||
```
|
||
|
||
Current lint may report existing warnings, but it should exit with no errors.
|