feat(desktop): add "Connect to existing Hermes" option to first-run onboarding

[OutThisLife]

Adds a first-run Desktop choice between installing Hermes locally and connecting to an existing remote Hermes gateway. When Desktop can't find a usable local runtime or saved remote connection, users can connect to a running gateway without first installing Python, cloning the agent, or creating a local virtualenv. The unsupported packaged-install screen gets the same remote escape hatch.

The decision gate sits after backend resolution and before ensureRuntime(), so choosing remote can never fall through into local bootstrap. Remote credentials flow through the existing hermes:connection-config:apply IPC, encrypted token storage, and OAuth session partition — no new credential path, no new model tools, no prompt-cache or public-config changes, no new env vars.

This is a rebase/salvage of #60489 by @cat-thats-fat onto current main. The original was ~939 commits behind and GitHub-merge-conflicted after apps/desktop/electron/main.ts was reworked; the only real conflict was a single import collision, resolved by keeping both imports. The extracted orchestration seams (primary-backend-startup, primary-connection-rehome, first-run-setup-gate) re-integrate cleanly into the evolved startHermes() — verified by typecheck, the desktop test suite, and lint.

The main-process integration test (first-run-setup-main-process.test.ts) covers the exact gap flagged in review: a first-run bootstrap-needed remote apply connects remotely with ensureRuntime/runBootstrap called zero times.

Validation

• npm run typecheck (renderer + electron + e2e) — clean
• npx vitest run on the 5 new/changed test files — 30 passed
• npm run lint — 0 errors

Supersedes #60489
Fixes #38602
Fixes #36970

Co-authored-by: cat-thats-fat declanbatesmith@outlook.com

[github-actions]

૮ >ﻌ< ა ci review

_{ran on 7dd2b2d}

all good!

[cogitech2]

How do I get this to work? The installer still does the same thing it always did before. No option to just install the Desktop. Now I have a bunch of junk installed on my laptop that I don't want or need.

[zhengyilab]

Great to have this merged now! It could be much easier to have another desktop frontend deployed.

How do I get this to work? The installer still does the same thing it always did before. No option to just install the Desktop. Now I have a bunch of junk installed on my laptop that I don't want or need.

-I believe it's only changed behavior for the first-run, right? so for existing desktop deployed, it does not remove that backend/bootstrap installed. A fresh deploy might be needed if you want to make a simple client-only desktop.

[damian-duchnowski]

New release, but the Desktop installer still doesn't have this implemented. Am I doing something wrong?

[shniubobo]

For anyone wondering why this isn't working as you have expected, this PR is not related to the current Desktop installer shipped on Hermes' website.

There are two kinds of installer for Hermes. One is built from /apps/bootstrap-installer, which is what you download from Hermes' website, and doesn't benefit from this PR. To benefit from this PR, you have to use the other installer, which is built from /apps/desktop.

However, that kind of installer is NOT pre-built and shipped by Hermes, so you have to build it yourself:

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent/apps/desktop
nvm use
npm i
npm run dist:win:nsis  # For Windows
npm run dist:mac:dmg   # For Mac

So instead of setting up a full Python environment, now you need to set up a full Node environment 😅

[cogitech2]

Thank you!

So to be clear, there is no version for Linux?

[shniubobo]

Thank you!

So to be clear, there is no version for Linux?

There are several packaging options for Linux, all within the same command: npm run dist:linux. You can find all available options in apps/desktop/package.json.

[cogitech2]

Thank you!
So to be clear, there is no version for Linux?

There are several packaging options for Linux, all within the same command: npm run dist:linux. You can find all available options in apps/desktop/package.json.

Thanks. Yes, in the meantime I read the README and figured out how to run the installer build. It failed at the step where it creates the .deb, but I am running the appimage (eeewww) and so far it is working.

Thanks again. Not the smoothest UX but I'll take what I can get. :)