HermesDesktop Studio Documentation

HermesDesktop Studio is a community-maintained, open-source native desktop application for installing, configuring, and chatting with the Hermes Agent — a self-improving AI assistant with tool usage, multi-platform messaging, and closed-loop learning. The app replaces the manual CLI workflow for managing Hermes, guiding users through installation, provider setup, and daily use in a single unified interface.

At a Glance

Related Repositories

This guide takes you from nothing to a working HermesDesktop Studio installation with a model provider configured. Whether you're on Windows, macOS, or Linux, the process is the same — download, install, pick a provider, and start chatting.

1. Install the App

Option A — Download a Release

Grab the installer for your operating system from the download page or the GitHub releases:

Option B — Install via CLI

The hermesone npm package downloads the matching release, verifies its SHA-512 checksum, and installs it:

npm install -g hermesone
hermesone install        # download + verify + launch the installer
hermesone update         # later, to upgrade to the latest version

Option C — Windows PowerShell (One-Liner)

iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)

Option D — macOS/Linux Shell

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

2. First Run — Local or Remote Backend

On first launch, the app asks how you want to run the Hermes Agent backend:

3. Pick an LLM Provider

After the backend is ready, choose an LLM provider. The first-run picker offers:

• ▸ OpenRouter (recommended — 200+ models via one API key)
• ▸ Anthropic (Claude models)
• ▸ OpenAI (GPT models)
• ▸ Local LLM via any OpenAI-compatible base URL

Local presets are included for LM Studio, Atomic Chat, Ollama, vLLM, and llama.cpp — these need no API key, but the server must already be running. See Providers & Integrations for the full list.

Your provider choice and keys are saved through the Hermes config files (see Configuration). The app then opens the main workspace.

4. Start Chatting

The Chat screen is a streaming conversation UI with slash commands, tool progress indicators, markdown rendering, syntax highlighting, and live token/cost tracking in the footer. Type /help to see all available commands, or jump to the Features guide.

5. Add Capabilities

• 1Skills, MCP servers, agents, workflows — open the Discover tab to browse the community registry and install with one click.
• 2Messaging gateways — connect Telegram, Discord, Slack, and more from the Gateway screen.
• 3Scheduled tasks — build cron jobs with delivery targets from Schedules.

Where Your Data Lives

Everything is stored under ~/.hermes (or $HERMES_HOME):

~/.hermes/
├── .env                  # API keys (env secrets provider)
├── config.yaml           # provider + app configuration
├── hermes-agent/         # the Hermes Agent install (Python)
├── profiles/             # named profile directories
├── active_profile        # name of the active profile ("default" if absent)
├── state.db              # session history (SQLite, with FTS5 full-text search)
└── cron/jobs.json        # scheduled tasks

HermesDesktop Studio is an Electron application with the standard three-layer split — main, preload, and renderer — built and bundled by electron-vite. The renderer never touches Node or the filesystem directly; it calls a typed bridge that the preload exposes, and the main process does the privileged work (spawning the Hermes agent, reading ~/.hermes, talking to the API, running gateways).

┌─────────────────────────────────────────────────────────────────┐
│  Renderer (React)              src/renderer/src                   │
│    screens/ · components/ · hooks/       window.hermesAPI ──┐    │
└─────────────────────────────────────────────────────────────┼────┘
                        contextBridge (IPC)                     │
┌─────────────────────────────────────────────────────────────▼────┐
│  Preload    src/preload/index.ts   exposes window.hermesAPI       │
│             (+ window.electron); sandboxed, contextIsolated       │
└─────────────────────────────────────────────────────────────┬────┘
                        ipcRenderer ⇄ ipcMain                    │
┌─────────────────────────────────────────────────────────────▼────┐
│  Main Process   src/main/                                        │
│    app lifecycle · IPC registry · installer · hermes API client   │
│    · profiles · gateways · wallets · cron · secrets               │
└─────────────────────────────────────────────────────────────┬────┘
                        HTTP + SSE                                │
