Everything that can go wrong with Hermes Agent and Hermes Desktop — and exactly how to fix it. Work through each section in order. Start with Hermes Terminal if you use the CLI, or Hermes Desktop if you use the GUI app.
hermes doctor. It diagnoses most common issues automatically and may offer to fix them with hermes doctor --fix. Try that first.Everything that can break when you're running Hermes from the terminal.
Hermes isn't installed or isn't in your PATH. This is the most common first-time error.
Run: python -m hermes_agent --version or pip show hermes-agent. If one of these works, Hermes is installed but the shell shortcut isn't set up.
Run: python -c "import hermes_agent; print(hermes_agent.__file__)" — this shows the install location. The CLI script is usually in the same bin/ directory as Python.
Run: python -m site --user-base — this prints the user base path. Add /bin (Linux/Mac) or /Scripts (Windows) to your PATH.
Run: pip install --force-reinstall hermes-agent — this recreates all the command shortcuts.
Close and reopen your terminal, or run: exec $SHELL to reload the shell.
~/.bashrc or ~/.zshrc: export PATH="$(python -m site --user-base)/bin:$PATH" — then run source ~/.bashrc (or source ~/.zshrc).Hermes starts but immediately exits, or crashes with a Python traceback. This is usually a config problem.
hermes 2>&1 | head -50
Start Hermes with hermes -v to see exactly where it fails. The last few lines before the crash tell you the cause.
Run: hermes config edit — this opens the config. If it has YAML syntax errors (wrong indentation, missing colons), Hermes will fail to parse it. Try resetting: mv ~/.hermes/config.yaml ~/.hermes/config.yaml.bak then run hermes setup to recreate it.
Run: tail -50 ~/.hermes/logs/agent.log or tail -50 ~/.hermes/logs/errors.log — look for the most recent error.
Hermes requires Python 3.10 or higher. Run: python --version. If it's lower, download Python 3.11+.
Hermes won't do anything until you give it an API key. This is normal on first install.
# Option 1: Run the interactive setup wizard hermes setup # Option 2: Manually edit the .env file hermes config env-path # Opens the .env file — add your key there: OPENROUTER_API_KEY=sk-or-v1-your-actual-key
Go to openrouter.ai/keys.
Copy the key immediately — it won't be shown again.
Run: hermes config env-path — add the line OPENROUTER_API_KEY=sk-or-v1-... exactly as shown. Save and exit.
Exit Hermes with /quit and relaunch with hermes. The error should be gone.
Hermes can reach the API but the model name is wrong or the model isn't available on your provider.
Run: hermes model — this shows the current model. You can also run hermes config and look for the model.default line.
On OpenRouter, the model name format is like anthropic/claude-sonnet-4 or google/gemini-2.0-flash. Run hermes model and pick from the list — don't type it manually.
Even with the right model name, if you're out of credits the API returns an error. Log into openrouter.ai and check your credit balance.
Run hermes model and pick a different model — ideally one marked as "free" or "cheap" to test. If the new model works, the old one was unavailable.
meta-llama/llama-3-8b-instruct or anthropic/claude-3-haiku for testing.Hermes can't reach the AI provider's servers. This is a network issue on your side, the provider's side, or both.
# Test if you can reach OpenRouter curl -I https://openrouter.ai/api/v1/models 2>&1 | head -5 # Test with verbose output — look for the exact failure point curl -v https://openrouter.ai/api/v1/models 2>&1 | tail -20 # Test DNS resolution nslookup openrouter.ai
Try opening a website in your browser. If that works too, the issue is specific to HTTPS connections from the terminal.
If you're behind a corporate firewall, VPN, or proxy, Hermes can't reach external APIs. Try disabling your VPN temporarily. If that fixes it, add export HTTPS_PROXY=http://your-proxy:port to your ~/.hermes/.env.
Go to status.openrouter.ai — if there's an incident, wait for it to resolve.
If OpenRouter is blocked or slow, run hermes model and try Anthropic directly, DeepSeek, or any other configured provider.
Hermes starts but can't use tools like terminal, browser, file editing, etc.
# Check which toolsets are enabled hermes tools list # Enable a toolset (e.g., terminal, web, file) hermes tools enable terminal hermes tools enable web hermes tools enable file
/reset or /quit and relaunch. Tools don't change mid-conversation.# Terminal tool: check if your shell works echo $SHELL which bash # Browser tool: check for Chrome/Chromium which google-chrome chromium-browser chromium 2>/dev/null # File tools: check .hermes directory permissions ls -la ~/.hermes/
Hermes loses track of conversation, loops on the same response, or forgets everything between messages.
Type /new or /reset in the current session — this clears the conversation history and starts clean. If Hermes is looping, this breaks the loop.
Run: hermes sessions stats — this shows how many sessions you have and storage used. If it's very large, run hermes sessions prune --older-than 30 to clean up old sessions.
Run: hermes memory status — if memory is off, Hermes won't remember things between sessions. Enable it with hermes memory setup.
Type /compress in session — this forces context compression and can break loops without losing full session history.
Hermes tries to run a shell command or access a file but gets a permission error.
Run: ls -la /path/to/problematic/file — if it shows drwx------ or -rw-------, only the owner can access it.
Run: chmod 700 ~/.hermes and chmod 600 ~/.hermes/config.yaml ~/.hermes/.env — this fixes most permission issues while keeping your secrets secure.
If you ran Hermes as root (sudo), files it created may be owned by root. Fix with: sudo chown -R $USER:$USER ~/.hermes
600 for secrets files and 700 for directories.Everything that can break when you're running the Hermes Desktop application.
You double-click the AppImage but nothing happens. No window, no error — just silence.
Right-click the file → Properties → Permissions → check "Allow executing as program". Or from terminal: chmod +x ~/Downloads/hermes-desktop-*.AppImage
Open terminal, navigate to where the AppImage is, and run: ./hermes-desktop-*.AppImage 2>&1 — this shows the actual error instead of hiding it.
AppImage needs FUSE to run. Run: which fusermount3. If it's missing: sudo apt install fuse libfuse2 (Debian/Ubuntu) or sudo dnf install fuse fuse-libs (Fedora).
Run: ./hermes-desktop-*.AppImage --appimage-extract — this extracts the contents. Then run: ./squashfs-root/AppRun from the extracted folder.
Hermes Desktop opens but shows a blank screen, a window too small to use, or opens off-screen where you can't reach it.
Run: hermes-desktop --reset-window (if supported) or delete the window state file: rm -f ~/.config/hermes-desktop/window-state.json
Try running with software rendering: hermes-desktop --disable-gpu or WEBKIT_DISABLE_COMPOSITING_MODE=1 ./hermes-desktop.AppImage
Try: xrandr (Linux) to see your displays. If using multiple monitors, try disconnecting external monitors to force the primary display.
Hermes Desktop is built on either Electron or Qt. Make sure your system has the latest version: sudo apt update && sudo apt upgrade (Debian/Ubuntu).
The same API key works fine in Hermes CLI but Hermes Desktop keeps saying the key is invalid or won't connect.
Both read from ~/.hermes/config.yaml and ~/.hermes/.env. If the CLI works, the Desktop app should pick up the same keys. Make sure both are using the same HERMES_HOME.
Run Hermes Desktop with HERMES_HOME=~/.hermes ./hermes-desktop.AppImage to force it to the same location as the CLI.
Go to Settings → API Keys in the Hermes Desktop interface and re-enter your OpenRouter key — sometimes the GUI key store doesn't sync properly on first launch.
Run from terminal: hermes-desktop 2>&1 | tee desktop.log — look for API-related errors in the output.
The app starts, shows the window, then crashes or freezes completely.
Run: free -h (memory) and df -h (disk space). Hermes Desktop needs at least 2GB free RAM and 500MB free disk. If either is too low, it will crash.
Run: ./hermes-desktop.AppImage 2>&1 — if it crashes, the terminal will show a stack trace. Note the last few lines before the crash.
Download the latest release from github.com/fathah/hermes-desktop/releases — older versions have bugs that were fixed later.
Run: rm -rf ~/.config/hermes-desktop/ — this removes cached data, window state, and local settings. Restarting fresh often fixes crashes caused by corrupted local state.
Hermes Desktop tries to start a local server but another process is using the same port.
# Find what's using the Hermes Desktop port (usually 8080 or 3000) lsof -i :8080 # or ss -tlnp | grep 8080 # Kill the process using that port kill -9 <PID> # Or if it's another Hermes instance running pkill -f hermes-desktop
Hermes Desktop doesn't auto-update. You have to manually install new versions.
Open Hermes Desktop → Settings → About. Note the version number.
Download the new .AppImage file and replace your old one. Your config files (~/.hermes/) are separate and won't be touched.
After replacing: chmod +x ~/Downloads/hermes-desktop-new.AppImage
Remove Hermes Desktop and optionally all user data.
# Step 1: Kill any running Hermes Desktop process pkill -f hermes-desktop # Step 2: Delete the AppImage file rm /path/to/hermes-desktop.AppImage # Step 3: Delete Hermes Desktop config (optional — keeps your CLI data) rm -rf ~/.config/hermes-desktop/ # Step 4: Delete ALL Hermes data (including CLI, personas, skills, sessions) rm -rf ~/.hermes/ # Step 5: Uninstall the Hermes CLI pip package pip uninstall hermes-agent
API keys, provider issues, proxy configuration, and connectivity problems.
The API key you provided is being rejected by the provider.
# Test your OpenRouter key directly via curl curl https://openrouter.ai/api/v1/models \ -H "Authorization: Bearer sk-or-v1-YOUR-KEY-HERE" \ 2>&1 | head -20 # If it returns a JSON list of models — key is valid # If it returns {"error": ...} — key is invalid or expired
Run: cat ~/.hermes/.env — the key should look exactly like OPENROUTER_API_KEY=sk-or-v1-... with no spaces around the = and no trailing whitespace.
An OpenAI key won't work with OpenRouter. An Anthropic key won't work with DeepSeek. Each provider has its own key format. Make sure the key matches the provider configured in hermes config.
Delete the old key from the provider's dashboard and create a new one. Paste it carefully into ~/.hermes/.env.
Hermes works fine at home but fails to connect when you're on a restricted network.
# Tell Hermes to use your corporate proxy HTTPS_PROXY=http://proxy.company.com:8080 HTTP_PROXY=http://proxy.company.com:8080 NO_PROXY=localhost,127.0.0.1,.local
Add these to your ~/.hermes/.env file. Ask your IT department for the proxy address and port.
http://user:password@proxy.company.com:8080Your provider is throttling you because you're making too many requests too quickly.
Rate limits reset after a cooldown period — usually 60 seconds. Wait a minute and try again.
If you're running automated tasks, add delays between requests. Check hermes insights to see your request rate.
Free tiers have strict rate limits. Paid plans on OpenRouter have higher limits. Go to your provider's billing page to upgrade.
Run: hermes auth add to add multiple API keys. Hermes rotates through them automatically when one hits its rate limit.
Your system's CA certificates are outdated or missing, so HTTPS connections fail.
sudo apt update && sudo apt install ca-certificates sudo update-ca-certificates
/Applications/Python\ 3.*/Install\ Certificates.command # Or update certifi: pip install --upgrade certifi
SOUL.md, persona switching, skill loading, and configuration problems.
You updated your agent's identity file but it still acts the same way.
Changes to ~/.hermes/SOUL.md only take effect when Hermes starts a new session. Exit with /quit and restart with hermes. A /reset inside the session won't re-read SOUL.md — it only resets conversation history.
Run: cat ~/.hermes/SOUL.md — make sure the file has your changes and isn't empty or corrupted.
If you're using a profile (hermes -p myprofile), each profile has its own ~/.hermes/profiles/myprofile/SOUL.md. Make sure you're editing the right one.
You installed a skill but Hermes doesn't recognize it or can't use it.
# List all installed skills hermes skills list # Load a specific skill into the current session /skill my-skill-name # Or from the CLI: hermes -s my-skill-name # Check which skills are enabled for your platform hermes skills config
hermes session. Skills are loaded at session start, not mid-conversation.Run: ls ~/.hermes/skills/ — skills must be in a subfolder with a SKILL.md file inside.
Run: hermes skills inspect my-skill — this validates the skill and shows any frontmatter errors.
Type /reload-skills in session — this rescans the skills directory for new or removed skills without requiring a full restart.
You edited config.yaml and now Hermes crashes on startup.
Run: mv ~/.hermes/config.yaml ~/.hermes/config.yaml.broken — then run hermes setup to recreate a fresh config with defaults. Your .env file (API keys) is separate and won't be touched.
Run: python -c "import yaml; yaml.safe_load(open('~/.hermes/config.yaml'))" — if Python shows an error, the YAML has a syntax problem (missing colon, wrong indentation, unquoted special characters).
Make sure indentation uses spaces (not tabs). Make sure colons have a space after them: model: anthropic/claude-sonnet-4 not model:anthropic/claude-sonnet-4. If a value contains special characters like # or :, wrap it in quotes.
The best way to switch from one agent persona to another without contamination.
# Step 1: Exit the current Hermes session completely /quit # Step 2: Back up the current SOUL cp ~/.hermes/SOUL.md ~/.hermes/personas/current-SOUL.md.bak # Step 3: Copy the new persona SOUL into place cp ~/.hermes/personas/my-new-persona.md ~/.hermes/SOUL.md # Step 4: Verify the correct SOUL is in place head -3 ~/.hermes/SOUL.md # Step 5: Start a fresh Hermes session hermes
/quit (not just /reset) when switching personas. A reset only clears conversation history — the old persona's context can still bleed through. A full quit ensures a completely fresh session with the new SOUL.When nothing else works — full reset procedures that get Hermes back to a working state.
Use this when you've tried everything and Hermes is fundamentally broken. This wipes everything and starts fresh. Your API keys will need to be re-entered.
Type /quit in any active session. Run pkill -f hermes to make sure no Hermes processes are running.
Copy anything you want to keep: cp -r ~/.hermes ~/.hermes.backup-$(date +%Y%m%d) — this lets you restore personas, skills, and sessions if needed.
rm ~/.hermes/config.yaml — this removes all settings. Your API keys in .env are separate and safe.
hermes setup — this asks you to choose a model, provider, and configure basics. It creates a fresh config.yaml.
hermes — you now have a clean, working installation. Re-install any skills you need.
The hermes doctor command checks your installation, config, and environment for common problems and can auto-fix many of them.
# Check for problems (read-only) hermes doctor # Check AND attempt auto-fix hermes doctor --fix # Show detailed output hermes doctor -v
It checks: Python version, pip packages, config file validity, API key presence, provider connectivity, tool availability, and directory permissions.
If a session file got corrupted and you can't resume it.
# List all sessions hermes sessions list # Try to export the session even if it's damaged hermes sessions export /tmp/rescue.jsonl --session SESSION_ID # Resume a different recent session hermes --continue # Delete the broken session hermes sessions delete SESSION_ID
The messaging gateway (for Telegram, Discord, etc.) won't stay running.
# Check why it's crashing hermes gateway run 2>&1 | head -30 # Reset failed systemd state (Linux) systemctl --user reset-failed hermes-gateway # Reinstall the gateway service hermes gateway install # Check gateway logs tail -30 ~/.hermes/logs/gateway.log
[boot] systemd=true to /etc/wsl.conf and restart WSL. Without systemd, gateway falls back to nohup mode and dies on session close.Wipe everything including Hermes CLI and start completely over.
# 1. Uninstall the pip package pip uninstall hermes-agent -y # 2. Delete all Hermes data rm -rf ~/.hermes/ # 3. Reinstall fresh pip install hermes-agent # 4. Run the setup wizard hermes setup # 5. Start hermes
When Hermes is running wild — executing commands you didn't approve, stuck in a loop, or acting dangerously.
If Hermes is running commands you didn't authorize, executing dangerous operations, or in any kind of dangerous loop — stop it NOW.
# Stop the current Hermes CLI session (inside session) /stop # Force kill all Hermes processes immediately pkill -9 -f hermes # Kill Hermes Desktop specifically pkill -9 -f hermes-desktop # Kill the gateway (messaging platforms) hermes gateway stop pkill -9 -f hermes-gateway
rm -rf or git reset --hard), stop it first, then immediately check what damage was done. Run ls -la in directories where files might be missing. For git operations, check git status and git reflog to recover.Configure Hermes to always ask before running destructive commands.
# Make Hermes ask before EVERY shell command hermes config set approvals.mode manual # Auto-approve safe commands, prompt on dangerous ones (recommended) hermes config set approvals.mode smart # Bypass all prompts (dangerous — only use in emergencies) hermes config set approvals.mode off # Or use --yolo flag when starting: hermes --yolo
rm -rf, git reset --hard, and mkfs. The approval system catches these even if approvals.modeoff — but only for commands Hermes explicitly recognizes. Use manual or smart mode for maximum safety.If Hermes made unwanted changes to your files and you need to undo them.
# Check git status to see what changed git status # See the recent git reflog git reflog | head -20 # Restore a file to how it was 3 commits ago git checkout HEAD~3 -- path/to/file # Restore entire repo to 2 commits ago git reset --hard HEAD~2
# Rollback using Hermes checkpoints /rollback 1 # List available snapshots /snapshot list
Extreme case — Hermes or its subprocesses won't die.
# Find ALL Hermes-related processes ps aux | grep -i hermes # Kill by process ID (replace PID with the number) kill -9 PID # If it's a subprocess, find the parent and kill it pstree -p | grep hermes kill -9 PARENT_PID # Last resort: reboot the machine sudo reboot