# 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

| Requirement | Version |
|-------------|---------|
| Python | 3.10+ |
| Node.js | 20+ (for browser tools) |
| Git | Any recent version |

### Install and Run

```bash
pip install hermes-agent
```

Start an interactive session:

```bash
hermes
```

Ask a single question:

```bash
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](#2-installation) — all install methods and extras
- [Section 3: Configuration](#3-configuration) — set up models, providers, and profiles
- [Section 4: Core Usage](#4-core-usage) — interactive chat, toolsets, skills, gateway, and more
- [Section 5: Common Tasks](#5-common-tasks) — step-by-step recipes for real-world scenarios

---

## 2. Installation

### System Requirements

| Component | Required | Notes |
|-----------|----------|-------|
| Python | 3.10+ | 3.11+ recommended |
| Node.js | 20+ | Required for browser tools |
| Git | Any | For worktree isolation and updates |
| ffmpeg | Optional | Required for media skills and TTS |
| Docker | Optional | For sandboxed terminal environments |

### Install Methods

#### pip (recommended)

Install the base package:

```bash
pip install hermes-agent
```

Install with all extras:

```bash
pip install "hermes-agent[all]"
```

#### From Source

```bash
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:

```bash
brew install hermes-agent
```

#### Docker

Build from the included Dockerfile:

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

#### Nix

A `flake.nix` is included for Nix users:

```bash
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:

| Extra | What It Adds |
|-------|-------------|
| `[all]` | Everything below |
| `[web]` | Web scraping tools (firecrawl-py, parallel-web) |
| `[voice]` | Voice input/output (sounddevice, numpy, faster-whisper) |
| `[mcp]` | Model Context Protocol server support |
| `[bedrock]` | AWS Bedrock provider (boto3) |
| `[yc-bench]` | Benchmarking tools |

Example:

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

### Post-Install Setup

Run the interactive setup wizard:

```bash
hermes setup
```

```text
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:

```bash
hermes doctor
```

```text
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:

```bash
hermes --version
```

```text
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:

```bash
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/`:

```text
~/.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:

```bash
hermes model
```

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

```bash
hermes config set model anthropic/claude-sonnet-4
```

### Environment Variables

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

```bash
# 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`:

```bash
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

```yaml
# ~/.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:

```markdown
# 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):

```bash
# 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:

```bash
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:

| Command | Description |
|---------|-------------|
| `/new` | Start a new conversation (clears context) |
| `/model` | Switch the active model |
| `/title <name>` | Set a title for the current session |
| `/skin` | Change the TUI skin/theme |
| `/resume` | Resume a previous session |
| `/compress` | Manually compress the conversation context |
| `/tools` | Show or toggle active toolsets |
| `/skills` | List loaded skills |
| `/help` | Show all available commands |
| `/voice on` | Enable voice input mode |
| `/rollback` | Restore files from a checkpoint (requires `--checkpoints`) |
| `/undo` | Undo the last assistant action |
| `/retry` | Retry the last response |

#### Voice Mode

Enable voice input during a session:

```text
/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:

```bash
hermes -r <session_id>
```

Resume by name, or the most recent session:

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

Browse previous sessions interactively:

```bash
hermes sessions browse
```

#### Git Worktree Isolation

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

```bash
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:

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

Combine with model and toolset flags:

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

Attach an image:

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

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

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

```text
4
```

### Toolsets

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

| Toolset | Description |
|---------|-------------|
| `terminal` | Execute shell commands |
| `web` | Fetch and extract web content |
| `browser` | Full browser automation (requires Node.js 20+) |
| `file` | Read, write, and manage files |
| `vision` | Analyze images with vision models |
| `image_gen` | Generate images (fal.ai) |
| `tts` | Text-to-speech output (Edge TTS) |
| `todo` | Manage task lists |
| `memory` | Access persistent memory |
| `session_search` | Search across past sessions |
| `clarify` | Ask clarifying questions before acting |
| `code_execution` | Run Python code in a sandbox |
| `delegation` | Delegate tasks to sub-agents |
| `cronjob` | Create and manage scheduled tasks |
| `homeassistant` | Control smart home devices |
| `messaging` | Send messages across platforms |
| `moa` | Mixture-of-agents responses |
| `rl` | Reinforcement learning tools |
| `skills` | Load and execute skills |

Manage toolsets from the CLI:

```bash
# 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:

