Hermes Desktop Install Troubleshooting on Windows

Steps

1. 1

   Capture the failing stage before reinstalling

   Record whether the failure happens while downloading Desktop, provisioning Python/Node/PortableGit, cloning Hermes, installing Python or npm dependencies, opening the app, or sending the first model request. A bootstrap error, PATH error, and provider error need different fixes.

2. 2

   Open a new PowerShell session and verify PATH

   Close the terminal used during installation, open a new PowerShell window, then run Get-Command hermes and hermes --version. The native installer updates User PATH, but existing terminals do not inherit that change.

3. 3

   Separate Desktop from the Hermes core install

   If the GUI bootstrap failed, run the official native installer: iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1). Then run hermes doctor. A working CLI proves the core runtime is healthy even if Desktop still needs repair.

4. 4

   Check the native Windows install directories

   Confirm the disposable code and virtual environment live under %LOCALAPPDATA%\hermes\hermes-agent, while config, auth, skills, sessions, and logs live directly under %LOCALAPPDATA%\hermes. Do not delete the whole Hermes root if you want to preserve user data.

5. 5

   Diagnose enterprise npm proxy failures

   If the error names an unavailable npm package or version, test that exact dependency against the approved registry. Ask IT to mirror the current lockfile dependencies or temporarily permit the public npm registry. Do not freeze an old package version from a support thread into your permanent setup.

6. 6

   Verify Node and command shims

   Run node --version, npm --version, and Get-Command npx.cmd. Current native Windows setup provisions Node for browser and bridge features. If an older system Node shadows the managed install, fix PATH ordering rather than invoking extensionless Unix shims.

7. 7

   Run the smallest provider smoke test

   Use hermes model or hermes setup --portal, then run hermes chat -q "Reply with OK". If Desktop loads forever but this command fails too, diagnose provider auth, credits, or network access before rebuilding the interface.

8. 8

   Choose native Windows or WSL2 deliberately

   Stay native for the CLI, Desktop, gateways, cron, browser tools, MCP, and the normal dashboard. Use WSL2 when you specifically need POSIX semantics or the dashboard /chat embedded terminal pane. Native and WSL2 keep separate Hermes homes, so do not troubleshoot them as one install.

9. 9

   Test Desktop with one local profile

   Launch Desktop only after the CLI smoke test passes. Select the same provider/profile, send one harmless prompt, and inspect the exact log time if the interface remains loading. Add a remote backend only after local Desktop works.

10. 10

    Escalate with a redacted diagnostics packet

    Include Windows version, Desktop version, install method, exact failing stage, hermes --version, hermes doctor summary, Node/npm versions, registry/proxy context, and redacted logs around one controlled retry. Remove tokens, keys, usernames, and private URLs.

Pro Tips

• 💡Use the PowerShell installer as a diagnostic lane, not as a second mystery install: Desktop and native CLI share the same Windows runtime directory.
• 💡A new PowerShell window is the first PATH fix; manually appending directories can hide the real installer state.
• 💡On corporate machines, verify the exact registry configured by npm config get registry without copying authentication tokens into support messages.
• 💡If the installer names one missing npm package, verify registry availability before repeatedly deleting the whole install.
• 💡Keep %LOCALAPPDATA%\hermes user data when reinstalling; remove only the disposable hermes-agent subdirectory unless you intentionally want a full reset.
• 💡Use hermes doctor after every repair so dependency problems are separated from provider and gateway problems.
• 💡Do not debug a remote backend, Docker socket, Desktop UI, and model provider in the same retry.
• 💡Native Windows supports the normal dashboard, but its embedded terminal pane needs WSL2; that limitation is not a failed Desktop install.
• 💡For an always-on business agent, installation success is not uptime. You still own Windows login tasks, provider credits, updates, backups, and channel delivery.
• 💡Choose FlyHermes when browser/mobile access and managed uptime matter more than maintaining a Windows or VPS runtime.

Troubleshooting

FAQ

Related setup and cost guides