A Windows-native AI agent that lives on your desktop. Chat with it, give it tools, let it learn who you are. Built with WinUI 3 and .NET 10.
v2.4.0 — Download | Changelog | Discussion
Download and run — no installer, no SDK, no setup wizard.
- Grab
HermesDesktop-portable-x64.zipfrom Releases - Extract anywhere
- Run
HermesDesktop.exe - Add your API key to
%LOCALAPPDATA%\hermes\config.yaml
Works on Windows 10 (1809+) and Windows 11. The portable build is fully self-contained — everything ships in the folder.
Minimal config.yaml to get chatting
model:
provider: anthropic
default: claude-sonnet-4-6
base_url: https://api.anthropic.com
api_key: sk-ant-your-key-here
# Add more providers for runtime swapping (optional)
provider_keys:
anthropic: sk-ant-your-key
openai: sk-proj-your-key
ollama_url: http://127.0.0.1:11434/v1First launch creates %LOCALAPPDATA%\hermes with config, memory, transcripts, and logs.
Portable (zip from Releases) — your data lives outside the app folder.
- Quit Hermes Desktop (system tray → Exit, or close the window).
- Download the latest
HermesDesktop-portable-x64.zip. - Either replace the folder (delete the old extracted folder, extract the new zip to the same path) or extract to a new folder and run
HermesDesktop.exefrom there — either way, do not delete%LOCALAPPDATA%\hermes; yourconfig.yaml, sessions, memory, and wiki stay there. - Start the new
HermesDesktop.exe.
There is no in-app auto-updater yet; check Releases when you want a new build.
Built from git (dev / dotnet run) — pull and run again:
cd Hermes-Desktop
git pull
dotnet run --project Desktop/HermesDesktop/HermesDesktop.csproj -c Debug -p:Platform=x64 --launch-profile "HermesDesktop (Dev)"MSIX (run-dev.ps1) — pull, then re-register:
cd Hermes-Desktop
git pull
powershell -ExecutionPolicy Bypass -File .\Desktop\HermesDesktop\run-dev.ps1Hermes Desktop is an in-process agent runtime with a native Windows UI — not a chat wrapper. The agent runs locally, calls tools, remembers context across sessions, and can reach out to Telegram and Discord on your behalf.
 |
 |
 |
 |
 |
 |
 |
 |
