Hermes Agent — User Guide

1. Quick Start

Hermes Agent is an open-source AI-powered CLI assistant and multi-platform agent by Nous Research. It provides an interactive terminal interface with tool-calling capabilities spanning terminal execution, web browsing, file management, vision, image generation, and text-to-speech. With a composable skills system, pluggable memory providers, a gateway connecting 19+ messaging platforms, scheduled tasks, and support for 30+ LLM providers, Hermes Agent turns your terminal into a fully autonomous AI workspace.

Key Features

• Interactive CLI REPL — rich TUI with streaming responses, status bar, slash commands, and voice mode
• Multi-platform gateway — connect Hermes to Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost, Email, SMS, and more
• 30+ LLM providers — OpenRouter, Anthropic, OpenAI, Ollama, Nous Portal, AWS Bedrock, Google Gemini, Groq, and others
• Composable toolsets — terminal, web, browser, file, vision, image generation, TTS, code execution, and delegation
• Skills system — 100+ bundled skills for creative work, productivity, research, MLOps, GitHub workflows, and software development
• Pluggable memory — Honcho, Hindsight, Holographic, Mem0, and other providers for persistent conversation context
• Cron scheduling — schedule recurring tasks with flexible delivery to any connected platform
• Web dashboard — browser-based management for config, sessions, cron jobs, skills, and plugins

Prerequisites

Install and Run

pip install hermes-agent

Start an interactive session:

hermes

Ask a single question:

hermes -q "What is the capital of France?"

Tip

Run hermes setup after installation to walk through provider configuration, model selection, and gateway setup in an interactive wizard.

What to Try Next

• Section 2: Installation — all install methods and extras
• Section 3: Configuration — set up models, providers, and profiles
• Section 4: Core Usage — interactive chat, toolsets, skills, gateway, and more
• Section 5: Common Tasks — step-by-step recipes for real-world scenarios

2. Installation

System Requirements

Install Methods

pip (recommended)

Install the base package:

pip install hermes-agent

Install with all extras:

pip install "hermes-agent[all]"

From Source

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
pip install -e ".[all]"

Homebrew

A Homebrew formula is available in the packaging/homebrew/ directory:

brew install hermes-agent

Docker

Build from the included Dockerfile:

cd docker
docker build -t hermes-agent .
docker run -it hermes-agent

Nix

A flake.nix is included for Nix users:

nix develop

Important

On Windows, Hermes Agent requires Git for Windows (Git Bash). If Git Bash is not found at the default location, set the HERMES_GIT_BASH_PATH environment variable to your bash.exe path.

Install Extras

Install only the features you need with optional extras:

Example:

pip install "hermes-agent[web,voice]"

Post-Install Setup

Run the interactive setup wizard:

hermes setup

Welcome to Hermes Agent Setup!
Select your inference provider:
  1. Nous Portal (free tier available)
  2. OpenRouter
  3. Anthropic
  4. OpenAI
  5. Ollama (local)
  ...

Verify your installation:

hermes doctor

Hermes Agent v0.9.0
  Python .......... 3.11.9 ✓
  Node.js ......... v20.18.0 ✓
  Git ............. 2.45.0 ✓
  Docker .......... 27.0.3 ✓
  Provider ........ openrouter ✓
  API Key ......... set ✓
  Gateway ......... not running
  Memory .......... holographic ✓

Check your version:

hermes --version

0.9.0

Install Troubleshooting

pip install hermes-agent fails with dependency conflicts Cause: Conflicting packages in your Python environment. Solution: Use a virtual environment:

python -m venv ~/.hermes-venv
source ~/.hermes-venv/bin/activate
pip install hermes-agent

Git Bash not found. Hermes Agent requires Git for Windows on Windows. Cause: Git for Windows is not installed or not in the default path. Solution: Install Git for Windows from https://git-scm.com/download/win, or set HERMES_GIT_BASH_PATH to your bash.exe location.

Voice mode requires sounddevice and numpy. Cause: Voice dependencies not installed. Solution: pip install "hermes-agent[voice]" or pip install sounddevice numpy.

MCP server requires the 'mcp' package. Cause: MCP extra not installed. Solution: pip install "hermes-agent[mcp]".

The 'anthropic' package is required for the Anthropic provider. Cause: Anthropic SDK not installed. Solution: pip install "anthropic>=0.39.0".

The 'boto3' package is required for the AWS Bedrock provider. Cause: AWS dependencies not installed. Solution: pip install "hermes-agent[bedrock]" or pip install boto3.

3. Configuration

Config File Location

All configuration lives under ~/.hermes/:

~/.hermes/
  config.yaml       Main configuration
  .env              API keys and secrets
  SOUL.md           System prompt customization
  state.db          Session database (SQLite)
  skills/           Installed skills
  plugins/          Installed plugins
  logs/             Log files

On Termux (Android), the default home is $PREFIX/etc/hermes/.

Override the home directory with the HERMES_HOME environment variable.

Setting a Model and Provider