```bash
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:

| Category | Examples |
|----------|---------|
| **Creative** | ASCII video, Manim animations, p5.js sketches, Excalidraw diagrams, architecture diagrams |
| **Productivity** | Google Workspace, Notion, Linear, OCR, PowerPoint |
| **Research** | arXiv papers, Polymarket, blog watcher, paper writing |
| **MLOps** | Training (Axolotl, TRL, GRPO, Unsloth), inference (vLLM, llama.cpp, GGUF), evaluation (lm-eval-harness, W&B) |
| **GitHub** | Code review, PR workflow, issues, repo management, auth |
| **Software Development** | TDD, debugging, code review, subagent-driven development |
| **Data Science** | Jupyter live kernel integration |
| **Media** | YouTube transcripts, GIF search |
| **Social Media** | X/Twitter posting and reading |
| **Email** | Himalaya email client |
| **Smart Home** | OpenHue light control |
| **Gaming** | Minecraft, Pokemon |
| **DevOps** | Docker management, webhooks |
| **Red-Teaming** | Godmode prompt engineering |
| **Diagramming** | Mermaid, ASCII, Excalidraw |
| **Note-Taking** | Obsidian integration |
| **Autonomous AI** | Claude Code, Codex, Hermes Agent, OpenCode orchestration |

#### 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:

```bash
# 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:

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

#### Managing Skills

```bash
# 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:

```bash
hermes memory setup
```

Available providers:

| Provider | Type | Description |
|----------|------|-------------|
| **Honcho** | Cloud + Local | Knowledge graph with dialectic reasoning |
| **Hindsight** | Cloud/Local/External | Flexible storage options |
| **Holographic** | Local (SQLite) | FTS5-based full-text search, zero dependencies |
| **Mem0** | Cloud | Semantic memory with embeddings |
| **ByteRover** | CLI-based | Command-line memory management |
| **OpenViking** | Cloud (Volcengine) | Volcengine-backed storage |
| **RetainDB** | Cloud | Cloud-hosted persistent memory |
| **Supermemory** | Cloud | Cloud-based semantic memory |

Configure your provider:

```bash
hermes config set memory.provider holographic
```

For Honcho, additional setup is available:

```bash
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

```bash
hermes gateway start
```

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

```bash
hermes gateway service install
```

#### Supported Platforms

| Platform | Token/Key Env Var | Notes |
|----------|------------------|-------|
| Telegram | `TELEGRAM_BOT_TOKEN` | Most fully featured; supports reactions, threads, webhooks |
| Discord | `DISCORD_BOT_TOKEN` | Slash commands, thread auto-creation, reactions |
| Slack | `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN` | Socket Mode; thread-based conversations |
| WhatsApp | (via bridge) | Requires Node.js WhatsApp bridge (`scripts/whatsapp-bridge/`) |
| Signal | `SIGNAL_HTTP_URL`, `SIGNAL_ACCOUNT` | Via Signal CLI REST API |
| Matrix | `MATRIX_HOMESERVER`, `MATRIX_USER_ID` | Supports E2EE with `MATRIX_ENCRYPTION=true` |
| Mattermost | `MATTERMOST_TOKEN`, `MATTERMOST_URL` | WebSocket-based |
| Email | `EMAIL_ADDRESS`, `EMAIL_PASSWORD`, `EMAIL_IMAP_HOST`, `EMAIL_SMTP_HOST` | IMAP polling |
| SMS | `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, `TWILIO_PHONE_NUMBER` | Via Twilio |
| Home Assistant | `HASS_TOKEN`, `HASS_URL` | Smart home integration |
| DingTalk | `DINGTALK_CLIENT_ID`, `DINGTALK_CLIENT_SECRET` | Chinese enterprise messaging |
| Feishu/Lark | `FEISHU_APP_ID`, `FEISHU_APP_SECRET` | WebSocket or webhook mode |
| WeCom | `WECOM_BOT_ID`, `WECOM_SECRET` | WeChat Work |
| Weixin | `WEIXIN_ACCOUNT_ID`, `WEIXIN_TOKEN` | WeChat personal |
| BlueBubbles | `BLUEBUBBLES_SERVER_URL`, `BLUEBUBBLES_PASSWORD` | iMessage bridge |
| QQ | `QQ_APP_ID`, `QQ_CLIENT_SECRET` | QQ Bot platform |
| API Server | `API_SERVER_KEY` | OpenAI-compatible REST API |
| Webhook | `WEBHOOK_SECRET` | Generic webhook receiver |

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:

```bash
hermes gateway pair telegram <pairing_code>
```

Control who can interact with Hermes by setting allowed users:

```bash
# 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

```bash
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:

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

Schedule formats:

| Format | Example | Meaning |
|--------|---------|---------|
| Duration | `30m`, `2h`, `1d` | One-shot after delay |
| Interval | `every 30m`, `every 2h` | Recurring |
| Cron expression | `0 9 * * *` | Standard cron (requires `croniter` package) |
| Timestamp | `2026-06-01T14:00:00` | One-shot at specific time |

Manage scheduled jobs:

```bash
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:

```bash
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:

```bash
hermes web
```

```text
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`.

```bash
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:

```bash
# 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:

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

### Plugins

Extend Hermes with community plugins:

```bash
# 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:
   ```bash
   hermes config set model openrouter/anthropic/claude-sonnet-4
   ```
3. Add the API key to `~/.hermes/.env`:
   ```bash
   echo "OPENROUTER_API_KEY=sk-or-your-key-here" >> ~/.hermes/.env
   ```
4. Verify:
   ```bash
   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:
   ```bash
   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:
   ```bash
   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:
   ```bash
   ollama pull llama3.1
   ```
3. Configure Hermes:
   ```bash
   hermes model
   ```
   Select "Ollama" and choose your model.
4. Verify:
   ```bash
   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:
   ```text
   /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:
```bash
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`:
   ```bash
   TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
   TELEGRAM_ALLOWED_USERS=your_telegram_user_id
   ```
4. Start the gateway:
   ```bash
   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`:
   ```bash
   DISCORD_BOT_TOKEN=MTIz...your_token
   DISCORD_ALLOWED_USERS=your_discord_user_id
   ```
6. Start the gateway:
   ```bash
   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:
   ```bash
   cd scripts/whatsapp-bridge
   npm install
   ```
2. Configure `~/.hermes/.env`:
   ```bash
   WHATSAPP_ENABLED=true
   ```
3. Start the bridge:
   ```bash
   npm start
   ```
4. Scan the QR code with your WhatsApp mobile app.
5. Start the Hermes gateway:
   ```bash
   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`:
   ```bash
   HONCHO_API_KEY=your_key_here
   ```
3. Configure:
   ```bash
   hermes config set memory.provider honcho
   hermes honcho setup
   ```
4. Set recall mode:
   ```bash
   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:
   ```bash
   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:
   ```bash
   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:
   ```bash
   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:
   ```bash
   mkdir -p ~/.hermes/skills/my-custom-skill
   ```
2. Write `SKILL.md`:
   ```markdown
   ---
   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:
   ```bash
   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:
   ```bash
   hermes skills search "code review"
   ```
2. Install one:
   ```bash
   hermes skills install openai/skills/code-review
   ```
3. Verify:
   ```bash
   hermes skills list
   ```
4. Use it:
   ```bash
   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:
   ```bash
   hermes sessions browse
   ```
2. Or list recent sessions:
   ```bash
   hermes sessions list --limit 10
   ```
3. Resume by ID:
   ```bash
   hermes -r abc123def
   ```
4. Resume the most recent session:
   ```bash
   hermes -c
   ```
5. Resume a named session:
   ```bash
   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:
   ```bash
   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:
   ```bash
   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:
   ```bash
   hermes tools enable image_gen
   ```
2. Ask Hermes to generate an image:
   ```text
   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:
   ```bash
   hermes tools enable browser
   ```
2. Ask Hermes to browse:
   ```text
   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:
   ```bash
   cd docker
   docker build -t hermes-agent .
   ```
2. Run interactively:
   ```bash
   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:
   ```bash
   hermes profile create coding --clone
   hermes profile create research --clone
   ```
2. Customize each:
   ```bash
   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:
   ```bash
   hermes profile use coding
   ```

### 20. Export and Import a Profile

**Goal:** Back up or share a profile configuration.

**Steps:**
1. Export:
   ```bash
   hermes profile export coding -o coding-profile.tar.gz
   ```
2. Import on another machine:
   ```bash
   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:
   ```bash
   hermes backup
   ```
   ```text
   Backup saved to ~/hermes-backup-20260512T120000.zip
   ```
2. Quick snapshot (config + state only):
   ```bash
   hermes backup --quick --label "before-upgrade"
   ```
3. Restore from backup:
   ```bash
   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`:
   ```bash
   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):
   ```bash
   hermes gateway start
   ```
3. Use with any OpenAI-compatible client:
   ```bash
   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`:
   ```bash
   HASS_TOKEN=eyJhbGciOi...
   HASS_URL=http://homeassistant.local:8123
   ```
3. Enable the toolset:
   ```bash
   hermes tools enable homeassistant
   ```
4. Test:
   ```text
   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:
   ```bash
   hermes
   ```
2. Enable voice:
   ```text
   /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:
   ```bash
   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`:
   ```bash
   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):
   ```bash
   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`:
   ```bash
   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:**
```bash
pip install "hermes-agent[mcp]"
```

---

### Error: `croniter package required for cron expressions`

**Cause:** Cron expression parsing requires the `croniter` package.

**Solution:**
```bash
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:**
```bash
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:**
```bash
pip install "hermes-agent[web]"
```

Or install directly:
```bash
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:
   ```bash
   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`:
```bash
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`:
```bash
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:
   ```bash
   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:
```bash
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`.

---

_Generated May 2026 from NousResearch/hermes-agent at 512c328. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._