┌─────────────────────────────────────────────────────────────▼────┐
│  Hermes Agent   local 127.0.0.1:<port>   or   remote API server   │
└──────────────────────────────────────────────────────────────────┘

Processes

Main Process — src/main/

The entrypoint stays tiny and delegates startup. src/main/index.ts does only pre-ready work — applies GPU crash preferences, optionally enables the CDP testing port — then calls startMainProcess() in src/main/app/start.ts.

startMainProcess() owns the app lifecycle: crash logging, IPC handler registration, updater wiring, Electron ready/activate/window-all-closed/before-quit events, CSP headers, security hardening, and the main BrowserWindow.

App chrome lives in focused modules under src/main/app/:

• menu.ts — the application menu (incl. a Help-menu Developer Tools toggle)
• updater.ts — update IPC and electron-updater events
• context-menu.ts — the chat right-click menu

The rest of src/main/ is domain logic — a flat module per concern: installer.ts, hermes.ts (API client), config.ts, profiles.ts, sessions.ts, skills.ts, tools.ts, memory.ts, cronjobs.ts, messaging-platforms.ts, registry.ts (Discover), wallet-*.ts, run-stream.ts / sse-parser.ts (streaming), and the secrets/ provider.

Preload — src/preload/index.ts

Runs in an isolated world and exposes two globals via contextBridge: window.hermesAPI (the app's typed surface) and window.electron. The window is created with nodeIntegration: false, contextIsolation: true, and sandbox: true — so the renderer has no ambient Node access and everything goes through explicit IPC.

Renderer — src/renderer/src/

A React app: App.tsx + main.tsx, with screens/, components/, hooks/, utils/, and constants.ts. Each top-level screen maps to a nav destination — Welcome, Setup, Install, Chat, Sessions, Agents, Skills, Models, Memory, Soul, Tools, Schedules, Gateway, Office, Kanban, Discover, Providers, Settings, plus a Layout shell and a SplashScreen.

IPC Registry

Renderer↔main calls are isolated from bootstrap so the registry can be split by domain. registerIpcHandlers() in src/main/ipc/register.ts registers all handlers behind one function and receives app-level callbacks (the main window, model-library and connection-config notifications, external-URL opening, active chat abort handles). Examples: chat streaming, sessions, profiles, the wallet handlers (list-wallets, create-wallet, …, get-token-balances), and transcribe-audio for speech-to-text.

Talking to the Hermes Agent

src/main/hermes.ts is the HTTP/SSE client. In local mode it resolves a per-profile base URL (http://127.0.0.1:<port>, default 8642) and can manage the local gateway; in remote mode it targets your configured URL + key. Chat responses stream as Server-Sent Events, parsed in real time (run-stream.ts / sse-parser.ts) so the UI renders tool progress, markdown, and token usage as it arrives.

Speech-to-text is deliberately routed through the Hermes API server (/api/audio/transcribe), independent of the selected chat model, falling back to the Python transcription dispatcher when the desktop route is absent.

Startup Hardening & Resilience

Build & Packaging

electron-vite bundles the main file to out/main/index.js and the renderer to out/renderer/; packaged main resolves ../renderer/index.html from __dirname. electron-builder ( electron-builder.yml) produces the per-OS artifacts.

All Hermes state lives under a single Hermes home directory. The desktop app reads and writes it; the Hermes agent runs from it. You rarely need to edit these files by hand — the GUI manages them — but knowing the layout helps with backups, debugging, and advanced setups.

Hermes Home Directory

Resolution order:

1. HERMES_HOME environment variable, if set.
2. On Windows, %LOCALAPPDATA%\hermes (the installer's default).
3. Otherwise ~/.hermes.

~/.hermes/
├── .env                 # API keys (default "env" secrets provider)
├── config.yaml          # provider + app configuration
├── hermes-agent/        # the Hermes Agent install (Python)
├── profiles/            # named profile directories
│   └── <name>/          #   each with its own config.yaml, SOUL.md, state.db…
├── active_profile       # name of the active profile ("default" if absent)
├── state.db             # default profile's session history (SQLite, FTS5)
└── cron/jobs.json       # scheduled tasks

Profiles

A profile is an isolated Hermes environment — its own config, persona, sessions, and (optionally) gateways. The default profile is ~/.hermes itself; named profiles live under ~/.hermes/profiles/<name>. The active profile is recorded in ~/.hermes/active_profile.

Create, delete, and switch profiles from the Agents screen. Each profile gets its own local gateway port, so multiple profiles can run side by side. Installing a registry agent creates a new profile cloned from default with the agent's persona as its SOUL.md.

config.yaml

The agent's configuration: the selected provider and model, MCP servers (mcp_servers:), the secrets provider, network settings, and more. The desktop app edits this for you (provider setup, Discover installs, Settings). MCP entries installed from the registry are spliced under mcp_servers:.

Secrets Management

By default, API keys live in ~/.hermes/.env (the env provider) — no setup needed. Resolution order everywhere is: process.env → .env → provider → unset.

If you'd rather not keep keys in a plaintext .env, the opt-in command provider resolves them by running a helper you configure (POSIX-only; Linux/macOS — Windows stays on env):

secrets:
  provider: command
  command: secret-tool lookup hermes "$HERMES_SECRET_KEY"

The helper's stdout may be a single bare value (per-key) or KEY=VALUE dotenv lines (a dump) — both are auto-detected. The requested key name arrives as the HERMES_SECRET_KEY environment variable.

Vault Integrations

The command provider is vault-agnostic — anything that prints a value works:

Network: Local vs. Remote

• ▸ Local — the app manages the Hermes gateway on 127.0.0.1:<port> (default 8642, per-profile).
• ▸ Remote — point the app at a remote Hermes API server (URL + API key) from Settings; SSH tunneling options are also supported.

Backup, Import & Debug

From Settings you can take a full data backup, restore/import it, view gateway and agent logs, and produce a debug dump for diagnostics. Re-running is safe; backups capture your profiles, config, and session history.

HermesDesktop Studio packs a comprehensive suite of AI agent tools into a single desktop application. Every screen is designed to be both powerful for advanced users and approachable for beginners. Screens live in src/renderer/src/screens/.

Chat — Streaming AI Conversations

A streaming conversation UI with SSE streaming, tool-progress indicators, markdown rendering, and syntax highlighting. The footer shows live token usage and cost (prompt/completion counts). Long code blocks are collapsible, and a browser-style title bar holds open-conversation tabs.

Slash Commands

Typed slash commands are routed through the gateway's slash.exec / command.dispatch pipeline — they are executed as commands, not sent as prompt text. There are 22+ commands:

In-Chat Model Override

/model (or the model picker) switches the model — and its provider — for the current conversation only, without changing the global default. A per-model context-window override drives the context gauge and the agent's auto-compaction.

Context Folder

Each session can be linked to a working folder on disk. The link is persisted in a desktop-owned state.db table, so re-opening a conversation restores its folder.

Sessions — History with Full-Text Search

Browse, search, and resume past conversations. History is stored in SQLite with full-text search (FTS5) and grouped by date. The Chat nav item also shows a recent-sessions list (capped at five, with "Show more" opening the full list).

Agents (Profiles)

Create, delete, and switch between Hermes profiles — separate environments with isolated config, persona, and history. Each profile can have its own LLM provider, SOUL.md persona, skills, and gateway connections.

Skills

Browse, install, and manage skills — both bundled skills and ones installed from the registry. Registry skills are downloaded into <profile>/skills/<category>/<id>/.

Models

CRUD management for saved model configurations across providers — keep multiple model presets and switch between them instantly.

Memory — Cross-Session Learning

View and edit memory entries and the user-profile memory, with capacity tracking. The app can also configure discoverable memory providers:

Soul (Persona)

Edit and reset your agent's personality — the active profile's SOUL.md. Installing a registry agent writes its AGENT.md as the new profile's SOUL.md.

Tools — 14 Built-in Toolsets

Enable or disable individual toolsets:

Schedules — Cron-Based Automations

A cron-job builder — minutes, hourly, daily, weekly, or custom cron expressions — with 15 delivery targets for where results are sent. Jobs are stored in ~/.hermes/cron/jobs.json.

Gateway — 16 Messaging Platforms

Configure and control messaging-platform integrations so you can chat with your agent from anywhere. 16 gateways supported:

Office (Claw3d)

A visual 3D interface ("Hermes Office") with its own dev server and adapter management — for spatial AI agent interactions.

Kanban — Multi-Agent Task Board

A JIRA-style multi-agent board — a thin client over the hermes kanban CLI with canonical status columns, an archived toggle, and focus/poll refresh.

Discover — In-App Marketplace

The in-app marketplace for the community registry — browse and one-click install skills, MCP servers, agents, and workflows. See Registry & Marketplace.

Settings

Provider config, credential pools, backup/import, the log viewer (gateway + agent logs), network/remote settings, secrets provider, theme, and the auto-updater.

Wallets & Token Balances

Profile-scoped Base mainnet wallets with encrypted recovery phrases, and on-chain ERC-20 token balance reads (via ethers v6).

Analytics

Privacy-first, opt-out usage analytics: anonymous events POSTed to the in-house analytics service, keyed by a per-install UUID stored in localStorage. No third-party analytics SDK.

Internationalization

An i18n framework with a complete English locale across all screens, ready for community translations (src/shared/i18n/, src/renderer/src/components/I18nProvider.tsx).

HermesDesktop Studio sits in front of the Hermes Agent, so it supports every provider and integration the agent supports — and provides a GUI setup screen for each one.

LLM Providers

The first-run picker mirrors the agent's native canonical providers; any OpenAI-compatible endpoint is routed through the Local preset.

Local Model Presets

Built-in presets need no API key — but the corresponding server must already be running on your machine:

Select Local LLM, then choose a preset or provide a custom OpenAI-compatible base URL.

Messaging Platforms (Gateways)

Connect from the Gateway screen so you can chat with your agent from your existing chat apps. 16 platforms supported:

Tool Integrations

External services usable by the agent's toolsets:

Memory Providers

Discoverable memory backends configurable from the Memory screen:

Speech-to-Text

Voice transcription is routed through the Hermes API server (/api/audio/transcribe), independent of the selected chat model — so local Whisper, Groq, OpenAI, ElevenLabs, and command/plugin STT providers all work regardless of which chat model you're using.

Credential Storage

Provider API keys are stored through the Hermes secrets provider — by default in ~/.hermes/.env, or via the optional command/vault helper. Local providers need no key.

HermesDesktop Studio can install community extensions — skills, MCP servers, agents, and workflows — from the hermes-registry directory. The same install model has two front-ends: the in-app Discover tab and the hermesone add CLI.

The Catalog

The registry is a directory, not a package mirror. It's a public GitHub repository whose generated index.json lists each entry with its type, id, path, version, and compatibility. Skills/agents/workflows store their files directly in the repo; MCP entries are lightweight manifests pointing to pinned, published servers (npx/uvx/docker).

Discover (In-App)

The Discover screen renders the catalog as a gallery. For each entry, it:

1. Discovers — reads entries from index.json.
2. Checks compatibility — compares the running Hermes/desktop version with the entry's compatibility range (e.g. desktop: ">=0.6.0").
3. Collects config — for MCP, builds a form from the manifest's configSchema and requests required secrets (stored via the secrets provider, never committed).
4. Installs — into the active profile.

Install Model (Per Type)

hermesone add (CLI)

The hermesone CLI mirrors the same install model from the terminal, and also pings the registry website so the entry's public download counter increments:

hermesone add mcp/github
hermesone add skill/plan
hermesone add agent/code-reviewer
hermesone add workflow/pr-triage

• <type> ∈ skill | mcp | agent | workflow; <id> is the entry ID.
• --profile <name> targets a specific profile (default: active).
• HERMES_HOME and HERMESONE_REGISTRY can override the data directory and registry base URL.

Because it writes the same ~/.hermes location, entries added via CLI show up in the app and vice versa.

Models Catalog

The registry also publishes a models catalog (models.json) that the Models / provider screens can use to offer curated model lists per provider.

HermesDesktop Studio is open source under the MIT license. Contributions are welcome — whether it's a bug fix, a new feature, or improved documentation.

Prerequisites

• ▸ Node.js and npm
• ▸ A Unix-like shell environment for the Hermes installer (first-run local install)
• ▸ Network access for downloading Hermes during first-run install

Setup

npm install              # also runs electron-builder install-app-deps (postinstall)

Run

npm run dev              # electron-vite dev (hot reload)
npm run dev:fresh        # dev against a throwaway HERMES_HOME (mktemp) — clean state
npm run start            # electron-vite preview (run a built app)

Checks & Tests

npm run lint             # eslint (cached)
npm run typecheck        # node + web tsconfigs
npm run test             # vitest run
npm run test:watch       # vitest watch
npm run test:coverage    # coverage report

The test suite (Vitest) covers the SSE parser, IPC handlers, the preload API surface, installer utilities, config-health, SSH remote, wallet store/balances, and constants validation.

Build & Package

npm run build            # typecheck + electron-vite build → out/
npm run build:unpack     # unpacked dir build
npm run build:mac        # electron-builder --mac
npm run build:win        # electron-builder --win
npm run build:linux      # electron-builder --linux
npm run build:rpm        # Fedora/RHEL .rpm

Packaging config is in electron-builder.yml. electron-vite emits the bundled main to out/main/index.js and the renderer to out/renderer/.

Project Layout

src/
├── main/            # Electron main process (privileged)
│   ├── index.ts     #   pre-ready setup → app/start.ts
│   ├── app/         #   start.ts, menu.ts, updater.ts, context-menu.ts
│   ├── ipc/         #   register.ts — the IPC handler registry
│   ├── secrets/     #   env / command secrets providers
│   └── *.ts         #   one module per concern (installer, hermes, config,
│                    #   profiles, sessions, skills, tools, memory, cronjobs,
│                    #   messaging-platforms, registry, wallet-*, run-stream…)
├── preload/         # contextBridge → window.hermesAPI + window.electron
├── renderer/src/    # React UI: screens/, components/, hooks/, utils/
└── shared/          # code shared across processes (i18n, chat-stream,
                     #   attachments, tokens, wallets, registry types…)

The lat.md Knowledge Graph

This repo uses lat.md to maintain a cross-linked knowledge graph of architecture, design decisions, and test specs in lat.md/. It anchors source code to concepts via [[wiki links]] and // @lat: comments.

npm i -g lat.md
lat locate "Section Name"      # find a section
lat search "natural language"  # semantic search (needs an LLM key)
lat check                      # validate all links and code refs

Conventions

• ▸ TypeScript throughout; npm run typecheck must pass for both node and web tsconfigs.
• ▸ Keep the main entrypoint thin — boot concerns in index.ts, lifecycle in app/start.ts, IPC behind ipc/register.ts, domain logic in its own module.
• ▸ The renderer never imports Node or hits the filesystem directly — add a typed method to the preload bridge and an IPC handler instead.

Contributing

See CONTRIBUTING.md and the open issues. The project is in active development — features may change.