The quickest way to configure your LLM provider:

hermes model

This opens an interactive menu to select your provider and model. You can also set it directly:

hermes config set model anthropic/claude-sonnet-4

Environment Variables

API keys and secrets go in ~/.hermes/.env:

# Provider keys
OPENROUTER_API_KEY=sk-or-...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Gateway platform tokens
TELEGRAM_BOT_TOKEN=123456:ABC-...
DISCORD_BOT_TOKEN=MTIz...

# Optional
FIRECRAWL_API_KEY=fc-...
HONCHO_API_KEY=...

Warning

Never expose your ~/.hermes/.env file. It contains sensitive API keys. The web dashboard binds to 127.0.0.1 by default to prevent network exposure.

Key Configuration Options

Set individual values with hermes config set:

hermes config set model openrouter/anthropic/claude-sonnet-4
hermes config set terminal.backend local
hermes config set agent.max_turns 90
hermes config set security.redact_secrets true

Annotated Minimal Config

# ~/.hermes/config.yaml

# Primary model for conversations
model: openrouter/anthropic/claude-sonnet-4

# Terminal backend: local, docker, ssh, singularity, modal
terminal:
  backend: local

# Enabled toolsets (customize per your needs)
toolsets:
  - terminal
  - web
  - file

# Memory provider (optional)
memory:
  provider: holographic

# Agent behavior
agent:
  max_turns: 90

SOUL.md Customization

Create ~/.hermes/SOUL.md to customize Hermes's personality and system prompt. This file is injected into the system prompt for every session:

# My Custom Assistant

You are a senior Python developer who prefers concise explanations
and always suggests test-driven approaches. You speak in a professional
but friendly tone.

Profiles

Profiles let you maintain separate configurations for different contexts (work, personal, different models):

# Create a new profile
hermes profile create work

# Clone settings from your current profile
hermes profile create work --clone

# Switch to a profile
hermes profile use work

# List all profiles
hermes profile list

# Export a profile for backup or sharing
hermes profile export work -o work-profile.tar.gz

# Import a profile
hermes profile import work-profile.tar.gz --name work-restored

Each profile gets its own config.yaml, .env, SOUL.md, session database, and skill/plugin directories.

Tip

Create a shell alias for a profile: hermes profile alias work --name h-work. Then start that profile with just h-work from your terminal.

See the Admin Guide for full configuration reference, including all available config keys, advanced terminal backends, and proxy settings.

4. Core Usage

Interactive Chat

Launch the interactive REPL:

hermes

The TUI displays a status bar showing the active model, token usage, and session info. Responses stream in real-time. Type your message and press Enter to send.

Slash Commands

Inside the interactive session, use slash commands to control behavior:

Voice Mode

Enable voice input during a session:

/voice on

Or press Ctrl+B to record audio. Voice mode requires an STT (speech-to-text) provider:

• Local (free): pip install faster-whisper
• Groq (free tier): Set GROQ_API_KEY in ~/.hermes/.env
• OpenAI (paid): Set VOICE_TOOLS_OPENAI_KEY in ~/.hermes/.env

On Termux (Android), install termux-api and the Termux:API Android app for microphone access.

File and Image Attachment

Reference files or images by path in your messages. For images, the vision toolset processes them with a vision-capable model.

Session Management

Resume a previous session by ID:

hermes -r <session_id>

Resume by name, or the most recent session:

hermes -c           # Resume most recent
hermes -c my-project  # Resume by name

Browse previous sessions interactively:

hermes sessions browse

Git Worktree Isolation

Run Hermes in an isolated git worktree for parallel agent work on the same repository:

hermes -w

This creates a temporary worktree so the agent can make changes without affecting your working directory.

Single Query Mode

Run a single query without entering interactive mode:

hermes -q "Explain the difference between TCP and UDP"

Combine with model and toolset flags:

hermes -q "Summarize this page" --model openai/gpt-4o --toolsets web

Attach an image:

hermes -q "Describe this image" --image screenshot.png

Quiet mode for scripting — suppresses banners, spinners, and tool previews:

hermes -Q -q "What is 2+2?"

4

Toolsets

Toolsets are groups of related tools that Hermes can use. Enable or disable them to control what the agent can do.

Manage toolsets from the CLI:

# Enable a toolset
hermes tools enable browser

# Disable a toolset
hermes tools disable image_gen

# Show all toolsets and their status
hermes tools list

# Show toolsets for a specific platform
hermes tools list --platform telegram

Override toolsets for a single session:

hermes --toolsets web,terminal,browser

Note

Browser tools require Node.js 20+ and the browser dependencies installed via npm install in the repo root. Cloud browser providers (Browserbase, Firecrawl, Browser Use) are available as alternatives.

Skills

Skills are markdown-based instructions that teach Hermes specialized tasks. They are loaded into the system prompt and can include tool configurations, step-by-step procedures, and domain knowledge.

Bundled Skills (100+)

Skills are organized by category:

Optional Skills (installed separately)