- 27+ tools — file ops, shell, web fetch/search, code sandbox, browser automation, vision, TTS, and more
- Parallel execution for read-only tools (8-worker semaphore), sequential with permission gating for mutations
- Runtime model swapping — switch between Claude, GPT, Ollama, Qwen, DeepSeek, and others mid-conversation without restarting
- Sub-agent spawning with 5 profiles for delegation and parallel work
- 94 skills across 28 categories (code review, TDD, GitHub workflows, MLOps, research, creative, and more)
- Soul system — persistent personality (SOUL.md), user profile (USER.md), project rules (AGENTS.md), mistakes journal, habits journal
- 12 soul templates — Default, Creative, Teacher, Researcher, Pair Programmer, DevOps, Security, and more
- Wiki knowledge base — markdown files with SQLite FTS5 full-text search, Obsidian-compatible, crash-safe writes
- Compiled memory stack — wiki content injected into agent context automatically, configurable in
config.yaml - 6-layer context runtime — soul context, system prompt, session state, retrieved knowledge, recent turns, current message
Built from lessons across 168+ upstream PRs and 46+ production incidents:
- Compression cooldown (600s) to prevent infinite token-burning loops
- Provider fallback with automatic 5-minute restoration
- Credential pool rotation on 401/429
- Atomic writes (WriteThrough + FlushAsync) for crash safety
- Secret scanning on all tool outputs
- Deterministic tool-call IDs for prompt cache efficiency
Eight pages: Dashboard (usage insights, KPIs, platform badges), Chat (tool calling, reasoning display, model switcher, side panels), Agent (identity editor, souls browser), Skills (searchable library with categories), Memory (browser + project rules editor), Buddy (companion with ASCII art), Integrations (Telegram, Discord, and more), Settings (model, memory, display, execution, paths).
Native C# adapters for Telegram and Discord — no Python CLI required. Slack, WhatsApp, Matrix, and webhooks are configured in the same config.yaml from Integrations; use the optional Python gateway when you want those bots live (not required just to save tokens).
For contributors or anyone who wants to hack on the code.
Requirements: Windows 10+, .NET 10 SDK, Windows App SDK 1.7
git clone https://github.com/RedWoodOG/Hermes-Desktop.git
cd Hermes-Desktop
dotnet run --project Desktop/HermesDesktop/HermesDesktop.csproj -c Debug -p:Platform=x64 --launch-profile "HermesDesktop (Dev)"Runs unpackaged with no MSIX registration. The Dev profile enables HERMES_DESKTOP_SHOW_LOCAL_DETAILS so paths and endpoints are visible in the UI. In Visual Studio or Cursor, select the HermesDesktop (Dev) launch profile and press F5.
powershell -ExecutionPolicy Bypass -File .\Desktop\HermesDesktop\run-dev.ps1Builds, registers the MSIX package, and launches. Use -ShowLocalDetails to surface paths in the UI.
.\scripts\publish-portable.ps1 -ZipProduces Desktop\HermesDesktop\bin\HermesDesktop-portable-x64.zip — self-contained, ready to distribute. For ARM64: add -Platform ARM64.
Clean uninstall, manual build, troubleshooting
Updating from git is covered above under Updating (portable zip vs dotnet run vs run-dev.ps1).
Clean uninstall (MSIX):
Get-AppxPackage *EDC29F63* | Remove-AppxPackage
Remove-Item -Recurse -Force Desktop\HermesDesktop\bin, Desktop\HermesDesktop\obj, src\bin, src\obj -ErrorAction SilentlyContinueTo also remove user data: Remove-Item -Recurse -Force "$env:LOCALAPPDATA\hermes"
Manual build (if scripts don't work):
dotnet build Desktop/HermesDesktop/HermesDesktop.csproj -c Debug -p:Platform=x64
cd Desktop\HermesDesktop\bin\x64\Debug\net10.0-windows10.0.26100.0\win-x64
Add-AppxPackage -Register AppxManifest.xml
Start-Process "shell:AppsFolder\EDC29F63-281C-4D34-8723-155C8122DEA2_1z32rh13vfry6!App"Troubleshooting:
- App window doesn't appear? Remove old packages (
Get-AppxPackage *EDC29F63* | Remove-AppxPackage), cleanbin/andobj/, rebuild. - Check crash logs:
%LOCALAPPDATA%\hermes\hermes-cs\logs\desktop-startup.log - Check Windows crash reports:
C:\ProgramData\Microsoft\Windows\WER\ReportArchive - Close overlay software (MSI Afterburner, RTSS) — these can interfere with WinUI startup.
- Verify SDK:
dotnet --versionshould show10.x.x - Build errors on
BriefServiceorDashboardPage? See issue #25. - Use
-p:Platform=x64, notAMD64— seeDesktop/HermesDesktop/AGENTS.mdfor details.
MSIX signing: Local cert material (Desktop/HermesDesktop/packaging/dev-msix.pfx) must stay out of git. Generate a dev cert with scripts/new-msix-dev-cert.ps1.
Hermes.CS/
├── src/ # Core agent library (Hermes.Core)
│ ├── Core/ # Agent loop, models, tool interfaces
│ ├── Tools/ # 27+ tool implementations
│ ├── LLM/ # Provider abstraction, model swapping
│ ├── soul/ # Identity system, templates, profiles
│ ├── wiki/ # WikiManager, FTS5 search
│ ├── Context/ # Prompt builder, token budget
│ ├── dreamer/ # Background free-association worker
│ ├── gateway/ # Telegram, Discord adapters
│ └── ... # memory, skills, security, plugins, etc.
├── Desktop/HermesDesktop/ # WinUI 3 desktop application
│ ├── Views/ # 8 pages + side panels
│ ├── Services/ # Chat bridge, environment, diagnostics
│ └── Strings/ # Localization (en-us, zh-cn)
├── skills/ # 94 skill definitions
├── scripts/ # Build, publish, install scripts
└── HermesDesktop.slnx
.NET 10 / C# 13 • WinUI 3 (Windows App SDK 1.7, Mica backdrop) • SQLite FTS5 • Playwright • System.Text.Json
| Version | Date | Highlights |
|---|---|---|
| v2.4.0 | 2026-04-19 | Buddy: persist to buddy/buddy.json, species hatch UI, LLM-off fallback soul, aligned panel identity. Integrations: native Telegram/Discord adapter status fix, clearer optional-Python messaging. Tests: BuddyServiceTests. Assembly / MSIX manifest 2.4.0.0. |
| v2.3.1 | 2026-04-13 | Fix v2.3.0 source zip DreamerStatusSnapshot.LastLocalDigestHint compile error, fix portable startup XamlParseException on ReplayPanel (disable PublishTrimmed), add ReplayPanel constructor diagnostic capture, refresh readme screenshots |
| v2.3.0 | 2026-04-12 | Portable release (self-contained zip, no MSIX required), compiled memory stack, wiki tool, Dev launch profile, publish-portable.ps1 |
| v2.2.1 | 2026-04-10 | Fix startup crash on fresh clone, safe file ops, one-click installer |
| v2.2.0 | 2026-04-10 | User Profile section in Settings |
| v2.1.0 | 2026-04-10 | Native C# gateway — Telegram and Discord without Python CLI |
| v2.0.0 | 2026-04-09 | Runtime model swapping (Claude/OpenAI/Ollama/Qwen mid-conversation) |
| v1.9.0 | 2026-04-09 | Wiki knowledge base with SQLite FTS5 search |
| v1.8.0 | 2026-04-09 | Production hardening: cooldowns, fallback, atomic writes, secret scanning |
| v1.7.0 | 2026-04-09 | Anthropic tool calling |
| v1.5.0 | 2026-04-08 | Parallel tool execution (8 workers) |
Earlier releases
| Version | Date | Highlights |
|---|---|---|
| v2.1.1 | 2026-04-10 | Fix skills discovery, model dropdown, memory paths |
| v2.0.1 | 2026-04-09 | Fix dark theme, first-run skill copy, gateway notice |
| v1.9.1 | 2026-04-09 | Agent tool loop tests (207 pass), Chat UX |
| v1.6.0 | 2026-04-09 | Execution backends, plugins, analytics dashboard |
| v1.4.0 | 2026-04-08 | +7 new tools (21 total) |
| v1.3.0 | 2026-04-08 | Chat routes through full Agent pipeline |
| v1.2.0 | 2026-04-08 | Settings page overhaul |
| v1.1.0 | 2026-04-08 | Skills page redesign |
Built on the NousResearch Hermes Agent architecture. This project exists to show appreciation for the NousResearch team — please support them and use the product they created.
MIT