mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-07-27 17:58:07 +00:00
7dd2b2dc77
Adds a first-run Desktop choice between installing Hermes locally and connecting to an existing remote Hermes gateway. The choice appears after backend resolution but before ensureRuntime(), so selecting remote cannot accidentally trigger local bootstrap. New modules: - first-run-setup-gate: concurrent first-run decision gate and reset semantics - primary-backend-startup: Electron-free orchestration seam (saved remote resolution, gate decision, remote re-resolution, local continuation) - primary-connection-rehome: prevents dual-owner race where both cold boot() and renderer softSwitch() could connect simultaneously - first-run-remote-form: extracted remote form with stale-result guards Reuses existing connection-config IPC, encrypted token storage, OAuth session partition, and primary backend resolution. Fixes #38602 Fixes #36970
216 lines
9 KiB
Markdown
216 lines
9 KiB
Markdown
# Hermes Desktop ☤
|
|
|
|
<p align="center">
|
|
<a href="https://github.com/NousResearch/hermes-agent/releases"><img src="https://img.shields.io/badge/Download-macOS%20%C2%B7%20Windows%20%C2%B7%20Linux-FFD700?style=for-the-badge" alt="Download"></a>
|
|
<a href="https://hermes-agent.nousresearch.com/docs/"><img src="https://img.shields.io/badge/Docs-hermes--agent.nousresearch.com-FFD700?style=for-the-badge" alt="Documentation"></a>
|
|
<a href="https://discord.gg/NousResearch"><img src="https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>
|
|
<a href="https://github.com/NousResearch/hermes-agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License: MIT"></a>
|
|
</p>
|
|
|
|
**The native desktop app for [Hermes Agent](../../README.md) — the self-improving AI agent from [Nous Research](https://nousresearch.com).** Same agent, same skills, same memory as the CLI and gateway, in a polished native window — chat with streaming tool output, side-by-side previews, a file browser, voice, and settings, no terminal required. Available for **macOS, Windows, and Linux**.
|
|
|
|
<table>
|
|
<tr><td><b>Chat with the full agent</b></td><td>Streaming responses, live tool activity, structured tool summaries, and the same conversation history as every other Hermes surface.</td></tr>
|
|
<tr><td><b>Side-by-side previews</b></td><td>Render web pages, files, and tool outputs in a right-hand pane while you keep chatting.</td></tr>
|
|
<tr><td><b>File browser</b></td><td>Explore and preview the working directory without leaving the app.</td></tr>
|
|
<tr><td><b>Voice</b></td><td>Talk to Hermes and hear it back.</td></tr>
|
|
<tr><td><b>Settings & onboarding</b></td><td>Manage providers, models, tools, and credentials from a real UI. First-run setup gets you to your first message in seconds.</td></tr>
|
|
<tr><td><b>Stays current</b></td><td>Built-in updates pull the latest agent and rebuild the app in place.</td></tr>
|
|
</table>
|
|
|
|
---
|
|
|
|
## Install
|
|
|
|
### Install with Hermes (recommended)
|
|
|
|
Already have the Hermes CLI? Just run:
|
|
|
|
```bash
|
|
hermes desktop
|
|
```
|
|
|
|
It builds and launches the GUI against your existing install — same config, keys, sessions, and skills. If Desktop cannot find a usable runtime or saved remote connection, first launch lets you connect to an existing Hermes gateway or install Hermes locally. Local onboarding then walks you through choosing a provider and model.
|
|
|
|
### Prebuilt installers
|
|
|
|
Prebuilt installers are built and distributed via [the Hermes Desktop website.](https://hermes-agent.nousresearch.com/).
|
|
|
|
---
|
|
|
|
## Updating
|
|
|
|
The app checks for updates in the background and offers a one-click update when one is ready. You can also update any time from the CLI:
|
|
|
|
```bash
|
|
hermes update
|
|
```
|
|
|
|
---
|
|
|
|
## Requirements
|
|
|
|
The installer handles everything for you (Python 3.11+, a portable Git, ripgrep).
|
|
|
|
---
|
|
|
|
## Development
|
|
|
|
Want to hack on the app itself? Install workspace deps from the repo root once, then run the dev server from this directory:
|
|
|
|
```bash
|
|
npm install # from repo root — links apps/desktop, web, apps/shared
|
|
cd apps/desktop
|
|
npm run dev # Vite renderer + Electron, which boots the Python backend
|
|
```
|
|
|
|
Point the app at a specific source checkout, or sandbox it away from your real config:
|
|
|
|
```bash
|
|
# throwaway HERMES_HOME, separate Electron userData, distinct app name to avoid the single-instance lock
|
|
../scripts/dev-sandbox.sh npm run dev
|
|
HERMES_DESKTOP_HERMES_ROOT=/path/to/clone npm run dev
|
|
HERMES_HOME=/tmp/throwaway npm run dev
|
|
npm run dev:fake-boot # exercise the startup overlay with deterministic delays
|
|
```
|
|
|
|
### Building installers
|
|
|
|
```bash
|
|
npm run dist:mac # DMG + zip
|
|
npm run dist:win # NSIS + MSI
|
|
npm run dist:linux # AppImage + deb + rpm
|
|
npm run pack # unpacked app under release/ (no installer)
|
|
```
|
|
|
|
Installers are built and uploaded to GitHub Releases manually. macOS/Windows signing & notarization happen automatically when the relevant credentials are present in the environment (`CSC_LINK` / `CSC_KEY_PASSWORD` / `APPLE_*` for macOS, `WIN_CSC_*` for Windows).
|
|
|
|
### How it works
|
|
|
|
The packaged app ships the Electron shell and a native React chat surface. On
|
|
first launch it can install the Hermes Agent runtime into `HERMES_HOME`
|
|
(`~/.hermes`, or `%LOCALAPPDATA%\hermes` on Windows), using the same layout as a
|
|
CLI install.
|
|
|
|
The app has three boundaries:
|
|
|
|
- **Electron** resolves and validates a runnable backend, owns native
|
|
filesystem/git/window capabilities, and exposes a narrow preload bridge.
|
|
- **React** owns the Desktop routes, panes, interaction state, and
|
|
`@assistant-ui/react` transcript.
|
|
- **Hermes Agent** runs as a headless `hermes serve` process and exposes the
|
|
`tui_gateway` JSON-RPC/WebSocket API. The renderer connects through
|
|
[`apps/shared`](../shared/), which is also used by the browser dashboard.
|
|
|
|
Backend resolution is an ordered ladder:
|
|
|
|
1. `HERMES_DESKTOP_HERMES_ROOT`
|
|
2. the current source checkout during development
|
|
3. a completed managed install
|
|
4. `HERMES_DESKTOP_HERMES`, or `hermes` on `PATH`
|
|
5. a system Python that can import the Hermes runtime
|
|
6. the first-launch bootstrap installer
|
|
|
|
Candidates are probed before use; an existing shim or interpreter is not enough.
|
|
A runtime that predates `serve` falls back to headless
|
|
`dashboard --no-open`. This is compatibility for the backend command only and
|
|
does not launch or embed the dashboard UI.
|
|
|
|
The Electron orchestration entry point is `electron/main.ts`; pure resolution,
|
|
probe, hardening, and platform policies live in focused modules beside it. The
|
|
renderer is under `src/`, with shared atoms in `src/store` and transport/native
|
|
adapters in `src/lib`.
|
|
|
|
Before changing the app, read:
|
|
|
|
- [`AGENTS.md`](./AGENTS.md): architecture, state ownership, resolver/fallback,
|
|
transport, performance, and testing rules.
|
|
- [`DESIGN.md`](./DESIGN.md): visual system, information architecture, motion,
|
|
direct manipulation, and keyboard behavior.
|
|
|
|
### Connections, projects, and switching
|
|
|
|
Desktop supports a managed local backend, explicit remote gateways, and Hermes
|
|
Cloud connections. Remote and cloud modes use the same remote-capability path;
|
|
authentication and discovery differ, not the renderer feature model.
|
|
|
|
When no usable local runtime or saved remote connection exists, the first-run
|
|
screen offers **Connect to existing Hermes** before starting the local installer.
|
|
Desktop probes the gateway to discover token or OAuth authentication, requires a
|
|
successful HTTP and WebSocket connection test, and saves the connection using
|
|
the same encrypted Desktop configuration used by Settings. A saved remote
|
|
connection bypasses this choice on later launches. The regular Desktop build
|
|
still includes the local-install option; this is a remote operating mode, not a
|
|
separate client-only application.
|
|
|
|
In remote mode the gateway host is the execution boundary: agent tools,
|
|
terminal commands, and file operations run against the remote Hermes host, not
|
|
the computer displaying the Desktop UI.
|
|
|
|
Projects are the workspace abstraction. A project may own multiple folders,
|
|
repositories, worktrees, and sessions; a bare new chat remains detached unless
|
|
the user enters a project or configures a default project directory. Use the
|
|
Projects UI rather than adding a second per-session folder-picker workflow.
|
|
|
|
Changing profiles or connection modes is a soft workspace switch, not another
|
|
cold boot. The shell and current management overlay remain mounted while
|
|
gateway-bound nanostores are wiped, query-backed data is invalidated, and the
|
|
new connection repopulates skeletons. This prevents rows or transcripts from
|
|
the previous gateway bleeding into the next one.
|
|
|
|
### Verification
|
|
|
|
Run before opening a PR (lint may surface pre-existing warnings but must exit cleanly):
|
|
|
|
```bash
|
|
npm run fix
|
|
npm run typecheck
|
|
npm run lint
|
|
npm run test:ui
|
|
npm run test:desktop:platforms
|
|
```
|
|
|
|
Run `npm run test:desktop:all` for install, boot, update, packaging, or other
|
|
release-path changes.
|
|
|
|
### Troubleshooting
|
|
|
|
Boot logs land in `HERMES_HOME/logs/desktop.log` (includes backend output and recent Python tracebacks) — check it first if the app reports a boot failure.
|
|
|
|
**macOS / Linux:**
|
|
|
|
```bash
|
|
# Force a clean first-launch setup
|
|
rm "$HOME/.hermes/hermes-agent/.hermes-bootstrap-complete"
|
|
# Rebuild a broken Python venv
|
|
rm -rf "$HOME/.hermes/hermes-agent/venv"
|
|
# Reset a stuck macOS microphone prompt (macOS only)
|
|
tccutil reset Microphone com.nousresearch.hermes
|
|
```
|
|
|
|
**Windows (PowerShell):**
|
|
|
|
```powershell
|
|
# Force a clean first-launch setup
|
|
Remove-Item "$env:LOCALAPPDATA\hermes\hermes-agent\.hermes-bootstrap-complete"
|
|
# Rebuild a broken Python venv
|
|
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\hermes\hermes-agent\venv"
|
|
```
|
|
|
|
> The default Hermes home on Windows is `%LOCALAPPDATA%\hermes`. Set the `HERMES_HOME` env var if you've relocated it.
|
|
|
|
---
|
|
|
|
## Community
|
|
|
|
- 💬 [Discord](https://discord.gg/NousResearch)
|
|
- 📖 [Documentation](https://hermes-agent.nousresearch.com/docs/)
|
|
- 🐛 [Issues](https://github.com/NousResearch/hermes-agent/issues)
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
MIT — see [LICENSE](../../LICENSE).
|
|
|
|
Built by [Nous Research](https://nousresearch.com).
|