Additional skills available through the Skills Hub:

• MCP/FastMCP integrations
• MLOps: SAELens, Chroma, Pinecone, Qdrant
• Research: DuckDuckGo, drug discovery, bioinformatics, GitNexus, Scrapling
• DevOps/CLI tools
• Creative: Blender MCP, meme generation
• Security: 1Password, OSS forensics, Sherlock OSINT
• Health: fitness/nutrition tracking, neuroskill
• Blockchain: Solana, Base
• Email: AgentMail
• Migration: OpenClaw migration tools
• Productivity: telephony, Siyuan, Canvas, Memento flashcards

Skills Hub

Browse and install skills from the community hub:

# Search for skills
hermes skills search "jupyter"

# Browse the hub interactively
hermes skills browse

# Install a skill
hermes skills install openai/skills/skill-creator

# Check for updates
hermes skills check

# Update outdated skills
hermes skills update

Preloading Skills

Load specific skills at startup:

hermes --skills hermes-agent-dev,github-auth
# or
hermes -s github-auth -s hermes-agent-dev

Managing Skills

# List installed skills
hermes skills list

# Remove a skill
hermes skills remove youtube-quiz

# Audit skills for security
hermes skills audit

# Publish a skill
hermes skills publish ./my-skill --to github --repo myuser/skills

Memory Providers

Memory providers give Hermes persistent context across sessions. Set up memory:

hermes memory setup

Available providers:

Configure your provider:

hermes config set memory.provider holographic

For Honcho, additional setup is available:

hermes honcho setup       # Configure Honcho connection
hermes honcho config      # Show current Honcho config
hermes honcho session     # Manage session mappings
hermes honcho recall      # Set recall mode (hybrid/context/tools)

Messaging Gateway

The gateway connects Hermes to messaging platforms so you can chat with it from your phone, desktop apps, or team channels.

Start the Gateway

hermes gateway start

The gateway runs as a long-lived process. Install it as a system service for automatic startup:

hermes gateway service install

Supported Platforms

Set the required environment variables in ~/.hermes/.env, then start the gateway.

DM Pairing for Authorization

For platforms that support it, Hermes uses DM pairing to authorize users:

hermes gateway pair telegram <pairing_code>

Control who can interact with Hermes by setting allowed users:

# In ~/.hermes/.env
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=user1_id,user2_id

Important

Without TELEGRAM_ALLOWED_USERS or equivalent, anyone who finds your bot can interact with it. Always restrict access in production.

Gateway Management

hermes gateway status          # Check if running
hermes gateway status --deep   # Detailed health check
hermes gateway stop            # Stop the gateway
hermes gateway restart         # Restart gracefully
hermes gateway logs            # View gateway logs

Cron / Scheduled Tasks

Schedule recurring tasks that Hermes executes autonomously:

hermes cron create "every 2h" --prompt "Check my email and summarize new messages" --deliver telegram

Schedule formats:

Manage scheduled jobs:

hermes cron list                # List all jobs
hermes cron list --all          # Include disabled jobs
hermes cron pause <job_id>      # Pause a job
hermes cron resume <job_id>     # Resume a paused job
hermes cron run <job_id>        # Trigger immediately
hermes cron remove <job_id>     # Delete a job
hermes cron edit <job_id> --schedule "every 4h"  # Modify schedule

Attach skills and scripts to cron jobs:

hermes cron create "every 1h" \
  --prompt "Monitor the production dashboard" \
  --skill monitoring \
  --script ./scripts/fetch-metrics.py \
  --deliver slack

Delivery targets: origin, local, telegram, discord, slack, signal, or platform:chat_id.

Web Dashboard

Launch the web-based management interface:

hermes web

Dashboard: http://127.0.0.1:9119

The dashboard provides a browser interface for managing configuration, browsing sessions, controlling cron jobs, toggling skills and toolsets, and viewing logs.

Available themes: default, midnight, ember, mono, cyberpunk, rose.

hermes web --port 8080         # Custom port
hermes web --no-open           # Don't auto-open browser

Caution

The dashboard exposes API keys and configuration. It binds to 127.0.0.1 by default. Using --insecure to bind to 0.0.0.0 is dangerous on untrusted networks.

MCP (Model Context Protocol)

Add external tool servers via MCP:

# Add an HTTP/SSE server
hermes mcp add my-tools --url http://localhost:8080/sse

# Add a stdio server
hermes mcp add code-search --command npx --args "@anthropic-ai/mcp-search"

# Add from a preset
hermes mcp add github --preset github

# Test connectivity
hermes mcp test my-tools

# List configured servers
hermes mcp list

# Remove a server
hermes mcp remove my-tools

Set environment variables for stdio servers:

hermes mcp add my-server --command ./server.py --env "DB_URL=sqlite:///data.db" --env "API_KEY=abc123"

Plugins

Extend Hermes with community plugins:

# Install from GitHub
hermes plugins install anpicasso/hermes-plugin-chrome-profiles

