Hermes Desktop is the native, chat-first interface for the same Hermes Agent runtime used by the CLI, TUI, and messaging gateway. It shares your profiles, provider keys, sessions, memory, skills, and tools instead of creating a separate desktop-only agent.
Quick answer#
Install Hermes Agent, run hermes doctor, then launch the native app with hermes desktop. The app works on macOS, Windows, and Linux. If the bottom context meter is missing, right-click the status bar and enable Context meter under Show in status bar; Cmd/Ctrl+Shift+S toggles the entire bar. Click the meter for a category-level token breakdown, or run /context in chat. The current Bots tab is Bot Mode: each Bot is an isolated Hermes profile with its own config, memory, skills, credentials, and canonical chat; its Routines are ordinary profile-scoped cron jobs. Keep the computer awake for long local runs, or connect Desktop to a remote hermes serve backend when work must continue after the laptop closes.
What this guide is for#
People searching for the Hermes Desktop app usually want a native interface without giving up the agent's local tools, files, sessions, memory, or profiles. They also need to know which controls are Desktop-only, why context or project UI may disappear, and when a local laptop should give way to an always-on remote backend.
Use this article as a practical checklist. If you are evaluating Hermes for the first time, begin with install Hermes Agent. If you already run Hermes locally and want the agent to stay online, compare the workflow with self-host Hermes. If you need a managed or commercial route, check Hermes pricing before overbuilding your own deployment.
Practical setup checklist#
- Confirm the base agent works — run one local Hermes prompt before adding any integration, backend, or UI layer.
- Choose the narrow workflow — define the smallest outcome that proves the Desktop app works on your platform; do not begin with a giant automation.
- Add credentials safely — place API keys, bot tokens, and webhook secrets in config or environment files, never in prompts or committed content.
- Enable only the needed tools — give Hermes the specific browser, terminal, messaging, file, or web tools required for this workflow.
- Run a visible smoke test — send one message, create one file, complete one background job, or receive one webhook event.
- Save the procedure — after the first success, turn the verified steps and pitfalls into a Hermes skill so the workflow improves next time.
This order matters. If the model key is wrong, every gateway looks broken. If the workspace mount is wrong, every Docker run looks like a reasoning failure. If a bot token is copied into the wrong profile, the agent can be healthy while the integration stays silent.
Hermes-specific proof points#
- Persistent memory: persistent memory lets Hermes remember stable preferences, project facts, and corrections across sessions.
- Reusable skills: the Hermes skills guide explains how successful procedures become reusable operating knowledge.
- Tool execution: Hermes can use terminal, browser, web, file, GitHub, messaging, and MCP-style tools when the profile enables them.
- Gateway architecture: platform-specific entry points can route into the same underlying agent instead of creating separate bot brains.
- Self-hosting path: long-running workflows can move from a laptop to a server when reliability matters.
These are the reasons Hermes is different from a normal chatbot. A hosted chat tab can answer a question, but Hermes can remember how your environment works, call tools, and repeat a verified process.
Common failure modes and fixes#
- The agent does not start: check Python, Node, PATH, virtualenv, and the Hermes config path before debugging the workflow itself.
- The model answers but tools fail: the provider may work while tool calling, toolsets, or local permissions are disabled.
- The integration is silent: bot tokens, OAuth scopes, channel permissions, webhook URLs, or gateway processes are usually the cause.
- The task works once but not later: store durable facts in memory and procedural steps in skills instead of relying on the current chat.
- A background workflow reports success too early: verify the real artifact, rendered page, sent message, or external event, not only the process exit code.
When troubleshooting, change one layer at a time. Start with the CLI, then the model, then tools, then the backend, then the integration. This makes the root cause visible instead of turning the whole setup into a guessing game.
When to use this workflow#
Use this workflow when the result needs continuity. Good examples include team message gateways, scheduled monitoring, coding tasks with repeatable review steps, local file operations, server-side automations, and research processes that should remember prior decisions. Hermes is usually overkill for a single casual answer, but it is a strong fit when the agent should become part of how work gets done.
If the task touches sensitive files, paid APIs, production servers, or public messaging channels, add a human approval point. Hermes can act quickly, which is useful, but operational speed should be paired with clear scope and reversible steps.
Restore and read the Hermes Desktop context meter#
The status bar at the bottom of Desktop is customizable. Reinstalling Hermes or changing the workspace can leave the context meter hidden even though session context, history, and durable memory are healthy.
- Right-click the bottom status bar.
- Open Show in status bar.
- Enable Context meter.
- If the whole bar is hidden, press
Cmd/Ctrl+Shift+S. - Send a message in the current chat if the meter has no usage data yet.
- Click the meter to open the Context Usage popover.
The popover separates the system prompt, tool definitions, skills, memory, rules, MCP, subagent definitions, and conversation tokens. Run /context for the in-chat summary or /context all when you need per-skill and per-toolset detail. This diagnoses the live prompt window; it does not represent every provider billing category. Use /usage for provider/session consumption, and follow the memory and context troubleshooting guide when the symptom is recall drift rather than a hidden meter.
A full meter is not proof that memory is broken. It usually means the current conversation, tool output, loaded skills, or system instructions are large. Inspect first, then use /compress or start a clean session with a handoff if needed. The context compression guide explains that decision.
Hermes Desktop is not the Web Dashboard#
Hermes Desktop and the Hermes Web UI dashboard share the same agent state, but they are different surfaces. Desktop is a native application for chat, projects, files, terminals, artifacts, Git review, and concurrent sessions. Web UI is a browser control plane for profiles, config, keys, sessions, logs, cron jobs, tools, and gateways; its optional Chat tab embeds the TUI.
Desktop starts its own local hermes serve backend and does not require the dashboard. A remote Desktop connection also targets a hermes serve-compatible backend, normally on port 9119, not the OpenAI-compatible API server on port 8642. For browser administration, use the dashboard setup guide. For managed browser/mobile access and uptime without maintaining either backend, compare FlyHermes pricing.
Install and launch the current Desktop app#
- Follow the Hermes installation guide.
- Run
hermes doctorandhermes chat -q "Reply with desktop-ready"to prove the provider and runtime work. - Launch the native app with
hermes desktop. Existing profiles, keys, sessions, skills, tools, and memory are reused. - Open a project with
hermes desktop --cwd /path/to/project, or select a repository in the Projects sidebar. - Ask for one visible artifact, file inspection, or small diff and verify the real output.
The first source-based launch can build the Electron application. Later launches may use hermes desktop --skip-build when a current packaged build exists. Use --force-build only when the local app bundle is stale or damaged.
What the native app includes#
- Chat and queued prompts: streaming responses, tool activity, file drop, prompt history, queue editing, and transcript search.
- Projects and files: repository discovery, file browsing, side-by-side previews, and a selectable working directory.
- Artifacts: a searchable gallery of generated files, images, and links connected to their source sessions.
- Tabs, windows, and panes: concurrent sessions, popped-out chats, project navigation, preview panes, and persistent terminals.
- Git review: changed files, scoped diffs, staging, commit/push controls, pull-request actions, branches, and worktrees.
- Profiles and management: providers, models, tools, MCP, skills, memory, cron, messaging, agents, and Command Center.
- Quick Entry and HUD: a global prompt shortcut and an always-on-top chat surface for work over other applications.
These surfaces improve visibility, but they do not replace acceptance tests. A polished activity stream is not proof that a file is correct, a deployment is live, or a scheduled message arrived. Keep verifying the external artifact, as described in the Hermes troubleshooting guide.
Keep long local runs alive#
Desktop work runs on the machine hosting its backend. If the computer sleeps or shuts down, local turns and scheduled work cannot continue. Enable Settings → Advanced → Keep computer awake for a bounded long local run; the display may still dim.
For business-critical schedules, connect Desktop to an always-on home server or VPS, or use managed cloud. The self-hosted vs hosted AI agent guide explains who owns process supervision, credentials, updates, backups, and incident recovery. The phone access guide also separates controlling a remote agent from trying to host the full runtime on a phone.
Connect Desktop to a remote Hermes backend#
On the remote machine, run and supervise hermes serve. In Desktop, open Settings → Gateway → Connection mode, choose Remote gateway, enter the backend URL, and sign in. Connection mode is profile-specific, so one profile can stay local while another points at a VPS, home server, or cloud agent.
Use Nous OAuth or your own OIDC provider for anything reachable beyond a trusted private network. Username/password is suitable only for a trusted LAN or VPN such as Tailscale. A non-loopback backend engages the authentication gate automatically. Do not expose an unauthenticated admin endpoint.
The connection has separate HTTP and WebSocket legs. A status probe can succeed while live Chat fails. Test the connection in Desktop, open a new session, send one prompt, and verify streamed output. If messaging channels are also required, run the gateway as a separate service and test the exact destination. The remote Desktop backend guide covers the full path.
Common Desktop problems#
The context meter disappeared#
Right-click the status bar, enable Context meter, and use Cmd/Ctrl+Shift+S if the entire bar is hidden. Run /context to confirm live data exists. A hidden UI item does not delete messages or memory.
Desktop opens but the model cannot answer#
Run hermes doctor plus a one-turn CLI smoke test. Repair provider authentication or configuration before rebuilding the application.
Projects or repositories are missing#
Launch with --cwd, or review Settings → Workspace. Repository discovery is profile-specific and can be restricted with desktop.repo_scan_roots, disabled with desktop.repo_scan_enabled, or pruned with excluded paths.
A long run stopped overnight#
Check whether the machine slept. Enable Keep computer awake for local work, then repeat a bounded test. Move unattended jobs to an always-on backend when laptop availability cannot be the uptime guarantee.
Remote status works but Chat disconnects#
Verify the backend is a reachable hermes serve process rather than port 8642; confirm authentication, the exact URL, and the WebSocket path. Test both connection legs from Desktop.
Desktop looks healthy but Telegram or cron failed#
Desktop shows local state. Channel routing, allowlists, the profile-specific gateway process, delivery permissions, and provider credits still require an end-to-end test. Use the gateway troubleshooting guide when a bot is silent.
Desktop, self-hosted Web UI, or FlyHermes?#
Choose Hermes Desktop for native local chat, project files, terminals, Git review, artifacts, and multiple working sessions. Choose self-hosted Web UI for browser-based administration and monitoring of a runtime you operate. Choose FlyHermes when the requirement is managed browser/mobile access, connected channels, and reliable uptime without owning the VPS, authentication, provider, update, backup, and gateway maintenance loop.
Bottom line#
Hermes Desktop is now a full native workspace, not a thin Mac-only wrapper around terminal chat. Start with hermes doctor, launch with hermes desktop, restore the context meter from the status-bar menu when needed, and verify one real artifact before expanding. Keep the local computer awake for bounded long runs; use a protected remote backend or FlyHermes when the agent must keep working after the laptop closes.
Use Web UI to separate a Desktop client failure from a backend failure#
If Desktop is blank or times out while hermes still works, preserve the profile and open the Hermes dashboard troubleshooting guide. A working browser dashboard narrows the problem to Desktop or its connection layer. For a remote backend, remember that public /api/status can pass while authenticated /api/ws Chat fails; inspect 4401 authentication and 4403 Host/peer rejections before rebuilding or deleting state. Use FlyHermes when the desired outcome is managed browser/mobile access rather than maintaining this remote client path.
Desktop preview and real-profile browsing are different surfaces#
A Desktop preview/control session is not proof that Hermes selected the intended signed-in Chrome identity. For existing macOS login state, use the real-profile snapshot path, update for current Keychain handling, and test a harmless account page before side effects. The browser troubleshooting guide covers profile pinning, signed-out recovery, and the CLI-only /browser connect boundary.
Desktop becomes the Pantheon control surface#
v0.21 bundles Bot Mode, the unified MCP command center, an agent-controlled in-app browser, richer cron/Routines visibility, and safer macOS permission persistence. Use the Pantheon release guide as the current feature map, then this page for Desktop operation.
Desktop is the client; the dashboard is the control plane#
Current Hermes Desktop is the native, chat-first client and can register local, remote-gateway, SSH, and cloud connections. The Hermes Dashboard and Web UI is the browser control plane for the backend: configuration, sessions, logs, analytics, Kanban, cron, skills, MCP, and embedded TUI Chat. Use Desktop when multi-chat and multi-machine work is the job; use Web Dashboard for browser administration; use FlyHermes when you do not want to own either backend's uptime and security.
Desktop browser control still needs a transport smoke test#
A polished Desktop surface can hide whether the backend browser driver, profile copy, or CDP endpoint is healthy. After an update or browser restart, open a harmless public page and verify URL, H1, screenshot, and console output. Use the browser automation CDP and timeout guide when the UI waits without page progress.