website/docs/reference/faq.md
Quick answers and fixes for the most common questions and issues.
Hermes Agent works with any OpenAI-compatible API. Supported providers include:
hermes auth add anthropic, OpenRouter, or any compatible proxy)gemini provider, the google-gemini-cli OAuth provider, OpenRouter, or compatible proxy)Set your provider with hermes model or by editing ~/.hermes/.env. See the Environment Variables reference for all provider keys.
Yes, natively. Hermes supports native Windows via the PowerShell installer — no WSL required. Run in PowerShell:
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
The installer provisions a PortableGit that backs the terminal tool's shell. See the Windows (Native) Guide for details.
WSL2 remains a fully supported alternative. To run Hermes inside WSL2, install WSL2 and use the standard install command:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
Prefer an MCP bridge over /browser connect.
Recommended pattern:
chrome-devtools-mcp as an MCP server through cmd.exe or powershell.exeThis is more reliable than trying to force Hermes core browser transport to attach directly across the WSL2/Windows boundary.
See:
Yes — Hermes now has a tested Termux install path for Android phones.
Quick install:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
For the fully explicit manual steps, supported extras, and current limitations, see the Termux guide.
Important caveat: the full .[all] extra is not currently available on Android because the voice extra depends on faster-whisper → ctranslate2, and ctranslate2 does not publish Android wheels. Use the tested .[termux] extra instead.
API calls go only to the LLM provider you configure (e.g., OpenRouter, your local Ollama instance). Hermes Agent does not collect telemetry, usage data, or analytics. Your conversations, memory, and skills are stored locally in ~/.hermes/.
Yes. Run hermes model, select Custom endpoint, and enter your server's URL:
hermes model
# Select: Custom endpoint (enter URL manually)
# API base URL: http://localhost:11434/v1
# API key: ollama
# Model name: qwen3.5:27b
# Context length: 64000 ← Hermes minimum; set this to match your server's actual context window
Or configure it directly in config.yaml:
model:
default: qwen3.5:27b
provider: custom
base_url: http://localhost:11434/v1
Hermes persists the endpoint, provider, and base URL in config.yaml so it survives restarts. If your local server has exactly one model loaded, /model custom auto-detects it. You can also set provider: custom in config.yaml — it's a first-class provider, not an alias for anything else.
This works with Ollama, vLLM, llama.cpp server, SGLang, LocalAI, and others. See the Configuration guide for details.
:::tip Ollama users
If you set a custom num_ctx in Ollama (e.g., ollama run --num_ctx 64000), make sure to set the matching context length in Hermes — Ollama's /api/show reports the model's maximum context, not the effective num_ctx you configured.
:::
:::tip Timeouts with local models
Hermes auto-detects local endpoints and relaxes streaming timeouts (read timeout raised from 120s to 1800s, stale stream detection disabled). If you still hit timeouts on very large contexts, set HERMES_STREAM_READ_TIMEOUT=1800 in your .env. See the Local LLM guide for details.
:::
Hermes Agent itself is free and open-source (MIT license). You pay only for the LLM API usage from your chosen provider. Local models are completely free to run.
Yes. The messaging gateway lets multiple users interact with the same Hermes Agent instance via Telegram, Discord, Slack, WhatsApp, or Home Assistant. Access is controlled through allowlists (specific user IDs) and DM pairing (first user to message claims access).
Both persist across sessions. See Memory and Skills for details.
Yes. Import the AIAgent class and use Hermes programmatically:
from run_agent import AIAgent
agent = AIAgent(model="anthropic/claude-opus-4.7")
response = agent.chat("Explain quantum computing briefly")
See the Python Library guide for full API usage.
hermes: command not found after installationCause: Your shell hasn't reloaded the updated PATH.
Solution:
# Reload your shell profile
source ~/.bashrc # bash
source ~/.zshrc # zsh
# Or start a new terminal session
If it still doesn't work, verify the install location:
which hermes
ls ~/.local/bin/hermes
:::tip
The installer adds ~/.local/bin to your PATH. If you use a non-standard shell config, add export PATH="$HOME/.local/bin:$PATH" manually.
:::
Cause: Hermes requires Python 3.11 or newer.
Solution:
python3 --version # Check current version
# Install a newer Python
sudo apt install python3.12 # Ubuntu/Debian
brew install [email protected] # macOS
The installer handles this automatically — if you see this error during manual installation, upgrade Python first.
node: command not found (or nvm, pyenv, asdf, …)Cause: Hermes builds a per-session environment snapshot by running bash -l once at startup. A bash login shell reads /etc/profile, ~/.bash_profile, and ~/.profile, but does not source ~/.bashrc — so tools that install themselves there (nvm, asdf, pyenv, cargo, custom PATH exports) stay invisible to the snapshot. This most commonly happens when Hermes runs under systemd or in a minimal shell where nothing has pre-loaded the interactive shell profile.
Solution: Hermes auto-sources ~/.bashrc by default. If that's not enough — e.g. you're a zsh user whose PATH lives in ~/.zshrc, or you init nvm from a standalone file — list the extra files to source in ~/.hermes/config.yaml:
terminal:
shell_init_files:
- ~/.zshrc # zsh users: pulls zsh-managed PATH into the bash snapshot
- ~/.nvm/nvm.sh # direct nvm init (works regardless of shell)
- /etc/profile.d/cargo.sh # system-wide rc files
# When this list is set, the default ~/.bashrc auto-source is NOT added —
# include it explicitly if you want both:
# - ~/.bashrc
# - ~/.zshrc
Missing files are skipped silently. Sourcing happens in bash, so files that rely on zsh-only syntax may error — if that's a concern, source just the PATH-setting portion (e.g. nvm's nvm.sh directly) rather than the whole rc file.
To disable the auto-source behaviour (strict login-shell semantics only):
terminal:
auto_source_bashrc: false
uv: command not foundCause: The uv package manager isn't installed or not in PATH.
Solution:
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc
Cause: Insufficient permissions to write to the install directory.
Solution:
# Don't use sudo with the installer — it installs to ~/.local/bin
# If you previously installed with sudo, clean up:
sudo rm /usr/local/bin/hermes
# Then re-run the standard installer
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
/model only shows one provider / can't switch providersCause: /model (inside a chat session) can only switch between providers you've already configured. If you've only set up OpenRouter, that's all /model will show.
Solution: Exit your session and use hermes model from your terminal to add new providers:
# Exit the Hermes chat session first (Ctrl+C or /quit)
# Run the full provider setup wizard
hermes model
# This lets you: add providers, run OAuth, enter API keys, configure endpoints
After adding a new provider via hermes model, start a new chat session — /model will now show all your configured providers.
:::tip Quick reference
| Want to... | Use |
|---|---|
| Add a new provider | hermes model (from terminal) |
| Enter/change API keys | hermes model (from terminal) |
| Switch model mid-session | /model <name> (inside session) |
| Switch to different configured provider | /model provider:model (inside session) |
| ::: |
Cause: Key is missing, expired, incorrectly set, or for the wrong provider.
Solution:
# Check your configuration
hermes config show
# Re-configure your provider
hermes model
# Or set directly
hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx
:::warning
Make sure the key matches the provider. An OpenAI key won't work with OpenRouter and vice versa. Check ~/.hermes/.env for conflicting entries.
:::
Cause: The model identifier is incorrect or not available on your provider.
Solution:
# List available models for your provider
hermes model
# Set a valid model
hermes config set HERMES_MODEL anthropic/claude-opus-4.7
# Or specify per-session
hermes chat --model openrouter/meta-llama/llama-3.1-70b-instruct
Cause: You've exceeded your provider's rate limits.
Solution: Wait a moment and retry. For sustained usage, consider:
hermes chat --provider <alternative> to route to a different backendCause: The conversation has grown too long for the model's context window, or Hermes detected the wrong context length for your model.
Solution:
# Compress the current session
/compress
# Or start a fresh session
hermes chat
# Use a model with a larger context window
hermes chat --model openrouter/google/gemini-3-flash-preview
If this happens on the first long conversation, Hermes may have the wrong context length for your model. Check what it detected:
Look at the CLI startup line — it shows the detected context length (e.g., 📊 Context limit: 128000 tokens). You can also check with /usage during a session.
To fix context detection, set it explicitly:
# In ~/.hermes/config.yaml
model:
default: your-model-name
context_length: 131072 # your model's actual context window
Or for custom endpoints, add it per-model:
custom_providers:
- name: "My Server"
base_url: "http://localhost:11434/v1"
models:
qwen3.5:27b:
context_length: 64000
See Context Length Detection for how auto-detection works and all override options.
Cause: Hermes detected a potentially destructive command (e.g., rm -rf, DROP TABLE). This is a safety feature.
Solution: When prompted, review the command and type y to approve it. You can also:
:::tip This is working as intended — Hermes never silently runs destructive commands. The approval prompt shows you exactly what will execute. :::
sudo not working via messaging gatewayCause: The messaging gateway runs without an interactive terminal, so sudo cannot prompt for a password.
Solution:
sudo in messaging — ask the agent to find alternativessudo, configure passwordless sudo for specific commands in /etc/sudoershermes chatCause: Docker daemon isn't running or the user lacks permissions.
Solution:
# Check Docker is running
docker info
# Add your user to the docker group
sudo usermod -aG docker $USER
newgrp docker
# Verify
docker run hello-world
Cause: The bot isn't running, isn't authorized, or your user isn't in the allowlist.
Solution:
# Check if the gateway is running
hermes gateway status
# Start the gateway
hermes gateway start
# Check logs for errors
cat ~/.hermes/logs/gateway.log | tail -50
Cause: Network issues, bot token expired, or platform webhook misconfiguration.
Solution:
hermes gateway setupcat ~/.hermes/logs/gateway.log | tail -50Cause: Authorization mode determines who gets access.
Solution:
| Mode | How it works |
|---|---|
| Allowlist | Only user IDs listed in config can interact |
| DM pairing | First user to message in DM claims exclusive access |
| Open | Anyone can interact (not recommended for production) |
Configure in ~/.hermes/config.yaml under your gateway's settings. See the Messaging docs.
Cause: Missing dependencies, port conflicts, or misconfigured tokens.
Solution:
# Install core messaging gateway dependencies
pip install "hermes-agent[messaging]" # Telegram, Discord, Slack, and shared gateway deps
# Check for port conflicts
lsof -i :8080
# Verify configuration
hermes config show
hermes gateway start failsCause: WSL's systemd support is unreliable. Many WSL2 installations don't have systemd enabled, and even when enabled, services may not survive WSL restarts or Windows idle shutdowns.
Solution: Use foreground mode instead of the systemd service:
# Option 1: Direct foreground (simplest)
hermes gateway run
# Option 2: Persistent via tmux (survives terminal close)
tmux new -s hermes 'hermes gateway run'
# Reattach later: tmux attach -t hermes
# Option 3: Background via nohup
nohup hermes gateway run > ~/.hermes/logs/gateway.log 2>&1 &
If you want to try systemd anyway, make sure it's enabled:
/etc/wsl.conf (create it if it doesn't exist)[boot]
systemd=true
wsl --shutdownsystemctl is-system-running should say "running" or "degraded":::tip Auto-start on Windows boot For reliable auto-start, use Windows Task Scheduler to launch WSL + the gateway on login:
wsl -d Ubuntu -- bash -lc 'hermes gateway run'Cause: launchd services inherit a minimal PATH (/usr/bin:/bin:/usr/sbin:/sbin) that doesn't include Homebrew, nvm, cargo, or other user-installed tool directories. This commonly breaks the WhatsApp bridge (node not found) or voice transcription (ffmpeg not found).
Solution: The gateway captures your shell PATH when you run hermes gateway install. If you installed tools after setting up the gateway, re-run the install to capture the updated PATH:
hermes gateway install # Re-snapshots your current PATH
hermes gateway start # Detects the updated plist and reloads
You can verify the plist has the correct PATH:
/usr/libexec/PlistBuddy -c "Print :EnvironmentVariables:PATH" \
~/Library/LaunchAgents/ai.hermes.gateway.plist
Cause: Large model, distant API server, or heavy system prompt with many tools.
Solution:
hermes chat --model openrouter/meta-llama/llama-3.1-8b-instructhermes chat -t "terminal"Cause: Long conversations, verbose system prompts, or many tool calls accumulating context.
Solution:
# Compress the conversation to reduce tokens
/compress
# Check session token usage
/usage
:::tip
Use /compress regularly during long sessions. It summarizes the conversation history and reduces token usage significantly while preserving context.
:::
Cause: Extended conversations accumulate messages and tool outputs, approaching context limits.
Solution:
# Compress current session (preserves key context)
/compress
# Start a new session with a reference to the old one
hermes chat
# Resume a specific session later if needed
hermes chat --continue
Cause: Server binary not found, wrong command path, or missing runtime.
Solution:
# Ensure MCP dependencies are installed (already included in standard install)
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"
# For npm-based servers, ensure Node.js is available
node --version
npx --version
# Test the server manually
npx -y @modelcontextprotocol/server-filesystem /tmp
Verify your ~/.hermes/config.yaml MCP configuration:
mcp_servers:
filesystem:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]
Cause: Server started but tool discovery failed, tools were filtered out by config, or the server does not support the MCP capability you expected.
Solution:
tools/list RPC methodtools.include, tools.exclude, tools.resources, tools.prompts, or enabled settings under that server/reload-mcp after changing config# Verify MCP servers are configured
hermes config show | grep -A 12 mcp_servers
# Restart Hermes or reload MCP after config changes
hermes chat
See also:
Cause: The MCP server is taking too long to respond, or it crashed during execution.
Solution:
:::warning If an MCP server crashes mid-request, Hermes will report a timeout. Check the server's own logs (not just Hermes logs) to diagnose the root cause. :::
Profiles are a managed layer on top of HERMES_HOME. You could manually set HERMES_HOME=/some/path before every command, but profiles handle all the plumbing for you: creating the directory structure, generating shell aliases (hermes-work), tracking the active profile in ~/.hermes/active_profile, and syncing skill updates across all profiles automatically. They also integrate with tab completion so you don't have to remember paths.
No. Each messaging platform (Telegram, Discord, etc.) requires exclusive access to a bot token. If two profiles try to use the same token simultaneously, the second gateway will fail to connect. Create a separate bot per profile — for Telegram, talk to @BotFather to make additional bots.
No. Each profile has its own memory store, session database, and skills directory. They are completely isolated. If you want to start a new profile with existing memories and sessions, use hermes profile create newname --clone-all to copy everything from the current profile.
hermes update?hermes update pulls the latest code and reinstalls dependencies once (not per-profile). It then syncs updated skills to all profiles automatically. You only need to run hermes update once — it covers every profile on the machine.
There is no hard limit. Each profile is just a directory under ~/.hermes/profiles/. The practical limit depends on your disk space and how many concurrent gateways your system can handle (each gateway is a lightweight Python process). Running dozens of profiles is fine; each idle profile uses no resources.
Scenario: You use GPT-5.4 as your daily driver, but Gemini or Grok writes better social media content. Manually switching models every time is tedious.
Solution: Delegation config. Hermes can route subagents to a different model automatically. Set this in ~/.hermes/config.yaml:
delegation:
model: "google/gemini-3-flash-preview" # subagents use this model
provider: "openrouter" # provider for subagents
Now when you tell Hermes "write me a Twitter thread about X" and it spawns a delegate_task subagent, that subagent runs on Gemini instead of your main model. Your primary conversation stays on GPT-5.4.
You can also be explicit in your prompt: "Delegate a task to write social media posts about our product launch. Use your subagent for the actual writing." The agent will use delegate_task, which automatically picks up the delegation config.
For one-off model switches without delegation, use /model in the CLI:
/model google/gemini-3-flash-preview # switch for this session
# ... write your content ...
/model openai/gpt-5.4 # switch back
See Subagent Delegation for more on how delegation works.
Scenario: In OpenClaw, you had multiple independent agents bound to specific WhatsApp chats — one for a family shopping list group, another for your private chat. Can Hermes do this?
Current limitation: Hermes profiles each require their own WhatsApp number/session. You cannot bind multiple profiles to different chats on the same WhatsApp number — the WhatsApp bridge (Baileys) uses one authenticated session per number.
Workarounds:
Use a single profile with personality switching. Create different AGENTS.md context files or use the /personality command to change behavior per chat. The agent sees which chat it's in and can adapt.
Use cron jobs for specialized tasks. For a shopping list tracker, set up a cron job that monitors a specific chat and manages the list — no separate agent needed.
Use separate numbers. If you need truly independent agents, pair each profile with its own WhatsApp number. Virtual numbers from services like Google Voice work for this.
Use Telegram or Discord instead. These platforms support per-chat binding more naturally — each Telegram group or Discord channel gets its own session, and you can run multiple bot tokens (one per profile) on the same account.
See Profiles and WhatsApp setup for more details.
Scenario: You see gateway exec logs, Hermes reasoning, and tool call details in Telegram instead of just the final output.
Solution: The display.tool_progress setting in config.yaml controls how much tool activity is shown:
display:
tool_progress: "off" # options: off, new, all, verbose
off — Only the final response. No tool calls, no reasoning, no logs.new — Shows new tool calls as they happen (brief one-liners).all — Shows all tool activity including results.verbose — Full detail including tool arguments and outputs.For messaging platforms, off or new is usually what you want. After editing config.yaml, restart the gateway for changes to take effect.
You can also toggle this per-session with the /verbose command (if enabled):
display:
tool_progress_command: true # enables /verbose in the gateway
Scenario: Telegram has a 100 slash command limit, and your skills are pushing past it. You want to disable skills you don't need on Telegram, but hermes skills config settings don't seem to take effect.
Solution: Use hermes skills config to disable skills per-platform. This writes to config.yaml:
skills:
disabled: [] # globally disabled skills
platform_disabled:
telegram: [skill-a, skill-b] # disabled only on telegram
After changing this, restart the gateway (hermes gateway restart or kill and relaunch). The Telegram bot command menu rebuilds on startup.
:::tip Skills with very long descriptions are truncated to 40 characters in the Telegram menu to stay within payload size limits. If skills aren't appearing, it may be a total payload size issue rather than the 100 command count limit — disabling unused skills helps with both. :::
Scenario: You have a Telegram or Discord thread where multiple people mention the bot. You want all mentions in that thread to be part of one shared conversation, not separate per-user sessions.
Current behavior: Hermes creates sessions keyed by user ID on most platforms, so each person gets their own conversation context. This is by design for privacy and context isolation.
Workarounds:
Use Slack. Slack sessions are keyed by thread, not by user. Multiple users in the same thread share one conversation — exactly the behavior you're describing. This is the most natural fit.
Use a group chat with a single user. If one person is the designated "operator" who relays questions, the session stays unified. Others can read along.
Use a Discord channel. Discord sessions are keyed by channel, so all users in the same channel share context. Use a dedicated channel for the shared conversation.
Scenario: You've built up skills, cron jobs, and memories on one machine and want to move everything to a new dedicated Linux box.
Solution:
Install Hermes Agent on the new machine:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
On the source machine, create a full backup:
hermes backup
This creates a zip of your entire ~/.hermes/ directory — config, API keys, memories, skills, sessions, and profiles — saved to your home directory as ~/hermes-backup-<timestamp>.zip.
Copy the zip to the new machine and import it:
# On the source machine
scp ~/hermes-backup-<timestamp>.zip newmachine:~/
# On the new machine
hermes import ~/hermes-backup-<timestamp>.zip
On the new machine, run hermes setup to verify API keys and provider config are working.
Scenario: You want to move or share one specific profile — not your full installation.
# On the source machine
hermes profile export work ./work-backup.tar.gz
# Copy the file to the target machine, then:
hermes profile import ./work-backup.tar.gz work
The imported profile will have all config, memories, sessions, and skills from the export. You may need to update paths or re-authenticate with providers if the new machine has a different setup.
hermes backup vs hermes profile export| Feature | hermes backup | hermes profile export |
|---|---|---|
| Use Case | Full machine migration | Porting/sharing a specific profile |
| Scope | Global (entire ~/.hermes directory) | Local (single profile directory) |
| Includes | All profiles, global config, API keys, sessions | Single profile: SOUL.md, memories, sessions, skills |
| Credentials | Included (.env and auth.json) | Excluded (stripped for safe sharing) |
| Format | .zip | .tar.gz |
Manual fallback (rsync): If you prefer to copy files directly, exclude the code repo:
rsync -av --exclude='hermes-agent' ~/.hermes/ newmachine:~/.hermes/
:::tip
hermes backup produces a consistent snapshot even while Hermes is actively running. The restored archive excludes machine-local runtime files like gateway.pid and cron.pid.
:::
Scenario: After running the Hermes installer, source ~/.zshrc gives a permission denied error.
Cause: This usually happens when ~/.zshrc (or ~/.bashrc) has incorrect file permissions, or when the installer couldn't write to it cleanly. It's not a Hermes-specific issue — it's a shell config permissions problem.
Solution:
# Check permissions
ls -la ~/.zshrc
# Fix if needed (should be -rw-r--r-- or 644)
chmod 644 ~/.zshrc
# Then reload
source ~/.zshrc
# Or just open a new terminal window — it picks up PATH changes automatically
If the installer added the PATH line but permissions are wrong, you can add it manually:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
Scenario: Setup completes fine, but the first chat attempt fails with HTTP 400.
Cause: Usually a model name mismatch — the configured model doesn't exist on your provider, or the API key doesn't have access to it.
Solution:
# Check what model and provider are configured
hermes config show | head -20
# Re-run model selection
hermes model
# Or test with a known-good model
hermes chat -q "hello" --model anthropic/claude-opus-4.7
If using OpenRouter, make sure your API key has credits. A 400 from OpenRouter often means the model requires a paid plan or the model ID has a typo.
If your issue isn't covered here:
python3 --version), Hermes version (hermes --version), and the full error message