# Install from a Git URL
hermes plugins install https://github.com/user/hermes-plugin-example.git

# List installed plugins
hermes plugins list

# Enable/disable
hermes plugins enable my-plugin
hermes plugins disable my-plugin

# Update a plugin
hermes plugins update my-plugin

# Remove
hermes plugins remove my-plugin

5. Common Tasks

1. Set Up Hermes with OpenRouter

Goal: Use OpenRouter as your inference provider for access to multiple models.

Steps:

1. Get an API key from https://openrouter.ai/keys
2. Add the key to your environment:

   hermes config set model openrouter/anthropic/claude-sonnet-4
   

3. Add the API key to ~/.hermes/.env:

   echo "OPENROUTER_API_KEY=sk-or-your-key-here" >> ~/.hermes/.env
   

4. Verify:

   hermes doctor
   

If it fails: Run hermes model to interactively select OpenRouter and re-enter your key.

2. Set Up with Nous Portal (Free Tier)

Goal: Use Nous Research's free inference tier.

Steps:

1. Run the authentication flow:

   hermes auth --provider nous
   

2. Follow the browser-based login to create/sign into your Nous account.
3. Hermes stores the OAuth tokens automatically.
4. Verify:

   hermes doctor
   

If it fails: Try hermes auth --provider nous --no-browser for headless environments, or check with hermes auth list.

3. Set Up with Local Ollama

Goal: Run Hermes with a local Ollama instance for fully offline usage.

Steps:

1. Install and start Ollama: https://ollama.ai
2. Pull a model:

   ollama pull llama3.1
   

3. Configure Hermes:

   hermes model
   

   Select "Ollama" and choose your model.
4. Verify:

   hermes -q "Hello, are you working?"
   

Tip

