Maintain and Recover Hermes Desktop Safely

Desktop maintenance has three different scopes: updating the app, removing only the GUI, and removing the agent or its data. Recovery should start with logs and the least destructive action, not with deleting caches, environments, or user state.

Official Desktop documentation: Open the official guide

General update and uninstall guide: Open the official guide

Update and uninstall by scope

Hermes Desktop checks for updates in the background and can offer a one-click update. The manual Hermes update process also works with the GUI. Before updating during important work, finish or checkpoint active tasks, confirm the source and version, and preserve recoverable state.

Under Settings → About → Danger zone, choose exactly what to remove:

Uninstall Chat GUI only removes the Desktop app and its data while keeping the Hermes agent, configuration, and chats.
Uninstall GUI + agent, keep my data removes app and agent but preserves configuration, chats, and secrets for reinstall.
Uninstall everything removes app, agent, and user data.

The app closes while cleanup finishes. In a source checkout, GUI-only uninstall can also remove recoverable Desktop build artifacts such as node_modules, dist, and release.

Log-first recovery

Desktop boot logs are stored under HERMES_HOME/logs/desktop.log. Inspect them first, or follow current output with:

hermes logs gui -f

Use reset or deletion commands from the official troubleshooting guide only after the logs identify that layer, the path has been confirmed, and necessary data is backed up. A broken Python environment, a stuck microphone permission, and a blocked Electron download are different failures and should not share one blind cleanup routine.

Maintenance checklist

Confirm the active profile and whether work is still running.
Back up configuration and required user data before removal or major recovery.
Read desktop.log and capture the first relevant error boundary.
Choose GUI-only, agent-preserving, or full removal deliberately.
Treat cache, environment, and permission resets as targeted recovery actions.
If an Electron mirror is involved, review its trust boundary; checksum retrieval from the same mirror detects corruption, not mirror compromise.
After recovery, verify the app uses the expected agent, profile, sessions, and credentials without printing secrets.

Common pitfalls

Choosing full uninstall to fix one UI problem. That can destroy unrelated user state.
Deleting the managed environment before reading logs. Evidence disappears and the wrong layer may be rebuilt.
Assuming a third-party download mirror is equivalent to the official source. Use a trusted or organization-controlled mirror when policy requires it.
Reporting success because the window opens. Sessions, profiles, backend connectivity, and expected tools still need checks.

Verification

After an update or recovery, launch Desktop and confirm the version, active profile, session list, a harmless local chat, and expected file/terminal surfaces. For an uninstall, verify only the selected scope was removed and retained data remains where promised. Do not run destructive verification against a production profile merely to prove the buttons work.