1 · "hermes: command not found" after install
Fix: reload your shell so it sees the new command:
source ~/.bashrc (or source ~/.zshrc on macOS)
Then try hermes again. If you just installed the desktop app, close and reopen it once. On Windows, reopen your chosen shell so it can see the updated PATH.
2 · "API key not set" error
Fix: connect a model through the configured provider:
hermes setup --portal
Complete the browser login fully. This sets a model and the Tool Gateway with no manual keys. If you brought your own provider, run hermes model or hermes config set OPENROUTER_API_KEY your_key.
3 · App installed but won't open
Fix: restart your computer once, then launch again. Installers sometimes need a clean shell to register the app. If it still won't open, reinstall from the official site — the installer is idempotent.
4 · Chat responds but can't use tools (search/browse fails)
Fix: the Tool Gateway may be off. Re-run hermes setup --portal (it turns on all four tools), or run hermes tools and enable the ones you need. A model without tool access will still chat but can't act.
5 · Settings vanished after an update
Fix: run hermes config check then hermes config migrate. Updates occasionally need a config refresh.
The Windows shell box (read this if you're on Windows)
You can install and launch Hermes from PowerShell, CMD, or Git Bash. Inside an agent session, Hermes's terminal tool uses a bash/MSYS command environment; that is separate from the shell you use to start Hermes.
Fix: launch Hermes from your preferred shell. Paste bash-style commands only into a bash environment; use PowerShell syntax when you are actually at a PowerShell prompt.
Verify the CLI is available by running hermes --version in the shell you intend to use.
The one command that diagnoses everything
If none of the above fits, run the built-in diagnostic:
hermes doctor
It reports the install method, what's missing, and what's misconfigured — paste its output into a Hermes chat (or our receptionist) and it'll tell you the exact fix. Most "mysterious" problems end here.
Still stuck? That's normal at first.
Everyone hits a wall on their first agent. If you'd rather learn it surrounded by people who've already cleared the traps, that's what the bootcamp is for — seven days in Pai applying the tools to a focused prototype.