Hermes Desktop App: Setup, Versions and Safe Updates

Hermes Desktop is the native, chat-first interface for Hermes Agent. It uses the same agent core as the CLI and messaging gateway, but the app on your computer and a backend on a server are separate update targets. A different version label is a reason to identify those targets, not a reason to erase your profiles.

Install Desktop and prove the first session#

The official Desktop documentation covers macOS Apple Silicon, Windows and Linux. Installation and update behavior depends on whether you use a bundled application, a source installation or another package channel. Do not assume a terminal command updates an app owned by the Microsoft Store.

For an existing CLI installation, start with:

hermes --version
hermes doctor
hermes desktop

These commands identify the runtime, check its environment and open Desktop. They do not prove provider authentication or tool permissions. In Desktop, select a profile and send a small request such as: “Tell me your current working directory. Do not edit any files.” Inspect the tool result and confirm that the directory belongs to the machine you intended.

For project work, hermes desktop --cwd /path/to/project selects an initial directory. Replace the example path with an existing project. A remote session's files live on its backend, not automatically on the laptop displaying the window.

If a fresh installation cannot answer, fix that failure before adding remote connections. If an update left the window blank, use the Desktop after-update recovery guide rather than deleting the Hermes home.

Read Desktop and backend versions separately#

A September 28 community support thread reported a Docker backend labeled v0.21.5 and a Desktop client labeled v0.17.6. The response distinguished the Desktop package version from the backend agent version and asked for the client's Commit row. That is a reported support case, not a benchmark or a compatibility guarantee for every build. See the source discussion.

Use that distinction to make an installation record:

1. Client: record the application channel, package version and build commit exposed in its version/About details. In the reported build, clicking the client version opened those details; labels can change across versions.
2. Backend: record the selected connection name, host, install method and agent version. For Docker, inspect the running container, not an unrelated host CLI.
3. Profile: record the profile selected for the failing session. The same computer can hold more than one Hermes configuration.
4. Symptom: distinguish “the labels differ” from a reproducible failure: a missing control, blank window, rejected connection or failed model request.
5. After update: reopen the intended application and compare its build identity with your before-update record. Then repeat the same small request.

On each relevant machine, a read-only starting point is:

hermes --version
hermes config path
hermes profile list

These report the CLI installation reached by that shell. They do not identify a different Desktop bundle or prove which container Desktop selected. Keep the app's own build details and connection target beside the terminal output.

An update notice plus an old commit is useful evidence that the client needs attention. A smaller package number alone is not. Do not invent a required client/backend number pairing: consult the installed release's documentation if behavior fails.

Choose the updater that owns the installation#

The official updating guide distinguishes these paths:

• Managed source checkout: use hermes update or its source-built Desktop update handoff.
• Windows sideload MSIX: use Desktop's Update control and Windows App Installer.
• Microsoft Store application: use Store updates.
• macOS bundled application: use Desktop's Update control.
• Docker backend: pull the chosen image and recreate the container with the same data mount; do not run the source updater inside an image-managed install.
• Nix installation: update the flake/profile and rebuild.

For a source installation, hermes update --check previews availability. It does not apply an update. On builds that support it, hermes update --plan previews the fleet targets. Check the installed help before relying on a newer option. Use the update failure runbook if the check fails, dependencies fail, or relaunch leaves the previous build running.

An update button may affect more than this window#

Current Desktop documentation says that, when multiple eligible update targets exist, the update action handles the connected backend first, other eligible registered gateways next, and Desktop last. Platform-managed Hermes Cloud entries are skipped. Review the target list and arrange a maintenance window before treating Update now as a cosmetic client refresh.

For a Docker deployment, keep its image-managed update path explicit rather than assuming every registered backend accepts a source update. Back up the owning state and confirm the mount before recreating anything. A successful download is not a successful relaunch, and a failed update check is not evidence that the app is current.

Stable, canary and one-off commit bundles are also different applications. The updating guide warns that separate applications can still share profiles and sessions under the same Hermes home. That is not data-schema isolation. Back up shared state before testing another build; do not assume an older app can safely read data written by a newer one.

Restore the context meter without resetting memory#