Set OLLAMA_BASE_URL in ~/.hermes/.env if Ollama runs on a different host or port (default: http://localhost:11434).

4. Switch Models Mid-Session

Goal: Change the LLM model during an active conversation.

Steps:

1. Inside the interactive REPL, type:

   /model
   

2. Select from the list of available models, or type a model identifier directly.
3. The switch takes effect immediately for the next response.

Alternative: From the CLI, specify a model for a single query:

hermes -q "Complex reasoning task" --model anthropic/claude-opus-4

5. Create a Telegram Bot

Goal: Chat with Hermes through Telegram.

Prerequisites: A Telegram account.

Steps:

1. Message @BotFather on Telegram and create a new bot with /newbot.
2. Copy the bot token.
3. Add it to ~/.hermes/.env:

   TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
   TELEGRAM_ALLOWED_USERS=your_telegram_user_id
   

4. Start the gateway:

   hermes gateway start
   

5. Message your bot on Telegram.

Verify: The bot responds to your messages. Check hermes gateway status if silent.

If it fails: Ensure TELEGRAM_ALLOWED_USERS contains your numeric Telegram user ID (get it from @userinfobot).

6. Create a Discord Bot

Goal: Chat with Hermes in Discord.

Prerequisites: Discord account with server admin permissions.

Steps:

1. Go to https://discord.com/developers/applications and create a new application.
2. Under "Bot", create a bot and copy the token.
3. Enable "Message Content Intent" under Privileged Gateway Intents.
4. Invite the bot to your server with appropriate permissions.
5. Add to ~/.hermes/.env:

   DISCORD_BOT_TOKEN=MTIz...your_token
   DISCORD_ALLOWED_USERS=your_discord_user_id
   

6. Start the gateway:

   hermes gateway start
   

Verify: Mention the bot in a channel or DM it.

If it fails: Discord requires the bot to be mentioned by default (DISCORD_REQUIRE_MENTION=true). Set DISCORD_REQUIRE_MENTION=false for DMs to work without mentions.

7. Set Up WhatsApp Bridge

Goal: Chat with Hermes through WhatsApp.

Prerequisites: Node.js 20+, a WhatsApp account.

Steps:

1. Navigate to the bridge directory:

   cd scripts/whatsapp-bridge
   npm install
   

2. Configure ~/.hermes/.env:

   WHATSAPP_ENABLED=true
   

3. Start the bridge:

   npm start
   

4. Scan the QR code with your WhatsApp mobile app.
5. Start the Hermes gateway:

   hermes gateway start
   

If it fails: Delete the auth_info_baileys/ directory in the bridge folder and re-scan the QR code.

8. Configure Persistent Memory with Honcho

Goal: Give Hermes persistent, cross-session memory using Honcho.

Steps:

1. Get an API key from https://app.honcho.dev
2. Add to ~/.hermes/.env:

   HONCHO_API_KEY=your_key_here
   

3. Configure:

   hermes config set memory.provider honcho
   hermes honcho setup
   

4. Set recall mode:

   hermes honcho recall hybrid
   

Verify: Have a conversation, exit, start a new session, and ask Hermes to recall what you discussed.

9. Configure Local Memory with Holographic

Goal: Use local SQLite-based memory with no external dependencies.

Steps:

1. Configure:

   hermes config set memory.provider holographic
   

2. That is all. Holographic stores data in ~/.hermes/ using SQLite with FTS5.

Verify: Chat across sessions and ask Hermes what it remembers.

10. Schedule a Daily Summary to Telegram

Goal: Get a daily morning summary delivered to your Telegram.

Prerequisites: Telegram bot configured and gateway running.

Steps:

1. Create the cron job:

   hermes cron create "0 9 * * *" \
     --prompt "Summarize my recent notifications, emails, and calendar for today" \
     --deliver telegram \
     --name "morning-summary"
   

2. Verify it was created:

   hermes cron list
   

If it fails: Ensure croniter is installed (pip install croniter) and the gateway is running.

11. Create and Use a Custom Skill

Goal: Write a skill that teaches Hermes a specialized task.

Steps:

1. Create a skill directory:

   mkdir -p ~/.hermes/skills/my-custom-skill
   

2. Write SKILL.md:

   ---
   name: my-custom-skill
   description: Formats code review comments in a specific style
   ---
   
   # Code Review Skill
   
   When reviewing code, follow these steps:
   1. Check for security vulnerabilities first
   2. Then check for performance issues
   3. Then check for style/readability
   4. Format each finding as: [SEVERITY] file:line - description
   

3. Use it:

   hermes -s my-custom-skill
   

12. Install a Skill from Skills Hub

Goal: Add a community skill to your installation.

Steps:

1. Search for skills:

   hermes skills search "code review"
   

2. Install one:

   hermes skills install openai/skills/code-review
   

3. Verify:

   hermes skills list
   

4. Use it:

   hermes -s code-review
   

If it fails: Try hermes skills install <id> --force if a security scan blocks installation.

13. Browse and Resume Previous Sessions

Goal: Find and continue a past conversation.

Steps:

1. Browse sessions interactively:

   hermes sessions browse
   

2. Or list recent sessions:

   hermes sessions list --limit 10
   

3. Resume by ID:

   hermes -r abc123def
   

4. Resume the most recent session:

   hermes -c
   

5. Resume a named session:

   hermes -c my-project
   

14. Use Git Worktree for Parallel Agent Work

Goal: Run multiple Hermes agents on the same repo without conflicts.

Steps:

1. Start Hermes with worktree isolation:

   hermes -w
   

2. Hermes creates a temporary git worktree and operates inside it.
3. When done, changes can be merged back to your main branch.

Note

Worktree mode requires the current directory to be a git repository.

15. Attach an Image for Vision Analysis

Goal: Have Hermes analyze an image.

Steps:

1. Single query with image:

   hermes -q "What's in this image?" --image ./photo.png
   

2. In interactive mode, just reference the file path in your message.

Prerequisites: A vision-capable model must be configured. Most providers offer vision models (e.g., gpt-4o, claude-sonnet-4).

16. Generate Images with fal.ai

Goal: Generate images using AI.

Prerequisites: fal-client installed (included in [all] extra), FAL_KEY set in ~/.hermes/.env.

Steps:

1. Enable the image generation toolset:

   hermes tools enable image_gen
   

2. Ask Hermes to generate an image:

   Generate an image of a futuristic city at sunset
   

17. Use Browser Automation

Goal: Let Hermes control a web browser for research or testing.

Prerequisites: Node.js 20+, npm install in the repo root.

Steps:

1. Enable the browser toolset:

   hermes tools enable browser
   

2. Ask Hermes to browse:

   Go to github.com/NousResearch and list their most popular repositories
   

Cloud alternatives: Set BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID for Browserbase, or FIRECRAWL_API_KEY for Firecrawl.

18. Run in Docker

Goal: Run Hermes in a containerized environment.

Steps:

1. Build the image:

   cd docker
   docker build -t hermes-agent .
   

2. Run interactively:

   docker run -it \
     -v ~/.hermes:/root/.hermes \
     hermes-agent
   

Set HERMES_CONTAINER=true to skip filesystem permission checks inside containers.

19. Set Up Profiles for Different Personas

Goal: Maintain separate configurations for different use cases.

Steps:

1. Create profiles:

   hermes profile create coding --clone
   hermes profile create research --clone
   

2. Customize each:

   hermes profile use coding
   hermes config set model anthropic/claude-sonnet-4
   hermes profile use research
   hermes config set model openrouter/google/gemini-2.5-pro
   

3. Switch between them:

   hermes profile use coding
   

20. Export and Import a Profile

Goal: Back up or share a profile configuration.

Steps:

1. Export:

   hermes profile export coding -o coding-profile.tar.gz
   

2. Import on another machine:

   hermes profile import coding-profile.tar.gz --name coding
   

21. Back Up Your Hermes Data

Goal: Create a full or quick backup of your Hermes data.

Steps:

1. Full backup:

   hermes backup
   

   Backup saved to ~/hermes-backup-20260512T120000.zip
   

2. Quick snapshot (config + state only):

   hermes backup --quick --label "before-upgrade"
   

3. Restore from backup:

   hermes backup restore ~/hermes-backup-20260512T120000.zip
   

22. Use the API Server for OpenAI-Compatible Clients

Goal: Expose Hermes as an OpenAI-compatible API endpoint.

Steps:

1. Set the API key in ~/.hermes/.env:

   API_SERVER_ENABLED=true
   API_SERVER_KEY=your-secret-key
   API_SERVER_PORT=8080
   

2. Start the gateway (the API server runs as a gateway platform):

   hermes gateway start
   

3. Use with any OpenAI-compatible client:

   curl http://localhost:8080/v1/chat/completions \
     -H "Authorization: Bearer your-secret-key" \
     -H "Content-Type: application/json" \
     -d '{"model": "hermes", "messages": [{"role": "user", "content": "Hello"}]}'
   

23. Set Up Home Assistant Integration

Goal: Control smart home devices through Hermes.

Steps:

1. Get a long-lived access token from Home Assistant (Profile > Security > Long-Lived Access Tokens).
2. Add to ~/.hermes/.env:

   HASS_TOKEN=eyJhbGciOi...
   HASS_URL=http://homeassistant.local:8123
   

3. Enable the toolset:

   hermes tools enable homeassistant
   

4. Test:

   Turn on the living room lights
   

24. Use Voice Mode

Goal: Talk to Hermes using your microphone.

Prerequisites: pip install "hermes-agent[voice]" or pip install sounddevice numpy faster-whisper.

Steps:

1. Start interactive mode:

   hermes
   

2. Enable voice:

   /voice on
   

3. Press Ctrl+B to record, release to send.

25. Configure Smart Model Routing

Goal: Use a cheaper model for simple queries and a powerful model for complex ones.

Steps:

1. Configure your primary (powerful) model:

   hermes config set model anthropic/claude-sonnet-4
   

2. Set up smart routing in ~/.hermes/config.yaml (see Admin Guide for full routing configuration options).

6. Troubleshooting

Error: No inference provider configured. Run 'hermes model' to choose a provider

Cause: No LLM provider is set up. Hermes does not know which model to use.

Solution:

1. Run hermes model and select a provider.
2. Or run hermes setup for the full interactive wizard.
3. Or set an API key directly in ~/.hermes/.env (e.g., OPENROUTER_API_KEY=sk-or-...).

Prevention: Always run hermes setup after a fresh install.

Error: Git Bash not found. Hermes Agent requires Git for Windows on Windows.

Cause: On Windows, Hermes uses Git Bash as the terminal backend, but it was not found.

Solution:

1. Install Git for Windows from https://git-scm.com/download/win.
2. Or set HERMES_GIT_BASH_PATH to the path of your bash.exe:

   set HERMES_GIT_BASH_PATH=C:\Program Files\Git\bin\bash.exe
   

Prevention: Install Git for Windows before installing Hermes on Windows.

Error: Voice mode requires sounddevice and numpy.

Cause: Voice input dependencies are not installed.

Solution:

1. pip install sounddevice numpy
2. Or: pip install "hermes-agent[voice]"

Prevention: Install the [voice] extra if you plan to use voice mode.

Error: Voice mode requires an STT provider for transcription.

Cause: No speech-to-text backend is available.

Solution:

1. Install local Whisper: pip install faster-whisper (free, runs locally)
2. Or set GROQ_API_KEY in ~/.hermes/.env (free tier available)
3. Or set VOICE_TOOLS_OPENAI_KEY in ~/.hermes/.env (paid)

Error: Docker executable not found in PATH

Cause: Docker is not installed or not in your system PATH.

Solution:

1. Install Docker: https://docs.docker.com/get-docker/
2. Ensure the docker command is accessible from your terminal.
3. Restart your terminal after installation.

Error: Docker daemon is not responding

Cause: Docker is installed but the daemon is not running.

Solution:

1. Start Docker Desktop (Windows/macOS) or the Docker service (Linux):

   sudo systemctl start docker
   

2. Verify: docker version

Error: SSH connection failed

Cause: SSH terminal backend cannot connect to the configured host.

Solution:

1. Verify SSH credentials: ssh user@host
2. Check TERMINAL_SSH_HOST, TERMINAL_SSH_USER, and TERMINAL_SSH_PORT in your environment.
3. Ensure SSH key authentication is set up.

Error: No Codex credentials stored. Run hermes auth to authenticate.

Cause: OpenAI Codex provider is configured but not authenticated.

Solution:

1. Run hermes auth --provider openai-codex
2. Follow the browser-based authentication flow.

Error: Provider 'X' is set in config.yaml but no API key was found

Cause: The configured provider requires an API key that is not set.

Solution:

1. Set the environment variable in ~/.hermes/.env:

   OPENROUTER_API_KEY=your-key
   # or
   OPENAI_API_KEY=your-key
   # or
   ANTHROPIC_API_KEY=your-key
   

2. Or switch providers: hermes model

Error: Missing API key. Set {env_var} environment variable.

Cause: A specific API key environment variable is required but not set.

Solution: Set the named environment variable in ~/.hermes/.env. Run hermes doctor --show-keys to see which keys are configured.

Error: hermes-agent[mcp] import error

Cause: The MCP extra is not installed.

Solution:

pip install "hermes-agent[mcp]"

Error: croniter package required for cron expressions

Cause: Cron expression parsing requires the croniter package.

Solution:

pip install croniter

Error: Unknown skill(s): {missing}

Cause: One or more skills specified with --skills or -s are not installed.

Solution:

1. Check available skills: hermes skills list
2. Install the missing skill: hermes skills install <identifier>
3. Verify the skill name matches exactly (case-sensitive).

Error: honcho-ai is required for Honcho integration

Cause: The Honcho memory plugin depends on the honcho-ai package.

Solution:

pip install honcho-ai

Error: Malformed custom endpoint URL

Cause: A custom LLM endpoint URL is malformed (not a valid http:// or https:// URL).

Solution:

1. Run hermes setup or hermes model and enter a valid base URL.
2. Check your ~/.hermes/config.yaml for typos in custom endpoint URLs.

Error: Web UI requires fastapi and uvicorn

Cause: The web dashboard dependencies are not installed.

Solution:

pip install "hermes-agent[web]"

Or install directly:

pip install fastapi uvicorn

Error: systemctl is not available on this system

Cause: Trying to install or manage the gateway as a system service on a platform without systemd (e.g., macOS, Termux).

Solution:

1. On macOS, the gateway uses launchd instead -- it should auto-detect.
2. On Termux, run the gateway manually: hermes gateway start.
3. Use a process manager like tmux or screen to keep it running.

Error: Neither 'apptainer' nor 'singularity' was found in PATH

Cause: Singularity/Apptainer terminal backend is configured but not installed.

Solution:

1. Install Apptainer: https://apptainer.org/docs/admin/main/installation.html
2. Or switch to a different terminal backend:

   hermes config set terminal.backend local
   

Error: Browserbase requires BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID

Cause: Browserbase cloud browser provider is selected but credentials are missing.

Solution: Add to ~/.hermes/.env:

BROWSERBASE_API_KEY=your-key
BROWSERBASE_PROJECT_ID=your-project-id

Error: FIRECRAWL_API_KEY environment variable is required

Cause: Firecrawl web extraction is enabled but the API key is missing.

Solution: Get a key at https://firecrawl.dev and add to ~/.hermes/.env:

FIRECRAWL_API_KEY=fc-your-key

Error: Honcho API key not found

Cause: Honcho memory provider is configured but no API key is set.

Solution:

1. Get a key at https://app.honcho.dev
2. Run hermes honcho setup or set HONCHO_API_KEY in ~/.hermes/.env.
3. For local Honcho instances, set HONCHO_BASE_URL instead.

Error: OSError: [Errno 22] Invalid argument (prompt_toolkit crash) -- Issue #5884

Cause: A known prompt_toolkit compatibility issue on certain terminal emulators.

Solution:

1. Update prompt_toolkit: pip install --upgrade prompt_toolkit
2. Try a different terminal emulator.
3. If on Windows, ensure you are using Windows Terminal or a compatible terminal, not the legacy cmd.exe.

Error: APIConnectionError -- Issue #10980

Cause: Network connectivity issue reaching the inference provider's API.

Solution:

1. Check your internet connection.
2. Verify the provider's API status page.
3. If behind a proxy, set GATEWAY_PROXY_URL in ~/.hermes/.env.
4. Try increasing the timeout: set HERMES_API_TIMEOUT (default: 1800 seconds).

Stale update cache: banner shows "N commits behind" after updating -- Issue #11007

Cause: The update check cache is not refreshed after a successful update.

Solution:

1. This is a known cosmetic issue. The banner message is outdated but Hermes is up to date.
2. The cache will refresh automatically after the next check interval.
3. Run hermes --version to confirm you are on the latest version.

Death spiral: 400 invalid tool call arguments causes context compression loop -- Issue #11001

Cause: When the model produces invalid tool call arguments, repeated retries can trigger continuous context compression instead of a graceful abort.

Solution:

1. Start a new session with /new.
2. If the issue persists, try a different model: /model
3. Reduce agent.max_turns to limit runaway loops:

   hermes config set agent.max_turns 30
   

7. FAQ

Getting Started

How do I update Hermes to the latest version? If installed via pip: pip install --upgrade hermes-agent. If installed from source: cd hermes-agent && git pull && pip install -e ".[all]". Inside a running session, use the /update slash command.

How do I uninstall Hermes? Run hermes uninstall for a clean removal. Add --full to remove all configs, data, and profiles. Then pip uninstall hermes-agent.

How do I use Hermes on my phone (Termux)? Install Termux from F-Droid, then pkg install python git followed by pip install hermes-agent. The HERMES_HOME defaults to $PREFIX/etc/hermes/ on Termux. For voice, install termux-api and the Termux:API Android app.

How do I check my token usage? Use the /usage slash command inside a session. On the gateway, use the /usage platform command. For analytics across sessions: hermes sessions stats.

Models and Providers

How do I change the default model? Run hermes model for an interactive picker, or hermes config set model <provider/model>.

Which LLM providers are supported? Over 30 providers including: OpenRouter, Anthropic, OpenAI, Nous Portal, Ollama, AWS Bedrock, Google Gemini, Groq, Together, Fireworks, Mistral, Deepseek, Qwen, Cohere, and more. Any OpenAI-compatible endpoint works via the custom provider option.

Can I use Hermes with a local model (Ollama)? Yes. Install Ollama, pull a model (ollama pull llama3.1), then run hermes model and select Ollama. Set OLLAMA_BASE_URL if Ollama runs on a non-default address.

What is smart model routing? Smart model routing automatically selects cheaper models for simple queries and more capable models for complex ones. Configure it through hermes config set or in ~/.hermes/config.yaml. See the Admin Guide for full routing configuration.

Can I use Hermes offline? Yes, with a local model like Ollama. All core features work offline except web tools, cloud browser providers, cloud memory providers, and gateway platforms that require internet.

How much context can Hermes handle? This depends on your model. Hermes supports context compression (/compress) to manage long conversations. Configure compression behavior with hermes config set.

Gateway

Can I run multiple agents in parallel? Yes. Use profiles to run separate instances (hermes profile create agent2), each with its own gateway. Or use hermes -w for git worktree isolation within a single profile.

How do I set up end-to-end encryption on Matrix? Set MATRIX_ENCRYPTION=true in ~/.hermes/.env. Provide MATRIX_RECOVERY_KEY for cross-signing verification. The nio library handles the E2EE protocol.

What is YOLO mode? YOLO mode (hermes --yolo or HERMES_YOLO_MODE=true) bypasses all dangerous command approval prompts. The agent executes terminal commands without asking for confirmation. Use with caution.

Skills

What is the difference between skills and toolsets? Toolsets provide tool functions the agent can call (e.g., terminal.run_bash, web.fetch). Skills are markdown instructions loaded into the system prompt that guide how the agent approaches tasks. Skills can reference toolsets but are not tools themselves.

How do I delegate tasks to sub-agents? Enable the delegation toolset (hermes tools enable delegation). Then ask Hermes to delegate: "Delegate the code review to a sub-agent." The main agent spawns a sub-agent with its own context and tools.

Memory

How do I keep conversation history? Hermes stores all sessions in a local SQLite database (~/.hermes/state.db). Browse with hermes sessions list or hermes sessions browse. For cross-session memory, configure a memory provider (hermes config set memory.provider holographic).

Is my data sent to third parties? Your conversations are sent to your configured LLM provider for inference. If using cloud memory providers (Honcho cloud, Mem0, etc.), memory data is stored on their servers. Local providers (Holographic, Honcho local) keep everything on your machine.

Configuration

What are profiles? Profiles are independent Hermes configurations, each with its own config file, API keys, sessions, skills, and plugins. Create them with hermes profile create <name> and switch with hermes profile use <name>.

How do I customize the system prompt? Create or edit ~/.hermes/SOUL.md. Its contents are injected into the system prompt for every session.

How do I configure compression? Hermes compresses conversation context when it exceeds the model's context window. Use /compress to trigger manually. Configure compression behavior in ~/.hermes/config.yaml. See the Admin Guide for detailed options.

What are platform toolsets? Platform toolsets are toolset configurations scoped to specific gateway platforms. For example, you can enable browser for CLI but disable it for Telegram. Manage with hermes tools enable <name> --platform telegram.

Sessions

How do I use checkpoints/rollback? Start Hermes with hermes --checkpoints. Before destructive file operations, Hermes creates filesystem snapshots. Use /rollback inside a session to restore to a previous checkpoint.

Can I use Hermes in CI/CD pipelines? Yes. Use quiet mode for programmatic output: hermes -Q -q "Generate a changelog". Use --source tool to tag sessions as non-interactive. The --max-turns flag prevents runaway execution.

Advanced

Can I use Hermes as an OpenAI-compatible API server? Yes. Set API_SERVER_ENABLED=true and API_SERVER_KEY=your-secret in ~/.hermes/.env, then start the gateway. The API server is accessible at http://localhost:<API_SERVER_PORT>/v1/chat/completions.

What is the ACP adapter? The Agent Communication Protocol (ACP) adapter exposes Hermes as an ACP-compliant agent. It lives in the acp_adapter/ directory and allows orchestration tools to interact with Hermes using the standard ACP protocol.

How do I set up webhooks? Create webhook subscriptions to react to external events:

hermes webhooks create my-hook \
  --prompt "A deployment happened: {body.status}" \
  --events deployment \
  --deliver telegram

Set WEBHOOK_ENABLED=true and WEBHOOK_SECRET in ~/.hermes/.env.