Hermes Deck is a desktop app for Hermes Agent. It lets you chat with your Hermes agents, see what they are doing right now (thinking, tools, sub-agents), steer or stop them, and keep an eye on usage and subscription limits, all from one window on your Windows or macOS computer. It connects to the Hermes instance you already run, over SSH, WSL or locally, through a small Hermes plugin. An optional relay on the Hermes host adds a live view of every agent, host-wide usage, and letting agents use a browser or one window on your computer, both off until you allow them. Telegram is optional.
 Needs you: approvals and questions from every agent in one inbox |
 Bot Chat: every profile has its own chat and personality |
 Telegram mode: your account, your bots, your group topics |
 Desktop control: watch an agent work in one window, take control any time |
 Agent browsers: the agent's own browser tab, live on your device |
 Themes: dark, light and OLED themes, wallpapers, reading preferences |
| Feature | What it does | Needs relay? | Needs Telegram? |
|---|---|---|---|
| Sessions | Browse, search and continue every Hermes session from every profile and platform | No | No |
| Bots and Bot Chat | One chat per Hermes profile, with its face, state and routines | Routines only | No |
| Telegram mode | Your bot DMs and one forum group's topics, inside Deck | For live activity | Yes |
| Live activity | Thinking, current tool, sub-agents; queue, steer, interrupt, stop, take over | For the all-agents view | No |
| Attachments, voice and drafts | Files, window captures, voice notes, dictation transcribed by Hermes, per-chat drafts | No | No |
| Model and reasoning pickers | Change the model or reasoning effort for one session | No | No |
| Usage and quotas | Tokens, cost and cache use over 24h–All; Claude/Codex limits; gateway health | Yes | No |
| Notifications, pet, themes | OS notifications, taskbar badge, status pet, themes, English/Turkish | No | No |
| Agent browsers | Watch an agent's browser live, take control, hand it back | Yes | No |
| Desktop control | Let an agent use one window you hand over, with Stop always available | Yes | No |
| Agent spaces | Each agent on its own Linux desktop (or taking turns on a shared one); watch or join in, approve risky commands, undo changes | Yes | No |
Details of each feature, what it needs and where its settings are: docs/features.md.
Hermes + Deck plugin ←── SSH / WSL / local ──→ Deck app
│ events + state ↕
└────────→ optional relay ←─ token ────→ app
↕
optional Telegram
| Part | Runs on | Source |
|---|---|---|
| Hermes plugin | The Hermes host, inside each Hermes profile | hermes-plugin/hermes-deck |
| Relay (optional) | The Hermes host | relay, guide: docs/relay.md |
| Desktop app | Your Windows or macOS computer | app |
More: docs/architecture.md.
Hermes Deck ships a setup skill that your own Hermes agent can follow on its host. Give your agent this prompt:
Install Hermes Deck on this host from https://github.com/Hermes-Deck/hermes-deck. Use its skills/hermes-deck-setup skill. Ask me before changing any profile or starting services.
The skill checks your Hermes installation, shows the plugin installer's plan before applying it, optionally sets up the relay, and prints the values to enter in the app. It asks before every change and never restarts a busy gateway. Your agent can read it from a clone, or you can install it into Hermes first:
hermes skills install Hermes-Deck/hermes-deck/skills/hermes-deck-setupTo check a host at any time, run the read-only doctor from a clone with Hermes' Python:
<hermes-python> scripts/doctor.py (--json for agents, --home <hermes-home>, --relay http://<relay-host>:9330).
Details and the manual equivalent: docs/install-with-hermes.md.
Then install the desktop app (step 2 below) and complete its first-start setup (step 3).
1. Install the plugin on the Hermes host. From a clone of this repository, with Hermes' own Python (the interpreter of your Hermes installation):
cd hermes-plugin/hermes-deck
<hermes-python> install.py --dry-run # shows the plan, changes nothing
<hermes-python> install.pyThe installer backs up each changed config.yaml, enables hermes-deck in the selected profiles (--profile NAME,
default: all) and writes the direct-connection entry point to <Hermes home>/hermes-deck/stream.py (normally
~/.hermes/hermes-deck/stream.py). Restart each affected gateway only when its foreground and background work has
finished; a restart also ends background sub-agents. Options: plugin README.
2. Install the desktop app. Download from Releases:
| System | File |
|---|---|
| Windows x64 | Hermes-Deck-<version>-Setup.exe (recommended) or Hermes-Deck-<version>-win-x64.zip |
| macOS Apple Silicon | Hermes-Deck-<version>-mac-arm64.dmg |
| macOS Intel | Hermes-Deck-<version>-mac-x64.dmg |
Builds are not code-signed (macOS builds are ad-hoc signed, not notarized). Check the download against the release's
SHA256SUMS.txt first:
Get-FileHash .\Hermes-Deck-<version>-Setup.exe -Algorithm SHA256shasum -a 256 Hermes-Deck-<version>-mac-arm64.dmgOn Windows, Setup installs per user without admin rights and adds Start menu and Desktop shortcuts (Windows notifications need the Start menu shortcut). On macOS, drag the app to Applications. SmartScreen or Gatekeeper asks once; approve only a download you verified.
3. First-start setup. The app walks you through:
- Chat modes: Telegram, Sessions, Bots or a combination, and which one opens at start.
- Connect to Hermes: SSH (another machine), WSL (Windows) or Local (macOS/Linux); the SSH target, the Hermes
Python path and the
stream.pypath from step 1; Test connection. SSH uses your existing key login andknown_hosts; Deck never prompts for passwords. - Relay (optional): its address and token, or Set up later.
- What may run on this device?: Allow agent browsers and Allow desktop control, both off by default.
- Make it yours: status pet, notifications and language, then Finish setup.
With Telegram mode on, Telegram's API-key and phone login screens follow. Everything can be changed later in Settings (gear in the top bar, or Ctrl+, / Cmd+,).
4. Relay (optional). Run it on the Hermes host, bound to loopback or a private network address only, then enter
ws://<relay-host>:9330 and its token in Settings → Relay. Setup for Linux and macOS: docs/relay.md.
- Desktop app: Settings → General → Updates. On Windows, Deck downloads the new installer, checks it against
SHA256SUMS.txtand installs it. On macOS, install the new DMG from the release page. - Relay and plugin: update them on the Hermes host to the same version as the app. The app tells you when they are behind and shows the command. See docs/updating.md.
- Hermes Agent at or above the version in
compat.json(minHermes), on Linux, macOS or WSL. - Python 3.10+ with PyYAML for the plugin installer (Hermes' own Python has it).
- Node.js 22.13+ for the relay.
- Windows x64 or macOS (Apple Silicon or Intel) for the desktop app.
- For Telegram mode only: your own API keys from my.telegram.org.
- For agent desktops only: Docker (Docker Desktop, Docker Engine or colima) on the computer that hosts them.
App, relay and plugin share one version; run the same version of each. Full matrix and the version/protocol rules: docs/compatibility.md.
- The relay never goes on the internet. Bind it to loopback or a private network (Tailscale, WireGuard). Its token grants access to every agent's sessions and history.
- Device permissions start off. Agent browsers and desktop control run on a computer only after its owner turns them on locally; the relay cannot enable them, and desktop control is limited to one window you hand over.
- Tokens are stored encrypted. The relay token, Telegram session and device key are kept in the app's main
process with the OS keychain (Electron
safeStorage); the UI never receives them. - Builds are unsigned, so verify them. Each release publishes
SHA256SUMS.txtand a build provenance attestation for its files.
More: SECURITY.md (reporting vulnerabilities) and docs/security.md.
- Features, compatibility, updating
- Relay and device tools, host-wide usage, agent spaces
- Architecture, desktop-control protocol, security notes
- Development: running from source, tests, fixtures and builds
Contributions are welcome. Read CONTRIBUTING.md for setup, tests and the pull-request flow. Coding agents: see AGENTS.md. User-visible changes are listed in CHANGELOG.md.