The bottom status bar is customizable. If it is missing, press Cmd/Ctrl+Shift+S. Right-click the visible bar, open Show in status bar, and enable Context meter. Click the meter for the Context Usage breakdown.

It separates live prompt categories such as system instructions, tools, skills, memory and conversation. Run /context in chat for context diagnostics. A hidden meter does not mean stored sessions or durable memory disappeared; a nearly full meter does not establish a provider billing error.

Cache hit rate and tokens per second can also be enabled in the status-bar menu. Treat these as session observations, not a monthly invoice. If the issue is recall, compression or the wrong session, use the memory and context troubleshooting guide.

Use projects, files and sessions deliberately#

Desktop supports concurrent chat tabs, project navigation, file previews, terminals, artifacts and Git review. Choose the working directory before asking for edits, inspect the resulting diff, and verify the produced file rather than trusting an activity card.

Missing repositories can be a discovery setting rather than lost data. Review Settings → Workspace, including scan roots and exclusions, or open the intended project directly. A profile switch changes the context in which you work; it is not an operating-system security boundary.

Bot Mode presents named profiles as Bots, with their own configuration, memory, credentials and conversation history. Routines are profile-scoped scheduled jobs. A remote Bot's state remains on its owning backend. If the roster looks empty, verify the connection and profile before creating replacement Bots that could duplicate existing work.

Connect a remote backend and test the real session#

A remote backend is useful when the runtime must remain available while the laptop is closed, or when files and tools belong on another machine. Follow the remote Desktop connection guide for private access, authentication and the exact service endpoint. The Desktop backend and a messaging gateway are separate operational concerns.

A public status response is weaker evidence than a working authenticated session. Run the connection test, open a chat under the intended profile and verify a harmless streamed response and file read on the backend. Do not disable authentication to make a test pass. If Telegram or Discord is part of the job, its destination needs a separate end-to-end check.

Current documentation describes both the headless hermes serve backend and the Dashboard-backed remote connection. Use the instructions matching your build and chosen surface. Do not substitute the separate OpenAI-compatible API endpoint for Desktop's connection.

Diagnose the failing layer before rebuilding#

Different labels, no functional failure#

Record the client build and backend identity first. Check for updates through their proper channels. Do not reinstall merely to force two independently versioned components to display the same number.

Blank window after an update#

Preserve the profile. Check whether the CLI still starts and whether the backend is reachable, then inspect the update log for the same attempt. A damaged source-built client may need a rebuild; that is different from repairing a Store or bundled application. Do not apply a generic pip install or source-build recipe to every distribution.

Window works but Chat does not#

Confirm the selected connection and profile, then authentication, live transport and provider response. A healthy renderer does not rule out a remote session failure. Rebuilding the client is not a substitute for fixing rejected credentials or an unreachable backend.

Update appears stuck#

The official Desktop guide says source/local update details go to the active profile's logs/update.log. Inspect new output and the failed phase, not just whether a process exists. Windows handoff progress and idle-watchdog behavior are version-dependent. Keep the attempt time and redacted error together; never post credentials or full authentication URLs with the log.

Work stopped when the laptop slept#

The backend's host must stay awake. Settings → Advanced → Keep computer awake can help a bounded local run, but it is not server supervision. A remote service must survive client disconnects independently. Test that boundary before relying on overnight work.

Desktop, self-hosted Dashboard or managed hosting?#

Choose Desktop for a native project workspace and direct visibility into local or remote agent work. Choose the self-hosted Dashboard when you want browser administration of a runtime you operate. Current Dashboard documentation also describes embedded TUI Chat with platform requirements; this is not the same product or operating commitment as a managed cloud service.

Choose the hosted route when you want browser/mobile access and managed uptime without operating the server, update process and gateway supervision yourself. Compare the current offer on Hermes and FlyHermes pricing. Hosting responsibility, model-account charges and integration authorization remain separate questions; do not assume any plan includes unlimited inference or every external integration.

Before returning to real work, confirm four things: the expected client build reopened, the intended backend and profile are selected, a harmless prompt completed, and any required channel or unattended job was independently verified. Those checks are stronger than a matching pair of version labels.