How-To Guide
Hermes Desktop Won't Open After an Update
Recover Hermes Desktop when it will not launch after an update without deleting profiles, memory, sessions, skills, or credentials.
Quick answer
Do not delete ~/.hermes. Close every Hermes Desktop window and stale Hermes backend or gateway process, then run hermes --version, hermes doctor, and hermes chat -q "reply ok". If the CLI works, try hermes dashboard to confirm your profile state is intact. Next run hermes update --check, back up important state with hermes update --backup, complete the supported update, and relaunch with hermes desktop. On Windows, stop processes that lock hermes.exe or the venv before retrying.
A Desktop app that stops opening after an update is usually a client build, dependency, updater, process-lock, or backend-startup problem—not proof that Hermes lost your data. This recovery guide isolates the native app from the shared agent runtime, protects state with the Hermes backup and restore workflow, and uses the current safe update path. It is intentionally narrower than the general Hermes Desktop app guide and the Windows installation guide.
Managed cloud · API costs included · Skill library · Cancel anytime
Before you start:
- ☑Terminal access on the same Windows, macOS, or Linux account that runs Hermes Desktop
- ☑Enough disk space for an update snapshot and Desktop dependency rebuild
- ☑Permission to stop a local Hermes gateway briefly if it holds update files open
- ☑A copy of any visible error plus
~/.hermes/logs/update.logand~/.hermes/logs/bootstrap-installer.logwhen present
Steps
- 1
Protect the Hermes home before changing anything
Do not uninstall everything or delete
~/.hermes. That directory can hold profiles, sessions, memory, skills, cron jobs, auth, and config. If the CLI still starts, runhermes update --backup; otherwise copy the Hermes home before reinstalling. Follow the backup guide when the profile is expensive to reconstruct. - 2
Close Desktop and stop stale child processes
Quit every Desktop window. Stop the local gateway with
hermes gateway stopif it uses the same install, exit open Hermes REPLs, and close old updater or backend processes. On Windows this matters because runninghermes.exe, Python, or native-extension files can lock the venv and make a dependency refresh stop halfway. - 3
Prove whether the shared Hermes runtime still works
Run
hermes --version,hermes doctor, andhermes chat -q "reply ok". If these pass, your provider, profile, and core runtime are available; focus on Desktop build or startup. If they fail, use the layer-by-layer Hermes troubleshooting guide before rebuilding the GUI. - 4
Use Web UI as a recovery checkpoint
Run
hermes dashboardand openhttp://127.0.0.1:9119. A working Hermes dashboard confirms that sessions and profile state can still be read, but it does not repair Desktop by itself. Stop it before relaunching Desktop if both try to own the same backend port. - 5
Read the updater logs before retrying
Inspect
~/.hermes/logs/update.logand~/.hermes/logs/bootstrap-installer.log. Look for a real updater still running, an in-progress marker, Node/npm engine mismatch, PATH failure, locked Windows executable, failed native dependency, or incomplete Desktop build. Do not remove~/.hermes/.hermes-update-in-progressunless no updater process is active. - 6
Preview and complete the supported update
Run
hermes update --check, thenhermes update. Read any partial-update message literally: core Python may be current while Desktop assets are not. If Node/npm failed, comparenode --versionandnpm --versionwith the current source requirements instead of bypassing engine checks or using blanketsudo. The hanging-update recovery guide covers mixed dependency state. - 7
Rebuild and relaunch the native app
Run
hermes desktop. The command installs the Desktop workspace dependencies, builds the current operating system's unpacked Electron app, and launches it. Usehermes desktop --force-buildwhen a stale content stamp or incomplete build is the suspected cause. Use--skip-buildonly when a verified unpacked app already exists. - 8
Apply the operating-system branch
On Windows, close every process using the Hermes venv and retry the transactional update before forcing anything. On macOS, check reduced PATH when app-launched subprocesses cannot find git, ssh, bash, node, or npm. On Linux, verify Node/npm, executable permissions, and whether the app was started from the same account and environment as the working CLI.
- 9
Reconnect the intended local or remote backend
If Desktop opens but Chat disconnects, confirm the profile's connection mode. Local mode starts its own
hermes servebackend; remote mode points to a protected serve-compatible backend, normally on port 9119—not the OpenAI-compatible API on 8642. Use the remote Desktop backend guide for HTTP versus WebSocket failures. - 10
Verify one real Desktop workflow
Open the intended profile, send one message, and verify one artifact, file, terminal action, or tool result. If you restarted a gateway, also test the exact Telegram or Discord destination. Choose FlyHermes managed hosting when the real requirement is browser/mobile access and uptime without owning Desktop, provider, update, backup, and gateway maintenance.
Pro Tips
- 💡Treat a working CLI or dashboard as evidence that state survived, not as proof the native app is repaired.
- 💡Use
hermes desktop --force-buildfor a suspected stale or incomplete Desktop artifact; do not begin with a full data-destructive uninstall. - 💡On Windows, do not use
--force-venvuntil you have verified that reported venv holders are false positives. - 💡If only the GUI needs removal,
hermes uninstall --guipreserves the agent, config, and chats; avoidhermes uninstall --fullduring recovery. - 💡After recovery, follow the session handoff checklist before a planned restart of important long-running work.
Troubleshooting
❌ Desktop disappeared or still does nothing after clicking Update
✅ Close stale app/backend processes, inspect both update logs, run the CLI smoke test, complete hermes update, then rebuild with hermes desktop --force-build. Preserve ~/.hermes throughout.
❌ Windows says another hermes.exe or venv Python process is running
✅ Close Desktop and open Hermes terminals, run hermes gateway stop, then retry. The updater refuses partial native-dependency replacement because Windows locks running executables and .pyd files.
❌ Update reports success but Desktop assets are still mixed
✅ Check the update output for a Node/npm workspace failure. Repair the Required versus Actual engine mismatch, rerun the update, and force a Desktop rebuild before relaunching.
❌ CLI and dashboard work but Desktop cannot start its local backend
✅ Stop the dashboard or other process using port 9119, verify the selected profile and connection mode, then relaunch Desktop. Inspect backend startup output rather than deleting profile data.
❌ Desktop opens but a remote agent will not connect
✅ Test both the backend HTTP status and WebSocket path, verify authentication, use port 9119 for the serve-compatible backend, and make sure the profile did not fall back to a different local connection.
❌ macOS app launch cannot find git, node, npm, ssh, or bash
✅ Compare the app or service PATH with the interactive shell. Use explicit standard macOS paths or relaunch from a correctly initialized environment; do not assume a working terminal PATH is inherited by app-launched subprocesses.
❌ Reinstall seems necessary
✅ Back up first. Prefer repairing the update and rebuilding Desktop. If GUI-only removal is needed, use hermes uninstall --gui, then run hermes desktop; this keeps the Hermes agent and user state.
FAQ
Will reinstalling Hermes Desktop delete my memory and sessions?
A GUI-only reinstall should preserve the agent and user state, but back up first. Do not delete ~/.hermes or use the full-uninstall option during ordinary Desktop recovery.
What command should I run when Hermes Desktop will not open?
Start with hermes doctor and a CLI chat smoke test. Then preview and complete the update, and launch or rebuild the app with hermes desktop or hermes desktop --force-build.
Why does Windows block the Hermes Desktop update?
A running Desktop backend, gateway, REPL, or venv Python process can hold hermes.exe or native files open. Close those processes before retrying so the updater can replace dependencies transactionally.
Does a working dashboard prove Hermes Desktop is fixed?
No. It proves the shared runtime and profile state are reachable. Desktop still needs its own build, backend startup, authentication, and native UI verification.
Should I remove the update-in-progress marker?
Only after confirming no updater is running. Removing the marker while a real update is active can create overlapping update attempts.
When should I use FlyHermes instead of repairing Desktop?
Use FlyHermes when you want managed browser/mobile access, connected channels, and uptime without maintaining local Desktop builds, dependencies, provider credentials, backups, and gateways.
Related setup and cost guides
Update Hermes Agent safely
Preview, back up, update, read partial failures, and verify the runtime.
Hermes Desktop app guide
Install, launch, manage profiles, inspect context, and choose a local or remote backend.
Windows Desktop install troubleshooting
Separate native Windows, WSL, PATH, proxy, dependency, and app-loading failures.
Hermes Web UI recovery checkpoint
Confirm profile and session state from the self-hosted browser control plane.
FlyHermes managed path
Compare managed browser/mobile access and uptime with self-hosted maintenance.