@witcheer: by the way, for anyone wanting to set up the perfect @NousResearch Hermes Agent: (a) direct your most capable LLM to ht…

X AI KOLs Timeline 06/10/26, 07:15 PM Tools

hermes-agent nousresearch cli-tool agent-framework developer-tools open-source terminal-ui

Summary

A guide to setting up and using the NousResearch Hermes Agent, a CLI tool for creating and managing autonomous AI agents, including background sessions, context compression, and session storage.

by the way, for anyone wanting to set up the perfect @NousResearch Hermes Agent: (a) direct your most capable LLM to https://hermes-agent.nousresearch.com/docs/llms-full.txt… (b) explain your needs, what you want the agent to do for you, and provide full context (c) enjoy this file is the entire Hermes Agent documentation concatenated for LLM context ingestion.

Original Article

View Cached Full Text

Cached at: 06/11/26, 11:46 PM

by the way, for anyone wanting to set up the perfect @NousResearch Hermes Agent:

(a) direct your most capable LLM to https://hermes-agent.nousresearch.com/docs/llms-full.txt… (b) explain your needs, what you want the agent to do for you, and provide full context (c) enjoy

this file is the entire Hermes Agent documentation concatenated for LLM context ingestion.

`from the command line. Use`hermes sessions list`to browse past sessions. ### Session Storage CLI sessions are stored in Hermes's SQLite state database under`/.hermes/state.db`. The database keeps: - session metadata (ID, title, timestamps, token counters) - message history - lineage across compressed/resumed sessions - full-text search indexes used by` session_searchSome messaging adapters also keep per-platform transcript files alongside the database, but the CLI itself resumes from the SQLite session store. ### Context Compression Long conversations are automatically summarized when approaching context limits: ```yaml # In ~/.hermes/config.yaml compression: enabled: true threshold: 0.50 # Compress at 50% of context limit by default # Summarization model configured under auxiliary: auxiliary: compression: model: "" # Leave empty to use the main chat model (default). Or pin a cheap fast model, e.g. "google/gemini-3-flash-preview". ``` When compression triggers, middle turns are summarized while the first 3 and last 20 turns are always preserved. ## Background Sessions Run a prompt in a separate background session while continuing to use the CLI for other work: ``` /background Analyze the logs in /var/log and summarize any errors from today ``` Hermes immediately confirms the task and gives you back the prompt: ``` 🔄 Background task #1 started: "Analyze the logs in /var/log and summarize..." Task ID: bg_143022_a1b2c3 ``` ### How It Works Each/backgroundprompt spawns a completely separate agent session in a daemon thread: - Isolated conversation — the background agent has no knowledge of your current session's history. It receives only the prompt you provide. - Same configuration — the background agent inherits your model, provider, toolsets, reasoning settings, and fallback model from the current session. - Non-blocking — your foreground session stays fully interactive. You can chat, run commands, or even start more background tasks. - Multiple tasks — you can run several background tasks simultaneously. Each gets a numbered ID. ### Results When a background task finishes, the result appears as a panel in your terminal: ``` ╭─ ⚕ Hermes (background #1) ──────────────────────────────────╮ │ Found 3 errors in syslog from today: │ │ 1. OOM killer invoked at 03:22 — killed process nginx │ │ 2. Disk I/O error on /dev/sda1 at 07:15 │ │ 3. Failed SSH login attempts from 192.168.1.50 at 14:30 │ ╰──────────────────────────────────────────────────────────────╯ ``` If the task fails, you'll see an error notification instead. Ifdisplay.bell_on_completeis enabled in your config, the terminal bell rings when the task finishes. ### Use Cases - Long-running research — "/background research the latest developments in quantum error correction" while you work on code - File processing — "/background analyze all Python files in this repo and list any security issues" while you continue a conversation - Parallel investigations — start multiple background tasks to explore different angles simultaneously :::info Background sessions do not appear in your main conversation history. They are standalone sessions with their own task ID (e.g.,bg_143022_a1b2c3). ::: ## Quiet Mode By default, the CLI runs in quiet mode which: - Suppresses verbose logging from tools - Enables kawaii-style animated feedback - Keeps output clean and user-friendly For debug output: ```bash hermes chat --verbose ``` ---  # TUI # TUI The TUI is the modern front-end for Hermes — a terminal UI backed by the same Python runtime as the [Classic CLI](cli.md). Same agent, same sessions, same slash commands; a cleaner, more responsive surface for interacting with them. It's the recommended way to run Hermes interactively. ## Launch ```bash # Launch the TUI hermes --tui # Resume the latest TUI session (falls back to the latest classic session) hermes --tui -c hermes --tui --continue # Resume a specific session by ID or title hermes --tui -r 20260409_000000_aa11bb hermes --tui --resume "my t0p session" # Run source directly — skips the prebuild step (for TUI contributors) hermes --tui --dev ``` You can also enable it via env var: ```bash export HERMES_TUI=1 hermes # now uses the TUI hermes chat # same ``` Or make it the persistent default in /.hermes/config.yaml: ```yaml display: interface: tui # "cli" (default) or "tui" ``` With display.interface: tui`, a bare` hermes`(and`hermes chat`) launches the TUI. Explicit flags always win — run` hermes –cli`to drop back to the classic REPL for a single invocation, or`hermes –tui`/`HERMES_TUI=1`to force the TUI when the config default is`cli. The classic CLI remains the shipped default. Anything documented in [CLI Interface](cli.md) — slash commands, quick commands, skill preloading, personalities, multi-line input, interrupts — works in the TUI identically. ## Why the TUI - Instant first frame — the banner paints before the app finishes loading, so the terminal never feels frozen while Hermes is starting. - Non-blocking input — type and queue messages before the session is ready. Your first prompt sends the moment the agent comes online. - Rich overlays — model picker, session picker, approval and clarification prompts all render as modal panels rather than inline flows. - Live session panel — tools and skills fill in progressively as they initialize. - Mouse-friendly selection — drag to highlight with a uniform background instead of SGR inverse. Copy with your terminal's normal copy gesture. - Alternate-screen rendering — differential updates mean no flicker when streaming, no scrollback clutter after you quit. - Composer affordances — inline paste-collapse for long snippets, Cmd+V`/`Ctrl+V`text paste with clipboard-image fallback, bracketed-paste safety, and image/file-path attachment normalization. Same [skins](features/skins.md) and [personalities](features/personality.md) apply. Switch mid-session with`/skin ares`,` /personality pirate`, and the UI repaints live. See [Skins & Themes](features/skins.md) for the full list of customizable keys and which ones apply to classic vs TUI — the TUI honors the banner palette, UI colors, prompt glyph/color, session display, completion menu, selection bg,` tool_prefix`, and` help_header`. ### Collapsible banner sections The TUI startup banner groups runtime info into four collapsible sections, each rendered with a` ▸`/`▾chevron next to the section title: | Section | Default state | |---------|---------------| | Tools | Open | | Skills | Collapsed | | System Prompt | Collapsed | | MCP Servers | Collapsed | Click anywhere on a section header (or its chevron) to toggle it. The Tools list opens by default because it's the most-checked section at session start; Skills, System Prompt, and MCP Servers collapse by default so the banner stays compact even when you've installed dozens of skills or wired up many MCP servers. State is local to the banner instance, so the next launch resets to the defaults. ## Requirements - Node.js ≥ 20 — the TUI runs as a subprocess launched from the Python CLI.hermes doctor`verifies this. - TTY — like the classic CLI, piping stdin or running in non-interactive environments falls back to single-query mode. On first launch Hermes installs the TUI's Node dependencies into`ui-tui/node_modules(one-time, a few seconds). Subsequent launches are fast. If you pull a new Hermes version, the TUI bundle is rebuilt automatically when sources are newer than the dist. ### External prebuild Distributions that ship a prebuilt bundle (Nix, system packages) can point Hermes at it: ```bash export HERMES_TUI_DIR=/path/to/prebuilt/ui-tui hermes --tui ``` The directory must containdist/entry.js`. ## Keybindings Keybindings match the [Classic CLI](cli.md#keybindings) exactly. The only behavioral differences: - Mouse drag highlights text with a uniform selection background. - `Cmd+V`/`Ctrl+V` first tries normal text paste, then falls back to OSC52/native clipboard reads, and finally image attach when the clipboard or pasted payload resolves to an image. - `/terminal-setup` installs local VS Code / Cursor / Windsurf terminal bindings for better` Cmd+Enter `and undo/redo parity on macOS. - Slash autocompletion opens as a floating panel with descriptions, not an inline dropdown. - `Ctrl+X` opens the live session switcher. When a queued message is highlighted (sent while the agent was still running), it still deletes that queued message instead. `Esc` cancels editing and unhighlights without deleting. - `Ctrl+G`/`Ctrl+X Ctrl+E` — open the current input buffer in` $EDITOR` for multi-line / long-prompt composition; save-and-exit sends the contents back as the prompt. ## Slash commands All slash commands work unchanged. A few are TUI-owned — they produce richer output or render as overlays rather than inline panels: | Command | TUI behavior | |---------|--------------| | `/help` | Overlay with categorized commands, arrow-key navigable | | `/sessions` (alias `/switch`) | Live session switcher — list open TUI sessions, switch between them, close them, or start another one | | `/model` | Modal model picker grouped by provider, with cost hints | | `/skin` | Live preview — theme change applies as you browse | | `/details` | Toggle verbose tool-call details (global or per-section) | | `/usage` | Rich token / cost / context panel | | `/agents` (alias `/tasks`) | Observability overlay — live subagent tree with kill/pause controls, per-branch cost / token / file rollups, turn-by-turn history | | `/reload` | Re-reads `~/.hermes/.env` into the running TUI process so newly added API keys take effect without a restart | | `/mouse [on\|off\|toggle\|wheel\|buttons\|all]` | Pick a mouse tracking preset at runtime (also persists to `display.mouse_tracking` in `config.yaml`). `wheel` (1000+1006) keeps scroll-wheel scrolling without the hover events that make tmux spam "No image in clipboard" over the prompt row; `buttons` adds drag-to-select; `all` is the default with hover-driven UI. | Every other slash command (including installed skills, quick commands, and personality toggles) works identically to the classic CLI. See [Slash Commands Reference](../reference/slash-commands.md). ## Live session switcher Use the live session switcher when you want one terminal to act as a dispatcher for several TUI sessions. It lists only sessions that are currently live in this TUI process; closed sessions remain saved transcripts and can still be reopened with `/resume` or `hermes --tui --resume <id-or-title>`. Open it with any of these: - `Ctrl+X` from the TUI. - `/sessions` or `/switch`. - `/sessions new` to create a fresh live session immediately. - Click the `N live sessions` count in the status line. <img alt="Hermes TUI Session Orchestrator with one live session and a +new row" src="/img/docs/tui-session-orchestrator/session-orchestrator.png" /> <video controls muted loop playsInline src="/img/docs/tui-session-orchestrator/session-orchestrator-demo.mp4" title="Hermes TUI Session Orchestrator demo" /> Inside the switcher: - `↑` / `↓` move the selection; mouse clicks select rows too. - `Enter` switches to the selected live session. - `Ctrl+D` closes the selected live session. - `Ctrl+N` starts a blank live session. - `Ctrl+R` refreshes the live-session list. - `Esc` closes the switcher. - Select `+new`, type a prompt, and press `Enter` to dispatch a new live session. Press `Tab` first if you want to choose a model just for that new session. ## LaTeX math rendering The TUI's markdown pipeline renders LaTeX math inline: `$ E = mc^2 $` and `$ $\frac{a}{b}$ {VAR_NAME}syntax: ```yaml auxiliary: vision: api_key: ${GOOGLE_API_KEY} base_url: ${CUSTOM_VISION_URL} delegation: api_key: ${DELEGATION_KEY} ``` Multiple references in a single value work:url: “ ${HOST}:$ {PORT}”`. If a referenced variable is not set, the placeholder is kept verbatim (` ${UNDEFINED_VAR}` stays as-is). Only the `$ {VAR}`syntax is supported — bare` $VAR` is not expanded. For AI provider setup (OpenRouter, Anthropic, Copilot, custom endpoints, self-hosted LLMs, fallback models, etc.), see [AI Providers](/integrations/providers). ### Provider Timeouts You can set `providers.<id>.request_timeout_seconds` for a provider-wide request timeout, plus `providers.<id>.models.<model>.timeout_seconds` for a model-specific override. Applies to the primary turn client on every transport (OpenAI-wire, native Anthropic, Anthropic-compatible), the fallback chain, rebuilds after credential rotation, and (for OpenAI-wire) the per-request timeout kwarg — so the configured value wins over the legacy `HERMES_API_TIMEOUT` env var. You can also set `providers.<id>.stale_timeout_seconds` for the non-streaming stale-call detector, plus `providers.<id>.models.<model>.stale_timeout_seconds` for a model-specific override. This wins over the legacy `HERMES_API_CALL_STALE_TIMEOUT` env var. Leaving these unset keeps the legacy defaults (`HERMES_API_TIMEOUT=1800`s, `HERMES_API_CALL_STALE_TIMEOUT=300`s, native Anthropic 900s). Not currently wired for AWS Bedrock (both `bedrock_converse` and AnthropicBedrock SDK paths use boto3 with its own timeout configuration). See the commented example in [`cli-config.yaml.example`](https://github.com/NousResearch/hermes-agent/blob/main/cli-config.yaml.example). ## Update Behavior `hermes update` settings live under `updates` in `config.yaml`: ```yaml updates: pre_update_backup: false # Create a full HERMES_HOME zip before every update backup_keep: 5 # Keep this many pre-update backup zips non_interactive_local_changes: stash # stash | discard ``` For git installs, Hermes auto-stashes dirty tracked files and untracked files before checking out the update branch or pulling. Interactive terminal updates prompt before restoring that stash. Non-interactive updates (desktop/chat app, gateway, or `--yes`) use `updates.non_interactive_local_changes`: `stash` restores local source edits after a successful pull, while `discard` drops the update-created stash after a successful pull. Use `discard` only on managed installs where local source edits are never meant to persist. Before that stash step, Hermes also restores tracked `package-lock.json` diffs left by npm install/build churn. Commit or manually stash intentional lockfile edits before updating. ## Terminal Backend Configuration Hermes supports six terminal backends. Each determines where the agent's shell commands actually execute — your local machine, a Docker container, a remote server via SSH, a Modal cloud sandbox (direct or via the Nous-managed gateway), a Daytona workspace, or a Singularity/Apptainer container. ```yaml terminal: backend: local # local | docker | ssh | modal | daytona | singularity cwd: "." # Gateway/cron working directory (CLI always uses launch dir) timeout: 180 # Per-command timeout in seconds env_passthrough: [] # Env var names to forward to sandboxed execution (terminal + execute_code) singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20" # Container image for Singularity backend modal_image: "nikolaik/python-nodejs:python3.11-nodejs20" # Container image for Modal backend daytona_image: "nikolaik/python-nodejs:python3.11-nodejs20" # Container image for Daytona backend ``` For cloud sandboxes such as Modal and Daytona, `container_persistent: true` means Hermes will try to preserve filesystem state across sandbox recreation. It does not promise that the same live sandbox, PID space, or background processes will still be running later. ### Backend Overview | Backend | Where commands run | Isolation | Best for | |---------|-------------------|-----------|----------| | local | Your machine directly | None | Development, personal use | | docker | Single persistent Docker container (shared across session, `/new`, subagents) | Full (namespaces, cap-drop) | Safe sandboxing, CI/CD | | ssh | Remote server via SSH | Network boundary | Remote dev, powerful hardware | | modal | Modal cloud sandbox | Full (cloud VM) | Ephemeral cloud compute, evals | | daytona | Daytona workspace | Full (cloud container) | Managed cloud dev environments | | singularity | Singularity/Apptainer container | Namespaces (--containall) | HPC clusters, shared machines | ### Local Backend The default. Commands run directly on your machine with no isolation. No special setup required. ```yaml terminal: backend: local ``` :::warning The agent has the same filesystem access as your user account. Use `hermes tools` to disable tools you don't want, or switch to Docker for sandboxing. ::: ### Docker Backend Runs commands inside a Docker container with security hardening (all capabilities dropped, no privilege escalation, PID limits). Single persistent container, shared across Hermes processes. Hermes starts ONE long-lived container on first use and routes every terminal, file, and `execute_code` call through `docker exec` into that same container — across sessions, `/new`, `/reset`, and `delegate_task` subagents. Working-directory changes, installed packages, files in `/workspace`, and background processes all carry over from one tool call to the next, and from one Hermes process to the next. When you close a TUI session, run `/quit`, or start a new `hermes` invocation, the container keeps running and the next Hermes process reuses it via a labeled lookup. See Container lifecycle below for the exact teardown rules. ```yaml terminal: backend: docker docker_image: "nikolaik/python-nodejs:python3.11-nodejs20" docker_mount_cwd_to_workspace: false # Mount launch dir into /workspace docker_run_as_host_user: false # See "Running container as host user" below docker_forward_env: # Host env vars to forward into container - "GITHUB_TOKEN" docker_env: # Literal env vars to inject (KEY=value) DEBUG: "1" PYTHONUNBUFFERED: "1" docker_volumes: # Host directory mounts - "/home/user/projects:/workspace/projects" - "/home/user/data:/data:ro" # :ro for read-only docker_extra_args: # Extra flags appended verbatim to `docker run` - "--gpus=all" - "--network=host" # Resource limits container_cpu: 1 # CPU cores (0 = unlimited) container_memory: 5120 # MB (0 = unlimited) container_disk: 51200 # MB (requires overlay2 on XFS+pquota) container_persistent: true # Persist /workspace and /root bind-mount dirs # Cross-process container reuse (defaults match the "one long-lived # container shared across sessions" contract — see Container lifecycle). docker_persist_across_processes: true # Reuse container across Hermes restarts docker_orphan_reaper: true # Sweep abandoned Exited containers at startup # Cross-backend lifecycle settings (apply to docker as well) timeout: 180 # Per-command timeout in seconds lifetime_seconds: 300 # Idle-reaper window; also feeds 2× orphan-reaper threshold ``` `docker_env` vs `docker_forward_env`: the former injects literal `KEY=value` pairs you specify in the config (the values live in your `config.yaml` or are passed as a JSON dict via `TERMINAL_DOCKER_ENV='{"DEBUG":"1"}'`). The latter forwards values from your shell or `~/.hermes/.env`, so the actual secret never appears in the config file. Use `docker_forward_env` for tokens and `docker_env` for static knobs the container needs. `terminal.docker_extra_args` (also overridable via `TERMINAL_DOCKER_EXTRA_ARGS='["--gpus=all"]'`) lets you pass arbitrary `docker run` flags that Hermes doesn't surface as first-class keys — `--gpus`, `--network`, `--add-host`, alternative `--security-opt` overrides, etc. Each entry must be a string; the list is appended last to the assembled `docker run` invocation so it can override Hermes' defaults if needed. Use sparingly — flags that conflict with the sandbox hardening (capability drops, `--user`, the workspace bind mount) will silently weaken isolation. Requirements: Docker Desktop or Docker Engine installed and running. Hermes probes `$ PATH `plus common macOS install locations (`/usr/local/bin/docker`,` /opt/homebrew/bin/docker`, Docker Desktop app bundle). Podman is supported out of the box: set` HERMES_DOCKER_BINARY=podman`(or the full path) to force it when both are installed. #### Container lifecycle Every Hermes-managed container is tagged with three labels so subsequent processes (and the orphan reaper) can identify it: -`hermes-agent=1`— marks it as Hermes-managed -`hermes-task-id=`— keys the per-task reuse probe -`hermes-profile=`— scopes reuse and reaping to the active Hermes profile On startup, Hermes runs`docker ps –filter label=hermes-task-id= –filter label=hermes-profile=`and attaches to the existing container when it finds one. If the container is`exited`(e.g. after a Docker daemon restart), it's`docker start`'d and reused — filesystem state and any installed packages survive, but in-container background processes do not. When a Hermes process exits —` /quit`, closing a TUI session, gateway shutdown, even SIGKILL — the cleanup path is a no-op for the container in default mode. The container keeps running. The next Hermes process attaches to it in milliseconds via the label probe. This is the behavior the "one long-lived container shared across sessions" contract requires: it's the only way background processes (npm watchers, dev servers, long-running pytest) survive across sessions. The container is only torn down (stopped and` docker rm -f`'d) in these cases: | Trigger | When it fires | |---|---| |` docker_persist_across_processes: false`| Explicit per-process isolation. Every`cleanup()`does`stop`+`rm -f`. Matches pre-issue-#20561 behavior. | | Idle reaper (`lifetime_seconds`, default 300s) | Only when the env is` persist_across_processes=false`. Persist-mode envs are no-op'd; container survives the idle sweep. | | Orphan reaper at next startup | Sweeps Exited hermes-labeled containers older than` 2 × lifetime_seconds`(default 600s = 10 min), scoped to the current profile. Running containers are never touched — sibling-process safety. Set`docker_orphan_reaper: false`to disable. | | Direct user action |`docker rm -f`,` docker system prune`, Docker Desktop restart. We don't set` –restart=always`, so a host reboot leaves the container` Exited`(its CoW layer survives and gets reused on next startup, but bg processes are gone). | Edge cases worth knowing: - OOM kill of in-container PID 1 transitions the container to`Exited`. Next reuse will` docker start`it; filesystem state survives, bg processes do not. - Switching profiles isolates containers from each other — a container labeled`hermes-profile=work`is invisible to a Hermes process running under`hermes-profile=research`. The orphan reaper is profile-scoped too, so cross-profile containers don't get reaped accidentally, but they also won't get cleaned up automatically until you start Hermes again under their original profile. Parallel subagents spawned via` delegate_task(tasks=[…])`share this one container — concurrent`cd`, env mutations, and writes to the same path will collide. If a subagent needs an isolated sandbox, it must register a per-task image override via` register_task_env_overrides()`, which RL and benchmark environments (TerminalBench2, HermesSweEnv, etc.) do automatically for their per-task Docker images. Security hardening: -` –cap-drop ALL`with only`DAC_OVERRIDE`,` CHOWN`,` FOWNER`added back -`–security-opt no-new-privileges`-`–pids-limit 256`- Size-limited tmpfs for`/tmp`(512MB),`/var/tmp`(256MB),`/run`(64MB) Credential forwarding: Env vars listed in`docker_forward_env`are resolved from your shell environment first, then`/.hermes/.env`. Skills can also declare` required_environment_variables`which are merged automatically. #### Environment variable overrides Every key under`terminal:`has an env-var override of the form`TERMINAL_<KEY_UPPERCASE>`. The most useful ones for the Docker backend: | Env var | Maps to | Notes | |---|---|---| |` TERMINAL_DOCKER_IMAGE`|`docker_image`| Base image | |`TERMINAL_DOCKER_FORWARD_ENV`|`docker_forward_env`| JSON array:`‘[“GITHUB_TOKEN”,“OPENAI_API_KEY”]’`| |`TERMINAL_DOCKER_ENV`|`docker_env`| JSON dict:`‘{“DEBUG”:“1”}’`| |`TERMINAL_DOCKER_VOLUMES`|`docker_volumes`| JSON array of`“host:container[:ro]”`strings | |`TERMINAL_DOCKER_EXTRA_ARGS`|`docker_extra_args`| JSON array | |`TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE`|`docker_mount_cwd_to_workspace`|`true`/`false`| |`TERMINAL_DOCKER_RUN_AS_HOST_USER`|`docker_run_as_host_user`|`true`/`false`| |`TERMINAL_DOCKER_PERSIST_ACROSS_PROCESSES`|`docker_persist_across_processes`|`true`/`false`— default`true`| |`TERMINAL_DOCKER_ORPHAN_REAPER`|`docker_orphan_reaper`|`true`/`false`— default`true`| |`TERMINAL_CONTAINER_CPU`|`container_cpu`| CPU cores | |`TERMINAL_CONTAINER_MEMORY`|`container_memory`| MB | |`TERMINAL_CONTAINER_DISK`|`container_disk`| MB | |`TERMINAL_CONTAINER_PERSISTENT`|`container_persistent`|`true`/`false`— controls the bind-mount workspace dirs, distinct from`docker_persist_across_processes`| |`TERMINAL_LIFETIME_SECONDS`|`lifetime_seconds`| Idle reaper window | |`TERMINAL_TIMEOUT`|`timeout`| Per-command timeout | |`HERMES_DOCKER_BINARY| _none_ | Force a specific docker/podman binary path | ### SSH Backend Runs commands on a remote server over SSH. Uses ControlMaster for connection reuse (5-minute idle keepalive). Persistent shell is enabled by default — state (cwd, env vars) survives across commands. ```yaml terminal: backend: ssh persistent_shell: true # Keep a long-lived bash session (default: true) ``` Required environment variables: ```bash TERMINAL_SSH_HOST=my-server.example.com TERMINAL_SSH_USER=ubuntu ``` Optional: | Variable | Default | Description | |----------|---------|-------------| |TERMINAL_SSH_PORT`|`22`| SSH port | |`TERMINAL_SSH_KEY`| (system default) | Path to SSH private key | |`TERMINAL_SSH_PERSISTENT`|`true`| Enable persistent shell | How it works: Connects at init time with`BatchMode=yes`and`StrictHostKeyChecking=accept-new`. Persistent shell keeps a single` bash -l`process alive on the remote host, communicating via temporary files. Commands that need`stdin_data`or`sudoautomatically fall back to one-shot mode. ### Modal Backend Runs commands in a [Modal](https://modal.com) cloud sandbox. Each task gets an isolated VM with configurable CPU, memory, and disk. Filesystem can be snapshot/restored across sessions. ```yaml terminal: backend: modal container_cpu: 1 # CPU cores container_memory: 5120 # MB (5GB) container_disk: 51200 # MB (50GB) container_persistent: true # Snapshot/restore filesystem ``` Required: EitherMODAL_TOKEN_ID`+`MODAL_TOKEN_SECRET`environment variables, or a`/.modal.toml`config file. Persistence: When enabled, the sandbox filesystem is snapshotted on cleanup and restored on next session. Snapshots are tracked in`/.hermes/modal_snapshots.json`. This preserves filesystem state, not live processes, PID space, or background jobs. Credential files: Automatically mounted from` /.hermes/(OAuth tokens, etc.) and synced before each command. ### Daytona Backend Runs commands in a [Daytona](https://daytona.io) managed workspace. Supports stop/resume for persistence. ```yaml terminal: backend: daytona container_cpu: 1 # CPU cores container_memory: 5120 # MB → converted to GiB container_disk: 10240 # MB → converted to GiB (max 10 GiB) container_persistent: true # Stop/resume instead of delete ``` Required:DAYTONA_API_KEY`environment variable. Persistence: When enabled, sandboxes are stopped (not deleted) on cleanup and resumed on next session. Sandbox names follow the pattern`hermes-{task_id}. Disk limit: Daytona enforces a 10 GiB maximum. Requests above this are capped with a warning. ### Singularity/Apptainer Backend Runs commands in a [Singularity/Apptainer](https://apptainer.org) container. Designed for HPC clusters and shared machines where Docker isn't available. ```yaml terminal: backend: singularity singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20" container_cpu: 1 # CPU cores container_memory: 5120 # MB container_persistent: true # Writable overlay persists across sessions ``` Requirements: apptainer`or`singularity`binary in` $PATH`. Image handling: Docker URLs (`docker://...`) are automatically converted to SIF files and cached. Existing `.sif` files are used directly. Scratch directory: Resolved in order: `TERMINAL_SCRATCH_DIR` \to `TERMINAL_SANDBOX_DIR/singularity` \to `/scratch/$ USER/hermes-agent`(HPC convention) →`/.hermes/sandboxes/singularity`. Isolation: Uses` –containall –no-home`for full namespace isolation without mounting the host home directory. ### Common Terminal Backend Issues If terminal commands fail immediately or the terminal tool is reported as disabled: - Local — No special requirements. The safest default when getting started. - Docker — Run`docker version`to verify Docker is working. If it fails, fix Docker or`hermes config set terminal.backend local`. - SSH — Both` TERMINAL_SSH_HOST`and`TERMINAL_SSH_USER`must be set. Hermes logs a clear error if either is missing. - Modal — Needs`MODAL_TOKEN_ID`env var or`/.modal.toml`. Run` hermes doctor`to check. - Daytona — Needs`DAYTONA_API_KEY`. The Daytona SDK handles server URL configuration. - Singularity — Needs` apptainer`or`singularity`in`$PATH`. Common on HPC clusters. When in doubt, set` terminal.backend`back to`local`and verify that commands run there first. ### Remote-to-Host File Sync on Teardown For the SSH, Modal, and Daytona backends (anywhere the agent's working tree lives on a different machine than the host running Hermes), Hermes tracks files the agent touched inside the remote sandbox and, on session teardown / sandbox cleanup, syncs the modified files back to the host under`/.hermes/cache/remote-syncs//`. - Triggers on: session close,` /new`,` /reset`, gateway message timeout,` delegate_task`subagent completion when the child used a remote backend. - Covers the whole tree the agent modified, not just files it explicitly opened. Additions, edits, and deletions are all captured. - The remote sandbox may have been torn down by the time you go looking; the local`/.hermes/cache/remote-syncs/…`copy is the authoritative record of what the agent changed. - Large binary outputs (model checkpoints, raw datasets) are capped by size — the sync skips files over`file_sync_max_mb`(default`100). Bump that if you expect bigger artifacts to come back. ```yaml terminal: file_sync_max_mb: 100 # default — sync files up to 100 MB each file_sync_enabled: true # default — set false to skip the sync entirely ``` This is how you recover results from ephemeral cloud sandboxes that get destroyed after the session ends, without having to tell the agent to explicitly scp`or`modal volume put`every artifact. ### Docker Volume Mounts When using the Docker backend,`docker_volumes`lets you share host directories with the container. Each entry uses standard Docker`-v`syntax:`host_path:container_path[:options]. ```yaml terminal: backend: docker docker_volumes: - "/home/user/projects:/workspace/projects" # Read-write (default) - "/home/user/datasets:/data:ro" # Read-only - "/home/user/.hermes/cache/documents:/output" # Gateway-visible exports ``` This is useful for: - Providing files to the agent (datasets, configs, reference code) - Receiving files from the agent (generated code, reports, exports) - Shared workspaces where both you and the agent access the same files If you use a messaging gateway and want the agent to send generated files via MEDIA:/…`, prefer a dedicated host-visible export mount such as` /home/user/.hermes/cache/documents:/output`. - Write files inside Docker to` /output/…`- Emit the host path in`MEDIA:`, for example:` MEDIA:/home/user/.hermes/cache/documents/report.txt`- Do not emit`/workspace/…`or`/output/…`unless that exact path also exists for the gateway process on the host :::warning YAML duplicate keys silently override earlier ones. If you already have a`docker_volumes:`block, merge new mounts into the same list instead of adding another`docker_volumes:`key later in the file. ::: Can also be set via environment variable:`TERMINAL_DOCKER_VOLUMES=‘[“/host:/container”]’`(JSON array). ### Docker Credential Forwarding By default, Docker terminal sessions do not inherit arbitrary host credentials. If you need a specific token inside the container, add it to`terminal.docker_forward_env. ```yaml terminal: backend: docker docker_forward_env: - "GITHUB_TOKEN" - "NPM_TOKEN" ``` Hermes resolves each listed variable from your current shell first, then falls back to /.hermes/.env`if it was saved with`hermes config set`. :::warning Anything listed in` docker_forward_env`becomes visible to commands run inside the container. Only forward credentials you are comfortable exposing to the terminal session. ::: ### Running the Container as Your Host User By default Docker containers run as`root`(UID 0). Files created inside`/workspace`or other bind-mounts end up owned by root on the host, so after a session you have to`sudo chown`them before you can edit them from your host editor. The`terminal.docker_run_as_host_userflag fixes this: ```yaml terminal: backend: docker docker_run_as_host_user: true # default: false ``` When enabled, Hermes appends–user $(id -u):$ (id -g)`to the`docker run `command so files written into bind-mounted directories (`/workspace`,` /root`, anything in` docker_volumes`) are owned by your host user, not root. The trade-off: the container can no longer` apt install`or write to root-owned paths like`/root/.npm`— use a base image whose`HOME`is owned by a non-root user (or add your required tooling at image build time) if you need both. Leave this`false`(the default) for backwards-compatible behavior. Turn it on when your workflow is mostly "edit mounted host files" and you're tired of`sudo chown -R`. ### Optional: Mount the Launch Directory into` /workspace`Docker sandboxes stay isolated by default. Hermes does not pass your current host working directory into the container unless you explicitly opt in. Enable it in`config.yaml: ```yaml terminal: backend: docker docker_mount_cwd_to_workspace: true ``` When enabled: - if you launch Hermes from /projects/my-app`, that host directory is bind-mounted to` /workspace`- the Docker backend starts in`/workspace`- file tools and terminal commands both see the same mounted project When disabled,`/workspace`stays sandbox-owned unless you explicitly mount something via`docker_volumes`. Security tradeoff: -` false`preserves the sandbox boundary -`true`gives the sandbox direct access to the directory you launched Hermes from Use the opt-in only when you intentionally want the container to work on live host files. ### Persistent Shell By default, each terminal command runs in its own subprocess — working directory, environment variables, and shell variables reset between commands. When persistent shell is enabled, a single long-lived bash process is kept alive across`execute() calls so that state survives between commands. This is most useful for the SSH backend, where it also eliminates per-command connection overhead. Persistent shell is enabled by default for SSH and disabled for the local backend. ```yaml terminal: persistent_shell: true # default — enables persistent shell for SSH ``` To disable: ```bash hermes config set terminal.persistent_shell false ``` What persists across commands: - Working directory (cd /tmp `sticks for the next command) - Exported environment variables (`export FOO=bar`) - Shell variables (`MY_VAR=hello`) Precedence: | Level | Variable | Default | |-------|----------|---------| | Config |` terminal.persistent_shell`|`true`| | SSH override |`TERMINAL_SSH_PERSISTENT`| follows config | | Local override |`TERMINAL_LOCAL_PERSISTENT`|`false| Per-backend environment variables take highest precedence. If you want persistent shell on the local backend too: ```bash export TERMINAL_LOCAL_PERSISTENT=true ``` :::note Commands that requirestdin_data`or sudo automatically fall back to one-shot mode, since the persistent shell's stdin is already occupied by the IPC protocol. ::: See [Code Execution](features/code-execution.md) and the [Terminal section of the README](features/tools.md) for details on each backend. ## Skill Settings Skills can declare their own configuration settings via their SKILL.md frontmatter. These are non-secret values (paths, preferences, domain settings) stored under the`skills.config`namespace in`config.yaml. ```yaml skills: config: myplugin: path: ~/myplugin-data # Example — each skill defines its own keys ``` How skill settings work: - hermes config migrate`scans all enabled skills, finds unconfigured settings, and offers to prompt you -`hermes config showdisplays all skill settings under "Skill Settings" with the skill they belong to - When a skill loads, its resolved config values are injected into the skill context automatically Setting values manually: ```bash hermes config set skills.config.myplugin.path ~/myplugin-data ``` For details on declaring config settings in your own skills, see [Creating Skills — Config Settings](/developer-guide/creating-skills#config-settings-configyaml). ### Guard on agent-created skill writes When the agent usesskill_manage`to create, edit, patch, or delete a skill, Hermes can optionally scan the new/updated content for dangerous keyword patterns (credential harvesting, obvious prompt injection, exfil instructions). The scanner is off by default — real agent workflows that legitimately touch`/.ssh/`or mention`$OPENAI_API_KEYwere tripping the heuristic too often. Turn it back on if you want the scanner to prompt you before the agent's skill writes land: ```yaml skills: guard_agent_created: true # default: false ``` When on, any flaggedskill_managewrite surfaces as an approval prompt with the scanner's rationale. Accepted writes land; denied writes return an explanatory error to the agent. ## Memory Configuration ```yaml memory: memory_enabled: true user_profile_enabled: true memory_char_limit: 2200 # ~800 tokens user_char_limit: 1375 # ~500 tokens ``` ## File Read Safety Controls how much content a singleread_file`call can return. Reads that exceed the limit are rejected with an error telling the agent to use`offset`and`limit for a smaller range. This prevents a single read of a minified JS bundle or large data file from flooding the context window. ```yaml file_read_max_chars: 100000 # default — ~25-35K tokens ``` Raise it if you're on a model with a large context window and frequently read big files. Lower it for small-context models to keep reads efficient: ```yaml # Large context model (200K+) file_read_max_chars: 200000 # Small local model (16K context) file_read_max_chars: 30000 ``` The agent also deduplicates file reads automatically — if the same file region is read twice and the file hasn't changed, a lightweight stub is returned instead of re-sending the content. This resets on context compression so the agent can re-read files after their content is summarized away. ## Tool Output Truncation Limits Three related caps control how much raw output a tool can return before Hermes truncates it: ```yaml tool_output: max_bytes: 50000 # terminal output cap (chars) max_lines: 2000 # read_file pagination cap max_line_length: 2000 # per-line cap in read_file's line-numbered view ``` - max_bytes` — When a` terminal`command produces more than this many characters of combined stdout/stderr, Hermes keeps the first 40% and last 60% and inserts a`[OUTPUT TRUNCATED]`notice between them. Default`50000 `(≈12-15K tokens across typical tokenisers). - `max_lines` — Upper bound on the` limit`parameter of a single`read_file`call. Requests above this are clamped so a single read can't flood the context window. Default`2000`. - `max_line_length` — Per-line cap applied when` read_file`emits the line-numbered view. Lines longer than this are truncated to this many chars followed by`… [truncated]`. Default` 2000. Raise the limits on models with large context windows that can afford more raw output per call. Lower them for small-context models to keep tool results compact: ```yaml # Large context model (200K+) tool_output: max_bytes: 150000 max_lines: 5000 # Small local model (16K context) tool_output: max_bytes: 20000 max_lines: 500 ``` ## Global Toolset Disable To suppress specific toolsets across the CLI and every gateway platform in one place, list their names under agent.disabled_toolsets: ```yaml agent: disabled_toolsets: - memory # hide memory tools + MEMORY_GUIDANCE injection - web # no web_search / web_extract anywhere ``` This applies after per-platform tool config (platform_toolsets`written by`hermes tools`), so a toolset listed here is always removed — even if a platform's saved config still lists it. Use this when you want a single switch for "turn X off everywhere" rather than editing 15+ platform rows in the` hermes toolsUI. Leaving the list empty, or omitting the key, is a no-op. ## Git Worktree Isolation Enable isolated git worktrees for running multiple agents in parallel on the same repo: ```yaml worktree: true # Always create a worktree (same as hermes -w) # worktree: false # Default — only when -w flag is passed ``` When enabled, each CLI session creates a fresh worktree under.worktrees/`with its own branch. Agents can edit files, commit, push, and create PRs without interfering with each other. Clean worktrees are removed on exit; dirty ones are kept for manual recovery. You can also list gitignored files to copy into worktrees via`.worktreeincludein your repo root: ``` # .worktreeinclude .env .venv/ node_modules/ ``` ## Context Compression Hermes automatically compresses long conversations to stay within your model's context window. The compression summarizer is a separate LLM call — you can point it at any provider or endpoint. All compression settings live inconfig.yaml(no environment variables). ### Full reference ```yaml compression: enabled: true # Toggle compression on/off threshold: 0.50 # Compress at this % of context limit target_ratio: 0.20 # Fraction of threshold to preserve as recent tail protect_last_n: 20 # Min recent messages to keep uncompressed protect_first_n: 3 # Non-system head messages pinned across compactions (0 = pin nothing) hygiene_hard_message_limit: 400 # Gateway safety valve — see below # The summarization model/provider is configured under auxiliary: auxiliary: compression: model: "" # Empty = use main chat model. Override with e.g. "google/gemini-3-flash-preview" for cheaper/faster compression. provider: "auto" # Provider: "auto", "openrouter", "nous", "codex", "main", etc. base_url: null # Custom OpenAI-compatible endpoint (overrides provider) ``` :::info Legacy config migration Older configs withcompression.summary_model`,` compression.summary_provider`, and` compression.summary_base_url`are automatically migrated to`auxiliary.compression.`on first load (config version 17). No manual action needed. :::`hygiene_hard_message_limit`is a gateway-only pre-compression safety valve. Runaway sessions with thousands of messages can hit model context limits before the normal percent-of-context threshold fires; when message count crosses this ceiling, Hermes forces compression regardless of token usage. Default`400`— raise it for platforms where very long sessions are normal, lower it to force more aggressive compression. Editing this value on a running gateway takes effect on the next message (see below).`protect_first_n`controls how many non-system head messages are pinned across every compaction. Default`3`— the opening user/assistant exchange survives every summarizer pass so the original goal stays visible. On long-running rolling-compaction sessions where the opening turn is no longer relevant, set`protect_first_n: 0`to pin nothing but the system prompt + summary + tail. The system prompt itself is always preserved regardless of this setting. :::tip Gateway hot-reload of compression and context length As of recent releases, editing`model.context_length`or any`compression.`key in`config.yaml`on a running gateway takes effect on the next message — no gateway restart, no`/reset, no session rotation required. The cached-agent signature includes these keys, so the gateway transparently rebuilds the agent when it sees a change. API keys and tool/skill config still require the usual reload paths. ::: ### Common setups Default (auto-detect) — no configuration needed: ```yaml compression: enabled: true threshold: 0.50 ``` Uses your main provider and main model. Override per-task (e.g. auxiliary.compression.provider: openrouter`+`model: google/gemini-2.5-flash) if you want compression on a cheaper model than your main chat model. Force a specific provider (OAuth or API-key based): ```yaml auxiliary: compression: provider: nous model: gemini-3-flash ``` Works with any provider: nous`,` openrouter`,` codex`,` anthropic`,` main, etc. Custom endpoint (self-hosted, Ollama, zai, DeepSeek, etc.): ```yaml auxiliary: compression: model: glm-4.7 base_url: https://api.z.ai/api/coding/paas/v4 ``` Points at a custom OpenAI-compatible endpoint. Uses OPENAI_API_KEY`for auth. ### How the three knobs interact |`auxiliary.compression.provider`|`auxiliary.compression.base_url`| Result | |---------------------|---------------------|--------| |`auto`(default) | not set | Auto-detect best available provider | |`nous`/`openrouter/ etc. | not set | Force that provider, use its auth | | any | set | Use the custom endpoint directly (provider ignored) | :::warning Summary model context length requirement The summary model must have a context window at least as large as your main agent model's. The compressor sends the full middle section of the conversation to the summary model — if that model's context window is smaller than the main model's, the summarization call will fail with a context length error. When this happens, the middle turns are dropped without a summary, losing conversation context silently. If you override the model, verify its context length meets or exceeds your main model's. ::: ## Context Engine The context engine controls how conversations are managed when approaching the model's token limit. The built-incompressorengine uses lossy summarization (see [Context Compression](/developer-guide/context-compression-and-caching)). Plugin engines can replace it with alternative strategies. ```yaml context: engine: "compressor" # default — built-in lossy summarization ``` To use a plugin engine (e.g., LCM for lossless context management): ```yaml context: engine: "lcm" # must match the plugin's name ``` Plugin engines are never auto-activated — you must explicitly setcontext.engine`to the plugin name. Available engines can be browsed and selected via`hermes plugins→ Provider Plugins → Context Engine. See [Memory Providers](/user-guide/features/memory-providers) for the analogous single-select system for memory plugins. ## Iteration Budget Pressure When the agent is working on a complex task with many tool calls, it can burn through its iteration budget (default: 90 turns) without realizing it's running low. Budget pressure automatically warns the model as it approaches the limit: | Threshold | Level | What the model sees | |-----------|-------|---------------------| | 70% | Caution |[BUDGET: 63/90. 27 iterations left. Start consolidating.]`| | 90% | Warning |`[BUDGET WARNING: 81/90. Only 9 left. Respond NOW.]`| Warnings are injected into the last tool result's JSON (as a`_budget_warningfield) rather than as separate messages — this preserves prompt caching and doesn't disrupt the conversation structure. ```yaml agent: max_turns: 90 # Max iterations per conversation turn (default: 90) api_max_retries: 3 # Retries per provider before fallback engages (default: 3) ``` Budget pressure is enabled by default. The agent sees warnings naturally as part of tool results, encouraging it to consolidate its work and deliver a response before running out of iterations. When the iteration budget is fully exhausted, the CLI shows a notification to the user:⚠ Iteration budget reached (90/90) — response may be incomplete`. If the budget runs out during active work, the agent generates a summary of what was accomplished before stopping.` agent.api_max_retries`controls how many times Hermes retries a provider API call on transient errors (rate limits, connection drops, 5xx) before fallback-provider switching engages. The default is`3`— four attempts total. If you have [fallback providers](/user-guide/features/fallback-providers) configured and want to fail over faster, drop this to`0so the first transient error on your primary immediately hands off to the fallback instead of churning retries against the flaky endpoint. ### API Timeouts Hermes has separate timeout layers for streaming, plus a stale detector for non-streaming calls. The stale detectors auto-adjust for local providers only when you leave them at their implicit defaults. | Timeout | Default | Local providers | Config / env | |---------|---------|----------------|--------------| | Socket read timeout | 120s | Auto-raised to 1800s |HERMES_STREAM_READ_TIMEOUT`| | Stale stream detection | 180s | Auto-disabled |`HERMES_STREAM_STALE_TIMEOUT`| | Stale non-stream detection | 300s | Auto-disabled when left implicit |`providers..stale_timeout_seconds`or`HERMES_API_CALL_STALE_TIMEOUT`| | API call (non-streaming) | 1800s | Unchanged |`providers..request_timeout_seconds`/`timeout_seconds`or`HERMES_API_TIMEOUT`| The socket read timeout controls how long httpx waits for the next chunk of data from the provider. Local LLMs can take minutes for prefill on large contexts before producing the first token, so Hermes raises this to 30 minutes when it detects a local endpoint. If you explicitly set`HERMES_STREAM_READ_TIMEOUT`, that value is always used regardless of endpoint detection. The stale stream detection kills connections that receive SSE keep-alive pings but no actual content. This is disabled entirely for local providers since they don't send keep-alive pings during prefill. The stale non-stream detection kills non-streaming calls that produce no response for too long. By default Hermes disables this on local endpoints to avoid false positives during long prefills. If you explicitly set` providers..stale_timeout_seconds`,` providers..models..stale_timeout_seconds`, or` HERMES_API_CALL_STALE_TIMEOUT, that explicit value is honored even on local endpoints. ## Context Pressure Warnings Separate from iteration budget pressure, context pressure tracks how close the conversation is to the compaction threshold — the point where context compression fires to summarize older messages. This helps both you and the agent understand when the conversation is getting long. | Progress | Level | What happens | |----------|-------|-------------| | ≥ 60% to threshold | Info | CLI shows a cyan progress bar; gateway sends an informational notice | | ≥ 85% to threshold | Warning | CLI shows a bold yellow bar; gateway warns compaction is imminent | In the CLI, context pressure appears as a progress bar in the tool output feed: ``` ◐ context ████████████░░░░░░░░ 62% to compaction 48k threshold (50%) · approaching compaction ``` On messaging platforms, a plain-text notification is sent: ``` ◐ Context: ████████████░░░░░░░░ 62% to compaction (threshold: 50% of window). ``` If auto-compression is disabled, the warning tells you context may be truncated instead. Context pressure is automatic — no configuration needed. It fires purely as a user-facing notification and does not modify the message stream or inject anything into the model's context. ## Credential Pool Strategies When you have multiple API keys or OAuth tokens for the same provider, configure the rotation strategy: ```yaml credential_pool_strategies: openrouter: round_robin # cycle through keys evenly anthropic: least_used # always pick the least-used key ``` Options: fill_first`(default),`round_robin`,` least_used`,` random`. See [Credential Pools](/user-guide/features/credential-pools) for full documentation. ## Prompt caching Hermes turns on cross-session prompt caching automatically when the active provider supports it — no user config needed. For Claude on native Anthropic, OpenRouter, and Nous Portal, Hermes attaches` cache_control `breakpoints with the 1-hour TTL (`ttl: “1h”`) on the system prompt and skill blocks. The first send within a fresh hour pays full input rates; subsequent sends across any session within the same hour pull from the cache at the discounted cached-read rate. This means the system prompt, loaded skill content, and the early portion of any long-context include get reused across` hermes sessions and across forked subagents for the first hour. The Qwen Cloud (Alibaba DashScope) upstream caps cache TTL at 5 minutes, so Hermes uses the 5-minute breakpoint TTL there instead. Other Claude-via-third-party paths (AWS Bedrock, Azure Foundry) fall back to the provider's own caching defaults. xAI Grok uses a separate session-pinned conversation-id mechanism — see [xAI prompt caching](/integrations/providers#xai-grok--responses-api--prompt-caching). No knob exists to disable this — caching is always-on and saves money even on single-turn conversations because the system prompt alone is a meaningful fraction of the input token count. ## Auxiliary Models Hermes uses "auxiliary" models for side tasks like image analysis, web page summarization, browser screenshot analysis, session-title generation, and context compression. By default (auxiliary..provider: “auto”`), Hermes routes every auxiliary task to your main chat model — the same provider/model you picked in` hermes model`. You don't need to configure anything to get started, but be aware that on expensive reasoning models (Opus, MiniMax M2.7, etc.) auxiliary tasks add meaningful cost. If you want cheap-and-fast side tasks regardless of your main model, set` auxiliary..provider`and`auxiliary..model`explicitly (for example, Gemini Flash on OpenRouter for vision and web extraction). :::note Why "auto" uses your main model Earlier builds split aggregator users (OpenRouter, Nous Portal) onto a cheap provider-side default. That was surprising — users who paid for an aggregator subscription would see a different model handling their auxiliary traffic.`auto`now uses the main model for everyone, and per-task overrides in`config.yaml`still win (see [Full auxiliary config reference](#full-auxiliary-config-reference) below). ::: ### Configuring auxiliary models interactively Instead of hand-editing YAML, run`hermes modeland pick "Configure auxiliary models" from the menu. You'll get an interactive per-task picker: ``` $ hermes model → Configure auxiliary models [ ] vision currently: auto / main model [ ] web_extract currently: auto / main model [ ] title_generation currently: openrouter / google/gemini-3-flash-preview [ ] compression currently: auto / main model [ ] approval currently: auto / main model [ ] triage_specifier currently: auto / main model [ ] kanban_decomposer currently: auto / main model [ ] profile_describer currently: auto / main model ``` Select a task, pick a provider (OAuth flows open a browser; API-key providers prompt), pick a model. The change persists toauxiliary..`in`config.yaml. Same machinery as the main-model picker — no extra syntax to learn. ### Video Tutorial <div style={{position: 'relative', width: '100%', aspectRatio: '16 / 9', marginBottom: '1.5rem'}}> <iframe src="https://www.youtube.com/embed/NoF-YajElIM" title="Hermes Agent — Auxiliary Models Tutorial" style={{position: 'absolute', top: 0, left: 0, width: '100%', height: '100%', border: 0}} allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowFullScreen /> </div> ### The universal config pattern Every model slot in Hermes — auxiliary tasks, compression, fallback — uses the same three knobs: | Key | What it does | Default | |-----|-------------|---------| | provider`| Which provider to use for auth and routing |`“auto”`| |`model`| Which model to request | provider's default | |`base_url`| Custom OpenAI-compatible endpoint (overrides provider) | not set | When`base_url`is set, Hermes ignores the provider and calls that endpoint directly (using`api_key`or`OPENAI_API_KEY`for auth). When only`provider`is set, Hermes uses that provider's built-in auth and base URL. Available providers for auxiliary tasks:`auto`,` main`, plus any provider in the [provider registry](/reference/environment-variables) —` openrouter`,` nous`,` openai-codex`,` copilot`,` copilot-acp`,` anthropic`,` gemini`,` google-gemini-cli`,` qwen-oauth`,` zai`,` kimi-coding`,` kimi-coding-cn`,` minimax`,` minimax-cn`,` minimax-oauth`,` deepseek`,` nvidia`,` xai`,` xai-oauth`,` ollama-cloud`,` alibaba`,` bedrock`,` huggingface`,` arcee`,` xiaomi`,` kilocode`,` opencode-zen`,` opencode-go`,` azure-foundry`— or any named custom provider from your`custom_providers`list (e.g.`provider: “beans”`). :::tip MiniMax OAuth` minimax-oauth`logs in via browser OAuth (no API key needed). Run`hermes model`and select MiniMax (OAuth) to authenticate. Auxiliary tasks use`MiniMax-M2.7-highspeed`automatically. See the [MiniMax OAuth guide](../guides/minimax-oauth.md). ::: :::tip xAI Grok OAuth`xai-oauth`logs in via browser OAuth for SuperGrok and X Premium+ subscribers (no API key needed). Run`hermes model`and select xAI Grok OAuth (SuperGrok / Premium+) to authenticate. The same OAuth token is reused for every direct-to-xAI surface (chat, auxiliary tasks, TTS, image gen, video gen, transcription). See the [xAI Grok OAuth guide](../guides/xai-grok-oauth.md), and if Hermes is on a remote host see [OAuth over SSH / Remote Hosts](../guides/oauth-over-ssh.md). ::: :::warning`“main”`is for auxiliary tasks only The`“main”`provider option means "use whatever provider my main agent uses" — it's only valid inside`auxiliary:`,` compression:`, and primary fallback entries (`fallback_providers:`or legacy`fallback_model:`). It is not a valid value for your top-level` model.provider`setting. If you use a custom OpenAI-compatible endpoint, set`provider: custom`in your`model:section. See [AI Providers](/integrations/providers) for all main model provider options. ::: ### Full auxiliary config reference ```yaml auxiliary: # Image analysis (vision_analyze tool + browser screenshots) vision: provider: "auto" # "auto", "openrouter", "nous", "codex", "main", etc. model: "" # e.g. "openai/gpt-4o", "google/gemini-2.5-flash" base_url: "" # Custom OpenAI-compatible endpoint (overrides provider) api_key: "" # API key for base_url (falls back to OPENAI_API_KEY) timeout: 120 # seconds — LLM API call timeout; vision payloads need generous timeout download_timeout: 30 # seconds — image HTTP download; increase for slow connections # Web page summarization + browser page text extraction web_extract: provider: "auto" model: "" # e.g. "google/gemini-2.5-flash" base_url: "" api_key: "" timeout: 360 # seconds (6min) — per-attempt LLM summarization # Dangerous command approval classifier approval: provider: "auto" model: "" base_url: "" api_key: "" timeout: 30 # seconds # Context compression timeout (separate from compression.* config) compression: timeout: 120 # seconds — compression summarizes long conversations, needs more time # Skills hub — skill matching and search skills_hub: provider: "auto" model: "" base_url: "" api_key: "" timeout: 30 # MCP tool dispatch mcp: provider: "auto" model: "" base_url: "" api_key: "" timeout: 30 # Kanban triage specifier —hermes kanban specify `(or the # dashboard's ✨ Specify button on Triage-column cards) uses this # slot to expand a one-liner into a concrete spec and promote the # task to`todo. Cheap fast models work well here; spec expansion # is short and doesn't need reasoning depth. triage_specifier: provider: "auto" model: "" base_url: "" api_key: "" timeout: 120 ``` :::tip Each auxiliary task has a configurable timeout`(in seconds). Defaults: vision 120s, web_extract 360s, approval 30s, compression 120s. Increase these if you use slow local models for auxiliary tasks. Vision also has a separate`download_timeout`(default 30s) for the HTTP image download — increase this for slow connections or self-hosted image servers. ::: :::info Context compression has its own`compression:`block for thresholds and an`auxiliary.compression:`block for model/provider settings — see [Context Compression](#context-compression) above. The primary fallback chain uses a top-level`fallback_providers:`list — see [Fallback Providers](/integrations/providers#fallback-providers). All three follow the same provider/model/base_url pattern. ::: ### OpenRouter routing & Pareto Code for auxiliary tasks When an auxiliary task resolves to OpenRouter (either explicitly or via`provider: “main”`while your main agent is on OpenRouter), the main agent's`provider_routing`and`openrouter.min_coding_score`settings do not propagate — by design, each auxiliary task is independent. To set OpenRouter provider preferences or use the [Pareto Code router](/integrations/providers#openrouter-pareto-code-router) for a specific aux task, set them per-task via`extra_body: ```yaml auxiliary: compression: provider: openrouter model: openrouter/pareto-code # use the Pareto Code router for this task extra_body: provider: # OpenRouter provider routing prefs order: [anthropic, google] # try these providers in order sort: throughput # or "price" | "latency" # only: [anthropic] # restrict to a specific provider # ignore: [deepinfra] # exclude specific providers plugins: # OpenRouter Pareto Code router knob - id: pareto-router min_coding_score: 0.5 # 0.0–1.0; higher = stronger coders ``` The shape mirrors what OpenRouter accepts in the chat completions request body. Hermes forwards the entire extra_bodyverbatim, so any other OpenRouter request-body field documented at [openrouter.ai/docs](https://openrouter.ai/docs) works the same way. ### Changing the Vision Model To use GPT-4o instead of Gemini Flash for image analysis: ```yaml auxiliary: vision: model: "openai/gpt-4o" ``` Or via environment variable (in/.hermes/.env): ```bash AUXILIARY_VISION_MODEL=openai/gpt-4o ``` ### Provider Options These options apply to auxiliary task configs (auxiliary:`,` compression:`) and primary fallback entries (`fallback_providers:`or legacy`fallback_model:`), not to your main` model.provider`setting. | Provider | Description | Requirements | |----------|-------------|-------------| |`“auto”`| Best available (default). Vision tries OpenRouter → Nous → Codex. | — | |`“openrouter”`| Force OpenRouter — routes to any model (Gemini, GPT-4o, Claude, etc.) |`OPENROUTER_API_KEY`| |`“nous”`| Force Nous Portal |`hermes auth`| |`“codex”`| Force Codex OAuth (ChatGPT account). Supports vision (gpt-5.3-codex). |`hermes model`→ Codex | |`“minimax-oauth”`| Force MiniMax OAuth (browser login, no API key). Uses MiniMax-M2.7-highspeed for auxiliary tasks. |`hermes model`→ MiniMax (OAuth) | |`“xai-oauth”`| Force xAI Grok OAuth (browser login for SuperGrok or X Premium+ subscribers, no API key). Same OAuth token covers chat, TTS, image, video, and transcription. |`hermes model`→ xAI Grok OAuth (SuperGrok / Premium+) | |`“main”`| Use your active custom/main endpoint. This can come from`OPENAI_BASE_URL`+`OPENAI_API_KEY`or from a custom endpoint saved via`hermes model`/`config.yaml`. Works with OpenAI, local models, or any OpenAI-compatible API. Auxiliary tasks only — not valid for` model.provider`. | Custom endpoint credentials + base URL | Direct API-key providers from the main provider catalog also work here when you want side tasks to bypass your default router.` gmi`is valid once`GMI_API_KEYis configured: ```yaml auxiliary: compression: provider: "gmi" model: "anthropic/claude-opus-4.6" ``` For GMI auxiliary routing, use the exact model ID returned by GMI's/v1/models`endpoint. ### Common Setups Using a direct custom endpoint (clearer than`provider: “main”for local/self-hosted APIs): ```yaml auxiliary: vision: base_url: "http://localhost:1234/v1" api_key: "local-key" model: "qwen2.5-vl" ```base_url`takes precedence over`provider`, so this is the most explicit way to route an auxiliary task to a specific endpoint. For direct endpoint overrides, Hermes uses the configured` api_key`or falls back to`OPENAI_API_KEY`; it does not reuse` OPENROUTER_API_KEYfor that custom endpoint. Using OpenAI API key for vision: ```yaml # In ~/.hermes/.env: # OPENAI_BASE_URL=https://api.openai.com/v1 # OPENAI_API_KEY=sk-... auxiliary: vision: provider: "main" model: "gpt-4o" # or "gpt-4o-mini" for cheaper ``` Using OpenRouter for vision (route to any model): ```yaml auxiliary: vision: provider: "openrouter" model: "openai/gpt-4o" # or "google/gemini-2.5-flash", etc. ``` Using Codex OAuth (ChatGPT Pro/Plus account — no API key needed): ```yaml auxiliary: vision: provider: "codex" # uses your ChatGPT OAuth token # model defaults to gpt-5.3-codex (supports vision) ``` Using MiniMax OAuth (browser login, no API key needed): ```yaml model: default: MiniMax-M2.7 provider: minimax-oauth base_url: https://api.minimax.io/anthropic ``` Runhermes model`and select MiniMax (OAuth) to log in and set this automatically. For the China region, the base URL will be`https://api.minimaxi.com/anthropic. See the [MiniMax OAuth guide](../guides/minimax-oauth.md) for the full walkthrough. Using a local/self-hosted model: ```yaml auxiliary: vision: provider: "main" # uses your active custom endpoint model: "my-local-model" ``` provider: “main”`uses whatever provider Hermes uses for normal chat — whether that's a named custom provider (e.g.`beans`), a built-in provider like` openrouter`, or a legacy` OPENAI_BASE_URL`endpoint. :::tip If you use Codex OAuth as your main model provider, vision works automatically — no extra configuration needed. Codex is included in the auto-detection chain for vision. ::: :::warning Vision requires a multimodal model. If you set`provider: “main”`, make sure your endpoint supports multimodal/vision — otherwise image analysis will fail. ::: ### Environment Variables (legacy) Auxiliary models can also be configured via environment variables. However,` config.yaml`is the preferred method — it's easier to manage and supports all options including`base_url`and`api_key`. | Setting | Environment Variable | |---------|---------------------| | Vision provider |` AUXILIARY_VISION_PROVIDER`| | Vision model |`AUXILIARY_VISION_MODEL`| | Vision endpoint |`AUXILIARY_VISION_BASE_URL`| | Vision API key |`AUXILIARY_VISION_API_KEY`| | Web extract provider |`AUXILIARY_WEB_EXTRACT_PROVIDER`| | Web extract model |`AUXILIARY_WEB_EXTRACT_MODEL`| | Web extract endpoint |`AUXILIARY_WEB_EXTRACT_BASE_URL`| | Web extract API key |`AUXILIARY_WEB_EXTRACT_API_KEY`| Compression and fallback model settings are config.yaml-only. :::tip Run`hermes configto see your current auxiliary model settings. Overrides only show up when they differ from the defaults. ::: ## Reasoning Effort Control how much "thinking" the model does before responding: ```yaml agent: reasoning_effort: "" # empty = medium (default). Options: none, minimal, low, medium, high, xhigh (max) ``` When unset (default), reasoning effort defaults to "medium" — a balanced level that works well for most tasks. Setting a value overrides it — higher reasoning effort gives better results on complex tasks at the cost of more tokens and latency. You can also change the reasoning effort at runtime with the/reasoningcommand: ``` /reasoning # Show current effort level and display state /reasoning high # Set reasoning effort to high /reasoning none # Disable reasoning /reasoning show # Show model thinking above each response /reasoning hide # Hide model thinking ``` ## Tool-Use Enforcement Some models occasionally describe intended actions as text instead of making tool calls ("I would run the tests..." instead of actually calling the terminal). Tool-use enforcement injects system prompt guidance that steers the model back to actually calling tools. ```yaml agent: tool_use_enforcement: "auto" # "auto" | true | false | ["model-substring", ...] ``` | Value | Behavior | |-------|----------| |“auto”`(default) | Enabled for models matching:`gpt`,` codex`,` gemini`,` gemma`,` grok`. Disabled for all others (Claude, DeepSeek, Qwen, etc.). | |` true`| Always enabled, regardless of model. Useful if you notice your current model describing actions instead of performing them. | |`false`| Always disabled, regardless of model. | |`[“gpt”, “codex”, “qwen”, “llama”]| Enabled only when the model name contains one of the listed substrings (case-insensitive). | ### What it injects When enabled, three layers of guidance may be added to the system prompt: 1. General tool-use enforcement (all matched models) — instructs the model to make tool calls immediately instead of describing intentions, keep working until the task is complete, and never end a turn with a promise of future action. 2. OpenAI execution discipline (GPT and Codex models only) — additional guidance addressing GPT-specific failure modes: abandoning work on partial results, skipping prerequisite lookups, hallucinating instead of using tools, and declaring "done" without verification. 3. Google operational guidance (Gemini and Gemma models only) — conciseness, absolute paths, parallel tool calls, and verify-before-edit patterns. These are transparent to the user and only affect the system prompt. Models that already use tools reliably (like Claude) don't need this guidance, which is why“auto”`excludes them. ### When to turn it on If you're using a model not in the default auto list and notice it frequently describes what it would do instead of doing it, set`tool_use_enforcement: trueor add the model substring to the list: ```yaml agent: tool_use_enforcement: ["gpt", "codex", "gemini", "grok", "my-custom-model"] ``` ## TTS Configuration ```yaml tts: provider: "edge" # "edge" | "elevenlabs" | "openai" | "minimax" | "mistral" | "gemini" | "xai" | "neutts" speed: 1.0 # Global speed multiplier (fallback for all providers) edge: voice: "en-US-AriaNeural" # 322 voices, 74 languages speed: 1.0 # Speed multiplier (converted to rate percentage, e.g. 1.5 → +50%) elevenlabs: voice_id: "pNInz6obpgDQGcFmaJgB" model_id: "eleven_multilingual_v2" openai: model: "gpt-4o-mini-tts" voice: "alloy" # alloy, echo, fable, onyx, nova, shimmer speed: 1.0 # Speed multiplier (clamped to 0.25–4.0 by the API) base_url: "https://api.openai.com/v1" # Override for OpenAI-compatible TTS endpoints minimax: speed: 1.0 # Speech speed multiplier # base_url: "" # Optional: override for OpenAI-compatible TTS endpoints mistral: model: "voxtral-mini-tts-2603" voice_id: "c69964a6-ab8b-4f8a-9465-ec0925096ec8" # Paul - Neutral (default) gemini: model: "gemini-2.5-flash-preview-tts" # or gemini-2.5-pro-preview-tts voice: "Kore" # 30 prebuilt voices: Zephyr, Puck, Kore, Enceladus, etc. xai: voice_id: "eve" # xAI TTS voice language: "en" # ISO 639-1 sample_rate: 24000 bit_rate: 128000 # MP3 bitrate # base_url: "https://api.x.ai/v1" neutts: ref_audio: '' ref_text: '' model: neuphonic/neutts-air-q4-gguf device: cpu ``` This controls both thetext_to_speech `tool and spoken replies in voice mode (`/voice tts`in the CLI or messaging gateway). Speed fallback hierarchy: provider-specific speed (e.g.`tts.edge.speed`) → global` tts.speed`→`1.0`default. Set the global`tts.speedto apply a uniform speed across all providers, or override per-provider for fine-grained control. ## Display Settings ```yaml display: tool_progress: all # off | new | all | verbose tool_progress_command: false # Enable /verbose slash command in messaging gateway platforms: {} # Per-platform display overrides (see below) tool_progress_overrides: {} # DEPRECATED — use display.platforms instead interim_assistant_messages: true # Gateway: send natural mid-turn assistant updates as separate messages skin: default # Built-in or custom CLI skin (see user-guide/features/skins) personality: "kawaii" # Legacy cosmetic field still surfaced in some summaries compact: false # Compact output mode (less whitespace) resume_display: full # full (show previous messages on resume) | minimal (one-liner only) bell_on_complete: false # Play terminal bell when agent finishes (great for long tasks) show_reasoning: false # Show model reasoning/thinking above each response (toggle with /reasoning show|hide) streaming: false # Stream tokens to terminal as they arrive (real-time output) show_cost: false # Show estimated $ cost in the CLI status bar timestamps: false # When true, prefixes user and assistant labels with [HH:MM] timestamps in the CLI / TUI transcript tool_preview_length: 0 # Max chars for tool call previews (0 = no limit, show full paths/commands) runtime_footer: # Gateway: append a runtime-context footer to final replies enabled: false fields: ["model", "context_pct", "cwd"] file_mutation_verifier: true # Append an advisory footer when write_file/patch calls failed this turn language: en # UI language for static messages (approval prompts, some gateway replies). en | zh | zh-hant | ja | de | es | fr | tr | uk | af | ko | it | ga | pt | ru | hu ``` ### File-mutation verifier Whendisplay.file_mutation_verifier`is`true`(default), Hermes appends a one-line advisory to the assistant's final response whenever a`write_file`or`patch`call failed during the turn and was never superseded by a successful write to the same path. This catches the "batch of parallel patches, half silently fail, model summarises success" class of over-claim without requiring you to manually run`git statusafter every edit. Example footer: ``` ⚠️ File-mutation verifier: 3 file(s) were NOT modified this turn despite any wording above that may suggest otherwise. Rungit status`or`read_fileto confirm. • concepts/automatic-organization.md — [patch] Could not find match for old_string • concepts/lora.md — [patch] Could not find match for old_string • concepts/rag-pipeline.md — [patch] Could not find match for old_string ``` Setfile_mutation_verifier: false`(or`HERMES_FILE_MUTATION_VERIFIER=0`) to suppress the footer. The verifier only fires when real failures are outstanding at turn end — a model that retries a failed patch and succeeds within the same turn will not trigger it for that file. ### UI language for static messages The` display.language`setting translates a small set of static user-facing messages — the CLI approval prompt, a handful of gateway slash-command replies (e.g. restart-drain notices, "approval expired", "goal cleared"). It does not translate agent responses, log lines, tool output, error tracebacks, or slash-command descriptions — those stay in English. If you want the agent itself to reply in another language, just tell it in your prompt or system message. Supported values:`en`(default),`zh`(Simplified Chinese),`zh-hant`(Traditional Chinese),`ja`(Japanese),`de`(German),`es`(Spanish),`fr`(French),`tr`(Turkish),`uk`(Ukrainian),`af`(Afrikaans),`ko`(Korean),`it`(Italian),`ga`(Irish),`pt`(Portuguese),`ru`(Russian),`hu`(Hungarian). Unknown values fall back to English. You can also set this per-session with the`HERMES_LANGUAGEenv var, which overrides the config value. ```yaml display: language: zh # CLI approval prompts appear in Chinese ``` | Mode | What you see | |------|-------------| |off`| Silent — just the final response | |`new`| Tool indicator only when the tool changes | |`all`| Every tool call with a short preview (default) | |`verbose`| Full args, results, and debug logs | In the CLI, cycle through these modes with`/verbose`. To use` /verbose`in messaging platforms (Telegram, Discord, Slack, etc.), set`tool_progress_command: true`in the`display`section above. The command will then cycle the mode and save to config. Tool progress requires a gateway adapter that can display progress updates safely. Platforms without message editing support, including Signal, suppress tool-progress bubbles even if`/verbose `saves a non-`off`mode. ### Runtime-metadata footer (gateway only) When`display.runtime_footer.enabled: true, Hermes appends a small runtime-context footer to the final message of each gateway turn. The current footer can show the model, context-window percentage, and current working directory. Off by default; opt in per-gateway if your team wants every reply to include this provenance. ```yaml display: runtime_footer: enabled: true fields: ["model", "context_pct", "cwd"] # supported fields: model, context_pct, cwd ``` The /footerslash command toggles this at runtime in any session. Example footer appended to a Telegram/Discord/Slack reply: ``` — claude-opus-4.7 · 12 tool calls · 2m 14s · $0.042 ``` Only the final message of a turn gets the footer; interim updates stay clean. ### Per-platform progress overrides Different platforms have different verbosity needs. Usedisplay.platformsto set per-platform modes: ```yaml display: tool_progress: all # global default platforms: signal: tool_progress: 'off' # Signal cannot currently display tool-progress bubbles telegram: tool_progress: verbose # detailed progress on Telegram slack: tool_progress: 'off' # quiet in shared Slack workspace ``` Platforms without an override fall back to the globaltool_progress`value. Valid platform keys:`telegram`,` discord`,` slack`,` signal`,` whatsapp`,` matrix`,` mattermost`,` email`,` sms`,` homeassistant`,` dingtalk`,` feishu`,` wecom`,` weixin`,` bluebubbles`,` qqbot`. The legacy` display.tool_progress_overrides`key still loads for backward compatibility but is deprecated and migrated into`display.platforms`on first load. Signal is listed as a valid platform key because the setting can be saved per platform, but the current Signal adapter cannot edit sent messages and does not render tool-progress bubbles. Keep Signal`tool_progress`set to`off`; use the CLI or an editing-capable messaging platform if you need to watch each tool call live.` interim_assistant_messages`is gateway-only. When enabled, Hermes sends completed mid-turn assistant updates as separate chat messages. This is independent from`tool_progressand does not require gateway streaming. ## Privacy ```yaml privacy: redact_pii: false # Strip PII from LLM context (gateway only) ``` Whenredact_pii`is`true`, the gateway redacts personally identifiable information from the system prompt before sending it to the LLM on supported platforms: | Field | Treatment | |-------|-----------| | Phone numbers (user ID on WhatsApp/Signal) | Hashed to` user_<12-char-sha256>`| | User IDs | Hashed to`user_<12-char-sha256> `| | Chat IDs | Numeric portion hashed, platform prefix preserved (`telegram:`) | | Home channel IDs | Numeric portion hashed | | User names / usernames | Not affected (user-chosen, publicly visible) | Platform support: Redaction applies to WhatsApp, Signal, and Telegram. Discord and Slack are excluded because their mention systems (`<@user_id>) require the real ID in the LLM context. Hashes are deterministic — the same user always maps to the same hash, so the model can still distinguish between users in group chats. Routing and delivery use the original values internally. ## Speech-to-Text (STT) ```yaml stt: provider: "local" # "local" | "groq" | "openai" | "mistral" local: model: "base" # tiny, base, small, medium, large-v3 openai: model: "whisper-1" # whisper-1 | gpt-4o-mini-transcribe | gpt-4o-transcribe # model: "whisper-1" # Legacy fallback key still respected ``` Provider behavior: - local`uses`faster-whisper`running on your machine. Install it separately with`pip install faster-whisper`. -` groq`uses Groq's Whisper-compatible endpoint and reads`GROQ_API_KEY`. -` openai`uses the OpenAI speech API and reads`VOICE_TOOLS_OPENAI_KEY`. If the requested provider is unavailable, Hermes falls back automatically in this order:` local`→`groq`→`openai. Groq and OpenAI model overrides are environment-driven: ```bash STT_GROQ_MODEL=whisper-large-v3-turbo STT_OPENAI_MODEL=whisper-1 GROQ_BASE_URL=https://api.groq.com/openai/v1 STT_OPENAI_BASE_URL=https://api.openai.com/v1 ``` ## Voice Mode (CLI) ```yaml voice: record_key: "ctrl+b" # Push-to-talk key inside the CLI max_recording_seconds: 120 # Hard stop for long recordings auto_tts: false # Enable spoken replies automatically when /voice on beep_enabled: true # Play record start/stop beeps in CLI voice mode silence_threshold: 200 # RMS threshold for speech detection silence_duration: 3.0 # Seconds of silence before auto-stop ``` Use /voice on`in the CLI to enable microphone mode,`record_key`to start/stop recording, and`/voice ttsto toggle spoken replies. See [Voice Mode](/user-guide/features/voice-mode) for end-to-end setup and platform-specific behavior. ## Streaming Stream tokens to the terminal or messaging platforms as they arrive, instead of waiting for the full response. ### CLI Streaming ```yaml display: streaming: true # Stream tokens to terminal in real-time show_reasoning: true # Also stream reasoning/thinking tokens (optional) ``` When enabled, responses appear token-by-token inside a streaming box. Tool calls are still captured silently. If the provider doesn't support streaming, it falls back to the normal display automatically. ### Gateway Streaming (Telegram, Discord, Slack) ```yaml streaming: enabled: true # Enable progressive message editing transport: edit # "edit" (progressive message editing) or "off" edit_interval: 0.3 # Seconds between message edits buffer_threshold: 40 # Characters before forcing an edit flush cursor: " ▉" # Cursor shown during streaming fresh_final_after_seconds: 60 # Send fresh final (Telegram) when preview is this old; 0 = always edit in place ``` When enabled, the bot sends a message on the first token, then progressively edits it as more tokens arrive. Platforms that don't support message editing (Signal, Email, Home Assistant) are auto-detected on the first attempt — streaming is gracefully disabled for that session with no flood of messages. For separate natural mid-turn assistant updates without progressive token editing, setdisplay.interim_assistant_messages: true`. Overflow handling: If the streamed text exceeds the platform's message length limit (~4096 chars), the current message is finalized and a new one starts automatically. Fresh final (Telegram): Telegram's` editMessageText`preserves the original message timestamp, so a long-running streamed reply would keep the first-token timestamp even after completion. When`fresh_final_after_seconds > 0`(default`60`), the completed reply is delivered as a brand-new message (with the stale preview best-effort deleted) so Telegram's visible timestamp reflects completion time. Short previews still finalize in place. Set to` 0`to always edit in place. :::note Per-platform streaming defaults The master`streaming.enabled`switch is`false`by default — nothing streams until you flip it. Once enabled, streaming is decided per platform: Telegram ships with`display.platforms.telegram.streaming: true`(streams) and Discord with`display.platforms.discord.streaming: false`(does not). So after enabling streaming, Telegram streams out of the box and Discord stays on whole-message replies until you change its toggle. You can adjust these per-platform switches from the dashboard's Channels toggles or directly in`/.hermes/config.yaml. ::: ## Group Chat Session Isolation Limit how many chat sessions can actively be open across CLI, TUI/dashboard, and messaging gateway: ```yaml max_concurrent_sessions: null # null/0 = unlimited; positive integer = active session cap ``` When the cap is reached, Hermes returns a direct limit message for new sessions. Existing active sessions keep their normal behavior. The canonical key is top-level max_concurrent_sessions`. Hermes also accepts` gateway.max_concurrent_sessions`as a fallback, but the top-level key wins when both are set. The cap is enforced with a local runtime lease file and is best-effort: Hermes fails open if the registry cannot be read or locked so users are not stranded. It is intended for a single host/profile runtime, not a shared`$HERMES_HOMEmounted across multiple machines. Control whether shared chats keep one conversation per room or one conversation per participant: ```yaml group_sessions_per_user: true # true = per-user isolation in groups/channels, false = one shared session per chat ``` -true`is the default and recommended setting. In Discord channels, Telegram groups, Slack channels, and similar shared contexts, each sender gets their own session when the platform provides a user ID. -`false`reverts to the old shared-room behavior. That can be useful if you explicitly want Hermes to treat a channel like one collaborative conversation, but it also means users share context, token costs, and interrupt state. - Direct messages are unaffected. Hermes still keys DMs by chat/DM ID as usual. - Threads stay isolated from their parent channel either way; with`true, each participant also gets their own session inside the thread. For the behavior details and examples, see [Sessions](/user-guide/sessions) and the [Discord guide](/user-guide/messaging/discord). ## Unauthorized DM Behavior Control what Hermes does when an unknown user sends a direct message: ```yaml unauthorized_dm_behavior: pair whatsapp: unauthorized_dm_behavior: ignore ``` - pair`is the default. Hermes denies access, but replies with a one-time pairing code in DMs. -`ignoresilently drops unauthorized DMs. - Platform sections override the global default, so you can keep pairing enabled broadly while making one platform quieter. ## Quick Commands Define custom commands that either run shell commands without invoking the LLM, or alias one slash command to another. Exec quick commands are zero-token and useful from messaging platforms (Telegram, Discord, etc.) for quick server checks or utility scripts. ```yaml quick_commands: status: type: exec command: systemctl status hermes-agent disk: type: exec command: df -h / update: type: exec command: cd ~/.hermes/hermes-agent && git pull && pip install -e . gpu: type: exec command: nvidia-smi --query-gpu=name,utilization.gpu,memory.used,memory.total --format=csv,noheader restart: type: alias target: /gateway restart ``` Usage: type/status`,` /disk`,` /update`,` /gpu`, or` /restart`in the CLI or any messaging platform.`exec`commands run locally on the host and return the output directly — no LLM call, no tokens consumed.`alias`commands rewrite to the configured slash command target. - 30-second timeout — long-running commands are killed with an error message - Priority — quick commands are checked before skill commands, so you can override skill names - Autocomplete — quick commands are resolved at dispatch time and are not shown in the built-in slash-command autocomplete tables - Type — supported types are`exec`and`alias; other types show an error - Works everywhere — CLI, Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant String-only prompt shortcuts are not valid quick commands. For reusable prompt workflows, create a skill or alias to an existing slash command. ## Human Delay Simulate human-like response pacing in messaging platforms: ```yaml human_delay: mode: "off" # off | natural | custom min_ms: 800 # Minimum delay (custom mode) max_ms: 2500 # Maximum delay (custom mode) ``` ## Code Execution Configure the execute_code tool: ```yaml code_execution: mode: project # project (default) | strict timeout: 300 # Max execution time in seconds max_tool_calls: 50 # Max tool calls within code execution ``` mode` controls the working directory and Python interpreter for scripts: - `project` (default) — scripts run in the session's working directory with the active virtualenv/conda env's python. Project deps (`pandas`,` torch`, project packages) and relative paths (`.env`,` ./data.csv`) resolve naturally, matching what` terminal() `sees. - `strict` — scripts run in a temp staging directory with` sys.executable`(Hermes's own python). Maximum reproducibility, but project deps and relative paths won't resolve. Environment scrubbing (strips`_API_KEY`,` _TOKEN`,` _SECRET`,` _PASSWORD`,` _CREDENTIAL`,` _PASSWD`,` _AUTH`) and the tool whitelist apply identically in both modes — switching mode does not change the security posture. ## Web Search Backends The` web_search`and`web_extract`tools support five backend providers. Configure the backend in`config.yaml`or via`hermes tools: ```yaml web: backend: firecrawl # firecrawl | searxng | parallel | tavily | exa # Or use per-capability keys to mix providers (e.g. free search + paid extract): search_backend: "searxng" extract_backend: "firecrawl" ``` | Backend | Env Var | Search | Extract | |---------|---------|--------|---------| | Firecrawl (default) | FIRECRAWL_API_KEY`| ✔ | ✔ | | SearXNG |`SEARXNG_URL`| ✔ | — | | Parallel |`PARALLEL_API_KEY`| ✔ | ✔ | | Tavily |`TAVILY_API_KEY`| ✔ | ✔ | | Exa |`EXA_API_KEY`| ✔ | ✔ | Backend selection: If`web.backend`is not set, the backend is auto-detected from available API keys. If only`SEARXNG_URL`is set, SearXNG is used. If only`EXA_API_KEY`is set, Exa is used. If only`TAVILY_API_KEY`is set, Tavily is used. If only`PARALLEL_API_KEY`is set, Parallel is used. Otherwise Firecrawl is the default. SearXNG is a free, self-hosted, privacy-respecting metasearch engine that queries 70+ search engines. No API key needed — just set`SEARXNG_URL`to your instance (e.g.,`http://localhost:8080`). SearXNG is search-only;` web_extract`requires a separate extract provider (set`web.extract_backend`). See the [Web Search setup guide](/user-guide/features/web-search) for Docker setup instructions. Self-hosted Firecrawl: Set` FIRECRAWL_API_URL`to point at your own instance. When a custom URL is set, the API key becomes optional (set`USE_DB_AUTHENTICATION= on the server to disable auth). Parallel search modes: Set `PARALLEL_SEARCH_MODE` to control search behavior — `fast`, `one-shot`, or `agentic` (default: `agentic`). Exa: Set `EXA_API_KEY` in `~/.hermes/.env`. Supports `category` filtering (`company`, `research paper`, `news`, `people`, `personal site`, `pdf`) and domain/date filters. ## Browser Configure browser automation behavior: yaml browser: inactivity_timeout: 120 # Seconds before auto-closing idle sessions command_timeout: 30 # Timeout in seconds for browser commands (screenshot, navigate, etc.) record_sessions: false # Auto-record browser sessions as WebM videos to ~/.hermes/browser_recordings/ # Optional CDP override — when set, Hermes attaches directly to your own # Chromium-family browser (via /browser connect) rather than starting a headless browser. cdp_url: "" # Dialog supervisor — controls how native JS dialogs (alert / confirm / prompt) # are handled when a CDP backend is attached (Browserbase, local Chromium-family # browser via /browser connect). Ignored on Camofox and default local agent-browser mode. dialog_policy: must_respond # must_respond | auto_dismiss | auto_accept dialog_timeout_s: 300 # Safety auto-dismiss under must_respond (seconds) camofox: managed_persistence: false # When true, Camofox sessions persist cookies/logins across restarts user_id: "" # Optional externally managed Camofox userId session_key: "" # Optional session key sent when Hermes creates a tab adopt_existing_tab: false # Reuse an existing tab for this identity before creating one Dialog policies: - `must_respond` (default) — capture the dialog, surface it in `browser_snapshot.pending_dialogs`, and wait for the agent to call `browser_dialog(action=...)`. After `dialog_timeout_s` seconds with no response, the dialog is auto-dismissed to prevent the page’s JS thread from stalling forever. - `auto_dismiss` — capture, dismiss immediately. The agent still sees the dialog record in `browser_snapshot.recent_dialogs` with `closed_by="auto_policy"` after the fact. - `auto_accept` — capture, accept immediately. Useful for pages with aggressive `beforeunload` prompts. See the browser feature page for the full dialog workflow. The browser toolset supports multiple providers. See the Browser feature page for details on Browserbase, Browser Use, and local Chromium-family CDP setup. ## Timezone Override the server-local timezone with an IANA timezone string. Affects timestamps in logs, cron scheduling, and system prompt time injection. `yaml timezone: "America/New_York" # IANA timezone (default: "" = server-local time)` Supported values: any IANA timezone identifier (e.g. `America/New_York`, `Europe/London`, `Asia/Kolkata`, `UTC`). Leave empty or omit for server-local time. ## Discord Configure Discord-specific behavior for the messaging gateway: `yaml discord: require_mention: true # Require @mention to respond in server channels free_response_channels: "" # Comma-separated channel IDs where bot responds without @mention auto_thread: true # Auto-create threads on @mention in channels` - `require_mention` — when `true` (default), the bot only responds in server channels when mentioned with `@BotName`. DMs always work without mention. - `free_response_channels` — comma-separated list of channel IDs where the bot responds to every message without requiring a mention. - `auto_thread` — when `true` (default), mentions in channels automatically create a thread for the conversation, keeping channels clean (similar to Slack threading). ## Security Pre-execution security scanning and secret redaction: `yaml security: redact_secrets: true # Redact API key patterns in tool output and logs (on by default) tirith_enabled: true # Enable Tirith security scanning for terminal commands tirith_path: "tirith" # Path to tirith binary (default: "tirith" in $PATH) tirith_timeout: 5 # Seconds to wait for tirith scan before timing out tirith_fail_open: true # Allow command execution if tirith is unavailable website_blocklist: # See Website Blocklist section below enabled: false domains: [] shared_files: []` - `redact_secrets` — when `true`, automatically detects and redacts patterns that look like API keys, tokens, and passwords in tool output before it enters the conversation context and logs. On by default**. Set to `false` explicitly only when you need raw credential-like strings for debugging or redactor development. - `tirith_enabled` — when `true`, terminal commands are scanned by Tirith before execution to detect potentially dangerous operations. - `tirith_path` — path to the tirith binary. Set this if tirith is installed in a non-standard location. - `tirith_timeout` — maximum seconds to wait for a tirith scan. Commands proceed if the scan times out. - `tirith_fail_open` — when `true` (default), commands are allowed to execute if tirith is unavailable or fails. Set to `false` to block commands when tirith cannot verify them. ## Website Blocklist Block specific domains from being accessed by the agent’s web and browser tools: `yaml security: website_blocklist: enabled: false # Enable URL blocking (default: false) domains: # List of blocked domain patterns - ".internal.company.com" - "admin.example.com" - ".local" shared_files: # Load additional rules from external files - "/etc/hermes/blocked-sites.txt"` When enabled, any URL matching a blocked domain pattern is rejected before the web or browser tool executes. This applies to `web_search`, `web_extract`, `browser_navigate`, and any tool that accesses URLs. Domain rules support: - Exact domains: `admin.example.com` - Wildcard subdomains: `.internal.company.com` (blocks all subdomains) - TLD wildcards: `.local` Shared files contain one domain rule per line (blank lines and `#` comments are ignored). Missing or unreadable files log a warning but don’t disable other web tools. The policy is cached for 30 seconds, so config changes take effect quickly without restart. ## Smart Approvals Control how Hermes handles potentially dangerous commands: `yaml approvals: mode: manual # manual | smart | off` | Mode | Behavior | |——|–––––| | `manual` (default) | Prompt the user before executing any flagged command. In the CLI, shows an interactive approval dialog. In messaging, queues a pending approval request. | | `smart` | Use an auxiliary LLM to assess whether a flagged command is actually dangerous. Low-risk commands are auto-approved with session-level persistence. Genuinely risky commands are escalated to the user. | | `off` | Skip all approval checks. Equivalent to `HERMES_YOLO_MODE=true`. Use with caution. | Smart mode is particularly useful for reducing approval fatigue — it lets the agent work more autonomously on safe operations while still catching genuinely destructive commands. :::warning Setting `approvals.mode: off` disables all safety checks for terminal commands. Only use this in trusted, sandboxed environments. ::: ## Checkpoints Automatic filesystem snapshots before destructive file operations. See the Checkpoints & Rollback for details. `yaml checkpoints: enabled: false # Enable automatic checkpoints (also: hermes chat --checkpoints). Default: false (opt-in). max_snapshots: 20 # Max checkpoints to keep per directory (default: 20)` ## Delegation Configure subagent behavior for the delegate tool: yaml delegation: # model: "google/gemini-3-flash-preview" # Override model (empty = inherit parent) # provider: "openrouter" # Override provider (empty = inherit parent) # base_url: "http://localhost:1234/v1" # Direct OpenAI-compatible endpoint (takes precedence over provider) # api_key: "local-key" # API key for base_url (falls back to OPENAI_API_KEY) # api_mode: "" # Wire protocol for base_url: "chat_completions", "codex_responses", or "anthropic_messages". Empty = auto-detect from URL (e.g. /anthropic suffix → anthropic_messages). Set explicitly for non-standard endpoints the heuristic can't detect. max_concurrent_children: 3 # Parallel children per batch (floor 1, no ceiling). Also via DELEGATION_MAX_CONCURRENT_CHILDREN env var. max_spawn_depth: 1 # Delegation tree depth cap (1-3, clamped). 1 = flat (default): parent spawns leaves that cannot delegate. 2 = orchestrator children can spawn leaf grandchildren. 3 = three levels. orchestrator_enabled: true # Global kill switch. When false, role="orchestrator" is ignored and every child is forced to leaf regardless of max_spawn_depth. Subagent provider:model override: By default, subagents inherit the parent agent’s provider and model. Set `delegation.provider` and `delegation.model` to route subagents to a different provider:model pair — e.g., use a cheap/fast model for narrowly-scoped subtasks while your primary agent runs an expensive reasoning model. Direct endpoint override: If you want the obvious custom-endpoint path, set `delegation.base_url`, `delegation.api_key`, and `delegation.model`. That sends subagents directly to that OpenAI-compatible endpoint and takes precedence over `delegation.provider`. If `delegation.api_key` is omitted, Hermes falls back to `OPENAI_API_KEY` only. Wire protocol (`api_mode`): Hermes auto-detects the wire protocol from `delegation.base_url` (e.g. paths ending in `/anthropic` → `anthropic_messages`; Codex / native Anthropic / Kimi-coding hostnames keep their existing detection). For endpoints the heuristic can’t classify — for example Azure AI Foundry, MiniMax, Zhipu GLM, or LiteLLM proxies fronting an Anthropic-shaped backend — set `delegation.api_mode` explicitly to one of `chat_completions`, `codex_responses`, or `anthropic_messages`. Leave it empty (the default) to keep auto-detection. The delegation provider uses the same credential resolution as CLI/gateway startup. All configured providers are supported: `openrouter`, `nous`, `copilot`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`. When a provider is set, the system automatically resolves the correct base URL, API key, and API mode — no manual credential wiring needed. Precedence: `delegation.base_url` in config → `delegation.provider` in config → parent provider (inherited). `delegation.model` in config → parent model (inherited). Setting just `model` without `provider` changes only the model name while keeping the parent’s credentials (useful for switching models within the same provider like OpenRouter). Width and depth: `max_concurrent_children` caps how many subagents run in parallel per batch (default `3`, floor of 1, no ceiling). Can also be set via the `DELEGATION_MAX_CONCURRENT_CHILDREN` env var. When the model submits a `tasks` array longer than the cap, `delegate_task` returns a tool error explaining the limit rather than silently truncating. `max_spawn_depth` controls the delegation tree depth (clamped to 1-3). At the default `1`, delegation is flat: children cannot spawn grandchildren, and passing `role="orchestrator"` silently degrades to `leaf`. Raise to `2` so orchestrator children can spawn leaf grandchildren; `3` for three-level trees. The agent opts into orchestration per call via `role="orchestrator"`; `orchestrator_enabled: false` forces every child back to leaf regardless. Cost scales multiplicatively — at `max_spawn_depth: 3` with `max_concurrent_children: 3`, the tree can reach 3×3×3 = 27 concurrent leaf agents. See Subagent Delegation → Depth Limit and Nested Orchestration for usage patterns. ## Clarify Configure the clarification prompt behavior: `yaml clarify: timeout: 120 # Seconds to wait for user clarification response` ## Context Files (SOUL.md, AGENTS.md) Hermes uses two different context scopes: | File | Purpose | Scope | |——|———|—––| | `SOUL.md` | Primary agent identity — defines who the agent is (slot #1 in the system prompt) | `~/.hermes/SOUL.md` or `$HERMES_HOME/SOUL.md` | | `.hermes.md` / `HERMES.md` | Project-specific instructions (highest priority) | Walks to git root | | `AGENTS.md` | Project-specific instructions, coding conventions | Recursive directory walk | | `CLAUDE.md` | Claude Code context files (also detected) | Working directory only | | `.cursorrules` | Cursor IDE rules (also detected) | Working directory only | | `.cursor/rules/.mdc` | Cursor rule files (also detected) | Working directory only | - SOUL.md is the agent’s primary identity. It occupies slot #1 in the system prompt, completely replacing the built-in default identity. Edit it to fully customize who the agent is. - If SOUL.md is missing, empty, or cannot be loaded, Hermes falls back to a built-in default identity. - Project context files use a priority system — only ONE type is loaded (first match wins): `.hermes.md` → `AGENTS.md` → `CLAUDE.md` → `.cursorrules`. SOUL.md is always loaded independently. - AGENTS.md is hierarchical: if subdirectories also have AGENTS.md, all are combined. - Hermes automatically seeds a default `SOUL.md` if one does not already exist. - All loaded context files are capped at 20,000 characters with smart truncation. See also: - Personality & SOUL.md - Context Files ## Working Directory | Context | Default | |———|———| | CLI (`hermes`) | Current directory where you run the command | | Messaging gateway | `terminal.cwd` from `~/.hermes/config.yaml`; if unset, home directory `~` | | Docker / Singularity / Modal / SSH | User’s home directory inside the container or remote machine | Override the working directory: `yaml # In ~/.hermes/config.yaml: terminal: cwd: /home/myuser/projects` `MESSAGING_CWD` and direct `TERMINAL_CWD` entries in `~/.hermes/.env` are legacy compatibility fallbacks. New configurations should use `terminal.cwd`. — # user-guide/configuring-models # Configuring Models Hermes uses two kinds of model slots: - Main model — what the agent thinks with. Every user message, every tool-call loop, every streamed response goes through this model. - Auxiliary models — smaller side-jobs the agent offloads. Context compression, vision (image analysis), web-page summarization, approval scoring, MCP tool routing, session-title generation, and skill search. Each has its own slot and can be overridden independently. This page covers configuring both from the dashboard. If you prefer config files or the CLI, jump to Alternative methods at the bottom. :::tip Fastest path: Nous Portal Nous Portal provides 300+ models under one subscription. On a fresh install, run `hermes setup --portal` to log in and set Nous as your provider in one command. Inspect what’s wired up with `hermes portal info`. - Portal subscribers also get 10% off token-billed providers. ::: :::note `model:` schema — empty string vs. mapping On a brand-new install the bundled default config has `model: ""` (an empty string sentinel meaning “not configured yet”). The first time you run `hermes setup` or `hermes model`, that key is upgraded in-place to a mapping with `provider`, `default`, `base_url`, and `api_mode` sub-keys — the shape shown throughout this page and in `profiles.md` / `configuration.md`. If you ever see an empty string in `config.yaml`, run `hermes model` (or click Change in the dashboard) and Hermes will write the dict form for you. ::: ## The Models page Open the dashboard and click Models in the sidebar. You get two sections: 1. Model Settings — the top panel, where you assign models to slots. 2. Usage analytics — ranked cards showing every model that ran a session in the selected period, with token counts, cost, and capability badges. The top card is the Model Settings panel. The main row always shows what the agent will spin up for new sessions. Click Change to open the picker. ## Setting the main model Click Change on the Main model row: The picker has two columns: - Left — authenticated providers. Only providers you’ve set up (API key set, OAuth’d, or defined as a custom endpoint) show up here. If a provider is missing, head to Keys and add its credential. - Right — the curated model list for the selected provider. These are the agentic models Hermes recommends for that provider, not the raw `/models` dump (which on OpenRouter includes 400+ models including TTS, image generators, and rerankers). Type in the filter box to narrow by provider name, slug, or model ID. Pick a model, hit Switch, and Hermes writes it to `~/.hermes/config.yaml` under the `model` section. This applies to new sessions only — any chat tab you already have open keeps running whatever model it started with. To hot-swap the current chat, use the `/model` slash command inside it. ## Setting auxiliary models Click Show auxiliary to reveal the 11 task slots: Every auxiliary task defaults to `auto` — meaning Hermes uses your main model for that job too. Override a specific task when you want a cheaper or faster model for a side-job. ### Common override patterns | Task | When to override | |—|—| | Title Gen | Almost always. A $0.10/M flash model writes session titles as well as Opus. Default config sets this to `google/gemini-3-flash-preview` on OpenRouter. | | Vision | When your main model lacks vision support. Point it at `google/gemini-2.5-flash` or `gpt-4o-mini`. | | Compression | When you’re burning reasoning tokens on Opus/M2.7 just to summarize context. A fast chat model does the job at 1/50th the cost. | | Approval | For `approval_mode: smart` — a fast/cheap model (haiku, flash, gpt-5-mini) decides whether to auto-approve low-risk commands. Expensive models here are waste. | | Web Extract | When you use `web_extract` heavily. Same logic as compression — summarization doesn’t need reasoning. | | Skills Hub | `hermes skills search` uses this. Usually fine at `auto`. | | MCP | MCP tool routing. Usually fine at `auto`. | | Triage Specifier | Routes the Kanban triage specifier (`hermes kanban specify`) that expands a rough one-liner into a concrete spec. A cheap, capable model works well. | | Kanban Decomposer | Routes Kanban task decomposition — splits a triage task into a graph of child tasks for specialist profiles. | | Profile Describer | Routes profile-description generation (`hermes profile describe --auto` / the dashboard auto-generate button). Short, cheap call. | | Curator | Routes the curator skill-usage review pass. Can run for minutes on reasoning models, so a cheaper aux model is often worthwhile. | ### Per-task override Click Change on any auxiliary row. Same picker opens, same behavior — pick provider + model, hit Switch. The row updates to show `provider · model` instead of `auto (use main model)`. ### Reset all to auto If you’ve over-tuned and want to start over, click Reset all to auto at the top of the auxiliary section. Every slot goes back to using your main model. ## The “Use as” shortcut Every model card on the page has a Use as dropdown. This is the fast path — pick a model you see in your analytics, click Use as, and assign it to the main slot or any specific auxiliary task in one click: The dropdown has: - Main model — same as clicking Change on the main row. - All auxiliary tasks — assigns this model to all 11 aux slots at once. Useful when you just want every side-job on a cheap flash model. - Individual task options — Vision, Web Extract, Compression, etc. The currently-assigned model for each task is marked `current`. Cards are badged with `main` or `aux · <task>` when they’re currently assigned to something — so you can see at a glance which of your historical models are wired in where. ## What gets written to `config.yaml` When you save via the dashboard, Hermes writes to `~/.hermes/config.yaml`: Main model: `yaml model: provider: openrouter default: anthropic/claude-opus-4.7 base_url: '' # cleared on provider switch api_mode: chat_completions` Auxiliary override (example — vision on gemini-flash): `yaml auxiliary: vision: provider: openrouter model: google/gemini-2.5-flash base_url: '' api_key: '' timeout: 120 extra_body: {} download_timeout: 30` Auxiliary on auto (default): `yaml auxiliary: compression: provider: auto model: '' base_url: '' # ... other fields unchanged` `provider: auto` with `model: ''` tells Hermes to use the main model for that task. ## When does it take effect? - CLI (`hermes chat`): next `hermes chat` invocation. - Gateway (Telegram, Discord, Slack, etc.): next new* session. Existing sessions keep their model. Restart the gateway (`hermes gateway restart`) if you want to force all sessions to pick up the change. - Dashboard chat tab (`/chat`): next new PTY. The currently-open chat keeps its model — use `/model` inside it to hot-swap. Changes never invalidate prompt caches on running sessions. That’s deliberate: swapping the main model inside a session requires a cache reset (the system prompt contains model-specific content), and we reserve that for the explicit `/model` slash command inside chat. ## Troubleshooting ### “No authenticated providers” in the picker Hermes lists a provider only if it has a working credential. Check Keys in the sidebar — you should see one of: an API key, a successful OAuth, or a custom endpoint URL. If the provider you want isn’t there, run `hermes setup` to wire it up, or go to Keys and add the env var. ### Main model didn’t change in my running chat Expected. The dashboard writes `config.yaml`, which new sessions read. The currently-open chat is a live agent process — it keeps whatever model it was spawned with. Use `/model <name>` inside the chat to hot-swap that specific session. ### Auxiliary override “didn’t take effect” Three things to check: 1. Did you start a new session? Existing chats don’t re-read config. 2. Is `provider` set to something other than `auto`? If the field shows `auto`, the task is still using your main model. Click Change and pick a real provider. 3. Is the provider authenticated? If you assigned `minimax` to a task but don’t have a MiniMax API key, that task falls back to the openrouter default and logs a warning in `agent.log`. ### I picked a model but Hermes switched providers on me On OpenRouter (or any aggregator), bare model names resolve within the aggregator first. So `claude-sonnet-4` on OpenRouter becomes `anthropic/claude-sonnet-4.6`, staying on your OpenRouter auth. But if you typed `claude-sonnet-4` on a native Anthropic auth, it would stay as `claude-sonnet-4-6`. If you see an unexpected provider switch, check that your current provider is what you expect — the picker always shows the current main at the top of the dialog. ## Alternative methods ### CLI slash command Inside any `hermes chat` session: `/model gpt-5.4 --provider openrouter # session-only /model gpt-5.4 --provider openrouter --global # also persists to config.yaml` `--global` does the same thing the dashboard’s Change button does, plus it switches the running session in-place. ### Custom aliases Define your own short names for models you reach for often, then use `/model <alias>` in the CLI or any messaging platform. There are two equivalent formats — pick whichever fits your workflow. Canonical (top-level `model_aliases:`) — full control over provider + base_url: `yaml # ~/.hermes/config.yaml model_aliases: fav: model: claude-sonnet-4.6 provider: anthropic grok: model: grok-4 provider: x-ai` Short string form (`model.aliases.<name>: provider/model`) — convenient from the shell because `hermes config set` only writes scalar values, but it can’t carry a custom `base_url`: `bash hermes config set model.aliases.fav anthropic/claude-opus-4.6 hermes config set model.aliases.grok x-ai/grok-4` Both paths feed the same loader (`hermes_cli/model_switch.py`). Entries declared in `model_aliases:` take precedence over `model.aliases:` entries with the same name. Then `/model fav` or `/model grok` in chat. User aliases shadow built-in short names (`sonnet`, `kimi`, `opus`, etc.). See Custom model aliases for the full reference. ### `hermes model` subcommand `bash hermes model # Interactive provider + model picker (the canonical way to switch defaults)` `hermes model` walks you through picking a provider, authenticating (OAuth flows open a browser; API-key providers prompt for the key), and then choosing a specific model from that provider’s curated catalog. The choice is written to `model.provider` and `model.model` in `~/.hermes/config.yaml`. To list providers/models without launching the picker, use the dashboard or the REST endpoints below. To inspect what the CLI will actually use right now: `hermes config show | grep '^model\.'` and `hermes status`. ### Direct config edit Edit `~/.hermes/config.yaml` and restart whatever reads it. See the Configuration reference for the full schema. ### REST API The dashboard uses three endpoints. Useful for scripting: bash # List authenticated providers + curated model lists curl -H "X-Hermes-Session-Token: $TOKEN" http://localhost:PORT/api/model/options # Read current main + auxiliary assignments curl -H "X-Hermes-Session-Token: $TOKEN" http://localhost:PORT/api/model/auxiliary # Set the main model curl -X POST -H "Content-Type: application/json" -H "X-Hermes-Session-Token: $TOKEN" \ -d '{"scope":"main","provider":"openrouter","model":"anthropic/claude-opus-4.7"}' \ http://localhost:PORT/api/model/set # Override a single auxiliary task curl -X POST -H "Content-Type: application/json" -H "X-Hermes-Session-Token: $TOKEN" \ -d '{"scope":"auxiliary","task":"vision","provider":"openrouter","model":"google/gemini-2.5-flash"}' \ http://localhost:PORT/api/model/set # Assign one model to every auxiliary task curl -X POST -H "Content-Type: application/json" -H "X-Hermes-Session-Token: $TOKEN" \ -d '{"scope":"auxiliary","task":"","provider":"openrouter","model":"google/gemini-2.5-flash"}' \ http://localhost:PORT/api/model/set # Reset all auxiliary tasks to auto curl -X POST -H "Content-Type: application/json" -H "X-Hermes-Session-Token: $TOKEN" \ -d '{"scope":"auxiliary","task":"reset","provider":"","model":""}' \ http://localhost:PORT/api/model/set The session token is injected into the dashboard HTML at startup and rotates on every server restart. Grab it from the browser devtools (`window.__HERMES_SESSION_TOKEN__`) if you’re scripting against a running dashboard. — # Sessions import useBaseUrl from ‘@docusaurus/useBaseUrl’; # Sessions Hermes Agent automatically saves every conversation as a session. Sessions enable conversation resume, cross-session search, and full conversation history management. ## How Sessions Work Every conversation — whether from the CLI, Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Teams, or any other messaging platform — is stored as a session with full message history. Sessions are tracked in: 1. SQLite database (`~/.hermes/state.db`) — structured session metadata with FTS5 full-text search, plus full message history The SQLite database stores: - Session ID, source platform, user ID - Session title (unique, human-readable name) - Model name and configuration - System prompt snapshot - Full message history (role, content, tool calls, tool results) - Token counts (input/output) - Timestamps (started_at, ended_at) - Parent session ID (for compression-triggered session splitting) ### What Counts Toward Context Hermes stores session history so it can resume conversations, but it does not keep re-sending every byte it has ever handled. On each turn, the model sees the selected system prompt, the current conversation window, and any content Hermes explicitly injects for that turn. Media attachments are handled as turn-scoped inputs: - Images may be attached natively to the next model call, or pre-analyzed into a text description when the active model does not support native vision. - Audio is transcribed into text when speech-to-text is configured. - Text documents can have their extracted text included; other document types are usually represented by a saved local path and a short note. - Attachment paths and extracted/derived text can appear in the transcript, but the raw image, audio, or binary file bytes are not repeatedly copied into future prompts. For example, if a user sends an image and asks Hermes to make a meme from it, Hermes may inspect that image once with vision and run an image-processing script. Future turns do not automatically carry the original JPEG in context. They carry only whatever was written into the conversation, such as the user’s request, a short image description, a local cache path, or the final assistant response. The most common cause of context growth is not the media file itself. It is verbose text: pasted transcripts, full logs, large tool outputs, long diffs, repeated status reports, and detailed proof dumps. Prefer summaries, file paths, focused excerpts, and tool-backed lookups over copying large artifacts into chat. :::tip Use `/compress` when a session gets long, `/new` for a fresh thread, and `hermes sessions prune` only when you want to delete old ended sessions from storage. Compression reduces the active context; it is not a privacy delete. Pass a name to `/new` (e.g. `/new payments-refactor`) to set the new session’s initial title up front — useful for finding it later with `/resume <name>` or in the `/sessions` picker. ::: ### Session Sources Each session is tagged with its source platform: | Source | Description | |––––|———––| | `cli` | Interactive CLI (`hermes` or `hermes chat`) | | `telegram` | Telegram messenger | | `discord` | Discord server/DM | | `slack` | Slack workspace | | `whatsapp` | WhatsApp messenger | | `signal` | Signal messenger | | `matrix` | Matrix rooms and DMs | | `mattermost` | Mattermost channels | | `email` | Email (IMAP/SMTP) | | `sms` | SMS via Twilio | | `dingtalk` | DingTalk messenger | | `feishu` | Feishu/Lark messenger | | `wecom` | WeCom (WeChat Work) | | `weixin` | Weixin (personal WeChat) | | `bluebubbles` | Apple iMessage via BlueBubbles macOS server | | `qqbot` | QQ Bot (Tencent QQ) via Official API v2 | | `homeassistant` | Home Assistant conversation | | `webhook` | Incoming webhooks | | `api-server` | API server requests | | `acp` | ACP editor integration | | `cron` | Scheduled cron jobs | | `batch` | Batch processing runs | ## CLI Session Resume Resume previous conversations from the CLI using `--continue` or `--resume`: ### Continue Last Session `bash # Resume the most recent CLI session hermes --continue hermes -c # Or with the chat subcommand hermes chat --continue hermes chat -c` This looks up the most recent `cli` session from the SQLite database and loads its full conversation history. ### Resume by Name If you’ve given a session a title (see Session Naming below), you can resume it by name: `bash # Resume a named session hermes -c "my project" # If there are lineage variants (my project, my project #2, my project #3), # this automatically resumes the most recent one hermes -c "my project" # → resumes "my project #3"` ### Resume Specific Session `bash # Resume a specific session by ID hermes --resume 20250305_091523_a1b2c3d4 hermes -r 20250305_091523_a1b2c3d4 # Resume by title hermes --resume "refactoring auth" # Or with the chat subcommand hermes chat --resume 20250305_091523_a1b2c3d4` Session IDs are shown when you exit a CLI session, and can be found with `hermes sessions list`. ### Conversation Recap on Resume When you resume a session, Hermes displays a compact recap of the previous conversation in a styled panel before the input prompt: <img className=“docs-terminal-figure” src={useBaseUrl(‘/img/docs/session-recap.svg’)} alt=“Stylized preview of the Previous Conversation recap panel shown when resuming a Hermes session.” />
Resume mode shows a compact recap panel with recent user and assistant turns before returning you to the live prompt.
The recap: - Shows user messages (gold `●`) and assistant responses (green `◆`) - Truncates long messages (300 chars for user, 200 chars / 3 lines for assistant) - Collapses tool calls to a count with tool names (e.g., `[3 tool calls: terminal, web_search]`) - Hides system messages, tool results, and internal reasoning - Caps at the last 10 exchanges with a “… N earlier messages …” indicator - Uses dim styling to distinguish from the active conversation To disable the recap and keep the minimal one-liner behavior, set in `~/.hermes/config.yaml`: `yaml display: resume_display: minimal # default: full` :::tip Session IDs follow the format `YYYYMMDD_HHMMSS_<hex>` — CLI/TUI sessions use a 6-char hex suffix (e.g. `20250305_091523_a1b2c3`), gateway sessions use an 8-char suffix (e.g. `20250305_091523_a1b2c3d4`). You can resume by ID (full or unique prefix) or by title — both work with `-c` and `-r`. ::: ## Cross-Platform Handoff Use `/handoff <platform>` from a CLI session to transfer the live conversation to a messaging platform’s home channel. The agent picks up exactly where the CLI left off — same session id, full role-aware transcript, tool calls and all. `bash # Inside a CLI session /handoff telegram` What happens: 1. The CLI validates that `<platform>` is enabled and has a home channel set (run `/sethome` from the destination chat once to configure it). 2. The CLI marks the session pending and block-polls the gateway. It refuses if the agent is mid-turn — wait for the current response to finish first. 3. The gateway watcher claims the handoff and asks the destination adapter for a fresh thread: - Telegram — opens a new forum topic (DM topics if Bot API 9.4+ Topics mode is enabled in the chat, or a forum supergroup topic). - Discord — creates a 1440-min auto-archive thread under the home text channel. - Slack — posts a seed message and uses its `ts` as the thread anchor. - WhatsApp / Signal / Matrix / SMS — no native threads, falls back to the home channel directly. 4. The gateway re-binds the destination key to your existing CLI session id, then forges a synthetic user turn asking the agent to confirm and summarize. The reply lands in the new thread. 5. When the gateway acknowledges success, the CLI prints a `/resume` hint and exits cleanly: `↻ Handoff complete. The session is now active on telegram. Resume it on this CLI later with: /resume my-session-title` 6. From that point, the conversation lives on the platform. Reply in the new thread — anyone authorized in that channel shares the same session, and any later real user message in the thread joins seamlessly because thread sessions key without `user_id`. Resume back to CLI: when you want to come back to a desktop, just run `/resume <title>` (or `hermes -r "<title>"` from the shell) and pick up where the platform left off. Failure modes: - No home channel configured → CLI refuses with a `/sethome` hint. - Platform not enabled / gateway not running → CLI times out at 60s with a clear message and your CLI session stays intact. - Thread creation fails (permissions, topics-mode off) → falls back to the home channel directly and still completes; no thread isolation but the handoff itself works. - `adapter.send` fails (rate limit, transient API error) → handoff marked failed with the reason; the row clears so you can retry. Limitation worth knowing: for non-thread-capable platforms with multi-user group home channels, the synthetic turn keys as a DM-style session. This works for self-DM home channels (the typical setup) but isn’t ideal for genuinely shared group chats. Threading covers Telegram / Discord / Slack — by far the common case — so most setups never hit this. ## Session Naming Give sessions human-readable titles so you can find and resume them easily. ### Auto-Generated Titles Hermes automatically generates a short descriptive title (3–7 words) for each session after the first exchange. This runs in a background thread using a fast auxiliary model, so it adds no latency. You’ll see auto-generated titles when browsing sessions with `hermes sessions list` or `hermes sessions browse`. Auto-titling only fires once per session and is skipped if you’ve already set a title manually. ### Setting a Title Manually Use the `/title` slash command inside any chat session (CLI or gateway): `/title my research project` The title is applied immediately. If the session hasn’t been created in the database yet (e.g., you run `/title` before sending your first message), it’s queued and applied once the session starts. You can also rename existing sessions from the command line: `bash hermes sessions rename 20250305_091523_a1b2c3d4 "refactoring auth module"` ### Title Rules - Unique — no two sessions can share the same title - Max 100 characters — keeps listing output clean - Sanitized — control characters, zero-width chars, and RTL overrides are stripped automatically - Normal Unicode is fine — emoji, CJK, accented characters all work ### Auto-Lineage on Compression When a session’s context is compressed (manually via `/compress` or automatically), Hermes creates a new continuation session. If the original had a title, the new session automatically gets a numbered title: `"my project" → "my project #2" → "my project #3"` When you resume by name (`hermes -c "my project"`), it automatically picks the most recent session in the lineage. ### /title in Messaging Platforms The `/title` command works in all gateway platforms (Telegram, Discord, Slack, WhatsApp): - `/title My Research` — set the session title - `/title` — show the current title ## Session Management Commands Hermes provides a full set of session management commands via `hermes sessions`: ### List Sessions `bash # List recent sessions (default: last 20) hermes sessions list # Filter by platform hermes sessions list --source telegram # Show more sessions hermes sessions list --limit 50` When sessions have titles, the output shows titles, previews, and relative timestamps: Title Preview Last Active ID ──────────────────────────────────────────────────────────────────────────────────────────────── refactoring auth Help me refactor the auth module please 2h ago 20250305_091523_a my project #3 Can you check the test failures? yesterday 20250304_143022_e — What's the weather in Las Vegas? 3d ago 20250303_101500_f When no sessions have titles, a simpler format is used: `Preview Last Active Src ID ────────────────────────────────────────────────────────────────────────────────────── Help me refactor the auth module please 2h ago cli 20250305_091523_a What's the weather in Las Vegas? 3d ago tele 20250303_101500_f` ### Export Sessions `bash # Export all sessions to a JSONL file hermes sessions export backup.jsonl # Export sessions from a specific platform hermes sessions export telegram-history.jsonl --source telegram # Export a single session hermes sessions export session.jsonl --session-id 20250305_091523_a1b2c3d4` Exported files contain one JSON object per line with full session metadata and all messages. ### Delete a Session `bash # Delete a specific session (with confirmation) hermes sessions delete 20250305_091523_a1b2c3d4 # Delete without confirmation hermes sessions delete 20250305_091523_a1b2c3d4 --yes` ### Rename a Session `bash # Set or change a session's title hermes sessions rename 20250305_091523_a1b2c3d4 "debugging auth flow" # Multi-word titles don't need quotes in the CLI hermes sessions rename 20250305_091523_a1b2c3d4 debugging auth flow` If the title is already in use by another session, an error is shown. ### Prune Old Sessions `bash # Delete ended sessions older than 90 days (default) hermes sessions prune # Custom age threshold hermes sessions prune --older-than 30 # Only prune sessions from a specific platform hermes sessions prune --source telegram --older-than 60 # Skip confirmation hermes sessions prune --older-than 30 --yes` :::info Pruning only deletes ended sessions (sessions that have been explicitly ended or auto-reset). Active sessions are never pruned. ::: ### Session Statistics `bash hermes sessions stats` Output: `Total sessions: 142 Total messages: 3847 cli: 89 sessions telegram: 38 sessions discord: 15 sessions Database size: 12.4 MB` For deeper analytics — token usage, cost estimates, tool breakdown, and activity patterns — use `hermes insights`. ## Session Search Tool The agent has a built-in `session_search` tool that performs full-text search across all past conversations using SQLite’s FTS5 engine — and lets the agent scroll through any session it finds. No LLM calls, no summarization, no truncation. Every shape returns actual messages from the DB. ### Three calling shapes The tool infers what you want from which arguments you set. There’s no `mode` parameter. 1. Discovery — pass `query`: `python session_search(query="auth refactor", limit=3)` Runs FTS5, dedupes hits by session lineage, returns the top N sessions. Each result carries: - `session_id`, `title`, `when`, `source` - `snippet` — FTS5-highlighted match excerpt - `bookend_start` — first 3 user+assistant messages of the session (the goal/kickoff) - `messages` — ±5 messages around the FTS5 match, with the anchor message flagged (the hit in context) - `bookend_end` — last 3 user+assistant messages of the session (the resolution/decisions) - `match_message_id`, `messages_before`, `messages_after` Bookends + window together reconstruct goal → match → resolution without paying for the whole transcript. Typical wall time: 15–50ms on a real session DB. 2. Scroll — pass `session_id` + `around_message_id`: `python session_search(session_id="20260510_174648_805cc2", around_message_id=590803, window=10)` Returns a window of ±`window` messages centered on the anchor. No FTS5, no bookends — just the slice. Use after a discovery call when you need more context than the ±5 default window. - To scroll forward: pass `messages[-1].id` back as `around_message_id` - To scroll backward: pass `messages[0].id` back as `around_message_id` - The boundary message appears in both windows as an orientation marker - When `messages_before` or `messages_after` is less than `window`, you’re at the start or end of the session Typical wall time: 1–2ms per scroll call. 3. Browse — no args: `python session_search()` Returns recent sessions chronologically (titles, previews, timestamps). Useful when the user asks “what was I working on” without naming a topic. ### FTS5 query syntax The keyword mode supports standard FTS5 query syntax: - Simple keywords: `docker deployment` (FTS5 defaults to AND) - Phrases: `"exact phrase"` - Boolean: `docker OR kubernetes`, `python NOT java` - Prefix: `deploy` ### Optional parameters - `sort` — `newest` or `oldest`, on top of FTS5 ranking. Omit for relevance-only ordering (the default; suitable for exploratory recall). Use `newest` for “where did we leave X” questions, `oldest` for “how did X start” questions. - `role_filter` — comma-separated roles to include. Discovery defaults to `user,assistant` (tool output is usually noise). Pass `user,assistant,tool` to include tool output (debugging tool behaviour) or `tool` to search tool output only. ### When It’s Used The agent is prompted to use session search automatically: > “When the user references something from a past conversation or you suspect relevant prior context exists, use session_search to recall it before asking them to repeat themselves.”* Typical triggers: “we did this before”, “remember when”, “last time”, “as I mentioned”, or any reference to a project/person/concept that isn’t in the current window. ## Per-Platform Session Tracking ### Gateway Sessions On messaging platforms, sessions are keyed by a deterministic session key built from the message source: | Chat Type | Default Key Format | Behavior | |———–|––––––––––|–––––| | Telegram DM | `agent:main:telegram:dm:<chat_id>` | One session per DM chat | | Discord DM | `agent:main:discord:dm:<chat_id>` | One session per DM chat | | WhatsApp DM | `agent:main:whatsapp:dm:<canonical_identifier>` | One session per DM user (LID/phone aliases collapse to one identity when mapping exists) | | Group chat | `agent:main:<platform>:group:<chat_id>:<user_id>` | Per-user inside the group when the platform exposes a user ID | | Group thread/topic | `agent:main:<platform>:group:<chat_id>:<thread_id>` | Shared session for all thread participants (default). Per-user with `thread_sessions_per_user: true`. | | Channel | `agent:main:<platform>:channel:<chat_id>:<user_id>` | Per-user inside the channel when the platform exposes a user ID | When Hermes cannot get a participant identifier for a shared chat, it falls back to one shared session for that room. ### Shared vs Isolated Group Sessions By default, Hermes uses `group_sessions_per_user: true` in `config.yaml`. That means: - Alice and Bob can both talk to Hermes in the same Discord channel without sharing transcript history - one user’s long tool-heavy task does not pollute another user’s context window - interrupt handling also stays per-user because the running-agent key matches the isolated session key If you want one shared “room brain” instead, set: `yaml group_sessions_per_user: false` That reverts groups/channels to a single shared session per room, which preserves shared conversational context but also shares token costs, interrupt state, and context growth. ### Session Reset Policies Gateway sessions are automatically reset based on configurable policies: - idle — reset after N minutes of inactivity - daily — reset at a specific hour each day - both — reset on whichever comes first (idle or daily) - none — never auto-reset Before a session is auto-reset, the agent is given a turn to save any important memories or skills from the conversation. Sessions with active background processes are never auto-reset, regardless of policy. ## Storage Locations | What | Path | Description | |——|——|———––| | SQLite database | `~/.hermes/state.db` | All session metadata + messages with FTS5 | | Gateway messages | `~/.hermes/state.db` | SQLite — canonical store for all session messages | | Gateway routing index | `~/.hermes/sessions/sessions.json` | Maps session keys to active session IDs (origin metadata, expiry flags) | The SQLite database uses WAL mode for concurrent readers and a single writer, which suits the gateway’s multi-platform architecture well. :::note Legacy JSONL transcripts Sessions created before state.db became canonical may have leftover `.jsonl` files in `~/.hermes/sessions/`. They are no longer written or read by Hermes. Safe to delete after verifying the corresponding session exists in state.db. ::: ### Database Schema Key tables in `state.db`: - sessions — session metadata (id, source, user_id, model, title, timestamps, token counts). Titles have a unique index (NULL titles allowed, only non-NULL must be unique). - messages — full message history (role, content, tool_calls, tool_name, token_count) - messages_fts — FTS5 virtual table for full-text search across message content ## Session Expiry and Cleanup ### Automatic Cleanup - Gateway sessions auto-reset based on the configured reset policy - Before reset, the agent saves memories and skills from the expiring session - Opt-in auto-pruning: when `sessions.auto_prune` is `true`, ended sessions older than `sessions.retention_days` (default 90) are pruned at CLI/gateway startup - After a prune that actually removed rows, `state.db` is `VACUUM`ed to reclaim disk space (SQLite does not shrink the file on plain DELETE) - Pruning runs at most once per `sessions.min_interval_hours` (default 24); the last-run timestamp is tracked inside `state.db` itself so it’s shared across every Hermes process in the same `HERMES_HOME` Default is off — session history is valuable for `session_search` recall, and silently deleting it could surprise users. Enable in `~/.hermes/config.yaml`: `yaml sessions: auto_prune: true # opt in — default is false retention_days: 90 # keep ended sessions this many days vacuum_after_prune: true # reclaim disk space after a pruning sweep min_interval_hours: 24 # don't re-run the sweep more often than this` Active sessions are never auto-pruned, regardless of age. ### Manual Cleanup `bash # Prune sessions older than 90 days hermes sessions prune # Delete a specific session hermes sessions delete <session_id> # Export before pruning (backup) hermes sessions export backup.jsonl hermes sessions prune --older-than 30 --yes` :::tip The database grows slowly (typical: 10-15 MB for hundreds of sessions) and session history powers `session_search` recall across past conversations, so auto-prune ships disabled. Enable it if you’re running a heavy gateway/cron workload where `state.db` is meaningfully affecting performance (observed failure mode: 384 MB state.db with 1000 sessions slowing down FTS5 inserts and `/resume` listing). Use `hermes sessions prune` for one-off cleanup without turning on the automatic sweep. ::: — # user-guide/profiles # Profiles: Running Multiple Agents Run multiple independent Hermes agents on the same machine — each with its own config, API keys, memory, sessions, skills, and gateway state. ## What are profiles? A profile is a separate Hermes home directory. Each profile gets its own directory containing its own `config.yaml`, `.env`, `SOUL.md`, memories, sessions, skills, cron jobs, and state database. Profiles let you run separate agents for different purposes — a coding assistant, a personal bot, a research agent — without mixing up Hermes state. When you create a profile, it automatically becomes its own command. Create a profile called `coder` and you immediately have `coder chat`, `coder setup`, `coder gateway start`, etc. ## Quick start `bash hermes profile create coder # creates profile + "coder" command alias coder setup # configure API keys and model coder chat # start chatting` That’s it. `coder` is now its own Hermes profile with its own config, memory, and state. ## Creating a profile :::tip Quickest setup: run `hermes setup --portal` inside the new profile to wire up models + tools at once. See Nous Portal. ::: ### Blank profile `bash hermes profile create mybot` Creates a fresh profile with bundled skills seeded. Run `mybot setup` to configure API keys, model, and gateway tokens. If you plan to use this profile as a kanban worker (or want the kanban orchestrator to route work to it), pass `--description "<role>"` at create time so the orchestrator knows what it’s good at: `bash hermes profile create researcher --description "Reads source code and external docs, writes findings."` You can also set or auto-generate the description later with `hermes profile describe` — see the Kanban guide for the full routing model. ### Clone config only (`--clone`) `bash hermes profile create work --clone` Copies your current profile’s `config.yaml`, `.env`, and `SOUL.md` into the new profile. Same API keys and model, but fresh sessions and memory. Edit `~/.hermes/profiles/work/.env` for different API keys, or `~/.hermes/profiles/work/SOUL.md` for a different personality. ### Clone everything (`--clone-all`) `bash hermes profile create backup --clone-all` Copies everything — config, API keys, personality, all memories, full session history, skills, cron jobs, plugins. A complete snapshot. Useful for backups or forking an agent that already has context. ### Clone from a specific profile `bash hermes profile create work --clone --clone-from coder` :::tip Honcho memory + profiles When Honcho is enabled, `--clone` automatically creates a dedicated AI peer for the new profile while sharing the same user workspace. Each profile builds its own observations and identity. See Honcho – Multi-agent / Profiles for details. ::: ## Using profiles ### Command aliases Every profile automatically gets a command alias at `~/.local/bin/<name>`: `bash coder chat # chat with the coder agent coder setup # configure coder's settings coder gateway start # start coder's gateway coder doctor # check coder's health coder skills list # list coder's skills coder config set model.default anthropic/claude-sonnet-4` The alias works with every hermes subcommand — it’s just `hermes -p <name>` under the hood. ### The `-p` flag You can also target a profile explicitly with any command: `bash hermes -p coder chat hermes --profile=coder doctor hermes chat -p coder -q "hello" # works in any position` ### Sticky default (`hermes profile use`) `bash hermes profile use coder hermes chat # now targets coder hermes tools # configures coder's tools hermes profile use default # switch back` Sets a default so plain `hermes` commands target that profile. Like `kubectl config use-context`. ### Knowing where you are The CLI always shows which profile is active: - Prompt: `coder ❯` instead of `❯` - Banner: Shows `Profile: coder` on startup - `hermes profile`: Shows current profile name, path, model, gateway status ## Profiles vs workspaces vs sandboxing Profiles are often confused with workspaces or sandboxes, but they are different things: - A profile gives Hermes its own state directory: `config.yaml`, `.env`, `SOUL.md`, sessions, memory, logs, cron jobs, and gateway state. - A workspace or working directory is where terminal commands start. That is controlled separately by `terminal.cwd`. - A sandbox is what limits filesystem access. Profiles do not sandbox the agent. On the default `local` terminal backend, the agent still has the same filesystem access as your user account. A profile does not stop it from accessing folders outside the profile directory. If you want a profile to start in a specific project folder, set an explicit absolute `terminal.cwd` in that profile’s `config.yaml`: `yaml terminal: backend: local cwd: /absolute/path/to/project` Using `cwd: "."` on the local backend means “the directory Hermes was launched from”, not “the profile directory”. Also note: - `SOUL.md` can guide the model, but it does not enforce a workspace boundary. - Changes to `SOUL.md` take effect cleanly on a new session. Existing sessions may still be using the old prompt state. - Asking the model “what directory are you in?” is not a reliable isolation test. If you need a predictable starting directory for tools, set `terminal.cwd` explicitly. ## Running gateways Each profile runs its own gateway as a separate process with its own bot token: `bash coder gateway start # starts coder's gateway assistant gateway start # starts assistant's gateway (separate process)` ### Different bot tokens Each profile has its own `.env` file. Configure a different Telegram/Discord/Slack bot token in each: `bash # Edit coder's tokens nano ~/.hermes/profiles/coder/.env # Edit assistant's tokens nano ~/.hermes/profiles/assistant/.env` ### Safety: token locks If two profiles accidentally use the same bot token, the second gateway will be blocked with a clear error naming the conflicting profile. Supported for Telegram, Discord, Slack, WhatsApp, and Signal. ### Persistent services `bash coder gateway install # creates hermes-gateway-coder systemd/launchd service assistant gateway install # creates hermes-gateway-assistant service` Each profile gets its own service name. They run independently. :::note Inside the official Docker image Per-profile gateways are supervised by s6-overlay (PID 1 in the container), so `hermes profile create <name>` automatically registers an s6 service slot at `/run/service/gateway-<name>/`. `hermes -p <name> gateway start/stop/restart` dispatches to `s6-svc` instead of spawning a bare process — crashes are auto-restarted and `docker restart` preserves the previously-running set of gateways. See Per-profile gateway supervision for details. ::: ## Configuring profiles Each profile has its own: - `config.yaml` — model, provider, toolsets, all settings - `.env` — API keys, bot tokens - `SOUL.md` — personality and instructions `bash coder config set model.default anthropic/claude-sonnet-4 echo "You are a focused coding assistant." > ~/.hermes/profiles/coder/SOUL.md` If you want this profile to work in a specific project by default, also set its own `terminal.cwd`: `bash coder config set terminal.cwd /absolute/path/to/project` ## Updating `hermes update` pulls code once (shared) and syncs new bundled skills to all profiles automatically: `bash hermes update # → Code updated (12 commits) # → Skills synced: default (up to date), coder (+2 new), assistant (+2 new)` User-modified skills are never overwritten. ## Managing profiles `bash hermes profile list # show all profiles with status hermes profile show coder # detailed info for one profile hermes profile rename coder dev-bot # rename (updates alias + service) hermes profile export coder # export to coder.tar.gz hermes profile import coder.tar.gz # import from archive` ## Deleting a profile `bash hermes profile delete coder` This stops the gateway, removes the systemd/launchd service, removes the command alias, and deletes all profile data. You’ll be asked to type the profile name to confirm. Use `--yes` to skip confirmation: `hermes profile delete coder --yes` :::note You cannot delete the default profile (`~/.hermes`). To remove everything, use `hermes uninstall`. ::: ## Tab completion `bash # Bash eval "$(hermes completion bash)" # Zsh eval "$(hermes completion zsh)"` Add the line to your `~/.bashrc` or `~/.zshrc` for persistent completion. Completes profile names after `-p`, profile subcommands, and top-level commands. ## How it works Profiles use the `HERMES_HOME` environment variable. When you run `coder chat`, the wrapper script sets `HERMES_HOME=~/.hermes/profiles/coder` before launching hermes. Since 119+ files in the codebase resolve paths via `get_hermes_home()`, Hermes state automatically scopes to the profile’s directory — config, sessions, memory, skills, state database, gateway PID, logs, and cron jobs. This is separate from terminal working directory. Tool execution starts from `terminal.cwd` (or the launch directory when `cwd: "."` on the local backend), not automatically from `HERMES_HOME`. The default profile is simply `~/.hermes` itself. No migration needed — existing installs work identically. ## Sharing profiles as distributions A profile you built on one machine can be packaged as a git repository and installed with one command on another machine — your own workstation, a teammate’s laptop, or a community user’s environment. The shared package includes the SOUL, config, skills, cron jobs, and MCP connections. Credentials, memories, and sessions stay per-machine. `bash # Install a whole agent from a git repo hermes profile install github.com/you/research-bot --alias # Update later when the author ships a new version (keeps your memories + .env) hermes profile update research-bot` See Profile Distributions: Share a Whole Agent for the full guide — authoring, publishing, update semantics, security model, and use cases. — # Git Worktrees # Git Worktrees Hermes Agent is often used on large, long‑lived repositories. When you want to: - Run multiple agents in parallel on the same project, or - Keep experimental refactors isolated from your main branch, Git worktrees are the safest way to give each agent its own checkout without duplicating the entire repository. This page shows how to combine worktrees with Hermes so each session has a clean, isolated working directory. ## Why Use Worktrees with Hermes? Hermes treats the current working directory as the project root: - CLI: the directory where you run `hermes` or `hermes chat` - Messaging gateways: the directory set by `terminal.cwd` in `~/.hermes/config.yaml` If you run multiple agents in the same checkout, their changes can interfere with each other: - One agent may delete or rewrite files the other is using. - It becomes harder to understand which changes belong to which experiment. With worktrees, each agent gets: - Its own branch and working directory - Its own Checkpoint Manager history for `/rollback` See also: Checkpoints and /rollback. ## Quick Start: Creating a Worktree From your main repository (containing `.git/`), create a new worktree for a feature branch: `bash # From the main repo root cd /path/to/your/repo # Create a new branch and worktree in ../repo-feature git worktree add ../repo-feature feature/hermes-experiment` This creates: - A new directory: `../repo-feature` - A new branch: `feature/hermes-experiment` checked out in that directory Now you can `cd` into the new worktree and run Hermes there: `bash cd ../repo-feature # Start Hermes in the worktree hermes` Hermes will: - See `../repo-feature` as the project root. - Use that directory for context files, code edits, and tools. - Use a separate checkpoint history for `/rollback` scoped to this worktree. ## Running Multiple Agents in Parallel You can create multiple worktrees, each with its own branch: `bash cd /path/to/your/repo git worktree add ../repo-experiment-a feature/hermes-a git worktree add ../repo-experiment-b feature/hermes-b` In separate terminals: `bash # Terminal 1 cd ../repo-experiment-a hermes # Terminal 2 cd ../repo-experiment-b hermes` Each Hermes process: - Works on its own branch (`feature/hermes-a` vs `feature/hermes-b`). - Writes checkpoints under a different shadow repo hash (derived from the worktree path). - Can use `/rollback` independently without affecting the other. This is especially useful when: - Running batch refactors. - Trying different approaches to the same task. - Pairing CLI + gateway sessions against the same upstream repo. ## Cleaning Up Worktrees Safely When you are done with an experiment: 1. Decide whether to keep or discard the work. 2. If you want to keep it: - Merge the branch into your main branch as usual. 3. Remove the worktree: `bash cd /path/to/your/repo # Remove the worktree directory and its reference git worktree remove ../repo-feature` Notes: - `git worktree remove` will refuse to remove a worktree with uncommitted changes unless you force it. - Removing a worktree does not automatically delete the branch; you can delete or keep the branch using normal `git branch` commands. - Hermes checkpoint data under `~/.hermes/checkpoints/` is not automatically pruned when you remove a worktree, but it is usually very small. ## Best Practices - One worktree per Hermes experiment - Create a dedicated branch/worktree for each substantial change. - This keeps diffs focused and PRs small and reviewable. - Name branches after the experiment - e.g. `feature/hermes-checkpoints-docs`, `feature/hermes-refactor-tests`. - Commit frequently - Use git commits for high‑level milestones. - Use checkpoints and /rollback as a safety net for tool‑driven edits in between. - Avoid running Hermes from the bare repo root when using worktrees - Prefer the worktree directories instead, so each agent has a clear scope. ## Using `hermes -w` (Automatic Worktree Mode) Hermes has a built‑in `-w` flag that automatically creates a disposable git worktree with its own branch. You don’t need to set up worktrees manually — just `cd` into your repo and run: `bash cd /path/to/your/repo hermes -w` Hermes will: - Create a temporary worktree under `.worktrees/` inside your repo. - Check out an isolated branch (e.g. `hermes/hermes-<hash>`). - Run the full CLI session inside that worktree. This is the easiest way to get worktree isolation. You can also combine it with a single query: `bash hermes -w -z "Fix issue #123"` For parallel agents, open multiple terminals and run `hermes -w` in each — every invocation gets its own worktree and branch automatically. ## Putting It All Together - Use git worktrees to give each Hermes session its own clean checkout. - Use branches to capture the high‑level history of your experiments. - Use checkpoints + `/rollback` to recover from mistakes inside each worktree. This combination gives you: - Strong guarantees that different agents and experiments do not step on each other. - Fast iteration cycles with easy recovery from bad edits. - Clean, reviewable pull requests. — # Docker # Hermes Agent — Docker There are two distinct ways Docker intersects with Hermes Agent: 1. Running Hermes IN Docker — the agent itself runs inside a container (this page’s primary focus) 2. Docker as a terminal backend — the agent runs on your host but executes every command inside a single, persistent Docker sandbox container that survives across tool calls, `/new`, and subagents for the life of the Hermes process (see Configuration → Docker Backend) This page covers option 1. The container stores all user data (config, API keys, sessions, skills, memories) in a single directory mounted from the host at `/opt/data`. The image itself is stateless and can be upgraded by pulling a new version without losing any configuration. ## Quick start If this is your first time running Hermes Agent, create a data directory on the host and start the container interactively to run the setup wizard: :::caution Avoid browser-based VPS consoles for the install commands Some VPS providers (Hetzner Cloud, and several others) offer a browser-based console for managing hosts. These consoles transmit special characters incorrectly — `:` may arrive as `;`, `@` may be mis-rendered, and non-English keyboard layouts fare worse — which silently corrupts `docker run` arguments like `-v ~/.hermes:/opt/data`, `-e KEY=value`, and pasted API keys / tokens. Connect over SSH instead (`ssh root@<host>`) for copy-paste-safe command entry. If you must use the browser console, type the commands manually instead of pasting, and double-check every `:`, `@`, `=`, and `/` in the result before hitting Enter. ::: `sh mkdir -p ~/.hermes docker run -it --rm \ -v ~/.hermes:/opt/data \ nousresearch/hermes-agent setup` This drops you into the setup wizard, which will prompt you for your API keys and write them to `~/.hermes/.env`. You only need to do this once. It is highly recommended to set up a chat system for the gateway to work with at this point. :::tip Inside the container, run `hermes setup --portal` once — the refresh token persists in the mounted `~/.hermes` volume. See Nous Portal. ::: ## Running in gateway mode Once configured, run the container in the background as a persistent gateway (Telegram, Discord, Slack, WhatsApp, etc.): `sh docker run -d \ --name hermes \ --restart unless-stopped \ -v ~/.hermes:/opt/data \ -p 8642:8642 \ nousresearch/hermes-agent gateway run` Port 8642 exposes the gateway’s OpenAI-compatible API server and health endpoint. It’s optional if you only use chat platforms (Telegram, Discord, etc.), but required if you want the dashboard or external tools to reach the gateway. :::tip Gateway runs supervised Inside the official Docker image, `gateway run` is automatically supervised by s6-overlay: if the gateway process crashes it’s restarted within a couple of seconds without losing the container, and the dashboard (when `HERMES_DASHBOARD=1` is set) is supervised alongside it. The `gateway run` CMD process itself is a `sleep infinity` heartbeat that keeps the container alive while s6 manages the actual gateway process — so `docker stop` still shuts everything down cleanly, but `docker logs` shows the supervised gateway’s output. You’ll see a one-line breadcrumb in `docker logs` confirming the upgrade. To opt out — and get the historical “gateway is the container’s main process, container exit = gateway exit” semantics — pass `--no-supervise` or set `HERMES_GATEWAY_NO_SUPERVISE=1`. The opt-out is useful for CI smoke tests that want the container to exit with the gateway’s status code; for production deployments the supervised default is strictly better. This behavior applies to the s6-based image only. Earlier (tini-based) images still run `gateway run` as the foreground main process. ::: :::note Where gateway logs go See the Where the logs go section below for the full routing map (per-profile gateways, dashboard, boot reconciler, container-wide `docker logs`). ::: Note: the API server is gated on `API_SERVER_ENABLED=true`. To expose it beyond `127.0.0.1` inside the container, also set `API_SERVER_HOST=0.0.0.0` and an `API_SERVER_KEY` (minimum 8 characters — generate one with `openssl rand -hex 32`). Example: `sh docker run -d \ --name hermes \ --restart unless-stopped \ -v ~/.hermes:/opt/data \ -p 8642:8642 \ -e API_SERVER_ENABLED=true \ -e API_SERVER_HOST=0.0.0.0 \ -e API_SERVER_KEY="$(openssl rand -hex 32)" \ -e API_SERVER_CORS_ORIGINS='' \ nousresearch/hermes-agent gateway run` Opening any port on an internet facing machine is a security risk. You should not do it unless you understand the risks. ## Running the dashboard The built-in web dashboard runs as a supervised s6-rc service alongside the gateway in the same container. Set `HERMES_DASHBOARD=1` to bring it up: `sh docker run -d \ --name hermes \ --restart unless-stopped \ -v ~/.hermes:/opt/data \ -p 8642:8642 \ -p 9119:9119 \ -e HERMES_DASHBOARD=1 \ nousresearch/hermes-agent gateway run` The dashboard is supervised by s6 — if it crashes, `s6-supervise` restarts it automatically after a short backoff. Dashboard stdout/stderr is forwarded to `docker logs <container>` (no prefix; the gateway’s own output now lives in a per-profile s6-log file — see Where the logs go below — so the two streams don’t clash). | Environment variable | Description | Default | |———————|———––|———| | `HERMES_DASHBOARD` | Set to `1` (or `true` / `yes`) to enable the supervised dashboard service | (unset — service is registered but stays down) | | `HERMES_DASHBOARD_HOST` | Bind address for the dashboard HTTP server | `0.0.0.0` | | `HERMES_DASHBOARD_PORT` | Port for the dashboard HTTP server | `9119` | | `HERMES_DASHBOARD_INSECURE` | Set to `1` (or `true` / `yes`) to bind without the OAuth auth gate. Only use on trusted networks behind a reverse proxy without the OAuth contract — the dashboard exposes API keys and session data | (unset — gate enforced when a `DashboardAuthProvider` is registered) | The dashboard inside the container defaults to binding `0.0.0.0` — without it, the published `-p 9119:9119` port would not be reachable from the host. To restrict the bind to container loopback (for sidecar / reverse-proxy setups), set `HERMES_DASHBOARD_HOST=127.0.0.1`. The dashboard’s auth gate engages automatically when both of the following are true: 1. The bind host is non-loopback (e.g. the default `0.0.0.0` inside the container), and 2. A `DashboardAuthProvider` plugin is registered. There are three bundled ways to satisfy the second condition: - Username/password — the simplest for a self-hosted / on-prem / homelab container on a trusted network or behind a VPN: set `HERMES_DASHBOARD_BASIC_AUTH_USERNAME` + `HERMES_DASHBOARD_BASIC_AUTH_PASSWORD` (and `HERMES_DASHBOARD_BASIC_AUTH_SECRET` for restart-stable sessions). Not suitable for direct public-internet exposure. - OAuth (Nous Portal) — for hosted/public deploys: the `dashboard_auth/nous` provider activates whenever `HERMES_DASHBOARD_OAUTH_CLIENT_ID` is set. - Self-hosted OIDC — to authenticate against your own identity provider via standard OpenID Connect: the `dashboard_auth/self_hosted` provider activates when `HERMES_DASHBOARD_OIDC_ISSUER` + `HERMES_DASHBOARD_OIDC_CLIENT_ID` are set. Whichever you choose, the gate redirects callers to a login page before they can reach any protected route. See Web Dashboard → Authentication for all three providers. If no provider is registered and the bind is non-loopback, the dashboard fails closed at startup with a specific error pointing at the missing env var. The `HERMES_DASHBOARD_INSECURE=1` escape hatch disables the gate entirely (the bind host alone never implies `--insecure`), but it serves an unauthenticated dashboard — configure a provider instead unless you have your own auth layer in front. :::warning `HERMES_DASHBOARD_INSECURE=1` exposes API keys Opting out of the OAuth gate serves the dashboard’s API surface (including model keys and session data) to anyone who can reach the published port. Only enable it when you have your own auth layer in front, or on a trusted LAN you fully control. ::: Running the dashboard as a separate container is supported when that container shares the host PID and network namespace (e.g. `network_mode: host`, as the repo’s own `docker-compose.yml` does — see its `dashboard` service). Its gateway-liveness detection requires a shared PID namespace with the gateway process, so the limitation only applies to dashboards run in isolated bridge-network containers without a shared PID namespace. ## Running interactively (CLI chat) To open an interactive chat session against a running data directory: `sh docker run -it --rm \ -v ~/.hermes:/opt/data \ nousresearch/hermes-agent` Or if you have already opened a terminal in your running container (via Docker Desktop for instance), just run: `sh /opt/hermes/.venv/bin/hermes` ## Persistent volumes The `/opt/data` volume is the single source of truth for all Hermes state. It maps to your host’s `~/.hermes/` directory and contains: | Path | Contents | |——|–––––| | `.env` | API keys and secrets | | `config.yaml` | All Hermes configuration | | `SOUL.md` | Agent personality/identity | | `sessions/` | Conversation history | | `memories/` | Persistent memory store | | `skills/` | Installed skills | | `home/` | Per-profile HOME for Hermes tool subprocesses (`git`, `ssh`, `gh`, `npm`, and skill CLIs) | | `cron/` | Scheduled job definitions | | `hooks/` | Event hooks | | `logs/` | Runtime logs | | `skins/` | Custom CLI skins | Skill CLIs that store credentials under `~` must be initialized against the subprocess HOME, not just the data-volume root. For example, the xurl skill stores OAuth state in `~/.xurl`; in the official Docker layout, Hermes tool calls read that as `/opt/data/home/.xurl`, so run manual xurl auth with `HOME=/opt/data/home` and verify with `HOME=/opt/data/home xurl auth status`. :::warning Never run two Hermes gateway containers against the same data directory simultaneously — session files and memory stores are not designed for concurrent write access. ::: ## Multi-profile support Hermes supports multiple profiles — separate `~/.hermes/` subdirectories that let you run independent agents (different SOUL, skills, memory, sessions, credentials) from a single installation. Inside the official Docker image, the s6 supervision tree treats each profile as a first-class supervised service, so the recommended deployment is one container hosting all profiles. Each profile created with `hermes profile create <name>` gets: - A dedicated s6 service slot at `/run/service/gateway-<name>/`, registered dynamically by the runtime — no container rebuild required. - Auto-restart on crash, backoff-managed by `s6-supervise`. - Per-profile rotated logs at `${HERMES_HOME}/logs/gateways/<name>/current` (10 archives × 1 MB each). - State persistence across container restarts: the boot-time reconciler reads `gateway_state.json` from each profile directory and brings the slot back up only for profiles whose last recorded state was `running`. Only a gateway you explicitly stopped (`hermes gateway stop`) stays down across a restart — a container restart, image upgrade, or unexpected exit leaves the recorded state as `running`, so the gateway auto-starts on the next boot. The lifecycle commands you’d run on the host work the same way from inside the container: sh # Create a profile — registers the gateway-<name> s6 slot. docker exec hermes hermes profile create coder # Start / stop / restart — dispatches s6-svc; the gateway lifecycle survives docker restart. docker exec hermes hermes -p coder gateway start docker exec hermes hermes -p coder gateway stop docker exec hermes hermes -p coder gateway restart # Status — reports `Manager: s6 (container supervisor)` inside the container. docker exec hermes hermes -p coder gateway status # Remove a profile — tears down the s6 slot too. docker exec hermes hermes profile delete coder Under the hood, `hermes gateway start/stop/restart` inside the container is intercepted and routed to `s6-svc` against the right service directory; you don’t need to learn the s6 commands directly. For raw supervisor state, use `/command/s6-svstat /run/service/gateway-<name>` (note `/command/` is on PATH only for processes spawned by the supervision tree — when calling from `docker exec`, pass the absolute path). ### Why one container with many profiles, not many containers Before the s6 migration, “one container per profile” was the recommended pattern because there was no in-container supervisor to manage multiple gateways. With s6 as PID 1, that’s no longer necessary, and the single-container layout is simpler in almost every dimension: | | One container, many profiles | One container per profile | |—|—|—| | Disk overhead | One image, one bundled venv, one Playwright cache | N images / N caches | | Memory overhead | Shared Python interpreter cache, shared node_modules | Duplicated per container | | Profile creation | `docker exec ... hermes profile create <name>` (seconds) | New `docker run` invocation + port allocation + bind-mount config | | Per-profile crash recovery | `s6-supervise` auto-restart | Docker’s `--restart unless-stopped` (slower, kills sibling work) | | Logs | Per-profile rotated file via `s6-log`, plus container-boot audit log | `docker logs <name>` per container — no built-in rotation | | Backup | One `~/.hermes` directory | N directories to coordinate | The default profile (`default`) is always registered on first boot, so a fresh container ships with one supervised gateway out of the box. Additional profiles are pure runtime adds. ### When you DO want a separate container Profile-in-container is the default. Run a separate container per profile only when you have a specific reason: - Resource isolation per workload — e.g. a runaway browser-tool session in profile A shouldn’t be able to OOM profile B. Containers give you `--memory` / `--cpus` per profile. - Independent image pinning — different upstream image tags per workload. - Network segmentation — distinct Docker networks per profile (e.g. one customer-facing, one internal). - Compliance / blast radius — distinct credentials never share an OS-level process tree. In those cases, declare one service per profile with distinct `container_name`, `volumes`, and `ports`: `yaml services: hermes-work: image: nousresearch/hermes-agent:latest container_name: hermes-work restart: unless-stopped command: gateway run ports: - "8642:8642" volumes: - ~/.hermes-work:/opt/data hermes-personal: image: nousresearch/hermes-agent:latest container_name: hermes-personal restart: unless-stopped command: gateway run ports: - "8643:8642" volumes: - ~/.hermes-personal:/opt/data` The warning from Persistent volumes still applies: never point two containers at the same `~/.hermes` directory simultaneously. The s6 supervisor inside each container manages its own profile set; cross-container sharing of a data volume corrupts session files and memory stores. ## Where the logs go The s6 container has four distinct log surfaces, and “why isn’t my gateway showing anything in `docker logs`” is a common surprise. Cheatsheet: | Source | Where it lands | How to read it | |—|—|—| | Per-profile gateway (`hermes gateway run` and per-profile gateways under s6) | Tee’d to two places: `docker logs <container>` (real time, no extra prefix) and `${HERMES_HOME}/logs/gateways/<profile>/current` (rotated, ISO-8601 timestamped, 10 archives × 1 MB each) | `docker logs -f hermes` or `tail -F ~/.hermes/logs/gateways/default/current` on the host | | Dashboard (when `HERMES_DASHBOARD=1`) | `docker logs <container>` (no prefix) | `docker logs -f hermes` — interleaved with gateway lines | | Boot reconciler (records which profile gateways were restored on each container start) | `${HERMES_HOME}/logs/container-boot.log` (append-only audit log) | `tail -F ~/.hermes/logs/container-boot.log` | | Generic Hermes logs (`agent.log`, `errors.log`) | `${HERMES_HOME}/logs/` (profile-aware) | `docker exec hermes hermes logs --follow [--level WARNING] [--session <id>]` | Two practical consequences worth knowing: - The file copy at `logs/gateways/<profile>/current` is what survives container restarts. `docker logs` only retains output from the current container’s lifetime (and is wiped on `docker rm`); the rotated files persist on the bind-mounted volume. - The boot reconciler’s audit line shape is `<iso-timestamp> profile=<name> prior_state=<state> action=<registered|started>`, so a quick `grep profile=coder ~/.hermes/logs/container-boot.log` reveals when a given profile was last restored and whether s6 auto-started it. ## Environment variable forwarding API keys are read from `/opt/data/.env` inside the container. You can also pass environment variables directly: `sh docker run -it --rm \ -v ~/.hermes:/opt/data \ -e ANTHROPIC_API_KEY="sk-ant-..." \ -e OPENAI_API_KEY="sk-..." \ nousresearch/hermes-agent` Direct `-e` flags override values from `.env`. This is useful for CI/CD or secrets-manager integrations where you don’t want keys on disk. :::note Looking for Docker as the terminal backend? This page covers running Hermes itself inside Docker. If you want Hermes to execute the agent’s `terminal` / `execute_code` calls inside a Docker sandbox container (one long-lived container shared across Hermes processes — see issue #20561), that’s a separate config block — `terminal.backend: docker` plus `terminal.docker_image`, `terminal.docker_volumes`, `terminal.docker_forward_env`, `terminal.docker_env`, `terminal.docker_run_as_host_user`, `terminal.docker_extra_args`, `terminal.docker_persist_across_processes`, and `terminal.docker_orphan_reaper`. See Configuration → Docker Backend for the full set including container-lifecycle rules. ::: ## Docker Compose example For persistent deployment with both the gateway and dashboard, a `docker-compose.yaml` is convenient: yaml services: hermes: image: nousresearch/hermes-agent:latest container_name: hermes restart: unless-stopped command: gateway run ports: - "8642:8642" # gateway API - "9119:9119" # dashboard (only reached when HERMES_DASHBOARD=1) volumes: - ~/.hermes:/opt/data environment: - HERMES_DASHBOARD=1 # Uncomment to forward specific env vars instead of using .env file: # - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY} # - OPENAI_API_KEY=${OPENAI_API_KEY} # - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN} deploy: resources: limits: memory: 4G cpus: "2.0" Start with `docker compose up -d` and view logs with `docker compose logs -f`. The supervised gateway’s stdout is also tee’d to `${HERMES_HOME}/logs/gateways/<profile>/current` on the volume — see Where the logs go for the full routing map. ## Optional: Linux desktop audio bridge Voice mode in Docker needs two separate things to work: Hermes must be allowed to probe audio devices inside the container, and the container must be able to reach your host audio server. The setup below covers the host audio plumbing for Linux desktops that expose a PulseAudio-compatible socket, including many PipeWire setups. :::caution This is a Linux desktop workaround, not a general Docker Desktop feature. It is useful when you already have host audio working and want CLI voice mode inside the Hermes container. If Hermes still reports `Running inside Docker container -- no audio devices`, use a build that includes Docker audio probing support for `PULSE_SERVER` / `PIPEWIRE_REMOTE`. ::: First, create an ALSA config next to your Compose file: `conf title="asound.conf" pcm.!default { type pulse hint { show on description "Default ALSA Output (PulseAudio)" } } pcm.pulse { type pulse } ctl.!default { type pulse }` Then build a small derived image with the ALSA PulseAudio plugin installed: `dockerfile title="Dockerfile.audio" FROM nousresearch/hermes-agent:latest USER root RUN apt-get update \ && apt-get install -y --no-install-recommends libasound2-plugins \ && rm -rf /var/lib/apt/lists/` Use that image in Compose and pass through the host user’s PulseAudio socket and cookie: yaml services: hermes: build: context: . dockerfile: Dockerfile.audio image: hermes-agent-audio container_name: hermes restart: unless-stopped command: gateway run volumes: - ~/.hermes:/opt/data - /run/user/${HERMES_UID}/pulse:/run/user/${HERMES_UID}/pulse - ~/.config/pulse/cookie:/tmp/pulse-cookie:ro - ./asound.conf:/etc/asound.conf:ro environment: - HERMES_UID=${HERMES_UID} - HERMES_GID=${HERMES_GID} - XDG_RUNTIME_DIR=/run/user/${HERMES_UID} - PULSE_SERVER=unix:/run/user/${HERMES_UID}/pulse/native - PULSE_COOKIE=/tmp/pulse-cookie Start it with your host UID/GID so the container process can access the per-user audio socket: `sh export HERMES_UID="$(id -u)" export HERMES_GID="$(id -g)" docker compose up -d --build` To verify what PortAudio sees inside the container: `sh docker exec hermes /opt/hermes/.venv/bin/python -c "import sounddevice as sd; print(sd.query_devices())"` ## Resource limits The Hermes container needs moderate resources. Recommended minimums: | Resource | Minimum | Recommended | |–––––|———|———––| | Memory | 1 GB | 2–4 GB | | CPU | 1 core | 2 cores | | Disk (data volume) | 500 MB | 2+ GB (grows with sessions/skills) | Browser automation (Playwright/Chromium) is the most memory-hungry feature. If you don’t need browser tools, 1 GB is sufficient. With browser tools active, allocate at least 2 GB. Set limits in Docker: `sh docker run -d \ --name hermes \ --restart unless-stopped \ --memory=4g --cpus=2 \ -v ~/.hermes:/opt/data \ nousresearch/hermes-agent gateway run` ## What the Dockerfile does The official image is based on `debian:13.4` and includes: - Python 3 with all Hermes dependencies (`uv pip install -e ".[all]"`) - Node.js + npm (for browser automation and WhatsApp bridge) - Playwright with Chromium (`npx playwright install --with-deps chromium --only-shell`) - ripgrep, ffmpeg, git, and `xz-utils` as system utilities - `docker-cli` — so agents running inside the container can drive the host’s Docker daemon (bind-mount `/var/run/docker.sock` to opt in) for `docker build`, `docker run`, container inspection, etc. - `openssh-client` — enables the SSH terminal backend from inside the container. The SSH backend shells out to the system `ssh` binary; without this, it failed silently in containerized installs. - The WhatsApp bridge (`scripts/whatsapp-bridge/`) - `s6-overlay` v3 as PID 1 (replaces the older `tini`) — supervises the dashboard and per-profile gateways with auto-restart on crash, reaps zombie subprocesses, and forwards signals. The container’s `ENTRYPOINT` is s6-overlay’s `/init`. On boot it: 1. Runs `/etc/cont-init.d/01-hermes-setup` (= `docker/stage2-hook.sh`) as root: optional UID/GID remap, fixes volume ownership, seeds `.env` / `config.yaml` / `SOUL.md` on first boot, runs non-interactive config-schema migrations unless `HERMES_SKIP_CONFIG_MIGRATION=1`, syncs bundled skills. 2. Runs `/etc/cont-init.d/02-reconcile-profiles` (= `hermes_cli.container_boot`): walks `$HERMES_HOME/profiles/<name>/`, recreates the per-profile gateway s6 service slot under `/run/service/gateway-<profile>/`, and auto-starts only those whose last recorded state was `running` (see Per-profile gateway supervision). 3. Starts the static `main-hermes` and `dashboard` s6-rc services. 4. Exec’s the container’s CMD as the main program (`/opt/hermes/docker/main-wrapper.sh`), which routes the arguments the user passed to `docker run`: - no args → `hermes` (the default) - first arg is an executable on PATH (e.g. `sleep`, `bash`) → exec it directly - anything else → `hermes <args>` (subcommand passthrough) The container exits when this main program exits, with its exit code. :::warning Breaking change vs. pre-s6 images The container ENTRYPOINT is now `/init` (s6-overlay), not `/usr/bin/tini`. All five documented `docker run` invocation patterns (no args, `chat -q "…"`, `sleep infinity`, `bash`, `--tui`) behave identically to the tini-based image. If you have a downstream wrapper that depended on tini-specific signal behavior or hard-coded `/usr/bin/tini --` invocation, pin to the previous image tag. ::: :::warning Privilege model Do not override the image entrypoint unless you keep `/init` (or, equivalently, the legacy `docker/entrypoint.sh` shim that forwards to the stage2 hook) in the command chain. s6-overlay’s `/init` runs as root so it can chown the volume on first boot, then drops to the `hermes` user via `s6-setuidgid` for every supervised service AND for the main program. Starting `hermes gateway run` as root inside the official image is refused by default because it can leave root-owned files in `/opt/data` and break later dashboard or gateway starts. Set `HERMES_ALLOW_ROOT_GATEWAY=1` only when you intentionally accept that risk. ::: ### `docker exec` automatically drops to the `hermes` user `docker exec hermes <cmd>` defaults to running as root inside the container, but the image ships a thin shim at `/opt/hermes/bin/hermes` (earliest on PATH) that detects root callers and transparently re-execs through `s6-setuidgid hermes`. So `docker exec hermes login`, `docker exec hermes profile create …`, `docker exec hermes setup`, etc. all write files owned by UID 10000 — i.e. readable by the supervised gateway — with no extra `--user` flag needed. Non-root callers (the supervised processes themselves, `docker exec --user hermes`, kanban subagents inside the container) hit a short-circuit that exec’s the venv binary directly, so there’s no overhead on the hot paths. If you specifically need a `docker exec` that retains root semantics (diagnostic sessions, inspecting root-only state, files outside `/opt/data` that root happens to own), opt out per invocation: `sh docker exec -e HERMES_DOCKER_EXEC_AS_ROOT=1 hermes <cmd>` The shim accepts `1` / `true` / `yes` (case-insensitive). Anything else — including typos like `=0` — falls through to the drop, so silent opt-outs aren’t possible. If `s6-setuidgid` isn’t available (custom builds that stripped s6-overlay), the shim refuses to run as root and exits 126 instead, surfacing the broken privilege model loudly rather than regressing to the historical footgun where `docker exec hermes login` would write `auth.json` as `root:root` and break the supervised gateway’s auth on every chat platform message. ### Per-profile gateway supervision Each profile created with `hermes profile create <name>` automatically gets an s6-supervised gateway service registered at `/run/service/gateway-<name>/`, with state-persistent auto-restart across container restarts. See Multi-profile support above for the user-facing workflow and the lifecycle commands. Supervision benefits over the pre-s6 image: - Gateway crashes are auto-restarted by `s6-supervise` after a 1s backoff. - Dashboard, when enabled with `HERMES_DASHBOARD=1`, is supervised on the same supervision tree and gets the same auto-restart treatment. - `docker restart`, image upgrades (`docker compose up -d --force-recreate`), and unexpected exits preserve running gateways: the cont-init reconciler reads `$HERMES_HOME/profiles/<name>/gateway_state.json` and brings the slot back up if the last recorded state was `running`. Only an explicit `hermes gateway stop` records `stopped` and keeps the gateway down across the restart; the container/s6 SIGTERM sent on a restart or upgrade is treated as “still running” and auto-starts. - Per-profile gateway logs persist under `$HERMES_HOME/logs/gateways/<profile>/current` (rotated by `s6-log`), and the reconciler’s actions are appended to `$HERMES_HOME/logs/container-boot.log` per boot. See Where the logs go for the full routing map. `hermes status` inside the container reports `Manager: s6 (container supervisor)`. Use `/command/s6-svstat /run/service/gateway-<name>` for the raw supervisor view (note `/command/` is on PATH for supervision-tree processes only; pass the absolute path when calling from `docker exec`). ## Upgrading Pull the latest image and recreate the container. Your data directory is preserved, and the container runs non-interactive config-schema migrations against the mounted `$HERMES_HOME/config.yaml` before starting the gateway. When a migration is needed, Hermes writes timestamped backups next to `config.yaml` and `.env` first. `sh docker pull nousresearch/hermes-agent:latest docker rm -f hermes docker run -d \ --name hermes \ --restart unless-stopped \ -v ~/.hermes:/opt/data \ nousresearch/hermes-agent gateway run` Or with Docker Compose: `sh docker compose pull docker compose up -d` Set `HERMES_SKIP_CONFIG_MIGRATION=1` only if you need to inspect or migrate the persisted config manually before letting the new image rewrite it. ## Skills and credential files When using Docker as the execution environment (not the methods above, but when the agent runs commands inside a Docker sandbox — see Configuration → Docker Backend), Hermes reuses a single long-lived container for all tool calls and automatically bind-mounts the skills directory (`~/.hermes/skills/`) and any credential files declared by skills into that container as read-only volumes. Skill scripts, templates, and references are available inside the sandbox without manual configuration, and because the container persists for the life of the Hermes process, any dependencies you install or files you write stay around for the next tool call. The same syncing happens for SSH and Modal backends — skills and credential files are uploaded via rsync or the Modal mount API before each command. ## Installing more tools in the container The official image ships with a curated set of utilities (see What the Dockerfile does), but not every tool an agent might want is preinstalled. There are five recommended approaches, in increasing order of effort and durability. ### npm or Python tools — use `npx` or `uvx` For any tool published to npm or PyPI, instruct Hermes to run it via `npx` (npm) or `uvx` (Python) and to remember that command in its persistent memory. If the tool needs a config file or credentials, instruct it to drop those under `/opt/data` (e.g. `/opt/data/<tool>/config.yaml`). Dependencies are fetched on demand and cached for the life of the container. Configuration written under `/opt/data` survives container restarts because it lives on the bind-mounted host directory. The package cache itself is rebuilt after a `docker rm`, but `npx` and `uvx` re-fetch transparently the next time the tool runs. ### Other tools (apt packages, binaries) — install and remember For anything outside npm or PyPI — `apt` packages, prebuilt binaries, language runtimes not already in the image — instruct Hermes how to install it (e.g. `apt-get update && apt-get install -y <package>`) and tell it to remember the install command. The tool persists for the rest of the container’s lifetime, and Hermes will re-run the install command after a container restart when it next needs the tool. This is a good fit for tools that are quick to install and used occasionally. For tools used constantly, prefer the next approach. ### Durable installs — build a derived image When a tool must be available immediately on every container start with no re-install delay, build a new image that inherits from `nousresearch/hermes-agent` and installs the tool in a layer: `dockerfile FROM nousresearch/hermes-agent:latest USER root RUN apt-get update \ && apt-get install -y --no-install-recommends <your-package> \ && rm -rf /var/lib/apt/lists/ USER hermes` Build it and use it in place of the official image: `sh docker build -t my-hermes:latest . docker run -d \ --name hermes \ --restart unless-stopped \ -v ~/.hermes:/opt/data \ -p 8642:8642 \ my-hermes:latest gateway run` The entrypoint script and `/opt/data` semantics are inherited unchanged, so the rest of this page still applies. Remember to rebuild the image when pulling a newer upstream `nousresearch/hermes-agent`. ### Complex tools or multi-service stacks — run a sidecar container For tools that bring their own service (a database, a web server, a queue, a headless browser farm) or that are too heavy to live inside the Hermes container, run them as a separate container on a shared Docker network. Hermes reaches the sidecar by container name, the same way it reaches a local inference server (see Connecting to local inference servers). `yaml services: hermes: image: nousresearch/hermes-agent:latest container_name: hermes restart: unless-stopped command: gateway run ports: - "8642:8642" volumes: - ~/.hermes:/opt/data networks: - hermes-net my-tool: image: example/my-tool:latest container_name: my-tool restart: unless-stopped networks: - hermes-net networks: hermes-net: driver: bridge` From inside the Hermes container, the sidecar is reachable at `http://my-tool:<port>` (or whatever protocol it serves). This pattern keeps each service’s lifecycle, resource limits, and upgrade cadence independent, and avoids bloating the Hermes image with dependencies that are only needed by one tool. ### Broadly useful tools — open an issue or pull request If a tool is likely to be useful to most Hermes Agent users, consider contributing it upstream rather than carrying it in a private derived image. Open an issue or pull request on the hermes-agent repository describing the tool and its use case. Tools that get bundled into the official image benefit every user and avoid the maintenance overhead of a downstream fork. ## Connecting to local inference servers (vLLM, Ollama, etc.) When running Hermes in Docker and your inference server (vLLM, Ollama, text-generation-inference, etc.) is also running on the host or in another container, networking requires extra attention. ### Docker Compose (recommended) Put both services on the same Docker network. This is the most reliable approach: yaml services: vllm: image: vllm/vllm-openai:latest container_name: vllm command: > --model Qwen/Qwen2.5-7B-Instruct --served-model-name my-model --host 0.0.0.0 --port 8000 ports: - "8000:8000" networks: - hermes-net deploy: resources: reservations: devices: - capabilities: [gpu] hermes: image: nousresearch/hermes-agent:latest container_name: hermes restart: unless-stopped command: gateway run ports: - "8642:8642" volumes: - ~/.hermes:/opt/data networks: - hermes-net networks: hermes-net: driver: bridge Then in your `~/.hermes/config.yaml`, use the container name as the hostname: `yaml model: provider: custom model: my-model base_url: http://vllm:8000/v1 api_key: "none"` :::tip Key points - Use the container name (`vllm`) as the hostname — not `localhost` or `127.0.0.1`, which refer to the Hermes container itself. - The `model` value must match the `--served-model-name` you passed to vLLM. - Set `api_key` to any non-empty string (vLLM requires the header but doesn’t validate it by default). - Do not include a trailing slash in `base_url`. ::: ### Standalone Docker run (no Compose) If your inference server runs directly on the host (not in Docker), use `host.docker.internal` on macOS/Windows, or `--network host` on Linux: macOS / Windows: `sh docker run -d \ --name hermes \ -v ~/.hermes:/opt/data \ -p 8642:8642 \ nousresearch/hermes-agent gateway run` `yaml # config.yaml model: provider: custom model: my-model base_url: http://host.docker.internal:8000/v1 api_key: "none"` Linux (host networking): `sh docker run -d \ --name hermes \ --network host \ -v ~/.hermes:/opt/data \ nousresearch/hermes-agent gateway run` `yaml # config.yaml model: provider: custom model: my-model base_url: http://127.0.0.1:8000/v1 api_key: "none"` :::warning With `--network host`, the `-p` flag is ignored — all container ports are directly exposed on the host. ::: ### Verifying connectivity From inside the Hermes container, confirm the inference server is reachable: `sh docker exec hermes curl -s http://vllm:8000/v1/models` You should see a JSON response listing your served model. If this fails, check: 1. Both containers are on the same Docker network (`docker network inspect hermes-net`) 2. The inference server is listening on `0.0.0.0`, not `127.0.0.1` 3. The port number matches ### Ollama Ollama works the same way. If Ollama runs on the host, use `host.docker.internal:11434` (macOS/Windows) or `127.0.0.1:11434` (Linux with `--network host`). If Ollama runs in its own container on the same Docker network: `yaml model: provider: custom model: llama3 base_url: http://ollama:11434/v1 api_key: "none"` ## Troubleshooting ### Container exits immediately Check logs: `docker logs hermes`. Common causes: - Missing or invalid `.env` file — run interactively first to complete setup - Port conflicts if running with exposed ports ### “Permission denied” errors The container’s stage2 hook drops privileges to the non-root `hermes` user (UID 10000) via `s6-setuidgid` inside each supervised service. If your host `~/.hermes/` is owned by a different UID, set `HERMES_UID`/`HERMES_GID` — or their `PUID`/`PGID` aliases, for parity with LinuxServer.io and NAS images — to match your host user, or ensure the data directory is writable: `sh chmod -R 755 ~/.hermes` On a NAS (UGOS, Synology, unRAID) the data directory is typically a bind mount owned by a host UID the container cannot `chown`. Set `PUID`/`PGID` (or `HERMES_UID`/`HERMES_GID`) to that host user so the runtime runs as the owner of the mount rather than UID 10000: `sh docker run -d \ --name hermes \ -e PUID=1000 -e PGID=10 \ -v /volume1/docker/hermes:/opt/data \ nousresearch/hermes-agent gateway run` `docker exec hermes <cmd>` automatically drops to UID 10000 too — see `docker exec` automatically drops to the `hermes` user for details and the per-invocation opt-out. ### Browser tools not working Playwright needs shared memory. Add `--shm-size=1g` to your Docker run command: `sh docker run -d \ --name hermes \ --shm-size=1g \ -v ~/.hermes:/opt/data \ nousresearch/hermes-agent gateway run` ### Gateway not reconnecting after network issues The `--restart unless-stopped` flag handles most transient failures. If the gateway is stuck, restart the container: `sh docker restart hermes` ### Checking container health `sh docker logs --tail 50 hermes # Recent logs docker run -it --rm nousresearch/hermes-agent:latest version # Verify version docker stats hermes # Resource usage` — # Security # Security Hermes Agent is designed with a defense-in-depth security model. This page covers every security boundary — from command approval to container isolation to user authorization on messaging platforms. ## Overview The security model has seven layers: 1. User authorization — who can talk to the agent (allowlists, DM pairing) 2. Dangerous command approval — human-in-the-loop for destructive operations 3. Container isolation — Docker/Singularity/Modal sandboxing with hardened settings 4. MCP credential filtering — environment variable isolation for MCP subprocesses 5. Context file scanning — prompt injection detection in project files 6. Cross-session isolation — sessions cannot access each other’s data or state; cron job storage paths are hardened against path traversal attacks 7. Input sanitization — working directory parameters in terminal tool backends are validated against an allowlist to prevent shell injection ## Dangerous Command Approval Before executing any command, Hermes checks it against a curated list of dangerous patterns. If a match is found, the user must explicitly approve it. ### Approval Modes The approval system supports three modes, configured via `approvals.mode` in `~/.hermes/config.yaml`: `yaml approvals: mode: manual # manual | smart | off timeout: 60 # seconds to wait for user response (default: 60) cron_mode: deny # deny | approve — what cron jobs do when they hit a dangerous command mcp_reload_confirm: true # /reload-mcp asks before invalidating the MCP tool cache destructive_slash_confirm: true # /clear, /new, /reset, /undo prompt before discarding state` The full set of keys: | Key | Default | What it controls | |—|—|—| | `mode` | `manual` | Approval policy for dangerous shell commands — see the table below. | | `timeout` | `60` | Seconds Hermes waits for an approval reply before timing out. | | `cron_mode` | `deny` | How cron jobs behave headlessly when they trigger a dangerous-command prompt. `deny` blocks the command (the agent must find another path); `approve` auto-approves everything in cron context. | | `mcp_reload_confirm` | `true` | When true, `/reload-mcp` asks before rebuilding the MCP tool set. Rebuilding invalidates the provider prompt cache (tool schemas live in the system prompt), so the next message re-sends full input tokens. Users who click Always Approve flip this key to `false`. | | `destructive_slash_confirm` | `true` | When true, destructive session slash commands (`/clear`, `/new`, `/reset`, `/undo`) prompt before discarding conversation state. Three-option dialog (Approve Once / Always Approve / Cancel) routed through native yes/no buttons on Telegram, Discord, and Slack; text fallback elsewhere. Users who click Always Approve flip this key to `false`. TUI uses its own modal overlay (set `HERMES_TUI_NO_CONFIRM=1` to opt out there). | | Mode | Behavior | |——|–––––| | manual (default) | Always prompt the user for approval on dangerous commands | | smart | Use an auxiliary LLM to assess risk. Low-risk commands (e.g., `python -c "print('hello')"`) are auto-approved. Genuinely dangerous commands are auto-denied. Uncertain cases escalate to a manual prompt. | | off | Disable all approval checks — equivalent to running with `--yolo`. All commands execute without prompts. | :::warning Setting `approvals.mode: off` disables all safety prompts. Use only in trusted environments (CI/CD, containers, etc.). ::: ### YOLO Mode YOLO mode bypasses all dangerous command approval prompts for the current session. It can be activated three ways: 1. CLI flag: Start a session with `hermes --yolo` or `hermes chat --yolo` 2. Slash command: Type `/yolo` during a session to toggle it on/off 3. Environment variable: Set `HERMES_YOLO_MODE=1` The `/yolo` command is a toggle — each use flips the mode on or off: `> /yolo ⚡ YOLO mode ON — all commands auto-approved. Use with caution. > /yolo ⚠ YOLO mode OFF — dangerous commands will require approval.` YOLO mode is available in both CLI and gateway sessions. Internally, it sets the `HERMES_YOLO_MODE` environment variable which is checked before every command execution. When YOLO is active, Hermes shows two persistent visual reminders so it’s hard to forget that approval prompts are bypassed: - A red banner line at session start when YOLO is already active: `⚠ YOLO mode — all approval prompts bypassed`. Hidden when YOLO is off so the default banner stays uncluttered. - A `⚠ YOLO` fragment in the status bar across all width tiers, updated live as you toggle YOLO on or off (rich-text renderer and plain-text fallback). :::danger YOLO mode disables all dangerous command safety checks for the session — except the hardline blocklist (see below). Use only when you fully trust the commands being generated (e.g., well-tested automation scripts in disposable environments). ::: For destructive session slash commands (`/clear`, `/new` / `/reset`, `/undo`, `/quit --delete` — `/exit --delete` is an alias), the CLI also prompts for confirmation before running them. See Slash Commands — Confirmation prompts for destructive commands. ### Hardline Blocklist (Always-On Floor) Some commands are so catastrophic — irreversible filesystem wipes, fork bombs, direct block-device writes — that Hermes refuses to run them regardless of: - `--yolo` / `/yolo` toggled on - `approvals.mode: off` - Cron jobs running in headless `approve` mode - User explicitly clicking “allow always” The blocklist is the floor below `--yolo`. It trips before the approval layer even sees the command, and there’s no override flag. Patterns currently covered (not exhaustive; kept in sync with `tools/approval.py::UNRECOVERABLE_BLOCKLIST`): | Pattern | Why it’s hardline | |—|—| | `rm -rf /` and obvious variants | Wipes the filesystem root | | `rm -rf --no-preserve-root /` | The explicit “yes I mean root” variant | | `:(){ :\|:& };:` (bash fork bomb) | Pegs the host until reboot | | `mkfs.` on a mounted root device | Formats the live system | | `dd if=/dev/zero of=/dev/sd` | Zeroes a physical disk | | Piping untrusted URLs to `sh` at the rootfs top level | Remote-code-execution attack vector too broad to approve | If you hit the blocklist, the tool call returns an explanatory error to the agent and nothing runs. If a legitimate workflow needs one of these commands (you’re the operator of a wipe-and-reinstall pipeline, for example), run it outside the agent. ### Approval Timeout When a dangerous command prompt appears, the user has a configurable amount of time to respond. If no response is given within the timeout, the command is denied by default (fail-closed). Configure the timeout in `~/.hermes/config.yaml`: `yaml approvals: timeout: 60 # seconds (default: 60)` ### What Triggers Approval The following patterns trigger approval prompts (defined in `tools/approval.py`): | Pattern | Description | |———|———––| | `rm -r` / `rm --recursive` | Recursive delete | | `rm ... /` | Delete in root path | | `chmod 777/666` / `o+w` / `a+w` | World/other-writable permissions | | `chmod --recursive` with unsafe perms | Recursive world/other-writable (long flag) | | `chown -R root` / `chown --recursive root` | Recursive chown to root | | `mkfs` | Format filesystem | | `dd if=` | Disk copy | | `> /dev/sd` | Write to block device | | `DROP TABLE/DATABASE` | SQL DROP | | `DELETE FROM` (without WHERE) | SQL DELETE without WHERE | | `TRUNCATE TABLE` | SQL TRUNCATE | | `> /etc/` | Overwrite system config | | `systemctl stop/restart/disable/mask` | Stop/restart/disable system services | | `kill -9 -1` | Kill all processes | | `pkill -9` | Force kill processes | | Fork bomb patterns | Fork bombs | | `bash -c` / `sh -c` / `zsh -c` / `ksh -c` | Shell command execution via `-c` flag (including combined flags like `-lc`) | | `python -e` / `perl -e` / `ruby -e` / `node -c` | Script execution via `-e`/`-c` flag | | `curl ... \| sh` / `wget ... \| sh` | Pipe remote content to shell | | `bash <(curl ...)` / `sh <(wget ...)` | Execute remote script via process substitution | | `tee` to `/etc/`, `~/.ssh/`, `~/.hermes/.env` | Overwrite sensitive file via tee | | `>` / `>>` to `/etc/`, `~/.ssh/`, `~/.hermes/.env` | Overwrite sensitive file via redirection | | `xargs rm` | xargs with rm | | `find -exec rm` / `find -delete` | Find with destructive actions | | `cp`/`mv`/`install` to `/etc/` | Copy/move file into system config | | `sed -i` / `sed --in-place` on `/etc/` | In-place edit of system config | | `pkill`/`killall` hermes/gateway | Self-termination prevention | | `gateway run` with `&`/`disown`/`nohup`/`setsid` | Prevents starting gateway outside service manager | :::info Container bypass: When running in `docker`, `singularity`, `modal`, or `daytona` backends, dangerous command checks are skipped because the container itself is the security boundary. Destructive commands inside a container can’t harm the host. ::: ### Approval Flow (CLI) In the interactive CLI, dangerous commands show an inline approval prompt: `⚠️ DANGEROUS COMMAND: recursive delete rm -rf /tmp/old-project [o]nce | [s]ession | [a]lways | [d]eny Choice [o/s/a/D]:` The four options: - once — allow this single execution - session — allow this pattern for the rest of the session - always — add to permanent allowlist (saved to `config.yaml`) - deny (default) — block the command ### Approval Flow (Gateway/Messaging) On messaging platforms, the agent sends the dangerous command details to the chat and waits for the user to reply: - Reply yes, y, approve, ok, or go to approve - Reply no, n, deny, or cancel to deny The `HERMES_EXEC_ASK=1` environment variable is automatically set when running the gateway. ### Permanent Allowlist Commands approved with “always” are saved to `~/.hermes/config.yaml`: `yaml # Permanently allowed dangerous command patterns command_allowlist: - rm - systemctl` These patterns are loaded at startup and silently approved in all future sessions. :::tip Use `hermes config edit` to review or remove patterns from your permanent allowlist. ::: ## User Authorization (Gateway) When running the messaging gateway, Hermes controls who can interact with the bot through a layered authorization system. ### Authorization Check Order The `_is_user_authorized()` method checks in this order: 1. Per-platform allow-all flag (e.g., `DISCORD_ALLOW_ALL_USERS=true`) 2. DM pairing approved list (users approved via pairing codes) 3. Platform-specific allowlists (e.g., `TELEGRAM_ALLOWED_USERS=12345,67890`) 4. Global allowlist (`GATEWAY_ALLOWED_USERS=12345,67890`) 5. Global allow-all (`GATEWAY_ALLOW_ALL_USERS=true`) 6. Default: deny ### Platform Allowlists Set allowed user IDs as comma-separated values in `~/.hermes/.env`: `bash # Platform-specific allowlists TELEGRAM_ALLOWED_USERS=123456789,987654321 DISCORD_ALLOWED_USERS=111222333444555666 WHATSAPP_ALLOWED_USERS=15551234567 SLACK_ALLOWED_USERS=U01ABC123 # Cross-platform allowlist (checked for all platforms) GATEWAY_ALLOWED_USERS=123456789 # Per-platform allow-all (use with caution) DISCORD_ALLOW_ALL_USERS=true # Global allow-all (use with extreme caution) GATEWAY_ALLOW_ALL_USERS=true` :::warning If no allowlists are configured and `GATEWAY_ALLOW_ALL_USERS` is not set, all users are denied. The gateway logs a warning at startup: `No user allowlists configured. All unauthorized users will be denied. Set GATEWAY_ALLOW_ALL_USERS=true in ~/.hermes/.env to allow open access, or configure platform allowlists (e.g., TELEGRAM_ALLOWED_USERS=your_id).` ::: ### DM Pairing System For more flexible authorization, Hermes includes a code-based pairing system. Instead of requiring user IDs upfront, unknown users receive a one-time pairing code that the bot owner approves via the CLI. How it works: 1. An unknown user sends a DM to the bot 2. The bot replies with an 8-character pairing code 3. The bot owner runs `hermes pairing approve <platform> <code>` on the CLI 4. The user is permanently approved for that platform Control how unauthorized direct messages are handled in `~/.hermes/config.yaml`: `yaml unauthorized_dm_behavior: pair whatsapp: unauthorized_dm_behavior: ignore` - `pair` is the default. Unauthorized DMs get a pairing code reply. - `ignore` silently drops unauthorized DMs. - Platform sections override the global default, so you can keep pairing on Telegram while keeping WhatsApp silent. Security features (based on OWASP + NIST SP 800-63-4 guidance): | Feature | Details | |———|———| | Code format | 8-char from 32-char unambiguous alphabet (no 0/O/1/I) | | Randomness | Cryptographic (`secrets.choice()`) | | Code TTL | 1 hour expiry | | Rate limiting | 1 request per user per 10 minutes | | Pending limit | Max 3 pending codes per platform | | Lockout | 5 failed approval attempts → 1-hour lockout | | File security | `chmod 0600` on all pairing data files | | Logging | Codes are never logged to stdout | Pairing CLI commands: `bash # List pending and approved users hermes pairing list # Approve a pairing code hermes pairing approve telegram ABC12DEF # Revoke a user's access hermes pairing revoke telegram 123456789 # Clear all pending codes hermes pairing clear-pending` Storage: Pairing data is stored in `~/.hermes/pairing/` with per-platform JSON files: - `{platform}-pending.json` — pending pairing requests - `{platform}-approved.json` — approved users - `_rate_limits.json` — rate limit and lockout tracking ## Container Isolation When using the `docker` terminal backend, Hermes applies strict security hardening to every container. ### Docker Security Flags Every container runs with these flags (defined in `tools/environments/docker.py`): python _BASE_SECURITY_ARGS = [ "--cap-drop", "ALL", # Drop ALL Linux capabilities "--cap-add", "DAC_OVERRIDE", # Root can write to bind-mounted dirs "--cap-add", "CHOWN", # Package managers need file ownership "--cap-add", "FOWNER", # Package managers need file ownership "--security-opt", "no-new-privileges", # Block privilege escalation "--pids-limit", "256", # Limit process count "--tmpfs", "/tmp:rw,nosuid,size=512m", # Size-limited /tmp "--tmpfs", "/var/tmp:rw,noexec,nosuid,size=256m", # No-exec /var/tmp ] `SETUID`/`SETGID` are not in the base list — they’re added conditionally when the container starts as root and an init/entrypoint must drop privileges (the s6 privilege-drop path). They’re skipped when the container already runs as a non-root `--user`. The `/run` tmpfs is also split out from the base list and mounted per-image (hardened `noexec` by default, `exec` only for s6-overlay images that exec from `/run`). ### Resource Limits Container resources are configurable in `~/.hermes/config.yaml`: `yaml terminal: backend: docker docker_image: "nikolaik/python-nodejs:python3.11-nodejs20" docker_forward_env: [] # Explicit allowlist only; empty keeps secrets out of the container container_cpu: 1 # CPU cores container_memory: 5120 # MB (default 5GB) container_disk: 51200 # MB (default 50GB, requires overlay2 on XFS) container_persistent: true # Persist filesystem across sessions` ### Filesystem Persistence - Persistent mode (`container_persistent: true`): Bind-mounts `/workspace` and `/root` from `~/.hermes/sandboxes/docker/<task_id>/` - Ephemeral mode (`container_persistent: false`): Uses tmpfs for workspace — everything is lost on cleanup :::tip For production gateway deployments, use `docker`, `modal`, or `daytona` backend to isolate agent commands from your host system. This eliminates the need for dangerous command approval entirely. ::: :::warning If you add names to `terminal.docker_forward_env`, those variables are intentionally injected into the container for terminal commands. This is useful for task-specific credentials like `GITHUB_TOKEN`, but it also means code running in the container can read and exfiltrate them. ::: ## Terminal Backend Security Comparison | Backend | Isolation | Dangerous Cmd Check | Best For | |———|———–|—————––|–––––| | local | None — runs on host | ✅ Yes | Development, trusted users | | ssh | Remote machine | ✅ Yes | Running on a separate server | | docker | Container | ❌ Skipped (container is boundary) | Production gateway | | singularity | Container | ❌ Skipped | HPC environments | | modal | Cloud sandbox | ❌ Skipped | Scalable cloud isolation | | daytona | Cloud sandbox | ❌ Skipped | Persistent cloud workspaces | ## Environment Variable Passthrough {#environment-variable-passthrough} Both `execute_code` and `terminal` strip sensitive environment variables from child processes to prevent credential exfiltration by LLM-generated code. However, skills that declare `required_environment_variables` legitimately need access to those vars. ### How It Works Two mechanisms allow specific variables through the sandbox filters: 1. Skill-scoped passthrough (automatic) When a skill is loaded (via `skill_view` or the `/skill` command) and declares `required_environment_variables`, any of those vars that are actually set in the environment are automatically registered as passthrough. Missing vars (still in setup-needed state) are not registered. `yaml # In a skill's SKILL.md frontmatter required_environment_variables: - name: TENOR_API_KEY prompt: Tenor API key help: Get a key from https://developers.google.com/tenor` After loading this skill, `TENOR_API_KEY` passes through to `execute_code`, `terminal` (local), and remote backends (Docker, Modal) — no manual configuration needed. :::info Docker & Modal Prior to v0.5.1, Docker’s `forward_env` was a separate system from the skill passthrough. They are now merged — skill-declared env vars are automatically forwarded into Docker containers and Modal sandboxes without needing to add them to `docker_forward_env` manually. ::: 2. Config-based passthrough (manual) For env vars not declared by any skill, add them to `terminal.env_passthrough` in `config.yaml`: `yaml terminal: env_passthrough: - MY_CUSTOM_KEY - ANOTHER_TOKEN` ### Credential File Passthrough (OAuth tokens, etc.) {#credential-file-passthrough} Some skills need files (not just env vars) in the sandbox — for example, Google Workspace stores OAuth tokens as `google_token.json` under the active profile’s `HERMES_HOME`. Skills declare these in frontmatter: `yaml required_credential_files: - path: google_token.json description: Google OAuth2 token (created by setup script) - path: google_client_secret.json description: Google OAuth2 client credentials` When loaded, Hermes checks if these files exist in the active profile’s `HERMES_HOME` and registers them for mounting: - Docker: Read-only bind mounts (`-v host:container:ro`) - Modal: Mounted at sandbox creation + synced before each command (handles mid-session OAuth setup) - Local: No action needed (files already accessible) You can also list credential files manually in `config.yaml`: `yaml terminal: credential_files: - google_token.json - my_custom_oauth_token.json` Paths are relative to `~/.hermes/`. Files are mounted to `/root/.hermes/` inside the container. This list is read by `tools/credential_files.py` (`terminal.credential_files`) — it lives under the `terminal:` block but is loaded by the credential-files module, not the core terminal backend, so it isn’t part of the bundled `DEFAULT_CONFIG` snapshot. ### What Each Sandbox Filters | Sandbox | Default Filter | Passthrough Override | |———|—————|———————| | execute_code | Blocks vars containing `KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `CREDENTIAL`, `PASSWD`, `AUTH` in name; only allows safe-prefix vars through | ✅ Passthrough vars bypass both checks | | terminal (local) | Blocks explicit Hermes infrastructure vars (provider keys, gateway tokens, tool API keys) | ✅ Passthrough vars bypass the blocklist | | terminal (Docker) | No host env vars by default | ✅ Passthrough vars + `docker_forward_env` forwarded via `-e` | | terminal (Modal) | No host env/files by default | ✅ Credential files mounted; env passthrough via sync | | MCP | Blocks everything except safe system vars + explicitly configured `env` | ❌ Not affected by passthrough (use MCP `env` config instead) | ### Security Considerations - The passthrough only affects vars you or your skills explicitly declare — the default security posture is unchanged for arbitrary LLM-generated code - Credential files are mounted read-only into Docker containers - Skills Guard scans skill content for suspicious env access patterns before installation - Missing/unset vars are never registered (you can’t leak what doesn’t exist) - Hermes infrastructure secrets (provider API keys, gateway tokens) should never be added to `env_passthrough` — they have dedicated mechanisms ## MCP Credential Handling MCP (Model Context Protocol) server subprocesses receive a filtered environment to prevent accidental credential leakage. ### Safe Environment Variables Only these variables are passed through from the host to MCP stdio subprocesses: `PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL, TMPDIR` Plus any `XDG_` variables. All other environment variables (API keys, tokens, secrets) are stripped. Variables explicitly defined in the MCP server’s `env` config are passed through: `yaml mcp_servers: github: command: "npx" args: ["-y", "@modelcontextprotocol/server-github"] env: GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..." # Only this is passed` ### Credential Redaction Error messages from MCP tools are sanitized before being returned to the LLM. The following patterns are replaced with `[REDACTED]`: - GitHub PATs (`ghp_...`) - OpenAI-style keys (`sk-...`) - Bearer tokens - `token=`, `key=`, `API_KEY=`, `password=`, `secret=` parameters ### Website Access Policy You can restrict which websites the agent can access through its web and browser tools. This is useful for preventing the agent from accessing internal services, admin panels, or other sensitive URLs. `yaml # In ~/.hermes/config.yaml security: website_blocklist: enabled: true domains: - ".internal.company.com" - "admin.example.com" shared_files: - "/etc/hermes/blocked-sites.txt"` When a blocked URL is requested, the tool returns an error explaining the domain is blocked by policy. The blocklist is enforced across `web_search`, `web_extract`, `browser_navigate`, and all URL-capable tools. See Website Blocklist in the configuration guide for full details. ### SSRF Protection All URL-capable tools (web search, web extract, vision, browser) validate URLs before fetching them to prevent Server-Side Request Forgery (SSRF) attacks. Blocked addresses include: - Private networks (RFC 1918): `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` - Loopback: `127.0.0.0/8`, `::1` - Link-local: `169.254.0.0/16` (includes cloud metadata at `169.254.169.254`) - CGNAT / shared address space (RFC 6598): `100.64.0.0/10` (Tailscale, WireGuard VPNs) - Cloud metadata hostnames: `metadata.google.internal`, `metadata.goog` - Reserved, multicast, and unspecified addresses SSRF protection is always active for internet-facing use and DNS failures are treated as blocked (fail-closed). Redirect chains are re-validated at each hop to prevent redirect-based bypasses. #### Intentionally allowing private URLs Some setups legitimately need private/internal URL access — home networks that resolve `home.arpa` to RFC 1918 space, LAN-only Ollama/llama.cpp endpoints, internal wikis, cloud metadata debugging, and the like. For those cases there’s a global opt-out: `yaml security: allow_private_urls: true # default: false` When on, web tools, the browser, vision URL fetches, and gateway media downloads no longer reject RFC 1918 / loopback / link-local / CGNAT / cloud-metadata destinations. This is a deliberate trust boundary — only enable it on machines where the agent running arbitrary prompt-injected URLs against the local network is an acceptable risk. Public-facing gateways should leave it off. The host-substring guard (which blocks lookalike Unicode domain tricks even when the underlying IP is public) stays on regardless of this setting. ### Tirith Pre-Exec Security Scanning Hermes integrates tirith for content-level command scanning before execution. Tirith detects threats that pattern matching alone misses: - Homograph URL spoofing (internationalized domain attacks) - Pipe-to-interpreter patterns (`curl | bash`, `wget | sh`) - Terminal injection attacks Tirith auto-installs from GitHub releases on first use with SHA-256 checksum verification (and cosign provenance verification if cosign is available). `yaml # In ~/.hermes/config.yaml security: tirith_enabled: true # Enable/disable tirith scanning (default: true) tirith_path: "tirith" # Path to tirith binary (default: PATH lookup) tirith_timeout: 5 # Subprocess timeout in seconds tirith_fail_open: true # Allow execution when tirith is unavailable (default: true)` When `tirith_fail_open` is `true` (default), commands proceed if tirith is not installed or times out. Set to `false` in high-security environments to block commands when tirith is unavailable. Tirith ships prebuilt binaries for Linux (x86_64 / aarch64) and macOS (x86_64 / arm64). On platforms with no prebuilt binary (Windows, etc.), tirith is silently skipped — pattern-matching guards still run, and the CLI does not surface an “unavailable” banner. To use tirith on Windows, run Hermes under WSL. Tirith’s verdict integrates with the approval flow: safe commands pass through, while both suspicious and blocked commands trigger user approval with the full tirith findings (severity, title, description, safer alternatives). Users can approve or deny — the default choice is deny to keep unattended scenarios secure. ### Context File Injection Protection Context files (AGENTS.md, .cursorrules, SOUL.md) are scanned for prompt injection before being included in the system prompt. The scanner checks for: - Instructions to ignore/disregard prior instructions - Hidden HTML comments with suspicious keywords - Attempts to read secrets (`.env`, `credentials`, `.netrc`) - Credential exfiltration via `curl` - Invisible Unicode characters (zero-width spaces, bidirectional overrides) Blocked files show a warning: `[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]` ## Best Practices for Production Deployment ### Gateway Deployment Checklist 1. Set explicit allowlists — never use `GATEWAY_ALLOW_ALL_USERS=true` in production 2. Use container backend — set `terminal.backend: docker` in config.yaml 3. Restrict resource limits — set appropriate CPU, memory, and disk limits 4. Store secrets securely — keep API keys in `~/.hermes/.env` with proper file permissions 5. Enable DM pairing — use pairing codes instead of hardcoding user IDs when possible 6. Review command allowlist — periodically audit `command_allowlist` in config.yaml 7. Set `terminal.cwd` — don’t let the agent operate from sensitive directories 8. Run as non-root — never run the gateway as root 9. Monitor logs — check `~/.hermes/logs/` for unauthorized access attempts 10. Keep updated — run `hermes update` regularly for security patches ### Securing API Keys `bash # Set proper permissions on the .env file chmod 600 ~/.hermes/.env # Keep separate keys for different services # Never commit .env files to version control` ### Network Isolation For maximum security, run the gateway on a separate machine or VM. Set `terminal.backend: ssh` in `config.yaml`, then provide host details via environment variables in `~/.hermes/.env`: `yaml # ~/.hermes/config.yaml terminal: backend: ssh` `bash # ~/.hermes/.env TERMINAL_SSH_HOST=agent-worker.local TERMINAL_SSH_USER=hermes TERMINAL_SSH_KEY=~/.ssh/hermes_agent_key` The SSH connection details live in `.env` (not `config.yaml`) so they aren’t checked in or shared along with profile exports. This keeps the gateway’s messaging connections separate from the agent’s command execution. ## Supply-chain advisory checking Hermes ships with a built-in advisory scanner that flags Python packages in the active venv that match a curated catalog of known-compromised versions (supply-chain worms like the May 2026 `mistralai 2.4.6` poisoning). Implementation lives in `hermes_cli/security_advisories.py`. How it runs: - CLI startup banner. A one-line warning is printed if any advisory matches, with a pointer to `hermes doctor` for the full remediation. - `hermes doctor`. Surfaces every active advisory with version specifics and 2-4 step remediation instructions. - Gateway startup. Logged to `gateway.log`; the first interactive message gets a short operator banner. Each advisory carries a stable id. Once you have read and acted on it you can dismiss it for good: `bash hermes doctor --ack <advisory-id>` The ack is persisted to `config.security.acked_advisories` and survives restart. Old advisories are intentionally not removed from the catalog — leaving them in place keeps fresh installs warned about historically poisoned versions that might still be cached in a private mirror. The check itself is stdlib-only and runs from one `importlib.metadata.version()` lookup per advisory, so it’s safe to run on every startup. ### Lazy install of optional dependencies Many features (Mistral TTS, ElevenLabs, Honcho memory, Bedrock, Slack, Matrix, …) depend on Python packages that not every user needs. Hermes installs these lazily on first use rather than eagerly under `hermes-agent[all]`. The implementation lives in `tools/lazy_deps.py`. The trade-off this fixes: - Fragility. When one extra’s transitive dependency becomes unavailable on PyPI (quarantined for malware, yanked, broken upload), the entire `[all]` resolve would fail and fresh installs would silently fall back to a stripped tier — losing 10+ unrelated extras at once. Lazy install isolates each backend so one poisoned dep can’t break unrelated features. - Bloat. A user who only ever talks to one provider no longer pulls hundreds of packages they will never import. How it works: 1. A backend module calls `ensure("feature.name")` at the top of its first-import path. 2. If the deps are missing, `ensure` checks `security.allow_lazy_installs` in `config.yaml` (default `true`) and runs a venv-scoped `pip install` for the allowlisted specs. 3. If the install fails or the user has disabled lazy installs, the call raises `FeatureUnavailable` with the actual pip stderr and a pointer at `hermes tools`. Security guarantees enforced by `tools/lazy_deps.py`: | Guarantee | What it means | |—|—| | Venv-scoped only | Installs target `sys.executable` in the active venv — never the system Python | | PyPI by name only | Specs accept `"package>=1.0,<2"` syntax. No `--index-url`, `git+https://`, or file: paths — a malicious `config.yaml` cannot redirect the install | | Allowlist | Only specs that appear in the in-tree `LAZY_DEPS` map can be installed via this path. A typo in a feature name does NOT get install-anything semantics | | Opt-out | Set `security.allow_lazy_installs: false` to disable runtime installs entirely. Useful for restricted networks or strict security postures | | No silent retries | Failures surface as `FeatureUnavailable` — no caching of bad state, no retry storms | To disable runtime installs: `yaml # ~/.hermes/config.yaml security: allow_lazy_installs: false` When disabled, backends that need optional deps will tell the user to run the install manually (`pip install …`) or pick a different backend via `hermes tools`. — # Checkpoints and /rollback # Checkpoints and `/rollback` Hermes Agent can automatically snapshot your project before destructive operations and restore it with a single command. Checkpoints are opt-in as of v2 — most users never use `/rollback`, and the shadow-store storage is non-trivial over time, so the default is off. Enable checkpoints per-session with `--checkpoints`: `bash hermes chat --checkpoints` Or enable globally in `~/.hermes/config.yaml`: `yaml checkpoints: enabled: true` This safety net is powered by an internal Checkpoint Manager that keeps a single shared shadow git repository under `~/.hermes/checkpoints/store/` — your real project `.git` is never touched. Every project the agent works in shares the same store, so git’s content-addressable object DB deduplicates across projects and across turns. ## What Triggers a Checkpoint Checkpoints are taken automatically before: - File tools — `write_file` and `patch` - Destructive terminal commands — `rm`, `rmdir`, `cp`, `install`, `mv`, `sed -i`, `truncate`, `dd`, `shred`, output redirects (`>`), and `git reset`/`clean`/`checkout` The agent creates at most one checkpoint per directory per turn, so long-running sessions don’t spam snapshots. ## Quick Reference In-session slash commands: | Command | Description | |———|———––| | `/rollback` | List all checkpoints with change stats | | `/rollback <N>` | Restore to checkpoint N (also undoes last chat turn) | | `/rollback diff <N>` | Preview diff between checkpoint N and current state | | `/rollback <N> <file>` | Restore a single file from checkpoint N | CLI for inspecting and managing the store outside a session: | Command | Description | |———|———––| | `hermes checkpoints` | Show total size, project count, per-project breakdown | | `hermes checkpoints status` | Same as bare `checkpoints` | | `hermes checkpoints list` | Alias for `status` | | `hermes checkpoints prune` | Force a sweep: delete orphans/stale, GC, enforce size cap | | `hermes checkpoints clear` | Nuke the entire checkpoint base (asks first) | | `hermes checkpoints clear-legacy` | Delete only the `legacy-` archives from v1 migration | ## How Checkpoints Work At a high level: - Hermes detects when tools are about to modify files in your working tree. - Once per conversation turn (per directory), it: - Resolves a reasonable project root for the file. - Initialises or reuses the single shared shadow store at `~/.hermes/checkpoints/store/`. - Stages into a per-project index, builds a tree, and commits to a per-project ref (`refs/hermes/<project-hash>`). - These per-project refs form a checkpoint history that you can inspect and restore via `/rollback`. `mermaid flowchart LR user["User command\n(hermes, gateway)"] agent["AIAgent\n(run_agent.py)"] tools["File & terminal tools"] cpMgr["CheckpointManager"] store["Shared shadow store\n~/.hermes/checkpoints/store/"] user --> agent agent -->|"tool call"| tools tools -->|"before mutate\nensure_checkpoint()"| cpMgr cpMgr -->|"git add/commit-tree/update-ref"| store cpMgr -->|"OK / skipped"| tools tools -->|"apply changes"| agent` ## Configuration Configure in `~/.hermes/config.yaml`: yaml checkpoints: enabled: false # master switch (default: false — opt-in) max_snapshots: 20 # max checkpoints per project (enforced via ref rewrite + gc) max_total_size_mb: 500 # hard cap on total store size; oldest commits dropped max_file_size_mb: 10 # skip any single file larger than this # Auto-maintenance (on by default): sweep ~/.hermes/checkpoints/ at startup # and delete project entries whose working directory no longer exists # (orphans) or whose last_touch is older than retention_days. Runs at most # once per min_interval_hours, tracked via a .last_prune marker. auto_prune: true retention_days: 7 delete_orphans: true min_interval_hours: 24 To disable everything: `yaml checkpoints: enabled: false auto_prune: false` When `enabled: false`, the Checkpoint Manager is a no-op and never attempts git operations. When `auto_prune: false`, the store grows until you run `hermes checkpoints prune` manually. ## Listing Checkpoints From a CLI session: `/rollback` Hermes responds with a formatted list showing change statistics: `text 📸 Checkpoints for /path/to/project: 1. 4270a8c 2026-03-16 04:36 before patch (1 file, +1/-0) 2. eaf4c1f 2026-03-16 04:35 before write_file 3. b3f9d2e 2026-03-16 04:34 before terminal: sed -i s/old/new/ config.py (1 file, +1/-1) /rollback <N> restore to checkpoint N /rollback diff <N> preview changes since checkpoint N /rollback <N> <file> restore a single file from checkpoint N` ## Inspecting the Store from the Shell `bash hermes checkpoints` Sample output: `text Checkpoint base: /home/you/.hermes/checkpoints Total size: 142.3 MB store/ 138.1 MB legacy- 4.2 MB Projects: 12 WORKDIR COMMITS LAST TOUCH STATE /home/you/code/hermes-agent 20 2h ago live /home/you/code/experiments/rl-runner 8 1d ago live /home/you/code/old-prototype 3 9d ago orphan ... Legacy archives (1): legacy-20260506-050616 4.2 MB Clear with: hermes checkpoints clear-legacy` Force a full sweep (ignores the 24h idempotency marker): `bash hermes checkpoints prune --retention-days 3 --max-size-mb 200` ## Previewing Changes with `/rollback diff` Before committing to a restore, preview what has changed since a checkpoint: `/rollback diff 1` This shows a git diff stat summary followed by the actual diff. ## Restoring with `/rollback` `/rollback 1` Behind the scenes, Hermes: 1. Verifies the target commit exists in the shadow store. 2. Takes a pre-rollback snapshot of the current state so you can “undo the undo” later. 3. Restores tracked files in your working directory. 4. Undoes the last conversation turn so the agent’s context matches the restored filesystem state. ## Single-File Restore Restore just one file from a checkpoint without affecting the rest of the directory: `/rollback 1 src/broken_file.py` ## Safety and Performance Guards - Git availability — if `git` is not found on `PATH`, checkpoints are transparently disabled. - Directory scope — Hermes skips overly broad directories (root `/`, home `$HOME`). - Repository size — directories with more than 50,000 files are skipped. - Per-file size cap — files larger than `max_file_size_mb` (default 10 MB) are excluded from the snapshot. Prevents accidentally swallowing datasets, model weights, or generated media. - Total store size cap — when the store exceeds `max_total_size_mb` (default 500 MB), the oldest commit per project is dropped round-robin until under the cap. - Real pruning — `max_snapshots` is enforced by rewriting the per-project ref and running `git gc --prune=now` afterwards, so loose objects don’t accumulate. - No-change snapshots — if there are no changes since the last snapshot, the checkpoint is skipped. - Non-fatal errors — all errors inside the Checkpoint Manager are logged at debug level; your tools continue to run. ## Where Checkpoints Live `text ~/.hermes/checkpoints/ ├── store/ # single shared bare git repo │ ├── HEAD, objects/ # git internals (shared across projects) │ ├── refs/hermes/<hash> # per-project branch tip │ ├── indexes/<hash> # per-project git index │ ├── projects/<hash>.json # workdir + created_at + last_touch │ └── info/exclude ├── .last_prune # auto-prune idempotency marker └── legacy-<ts>/ # archived pre-v2 per-project shadow repos` Each `<hash>` is derived from the absolute path of the working directory. You normally never need to touch these manually — use `hermes checkpoints status` / `prune` / `clear` instead. ### Migration from v1 Before the v2 rewrite, each working directory got its own complete shadow git repo directly under `~/.hermes/checkpoints/<hash>/`. That layout couldn’t dedup objects across projects and had a documented no-op pruner — the store would grow without bound. On first v2 run, any pre-v2 shadow repos are moved into `~/.hermes/checkpoints/legacy-<timestamp>/` so the new single-store layout starts clean. Old `/rollback` history is still reachable by manually inspecting the legacy archive with `git`; once you’re confident you don’t need it, run: `bash hermes checkpoints clear-legacy` to reclaim the space. Legacy archives are also swept by `auto_prune` after `retention_days`. ## Best Practices - Enable checkpoints only when you need them — `hermes chat --checkpoints` or per-profile `enabled: true`. - Use `/rollback diff` before restoring — preview what will change to pick the right checkpoint. - Use `/rollback` instead of `git reset` when you want to undo agent-driven changes only. - Check `hermes checkpoints status` occasionally if you use checkpoints regularly — shows which projects are active and what the store costs you. - Combine with Git worktrees for maximum safety — keep each Hermes session in its own worktree/branch, with checkpoints as an extra layer. For running multiple agents in parallel on the same repo, see the guide on Git worktrees. — # Features Overview # Features Overview Hermes Agent includes a rich set of capabilities that extend far beyond basic chat. From persistent memory and file-aware context to browser automation and voice conversations, these features work together to make Hermes a powerful autonomous assistant. :::tip Don’t know where to start? `hermes setup --portal` covers a model provider plus all four Tool Gateway tools (web search, image generation, TTS, browser) in one command. See Nous Portal. ::: ## Core - Tools & Toolsets — Tools are functions that extend the agent’s capabilities. They’re organized into logical toolsets that can be enabled or disabled per platform, covering web search, terminal execution, file editing, memory, delegation, and more. - Skills System — On-demand knowledge documents the agent can load when needed. Skills follow a progressive disclosure pattern to minimize token usage and are compatible with the agentskills.io open standard. - Persistent Memory — Bounded, curated memory that persists across sessions. Hermes remembers your preferences, projects, environment, and things it has learned via `MEMORY.md` and `USER.md`. - Context Files — Hermes automatically discovers and loads project context files (`.hermes.md`, `AGENTS.md`, `CLAUDE.md`, `SOUL.md`, `.cursorrules`) that shape how it behaves in your project. - Context References — Type `@` followed by a reference to inject files, folders, git diffs, and URLs directly into your messages. Hermes expands the reference inline and appends the content automatically. - Checkpoints — Hermes automatically snapshots your working directory before making file changes, giving you a safety net to roll back with `/rollback` if something goes wrong. ## Automation - Scheduled Tasks (Cron) — Schedule tasks to run automatically with natural language or cron expressions. Jobs can attach skills, deliver results to any platform, and support pause/resume/edit operations. - Subagent Delegation — The `delegate_task` tool spawns child agent instances with isolated context, restricted toolsets, and their own terminal sessions. Run 3 concurrent subagents by default (configurable) for parallel workstreams. - Code Execution — The `execute_code` tool lets the agent write Python scripts that call Hermes tools programmatically, collapsing multi-step workflows into a single LLM turn via sandboxed RPC execution. - Event Hooks — Run custom code at key lifecycle points. Gateway hooks handle logging, alerts, and webhooks; plugin hooks handle tool interception, metrics, and guardrails. - Batch Processing — Run the Hermes agent across hundreds or thousands of prompts in parallel, generating structured ShareGPT-format trajectory data for training data generation or evaluation. ## Media & Web - Voice Mode — Full voice interaction across CLI and messaging platforms. Talk to the agent using your microphone, hear spoken replies, and have live voice conversations in Discord voice channels. - Browser Automation — Full browser automation with multiple backends: Browserbase cloud, Browser Use cloud, local Chrome/Brave/Chromium/Edge via CDP, or local Chromium. Navigate websites, fill forms, and extract information. - Vision & Image Paste — Multimodal vision support. Paste images from your clipboard into the CLI and ask the agent to analyze, describe, or work with them using any vision-capable model. - Image Generation — Generate images from text prompts using FAL.ai. Nine models supported (FLUX 2 Klein/Pro, GPT-Image 1.5/2, Nano Banana Pro, Ideogram V3, Recraft V4 Pro, Qwen, Z-Image Turbo); pick one via `hermes tools`. - Voice & TTS — Text-to-speech output and voice message transcription across all messaging platforms, with ten native provider options: Edge TTS (free), ElevenLabs, OpenAI TTS, MiniMax, Mistral Voxtral, Google Gemini, xAI, NeuTTS, KittenTTS, and Piper — plus custom command providers for any local TTS CLI. ## Integrations - MCP Integration — Connect to any MCP server via stdio or HTTP transport. Access external tools from GitHub, databases, file systems, and internal APIs without writing native Hermes tools. Includes per-server tool filtering and sampling support. - Provider Routing — Fine-grained control over which AI providers handle your requests. Optimize for cost, speed, or quality with sorting, whitelists, blacklists, and priority ordering. - Fallback Providers — Automatic failover to backup LLM providers when your primary model encounters errors, including independent fallback for auxiliary tasks like vision and compression. - Credential Pools — Distribute API calls across multiple keys for the same provider. Automatic rotation on rate limits or failures. - Prompt caching — Built-in cross-session 1-hour prefix cache for Claude on native Anthropic, OpenRouter, and Nous Portal. Always-on; no configuration required. - Memory Providers — Plug in external memory backends (Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover, Supermemory) for cross-session user modeling and personalization beyond the built-in memory system. - API Server — Expose Hermes as an OpenAI-compatible HTTP endpoint. Connect any frontend that speaks the OpenAI format — Open WebUI, LobeChat, LibreChat, and more. - IDE Integration (ACP) — Use Hermes inside ACP-compatible editors such as VS Code, Zed, and JetBrains. Chat, tool activity, file diffs, and terminal commands render inside your editor. - Batch Processing — Run the agent over many prompts or tasks in parallel from the CLI, with structured outputs and trajectory capture suitable for evals or downstream training pipelines. ## Customization - Personality & SOUL.md — Fully customizable agent personality. `SOUL.md` is the primary identity file — the first thing in the system prompt — and you can swap in built-in or custom `/personality` presets per session. - Skins & Themes — Customize the CLI’s visual presentation: banner colors, spinner faces and verbs, response-box labels, branding text, and the tool activity prefix. - Plugins — Add custom tools, hooks, and integrations without modifying core code. Three plugin types: general plugins (tools/hooks), memory providers (cross-session knowledge), and context engines (alternative context management). Managed via the unified `hermes plugins` interactive UI. — # Tools & Toolsets # Tools & Toolsets Tools are functions that extend the agent’s capabilities. They’re organized into logical toolsets that can be enabled or disabled per platform. ## Available Tools Hermes ships with a broad built-in tool registry covering web search, browser automation, terminal execution, file editing, memory, delegation, RL training, messaging delivery, Home Assistant, and more. :::note Honcho cross-session memory is available as a memory provider plugin (`plugins/memory/honcho/`), not as a built-in toolset. See Plugins for installation. ::: High-level categories: | Category | Examples | Description | |–––––|–––––|———––| | Web | `web_search`, `web_extract` | Search the web and extract page content. | | X Search | `x_search` | Search X (Twitter) posts and threads via xAI’s built-in `x_search` Responses tool — gated on xAI credentials (SuperGrok OAuth or `XAI_API_KEY`); off by default, opt in via `hermes tools` → 🐦 X (Twitter) Search. | | Terminal & Files | `terminal`, `process`, `read_file`, `patch` | Execute commands and manipulate files. | | Browser | `browser_navigate`, `browser_snapshot`, `browser_vision` | Interactive browser automation with text and vision support. | | Media | `vision_analyze`, `image_generate`, `text_to_speech` | Multimodal analysis and generation. | | Agent orchestration | `todo`, `clarify`, `execute_code`, `delegate_task` | Planning, clarification, code execution, and subagent delegation. | | Memory & recall | `memory`, `session_search` | Persistent memory and session search. | | Automation & delivery | `cronjob`, `send_message` | Scheduled tasks with create/list/update/pause/resume/run/remove actions, plus outbound messaging delivery. | | Integrations | `ha_`, MCP server tools | Home Assistant, MCP, and other integrations. | For the authoritative code-derived registry, see Built-in Tools Reference and Toolsets Reference. :::tip Nous Tool Gateway Paid Nous Portal subscribers can use web search, image generation, TTS, and browser automation through the Tool Gateway — no separate API keys needed. Run `hermes model` to enable it, or configure individual tools with `hermes tools`. ::: ## Using Toolsets `bash # Use specific toolsets hermes chat --toolsets "web,terminal" # See all available tools hermes tools # Configure tools per platform (interactive) hermes tools` Common toolsets include `web`, `search`, `terminal`, `file`, `browser`, `vision`, `image_gen`, `moa`, `skills`, `tts`, `todo`, `memory`, `session_search`, `cronjob`, `code_execution`, `delegation`, `clarify`, `homeassistant`, `messaging`, `spotify`, `discord`, `discord_admin`, `debugging`, and `safe`. See Toolsets Reference for the full set, including platform presets such as `hermes-cli`, `hermes-telegram`, and dynamic MCP toolsets like `mcp-<server>`. ## Terminal Backends The terminal tool can execute commands in different environments: | Backend | Description | Use Case | |———|———––|–––––| | `local` | Run on your machine (default) | Development, trusted tasks | | `docker` | Isolated containers | Security, reproducibility | | `ssh` | Remote server | Sandboxing, keep agent away from its own code | | `singularity` | HPC containers | Cluster computing, rootless | | `modal` | Cloud execution | Serverless, scale | | `daytona` | Cloud sandbox workspace | Persistent remote dev environments | ### Configuration `yaml # In ~/.hermes/config.yaml terminal: backend: local # or: docker, ssh, singularity, modal, daytona cwd: "." # Working directory timeout: 180 # Command timeout in seconds` ### Docker Backend `yaml terminal: backend: docker docker_image: python:3.11-slim` One persistent container, shared across the whole process. Hermes starts a single long-lived container on first use (`docker run -d ... sleep 2h`) and routes every terminal, file, and `execute_code` call through `docker exec` into that same container. Working-directory changes, installed packages, environment tweaks, and files written to `/workspace` all carry over from one tool call to the next, across `/new`, `/reset`, and `delegate_task` subagents, for the lifetime of the Hermes process. The container is stopped and removed on shutdown. This means the Docker backend behaves like a persistent sandbox VM, not a fresh container per command. If you `pip install foo` once, it’s there for the rest of the session. If you `cd /workspace/project`, subsequent `ls` calls see that directory. See Configuration → Docker Backend for the full lifecycle details and the `container_persistent` flag that controls whether `/workspace` and `/root` survive across Hermes restarts. ### SSH Backend Recommended for security — agent can’t modify its own code: `yaml terminal: backend: ssh` `bash # Set credentials in ~/.hermes/.env TERMINAL_SSH_HOST=my-server.example.com TERMINAL_SSH_USER=myuser TERMINAL_SSH_KEY=~/.ssh/id_rsa` ### Singularity/Apptainer `bash # Pre-build SIF for parallel workers apptainer build ~/python.sif docker://python:3.11-slim # Configure hermes config set terminal.backend singularity hermes config set terminal.singularity_image ~/python.sif` ### Modal (Serverless Cloud) `bash uv pip install modal modal setup hermes config set terminal.backend modal` ### Container Resources Configure CPU, memory, disk, and persistence for all container backends: `yaml terminal: backend: docker # or singularity, modal, daytona container_cpu: 1 # CPU cores (default: 1) container_memory: 5120 # Memory in MB (default: 5GB) container_disk: 51200 # Disk in MB (default: 50GB) container_persistent: true # Persist filesystem across sessions (default: true)` When `container_persistent: true`, installed packages, files, and config survive across sessions. ### Container Security All container backends run with security hardening: - Read-only root filesystem (Docker) - All Linux capabilities dropped - No privilege escalation - PID limits (256 processes) - Full namespace isolation - Persistent workspace via volumes, not writable root layer Docker can optionally receive an explicit env allowlist via `terminal.docker_forward_env`, but forwarded variables are visible to commands inside the container and should be treated as exposed to that session. ## Background Process Management Start background processes and manage them: python terminal(command="pytest -v tests/", background=true) # Returns: {"session_id": "proc_abc123", "pid": 12345} # Then manage with the process tool: process(action="list") # Show all running processes process(action="poll", session_id="proc_abc123") # Check status process(action="wait", session_id="proc_abc123") # Block until done process(action="log", session_id="proc_abc123") # Full output process(action="kill", session_id="proc_abc123") # Terminate process(action="write", session_id="proc_abc123", data="y") # Send input PTY mode (`pty=true`) enables interactive CLI tools like Codex and Claude Code. ## Sudo Support If a command needs sudo, you’ll be prompted for your password (cached for the session). Or set `SUDO_PASSWORD` in `~/.hermes/.env`. :::warning On messaging platforms, if sudo fails, the output includes a tip to add `SUDO_PASSWORD` to `~/.hermes/.env`. ::: — # Skills System # Skills System Skills are on-demand knowledge documents the agent can load when needed. They follow a progressive disclosure pattern to minimize token usage and are compatible with the agentskills.io open standard. All skills live in `~/.hermes/skills/` — the primary directory and source of truth. On fresh install, bundled skills are copied from the repo. Hub-installed and agent-created skills also go here. The agent can modify or delete any skill. You can also point Hermes at external skill directories — additional folders scanned alongside the local one. See External Skill Directories below. See also: - Bundled Skills Catalog - Official Optional Skills Catalog ## Starting with a blank slate By default every profile is seeded with the bundled skill catalog, and each `hermes update` adds any newly bundled skills. If you want a profile with no bundled skills — and that stays empty across updates — you have two paths: At install time (applies to the default `~/.hermes` profile): `bash curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --no-skills` At profile-create time (named profiles): `bash hermes profile create research --no-skills` On an already-installed profile (default or named), toggle it at runtime: `bash hermes skills opt-out # stop future seeding — nothing on disk is touched hermes skills opt-out --remove # also delete UNMODIFIED bundled skills (confirms first) hermes skills opt-in --sync # undo: remove the marker and re-seed now` All three paths write a `.no-bundled-skills` marker into the profile directory. While the marker is present, the installer, `hermes update`, and any skill sync all skip bundled-skill seeding for that profile. Delete the marker (or run `hermes skills opt-in`) to re-enable. :::note Safe by default `hermes skills opt-out` only stops future* seeding — it never deletes anything already on disk. The optional `--remove` flag deletes bundled skills only when they are unmodified (byte-identical to the version Hermes installed). Skills you have edited, skills installed from the hub, and skills you wrote yourself are always kept. ::: ## Using Skills Every installed skill is automatically available as a slash command: `bash # In the CLI or any messaging platform: /gif-search funny cats /axolotl help me fine-tune Llama 3 on my dataset /github-pr-workflow create a PR for the auth refactor /plan design a rollout for migrating our auth provider # Just the skill name loads it and lets the agent ask what you need: /excalidraw` The bundled `plan` skill is a good example. Running `/plan [request]` loads the skill’s instructions, telling Hermes to inspect context if needed, write a markdown implementation plan instead of executing the task, and save the result under `.hermes/plans/` relative to the active workspace/backend working directory. You can also interact with skills through natural conversation: `bash hermes chat --toolsets skills -q "What skills do you have?" hermes chat --toolsets skills -q "Show me the axolotl skill"` ## Progressive Disclosure Skills use a token-efficient loading pattern: `Level 0: skills_list() → [{name, description, category}, ...] (~3k tokens) Level 1: skill_view(name) → Full content + metadata (varies) Level 2: skill_view(name, path) → Specific reference file (varies)` The agent only loads the full skill content when it actually needs it. ## SKILL.md Format markdown --- name: my-skill description: Brief description of what this skill does version: 1.0.0 platforms: [macos, linux] # Optional — restrict to specific OS platforms metadata: hermes: tags: [python, automation] category: devops fallback_for_toolsets: [web] # Optional — conditional activation (see below) requires_toolsets: [terminal] # Optional — conditional activation (see below) config: # Optional — config.yaml settings - key: my.setting description: "What this controls" default: "value" prompt: "Prompt for setup" --- # Skill Title ## When to Use Trigger conditions for this skill. ## Procedure 1. Step one 2. Step two ## Pitfalls - Known failure modes and fixes ## Verification How to confirm it worked. ### Platform-Specific Skills Skills can restrict themselves to specific operating systems using the `platforms` field: | Value | Matches | |—––|———| | `macos` | macOS (Darwin) | | `linux` | Linux | | `windows` | Windows | `yaml platforms: [macos] # macOS only (e.g., iMessage, Apple Reminders, FindMy) platforms: [macos, linux] # macOS and Linux` When set, the skill is automatically hidden from the system prompt, `skills_list()`, and slash commands on incompatible platforms. If omitted, the skill loads on all platforms. ## Skill output and media delivery When a skill response (or any agent response) includes a bare absolute path to a media file — for example `/home/user/screenshots/diagram.png` — the gateway auto-detects it, strips it from the visible text, and delivers the file natively to the user’s chat (Telegram photo, Discord attachment, etc.) instead of leaving the raw path in the message. For audio specifically, the `[[audio_as_voice]]` directive promotes audio files to native voice-message bubbles on platforms that support them (Telegram, WhatsApp). ### Forcing document-style delivery: `[[as_document]]` Sometimes you want the opposite of inline preview: you want the file delivered as a downloadable attachment, not a re-compressed image bubble. The classic example is a high-resolution screenshot or chart — Telegram’s `sendPhoto` recompresses it to 200 KB at 1280 px, destroying readability. A 1-2 MB PNG sent via `sendDocument` keeps the original bytes intact. If a response (or any text inside it — typically the last line) contains the literal directive `[[as_document]]`, every media path extracted from that response is delivered as a document/file attachment rather than an image bubble: `Here is your rendered chart: /home/user/.hermes/cache/chart-q4-2025.png [[as_document]]` The directive is stripped before delivery, so users never see it. Granularity is intentionally all-or-nothing per response: emit `[[as_document]]` once and every image path in the same response is delivered as a document. This mirrors the scope of `[[audio_as_voice]]`. Use it from a skill when: - You produce screenshots or charts the user needs as files (for editing in another tool, archiving, sharing intact). - The default lossy preview would obscure detail (small text, pixel-accurate diagrams, color-sensitive renders). Platforms without a separate document path (e.g. SMS) fall back to whatever attachment mechanism they have. ### Conditional Activation (Fallback Skills) Skills can automatically show or hide themselves based on which tools are available in the current session. This is most useful for fallback skills — free or local alternatives that should only appear when a premium tool is unavailable. `yaml metadata: hermes: fallback_for_toolsets: [web] # Show ONLY when these toolsets are unavailable requires_toolsets: [terminal] # Show ONLY when these toolsets are available fallback_for_tools: [web_search] # Show ONLY when these specific tools are unavailable requires_tools: [terminal] # Show ONLY when these specific tools are available` | Field | Behavior | |—––|–––––| | `fallback_for_toolsets` | Skill is hidden when the listed toolsets are available. Shown when they’re missing. | | `fallback_for_tools` | Same, but checks individual tools instead of toolsets. | | `requires_toolsets` | Skill is hidden when the listed toolsets are unavailable. Shown when they’re present. | | `requires_tools` | Same, but checks individual tools. | Example: The built-in `duckduckgo-search` skill uses `fallback_for_toolsets: [web]`. When you have `FIRECRAWL_API_KEY` set, the web toolset is available and the agent uses `web_search` — the DuckDuckGo skill stays hidden. If the API key is missing, the web toolset is unavailable and the DuckDuckGo skill automatically appears as a fallback. Skills without any conditional fields behave exactly as before — they’re always shown. ## Secure Setup on Load Skills can declare required environment variables without disappearing from discovery: `yaml required_environment_variables: - name: TENOR_API_KEY prompt: Tenor API key help: Get a key from https://developers.google.com/tenor required_for: full functionality` When a missing value is encountered, Hermes asks for it securely only when the skill is actually loaded in the local CLI. You can skip setup and keep using the skill. Messaging surfaces never ask for secrets in chat — they tell you to use `hermes setup` or `~/.hermes/.env` locally instead. Once set, declared env vars are automatically passed through to `execute_code` and `terminal` sandboxes — the skill’s scripts can use `$TENOR_API_KEY` directly. For non-skill env vars, use the `terminal.env_passthrough` config option. See Environment Variable Passthrough for details. ### Skill Config Settings Skills can also declare non-secret config settings (paths, preferences) stored in `config.yaml`: `yaml metadata: hermes: config: - key: myplugin.path description: Path to the plugin data directory default: "~/myplugin-data" prompt: Plugin data directory path` Settings are stored under `skills.config` in your config.yaml. `hermes config migrate` prompts for unconfigured settings, and `hermes config show` displays them. When a skill loads, its resolved config values are injected into the context so the agent knows the configured values automatically. See Skill Settings and Creating Skills — Config Settings for details. ## Skill Directory Structure text ~/.hermes/skills/ # Single source of truth ├── mlops/ # Category directory │ ├── axolotl/ │ │ ├── SKILL.md # Main instructions (required) │ │ ├── references/ # Additional docs │ │ ├── templates/ # Output formats │ │ ├── scripts/ # Helper scripts callable from the skill │ │ └── assets/ # Supplementary files │ └── vllm/ │ └── SKILL.md ├── devops/ │ └── deploy-k8s/ # Agent-created skill │ ├── SKILL.md │ └── references/ ├── .hub/ # Skills Hub state │ ├── lock.json │ ├── quarantine/ │ └── audit.log └── .bundled_manifest # Tracks seeded bundled skills ## External Skill Directories If you maintain skills outside of Hermes — for example, a shared `~/.agents/skills/` directory used by multiple AI tools — you can tell Hermes to scan those directories too. Add `external_dirs` under the `skills` section in `~/.hermes/config.yaml`: `yaml skills: external_dirs: - ~/.agents/skills - /home/shared/team-skills - ${SKILLS_REPO}/skills` Paths support `~` expansion and `${VAR}` environment variable substitution. ### How it works - Create locally, update in place: New agent-created skills are written to `~/.hermes/skills/`. Existing skills are modified where they are found, including skills under `external_dirs`, when the agent uses `skill_manage` actions such as `patch`, `edit`, `write_file`, `remove_file`, or `delete`. - External dirs are not a write-protection boundary: If an external skill directory is writable by the Hermes process, agent-managed skill updates can change files in that directory. Use filesystem permissions or a separate profile/toolset setup if shared external skills must stay read-only. - Local precedence: If the same skill name exists in both the local dir and an external dir, the local version wins. - Full integration: External skills appear in the system prompt index, `skills_list`, `skill_view`, and as `/skill-name` slash commands — no different from local skills. - Non-existent paths are silently skipped: If a configured directory doesn’t exist, Hermes ignores it without errors. Useful for optional shared directories that may not be present on every machine. ### Example `text ~/.hermes/skills/ # Local (primary, read-write) ├── devops/deploy-k8s/ │ └── SKILL.md └── mlops/axolotl/ └── SKILL.md ~/.agents/skills/ # External (shared, mutable if writable) ├── my-custom-workflow/ │ └── SKILL.md └── team-conventions/ └── SKILL.md` All four skills appear in your skill index. If you create a new skill called `my-custom-workflow` locally, it shadows the external version. ## Skill Bundles Skill bundles are tiny YAML files that group several skills under a single slash command. When you run `/<bundle-name>`, every skill listed in the bundle loads at once — useful when a particular task always benefits from the same set of skills together. ### Quick example `bash # Create a bundle for backend feature work hermes bundles create backend-dev \ --skill github-code-review \ --skill test-driven-development \ --skill github-pr-workflow \ -d "Backend feature work — review, test, PR workflow"` Then in the CLI or any gateway platform: `/backend-dev refactor the auth middleware` The agent receives all three skills loaded into one user message, with any text after the slash command attached as a user instruction. ### YAML schema Bundles live in `~/.hermes/skill-bundles/<slug>.yaml` and look like this: `yaml name: backend-dev description: Backend feature work — review, test, PR workflow. skills: - github-code-review - test-driven-development - github-pr-workflow instruction: | Always start by writing failing tests, then implement. Open the PR through the standard workflow with co-author tags.` Fields: - `name` (optional — defaults to the filename stem) — the bundle’s display name. Normalized to a hyphen slug for the slash command (`Backend Dev` → `/backend-dev`). - `description` (optional) — short text shown in `/bundles` and `hermes bundles list`. - `skills` (required, non-empty list) — skill names or paths relative to your skills directory. Use the same identifier you’d pass to `/<skill-name>`. - `instruction` (optional) — extra guidance prepended to the loaded skill content. Useful for codifying “how we always use these together.” ### Managing bundles `bash # List all installed bundles hermes bundles list # Inspect one bundle hermes bundles show backend-dev # Create a bundle interactively (omit --skill flags to enter them one per line) hermes bundles create research # Overwrite an existing bundle hermes bundles create backend-dev --skill ... --force # Delete a bundle hermes bundles delete backend-dev # Re-scan ~/.hermes/skill-bundles/ and report changes hermes bundles reload` From inside a chat session, `/bundles` lists every installed bundle and its skills. ### Behavior - Bundles take precedence over individual skills when slugs collide. If you name a bundle `research` and you also have a skill called `research`, `/research` invokes the bundle. This is intentional — you opted into the bundle by naming it. - Missing skills are skipped, not fatal. If a bundle lists `skill-foo` and you haven’t installed it, the bundle still loads the skills that do resolve, and the agent gets a note listing what was skipped. - Bundles work in every surface — interactive CLI, TUI, dashboard chat, and every gateway platform (Telegram, Discord, Slack, …) — because dispatch is centralized in the same place as individual skill commands. - Bundles do not invalidate the prompt cache. They generate a fresh user message at invocation time, the same way `/<skill-name>` does — no system prompt mutation. ### When bundles beat installing each skill manually Use a bundle when: - You always pair the same skills for a recurring task (`/backend-dev`, `/release-prep`, `/incident-response`). - You want a one-character-shorter mental model than typing several `/skill` invocations in a row. - You want to ship a team-wide “task profile” by checking the bundle YAML into a shared dotfiles repo and symlinking it into `~/.hermes/skill-bundles/`. A bundle is just a YAML alias — it doesn’t install skills for you. The skills themselves must already be present (in `~/.hermes/skills/` or an external skill directory). Otherwise the bundle invocation just skips the missing ones. ## Agent-Managed Skills (skill_manage tool) The agent can create, update, and delete its own skills via the `skill_manage` tool. This is the agent’s procedural memory — when it figures out a non-trivial workflow, it saves the approach as a skill for future reuse. ### When the Agent Creates Skills - After completing a complex task (5+ tool calls) successfully - When it hit errors or dead ends and found the working path - When the user corrected its approach - When it discovered a non-trivial workflow ### Actions | Action | Use for | Key params | |––––|———|————| | `create` | New skill from scratch | `name`, `content` (full SKILL.md), optional `category` | | `patch` | Targeted fixes (preferred) | `name`, `old_string`, `new_string` | | `edit` | Major structural rewrites | `name`, `content` (full SKILL.md replacement) | | `delete` | Remove a skill entirely | `name` | | `write_file` | Add/update supporting files | `name`, `file_path`, `file_content` | | `remove_file` | Remove a supporting file | `name`, `file_path` | :::tip The `patch` action is preferred for updates — it’s more token-efficient than `edit` because only the changed text appears in the tool call. ::: ## Skills Hub Browse, search, install, and manage skills from online registries, `skills.sh`, direct well-known skill endpoints, and official optional skills. ### Common commands bash hermes skills browse # Browse all hub skills (official first) hermes skills browse --source official # Browse only official optional skills hermes skills search kubernetes # Search all sources hermes skills search react --source skills-sh # Search the skills.sh directory hermes skills search https://mintlify.com/docs --source well-known hermes skills inspect openai/skills/k8s # Preview before installing hermes skills install openai/skills/k8s # Install with security scan hermes skills install official/security/1password hermes skills install skills-sh/vercel-labs/json-render/json-render-react --force hermes skills install well-known:https://mintlify.com/docs/.well-known/skills/mintlify hermes skills install https://sharethis.chat/SKILL.md # Direct URL (single-file SKILL.md) hermes skills install https://example.com/SKILL.md --name my-skill # Override name when frontmatter has none hermes skills list --source hub # List hub-installed skills hermes skills check # Check installed hub skills for upstream updates hermes skills update # Reinstall hub skills with upstream changes when needed hermes skills audit # Re-scan all hub skills for security hermes skills uninstall k8s # Remove a hub skill hermes skills reset google-workspace # Un-stick a bundled skill from "user-modified" (see below) hermes skills reset google-workspace --restore # Also restore the bundled version, deleting your local edits hermes skills publish skills/my-skill --to github --repo owner/repo hermes skills snapshot export setup.json # Export skill config hermes skills tap add myorg/skills-repo # Add a custom GitHub source ### Supported hub sources | Source | Example | Notes | |––––|———|—––| | `official` | `official/security/1password` | Optional skills shipped with Hermes. | | `skills-sh` | `skills-sh/vercel-labs/agent-skills/vercel-react-best-practices` | Searchable via `hermes skills search <query> --source skills-sh`. Hermes resolves alias-style skills when the skills.sh slug differs from the repo folder. | | `well-known` | `well-known:https://mintlify.com/docs/.well-known/skills/mintlify` | Skills served directly from `/.well-known/skills/index.json` on a website. Search using the site or docs URL. | | `url` | `https://sharethis.chat/SKILL.md` | Direct HTTP(S) URL to a single-file `SKILL.md`. Name resolution: frontmatter → URL slug → interactive prompt → `--name` flag. | | `github` | `openai/skills/k8s` | Direct GitHub repo/path installs and custom taps. | | `clawhub`, `lobehub`, `browse-sh` | Source-specific identifiers | Community or marketplace integrations. | ### Integrated hubs and registries Hermes currently integrates with these skills ecosystems and discovery sources: #### 1. Official optional skills (`official`) These are maintained in the Hermes repository itself and install with built-in trust. - Catalog: Official Optional Skills Catalog - Source in repo: `optional-skills/` - Example: `bash hermes skills browse --source official hermes skills install official/security/1password` #### 2. skills.sh (`skills-sh`) This is Vercel’s public skills directory. Hermes can search it directly, inspect skill detail pages, resolve alias-style slugs, and install from the underlying source repo. - Directory: skills.sh - CLI/tooling repo: vercel-labs/skills - Official Vercel skills repo: vercel-labs/agent-skills - Example: `bash hermes skills search react --source skills-sh hermes skills inspect skills-sh/vercel-labs/json-render/json-render-react hermes skills install skills-sh/vercel-labs/json-render/json-render-react --force` #### 3. Well-known skill endpoints (`well-known`) This is URL-based discovery from sites that publish `/.well-known/skills/index.json`. It is not a single centralized hub — it is a web discovery convention. - Example live endpoint: Mintlify docs skills index - Reference server implementation: vercel-labs/skills-handler - Example: `bash hermes skills search https://mintlify.com/docs --source well-known hermes skills inspect well-known:https://mintlify.com/docs/.well-known/skills/mintlify hermes skills install well-known:https://mintlify.com/docs/.well-known/skills/mintlify` #### 4. Direct GitHub skills (`github`) Hermes can install directly from GitHub repositories and GitHub-based taps. This is useful when you already know the repo/path or want to add your own custom source repo. Default taps (browsable without any setup): - openai/skills - anthropics/skills - huggingface/skills - NVIDIA/skills — NVIDIA-verified skills (signed `skill.oms.sig` + governance `skill-card.md`) - garrytan/gstack - Example: `bash hermes skills install openai/skills/k8s hermes skills tap add myorg/skills-repo` Category groupings (`skills.sh.json`). A GitHub tap may ship a `skills.sh.json` file at its repo root following the skills.sh schema. Its `groupings` (each with a `title` and a list of skill names) are read at index time and become the category labels shown in the Skills Hub page — instead of a tag-derived guess. This is generic: any tap that ships the file gets real categorization, no Hermes-side changes required. `json { "$schema": "https://skills.sh/schemas/skills.sh.schema.json", "groupings": [ { "title": "Inference AI", "skills": ["dynamo-recipe-runner", "dynamo-router-sla"] }, { "title": "Decision Optimization", "skills": ["cuopt-developer", "cuopt-install"] } ] }` #### 5. ClawHub (`clawhub`) A third-party skills marketplace integrated as a community source. - Site: clawhub.ai - Hermes source id: `clawhub` #### 6. Claude marketplace-style repos (`claude-marketplace`) Hermes supports marketplace repos that publish Claude-compatible plugin/marketplace manifests. Known integrated sources include: - anthropics/skills - aiskillstore/marketplace Hermes source id: `claude-marketplace` #### 7. LobeHub (`lobehub`) Hermes can search and convert agent entries from LobeHub’s public catalog into installable Hermes skills. - Site: LobeHub - Public agents index: chat-agents.lobehub.com - Backing repo: lobehub/lobe-chat-agents - Hermes source id: `lobehub` #### 8. browse.sh (`browse-sh`) Hermes integrates with browse.sh, Browserbase’s catalog of 200+ site-specific browser-automation SKILL.md files (Airbnb, Amazon, arXiv, 12306.cn, Etsy, Xero, and many more). Each skill describes how to drive one website end-to-end and is suitable for use with Hermes’ browser tools and any browser-automation skills you already have installed. - Site: browse.sh - Catalog API: `https://browse.sh/api/skills` - Hermes source id: `browse-sh` - Trust level: `community` `bash hermes skills search airbnb --source browse-sh hermes skills inspect browse-sh/airbnb.com/search-listings-ddgioa hermes skills install browse-sh/airbnb.com/search-listings-ddgioa` Identifiers use the form `browse-sh/<hostname>/<task-id>` and match the slug exposed by the browse.sh catalog. Content is resolved through the per-skill detail endpoint (`/api/skills/<slug>` → `skillMdUrl`), not through the catalog’s GitHub `sourceUrl`. #### 9. Direct URL (`url`) Install a single-file `SKILL.md` directly from any HTTP(S) URL — useful when an author hosts a skill on their own site (no hub listing, no GitHub path to type). Hermes fetches the URL, parses the YAML frontmatter, security-scans it, and installs. - Hermes source id: `url` - Identifier: the URL itself (no prefix needed) - Scope: single-file `SKILL.md` only. Multi-file skills with `references/` or `scripts/` need a manifest and should be published via one of the other sources above. `bash hermes skills install https://sharethis.chat/SKILL.md hermes skills install https://example.com/my-skill/SKILL.md --category productivity` Name resolution, in order: 1. `name:` field in the SKILL.md YAML frontmatter (recommended — every well-formed skill has one). 2. Parent directory name from the URL path (e.g. `.../my-skill/SKILL.md` → `my-skill`, or `.../my-skill.md` → `my-skill`), when it’s a valid identifier (`^[a-z][a-z0-9_-]$`). 3. Interactive prompt on a terminal with a TTY. 4. On non-interactive surfaces (the `/skills install` slash command inside the TUI, gateway platforms, scripts), a clean error pointing at the `--name` override. `bash # Frontmatter has no name and the URL slug is unhelpful — supply one: hermes skills install https://example.com/SKILL.md --name sharethis-chat # Or inside a chat session: /skills install https://example.com/SKILL.md --name sharethis-chat` Trust level is always `community` — the same security scan runs as for every other source. The URL is stored as the install identifier, so `hermes skills update` re-fetches from the same URL automatically when you want to refresh. ### Security scanning and `--force` All hub-installed skills go through a security scanner that checks for data exfiltration, prompt injection, destructive commands, supply-chain signals, and other threats. `hermes skills inspect ...` now also surfaces upstream metadata when available: - repo URL - skills.sh detail page URL - install command - weekly installs - upstream security audit statuses - well-known index/endpoint URLs Use `--force` when you have reviewed a third-party skill and want to override a non-dangerous policy block: `bash hermes skills install skills-sh/anthropics/skills/pdf --force` Important behavior: - `--force` can override policy blocks for caution/warn-style findings. - `--force` does not override a `dangerous` scan verdict. - Official optional skills (`official/...`) are treated as built-in trust and do not show the third-party warning panel. ### Trust levels | Level | Source | Policy | |—––|––––|––––| | `builtin` | Ships with Hermes | Always trusted | | `official` | `optional-skills/` in the repo | Built-in trust, no third-party warning | | `trusted` | Trusted registries/repos such as `openai/skills`, `anthropics/skills`, `huggingface/skills`, `NVIDIA/skills` | More permissive policy than community sources | | `community` | Everything else (`skills.sh`, well-known endpoints, custom GitHub repos, most marketplaces) | Non-dangerous findings can be overridden with `--force`; `dangerous` verdicts stay blocked | ### Update lifecycle The hub now tracks enough provenance to re-check upstream copies of installed skills: `bash hermes skills check # Report which installed hub skills changed upstream hermes skills update # Reinstall only the skills with updates available hermes skills update react # Update one specific installed hub skill` This uses the stored source identifier plus the current upstream bundle content hash to detect drift. :::tip GitHub rate limits Skills hub operations use the GitHub API, which has a rate limit of 60 requests/hour for unauthenticated users. If you see rate-limit errors during install or search, set `GITHUB_TOKEN` in your `.env` file to increase the limit to 5,000 requests/hour. The error message includes an actionable hint when this happens. ::: ### Publishing a custom skill tap If you want to share a curated set of skills — for your team, your org, or publicly — you can publish them as a tap: a GitHub repository other Hermes users add with `hermes skills tap add <owner/repo>`. No server, no registry sign-up, no release pipeline. Just a directory of `SKILL.md` files. #### Repo layout A tap is any GitHub repo (public or private — private needs `GITHUB_TOKEN`) laid out like this: `owner/repo ├── skills/ # default path; configurable per-tap │ ├── my-workflow/ │ │ ├── SKILL.md # required │ │ ├── references/ # optional supporting files │ │ ├── templates/ │ │ └── scripts/ │ ├── another-skill/ │ │ └── SKILL.md │ └── third-skill/ │ └── SKILL.md └── README.md # optional but helpful` Rules: - Each skill lives in its own directory under the tap’s root path (default `skills/`). - The directory name becomes the skill’s install slug. - Each skill directory must contain a `SKILL.md` with standard SKILL.md frontmatter (`name`, `description`, plus optional `metadata.hermes.tags`, `version`, `author`, `platforms`, `metadata.hermes.config`). - Subdirectories like `references/`, `templates/`, `scripts/`, `assets/` are downloaded alongside `SKILL.md` at install time. - Skills whose directory name starts with `.` or `_` are ignored. Hermes discovers skills by listing every subdirectory of the tap path and probing each for `SKILL.md`. #### Minimal tap example `my-org/hermes-skills └── skills/ └── deploy-runbook/ └── SKILL.md` `skills/deploy-runbook/SKILL.md`: `markdown --- name: deploy-runbook description: Our deployment runbook — services, rollback, Slack channels version: 1.0.0 author: My Org Platform Team metadata: hermes: tags: [deployment, runbook, internal] --- # Deploy Runbook Step 1: ...` After pushing that to GitHub, any Hermes user can subscribe and install: `bash hermes skills tap add my-org/hermes-skills hermes skills search deploy hermes skills install my-org/hermes-skills/deploy-runbook` #### Non-default paths If your skills don’t live under `skills/` (common when you’re adding a `skills/` subtree to an existing project), edit the tap entry in `~/.hermes/.hub/taps.json`: `json { "taps": [ {"repo": "my-org/platform-docs", "path": "internal/skills/"} ] }` The `hermes skills tap add` CLI defaults new taps to `path: "skills/"`; edit the file directly if you need a different path. `hermes skills tap list` shows the effective path per tap. #### Installing individual skills directly (without adding a tap) Users can also install a single skill from any public GitHub repo without adding the whole repo as a tap: `bash hermes skills install owner/repo/skills/my-workflow` Useful when you want to share one skill without asking the user to subscribe to your whole registry. #### Trust levels for taps New taps are assigned `community` trust by default. Skills installed from them run through the standard security scan and show the third-party warning panel on first install. If your org or a widely-trusted source should get higher trust, add its repo to `TRUSTED_REPOS` in `tools/skills_hub.py` (requires a Hermes core PR). #### Tap management `bash hermes skills tap list # show all configured taps hermes skills tap add myorg/skills-repo # add (default path: skills/) hermes skills tap remove myorg/skills-repo # remove` Inside a running session: `/skills tap list /skills tap add myorg/skills-repo /skills tap remove myorg/skills-repo` Taps are stored in `~/.hermes/.hub/taps.json` (created on demand). ## Bundled skill updates (`hermes skills reset`) Hermes ships with a set of bundled skills in `skills/` inside the repo. On install and on every `hermes update`, a sync pass copies those into `~/.hermes/skills/` and records a manifest at `~/.hermes/skills/.bundled_manifest` mapping each skill name to the content hash at the time it was synced (the origin hash). On each sync, Hermes recomputes the hash of your local copy and compares it to the origin hash: - Unchanged → safe to pull upstream changes, copy the new bundled version in, record the new origin hash. - Changed → treated as user-modified and skipped forever, so your edits never get stomped. The protection is good, but it has one sharp edge. If you edit a bundled skill and then later want to abandon your changes and go back to the bundled version by just copy-pasting from `~/.hermes/hermes-agent/skills/`, the manifest still holds the old* origin hash from whenever the last successful sync ran. Your fresh copy-paste contents (current bundled hash) won’t match that stale origin hash, so sync keeps flagging it as user-modified. `hermes skills reset` is the escape hatch: bash # Safe: clears the manifest entry for this skill. Your current copy is preserved, # but the next sync re-baselines against it so future updates work normally. hermes skills reset google-workspace # Full restore: also deletes your local copy and re-copies the current bundled # version. Use this when you want the pristine upstream skill back. hermes skills reset google-workspace --restore # Non-interactive (e.g. in scripts or TUI mode) — skip the --restore confirmation. hermes skills reset google-workspace --restore --yes The same command works in chat as a slash command: `text /skills reset google-workspace /skills reset google-workspace --restore` :::note Profiles Each profile has its own `.bundled_manifest` under its own `HERMES_HOME`, so `hermes -p coder skills reset <name>` only affects that profile. ::: ### Slash commands (inside chat) All the same commands work with `/skills`: `text /skills browse /skills search react --source skills-sh /skills search https://mintlify.com/docs --source well-known /skills inspect skills-sh/vercel-labs/json-render/json-render-react /skills install openai/skills/skill-creator --force /skills check /skills update /skills reset google-workspace /skills list` Official optional skills still use identifiers like `official/security/1password` and `official/migration/openclaw-migration`. — # Curator # Curator The curator is a background maintenance pass for agent-created skills. It tracks how often each skill is viewed, used, and patched, moves long-unused skills through `active → stale → archived` states, and periodically spawns a short auxiliary-model review that proposes consolidations or patches drift. It exists so that skills created via the self-improvement loop don’t pile up forever. Every time the agent solves a novel problem and saves a skill, that skill lands in `~/.hermes/skills/`. Without maintenance, you end up with dozens of narrow near-duplicates that pollute the catalog and waste tokens. By default (`prune_builtins: true`) the curator can archive unused bundled built-in skills (shipped with the repo) after `archive_after_days` of non-use, alongside the agent-created skills it primarily manages. Hub-installed skills (from agentskills.io) are always off-limits. Set `curator.prune_builtins: false` to restore the old agent-created-only behavior, where bundled skills are never touched. The curator also never auto-deletes — the worst outcome is archival into `~/.hermes/skills/.archive/`, which is recoverable. Tracks issue #7816. ## How it runs The curator is triggered by an inactivity check, not a cron daemon. On CLI session start, and on a recurring tick inside the gateway’s cron-ticker thread, Hermes checks whether: 1. Enough time has passed since the last curator run (`interval_hours`, default 7 days), and 2. The agent has been idle long enough (`min_idle_hours`, default 2 hours). If both are true, it spawns a background fork of `AIAgent` — the same pattern used by the memory/skill self-improvement nudges. The fork runs in its own prompt cache and never touches the active conversation. :::info First-run behavior On a brand-new install (or the first time a pre-curator install ticks after `hermes update`), the curator does not run immediately. The first observation seeds `last_run_at` to “now” and defers the first real pass by one full `interval_hours`. This gives you a full interval to review your skill library, pin anything important, or opt out entirely before the curator ever touches it. If you want to see what the curator would do before it runs for real, run `hermes curator run --dry-run` — it produces the same review report without mutating the library. ::: A run has two phases: 1. Automatic transitions (deterministic, no LLM). Skills unused for `stale_after_days` (30) become `stale`; skills unused for `archive_after_days` (90) are moved to `~/.hermes/skills/.archive/`. 2. LLM review (single aux-model pass, `max_iterations=8`). The forked agent surveys the agent-created skills, can read any of them with `skill_view`, and decides per-skill whether to keep, patch (via `skill_manage`), consolidate overlapping ones, or archive via the terminal tool. Consolidation treats a skill as a full package: if a skill has `references/`, `templates/`, `scripts/`, `assets/`, or relative links to those paths, the curator must either keep it standalone, re-home the needed support files and rewrite paths, or archive the entire package unchanged — not flatten only `SKILL.md` into another skill’s `references/` file. Pinned skills are off-limits to both the curator’s auto-transitions and the agent’s own `skill_manage` tool. See Pinning a skill below. ## Configuration All settings live in `config.yaml` under `curator:` (not `.env` — this isn’t a secret). Defaults: `yaml curator: enabled: true interval_hours: 168 # 7 days min_idle_hours: 2 stale_after_days: 30 archive_after_days: 90 prune_builtins: true # archive unused bundled built-in skills too (hub skills always exempt)` To disable entirely, set `curator.enabled: false`. ### Running the review on a cheaper aux model The curator’s LLM review pass is a regular auxiliary task slot — `auxiliary.curator` — alongside Vision, Compression, Session Search, etc. “Auto” means “use my main chat model”; override the slot to pin a specific provider + model for the review pass instead. Easiest — `hermes model`: `bash hermes model # → "Auxiliary models — side-task routing" # → pick "Curator" → pick provider → pick model` The same picker is available in the web dashboard under the Models tab. Direct config.yaml (equivalent): `yaml auxiliary: curator: provider: openrouter model: google/gemini-3-flash-preview timeout: 600 # generous — reviews can take several minutes` Leaving `provider: auto` (the default) routes the review pass through whatever your main chat model is, matching the behavior of every other auxiliary task. :::note Legacy config Earlier releases used a one-off `curator.auxiliary.{provider,model}` block. That path still works but emits a deprecation log line — please migrate to `auxiliary.curator` above so the curator shares the same plumbing (`hermes model`, dashboard Models tab, `base_url`, `api_key`, `timeout`, `extra_body`) as every other aux task. ::: ## CLI bash hermes curator status # last run, counts, pinned list, LRU top 5 hermes curator run # trigger a review now (blocks until the LLM pass finishes) hermes curator run --background # fire-and-forget: start the LLM pass in a background thread hermes curator run --dry-run # preview only — report without any mutations hermes curator backup # take a manual snapshot of ~/.hermes/skills/ hermes curator rollback # restore from the newest snapshot hermes curator rollback --list # list available snapshots hermes curator rollback --id <ts> # restore a specific snapshot hermes curator rollback -y # skip the confirmation prompt hermes curator pause # stop runs until resumed hermes curator resume hermes curator pin <skill> # never auto-transition this skill hermes curator unpin <skill> hermes curator restore <skill> # move an archived skill back to active hermes curator list-archived # list skills currently in ~/.hermes/skills/.archive/ hermes curator archive <skill> # manually archive a single skill now hermes curator prune [--days N] # bulk-archive agent-created skills idle >= N days (default 90) ## Backups and rollback Before every real curator pass, Hermes takes a tar.gz snapshot of `~/.hermes/skills/` at `~/.hermes/skills/.curator_backups/<utc-iso>/skills.tar.gz`. If a pass archives or consolidates something you didn’t want touched, you can undo the whole run with one command: `bash hermes curator rollback # restore newest snapshot (with confirmation) hermes curator rollback -y # skip the prompt hermes curator rollback --list # see all snapshots with reason + size` The rollback itself is reversible: before replacing the skills tree, Hermes takes another snapshot tagged `pre-rollback to <target-id>`, so a mistaken rollback can be undone by rolling forward to that one with `--id`. You can also take manual snapshots at any time with `hermes curator backup --reason "before-refactor"`. The `--reason` string lands in the snapshot’s `manifest.json` and is shown in `--list`. Snapshots are pruned to `curator.backup.keep` (default 5) to keep disk usage bounded: `yaml curator: backup: enabled: true keep: 5` Set `curator.backup.enabled: false` to disable automatic snapshotting. The manual `hermes curator backup` command still works when backups are disabled only if you set `enabled: true` first — the flag gates both paths symmetrically so there’s no way to accidentally skip the pre-run snapshot on mutating runs. `hermes curator status` also lists the five least-recently-used skills — a quick way to see what’s likely to become stale next. The same subcommands are available as the `/curator` slash command inside a running session (CLI or gateway platforms). ## What “agent-created” means The curator only manages skills explicitly marked as agent-created in `~/.hermes/skills/.usage.json`. A skill qualifies when ALL of the following are true: 1. Its name is not in `~/.hermes/skills/.bundled_manifest` (bundled skills shipped with the repo). 2. Its name is not in `~/.hermes/skills/.hub/lock.json` (hub-installed skills). 3. Its `.usage.json` entry has `"created_by": "agent"` or `"agent_created": true`. Currently, only the background self-improvement review fork sets this marker — when it creates a new umbrella skill during its periodic review pass (every 10 agent turns). The background fork runs with a write origin of `"background_review"` (via `tools/skill_provenance.py`), which is the only path that triggers the `mark_agent_created()` call in `skill_manage`. Skills the foreground agent creates via `skill_manage(action="create")` during a conversation are not marked as agent-created — they are considered user-directed and the curator intentionally leaves them alone. :::warning Your hand-written skills are NOT curated If you manually created a `SKILL.md` or pointed Hermes at an external skill directory, that skill will have a `.usage.json` entry with `created_by: null` (or the field absent). The curator will not touch it. The same applies to skills the foreground agent created at your request. To see which skills the curator actually manages, run `hermes curator status`. If the agent-created count is 0, no skills are currently in the curator’s jurisdiction — the LLM review pass is skipped and the report will show `Model: (not resolved) via (not resolved)` with `Duration: 0s`. ::: Skills that ARE agent-created follow the full lifecycle: - `active` → (30d unused) `stale` → (90d unused) `archived` - Pinned skills bypass all auto-transitions - Archives are recoverable via `hermes curator restore <name>` If you want to protect a specific skill from ever being touched — for example a hand-authored skill you rely on — use `hermes curator pin <name>`. See the next section. ## Pinning a skill Pinning protects a skill from deletion — both the curator’s automated archive passes and the agent’s `skill_manage(action="delete")` tool call. Once a skill is pinned: - The curator skips it during auto-transitions (`active → stale → archived`), and its LLM review pass is instructed to leave it alone. - The agent’s `skill_manage` tool refuses `delete` on it, pointing the user at `hermes curator unpin <name>`. Patches and edits still go through, so the agent can improve a pinned skill’s content as pitfalls come up without a pin/unpin/re-pin dance. Pin and unpin with: `bash hermes curator pin <skill> hermes curator unpin <skill>` The flag is stored as `"pinned": true` on the skill’s entry in `~/.hermes/skills/.usage.json`, so it survives across sessions. Only agent-created skills can be pinned — `hermes curator pin` refuses on bundled and hub-installed skills with an explanatory message if you try. Hub-installed skills are never subject to curator mutation. Bundled built-in skills are only touched when `curator.prune_builtins: true` (the default), and even then only archived after `archive_after_days` of non-use — never patched, consolidated, or deleted. Set `curator.prune_builtins: false` to exempt bundled skills entirely. A small set of protected built-ins is hardcoded as never-archivable and never-consolidatable, regardless of `curator.prune_builtins`, pin state, or LLM judgment. These back load-bearing UX — for example, `plan` powers the `/plan` slash-command flow — so silently archiving one would turn its slash command into an “Unknown command” error with no signal to you. Protected built-ins are filtered out of the curator’s candidate list entirely, so the consolidation pass never sees them. If you want a stronger guarantee than “no deletion” — for instance, freezing a skill’s content entirely while the agent still reads it — edit `~/.hermes/skills/<name>/SKILL.md` directly with your editor. The pin guards tool-driven deletion, not your own filesystem access. ## Usage telemetry The curator maintains a sidecar at `~/.hermes/skills/.usage.json` with one entry per skill: `json { "my-skill": { "use_count": 12, "view_count": 34, "last_used_at": "2026-04-24T18:12:03Z", "last_viewed_at": "2026-04-23T09:44:17Z", "patch_count": 3, "last_patched_at": "2026-04-20T22:01:55Z", "created_at": "2026-03-01T14:20:00Z", "state": "active", "pinned": false, "archived_at": null } }` Counters increment when: - `view_count`: the agent calls `skill_view` on the skill. - `use_count`: the skill is loaded into a conversation’s prompt. - `patch_count`: `skill_manage patch/edit/write_file/remove_file` runs on the skill. Bundled and hub-installed skills are explicitly excluded from telemetry writes. ## Per-run reports Every curator run writes a timestamped directory under `~/.hermes/logs/curator/`: `~/.hermes/logs/curator/ └── 20260429-111512/ ├── run.json # machine-readable: full fidelity, stats, LLM output └── REPORT.md # human-readable summary` `REPORT.md` is a quick way to see what a given run did — which skills transitioned, what the LLM reviewer said, which skills it patched. Good for auditing without having to grep `agent.log`. :::note No candidates? Report shows `(not resolved)` When the curator has no agent-created skills to review, the LLM review pass is skipped entirely. The report header will show `Model: (not resolved) via (not resolved)` with `Duration: 0s` — this does not indicate a configuration error or model resolution failure. It simply means there were no candidates, so no model was ever invoked. The auto-transition phase still runs and reports its counts normally. ::: ### Rename map in the summary If a run consolidated multiple skills under an umbrella (or merged near-duplicates), the user-visible summary printed at the end of the run includes an explicit rename map showing every `old-name → new-name` pair the curator applied. This is in addition to per-skill transition lines, so when a wave of renames lands you can spot them at a glance without diffing the JSON report. The hint also surfaces under `hermes curator pin` so you can pin the umbrella name immediately if you want to lock the new label in. ## Restoring an archived skill If the curator archived something you still want: `bash hermes curator restore <skill-name>` This moves the skill back from `~/.hermes/skills/.archive/` to the active tree and resets its state to `active`. The restore refuses if a bundled or hub-installed skill has since been installed under the same name (would shadow upstream). ## Disabling per environment The curator is on by default. To turn it off: - For one profile only: edit `~/.hermes/config.yaml` (or the active profile’s config) and set `curator.enabled: false`. - For just one run: `hermes curator pause` — the pause persists across sessions; use `resume` to re-enable. The curator also refuses to run if `min_idle_hours` hasn’t elapsed, so on an active dev machine it naturally only runs during quiet stretches. ## See also - Skills System — how skills work in general and the self-improvement loop that creates them - Memory — a parallel background review that maintains long-term memory - Bundled Skills Catalog - Issue #7816 — original proposal and design discussion — # Persistent Memory # Persistent Memory Hermes Agent has bounded, curated memory that persists across sessions. This lets it remember your preferences, your projects, your environment, and things it has learned. ## How It Works Two files make up the agent’s memory: | File | Purpose | Char Limit | |——|———|————| | MEMORY.md | Agent’s personal notes — environment facts, conventions, things learned | 2,200 chars (800 tokens) | | USER.md | User profile — your preferences, communication style, expectations | 1,375 chars (500 tokens) | Both are stored in `~/.hermes/memories/` and are injected into the system prompt as a frozen snapshot at session start. The agent manages its own memory via the `memory` tool — it can add, replace, or remove entries. :::info Character limits keep memory focused. When memory is full, the agent consolidates or replaces entries to make room for new information. ::: ## How Memory Appears in the System Prompt At the start of every session, memory entries are loaded from disk and rendered into the system prompt as a frozen block: ══════════════════════════════════════════════ MEMORY (your personal notes) [67% — 1,474/2,200 chars] ══════════════════════════════════════════════ User's project is a Rust web service at ~/code/myapi using Axum + SQLx § This machine runs Ubuntu 22.04, has Docker and Podman installed § User prefers concise responses, dislikes verbose explanations The format includes: - A header showing which store (MEMORY or USER PROFILE) - Usage percentage and character counts so the agent knows capacity - Individual entries separated by `§` (section sign) delimiters - Entries can be multiline Frozen snapshot pattern: The system prompt injection is captured once at session start and never changes mid-session. This is intentional — it preserves the LLM’s prefix cache for performance. When the agent adds/removes memory entries during a session, the changes are persisted to disk immediately but won’t appear in the system prompt until the next session starts. Tool responses always show the live state. ## Memory Tool Actions The agent uses the `memory` tool with these actions: - add — Add a new memory entry - replace — Replace an existing entry with updated content (uses substring matching via `old_text`) - remove — Remove an entry that’s no longer relevant (uses substring matching via `old_text`) There is no `read` action — memory content is automatically injected into the system prompt at session start. The agent sees its memories as part of its conversation context. ### Substring Matching The `replace` and `remove` actions use short unique substring matching — you don’t need the full entry text. The `old_text` parameter just needs to be a unique substring that identifies exactly one entry: `python # If memory contains "User prefers dark mode in all editors" memory(action="replace", target="memory", old_text="dark mode", content="User prefers light mode in VS Code, dark mode in terminal")` If the substring matches multiple entries, an error is returned asking for a more specific match. ## Two Targets Explained ### `memory` — Agent’s Personal Notes For information the agent needs to remember about the environment, workflows, and lessons learned: - Environment facts (OS, tools, project structure) - Project conventions and configuration - Tool quirks and workarounds discovered - Completed task diary entries - Skills and techniques that worked ### `user` — User Profile For information about the user’s identity, preferences, and communication style: - Name, role, timezone - Communication preferences (concise vs detailed, format preferences) - Pet peeves and things to avoid - Workflow habits - Technical skill level ## What to Save vs Skip ### Save These (Proactively) The agent saves automatically — you don’t need to ask. It saves when it learns: - User preferences: “I prefer TypeScript over JavaScript” → save to `user` - Environment facts: “This server runs Debian 12 with PostgreSQL 16” → save to `memory` - Corrections: “Don’t use `sudo` for Docker commands, user is in docker group” → save to `memory` - Conventions: “Project uses tabs, 120-char line width, Google-style docstrings” → save to `memory` - Completed work: “Migrated database from MySQL to PostgreSQL on 2026-01-15” → save to `memory` - Explicit requests: “Remember that my API key rotation happens monthly” → save to `memory` ### Skip These - Trivial/obvious info: “User asked about Python” — too vague to be useful - Easily re-discovered facts: “Python 3.12 supports f-string nesting” — can web search this - Raw data dumps: Large code blocks, log files, data tables — too big for memory - Session-specific ephemera: Temporary file paths, one-off debugging context - Information already in context files: SOUL.md and AGENTS.md content ## Capacity Management Memory has strict character limits to keep system prompts bounded: | Store | Limit | Typical entries | |—––|—––|––––––––| | memory | 2,200 chars | 8-15 entries | | user | 1,375 chars | 5-10 entries | ### What Happens When Memory is Full When you try to add an entry that would exceed the limit, the tool returns an error: `json { "success": false, "error": "Memory at 2,100/2,200 chars. Adding this entry (250 chars) would exceed the limit. Consolidate now: use 'replace' to merge overlapping entries into shorter ones or 'remove' stale or less important entries (see current_entries below), then retry this add — all in this turn.", "current_entries": ["..."], "usage": "2,100/2,200" }` The agent should then: 1. Read the current entries (shown in the error response) 2. Identify entries that can be removed or consolidated 3. Use `replace` to merge related entries into shorter versions 4. Then `add` the new entry Best practice: When memory is above 80% capacity (visible in the system prompt header), consolidate entries before adding new ones. For example, merge three separate “project uses X” entries into one comprehensive project description entry. ### Practical Examples of Good Memory Entries Compact, information-dense entries work best: # Good: Packs multiple related facts User runs macOS 14 Sonoma, uses Homebrew, has Docker Desktop and Podman. Shell: zsh with oh-my-zsh. Editor: VS Code with Vim keybindings. # Good: Specific, actionable convention Project ~/code/api uses Go 1.22, sqlc for DB queries, chi router. Run tests with 'make test'. CI via GitHub Actions. # Good: Lesson learned with context The staging server (10.0.1.50) needs SSH port 2222, not 22. Key is at ~/.ssh/staging_ed25519. # Bad: Too vague User has a project. # Bad: Too verbose On January 5th, 2026, the user asked me to look at their project which is located at ~/code/api. I discovered it uses Go version 1.22 and... ## Duplicate Prevention The memory system automatically rejects exact duplicate entries. If you try to add content that already exists, it returns success with a “no duplicate added” message. ## Security Scanning Memory entries are scanned for injection and exfiltration patterns before being accepted, since they’re injected into the system prompt. Content matching threat patterns (prompt injection, credential exfiltration, SSH backdoors) or containing invisible Unicode characters is blocked. ## Session Search Beyond MEMORY.md and USER.md, the agent can search its past conversations using the `session_search` tool: - All CLI and messaging sessions are stored in SQLite (`~/.hermes/state.db`) with FTS5 full-text search - Search queries return actual messages from the DB — no LLM summarization, no truncation - The agent can find things it discussed weeks ago, even if they’re not in its active memory - The agent can also scroll forward/backward inside any session it finds `bash hermes sessions list # Browse past sessions` See Session Search Tool for the three calling shapes (discovery / scroll / browse) and the response format. ### session_search vs memory | Feature | Persistent Memory | Session Search | |———|——————|––––––––| | Capacity | 1,300 tokens total | Unlimited (all sessions) | | Speed | Instant (in system prompt) | 20ms FTS5 query, 1ms scroll | | Cost | Token cost in every prompt | Free — no LLM calls | | Use case | Key facts always available | Finding specific past conversations | | Management | Manually curated by agent | Automatic — all sessions stored | | Token cost | Fixed per session (1,300 tokens) | On-demand (searched when needed) | Memory is for critical facts that should always be in context. Session search is for “did we discuss X last week?” queries where the agent needs to recall specifics from past conversations. ## Configuration `yaml # In ~/.hermes/config.yaml memory: memory_enabled: true user_profile_enabled: true memory_char_limit: 2200 # ~800 tokens user_char_limit: 1375 # ~500 tokens write_approval: false # false = write freely (default) | true = require approval` ## Controlling memory writes (`write_approval`) By default the agent saves memory freely — including from the background self-improvement review that runs after a turn. If you’d rather approve saves first, set `memory.write_approval: true`. It’s a simple on/off gate applied to both foreground turns and the background review: | `write_approval` | Behaviour | |——————|———–| | `false` (default) | Write freely — the gate is off (the pre-gate behaviour). | | `true` | Require approval before anything is saved. Foreground writes prompt you inline (entries are small enough to read in a chat bubble). Background-review writes are staged instead of committed (a background thread can’t block on a prompt). | > To turn memory off entirely (not just gate it), set `memory_enabled: false`. Review staged writes from the CLI or any messaging platform: `/memory pending # list staged memory writes (auto ones tagged [auto]) /memory approve <id> # apply one (or 'all') /memory reject <id> # drop one (or 'all') /memory approval on # turn the gate on (or 'off') and persist it` This is the answer to “the agent saved a wrong assumption about me”: set `write_approval: true`, and every save — especially the unprompted background ones — waits for your yes/no before it ever enters your profile. ## Controlling skill writes (`skills.write_approval`) Skills use the same on/off gate, but the review UX differs because a `SKILL.md` is far too large to read in a chat bubble: `yaml skills: write_approval: false # false = write freely (default) | true = require approval` When `write_approval: true`, skill writes (create / edit / patch / write_file / delete) always stage regardless of origin. You review the one-line gist inline, but the full diff stays out-of-band: `/skills pending # list staged skill writes + a one-line gist each /skills diff <id> # full unified diff (best viewed in CLI or dashboard) /skills approve <id> # apply it (or 'all') /skills reject <id> # drop it (or 'all') /skills approval on # turn the gate on (or 'off') and persist it` On a messaging platform, approve a skill from its gist + metadata, or open `/skills diff` on the CLI / dashboard / the staged file under `~/.hermes/pending/skills/<id>.json` when you want to read the whole change. ## External Memory Providers For deeper, persistent memory that goes beyond MEMORY.md and USER.md, Hermes ships with 8 external memory provider plugins — including Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover, and Supermemory. External providers run alongside built-in memory (never replacing it) and add capabilities like knowledge graphs, semantic search, automatic fact extraction, and cross-session user modeling. `bash hermes memory setup # pick a provider and configure it hermes memory status # check what's active` See the Memory Providers guide for full details on each provider, setup instructions, and comparison. — # Memory Providers # Memory Providers Hermes Agent ships with 8 external memory provider plugins that give the agent persistent, cross-session knowledge beyond the built-in MEMORY.md and USER.md. Only one external provider can be active at a time — the built-in memory is always active alongside it. ## Quick Start `bash hermes memory setup # interactive picker + configuration hermes memory status # check what's active hermes memory off # disable external provider` You can also select the active memory provider via `hermes plugins` → Provider Plugins → Memory Provider. Or set manually in `~/.hermes/config.yaml`: `yaml memory: provider: openviking # or honcho, mem0, hindsight, holographic, retaindb, byterover, supermemory` ## How It Works When a memory provider is active, Hermes automatically: 1. Injects provider context into the system prompt (what the provider knows) 2. Prefetches relevant memories before each turn (background, non-blocking) 3. Syncs conversation turns to the provider after each response 4. Extracts memories on session end (for providers that support it) 5. Mirrors built-in memory writes to the external provider 6. Adds provider-specific tools so the agent can search, store, and manage memories The built-in memory (MEMORY.md / USER.md) continues to work exactly as before. The external provider is additive. ## Available Providers ### Honcho AI-native cross-session user modeling with dialectic reasoning, session-scoped context injection, semantic search, and persistent conclusions. Base context now includes the session summary alongside user representation and peer cards, giving the agent awareness of what has already been discussed. | | | |—|—| | Best for | Multi-agent systems with cross-session context, user-agent alignment | | Requires | `pip install honcho-ai` + API key or self-hosted instance | | Data storage | Honcho Cloud or self-hosted | | Cost | Honcho pricing (cloud) / free (self-hosted) | Tools (5): `honcho_profile` (read/update peer card), `honcho_search` (semantic search), `honcho_context` (session context — summary, representation, card, messages), `honcho_reasoning` (LLM-synthesized), `honcho_conclude` (create/delete conclusions) Architecture: Two-layer context injection — a base layer (session summary + representation + peer card, refreshed on `contextCadence`) plus a dialectic supplement (LLM reasoning, refreshed on `dialecticCadence`). The dialectic automatically selects cold-start prompts (general user facts) vs. warm prompts (session-scoped context) based on whether base context exists. Three orthogonal config knobs control cost and depth independently: - `contextCadence` — how often the base layer refreshes (API call frequency) - `dialecticCadence` — how often the dialectic LLM fires (LLM call frequency) - `dialecticDepth` — how many `.chat()` passes per dialectic invocation (1–3, depth of reasoning) Setup Wizard: `bash hermes memory setup # select "honcho" — runs the Honcho-specific post-setup` The legacy `hermes honcho setup` command still works (it now redirects to `hermes memory setup`), but is only registered after Honcho is selected as the active memory provider. Config: `$HERMES_HOME/honcho.json` (profile-local) or `~/.honcho/config.json` (global). Resolution order: `$HERMES_HOME/honcho.json` > `~/.hermes/honcho.json` > `~/.honcho/config.json`. See the config reference and the Honcho integration guide.

Full config reference
| Key | Default | Description | |—–|———|———––| | `apiKey` | – | API key from app.honcho.dev | | `baseUrl` | – | Base URL for self-hosted Honcho | | `peerName` | – | User peer identity | | `aiPeer` | host key | AI peer identity (one per profile) | | `workspace` | host key | Shared workspace ID | | `contextTokens` | `null` (uncapped) | Token budget for auto-injected context per turn. Truncates at word boundaries | | `contextCadence` | `1` | Minimum turns between `context()` API calls (base layer refresh) | | `dialecticCadence` | `2` | Minimum turns between `peer.chat()` LLM calls. Recommended 1–5. Only applies to `hybrid`/`context` modes | | `dialecticDepth` | `1` | Number of `.chat()` passes per dialectic invocation. Clamped 1–3. Pass 0: cold/warm prompt, pass 1: self-audit, pass 2: reconciliation | | `dialecticDepthLevels` | `null` | Optional array of reasoning levels per pass, e.g. `["minimal", "low", "medium"]`. Overrides proportional defaults | | `dialecticReasoningLevel` | `'low'` | Base reasoning level: `minimal`, `low`, `medium`, `high`, `max` | | `dialecticDynamic` | `true` | When `true`, model can override reasoning level per-call via tool param | | `dialecticMaxChars` | `600` | Max chars of dialectic result injected into system prompt | | `recallMode` | `'hybrid'` | `hybrid` (auto-inject + tools), `context` (inject only), `tools` (tools only) | | `writeFrequency` | `'async'` | When to flush messages: `async` (background thread), `turn` (sync), `session` (batch on end), or integer N | | `saveMessages` | `true` | Whether to persist messages to Honcho API | | `observationMode` | `'directional'` | `directional` (all on) or `unified` (shared pool). Override with `observation` object | | `messageMaxChars` | `25000` | Max chars per message (chunked if exceeded) | | `dialecticMaxInputChars` | `10000` | Max chars for dialectic query input to `peer.chat()` | | `sessionStrategy` | `'per-directory'` | `per-directory`, `per-repo`, `per-session`, `global` |

Minimal honcho.json (cloud)
`json { "apiKey": "your-key-from-app.honcho.dev", "hosts": { "hermes": { "enabled": true, "aiPeer": "hermes", "peerName": "your-name", "workspace": "hermes" } } }`

Minimal honcho.json (self-hosted)
`json { "baseUrl": "http://localhost:8000", "hosts": { "hermes": { "enabled": true, "aiPeer": "hermes", "peerName": "your-name", "workspace": "hermes" } } }`
:::tip Migrating from `hermes honcho` If you previously used `hermes honcho setup`, your config and all server-side data are intact. Just re-enable through the setup wizard again or manually set `memory.provider: honcho` to reactivate via the new system. ::: Multi-peer setup: Honcho models conversations as peers exchanging messages — one user peer plus one AI peer per Hermes profile, all sharing a workspace. The workspace is the shared environment: the user peer is global across profiles, each AI peer is its own identity. Every AI peer builds an independent representation / card from its own observations, so a `coder` profile stays code-oriented while a `writer` profile stays editorial against the same user. The mapping: | Concept | What it is | |———|———–| | Workspace | Shared environment. All Hermes profiles under one workspace see the same user identity. | | User peer (`peerName`) | The human. Shared across profiles in the workspace. | | AI peer (`aiPeer`) | One per Hermes profile. Host key `hermes` → default; `hermes.<profile>` for others. | | Observation | Per-peer toggles controlling what Honcho models from whose messages. `directional` (default, all four on) or `unified` (single-observer pool). | ### New profile, fresh Honcho peer `bash hermes profile create coder --clone` `--clone` creates a `hermes.coder` host block in `honcho.json` with `aiPeer: "coder"`, shared `workspace`, inherited `peerName`, `recallMode`, `writeFrequency`, `observation`, etc. The AI peer is eagerly created in Honcho so it exists before the first message. ### Existing profiles, backfill Honcho peers `bash hermes honcho sync` Scans every Hermes profile, creates host blocks for any profile without one, inherits settings from the default `hermes` block, and creates the new AI peers eagerly. Idempotent — skips profiles that already have a host block. ### Per-profile observation Each host block can override the observation config independently. Example: a code-focused profile where the AI peer observes the user but doesn’t self-model: `json "hermes.coder": { "aiPeer": "coder", "observation": { "user": { "observeMe": true, "observeOthers": true }, "ai": { "observeMe": false, "observeOthers": true } } }` Observation toggles (one set per peer): | Toggle | Effect | |––––|––––| | `observeMe` | Honcho builds a representation of this peer from its own messages | | `observeOthers` | This peer observes the other peer’s messages (feeds cross-peer reasoning) | Presets via `observationMode`: - `"directional"` (default) — all four flags on. Full mutual observation; enables cross-peer dialectic. - `"unified"` — user `observeMe: true`, AI `observeOthers: true`, rest false. Single-observer pool; AI models the user but not itself, user peer only self-models. Server-side toggles set via the Honcho dashboard win over local defaults — synced back at session init. See the Honcho page for the full observation reference.

Full honcho.json example (multi-profile)
json { "apiKey": "your-key", "workspace": "hermes", "peerName": "eri", "hosts": { "hermes": { "enabled": true, "aiPeer": "hermes", "workspace": "hermes", "peerName": "eri", "recallMode": "hybrid", "writeFrequency": "async", "sessionStrategy": "per-directory", "observation": { "user": { "observeMe": true, "observeOthers": true }, "ai": { "observeMe": true, "observeOthers": true } }, "dialecticReasoningLevel": "low", "dialecticDynamic": true, "dialecticCadence": 2, "dialecticDepth": 1, "dialecticMaxChars": 600, "contextCadence": 1, "messageMaxChars": 25000, "saveMessages": true }, "hermes.coder": { "enabled": true, "aiPeer": "coder", "workspace": "hermes", "peerName": "eri", "recallMode": "tools", "observation": { "user": { "observeMe": true, "observeOthers": false }, "ai": { "observeMe": true, "observeOthers": true } } }, "hermes.writer": { "enabled": true, "aiPeer": "writer", "workspace": "hermes", "peerName": "eri" } }, "sessions": { "/home/user/myproject": "myproject-main" } }
See the config reference and Honcho integration guide. — ### OpenViking Context database by Volcengine (ByteDance) with filesystem-style knowledge hierarchy, tiered retrieval, and automatic memory extraction into 6 categories. | | | |—|—| | Best for | Self-hosted knowledge management with structured browsing | | Requires | `pip install openviking` + running server | | Data storage | Self-hosted (local or cloud) | | Cost | Free (open-source, AGPL-3.0) | Tools: `viking_search` (semantic search), `viking_read` (tiered: abstract/overview/full), `viking_browse` (filesystem navigation), `viking_remember` (store facts), `viking_add_resource` (ingest URLs/docs) Setup: `bash # Start the OpenViking server first pip install openviking openviking-server # Then configure Hermes hermes memory setup # select "openviking" # Or manually: hermes config set memory.provider openviking echo "OPENVIKING_ENDPOINT=http://localhost:1933" >> ~/.hermes/.env` Key features: - Tiered context loading: L0 (100 tokens) → L1 (2k) → L2 (full) - Automatic memory extraction on session commit (profile, preferences, entities, events, cases, patterns) - `viking://` URI scheme for hierarchical knowledge browsing — ### Mem0 Server-side LLM fact extraction with semantic search, reranking, and automatic deduplication. | | | |—|—| | Best for | Hands-off memory management — Mem0 handles extraction automatically | | Requires | `pip install mem0ai` + API key | | Data storage | Mem0 Cloud | | Cost | Mem0 pricing | Tools: `mem0_profile` (all stored memories), `mem0_search` (semantic search + reranking), `mem0_conclude` (store verbatim facts) Setup: `bash hermes memory setup # select "mem0" # Or manually: hermes config set memory.provider mem0 echo "MEM0_API_KEY=your-key" >> ~/.hermes/.env` Config: `$HERMES_HOME/mem0.json` | Key | Default | Description | |—–|———|———––| | `user_id` | `hermes-user` | User identifier | | `agent_id` | `hermes` | Agent identifier | — ### Hindsight Long-term memory with knowledge graph, entity resolution, and multi-strategy retrieval. The `hindsight_reflect` tool provides cross-memory synthesis that no other provider offers. Automatically retains full conversation turns (including tool calls) with session-level document tracking. | | | |—|—| | Best for | Knowledge graph-based recall with entity relationships | | Requires | Cloud: API key from ui.hindsight.vectorize.io. Local: LLM API key (OpenAI, Groq, OpenRouter, etc.) | | Data storage | Hindsight Cloud or local embedded PostgreSQL | | Cost | Hindsight pricing (cloud) or free (local) | Tools: `hindsight_retain` (store with entity extraction), `hindsight_recall` (multi-strategy search), `hindsight_reflect` (cross-memory synthesis) Setup: `bash hermes memory setup # select "hindsight" # Or manually: hermes config set memory.provider hindsight echo "HINDSIGHT_API_KEY=your-key" >> ~/.hermes/.env` The setup wizard installs dependencies automatically and only installs what’s needed for the selected mode (`hindsight-client` for cloud, `hindsight-all` for local). Requires `hindsight-client >= 0.4.22` (auto-upgraded on session start if outdated). Local mode UI: `hindsight-embed -p hermes ui start` Config: `$HERMES_HOME/hindsight/config.json` | Key | Default | Description | |—–|———|———––| | `mode` | `cloud` | `cloud` or `local` | | `bank_id` | `hermes` | Memory bank identifier | | `recall_budget` | `mid` | Recall thoroughness: `low` / `mid` / `high` | | `memory_mode` | `hybrid` | `hybrid` (context + tools), `context` (auto-inject only), `tools` (tools only) | | `auto_retain` | `true` | Automatically retain conversation turns | | `auto_recall` | `true` | Automatically recall memories before each turn | | `retain_async` | `true` | Process retain asynchronously on the server | | `retain_context` | `conversation between Hermes Agent and the User` | Context label for retained memories | | `retain_tags` | — | Default tags applied to retained memories; merged with per-call tool tags | | `retain_source` | — | Optional `metadata.source` attached to retained memories | | `retain_user_prefix` | `User` | Label used before user turns in auto-retained transcripts | | `retain_assistant_prefix` | `Assistant` | Label used before assistant turns in auto-retained transcripts | | `recall_tags` | — | Tags to filter on recall | See plugin README for the full configuration reference. — ### Holographic Local SQLite fact store with FTS5 full-text search, trust scoring, and HRR (Holographic Reduced Representations) for compositional algebraic queries. | | | |—|—| | Best for | Local-only memory with advanced retrieval, no external dependencies | | Requires | Nothing (SQLite is always available). NumPy optional for HRR algebra. | | Data storage | Local SQLite | | Cost | Free | Tools: `fact_store` (9 actions: add, search, probe, related, reason, contradict, update, remove, list), `fact_feedback` (helpful/unhelpful rating that trains trust scores) Setup: `bash hermes memory setup # select "holographic" # Or manually: hermes config set memory.provider holographic` Config: `config.yaml` under `plugins.hermes-memory-store` | Key | Default | Description | |—–|———|———––| | `db_path` | `$HERMES_HOME/memory_store.db` | SQLite database path | | `auto_extract` | `false` | Auto-extract facts at session end | | `default_trust` | `0.5` | Default trust score (0.0–1.0) | Unique capabilities: - `probe` — entity-specific algebraic recall (all facts about a person/thing) - `reason` — compositional AND queries across multiple entities - `contradict` — automated detection of conflicting facts - Trust scoring with asymmetric feedback (+0.05 helpful / -0.10 unhelpful) — ### RetainDB Cloud memory API with hybrid search (Vector + BM25 + Reranking), 7 memory types, and delta compression. | | | |—|—| | Best for | Teams already using RetainDB’s infrastructure | | Requires | RetainDB account + API key | | Data storage | RetainDB Cloud | | Cost | $20/month | Tools: `retaindb_profile` (user profile), `retaindb_search` (semantic search), `retaindb_context` (task-relevant context), `retaindb_remember` (store with type + importance), `retaindb_forget` (delete memories) Setup: ```bash hermes memory setup # select "retaindb" # Or manually: hermes config set memory.provider retaindb echo "RETAINDB_API_KEY=your-key" >> ~/.hermes/.env ``` --- ### ByteRover Persistent memory via the `brv` CLI — hierarchical knowledge tree with tiered retrieval (fuzzy text \to LLM-driven search). Local-first with optional cloud sync. | | | |---|---| | Best for | Developers who want portable, local-first memory with a CLI | | Requires | ByteRover CLI (`npm install -g byterover-cli` or [install script](https://byterover.dev)) | | Data storage | Local (default) or ByteRover Cloud (optional sync) | | Cost | Free (local) or ByteRover pricing (cloud) | Tools: `brv_query` (search knowledge tree), `brv_curate` (store facts/decisions/patterns), `brv_status` (CLI version + tree stats) Setup: ```bash # Install the CLI first curl -fsSL https://byterover.dev/install.sh | sh # Then configure Hermes hermes memory setup # select "byterover" # Or manually: hermes config set memory.provider byterover ``` Key features: - Automatic pre-compression extraction (saves insights before context compression discards them) - Knowledge tree stored at `$ HERMES_HOME/byterover/`(profile-scoped) - SOC2 Type II certified cloud sync (optional) --- ### Supermemory Semantic long-term memory with profile recall, semantic search, explicit memory tools, and session-end conversation ingest via the Supermemory graph API. | | | |---|---| | Best for | Semantic recall with user profiling and session-level graph building | | Requires |`pip install supermemory`+ [API key](https://supermemory.ai) | | Data storage | Supermemory Cloud | | Cost | Supermemory pricing | Tools:`supermemory_store`(save explicit memories),`supermemory_search`(semantic similarity search),`supermemory_forget`(forget by ID or best-match query),`supermemory_profile(persistent profile + recent context) Setup: ```bash hermes memory setup # select "supermemory" # Or manually: hermes config set memory.provider supermemory echo 'SUPERMEMORY_API_KEY=' >> ~/.hermes/.env ``` Config:$HERMES_HOME/supermemory.json`| Key | Default | Description | |-----|---------|-------------| |`container_tag`|`hermes`| Container tag used for search and writes. Supports`{identity}`template for profile-scoped tags. | |`auto_recall`|`true`| Inject relevant memory context before turns | |`auto_capture`|`true`| Store cleaned user-assistant turns after each response | |`max_recall_results`|`10`| Max recalled items to format into context | |`profile_frequency`|`50`| Include profile facts on first turn and every N turns | |`capture_mode`|`all`| Skip tiny or trivial turns by default | |`search_mode`|`hybrid`| Search mode:`hybrid`,` memories`, or` documents`| |`api_timeout`|`5.0`| Timeout for SDK and ingest requests | Environment variables:`SUPERMEMORY_API_KEY`(required),`SUPERMEMORY_CONTAINER_TAG`(overrides config). Key features: - Automatic context fencing — strips recalled memories from captured turns to prevent recursive memory pollution - Full-session ingest — the entire conversation is sent once at session boundaries - Session-end conversation ingest (to`/v4/conversations`) for richer profile + graph building in Supermemory - Profile facts injected on first turn and at configurable intervals - Profile-scoped containers — use` {identity}`in`container_tag`(e.g.`hermes-{identity}`→`hermes-coder`) to isolate memories per Hermes profile - Multi-container mode — enable` enable_custom_container_tags`with a`custom_containerslist to let the agent read/write across named containers. Automatic operations stay on the primary container. <details> <summary>Multi-container example</summary> ```json { "container_tag": "hermes", "enable_custom_container_tags": true, "custom_containers": ["project-alpha", "shared-knowledge"], "custom_container_instructions": "Use project-alpha for coding context." } ``` </details> Support: [Discord](https://supermemory.link/discord) · [[email protected]](mailto:[email protected]) ### Memori Structured long-term memory using Memori Cloud, with background completed-turn capture, tool-aware turn context, and explicit recall tools for facts, summaries, quota, signup, and feedback. | | | |---|---| | Best for | Agent-controlled recall with structured project and session attribution | | Requires |pip install hermes-memori`+`hermes-memori install`+ [Memori API key](https://app.memorilabs.ai/signup) | | Data storage | Memori Cloud | | Cost | Memori pricing | Tools:`memori_recall`(search long-term memory),`memori_recall_summary`(summarized context),`memori_quota`(usage/quota),`memori_signup`(request signup email),`memori_feedback(send integration feedback) Setup: ```bash pip install hermes-memori hermes-memori install hermes config set memory.provider memori hermes memory setup ``` --- ## Provider Comparison | Provider | Storage | Cost | Tools | Dependencies | Unique Feature | |----------|---------|------|-------|-------------|----------------| | Honcho | Cloud | Paid | 5 |honcho-ai`| Dialectic user modeling + session-scoped context | | OpenViking | Self-hosted | Free | 5 |`openviking`+ server | Filesystem hierarchy + tiered loading | | Mem0 | Cloud | Paid | 3 |`mem0ai`| Server-side LLM extraction | | Hindsight | Cloud/Local | Free/Paid | 3 |`hindsight-client`| Knowledge graph + reflect synthesis | | Holographic | Local | Free | 2 | None | HRR algebra + trust scoring | | RetainDB | Cloud | $20/mo | 5 |`requests`| Delta compression | | ByteRover | Local/Cloud | Free/Paid | 3 |`brv`CLI | Pre-compression extraction | | Supermemory | Cloud | Paid | 4 |`supermemory`| Context fencing + session graph ingest + multi-container | | Memori | Cloud | Free/Paid | 5 |`hermes-memori`| Tool-aware memory + structured recall | ## Profile Isolation Each provider's data is isolated per [profile](/user-guide/profiles): - Local storage providers (Holographic, ByteRover) use` $HERMES_HOME/` paths which differ per profile - Config file providers (Honcho, Mem0, Hindsight, Supermemory) store config in `$ HERMES_HOME/`so each profile has its own credentials - Cloud providers (RetainDB) auto-derive profile-scoped project names - Env var providers (OpenViking) are configured via each profile's`.env`file ## Building a Memory Provider See the [Developer Guide: Memory Provider Plugins](/developer-guide/memory-provider-plugin) for how to create your own. ---  # Context Files # Context Files Hermes Agent automatically discovers and loads context files that shape how it behaves. Some are project-local and discovered from your working directory.`SOUL.md`is now global to the Hermes instance and is loaded from`HERMES_HOMEonly. ## Supported Context Files | File | Purpose | Discovery | |------|---------|-----------| | .hermes.md / HERMES.md | Project instructions (highest priority) | Walks to git root | | AGENTS.md | Project instructions, conventions, architecture | CWD at startup + subdirectories progressively | | CLAUDE.md | Claude Code context files (also detected) | CWD at startup + subdirectories progressively | | SOUL.md | Global personality and tone customization for this Hermes instance |HERMES_HOME/SOUL.md`only | | .cursorrules | Cursor IDE coding conventions | CWD only | | .cursor/rules/.mdc | Cursor IDE rule modules | CWD only | :::info Priority system Only one project context type is loaded per session (first match wins):`.hermes.md`→`AGENTS.md`→`CLAUDE.md`→`.cursorrules`. SOUL.md is always loaded independently as the agent identity (slot #1). ::: ## AGENTS.md` AGENTS.md`is the primary project context file. It tells the agent how your project is structured, what conventions to follow, and any special instructions. ### Progressive Subdirectory Discovery At session start, Hermes loads the`AGENTS.md`from your working directory into the system prompt. As the agent navigates into subdirectories during the session (via`read_file`,` terminal`,` search_files, etc.), it progressively discovers context files in those directories and injects them into the conversation at the moment they become relevant. ``` my-project/ ├── AGENTS.md ← Loaded at startup (system prompt) ├── frontend/ │ └── AGENTS.md ← Discovered when agent reads frontend/ files ├── backend/ │ └── AGENTS.md ← Discovered when agent reads backend/ files └── shared/ └── AGENTS.md ← Discovered when agent reads shared/ files ``` This approach has two advantages over loading everything at startup: - No system prompt bloat — subdirectory hints only appear when needed - Prompt cache preservation — the system prompt stays stable across turns Each subdirectory is checked at most once per session. The discovery also walks up parent directories, so reading backend/src/main.py`will discover`backend/AGENTS.md`even if`backend/src/has no context file of its own. :::info Subdirectory context files go through the same [security scan](#security-prompt-injection-protection) as startup context files. Malicious files are blocked. ::: ### Example AGENTS.md ```markdown # Project Context This is a Next.js 14 web application with a Python FastAPI backend. ## Architecture - Frontend: Next.js 14 with App Router in/frontend`- Backend: FastAPI in`/backend`, uses SQLAlchemy ORM - Database: PostgreSQL 16 - Deployment: Docker Compose on a Hetzner VPS ## Conventions - Use TypeScript strict mode for all frontend code - Python code follows PEP 8, use type hints everywhere - All API endpoints return JSON with` {data, error, meta}`shape - Tests go in`tests/`directories (frontend) or`tests/`(backend) ## Important Notes - Never modify migration files directly — use Alembic commands - The`.env.localfile has real API keys, don't commit it - Frontend port is 3000, backend is 8000, DB is 5432 ``` ## SOUL.mdSOUL.md`controls the agent's personality, tone, and communication style. See the [Personality](/user-guide/features/personality) page for full details. Location:** -`/.hermes/SOUL.md`- or`$HERMES_HOME/SOUL.md`if you run Hermes with a custom home directory Important details: - Hermes seeds a default`SOUL.md`automatically if one does not exist yet - Hermes loads`SOUL.md`only from`HERMES_HOME`- Hermes does not probe the working directory for`SOUL.md`- If the file is empty, nothing from`SOUL.md`is added to the prompt - If the file has content, the content is injected verbatim after scanning and truncation ## .cursorrules Hermes is compatible with Cursor IDE's`.cursorrules`file and`.cursor/rules/*.mdc `rule modules. If these files exist in your project root and no higher-priority context file (`.hermes.md`,` AGENTS.md`, or` CLAUDE.md`) is found, they're loaded as the project context. This means your existing Cursor conventions automatically apply when using Hermes. ## How Context Files Are Loaded ### At startup (system prompt) Context files are loaded by` build_context_files_prompt()`in`agent/prompt_builder.py`: 1. Scan working directory — checks for` .hermes.md`→`AGENTS.md`→`CLAUDE.md`→`.cursorrules`(first match wins) 2. Content is read — each file is read as UTF-8 text 3. Security scan — content is checked for prompt injection patterns 4. Truncation — files exceeding 20,000 characters are head/tail truncated (70% head, 20% tail, with a marker in the middle) 5. Assembly — all sections are combined under a`# Project Context`header 6. Injection — the assembled content is added to the system prompt ### During the session (progressive discovery)`SubdirectoryHintTracker`in`agent/subdirectory_hints.py `watches tool call arguments for file paths: 1. Path extraction — after each tool call, file paths are extracted from arguments (`path`,` workdir`, shell commands) 2. Ancestor walk — the directory and up to 5 parent directories are checked (stopping at already-visited directories) 3. Hint loading — if an` AGENTS.md`,` CLAUDE.md`, or` .cursorrulesis found, it's loaded (first match per directory) 4. Security scan — same prompt injection scan as startup files 5. Truncation — capped at 8,000 characters per file 6. Injection — appended to the tool result, so the model sees it in context naturally The final prompt section looks roughly like: ```text # Project Context The following project context files have been loaded and should be followed: ## AGENTS.md [Your AGENTS.md content here] ## .cursorrules [Your .cursorrules content here] [Your SOUL.md content here] ``` Notice that SOUL content is inserted directly, without extra wrapper text. ## Security: Prompt Injection Protection All context files are scanned for potential prompt injection before being included. The scanner checks for: - Instruction override attempts: "ignore previous instructions", "disregard your rules" - Deception patterns: "do not tell the user" - System prompt overrides: "system prompt override" - Hidden HTML comments:`- Hidden div elements:`
`- Credential exfiltration:`curl … HERMES_HOME/.env`These directories are fully blocked (any file inside): -`/.ssh/`,` /.aws/`,` /.gnupg/`,` /.kube/`,` $HERMES_HOME/skills/.hub/ `### Path Traversal Protection All paths are resolved relative to the working directory. References that resolve outside the allowed workspace root are rejected. ### Binary File Detection Binary files are detected via MIME type and null-byte scanning. Known text extensions (`.py`,` .md`,` .json`,` .yaml`,` .toml`,` .js`,` .ts`, etc.) bypass MIME-based detection. Binary files are rejected with a warning. ## Platform Availability Context references are primarily a CLI feature. They work in the interactive CLI where` @`triggers tab completion and references are expanded before the message is sent to the agent. In messaging platforms (Telegram, Discord, etc.), the`@`syntax is not expanded by the gateway — messages are passed through as-is. The agent itself can still reference files via the`read_file`,` search_files`, and` web_extract`tools. ## Interaction with Context Compression When conversation context is compressed, the expanded reference content is included in the compression summary. This means: - Large file contents injected via`@file: `contribute to context usage - If the conversation is later compressed, the file content is summarized (not preserved verbatim) - For very large files, consider using line ranges (`@file:main.py:100-200) to inject only relevant sections ## Common Patterns ```text # Code review workflow Review @diff and check for security issues # Debug with context This test is failing. Here's the test @file:tests/test_auth.py and the implementation @file:src/auth.py:50-80 # Project exploration What does this project do? @folder:src @file:README.md # Research Compare the approaches in @url:https://arxiv.org/abs/2301.00001 and @url:https://arxiv.org/abs/2301.00002 ``` ## Error Handling Invalid references produce inline warnings rather than failures: | Condition | Behavior | |-----------|----------| | File not found | Warning: "file not found" | | Binary file | Warning: "binary files are not supported" | | Folder not found | Warning: "folder not found" | | Git command fails | Warning with git stderr | | URL returns no content | Warning: "no content extracted" | | Sensitive path | Warning: "path is a sensitive credential file" | | Path outside workspace | Warning: "path is outside the allowed workspace" | ---  # Personality & SOUL.md # Personality & SOUL.md Hermes Agent's personality is fully customizable. SOUL.md`is the primary identity — it's the first thing in the system prompt and defines who the agent is. -`SOUL.md`— a durable persona file that lives in`HERMES_HOME`and serves as the agent's identity (slot #1 in the system prompt) - built-in or custom`/personality`presets — session-level system-prompt overlays If you want to change who Hermes is — or replace it with an entirely different agent persona — edit`SOUL.md`. ## How SOUL.md works now Hermes now seeds a default` SOUL.mdautomatically in: ```text ~/.hermes/SOUL.md ``` More precisely, it uses the current instance'sHERMES_HOME, so if you run Hermes with a custom home directory, it will use: ```text $HERMES_HOME/SOUL.md ``` ### Important behavior - SOUL.md is the agent's primary identity. It occupies slot #1 in the system prompt, replacing the hardcoded default identity. - Hermes creates a starter SOUL.md`automatically if one does not exist yet - Existing user`SOUL.md`files are never overwritten - Hermes loads`SOUL.md`only from`HERMES_HOME`- Hermes does not look in the current working directory for`SOUL.md`- If`SOUL.md`exists but is empty, or cannot be loaded, Hermes falls back to a built-in default identity - If`SOUL.md`has content, that content is injected verbatim after security scanning and truncation - SOUL.md is not duplicated in the context files section — it appears only once, as the identity That makes`SOUL.md`a true per-user or per-instance identity, not just an additive layer. ## Why this design This keeps personality predictable. If Hermes loaded`SOUL.md`from whatever directory you happened to launch it in, your personality could change unexpectedly between projects. By loading only from`HERMES_HOME`, the personality belongs to the Hermes instance itself. That also makes it easier to teach users: - "Edit` /.hermes/SOUL.mdto change Hermes' default personality." ## Where to edit it For most users: ```bash ~/.hermes/SOUL.md ``` If you use a custom home: ```bash $HERMES_HOME/SOUL.md ``` ## What should go in SOUL.md? Use it for durable voice and personality guidance, such as: - tone - communication style - level of directness - default interaction style - what to avoid stylistically - how Hermes should handle uncertainty, disagreement, or ambiguity Use it less for: - one-off project instructions - file paths - repo conventions - temporary workflow details Those belong inAGENTS.md`, not` SOUL.md. ## Good SOUL.md content A good SOUL file is: - stable across contexts - broad enough to apply in many conversations - specific enough to materially shape the voice - focused on communication and identity, not task-specific instructions ### Example ```markdown # Personality You are a pragmatic senior engineer with strong taste. You optimize for truth, clarity, and usefulness over politeness theater. ## Style - Be direct without being cold - Prefer substance over filler - Push back when something is a bad idea - Admit uncertainty plainly - Keep explanations compact unless depth is useful ## What to avoid - Sycophancy - Hype language - Repeating the user's framing if it's wrong - Overexplaining obvious things ## Technical posture - Prefer simple systems over clever systems - Care about operational reality, not idealized architecture - Treat edge cases as part of the design, not cleanup ``` ## What Hermes injects into the prompt SOUL.md`content goes directly into slot #1 of the system prompt — the agent identity position. No wrapper language is added around it. The content goes through: - prompt-injection scanning - truncation if it is too large If the file is empty, whitespace-only, or cannot be read, Hermes falls back to a built-in default identity ("You are Hermes Agent, an intelligent AI assistant created by Nous Research..."). This fallback also applies when`skip_context_files`is set (e.g., in subagent/delegation contexts). ## Security scanning`SOUL.mdis scanned like other context-bearing files for prompt injection patterns before inclusion. That means you should still keep it focused on persona/voice rather than trying to sneak in strange meta-instructions. ## SOUL.md vs AGENTS.md This is the most important distinction. ### SOUL.md Use for: - identity - tone - style - communication defaults - personality-level behavior ### AGENTS.md Use for: - project architecture - coding conventions - tool preferences - repo-specific workflows - commands, ports, paths, deployment notes A useful rule: - if it should follow you everywhere, it belongs inSOUL.md`- if it belongs to a project, it belongs in`AGENTS.md`## SOUL.md vs`/personality SOUL.md`is your durable default personality.`/personality`is a session-level overlay that changes or supplements the current system prompt. So: -`SOUL.md`= baseline voice -`/personality`= temporary mode switch Examples: - keep a pragmatic default SOUL, then use`/personality teacher`for a tutoring conversation - keep a concise SOUL, then use`/personality creative`for brainstorming ## Built-in personalities Hermes ships with built-in personalities you can switch to with`/personality. | Name | Description | |------|-------------| | helpful | Friendly, general-purpose assistant | | concise | Brief, to-the-point responses | | technical | Detailed, accurate technical expert | | creative | Innovative, outside-the-box thinking | | teacher | Patient educator with clear examples | | kawaii | Cute expressions, sparkles, and enthusiasm ★ | | catgirl | Neko-chan with cat-like expressions, nya~ | | pirate | Captain Hermes, tech-savvy buccaneer | | shakespeare | Bardic prose with dramatic flair | | surfer | Totally chill bro vibes | | noir | Hard-boiled detective narration | | uwu | Maximum cute with uwu-speak | | philosopher | Deep contemplation on every query | | hype | MAXIMUM ENERGY AND ENTHUSIASM!!! | ## Switching personalities with commands ### CLI ```text /personality /personality concise /personality technical ``` ### Messaging platforms ```text /personality teacher ``` These are convenient overlays, but your global SOUL.md`still gives Hermes its persistent default personality unless the overlay meaningfully changes it. ## Custom personalities in config You can also define named custom personalities in`/.hermes/config.yaml`under`agent.personalities. ```yaml agent: personalities: codereviewer: > You are a meticulous code reviewer. Identify bugs, security issues, performance concerns, and unclear design choices. Be precise and constructive. ``` Then switch to it with: ```text /personality codereviewer ``` ## Recommended workflow A strong default setup is: 1. Keep a thoughtful global SOUL.md`in`/.hermes/SOUL.md`2. Put project instructions in`AGENTS.md`3. Use`/personality `only when you want a temporary mode shift That gives you: - a stable voice - project-specific behavior where it belongs - temporary control when needed ## How personality interacts with the full prompt At a high level, the prompt stack includes: 1. SOUL.md (agent identity — or built-in fallback if SOUL.md is unavailable) 2. tool-aware behavior guidance 3. memory/user context 4. skills guidance 5. context files (`AGENTS.md`,` .cursorrules`) 6. timestamp 7. platform-specific formatting hints 8. optional system-prompt overlays such as` /personality SOUL.md`is the foundation — everything else builds on top of it. ## Related docs - [Context Files](/user-guide/features/context-files) - [Configuration](/user-guide/configuration) - [Tips & Best Practices](/guides/tips) - [SOUL.md Guide](/guides/use-soul-with-hermes) ## CLI appearance vs conversational personality Conversational personality and CLI appearance are separate: -`SOUL.md`,` agent.system_prompt`, and` /personality`affect how Hermes speaks -`display.skin`and`/skinaffect how Hermes looks in the terminal For terminal appearance, see [Skins & Themes](./skins.md). ---  # Plugins # Plugins Hermes has a plugin system for adding custom tools, hooks, and integrations without modifying core code. If you want to create a custom tool for yourself, your team, or one project, this is usually the right path. The developer guide's [Adding Tools](/developer-guide/adding-tools) page is for built-in Hermes core tools that live intools/`and`toolsets.py`. → [Build a Hermes Plugin](/guides/build-a-hermes-plugin) — step-by-step guide with a complete working example. ## Quick overview Drop a directory into` /.hermes/plugins/`with a`plugin.yamland Python code: ``` ~/.hermes/plugins/my-plugin/ ├── plugin.yaml # manifest ├── init.py # register() — wires schemas to handlers ├── schemas.py # tool schemas (what the LLM sees) └── tools.py # tool handlers (what runs when called) ``` Start Hermes — your tools appear alongside built-in tools. The model can call them immediately. ### Minimal working example Here is a complete plugin that adds ahello_world `tool and logs every tool call via a hook. `/.hermes/plugins/hello-world/plugin.yaml ```yaml name: hello-world version: "1.0" description: A minimal example plugin ``` /.hermes/plugins/hello-world/init.py ```python """Minimal Hermes plugin — registers a tool and a hook.""" import json def register(ctx): # --- Tool: hello_world --- schema = { "name": "hello_world", "description": "Returns a friendly greeting for the given name.", "parameters": { "type": "object", "properties": { "name": { "type": "string", "description": "Name to greet", } }, "required": ["name"], }, } def handle_hello(params, **kwargs): del kwargs name = params.get("name", "World") return json.dumps({"success": True, "greeting": f"Hello, {name}!"}) ctx.register_tool( name="hello_world", toolset="hello_world", schema=schema, handler=handle_hello, description="Return a friendly greeting for the given name.", ) # --- Hook: log every tool call --- def on_tool_call(tool_name, params, result): print(f"[hello-world] tool called: {tool_name}") ctx.register_hook("post_tool_call", on_tool_call) ``` Drop both files into /.hermes/plugins/hello-world/`, restart Hermes, and the model can immediately call` hello_world`. The hook prints a log line after every tool invocation. Project-local plugins under` ./.hermes/plugins/`are disabled by default. Enable them only for trusted repositories by setting`HERMES_ENABLE_PROJECT_PLUGINS=true`before starting Hermes. ## What plugins can do Every`ctx.`API below is available inside a plugin's`register(ctx)`function. | Capability | How | |-----------|-----| | Add tools |`ctx.register_tool(name=…, toolset=…, schema=…, handler=…)`| | Add hooks |`ctx.register_hook(“post_tool_call”, callback)`| | Add slash commands |`ctx.register_command(name, handler, description)`— adds`/name`in CLI and gateway sessions | | Dispatch tools from commands |`ctx.dispatch_tool(name, args)`— invokes a registered tool with parent-agent context auto-wired | | Add CLI commands |`ctx.register_cli_command(name, help, setup_fn, handler_fn)`— adds`hermes `| | Inject messages |`ctx.inject_message(content, role=“user”)`— see [Injecting Messages](#injecting-messages) | | Ship data files |`Path(file).parent / “data” / “file.yaml”`| | Bundle skills |`ctx.register_skill(name, path)`— namespaced as`plugin:skill`, loaded via` skill_view(“plugin:skill”)`| | Gate on env vars |`requires_env: [API_KEY]`in plugin.yaml — prompted during`hermes plugins install`| | Distribute via pip |`[project.entry-points.“hermes_agent.plugins”]`| | Register a gateway platform (Discord, Telegram, IRC, …) |`ctx.register_platform(name, label, adapter_factory, check_fn, …)`— see [Adding Platform Adapters](/developer-guide/adding-platform-adapters) | | Register an image-generation backend |`ctx.register_image_gen_provider(provider)`— see [Image Generation Provider Plugins](/developer-guide/image-gen-provider-plugin) | | Register a video-generation backend |`ctx.register_video_gen_provider(provider)`— see [Video Generation Provider Plugins](/developer-guide/video-gen-provider-plugin) | | Register a context-compression engine |`ctx.register_context_engine(engine)`— see [Context Engine Plugins](/developer-guide/context-engine-plugin) | | Register a memory backend | Subclass`MemoryProvider`in`plugins/memory//init.py`— see [Memory Provider Plugins](/developer-guide/memory-provider-plugin) (uses a separate discovery system) | | Run a host-owned LLM call |`ctx.llm.complete(…)`/`ctx.llm.complete_structured(…)`— borrow the user's active model + auth for a one-shot completion with optional JSON schema validation. See [Plugin LLM Access](/developer-guide/plugin-llm-access) | | Register an inference backend (LLM provider) |`register_provider(ProviderProfile(…))`in`plugins/model-providers//init.py`— see [Model Provider Plugins](/developer-guide/model-provider-plugin) (uses a separate discovery system) | ## Plugin discovery | Source | Path | Use case | |--------|------|----------| | Bundled |`/plugins/`| Ships with Hermes — see [Built-in Plugins](/user-guide/features/built-in-plugins) | | User |`/.hermes/plugins/`| Personal plugins | | Project |`.hermes/plugins/`| Project-specific plugins (requires`HERMES_ENABLE_PROJECT_PLUGINS=true`) | | pip |` hermes_agent.plugins`entry_points | Distributed packages | | Nix |`services.hermes-agent.extraPlugins`/`extraPythonPackages`| NixOS declarative installs — see [Nix Setup](/getting-started/nix-setup#plugins) | Later sources override earlier ones on name collision, so a user plugin with the same name as a bundled plugin replaces it. ### Plugin sub-categories Within each source, Hermes also recognizes sub-category directories that route plugins to specialized discovery systems: | Sub-directory | What it holds | Discovery system | |---|---|---| |`plugins/`(root) | General plugins — tools, hooks, slash commands, CLI commands, bundled skills |`PluginManager`(kind:`standalone`or`backend`) | |` plugins/platforms// `| Gateway channel adapters (`ctx.register_platform()`) |` PluginManager`(kind:`platform`, one level deeper) | |` plugins/image_gen// `| Image-generation backends (`ctx.register_image_gen_provider()`) |` PluginManager`(kind:`backend`, one level deeper) | |` plugins/memory//`| Memory providers (subclass`MemoryProvider`) | Own loader in` plugins/memory/init.py`(kind:`exclusive`— one active at a time) | |`plugins/context_engine// `| Context-compression engines (`ctx.register_context_engine()`) | Own loader in` plugins/context_engine/init.py`(one active at a time) | |`plugins/model-providers// `| LLM provider profiles (`register_provider(ProviderProfile(…))`) | Own loader in` providers/init.py`(lazily scanned on first`get_provider_profile()`call) | User plugins at`/.hermes/plugins/model-providers//`and`/.hermes/plugins/memory//`override bundled plugins of the same name — last-writer-wins in`register_provider()`/`register_memory_provider()`. Drop a directory in, and it replaces the built-in without any repo edits. ## Plugins are opt-in (with a few exceptions) General plugins and user-installed backends are disabled by default — discovery finds them (so they show up in` hermes plugins`and`/plugins`), but nothing with hooks or tools loads until you add the plugin's name to` plugins.enabled`in`/.hermes/config.yaml. This stops third-party code from running without your explicit consent. ```yaml plugins: enabled: - my-tool-plugin - disk-cleanup disabled: # optional deny-list — always wins if a name appears in both - noisy-plugin ``` Three ways to flip state: ```bash hermes plugins # interactive toggle (space to check/uncheck) hermes plugins enable <name> # add to allow-list hermes plugins disable <name> # remove from allow-list + add to disabled ``` After hermes plugins install owner/repo`, you're asked` Enable ‘name’ now? [y/N]`— defaults to no. Skip the prompt for scripted installs with`–enable`or`–no-enable`. ### What the allow-list does NOT gate Several categories of plugin bypass` plugins.enabled`— they're part of Hermes' built-in surface and would break basic functionality if gated off by default: | Plugin kind | How it's activated instead | |---|---| | Bundled platform plugins (IRC, Teams, etc. under`plugins/platforms/`) | Auto-loaded so every shipped gateway channel is available. The actual channel turns on via` gateway.platforms..enabled`in`config.yaml`. | | Bundled backends (image-gen providers under` plugins/image_gen/`, etc.) | Auto-loaded so the default backend "just works". Selection happens via` .provider`in`config.yaml`(e.g.`image_gen.provider: openai`). | | Memory providers (`plugins/memory/`) | All discovered; exactly one is active, chosen by` memory.provider`in`config.yaml`. | | Context engines (`plugins/context_engine/`) | All discovered; one is active, chosen by` context.engine`in`config.yaml`. | | Model providers (`plugins/model-providers/`) | All bundled providers under` plugins/model-providers/`discover and register at the first`get_provider_profile()`call. The user picks one at a time via`–provider`or`config.yaml`. | | Pip-installed` backend`plugins | Opt-in via`plugins.enabled`(same as general plugins). | | User-installed platforms (under`/.hermes/plugins/platforms/`) | Opt-in via` plugins.enabled`— third-party gateway adapters need explicit consent. | In short: bundled "always-works" infrastructure loads automatically; third-party general plugins are opt-in. The`plugins.enabled`allow-list is the gate specifically for arbitrary code a user drops into`/.hermes/plugins/`. ### Migration for existing users When you upgrade to a version of Hermes that has opt-in plugins (config schema v21+), any user plugins already installed under` /.hermes/plugins/`that weren't already in`plugins.disabled`are automatically grandfathered into`plugins.enabled`. Your existing setup keeps working. Bundled standalone plugins are NOT grandfathered — even existing users have to opt in explicitly. (Bundled platform/backend plugins never needed grandfathering because they were never gated.) ## Available hooks Plugins can register callbacks for these lifecycle events. See the [Event Hooks page](/user-guide/features/hooks#plugin-hooks) for full details, callback signatures, and examples. | Hook | Fires when | |------|-----------| | [`pre_tool_call`](/user-guide/features/hooks#pre_tool_call) | Before any tool executes | | [`post_tool_call`](/user-guide/features/hooks#post_tool_call) | After any tool returns | | [`pre_llm_call`](/user-guide/features/hooks#pre_llm_call) | Once per turn, before the LLM loop — can return` {“context”: “…”} `to [inject context into the user message](/user-guide/features/hooks#pre_llm_call) | | [`post_llm_call`](/user-guide/features/hooks#post_llm_call) | Once per turn, after the LLM loop (successful turns only) | | [`on_session_start`](/user-guide/features/hooks#on_session_start) | New session created (first turn only) | | [`on_session_end`](/user-guide/features/hooks#on_session_end) | End of every` run_conversation `call + CLI exit handler | | [`on_session_finalize`](/user-guide/features/hooks#on_session_finalize) | CLI/gateway tears down an active session (`/new`, GC, CLI quit) | | [`on_session_reset`](/user-guide/features/hooks#on_session_reset) | Gateway swaps in a new session key (`/new`,` /reset`,` /clear`, idle rotation) | | [`subagent_stop`](/user-guide/features/hooks#subagent_stop) | Once per child after` delegate_task `finishes | | [`pre_gateway_dispatch`](/user-guide/features/hooks#pre_gateway_dispatch) | Gateway received a user message, before auth + dispatch. Return` {“action”: “skip” | “rewrite” | “allow”, …}`to influence flow. | ## Plugin types Hermes has four kinds of plugins: | Type | What it does | Selection | Location | |------|-------------|-----------|----------| | General plugins | Add tools, hooks, slash commands, CLI commands | Multi-select (enable/disable) |`/.hermes/plugins/`| | Memory providers | Replace or augment built-in memory | Single-select (one active) |`plugins/memory/`| | Context engines | Replace the built-in context compressor | Single-select (one active) |`plugins/context_engine/`| | Model providers | Declare an inference backend (OpenRouter, Anthropic, …) | Multi-register, picked by`–provider`/`config.yaml`|`plugins/model-providers/`| Memory providers and context engines are provider plugins — only one of each type can be active at a time. Model providers are also plugins, but many load simultaneously; the user picks one at a time via`–provider`or`config.yaml`. General plugins can be enabled in any combination. ## Pluggable interfaces — where to go for each The table above shows the four plugin categories, but within "General plugins" the` PluginContext`exposes several distinct extension points — and Hermes also accepts extensions outside the Python plugin system (config-driven backends, shell-hooked commands, external servers, etc.). Use this table to find the right doc for what you want to build: | Want to add… | How | Authoring guide | |---|---|---| | A tool the LLM can call | Python plugin —`ctx.register_tool()`| [Build a Hermes Plugin](/guides/build-a-hermes-plugin) · [Adding Tools](/developer-guide/adding-tools) | | A lifecycle hook (pre/post LLM, session start/end, tool filter) | Python plugin —`ctx.register_hook()`| [Hooks reference](/user-guide/features/hooks) · [Build a Hermes Plugin](/guides/build-a-hermes-plugin) | | A slash command for the CLI / gateway | Python plugin —`ctx.register_command()`| [Build a Hermes Plugin](/guides/build-a-hermes-plugin) · [Extending the CLI](/developer-guide/extending-the-cli) | | A subcommand for`hermes `| Python plugin —`ctx.register_cli_command()`| [Extending the CLI](/developer-guide/extending-the-cli) | | A bundled skill that your plugin ships | Python plugin —`ctx.register_skill()`| [Creating Skills](/developer-guide/creating-skills) | | An inference backend (LLM provider: OpenAI-compat, Codex, Anthropic-Messages, Bedrock) | Provider plugin —`register_provider(ProviderProfile(…))`in`plugins/model-providers//`| [Model Provider Plugins](/developer-guide/model-provider-plugin) · [Adding Providers](/developer-guide/adding-providers) | | A gateway channel (Discord / Telegram / IRC / Teams / etc.) | Platform plugin —`ctx.register_platform()`in`plugins/platforms//`| [Adding Platform Adapters](/developer-guide/adding-platform-adapters) | | A memory backend (Honcho, Mem0, Supermemory, …) | Memory plugin — subclass`MemoryProvider`in`plugins/memory//`| [Memory Provider Plugins](/developer-guide/memory-provider-plugin) | | A context-compression strategy | Context-engine plugin —`ctx.register_context_engine()`| [Context Engine Plugins](/developer-guide/context-engine-plugin) | | An image-generation backend (DALL·E, SDXL, …) | Backend plugin —`ctx.register_image_gen_provider()`| [Image Generation Provider Plugins](/developer-guide/image-gen-provider-plugin) | | A video-generation backend (Veo, Kling, Pixverse, Grok-Imagine, Runway, …) | Backend plugin —`ctx.register_video_gen_provider()`| [Video Generation Provider Plugins](/developer-guide/video-gen-provider-plugin) | | A TTS backend (any CLI — Piper, VoxCPM, Kokoro, xtts, voice-cloning scripts, …) | Config-driven (recommended) — declare under`tts.providers.`with`type: command`in`config.yaml`. OR Python backend plugin —` ctx.register_tts_provider()`for Python-SDK / streaming engines that need more than a shell template. | [TTS Setup](/user-guide/features/tts#custom-command-providers) · [Python plugin guide](/user-guide/features/tts#python-plugin-providers) | | An STT backend (any CLI — whisper.cpp, custom whisper binary, local ASR CLI) | Config-driven (recommended) — declare under`stt.providers.`with`type: command`in`config.yaml`, or set` HERMES_LOCAL_STT_COMMAND`for the legacy single-command escape hatch. OR Python backend plugin —`ctx.register_transcription_provider()`for Python-SDK engines (OpenRouter, SenseAudio, Gemini-STT, etc.). | [STT Setup](/user-guide/features/tts#stt-custom-command-providers) · [Python plugin guide](/user-guide/features/tts#python-plugin-providers-stt) | | External tools via MCP (filesystem, GitHub, Linear, Notion, any MCP server) | Config-driven — declare`mcp_servers.`with`command:`/`url:`in`config.yaml`. Hermes auto-discovers the server's tools and registers them alongside built-ins. | [MCP](/user-guide/features/mcp) | | Additional skill sources (custom GitHub repos, private skill indexes) | CLI —` hermes skills tap add `| [Skills Hub](/user-guide/features/skills#skills-hub) · [Publishing a custom tap](/user-guide/features/skills#publishing-a-custom-skill-tap) | | Gateway event hooks (fire on`gateway:startup`,` session:start`,` agent:end`,` command:`) | Drop` HOOK.yaml`+`handler.py`into`/.hermes/hooks//`| [Event Hooks](/user-guide/features/hooks#gateway-event-hooks) | | Shell hooks (run a shell command on events — notifications, audit logs, desktop alerts) | Config-driven — declare under`hooks:`in`config.yaml| [Shell Hooks](/user-guide/features/hooks#shell-hooks) | :::note Not everything is a Python plugin. Some extension surfaces intentionally use config-driven shell commands (TTS, STT, shell hooks) so any CLI you already have becomes a plugin without writing Python. Others are external servers (MCP) the agent connects to and auto-registers tools from. And some are drop-in directories (gateway hooks) with their own manifest format. Pick the right surface for the integration style that fits your use case; the authoring guides in the table above each cover placeholders, discovery, and examples. ::: ## NixOS declarative plugins On NixOS, plugins can be installed declaratively via the module options — nohermes plugins installneeded. See the [Nix Setup guide](/getting-started/nix-setup#plugins) for full details. ```nix services.hermes-agent = { # Directory plugin (source tree with plugin.yaml) extraPlugins = [ (pkgs.fetchFromGitHub { ... }) ]; # Entry-point plugin (pip package) extraPythonPackages = [ (pkgs.python312Packages.buildPythonPackage { ... }) ]; # Enable in config settings.plugins.enabled = [ "my-plugin" ]; }; ``` Declarative plugins are symlinked with anix-managed-prefix — they coexist with manually installed plugins and are cleaned up automatically when removed from the Nix config. ## Managing plugins ```bash hermes plugins # unified interactive UI hermes plugins list # table: enabled / disabled / not enabled hermes plugins install user/repo # install from Git, then prompt Enable? [y/N] hermes plugins install user/repo --enable # install AND enable (no prompt) hermes plugins install user/repo --no-enable # install but leave disabled (no prompt) hermes plugins update my-plugin # pull latest hermes plugins remove my-plugin # uninstall hermes plugins enable my-plugin # add to allow-list hermes plugins disable my-plugin # remove from allow-list + add to disabled ``` ### Interactive UI Runninghermes pluginswith no arguments opens a composite interactive screen: ``` Plugins ↑↓ navigate SPACE toggle ENTER configure/confirm ESC done General Plugins → [✓] my-tool-plugin — Custom search tool [ ] webhook-notifier — Event hooks [ ] disk-cleanup — Auto-cleanup of ephemeral files [bundled] Provider Plugins Memory Provider ▸ honcho Context Engine ▸ compressor ``` - General Plugins section — checkboxes, toggle with SPACE. Checked = inplugins.enabled`, unchecked = in` plugins.disabled`(explicit off). - Provider Plugins section — shows current selection. Press ENTER to drill into a radio picker where you choose one active provider. - Bundled plugins appear in the same list with a`[bundled]`tag. Provider plugin selections are saved to`config.yaml: ```yaml memory: provider: "honcho" # empty string = built-in only context: engine: "compressor" # default built-in compressor ``` ### Enabled vs. disabled vs. neither Plugins occupy one of three states: | State | Meaning | In plugins.enabled`? | In` plugins.disabled`? | |---|---|---|---| |` enabled`| Loaded on next session | Yes | No | |`disabled`| Explicitly off — won't load even if also in`enabled`| (irrelevant) | Yes | |`not enabled`| Discovered but never opted in | No | No | The default for a newly-installed or bundled plugin is`not enabled`.` hermes plugins list`shows all three distinct states so you can tell what's been explicitly turned off vs. what's just waiting to be enabled. In a running session,`/plugins`shows which plugins are currently loaded. ## Injecting Messages Plugins can inject messages into the active conversation using`ctx.inject_message(): ```python ctx.inject_message("New data arrived from the webhook", role="user") ``` Signature: ctx.inject_message(content: str, role: str = “user”) -> bool `How it works: - If the agent is idle (waiting for user input), the message is queued as the next input and starts a new turn. - If the agent is mid-turn (actively running), the message interrupts the current operation — the same as a user typing a new message and pressing Enter. - For non-`“user”`roles, the content is prefixed with`[role]`(e.g.`[system] …`). - Returns` True`if the message was queued successfully,`False`if no CLI reference is available (e.g. in gateway mode). This enables plugins like remote control viewers, messaging bridges, or webhook receivers to feed messages into the conversation from external sources. :::note`inject_message`is only available in CLI mode. In gateway mode, there is no CLI reference and the method returns`False`. ::: See the [full guide](/guides/build-a-hermes-plugin) for handler contracts, schema format, hook behavior, error handling, and common mistakes. ---  # Built-in Plugins # Built-in Plugins Hermes ships a small set of plugins bundled with the repository. They live under` /plugins//`and load automatically alongside user-installed plugins in`/.hermes/plugins/`. They use the same plugin surface as third-party plugins — hooks, tools, slash commands — just maintained in-tree. See the [Plugins](/user-guide/features/plugins) page for the general plugin system, and [Build a Hermes Plugin](/guides/build-a-hermes-plugin) to write your own. ## How discovery works The` PluginManager`scans four sources, in order: 1. Bundled —`/plugins//`(what this page documents) 2. User —`/.hermes/plugins//`3. Project —`./.hermes/plugins//`(requires`HERMES_ENABLE_PROJECT_PLUGINS=1`) 4. Pip entry points —` hermes_agent.plugins`On name collision, later sources win — a user plugin named`disk-cleanup`would replace the bundled one.`plugins/memory/`and`plugins/context_engine/`are deliberately excluded from bundled scanning. Those directories use their own discovery paths because memory providers and context engines are single-select providers configured through`hermes memory setup`/`context.engine`in config. ## Bundled plugins are opt-in Bundled plugins ship disabled. Discovery finds them (they appear in`hermes plugins list`and the interactive`hermes pluginsUI), but none load until you explicitly enable them: ```bash hermes plugins enable disk-cleanup ``` Or via/.hermes/config.yaml: ```yaml plugins: enabled: - disk-cleanup ``` This is the same mechanism user-installed plugins use. Bundled plugins are never auto-enabled — not on fresh install, not for existing users upgrading to a newer Hermes. You always opt in explicitly. To turn a bundled plugin off again: ```bash hermes plugins disable disk-cleanup # or: remove it from plugins.enabled in config.yaml ``` ## Currently shipped The repo ships these bundled plugins under plugins/`. All are opt-in — enable them via` hermes plugins enable `. | Plugin | Kind | Purpose | |---|---|---| |` disk-cleanup`| hooks + slash command | Auto-track ephemeral files and clean them on session end | |`security-guidance`| hooks | Pattern-match dangerous code on`write_file`/`patch`and append a security warning (or block) — 25 rules (Apache-2.0 fork of Anthropic's`claude-plugins-official`patterns) | |`observability/langfuse`| hooks | Trace turns / LLM calls / tools to [Langfuse](https://langfuse.com) | |`observability/nemo_relay`| hooks | Relay observability events (turns / LLM calls / tools) to an NVIDIA NeMo endpoint | |`teams_pipeline`| standalone | Microsoft Teams meeting pipeline — Graph-backed, transcript-first meeting summaries | |`spotify`| backend (7 tools) | Native Spotify playback, queue, search, playlists, albums, library | |`google_meet`| standalone | Join Meet calls, live-caption transcription, optional realtime duplex audio | |`image_gen/openai`| image backend | OpenAI`gpt-image-2`image generation backend (alternative to FAL) | |`image_gen/openai-codex`| image backend | OpenAI image generation via Codex OAuth | |`image_gen/xai`| image backend | xAI`grok-2-image`backend | |`hermes-achievements`| dashboard tab | Steam-style collectible badges generated from your real Hermes session history | |`kanban/dashboard `| dashboard tab | Kanban board UI for the multi-agent dispatcher — tasks, comments, fan-out, board switching. See [Kanban Multi-Agent](./kanban.md). | Memory providers (`plugins/memory/`) and context engines (`plugins/context_engine/`) are listed separately on [Memory Providers](./memory-providers.md) — they're managed through` hermes memory`and`hermes plugins`respectively. The full per-plugin detail for the two long-running hooks-based plugins follows. ### disk-cleanup Auto-tracks and removes ephemeral files created during sessions — test scripts, temp outputs, cron logs, stale chrome profiles — without requiring the agent to remember to call a tool. How it works: | Hook | Behaviour | |---|---| |`post_tool_call`| When`write_file`/`terminal`/`patch`creates a file matching`test_`,` tmp_`, or` .test.`inside`HERMES_HOME`or`/tmp/hermes-`, track it silently as` test`/`temp`/`cron-output`. | |` on_session_end`| If any test files were auto-tracked during the turn, run the safe`quick`cleanup and log a one-line summary. Stays silent otherwise. | Deletion rules: | Category | Threshold | Confirmation | |---|---|---| |`test`| every session end | Never | |`temp`| >7 days since tracked | Never | |`cron-output`| >14 days since tracked | Never | | empty dirs under HERMES_HOME | always | Never | |`research`| >30 days, beyond 10 newest | Always (deep only) | |`chrome-profile`| >14 days since tracked | Always (deep only) | | files >500 MB | never auto | Always (deep only) | Slash command —`/disk-cleanupavailable in both CLI and gateway sessions: ``` /disk-cleanup status # breakdown + top-10 largest /disk-cleanup dry-run # preview without deleting /disk-cleanup quick # run safe cleanup now /disk-cleanup deep # quick + list items needing confirmation /disk-cleanup track <path> <category> # manual tracking /disk-cleanup forget <path> # stop tracking (does not delete) ``` State — everything lives at $HERMES_HOME/disk-cleanup/`: | File | Contents | |---|---| | `tracked.json` | Tracked paths with category, size, and timestamp | | `tracked.json.bak` | Atomic-write backup of the above | | `cleanup.log` | Append-only audit trail of every track / skip / reject / delete | Safety — cleanup only ever touches paths under `HERMES_HOME` or `/tmp/hermes-`. Windows mounts (`/mnt/c/...`) are rejected. Well-known top-level state dirs (`logs/`, `memories/`, `sessions/`, `cron/`, `cache/`, `skills/`, `plugins/`, `disk-cleanup/` itself) are never removed even when empty — a fresh install does not get gutted on first session end. Enabling: `hermes plugins enable disk-cleanup` (or check the box in `hermes plugins`). Disabling again: `hermes plugins disable disk-cleanup`. ### security-guidance Fast pattern-matched security warnings on file writes. When the agent's `write_file` / `patch` / `skill_manage` calls carry content matching a known-dangerous code pattern — `pickle.load`, `yaml.load` without `SafeLoader`, `eval(`, `os.system`, `subprocess(..., shell=True)`, JS `child_process.exec`, React `dangerouslySetInnerHTML`, raw `.innerHTML =` / `.outerHTML =` / `document.write`, Node `crypto.createCipher`, AES ECB mode, TLS verification disabled, XXE-prone `xml.etree` / `minidom` parsers, `<script src="//..." >` without SRI, `torch.load` without `weights_only=True`, GitHub Actions `$ {{ github.event. }}`injection — the plugin appends a`⚠️ Security guidanceblock to the tool's result. The file is still written. The model reads the warning in the next turn's tool message and can either fix the code or document why the construct is safe in this context. Pattern matching has a non-trivial false-positive rate, which is why warn (not block) is the default. Coverage: 25 rules total, covering unsafe deserialization, command injection, XSS sinks, crypto footguns, XXE, supply-chain (SRI), and CI/CD workflow injection. The pattern data is a verbatim Apache-2.0 fork of [Anthropic'sclaude-plugins-official`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/security-guidance/hooks) — see the plugin's` LICENSE`and`NOTICE`files for attribution. Modes: | Env var | Effect | |---|---| | (unset) | warn mode (default) — file is written, warning appended to result | |`SECURITY_GUIDANCE_BLOCK=1`| block mode — write refused, warning returned as the block reason | |`SECURITY_GUIDANCE_DISABLE=1`| kill switch — plugin loads but does nothing | Enabling:`hermes plugins enable security-guidance`(or check the box in`hermes plugins`). Disabling again:` hermes plugins disable security-guidance`. What it does not do (yet): the upstream Anthropic plugin has two more layers — an LLM diff review on each agent turn that touched files, and an agentic commit-time review that traces data flow across files. Neither is ported. The agent can already run those reviews on demand via` delegate_task`. ### observability/langfuse Traces Hermes turns, LLM calls, and tool invocations to [Langfuse](https://langfuse.com) — an open-source LLM observability platform. One span per turn, one generation per API call, one tool observation per tool call. Usage totals, per-type token counts, and cost estimates come out of Hermes' canonical` agent.usage_pricing`numbers, so the Langfuse dashboard sees the same breakdown (input / output /`cache_read_input_tokens`/`cache_creation_input_tokens`/`reasoning_tokens`) that appears in` hermes logs. The plugin is fail-open: no SDK installed, no credentials, or a transient Langfuse error — all turn into a silent no-op in the hook. The agent loop is never impacted. Setup (interactive — recommended): ```bash hermes tools # → Langfuse Observability → Cloud or Self-Hosted ``` The wizard collects your keys, pip install`s the` langfuse`SDK, and adds`observability/langfuse`to`plugins.enabledfor you. Restart Hermes and the next turn ships a trace. Setup (manual): ```bash pip install langfuse hermes plugins enable observability/langfuse ``` Then put the credentials in/.hermes/.env: ```bash HERMES_LANGFUSE_PUBLIC_KEY=pk-lf-... HERMES_LANGFUSE_SECRET_KEY=sk-lf-... HERMES_LANGFUSE_BASE_URL=https://cloud.langfuse.com # or your self-hosted URL ``` How it works: | Hook | Behaviour | |---|---| | pre_api_request`/`pre_llm_call`| Open (or reuse) a per-turn root span "Hermes turn". Start a`generation`child observation for this API call with serialized recent messages as input. | |`post_api_request`/`post_llm_call`| Close the generation, attach`usage_details`,` cost_details`,` finish_reason`, assistant output + tool calls. If no tool calls and non-empty content, close the turn. | |` pre_tool_call`| Start a`tool`child observation with sanitized`args`. | |` post_tool_call`| Close the tool observation with sanitized`result`.` read_file`payloads get summarized (head + tail + omitted-line count) so a huge file read stays under`HERMES_LANGFUSE_MAX_CHARS`. | Session grouping keys off the Hermes session ID (or task ID for sub-agents) via` langfuse.propagate_attributes`, so everything in a single` hermes chatsession lives under one Langfuse session. Verify: ```bash hermes plugins list # observability/langfuse should show "enabled" hermes chat -q "hello" # check the Langfuse UI for a "Hermes turn" trace ``` Optional tuning (in.env`): | Variable | Default | Purpose | |---|---|---| |` HERMES_LANGFUSE_ENV `| — | Environment tag on traces (`production`,` staging`, …) | |` HERMES_LANGFUSE_RELEASE`| — | Release/version tag | |`HERMES_LANGFUSE_SAMPLE_RATE`|`1.0`| Sampling rate passed to the SDK (0.0–1.0) | |`HERMES_LANGFUSE_MAX_CHARS`|`12000`| Per-field truncation for message content / tool args / tool results | |`HERMES_LANGFUSE_DEBUG`|`false`| Verbose plugin logging to`agent.log `| Hermes-prefixed and standard SDK env vars (`LANGFUSE_PUBLIC_KEY`,` LANGFUSE_SECRET_KEY`,` LANGFUSE_BASE_URL`) are both accepted — Hermes-prefixed wins when both are set. Performance: the Langfuse client is cached after the first hook call. If credentials or SDK are missing, that decision is also cached — subsequent hooks fast-return without re-checking env vars or reloading config. Disabling:` hermes plugins disable observability/langfuse. The plugin module is still discovered, but no module code runs until you re-enable. ### google_meet Lets the agent join, transcribe, and participate in Google Meet calls — take notes on a meeting, summarize the back-and-forth after, follow up on specific points, and (optionally) speak replies back into the call via TTS. What it adds: - A headless virtual participant that joins a Meet URL using browser automation - Live transcription of the meeting audio via the configured STT provider - A meet_summarize`/`meet_speak`/`meet_followup`toolset the agent invokes to act on what it heard - Post-meeting artifacts (transcript, speaker-attributed notes, action items) saved under`/.hermes/cache/google_meet/<meeting_id>/Setup: ```bash hermes plugins enable google_meet # Prompts you to sign in via the plugin's OAuth flow on first use — # needs a Google account with Meet access. Host approval may be required # if the meeting enforces "only invited participants can join". ``` Usage from chat: > "Join meet.google.com/abc-defg-hij and take notes. After the call, send me a summary with action items." The agent kicks off the meeting join, streams the transcription back into its context as the call proceeds, and produces a structured summary when the meeting ends (or when you tell it to stop). When to use it: recurring standups where you want a bot to transcribe + summarize for async attendees; deposition-style interviews where you want structured notes; any case where you'd otherwise need Fireflies / Otter / Grain. When you'd rather not have an AI listening in — don't enable it. Disabling:hermes plugins disable google_meet`. Any cached transcripts and recordings stay in` /.hermes/cache/google_meet/until you remove them. ### hermes-achievements Adds a Steam-style achievements tab to the dashboard — 60+ collectible, tiered badges generated from your real Hermes session history. Tool-chain feats, debugging patterns, vibe-coding streaks, skill/memory usage, model/provider variety, lifestyle quirks (weekend and night sessions). Originally authored by [@PCinkusz](https://github.com/PCinkusz) as an external plugin; brought in-tree so it stays in lockstep with Hermes feature changes. How it works: - Scans your entire/.hermes/state.db`session history on the dashboard backend - Per-session stats are cached by`(started_at, last_active)`fingerprint, so only new or changed sessions re-analyze on subsequent scans - First-ever scan runs in a background thread — the dashboard never blocks waiting for it, even on databases with thousands of sessions - Unlock state is persisted to` $HERMES_HOME/plugins/hermes-achievements/state.json` Tier progression: Copper → Silver → Gold → Diamond → Olympian. Each card exposes a "What counts" section listing the exact metric being tracked. Achievement states: | State | Meaning | |---|---| | Unlocked | At least one tier achieved | | Discovered | Known achievement, progress visible, not yet earned | | Secret | Hidden until Hermes detects the first related signal in your history | API — routes mount under `/api/plugins/hermes-achievements/`: | Endpoint | Purpose | |---|---| | `GET /achievements` | Full catalog with per-badge unlock state (returns a pending placeholder while the first cold scan is running) | | `GET /scan-status` | State of the background scanner: `idle` / `running` / `failed`, last duration, run count | | `GET /recent-unlocks` | Twenty most recently unlocked badges, newest first | | `GET /sessions/{id}/badges` | Badges earned primarily in one specific session | | `POST /rescan` | Manual synchronous rescan (blocks; use when the user clicks the rescan button) | | `POST /reset-state` | Clear unlock history and cached snapshot | State files — live under `$ HERMES_HOME/plugins/hermes-achievements/`: | File | Contents | |---|---| |` state.json`| Unlock history: which badges you've earned and when. Stable across Hermes updates. | |`scan_snapshot.json`| Last completed scan payload (served immediately on dashboard load) | |`scan_checkpoint.json`| Per-session stats cache keyed by fingerprint (makes warm rescans fast) | Performance notes: - Cold scan on ~8,000 sessions takes a few minutes. It runs in a background thread on first dashboard request; the UI sees a pending placeholder and polls`/scan-status`. - Incremental results during a cold scan — the scanner publishes a partial snapshot every ~250 sessions so each dashboard refresh shows more badges unlocked as the scan progresses. No minute-long stare at zeros. - Warm rescan reuses per-session stats for every session whose` started_at`+`last_active`fingerprint matches the checkpoint — completes in seconds even on large histories. - The in-memory snapshot TTL is 120s; stale requests serve the old snapshot immediately and kick a background refresh. You never wait on a spinner just because TTL expired. Enabling: Nothing to enable —`hermes-achievements`is a dashboard-only plugin (no lifecycle hooks, no model-visible tools). It auto-registers as a tab in`hermes dashboard`on first launch. The`plugins.enabled`config only gates lifecycle/tool plugins; dashboard plugins are discovered purely via their`dashboard/manifest.json`. Opting out: Delete or rename` plugins/hermes-achievements/dashboard/manifest.json`, or override it with a user plugin of the same name in` /.hermes/plugins/hermes-achievements/`that ships no dashboard. The plugin's state files under`$HERMES_HOME/plugins/hermes-achievements/`survive — reinstalling preserves your unlock history. ## Adding a bundled plugin Bundled plugins are written exactly like any other Hermes plugin — see [Build a Hermes Plugin](/guides/build-a-hermes-plugin). The only differences are: - Directory lives at`/plugins//`instead of`/.hermes/plugins//`- Manifest source is reported as`bundled`in`hermes plugins list`- User plugins with the same name override the bundled version A plugin is a good candidate for bundling when: - It has no optional dependencies (or they're already`pip install .[all]deps) - The behaviour benefits most users and is opt-out rather than opt-in - The logic ties into lifecycle hooks that the agent would otherwise have to remember to invoke - It complements a core capability without expanding the model-visible tool surface Counter-examples — things that should stay as user-installable plugins, not bundled: third-party integrations with API keys, niche workflows, large dependency trees, anything that would meaningfully change agent behaviour by default. ---  # Scheduled Tasks (Cron) # Scheduled Tasks (Cron) Schedule tasks to run automatically with natural language or cron expressions. Hermes exposes cron management through a singlecronjobtool with action-style operations instead of separate schedule/list/remove tools. ## What cron can do now Cron jobs can: - schedule one-shot or recurring tasks - pause, resume, edit, trigger, and remove jobs - attach zero, one, or multiple skills to a job - deliver results back to the origin chat, local files, or configured platform targets - run in fresh agent sessions with the normal static tool list - run in no-agent mode — a script on a schedule, its stdout delivered verbatim, zero LLM involvement (see the [no-agent mode](#no-agent-mode-script-only-jobs) section below) All of this is available to Hermes itself through thecronjob`tool, so you can create, pause, edit, and remove jobs by asking in plain language — no CLI required. :::tip Cron jobs use whatever provider`hermes model`selected.`hermes setup –portal`is the lowest-friction option for unattended runs since OAuth refresh is automatic. See [Nous Portal](/integrations/nous-portal). ::: :::warning Cron-run sessions cannot recursively create more cron jobs. Hermes disables cron management tools inside cron executions to prevent runaway scheduling loops. ::: ## Creating scheduled tasks ### In chat with`/cron```bash /cron add 30m "Remind me to check the build" /cron add "every 2h" "Check server status" /cron add "every 1h" "Summarize new feed items" --skill blogwatcher /cron add "every 1h" "Use both skills and combine the result" --skill blogwatcher --skill maps ``` ### From the standalone CLI ```bash hermes cron create "every 2h" "Check server status" hermes cron create "every 1h" "Summarize new feed items" --skill blogwatcher hermes cron create "every 1h" "Use both skills and combine the result" \ --skill blogwatcher \ --skill maps \ --name "Skill combo" ``` ### Through natural conversation Ask Hermes normally: ```text Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram. ``` Hermes will use the unifiedcronjobtool internally. ## Skill-backed cron jobs A cron job can load one or more skills before it runs the prompt. ### Single skill ```python cronjob( action="create", skill="blogwatcher", prompt="Check the configured feeds and summarize anything new.", schedule="0 9 * ", name="Morning feeds", ) ``` ### Multiple skills Skills are loaded in order. The prompt becomes the task instruction layered on top of those skills. ```python cronjob( action="create", skills=["blogwatcher", "maps"], prompt="Look for new local events and interesting nearby places, then combine them into one short brief.", schedule="every 6h", name="Local brief", ) ``` This is useful when you want a scheduled agent to inherit reusable workflows without stuffing the full skill text into the cron prompt itself. ## Running a job inside a project directory Cron jobs default to running detached from any repo — noAGENTS.md`,` CLAUDE.md`, or` .cursorrules`is loaded, and the terminal / file / code-exec tools run from whatever working directory the gateway started in. Pass`–workdir`(CLI) or`workdir=(tool call) to change that: ```bash # Standalone CLI (schedule and prompt are positional) hermes cron create "every 1d at 09:00" \ "Audit open PRs, summarize CI health, and post to #eng" \ --workdir /home/me/projects/acme ``` ```python # From a chat, via the cronjob tool cronjob( action="create", schedule="every 1d at 09:00", workdir="/home/me/projects/acme", prompt="Audit open PRs, summarize CI health, and post to #eng", ) ``` Whenworkdir`is set: -`AGENTS.md`,` CLAUDE.md`, and` .cursorrules`from that directory are injected into the system prompt (same discovery order as the interactive CLI) -`terminal`,` read_file`,` write_file`,` patch`,` search_files`, and` execute_code`all use that directory as their working directory - The path must be an absolute directory that exists — relative paths and missing directories are rejected at create / update time - Pass`–workdir “”`(or`workdir=“”`via the tool) on edit to clear it and restore the old behaviour :::note Serialization Jobs with a`workdir`run sequentially on the scheduler tick, not in the parallel pool. This is deliberate: the cron worker applies the job workdir through process-global terminal state, so two workdir jobs running at the same time would corrupt each other's cwd. Workdir-less jobs still run in parallel as before. ::: ## Running cron jobs in a specific profile By default a cron job inherits whichever Hermes profile owned the gateway / CLI that created it. Pass`–profile `(CLI) or`profile=`(cronjob tool) to re-target the job at a different profile — the scheduler resolves that profile's`HERMES_HOME`, temporarily switches into it for the duration of the run, loads its` .env`+`config.yaml, and executes the job there: ```bash # Pin a job to the night-opsprofile regardless of where it was scheduled hermes cron create "every 1d at 03:00" \ "Tail the security log and flag anomalies" \ --profile night-ops ``` ```python # From a chat, via the cronjob tool cronjob( action="create", schedule="every 1d at 03:00", prompt="Tail the security log and flag anomalies", profile="night-ops", ) ``` Use–profile default`to explicitly pin to the root Hermes profile. The named profile must already exist; the scheduler refuses to create profiles on the fly. To clear a profile pin during`cron edit`, pass an empty string (`–profile “”`or`profile=“”`) — the job reverts to running in whatever profile the scheduler itself is in. If the pinned profile is later deleted, the scheduler logs a warning and falls back to running the job in its current profile rather than crashing — so a stale` profile`reference never wedges a job. :::note Serialization Jobs with a`profile`set also run sequentially, for the same reason as`workdir`-pinned jobs: switching` HERMES_HOME`is a process-global mutation, so two profile-pinned jobs running in parallel would race each other. Unpinned jobs still run in the normal parallel pool. ::: ## Editing jobs You do not need to delete and recreate jobs just to change them. :::tip Job reference The`<job_id>`placeholder below (and in [Lifecycle actions](#lifecycle-actions)) also accepts the job's name (case-insensitive) — handy when you remember`morning-digestbut not the hex ID. An exact job ID takes precedence over name matches; if the reference is not an ID and a name matches more than one job, the command refuses and prints the candidate IDs so you can disambiguate. ::: ### Chat ```bash /cron edit <job_id> --schedule "every 4h" /cron edit <job_id> --prompt "Use the revised task" /cron edit <job_id> --skill blogwatcher --skill maps /cron edit <job_id> --remove-skill blogwatcher /cron edit <job_id> --clear-skills ``` ### Standalone CLI ```bash hermes cron edit <job_id> --schedule "every 4h" hermes cron edit <job_id> --prompt "Use the revised task" hermes cron edit <job_id> --skill blogwatcher --skill maps hermes cron edit <job_id> --add-skill maps hermes cron edit <job_id> --remove-skill blogwatcher hermes cron edit <job_id> --clear-skills ``` Notes: - repeated–skill`replaces the job's attached skill list -`–add-skill`appends to the existing list without replacing it -`–remove-skill`removes specific attached skills -`–clear-skillsremoves all attached skills ## Lifecycle actions Cron jobs now have a fuller lifecycle than just create/remove. ### Chat ```bash /cron list /cron pause <job_id> /cron resume <job_id> /cron run <job_id> /cron remove <job_id> ``` ### Standalone CLI ```bash hermes cron list hermes cron pause <job_id_or_name> hermes cron resume <job_id_or_name> hermes cron run <job_id_or_name> hermes cron remove <job_id_or_name> hermes cron edit <job_id_or_name> [...flags] hermes cron status hermes cron tick ``` What they do: -pause`— keep the job but stop scheduling it -`resume`— re-enable the job and compute the next future run -`run`— trigger the job on the next scheduler tick -`remove`— delete it entirely -`edit `— modify schedule, prompt, profile, delivery, etc. Name-based lookup. All four mutating verbs (`pause`,` resume`,` run`,` remove`,` edit`) plus the agent's` cronjobtool now accept a job name (case-insensitive) in place of the hex ID. The agent and CLI both prefer an exact ID match if one exists; ambiguous name matches (multiple jobs sharing the same name) are refused with the full list of candidate IDs so you can pick one explicitly. Names are not unique, so this guard is load-bearing — it prevents silently mutating the wrong job when two share a name. ## How it works Cron execution is handled by the gateway daemon. The gateway ticks the scheduler every 60 seconds, running any due jobs in isolated agent sessions. ```bash hermes gateway install # Install as a user service sudo hermes gateway install --system # Linux: boot-time system service for servers hermes gateway # Or run in foreground hermes cron list hermes cron status ``` ### Gateway scheduler behavior On each tick Hermes: 1. loads jobs from/.hermes/cron/jobs.json`2. checks`next_run_at`against the current time 3. starts a fresh`AIAgent`session for each due job 4. optionally injects one or more attached skills into that fresh session 5. runs the prompt to completion 6. delivers the final response 7. updates run metadata and the next scheduled time A file lock at`/.hermes/cron/.tick.lock`prevents overlapping scheduler ticks from double-running the same job batch. ## Delivery options When scheduling jobs, you specify where the output goes: | Option | Description | Example | |--------|-------------|---------| |`“origin”`| Back to where the job was created | Default on messaging platforms | |`“local” `| Save to local files only (`/.hermes/cron/output/`) | Default on CLI | |` “telegram”`| Telegram home channel | Uses`TELEGRAM_HOME_CHANNEL`| |`“telegram:123456”`| Specific Telegram chat by ID | Direct delivery | |`“telegram:-100123:17585”`| Specific Telegram topic |`chat_id:thread_id`format | |`“discord”`| Discord home channel | Uses`DISCORD_HOME_CHANNEL`| |`“discord:#engineering”`| Specific Discord channel | By channel name | |`“slack”`| Slack home channel | | |`“whatsapp”`| WhatsApp home | | |`“signal”`| Signal | | |`“matrix”`| Matrix home room | | |`“mattermost”`| Mattermost home channel | | |`“email”`| Email | | |`“sms”`| SMS via Twilio | | |`“homeassistant”`| Home Assistant | | |`“dingtalk”`| DingTalk | | |`“feishu”`| Feishu/Lark | | |`“wecom”`| WeCom | | |`“weixin”`| Weixin (WeChat) | | |`“bluebubbles”`| BlueBubbles (iMessage) | | |`“qqbot”`| QQ Bot (Tencent QQ) | | |`“all”`| Fan out to every connected home channel | Resolved at fire time | |`“telegram,discord”`| Fan out to a specific set of channels | Comma-separated list | |`“origin,all”`| Deliver to the origin plus every other connected channel | Combine any tokens | The agent's final response is automatically delivered. You do not need to call`send_message `in the cron prompt. ### Routing intent (`all`)` all`lets you ship one cron job to every messaging channel you have configured, without having to enumerate them by name. It is resolved at fire time, so a job created before you wired up Telegram will pick up Telegram on the next tick after you set`TELEGRAM_HOME_CHANNEL`. Semantics:` all`expands to every platform with a configured home channel. Zero is fine; the job simply produces no delivery targets and is recorded as a delivery failure upstream.`all`composes with explicit targets.`origin,all`delivers to the origin chat plus* every other connected home channel, de-duplicating by`(platform, chat_id, thread_id)`. ### Telegram cron topic (`TELEGRAM_CRON_THREAD_ID`) When Telegram topic mode is enabled, the root DM is reserved as a system lobby — replies sent there are rebuffed with a lobby reminder and` reply_to_message_id`is dropped, so you cannot reply to a cron message that landed in the main chat. Point cron at a dedicated forum topic instead: 1. In Telegram, open the bot DM and create a topic named e.g.`Cron`. Long-press the topic header → Copy link; the trailing integer is the topic's` message_thread_id`. 2. Set` TELEGRAM_CRON_THREAD_ID=`in your`.env`. This applies only to cron deliveries.` TELEGRAM_HOME_CHANNEL_THREAD_ID`(used elsewhere, e.g. restart notifications) is unchanged. Explicit`deliver=“telegram:chat_id:thread_id”targets continue to win over the env var. Replies to cron messages now arrive in the existing topic session, so you can act on them directly. ### Response wrapping By default, delivered cron output is wrapped with a header and footer so the recipient knows it came from a scheduled task: ``` Cronjob Response: Morning feeds ------------- <agent output here> Note: The agent cannot see this message, and therefore cannot respond to it. ``` To deliver the raw agent output without the wrapper, setcron.wrap_response`to`false: ```yaml # ~/.hermes/config.yaml cron: wrap_response: false ``` ### Silent suppression If the agent's final response starts with [SILENT]`, delivery is suppressed entirely. The output is still saved locally for audit (in` /.hermes/cron/output/), but no message is sent to the delivery target. This is useful for monitoring jobs that should only report when something is wrong: ```text Check if nginx is running. If everything is healthy, respond with only [SILENT]. Otherwise, report the issue. ``` Failed jobs always deliver regardless of the [SILENT]`marker — only successful runs can be silenced. ## Script timeout Pre-run scripts (attached via the`scriptparameter) have a default timeout of 120 seconds. If your scripts need longer — for example, to include randomized delays that avoid bot-like timing patterns — you can increase this: ```yaml # ~/.hermes/config.yaml cron: script_timeout_seconds: 300 # 5 minutes ``` Or set theHERMES_CRON_SCRIPT_TIMEOUT`environment variable. The resolution order is: env var → config.yaml → 120s default. ## No-agent mode (script-only jobs) For recurring jobs that don't need LLM reasoning — classic watchdogs, disk/memory alerts, heartbeats, CI pings — pass`no_agent=Trueat creation time. The scheduler runs your script on schedule and delivers its stdout directly, skipping the agent entirely: ```bash hermes cron create "every 5m" \ --no-agent \ --script memory-watchdog.sh \ --deliver telegram \ --name "memory-watchdog" ``` Semantics: - Script stdout (trimmed) → delivered verbatim as the message. - Empty stdout → silent tick, no delivery. This is the watchdog pattern: "only say something when something is wrong". - Non-zero exit or timeout → an error alert is delivered, so a broken watchdog can't fail silently. -{“wakeAgent”: false}`on the last line → silent tick (same gate LLM jobs use). - No tokens, no model, no provider fallback — the job never touches the inference layer.`.sh`/`.bash`files run under`/bin/bash`; anything else under the current Python interpreter (`sys.executable`). Scripts must live in` /.hermes/scripts/`(same sandboxing rule as the pre-run script gate). ### The agent sets these up for you The`cronjob`tool's schema exposes`no_agentto Hermes directly, so you can describe a watchdog in chat and let the agent wire it up: ```text Ping me on Telegram if RAM is over 85%, every 5 minutes. ``` Hermes will write the check script to/.hermes/scripts/`via`write_file, then call: ```python cronjob(action="create", schedule="every 5m", script="memory-watchdog.sh", no_agent=True, deliver="telegram", name="memory-watchdog") ``` It picks no_agent=True`automatically when the message content is fully determined by the script (watchdogs, threshold alerts, heartbeats). The same tool also lets the agent pause, resume, edit, and remove jobs — so the whole lifecycle is chat-driven without anyone touching the CLI. See the [Script-Only Cron Jobs guide](/guides/cron-script-only) for worked examples. ## Chaining jobs with`context_from`Cron jobs run in isolated sessions with no memory of previous runs. But sometimes one job's output is exactly what the next job needs. The`context_fromparameter wires that connection automatically — Job B's prompt gets Job A's most recent output prepended as context at runtime. ```python # Job 1: Collect raw data cronjob( action="create", prompt="Fetch the top 10 AI/ML stories from Hacker News. Save them to ~/.hermes/data/briefs/raw.md in markdown format with title, URL, and score.", schedule="0 7 * * ", name="AI News Collector", ) # Job 2: Triage — receives Job 1's output as context # Get Job 1's ID from: cronjob(action="list") cronjob( action="create", prompt="Read ~/.hermes/data/briefs/raw.md. Score each story 1–10 for engagement potential and novelty. Output the top 5 to ~/.hermes/data/briefs/ranked.md.", schedule="30 7 * ", context_from="<job1_id>", name="AI News Triage", ) # Job 3: Ship — receives Job 2's output as context cronjob( action="create", prompt="Read ~/.hermes/data/briefs/ranked.md. Write 3 tweet drafts (hook + body + hashtags). Deliver to telegram:7976161601.", schedule="0 8 * ", context_from="<job2_id>", name="AI News Brief", ) ``` How it works: - When Job 2 fires, Hermes reads Job 1's most recent output from/.hermes/cron/output/{job1_id}/.md`- That output is prepended to Job 2's prompt automatically - Job 2 doesn't need to hardcode "read this file" — it receives the content as context - The chain can be any length: Job 1 → Job 2 → Job 3 → ... What`context_from`accepts: | Format | Example | |--------|---------| | Single job ID (string) |`context_from=“a1b2c3d4”`| | Multiple job IDs (list) |`context_from=[“job_a”, “job_b”]| Outputs are concatenated in the order listed. When to use it: - Multi-stage pipelines (collect → filter → format → deliver) - Dependent tasks where step N's work depends on step N−1's output - Fan-out/fan-in patterns where one job aggregates results from several others ## Provider recovery Cron jobs inherit your configured fallback providers and credential pool rotation. If the primary API key is rate-limited or the provider returns an error, the cron agent can: - Fall back to an alternate provider if you havefallback_providers`(or the legacy`fallback_model`) configured in` config.yaml`- Rotate to the next credential in your [credential pool](/user-guide/configuration#credential-pool-strategies) for the same provider This means cron jobs that run at high frequency or during peak hours are more resilient — a single rate-limited key won't fail the entire run. ## Schedule formats The agent's final response is automatically delivered — you do not need to include`send_message`in the cron prompt for that same destination. If a cron run calls`send_message`to the exact target the scheduler will already deliver to, Hermes skips that duplicate send and tells the model to put the user-facing content in the final response instead. Use`send_message only for additional or different targets. ### Relative delays (one-shot) ```text 30m → Run once in 30 minutes 2h → Run once in 2 hours 1d → Run once in 1 day ``` ### Intervals (recurring) ```text every 30m → Every 30 minutes every 2h → Every 2 hours every 1d → Every day ``` ### Cron expressions ```text 0 9 * * → Daily at 9:00 AM 0 9 * * 1-5 → Weekdays at 9:00 AM 0 /6 * * → Every 6 hours 30 8 1 * * → First of every month at 8:30 AM 0 0 * * 0 → Every Sunday at midnight ``` ### ISO timestamps ```text 2026-03-15T09:00:00 → One-time at March 15, 2026 9:00 AM ``` ## Repeat behavior | Schedule type | Default repeat | Behavior | |--------------|----------------|----------| | One-shot (30m`, timestamp) | 1 | Runs once | | Interval (`every 2h) | forever | Runs until removed | | Cron expression | forever | Runs until removed | You can override it: ```python cronjob( action="create", prompt="...", schedule="every 2h", repeat=5, ) ``` ## Managing jobs programmatically The agent-facing API is one tool: ```python cronjob(action="create", ...) cronjob(action="list") cronjob(action="update", job_id="...") cronjob(action="pause", job_id="...") cronjob(action="resume", job_id="...") cronjob(action="run", job_id="...") cronjob(action="remove", job_id="...") ``` For update`, pass` skills=[]`to remove all attached skills. ## Toolsets available to cron jobs Cron runs each job in a fresh agent session with no chat platform attached. By default the cron agent gets the toolset you configured for the`cron`platform in`hermes tools — not the CLI default, not everything under the sun. ```bash hermes tools # → pick the "cron" platform in the curses UI # → toggle toolsets on/off just like you would for Telegram/Discord/etc. ``` Tighter per-job control is available via the enabled_toolsets`field on`cronjob.create`(or on an existing job via`cronjob.update): ```text cronjob(action="create", name="weekly-news-summary", schedule="every sunday 9am", enabled_toolsets=["web", "file"], # just web + file, no terminal/browser/etc. prompt="Summarize this week's AI news: ...") ``` When enabled_toolsets`is set on a job it wins; otherwise the`hermes tools`cron-platform config wins; otherwise Hermes falls back to the built-in defaults. This matters for cost control: carrying`moa`,` browser`,` delegation`into every tiny "fetch news" job bloats the tool-schema prompt on every LLM call. ### Skipping the agent entirely:`wakeAgent`If your cron job attaches a pre-check script (via`script=), the script can decide at runtime whether Hermes should even invoke the agent. Emit a final stdout line of the form: ```text {"wakeAgent": false} ``` …and cron skips the agent run entirely for this tick. Useful for frequent polls (every 1–5 min) that only need to wake the LLM when state actually changed — otherwise you pay for zero-content agent turns over and over. ```python # pre-check script import json, sys latest = fetch_latest_issue_count() prev = read_state("issue_count") if latest == prev: print(json.dumps({"wakeAgent": False})) # skip this tick sys.exit(0) write_state("issue_count", latest) print(json.dumps({"wakeAgent": True, "context": {"new_issues": latest - prev}})) ``` When wakeAgent`is omitted, the default is`true`(wake the agent as usual). #### Recipes: cheap pre-run gates The`wakeAgent`gate gives you a $0 way to decide whether a scheduled job should spend any LLM tokens at all. Three patterns cover most use cases. File-change gate — only run when a watched file has new content since the last successful tick. The scheduler records each job's`last_run_at; compare it against the file's mtime. ```bash #!/bin/bash # ~/.hermes/scripts/feed-changed.sh FEED="$HOME/data/feed.json" STATE="$HOME/.hermes/scripts/.feed-changed.last" test -f "$FEED" || { echo '{"wakeAgent": false}'; exit 0; } mtime=$(stat -c %Y "$FEED") last=$(cat "$STATE" 2>/dev/null || echo 0) if [ "$mtime" -le "$last" ]; then echo '{"wakeAgent": false}' else echo "$mtime" > "$STATE" echo '{"wakeAgent": true}' fi ``` ```text cronjob(action="create", name="process-feed", schedule="every 30m", script="feed-changed.sh", prompt="A new ~/data/feed.json has landed. Summarize what changed.") ``` External-flag gate — only run when some other process has signalled readiness (e.g. a deploy hook drops a file, a CI job sets a value in your state store). ```bash #!/bin/bash # ~/.hermes/scripts/flag-ready.sh if test -f /tmp/new-data-ready; then rm -f /tmp/new-data-ready echo '{"wakeAgent": true}' else echo '{"wakeAgent": false}' fi ``` ```text cronjob(action="create", name="nightly-analysis", schedule="0 9 * * ", script="flag-ready.sh", prompt="Run the nightly analysis over today's batch.") ``` SQL-count gate — only run when there are new rows to process in your own database. The script can also pass the count through to the agent via context, so the agent knows how much it's looking at without re-querying. ```python #!/usr/bin/env python # ~/.hermes/scripts/new-rows.py import json, sqlite3 conn = sqlite3.connect("/home/me/data/app.db") n = conn.execute( "SELECT COUNT() FROM messages WHERE ts > strftime('%s','now','-2 hours')" ).fetchone()[0] if n < 1: print(json.dumps({"wakeAgent": False})) else: print(json.dumps({"wakeAgent": True, "context": {"new_rows": n}})) ``` ```text cronjob(action="create", name="summarize-new-msgs", schedule="every 2h", script="new-rows.py", prompt="Summarize the new messages from the last 2 hours.") ``` The same pattern works for any data source you can query from a script — Postgres, an HTTP API, your own state store — without baking a SQL evaluator into the cron subsystem. :::tip Hermes's own /.hermes/state.db`is an internal schema that changes between releases. Don't query it from a pre-run gate — point at your own database or feed instead. ::: Credit: this recipe set was prompted by @iankar8's exploration in [#2654](https://github.com/NousResearch/hermes-agent/pull/2654), which proposed adding sql/file/command triggers as a parallel mechanism. The`script`+`wakeAgent`gate already covers all three cases at $0, so the work landed as documentation instead. ### Chaining jobs:`context_from`A cron job can consume the most recent successful output of one or more other jobs by listing their names (or IDs) in`context_from: ```text cronjob(action="create", name="daily-digest", schedule="every day 7am", context_from=["ai-news-fetch", "github-prs-fetch"], prompt="Write the daily digest using the outputs above.") ``` The referenced jobs' most recent completed outputs are injected above the prompt as context for this run. Each upstream entry must be a valid job ID or name (see cronjob action=“list”`). Note: chaining reads the most recent completed output — it does not wait for upstream jobs that are running in the same tick. ## Job storage Jobs are stored in` /.hermes/cron/jobs.json`. Output from job runs is saved to` /.hermes/cron/output/{job_id}/{timestamp}.md`. Jobs may store` model`and`provider`as`null. When those fields are omitted, Hermes resolves them at execution time from the global configuration. They only appear in the job record when a per-job override is set. The storage uses atomic file writes so interrupted writes do not leave a partially written job file behind. ## Self-contained prompts still matter :::warning Important Cron jobs run in a completely fresh agent session. The prompt must contain everything the agent needs that is not already provided by attached skills. ::: BAD: “Check on that server issue”`GOOD:`“SSH into server 192.168.1.100 as user ‘deploy’, check if nginx is running with ‘systemctl status nginx’, and verify https://example.com returns HTTP 200.”`## Security Scheduled task prompts are scanned for prompt-injection and credential-exfiltration patterns at creation and update time. Prompts containing invisible Unicode tricks, SSH backdoor attempts, or obvious secret-exfiltration payloads are blocked. ---  # Subagent Delegation # Subagent Delegation The`delegate_tasktool spawns child AIAgent instances with isolated context, restricted toolsets, and their own terminal sessions. Each child gets a fresh conversation and works independently — only its final summary enters the parent's context. ## Single Task ```python delegate_task( goal="Debug why tests fail", context="Error: assertion in test_foo.py line 42", toolsets=["terminal", "file"] ) ``` ## Parallel Batch Up to 3 concurrent subagents by default (configurable, no hard ceiling): ```python delegate_task(tasks=[ {"goal": "Research topic A", "toolsets": ["web"]}, {"goal": "Research topic B", "toolsets": ["web"]}, {"goal": "Fix the build", "toolsets": ["terminal", "file"]} ]) ``` ## How Subagent Context Works :::warning Critical: Subagents Know Nothing Subagents start with a completely fresh conversation. They have zero knowledge of the parent's conversation history, prior tool calls, or anything discussed before delegation. The subagent's only context comes from thegoal`and`context`fields the parent agent populates when it calls`delegate_task. ::: This means the parent agent must pass everything the subagent needs in the call: ```python # BAD - subagent has no idea what "the error" is delegate_task(goal="Fix the error") # GOOD - subagent has all context it needs delegate_task( goal="Fix the TypeError in api/handlers.py", context="""The file api/handlers.py has a TypeError on line 47: 'NoneType' object has no attribute 'get'. The function process_request() receives a dict from parse_body(), but parse_body() returns None when Content-Type is missing. The project is at /home/user/myproject and uses Python 3.11.""" ) ``` The subagent receives a focused system prompt built from your goal and context, instructing it to complete the task and provide a structured summary of what it did, what it found, any files modified, and any issues encountered. ## Practical Examples ### Parallel Research Research multiple topics simultaneously and collect summaries: ```python delegate_task(tasks=[ { "goal": "Research the current state of WebAssembly in 2025", "context": "Focus on: browser support, non-browser runtimes, language support", "toolsets": ["web"] }, { "goal": "Research the current state of RISC-V adoption in 2025", "context": "Focus on: server chips, embedded systems, software ecosystem", "toolsets": ["web"] }, { "goal": "Research quantum computing progress in 2025", "context": "Focus on: error correction breakthroughs, practical applications, key players", "toolsets": ["web"] } ]) ``` ### Code Review + Fix Delegate a review-and-fix workflow to a fresh context: ```python delegate_task( goal="Review the authentication module for security issues and fix any found", context="""Project at /home/user/webapp. Auth module files: src/auth/login.py, src/auth/jwt.py, src/auth/middleware.py. The project uses Flask, PyJWT, and bcrypt. Focus on: SQL injection, JWT validation, password handling, session management. Fix any issues found and run the test suite (pytest tests/auth/).""", toolsets=["terminal", "file"] ) ``` ### Multi-File Refactoring Delegate a large refactoring task that would flood the parent's context: ```python delegate_task( goal="Refactor all Python files in src/ to replace print() with proper logging", context="""Project at /home/user/myproject. Use the 'logging' module with logger = logging.getLogger(name). Replace print() calls with appropriate log levels: - print(f"Error: ...") -> logger.error(...) - print(f"Warning: ...") -> logger.warning(...) - print(f"Debug: ...") -> logger.debug(...) - Other prints -> logger.info(...) Don't change print() in test files or CLI output. Run pytest after to verify nothing broke.""", toolsets=["terminal", "file"] ) ``` ## Batch Mode Details When you provide a tasks`array, subagents run in parallel using a thread pool: - Maximum concurrency: 3 tasks by default (configurable via`delegation.max_concurrent_children`or the`DELEGATION_MAX_CONCURRENT_CHILDREN`env var; floor of 1, no hard ceiling). Batches larger than the limit return a tool error rather than being silently truncated. - Thread pool: Uses`ThreadPoolExecutorwith the configured concurrency limit as max workers - Progress display: In CLI mode, a tree-view shows tool calls from each subagent in real-time with per-task completion lines. In gateway mode, progress is batched and relayed to the parent's progress callback - Result ordering: Results are sorted by task index to match input order regardless of completion order - Interrupt propagation: Interrupting the parent (e.g., sending a new message) interrupts all active children Single-task delegation runs directly without thread pool overhead. ## Model Override You can configure a different model for subagents viaconfig.yaml— useful for delegating simple tasks to cheaper/faster models: ```yaml # In ~/.hermes/config.yaml delegation: model: "google/gemini-flash-2.0" # Cheaper model for subagents provider: "openrouter" # Optional: route subagents to a different provider ``` If omitted, subagents use the same model as the parent. ## Toolset Selection Tips Thetoolsets`parameter controls what tools the subagent has access to. Choose based on the task: | Toolset Pattern | Use Case | |----------------|----------| |`[“terminal”, “file”]`| Code work, debugging, file editing, builds | |`[“web”]`| Research, fact-checking, documentation lookup | |`[“terminal”, “file”, “web”]`| Full-stack tasks (default) | |`[“file”]`| Read-only analysis, code review without execution | |`[“terminal”]`| System administration, process management | Certain toolsets are blocked for subagents regardless of what you specify: -`delegation`— blocked for leaf subagents (the default). Retained for`role=“orchestrator”`children, bounded by`max_spawn_depth`— see [Depth Limit and Nested Orchestration](#depth-limit-and-nested-orchestration) below. -`clarify`— subagents cannot interact with the user -`memory`— no writes to shared persistent memory -`code_execution`— children should reason step-by-step -`send_message— no cross-platform side effects (e.g., sending Telegram messages) ## Max Iterations Each subagent has an iteration limit (default: 50) that controls how many tool-calling turns it can take: ```python delegate_task( goal="Quick file check", context="Check if /etc/nginx/nginx.conf exists and print its first 10 lines", max_iterations=10 # Simple task, don't need many turns ) ``` ## Child Timeout Subagents are killed as stuck if they go quiet for more thandelegation.child_timeout_secondswall-clock seconds. The default is 600 (10 minutes) — bumped up from 300s in earlier releases because high-reasoning models on non-trivial research tasks were getting killed mid-think. Tune it per-install: ```yaml delegation: child_timeout_seconds: 600 # default ``` Lower it for fast local models; raise it for slow reasoning models on hard problems. The timer resets every time the child makes an API call or tool call — only genuinely idle workers trigger the kill. :::tip Diagnostic dump on zero-call timeout If a subagent times out having made zero API calls (usually: provider unreachable, auth failure, or tool-schema rejection),delegate_task`writes a structured diagnostic to`/.hermes/logs/subagent-timeout--.log `containing the subagent's config snapshot, credential-resolution trace, and any early error messages. Much easier to root-cause than the previous silent-timeout behavior. ::: ## Monitoring Running Subagents (`/agents`) The TUI ships a` /agents`overlay (alias`/tasks`) that turns recursive` delegate_task`fan-out into a first-class audit surface: - Live tree view of running and recently-finished subagents, grouped by parent - Per-branch cost, token, and file-touched rollups - Kill and pause controls — cancel a specific subagent mid-flight without interrupting its siblings - Post-hoc review: step through each subagent's turn-by-turn history even after they've returned to the parent The classic CLI just prints`/agentsas a text summary; the TUI is where the overlay shines. See [TUI — Slash commands](/user-guide/tui#slash-commands). ## Depth Limit and Nested Orchestration By default, delegation is flat: a parent (depth 0) spawns children (depth 1), and those children cannot delegate further. This prevents runaway recursive delegation. For multi-stage workflows (research → synthesis, or parallel orchestration over sub-problems), a parent can spawn orchestrator children that can delegate their own workers: ```python delegate_task( goal="Survey three code review approaches and recommend one", role="orchestrator", # Allows this child to spawn its own workers context="...", ) ``` -role=“leaf”`(default): child cannot delegate further — identical to the flat-delegation behavior. -`role=“orchestrator”`: child retains the` delegation`toolset. Gated by`delegation.max_spawn_depth`(default 1 = flat, so`role=“orchestrator”`is a no-op at defaults). Raise`max_spawn_depth`to 2 to allow orchestrator children to spawn leaf grandchildren; 3+ for deeper trees. There is no upper ceiling — cost is the practical limit. -`delegation.orchestrator_enabled: false`: global kill switch that forces every child to` leaf`regardless of the`role`parameter. Cost warning: With`max_spawn_depth: 3`and`max_concurrent_children: 3`, the tree can reach 3×3×3 = 27 concurrent leaf agents. Each extra level multiplies spend — raise` max_spawn_depth`intentionally. ## Lifetime and Durability :::warning delegate_task is synchronous — not durable`delegate_task`runs inside the parent's current turn. It blocks the parent until every child finishes (or is cancelled). It is not a background job queue: - If the parent is interrupted (user sends a new message,`/stop`,` /new`), all active children are cancelled and return` status=“interrupted”`. Their in-progress work is discarded. - Children do not continue running after the parent turn ends. - Cancelled children return a structured result (`status=“interrupted”`,` exit_reason=“interrupted”`), but because the parent was interrupted too, that result often never makes it into a user-visible reply. For durable long-running work that must survive interrupts or outlive the current turn, use: -` cronjob `(action=`create`) — schedules a separate agent run; immune to parent-turn interrupts. -` terminal(background=True, notify_on_complete=True)`— long-running shell commands that keep running while the agent does other things. ::: ## Key Properties - Each subagent gets its own terminal session (separate from the parent) - Nested delegation is opt-in — only`role=“orchestrator”`children can delegate further, and only when`max_spawn_depth`is raised from its default of 1 (flat). Disable globally with`orchestrator_enabled: false`. - Leaf subagents cannot call:` delegate_task`,` clarify`,` memory`,` send_message`,` execute_code`. Orchestrator subagents retain` delegate_taskbut still cannot use the other four. - Interrupt propagation — interrupting the parent interrupts all active children (including grandchildren under orchestrators) - Only the final summary enters the parent's context, keeping token usage efficient - Subagents inherit the parent's API key, provider configuration, and credential pool (enabling key rotation on rate limits) ## Delegation vs execute_code | Factor | delegate_task | execute_code | |--------|--------------|-------------| | Reasoning | Full LLM reasoning loop | Just Python code execution | | Context | Fresh isolated conversation | No conversation, just script | | Tool access | All non-blocked tools with reasoning | 7 tools via RPC, no reasoning | | Parallelism | 3 concurrent subagents by default (configurable) | Single script | | Best for | Complex tasks needing judgment | Mechanical multi-step pipelines | | Token cost | Higher (full LLM loop) | Lower (only stdout returned) | | User interaction | None (subagents can't clarify) | None | Rule of thumb: Usedelegate_task`when the subtask requires reasoning, judgment, or multi-step problem solving. Use`execute_codewhen you need mechanical data processing or scripted workflows. ## Configuration ```yaml # In ~/.hermes/config.yaml delegation: max_iterations: 50 # Max turns per child (default: 50) # max_concurrent_children: 3 # Parallel children per batch (default: 3) # max_spawn_depth: 1 # Tree depth (floor 1, no ceiling, default 1 = flat). Raise to 2 to allow orchestrator children to spawn leaves; 3+ for deeper trees. # orchestrator_enabled: true # Disable to force all children to leaf role. model: "google/gemini-3-flash-preview" # Optional provider/model override provider: "openrouter" # Optional built-in provider api_mode: anthropic_messages # optional; auto-detected from base_url for anthropic_messages endpoints # Or use a direct custom endpoint instead of provider: delegation: model: "qwen2.5-coder" base_url: "http://localhost:1234/v1" api_key: "local-key" # api_mode: "anthropic_messages" # Optional. Wire protocol override for base_url ("chat_completions", "codex_responses", or "anthropic_messages"). Empty = auto-detect from URL (e.g. /anthropic suffix). Set explicitly for endpoints the heuristic can't classify (Azure AI Foundry, MiniMax, Zhipu GLM, LiteLLM proxies, …). ``` Whenbase_url`points at an Anthropic-compatible endpoint — for example a path ending in`/anthropic`, an Azure Foundry Claude route, or a MiniMax` /anthropic`proxy —`api_mode`is auto-detected as`anthropic_messages`so the subagent uses the right wire format without you setting anything. Set`api_modeexplicitly when the auto-detection guess is wrong (rare). :::tip The agent handles delegation automatically based on the task complexity. You don't need to explicitly ask it to delegate — it will do so when it makes sense. ::: ---  # Kanban (Multi-Agent Board) # Kanban — Multi-Agent Profile Collaboration > Want a walkthrough? Read the [Kanban tutorial](./kanban-tutorial) — four user stories (solo dev, fleet farming, role pipeline with retry, circuit breaker) with dashboard screenshots of each. This page is the reference; the tutorial is the narrative. Hermes Kanban is a durable task board, shared across all your Hermes profiles, that lets multiple named agents collaborate on work without fragile in-process subagent swarms. Every task is a row in/.hermes/kanban.db`; every handoff is a row anyone can read and write; every worker is a full OS process with its own identity. ### Two surfaces: the model talks through tools, you talk through the CLI The board has two front doors, both backed by the same` /.hermes/kanban.db`: - Agents drive the board through a dedicated` kanban_`toolset —`kanban_show`,` kanban_list`,` kanban_complete`,` kanban_block`,` kanban_heartbeat`,` kanban_comment`,` kanban_create`,` kanban_link`,` kanban_unblock`. The dispatcher spawns each worker with these tools already in its schema; orchestrator profiles can also enable the` kanban`toolset explicitly. The model reads and routes tasks by calling tools directly, not by shelling out to`hermes kanban`. See [How workers interact with the board](#how-workers-interact-with-the-board) below. - You (and scripts, and cron) drive the board through` hermes kanban …` on the CLI,` /kanban …`as a slash command, or the dashboard. These are for humans and automation — the places without a tool-calling model behind them. Both surfaces route through the same`kanban_db`layer, so reads see a consistent view and writes can't drift. The rest of this page shows CLI examples because they're easy to copy-paste, but every CLI verb has a tool-call equivalent the model uses. This is the shape that covers the workloads`delegate_task `can't: - Research triage — parallel researchers + analyst + writer, human-in-the-loop. - Scheduled ops — recurring daily briefs that build a journal over weeks. - Digital twins — persistent named assistants (`inbox-triage`,` ops-review`) that accumulate memory over time. - Engineering pipelines — decompose → implement in parallel worktrees → review → iterate → PR. - Fleet work — one specialist managing N subjects (50 social accounts, 12 monitored services). For the full design rationale, comparative analysis against Cline Kanban / Paperclip / NanoClaw / Google Gemini Enterprise, and the eight canonical collaboration patterns, see` docs/hermes-kanban-v1-spec.pdf`in the repository. ## Kanban vs.`delegate_task`They look similar; they are not the same primitive. | |`delegate_task`| Kanban | |---|---|---| | Shape | RPC call (fork → join) | Durable message queue + state machine | | Parent | Blocks until child returns | Fire-and-forget after`create| | Child identity | Anonymous subagent | Named profile with persistent memory | | Resumability | None — failed = failed | Block → unblock → re-run; crash → reclaim | | Human in the loop | Not supported | Comment / unblock at any point | | Agents per task | One call = one subagent | N agents over task's life (retry, review, follow-up) | | Audit trail | Lost on context compression | Durable rows in SQLite forever | | Coordination | Hierarchical (caller → callee) | Peer — any profile reads/writes any task | One-sentence distinction:delegate_task`is a function call; Kanban is a work queue where every handoff is a row any profile (or human) can see and edit. Use`delegate_task`when the parent agent needs a short reasoning answer before continuing, no humans involved, result goes back into the parent's context. Use Kanban when work crosses agent boundaries, needs to survive restarts, might need human input, might be picked up by a different role, or needs to be discoverable after the fact. They coexist: a kanban worker may call`delegate_task`internally during its run. ## Core concepts - Board — a standalone queue of tasks with its own SQLite DB, workspaces directory, and dispatcher loop. A single install can have many boards (e.g. one per project, repo, or domain); see [Boards (multi-project)](#boards-multi-project) below. Single-project users stay on the`default `board and never see the word "board" outside this docs section. - Task — a row with title, optional body, one assignee (a profile name), status (`triage | todo | ready | running | blocked | done | archived`), optional tenant namespace, optional idempotency key (dedup for retried automation). - Link —` task_links`row recording a parent → child dependency. The dispatcher promotes`todo → ready`when all parents are`done`. - Comment — the inter-agent protocol. Agents and humans append comments; when a worker is (re-)spawned it reads the full comment thread as part of its context. - Workspace — the directory a worker operates in. Three kinds: -` scratch`(default) — fresh tmp dir under`/.hermes/kanban/workspaces//`(or`/.hermes/kanban/boards//workspaces//`on non-default boards). Deleted when the task completes — scratch is ephemeral by design, so the dir is wiped the moment the worker (or`hermes kanban complete `) marks the task done. If you want to keep the worker's output, use` worktree:`or`dir:`instead. The first time a scratch workspace is created on an install, the dispatcher logs a warning and emits a`tip_scratch_workspace`event on the task (visible via`hermes kanban show `). -` dir:`— an existing shared directory (Obsidian vault, mail ops dir, per-account folder). Must be an absolute path. Relative paths like`dir:../tenants/foo/`are rejected at dispatch because they'd resolve against whatever CWD the dispatcher happens to be in, which is ambiguous and a confused-deputy escape vector. The path is otherwise trusted — it's your box, your filesystem, the worker runs with your uid. This is the trusted-local-user threat model; kanban is single-host by design. Preserved on completion. -`worktree`— a git worktree under`.worktrees//`for coding tasks. Use`worktree:`to pin the exact target path. Worker-side`git worktree add`creates it, using`–branch `when provided. Preserved on completion. - Dispatcher — a long-lived loop that, every N seconds (default 60): reclaims stale claims, reclaims crashed workers (PID gone but TTL not yet expired), promotes ready tasks, atomically claims, spawns assigned profiles. Runs inside the gateway by default (`kanban.dispatch_in_gateway: true`). One dispatcher sweeps all boards per tick; workers are spawned with` HERMES_KANBAN_BOARD`pinned so they can't see other boards. After`kanban.failure_limit `consecutive spawn failures on the same task (default: 2) the dispatcher auto-blocks it with the last error as the reason — prevents thrashing on tasks whose profile doesn't exist, workspace can't mount, etc. - Tenant — optional string namespace within a board. One specialist fleet can serve multiple businesses (`–tenant business-a`) with data isolation by workspace path and memory key prefix. Tenants are a soft filter; boards are the hard isolation boundary. ## Boards (multi-project) Boards let you separate unrelated streams of work — one per project, repo, or domain — into isolated queues. A new install has exactly one board called` default`(DB at`/.hermes/kanban.db `for back-compat). Users who only want one stream of work never need to know about boards; the feature is opt-in. Per-board isolation is absolute: - Separate SQLite DB per board (`/.hermes/kanban/boards//kanban.db`). - Separate` workspaces/`and`logs/`directories. - Workers spawned for a task see only their board's tasks — the dispatcher sets`HERMES_KANBAN_BOARD`in the child env and every`kanban_tool the worker has access to reads it. - Linking tasks across boards is not allowed (keeps the schema simple; if you really need cross-project refs, use free-text mentions and look them up by id manually). ### Managing boards from the CLI ```bash # See what's on disk. Fresh installs show only "default". hermes kanban boards list # Create a new board. hermes kanban boards create atm10-server \ --name "ATM10 Server" \ --description "Minecraft modded server ops" \ --icon 🎮 \ --switch # optional: make it the active board # Operate on a specific board without switching. hermes kanban --board atm10-server list hermes kanban --board atm10-server create "Restart ATM server" --assignee ops # Change which board is "current" for subsequent calls. hermes kanban boards switch atm10-server hermes kanban boards show # who's active right now? # Rename the display name (the slug is immutable — it's the directory name). hermes kanban boards rename atm10-server "ATM10 (Prod)" # Archive (default) — moves the board's dir to boards/_archived/<slug>-<ts>/. # Recoverable by moving the dir back. hermes kanban boards rm atm10-server # Hard delete —rm -rfthe board dir. No recovery. hermes kanban boards rm atm10-server --delete ``` Board resolution order (highest precedence first): 1. Explicit–board `on the CLI call. 2.`HERMES_KANBAN_BOARD`env var (set by the dispatcher when spawning a worker, so workers can't see other boards). 3.`~/.hermes/kanban/current`— the slug persisted by`hermes kanban boards switch`. 4.` default`. Slugs are validated: lowercase alphanumerics + hyphens + underscores, 1-64 chars, must start with alphanumeric. Uppercase input is auto-downcased. Anything else (slashes, spaces, dots,` ..`) is rejected at the CLI layer so path-traversal tricks can't name a board. ### Managing boards from the dashboard` hermes dashboard`→ Kanban tab shows a board switcher at the top as soon as more than one board exists (or any board has tasks). Single-board users see only a small`+ New board`button; the switcher is hidden until it matters. - Board dropdown — pick the active board. Your selection is saved to the browser's`localStorage`so it persists across reloads without shifting the CLI's`current `pointer out from under a terminal you left open. - + New board — opens a modal asking for slug, display name, description, and icon. Option to auto-switch to the new board. - Archive — only shown on non-`default`boards. Confirms, then moves the board dir to`boards/archived/`. All dashboard API endpoints accept` ?board=for board scoping. The events WebSocket is pinned to a board at connection time; switching in the UI opens a fresh WS against the new board. ## File attachments Tasks can carry file attachments — PDFs, images, source documents — so a worker has the source material it needs without you pasting paths into the body and hoping it finds them. - Upload — open a task in the dashboard drawer and use the Attachments section's Upload file button (multiple files at once are fine). Each upload is capped at 25 MB. - Storage — files land under/kanban/attachments/<task_id>/`for the default board, or`/kanban/boards//attachments/<task_id>/`for a named board. Set`HERMES_KANBAN_ATTACHMENTS_ROOT `to pin a custom location. - What the worker sees — when the dispatcher hands a task to a worker, the worker's context includes an Attachments section listing each file's name and its absolute path. The worker has full file/terminal tool access, so it reads attachments directly (`read_file`, or shell tools like` pdftotext`). - Download / remove — the drawer lists each attachment with a download link and a remove (×) control. Removing an attachment deletes both the metadata row and the on-disk file. :::note Remote terminal backends Attachment paths resolve directly on the local terminal backend, which is the default for Kanban workers. If you run workers on a remote backend (Docker, Modal), mount the board's` attachments/`directory into the sandbox so the absolute paths in the worker context are reachable. ::: ## Quick start The commands below are you (the human) setting up the board and creating tasks. Once a task is assigned, the dispatcher spawns the assigned profile as a worker, and from there the model drives the task through`kanbantool calls, not CLI commands — see [How workers interact with the board](#how-workers-interact-with-the-board). ```bash # 1. Create the board (you) hermes kanban init # 2. Start the gateway (hosts the embedded dispatcher) hermes gateway start # 3. Create a task (you — or an orchestrator agent via kanban_create) hermes kanban create "research AI funding landscape" --assignee researcher # 4. Watch activity live (you) hermes kanban watch # 5. See the board (you) hermes kanban list hermes kanban stats ``` When the dispatcher picks upt_abcd`and spawns the`researcher`profile, the very first thing that worker's model does is call`kanban_show()`to read its task. It doesn't run`hermes kanban show t_abcd. ### Gateway-embedded dispatcher (default) The dispatcher runs inside the gateway process. Nothing to install, no separate service to manage — if the gateway is up, ready tasks get picked up on the next tick (60s by default). ```yaml # config.yaml kanban: dispatch_in_gateway: true # default dispatch_interval_seconds: 60 # default ``` Override the config flag at runtime via HERMES_KANBAN_DISPATCH_IN_GATEWAY=0`for debugging. Standard gateway supervision applies: run`hermes gateway start`directly, or wire the gateway up as a systemd user unit (see the gateway docs). Without a running gateway,`ready`tasks stay where they are until one comes up —`hermes kanban create`warns about this at creation time. Running`hermes kanban daemon`as a separate process is deprecated; use the gateway. If you truly cannot run the gateway (headless host policy forbids long-lived services, etc.) a`–force`escape hatch keeps the old standalone daemon alive for one release cycle, but running both a gateway-embedded dispatcher AND a standalone daemon against the same`kanban.dbcauses claim races and is not supported. ### Idempotent create (for automation / webhooks) ```bash # First call creates the task. Any subsequent call with the same key # returns the existing task id instead of duplicating. hermes kanban create "nightly ops review" \ --assignee ops \ --idempotency-key "nightly-ops-$(date -u +%Y-%m-%d)" \ --json ``` ### Bulk CLI verbs All the lifecycle verbs accept multiple ids so you can clean up a batch in one command: ```bash hermes kanban complete t_abc t_def t_hij --result "batch wrap" hermes kanban archive t_abc t_def t_hij hermes kanban unblock t_abc t_def hermes kanban block t_abc "need input" --ids t_def t_hij ``` ## How workers interact with the board Workers do not shell out tohermes kanban`. When the dispatcher spawns a worker it sets` HERMES_KANBAN_TASK=t_abcd`in the child's env, and that env var flips on a dedicated kanban toolset in the model's schema. The same toolset is also available to orchestrator profiles that enable`kanban`in their toolsets config. These tools read and mutate the board directly via the Python`kanban_db`layer, same as the CLI does. A running worker calls these like any other tool; it never sees or needs the`hermes kanban`CLI. | Tool | Purpose | Required params | |---|---|---| |`kanban_show`| Read the current task (title, body, prior attempts, parent handoffs, comments, full pre-formatted`worker_context`). Defaults to the env's task id. | — | |` kanban_list`| List task summaries with filters for`assignee`,` status`,` tenant`, archived visibility, and limit. Intended for orchestrators discovering board work. | — | |` kanban_complete`| Finish with`summary`+`metadata`structured handoff. | at least one of`summary`/`result`| |`kanban_block`| Escalate for human input with a`reason`. |` reason`| |`kanban_heartbeat`| Signal liveness during long operations. Pure side-effect. | — | |`kanban_comment`| Append a durable note to the task thread. |`task_id`,` body`| |`kanban_create`| (Orchestrators) fan out into child tasks with an`assignee`, optional` parents`,` skills`, etc. |` title`,` assignee`| |`kanban_link`| (Orchestrators) add a`parent_id → child_id`dependency edge after the fact. |`parent_id`,` child_id`| |`kanban_unblock`| (Orchestrators) move a blocked task back to`ready`. |` task_id| A typical worker turn looks like: ``` # Model's tool calls, in order: kanban_show() # no args — uses HERMES_KANBAN_TASK # (model reads the returned worker_context, does the work via terminal/file tools) kanban_heartbeat(note="halfway through — 4 of 8 files transformed") # (more work) kanban_complete( summary="migrated limiter.py to token-bucket; added 14 tests, all pass", metadata={"changed_files": ["limiter.py", "tests/test_limiter.py"], "tests_run": 14}, ) ``` An orchestrator worker fans out instead: ``` kanban_show() kanban_create( title="research ICP funding 2024-2026", assignee="researcher-a", body="focus on seed + series A, North America, AI-adjacent", ) # → returns {"task_id": "t_r1", ...} kanban_create(title="research ICP funding — EU angle", assignee="researcher-b", body="…") # → returns {"task_id": "t_r2", ...} kanban_create( title="synthesize findings into launch brief", assignee="writer", parents=["t_r1", "t_r2"], # promotes to ready when both complete body="one-pager, 300 words, neutral tone", ) kanban_complete(summary="decomposed into 2 research tasks + 1 writer; linked dependencies") ``` The "(Orchestrators)" tools —kanban_list`,` kanban_create`,` kanban_link`,` kanban_unblock`, and` kanban_comment`on foreign tasks — are available through the same toolset; the convention (enforced by the`kanban-orchestrator`skill) is that worker profiles don't fan out or route unrelated work, and orchestrator profiles don't execute implementation work. Dispatcher-spawned workers are still task-scoped for destructive lifecycle operations and cannot mutate unrelated tasks. ### Why tools instead of shelling to`hermes kanban`Three reasons: 1. Backend portability. Workers whose terminal tool points at a remote backend (Docker / Modal / Singularity / SSH) would run`hermes kanban complete`inside the container, where`hermes`isn't installed and`/.hermes/kanban.db`isn't mounted. The kanban tools run in the agent's own Python process and always reach`/.hermes/kanban.db`regardless of terminal backend. 2. No shell-quoting fragility. Passing`–metadata ‘{“files”: […]}’`through shlex + argparse is a latent footgun. Structured tool args skip it entirely. 3. Better errors. Tool results are structured JSON the model can reason about, not stderr strings it has to parse. Zero schema footprint on normal sessions. A regular`hermes chat`session has zero`kanban_`tools in its schema unless the active profile explicitly enables the`kanban`toolset for orchestrator work. Dispatcher-spawned task workers get task-scoped tools because`HERMES_KANBAN_TASK`is set; orchestrator profiles get the broader routing surface through config. No tool bloat for users who never touch kanban. The`kanban-worker`and`kanban-orchestrator`skills teach the model which tool to call when and in what order. ### Recommended handoff evidence`kanban_complete(summary=…, metadata={…})`is intentionally flexible: the summary is the human-readable closeout, and`metadatais the machine-readable handoff that downstream agents, reviewers, or dashboards can reuse without scraping prose. For engineering and review tasks, prefer this optional metadata shape: ```json { "changed_files": ["path/to/file.py"], "verification": ["pytest tests/hermes_cli/test_kanban_db.py -q"], "dependencies": ["parent task id or external issue, if any"], "blocked_reason": null, "retry_notes": "what failed before, if this was a retry", "residual_risk": ["what was not tested or still needs human review"] } ``` These keys are a convention, not a schema requirement. The useful property is that every worker leaves enough evidence for the next reader to answer four questions quickly: 1. What changed? 2. How was it verified? 3. What can unblock or retry this if it fails? 4. What risk is still deliberately left open? Keep secrets, raw logs, tokens, OAuth material, and unrelated transcripts out ofmetadata`. Store pointers and summaries instead. If a task has no files or tests, say so explicitly in` summary`and use`metadata`for the evidence that does exist, such as source URLs, issue ids, or manual review steps. ### The worker skill Any profile that should be able to work kanban tasks must load the`kanban-worker`skill. It teaches the worker the full lifecycle in tool calls, not CLI commands: 1. On spawn, call`kanban_show()`to read title + body + parent handoffs + prior attempts + full comment thread. 2.`cd HERMES_TENANT`and namespace their memory writes by prefix. The board, the dispatcher, and the profile definitions are all shared; only the data is scoped. ## Gateway notifications When you run`/kanban create …`from the gateway (Telegram, Discord, Slack, etc.), the originating chat is automatically subscribed to the new task. The gateway's background notifier polls`task_events `every few seconds and delivers one message per terminal event (`completed`,` blocked`,` gave_up`,` crashed`,` timed_out`) to that chat. Completed tasks also send the first line of the worker's` –result`so you see the outcome without having to`/kanban show. You can manage subscriptions explicitly from the CLI — useful when a script / cron job wants to notify a chat it didn't originate from: ```bash hermes kanban notify-subscribe t_abcd \ --platform telegram --chat-id 12345678 --thread-id 7 hermes kanban notify-list hermes kanban notify-unsubscribe t_abcd \ --platform telegram --chat-id 12345678 --thread-id 7 ``` A subscription removes itself automatically once the task reaches done`or`archived`; no cleanup needed. ## Runs — one row per attempt A task is a logical unit of work; a run is one attempt to execute it. When the dispatcher claims a ready task it creates a row in` task_runs`and points`tasks.current_run_id`at it. When that attempt ends — completed, blocked, crashed, timed out, spawn-failed, reclaimed — the run row closes with an`outcome`and the task's pointer clears. A task that's been attempted three times has three`task_runs`rows. Why two tables instead of just mutating the task: you need full attempt history for real-world postmortems ("the second reviewer attempt got to approve, the third merged"), and you need a clean place to hang per-attempt metadata — which files changed, which tests ran, which findings a reviewer noted. Those are run facts, not task facts. Runs are also where structured handoff lives. When a worker completes a task (via`kanban_complete(…)`) it can pass: -` summary`(tool param) /`–summary`(CLI) — human handoff; goes on the run; downstream children see it in their`build_worker_context`. -` metadata`(tool param) /`–metadata`(CLI) — free-form JSON dict on the run; children see it serialized alongside the summary. -`result`(tool param) /`–result (CLI) — short log line that goes on the task row (legacy field, kept for back-compat). Downstream children read the most recent completed run's summary + metadata for each parent. Retrying workers read the prior attempts on their own task (outcome, summary, error) so they don't repeat a path that already failed. ``` # What a worker actually does — a tool call, from inside the agent loop: kanban_complete( summary="implemented token bucket, keys on user_id with IP fallback, all tests pass", metadata={"changed_files": ["limiter.py", "tests/test_limiter.py"], "tests_run": 14}, result="rate limiter shipped", ) ``` The same handoff is reachable from the CLI when you (the human) need to close out a task a worker can't — e.g. a task that was abandoned, or one you marked done manually from the dashboard: ```bash hermes kanban complete t_abcd \ --result "rate limiter shipped" \ --summary "implemented token bucket, keys on user_id with IP fallback, all tests pass" \ --metadata '{"changed_files": ["limiter.py", "tests/test_limiter.py"], "tests_run": 14}' # Review the attempt history on a retried task: hermes kanban runs t_abcd # # OUTCOME PROFILE ELAPSED STARTED # 1 blocked worker 12s 2026-04-27 14:02 # → BLOCKED: need decision on rate-limit key # 2 completed worker 8m 2026-04-27 15:18 # → implemented token bucket, keys on user_id with IP fallback ``` Runs are exposed on the dashboard (Run History section in the drawer, one coloured row per attempt) and on the REST API (GET /api/plugins/kanban/tasks/:id`returns a`runs[]`array).`PATCH /api/plugins/kanban/tasks/:id`with`{status: “done”, summary, metadata}`forwards both to the kernel, so the dashboard's "mark done" button is CLI-equivalent.`task_events`rows carry the`run_id`they belong to so the UI can group them by attempt, and the`completed`event embeds the first-line summary in its payload (capped at 400 chars) so gateway notifiers can render structured handoffs without a second SQL round-trip. Bulk close caveat.`hermes kanban complete a b c –summary X`is refused — structured handoff is per-run, so copy-pasting the same summary to N tasks is almost always wrong. Bulk close without`–summary`/`–metadata`still works for the common "I finished a pile of admin tasks" case. Reclaimed runs from status changes. If you drag a running task off`running`in the dashboard (back to`ready`, or straight to` todo`), or archive a task that was still running, the in-flight run closes with` outcome=‘reclaimed’`rather than being orphaned. The`task_runs`row is always in a terminal state when`tasks.current_run_id`is`NULL`, and vice versa — that invariant holds across CLI, dashboard, dispatcher, and notifier. Synthetic runs for never-claimed completions. Completing or blocking a task that was never claimed (e.g. a human closes a` ready`task from the dashboard with a summary, or a CLI user runs`hermes kanban complete –summary X`) would otherwise drop the handoff. Instead the kernel inserts a zero-duration run row (`started_at == ended_at`) carrying the summary / metadata / reason so attempt history stays complete. The` completed`/`blocked`event's`run_id`points at that row. Live drawer refresh. When the dashboard's WebSocket event stream reports new events for the task the user is currently viewing, the drawer reloads itself (via a per-task event counter threaded into its`useEffect`dependency list). Closing and reopening is no longer required to see a run's new row or updated outcome. ### Forward compatibility Two nullable columns on`tasks`are reserved for v2 workflow routing:`workflow_template_id`(which template this task belongs to) and`current_step_key`(which step in that template is active). The v1 kernel ignores them for routing but lets clients write them, so a v2 release can add the routing machinery without another schema migration. ## Event reference Every transition appends a row to`task_events`. Each row carries an optional` run_id `so UIs can group events by attempt. Kinds group into three clusters so filtering is easy (`hermes kanban watch –kinds completed,gave_up,timed_out`): Lifecycle (what changed about the task as a logical unit): | Kind | Payload | When | |---|---|---| |` created`|`{assignee, status, parents, tenant}`| Task inserted.`run_id`is`NULL`. | |` promoted`| — |`todo → ready`because all parents hit`done`.` run_id`is`NULL`. | |` claimed`|`{lock, expires, run_id}`| Dispatcher atomically claimed a`ready`task for spawn. | |`completed`|`{result_len, summary?}`| Worker wrote`–result`/`–summary`and task hit`done`.` summary`is the first-line handoff (400-char cap); full version lives on the run row. If`complete_task`is called on a never-claimed task with handoff fields, a zero-duration run is synthesized so`run_id`still points at something. | |`blocked`|`{reason}`| Worker or human flipped the task to`blocked`. Synthesizes a zero-duration run when called on a never-claimed task with` –reason`. | |` unblocked`| — |`blocked → ready`, either manually or via` /unblock`.` run_id`is`NULL`. | |` archived`| — | Hidden from the default board. If the task was still running, carries the`run_id`of the run that was reclaimed as a side effect. | Edits (human-driven changes that aren't transitions): | Kind | Payload | When | |---|---|---| |`assigned`|`{assignee}`| Assignee changed (including unassignment). | |`edited`|`{fields}`| Title or body updated. | |`reprioritized`|`{priority}`| Priority changed. | |`status`|`{status}`| Dashboard drag-drop wrote a status directly (e.g.`todo → ready`). Carries the` run_id`of the run that was reclaimed when dragging off`running`; otherwise` run_id`is NULL. | Worker telemetry (about the execution process, not the logical task): | Kind | Payload | When | |---|---|---| |`spawned`|`{pid}`| Dispatcher successfully started a worker process. | |`heartbeat`|`{note?}`| Worker called`hermes kanban heartbeat $TASK` to signal liveness during long operations. | | `reclaimed` | `{stale_lock}` | Claim TTL expired without a completion; task goes back to `ready`. | | `crashed` | `{pid, claimer}` | Worker PID no longer alive but TTL hadn't expired yet. | | `timed_out` | `{pid, elapsed_seconds, limit_seconds, sigkill}` | `max_runtime_seconds` exceeded; dispatcher SIGTERM'd (then SIGKILL'd after 5 s grace) and re-queued. | | `stale` | `{elapsed_seconds, last_heartbeat_at, heartbeat_age_seconds, timeout_seconds, pid, terminated}` | Task ran longer than `kanban.dispatch_stale_timeout_seconds` (default 4 h) AND no `kanban_heartbeat` arrived in the last hour. Dispatcher SIGTERM'd the host-local worker (if any), reset the task to `ready` for re-dispatch. Does NOT tick the failure counter (stale is dispatcher-side absence detection, not a worker fault). Workers running long operations should call `kanban_heartbeat` at least once an hour to avoid this. | | `respawn_guarded` | `{reason}` | Dispatcher refused to re-spawn this ready task this tick. Reasons: `blocker_auth` (last failure was a quota/auth/429 error — wait for the rate window to reset), `recent_success` (a completed run happened in the last hour — wait for review before re-running), `active_pr` (a GitHub PR URL appears in a recent comment — a prior worker already opened a PR). The task stays in `ready`; the next tick gets another chance to spawn. If the underlying condition persists, the normal `consecutive_failures` circuit breaker will auto-block via `gave_up` after `failure_limit` failures. | | `spawn_failed` | `{error, failures}` | One spawn attempt failed (missing PATH, workspace unmountable, …). Counter increments; task returns to `ready` for retry. | | `protocol_violation` | `{pid, claimer, exit_code}` | Worker exited successfully while the task was still `running`, usually because it answered without calling `kanban_complete` or `kanban_block`. The dispatcher also emits `gave_up` and auto-blocks immediately instead of retrying. | | `gave_up` | `{failures, effective_limit, limit_source, error}` | Circuit breaker fired after N consecutive non-successful attempts. Task auto-blocks with the last error. The effective limit resolves as task `max_retries`, then dispatcher `failure_limit` / `kanban.failure_limit`, then the built-in default. | `hermes kanban tail <id>` shows these for a single task. `hermes kanban watch` streams them board-wide. ## Out of scope Kanban is deliberately single-host. `~/.hermes/kanban.db` is a local SQLite file and the dispatcher spawns workers on the same machine. Running a shared board across two hosts is not supported — there's no coordination primitive for "worker X on host A, worker Y on host B," and the crash-detection path assumes PIDs are host-local. If you need multi-host, run an independent board per host and use `delegate_task` / a message queue to bridge them. ## Design spec The complete design — architecture, concurrency correctness, comparison with other systems, implementation plan, risks, open questions — lives in `docs/hermes-kanban-v1-spec.pdf`. Read that before filing any behavior-change PR. ---  # user-guide/features/kanban-tutorial # Kanban tutorial A walkthrough of the four use-cases the Hermes Kanban system was designed for, with the dashboard open in a browser. If you haven't read the [Kanban overview](./kanban) yet, start there — this assumes you know what a task, run, assignee, and dispatcher are. ## Setup ```bash hermes kanban init # optional; first `hermes kanban <anything>` auto-inits hermes dashboard # opens http://127.0.0.1:9119 in your browser # click Kanban in the left nav ``` The dashboard is the most comfortable place for you to watch the system. Agent workers the dispatcher spawns never see the dashboard or the CLI — they drive the board through a dedicated `kanban_*` [toolset](./kanban#how-workers-interact-with-the-board) (`kanban_show`, `kanban_list`, `kanban_complete`, `kanban_block`, `kanban_heartbeat`, `kanban_comment`, `kanban_create`, `kanban_link`, `kanban_unblock`). All three surfaces — dashboard, CLI, worker tools — route through the same per-board SQLite DB (`~/.hermes/kanban.db` for the default board, `~/.hermes/kanban/boards/<slug>/kanban.db` for any board you create later), so each board is consistent no matter which side of the fence a change came from. This tutorial uses the `default` board throughout. If you want multiple isolated queues (one per project / repo / domain), see [Boards (multi-project)](./kanban#boards-multi-project) in the overview — the same CLI / dashboard / worker flows apply per board, and workers physically cannot see tasks on other boards. Throughout the tutorial, **code blocks labelled `bash` are commands you run. Code blocks labelled `# worker tool calls` are what the spawned worker's model emits as tool calls — shown here so you can see the loop end-to-end, not because you'd ever run them yourself. ## The board at a glance ![Kanban board overview](/img/kanban-tutorial/01-board-overview.png) Six columns, left to right: - Triage — raw ideas. By default the dispatcher auto-runs the decomposer on tasks here: the built-in decomposer uses `auxiliary.kanban_decomposer`, reads your profile roster + descriptions, and produces a graph of child tasks routed to the best-fit specialists. The original task is held alive as the parent so its assignee (`kanban.orchestrator_profile`, or the active default profile when unset) wakes back up to judge completion when everything finishes. Flip the Orchestration: Auto/Manual pill at the top of the kanban page to switch modes. In Manual mode click ⚗ Decompose on a card, or run `hermes kanban decompose <id>` / `/kanban decompose <id>`. For single tasks that don't need fan-out, ✨ Specify does a one-shot spec rewrite (goal, approach, acceptance criteria) and promotes to `todo`. Configure the models under `auxiliary.kanban_decomposer` and `auxiliary.triage_specifier` in `config.yaml`. See [Auto vs Manual orchestration](./kanban#auto-vs-manual-orchestration) in the main Kanban guide. - Todo — created but waiting on dependencies, or not yet assigned. - Ready — assigned and waiting for the dispatcher to claim. - In progress — a worker is actively running the task. With "Lanes by profile" on (the default), this column sub-groups by assignee so you can see at a glance what each worker is doing. - Blocked — a worker asked for human input, or the circuit breaker tripped. - Done — completed. The top bar has filters for search, tenant, and assignee, plus a `Lanes by profile` toggle and a `Nudge dispatcher` button that runs one dispatch tick right now instead of waiting for the daemon's next interval. Clicking any card opens its drawer on the right. ### Flat view If the profile lanes are noisy, toggle "Lanes by profile" off and the In Progress column collapses to a single flat list ordered by claim time: ![Board with lanes by profile off](/img/kanban-tutorial/02-board-flat.png) ## Story 1 — Solo dev shipping a feature You're building a feature. Classic flow: design a schema, implement the API, write the tests. Three tasks with parent→child dependencies. ```bash SCHEMA=$ (hermes kanban create “Design auth schema” \ –assignee backend-dev –tenant auth-project –priority 2 \ –body “Design the user/session/token schema for the auth module.” \ –json | jq -r .id) API=$(hermes kanban create “Implement auth API endpoints” \ –assignee backend-dev –tenant auth-project –priority 2 \ –parent $SCHEMA \ –body “POST /register, POST /login, POST /refresh, POST /logout.” \ –json | jq -r .id) hermes kanban create “Write auth integration tests” \ –assignee qa-dev –tenant auth-project –priority 2 \ –parent $API \ --body "Cover happy path, wrong password, expired token, concurrent refresh." ``` Because `API` has `SCHEMA` as its parent, and `tests` has `API` as its parent, only `SCHEMA` starts in `ready`. The other two sit in `todo` until their parents complete. This is the dependency promotion engine doing its job — no other worker will pick up the test-writing until there's an API to test. On the next dispatcher tick (60s by default, or immediately if you hit Nudge dispatcher) the `backend-dev` profile spawns as a worker with `HERMES_KANBAN_TASK=$ SCHEMAin its env. Here's what the worker's tool-call loop looks like from inside the agent: ```python # worker tool calls — NOT commands you run kanban_show() # → returns title, body, worker_context, parents, prior attempts, comments # (worker reads worker_context, uses terminal/file tools to design the schema, # write migrations, run its own checks, commit — the real work happens here) kanban_heartbeat(note="schema drafted, writing migrations now") kanban_complete( summary="users(id, email, pw_hash), sessions(id, user_id, jti, expires_at); " "refresh tokens stored as sessions with type='refresh'", metadata={ "changed_files": ["migrations/001_users.sql", "migrations/002_sessions.sql"], "decisions": ["bcrypt for hashing", "JWT for session tokens", "7-day refresh, 15-min access"], }, ) ```kanban_show`defaults`task_id`to`$HERMES_KANBAN_TASK`, so the worker doesn't need to know its own id.` kanban_complete`writes the summary + metadata onto the current`task_runs`row, closes that run, and transitions the task to`done`— all in one atomic hop through`kanban_db`. When` SCHEMA`hits`done`, the dependency engine promotes` API`to`ready`automatically. The API worker, when it picks up, will call`kanban_show()`and see`SCHEMA`'s summary and metadata attached to the parent handoff — so it knows the schema decisions without re-reading a long design doc. Click the completed schema task on the board and the drawer shows everything: ![Solo dev — completed schema task drawer](/img/kanban-tutorial/03-drawer-schema-task.png) The Run History section at the bottom is the key addition. One attempt: outcome` completed`, worker` @backend-dev`, duration, timestamp, and the handoff summary in full. The metadata blob (`changed_files`,` decisions) is stored on the run too and surfaced to any downstream worker that reads this parent. You can inspect the same data from your terminal at any time — these commands are you peeking at the board, not the worker: ```bash hermes kanban show $SCHEMA hermes kanban runs $SCHEMA # # OUTCOME PROFILE ELAPSED STARTED # 1 completed backend-dev 0s 2026-04-27 19:34 # → users(id, email, pw_hash), sessions(id, user_id, jti, expires_at); refresh tokens ... ``` ## Story 2 — Fleet farming You have three workers (a translator, a transcriber, a copywriter) and a pile of independent tasks. You want all three pulling in parallel and making visible progress. This is the simplest kanban use-case and the one the original design optimized for. Create the work: ```bash for lang in Spanish French German; do hermes kanban create "Translate homepage to $lang" \ --assignee translator --tenant content-ops done for i in 1 2 3 4 5; do hermes kanban create "Transcribe Q3 customer call #$i" \ --assignee transcriber --tenant content-ops done for sku in 1001 1002 1003 1004; do hermes kanban create "Generate product description: SKU-$sku" \ --assignee copywriter --tenant content-ops done ``` Start the gateway and walk away — it hosts the embedded dispatcher that picks up all three specialist profiles' tasks on the same kanban.db: ```bash hermes gateway start ``` Now filter the board to content-ops(or just search for "Transcribe") and you get this: ![Fleet view filtered to transcribe tasks](/img/kanban-tutorial/07-fleet-transcribes.png) Two transcribes done, one running, two ready waiting for the next dispatcher tick. The In Progress column is grouped by profile (the "Lanes by profile" default) so you see each worker's active task without scanning a mixed list. The dispatcher will promote the next ready task to running as soon as the current one completes. With three daemons working on three assignee pools in parallel, the whole content queue drains without further human input. Everything Story 1 said about structured handoff still applies here. A translator worker completing a call emitskanban_complete(summary=“translated 4 pages, style matched existing marketing voice”, metadata={“duration_seconds”: 720, “tokens_used”: 2100})`— useful for analytics and for any downstream task that depends on this one. ## Story 3 — Role pipeline with retry This is where Kanban earns its keep over a flat TODO list. A PM writes a spec. An engineer implements it. A reviewer rejects the first attempt. The engineer tries again with changes. The reviewer approves. The dashboard view, filtered by`auth-project`: ![Pipeline view for a multi-role feature](/img/kanban-tutorial/08-pipeline-auth.png) Three-stage chain visible at once:` Spec: password reset flow`(DONE, pm),`Implement password reset flow`(DONE, backend-dev),`Review password reset PR(READY, reviewer). Each has its parent in green at the bottom and children as dependencies. The interesting one is the implementation task, because it was blocked and retried. Here's the full three-agent choreography, shown as the tool calls each worker's model makes: ```python # --- PM worker spawns on $SPEC and writes the acceptance criteria --- # worker tool calls kanban_show() kanban_complete( summary="spec approved; POST /forgot-password sends email, " "GET /reset/:token renders form, POST /reset applies new password", metadata={"acceptance": [ "expired token returns 410", "reused last-3 password returns 400 with message", "successful reset invalidates all active sessions", ]}, ) # → $SPEC is done; $IMPL auto-promotes from todo to ready # --- Engineer worker spawns on $IMPL (first attempt) --- # worker tool calls kanban_show() # reads $SPEC's summary + acceptance metadata in worker_context # (engineer writes code, runs tests, opens PR) # Reviewer feedback arrives — engineer decides the concerns are valid and blocks kanban_block( reason="Review: password strength check missing, reset link isn't " "single-use (can be replayed within 30min)", ) # → $IMPL transitions to blocked; run 1 closes with outcome='blocked' ``` Now you (the human, or a separate reviewer profile) read the block reason, decide the fix direction is clear, and unblock from the dashboard's "Unblock" button — or from the CLI / slash command: ```bash hermes kanban unblock $IMPL # or from a chat: /kanban unblock $IMPL ``` The dispatcher promotes$IMPL`back to`ready`and, on the next tick, respawns the`backend-devworker. This second spawn is a new run on the same task: ```python # --- Engineer worker spawns on $IMPL (second attempt) --- # worker tool calls kanban_show() # → worker_context now includes the run 1 block reason, so this worker knows # which two things to fix instead of re-reading the whole spec # (engineer adds zxcvbn check, makes reset tokens single-use, re-runs tests) kanban_complete( summary="added zxcvbn strength check, reset tokens are now single-use " "(stored + deleted on success)", metadata={ "changed_files": [ "auth/reset.py", "auth/tests/test_reset.py", "migrations/003_single_use_reset_tokens.sql", ], "tests_run": 11, "review_iteration": 2, }, ) ``` Click the implementation task. The drawer shows two attempts: ![Implementation task with two runs — blocked then completed](/img/kanban-tutorial/04b-drawer-retry-history-scrolled.png) - Run 1 —blocked`by`@backend-dev`. The review feedback sits right under the outcome: "password strength check missing, reset link isn't single-use (can be replayed within 30min)". - Run 2 —` completed`by`@backend-dev`. Fresh summary, fresh metadata. Each run is a row in` task_runs`with its own outcome, summary, and metadata. Retry history is not a conceptual afterthought layered on top of a "latest state" task — it's the primary representation. When a retrying worker opens the task,`build_worker_context`shows it the prior attempts, so the second-pass worker sees why the first pass was blocked and addresses those specific findings instead of re-running from scratch. The reviewer picks up next. When they open`Review password reset PR`, they see: ![Reviewer's drawer view of the pipeline](/img/kanban-tutorial/09-drawer-pipeline-review.png) The parent link is the completed implementation. When the reviewer's worker spawns on` Review password reset PR`and calls`kanban_show()`, the returned` worker_contextincludes the parent's most-recent-completed-run summary + metadata — so the reviewer reads "added zxcvbn strength check, reset tokens are now single-use" and has the list of changed files in hand before looking at a diff. ## Story 4 — Circuit breaker and crash recovery Real workers fail. Missing credentials, OOM kills, transient network errors. The dispatcher has two lines of defense: a circuit breaker that auto-blocks after N consecutive failures so the board doesn't thrash forever, and crash detection that reclaims a task whose worker PID went away before its TTL expired. ### Circuit breaker — permanent-looking failure A deploy task that can't spawn its worker becauseAWS_ACCESS_KEY_ID isn't set in the profile's environment: ```bash hermes kanban create "Deploy to staging (missing creds)" \ --assignee deploy-bot --tenant ops \ --max-retries 3 ``` The dispatcher tries to spawn the worker. Spawn fails (RuntimeError: AWS_ACCESS_KEY_ID not set`). The dispatcher releases the claim, increments a failure counter, and tries again next tick. Because this example sets` –max-retries 3`, the circuit trips after three consecutive failures: the task goes to` blocked`with outcome`gave_up`. If you omit the flag, Hermes uses` kanban.failure_limit`(default: 2). No more retries until a human unblocks it. Click the blocked task: ![Circuit breaker — 2 spawn_failed + 1 gave_up](/img/kanban-tutorial/11-drawer-gave-up.png) Three runs, all with the same error on the`error`field. The first two are`spawn_failed`(retryable), the third is`gave_up`(terminal). The event log above shows the full sequence:`created → claimed → spawn_failed → claimed → spawn_failed → claimed → gave_up. On the terminal: ```bash hermes kanban runs t_ef5d # # OUTCOME PROFILE ELAPSED STARTED # 1 spawn_failed deploy-bot 0s 2026-04-27 19:34 # ! AWS_ACCESS_KEY_ID not set in deploy-bot env # 2 spawn_failed deploy-bot 0s 2026-04-27 19:34 # ! AWS_ACCESS_KEY_ID not set in deploy-bot env # 3 gave_up deploy-bot 0s 2026-04-27 19:34 # ! AWS_ACCESS_KEY_ID not set in deploy-bot env ``` If Telegram / Discord / Slack is wired in, a gateway notification fires on the gave_up`event so you hear about the outage without having to check the board. ### Crash recovery — worker dies mid-flight Sometimes the spawn succeeds but the worker process dies later — segfault, OOM,`systemctl stop`. The dispatcher polls` kill(pid, 0)`and detects the dead pid; the claim releases, the task goes back to`ready, and the next tick gives it to a fresh worker. The example in the seed data is a migration that was running out of memory: ```bash # Worker claims, starts scanning 2.4M rows, OOM kills it at ~2.3M # Dispatcher detects dead pid, releases claim, increments attempt counter # Retry with a chunked strategy succeeds ``` The drawer shows the full two-attempt history: ![Crash and recovery — 1 crashed + 1 completed](/img/kanban-tutorial/06-drawer-crash-recovery.png) Run 1 — crashed`, with the error` OOM kill at row 2.3M (process 99999 gone)`. Run 2 —` completed`, with` “strategy”: “chunked with LIMIT + WHERE id > last_id”`in its metadata. The retrying worker saw the crash of run 1 in its context and picked a safer strategy; the metadata makes it obvious to a future observer (or postmortem writer) what changed. ## Structured handoff — why`summary`and`metadata`matter In every story above, workers called`kanban_complete(summary=…, metadata=…)`at the end. That's not decoration — it's the primary handoff channel between stages of a workflow. When a worker on task B is spawned and calls`kanban_show()`, the` worker_contextit gets back includes: - B's prior attempts (previous runs: outcome, summary, error, metadata) so a retrying worker doesn't repeat a failed path. - Parent task results — for each parent, the most-recent completed run's summary and metadata — so downstream workers see why and how the upstream work was done. This replaces the "dig through comments and the work output" dance that plagues flat kanban systems. A PM writes acceptance criteria in the spec's metadata, and the engineer's worker sees them structurally in the parent handoff. An engineer records which tests they ran and how many passed, and the reviewer's worker has that list in hand before opening a diff. The bulk-close guard exists because this data is per-run.hermes kanban complete a b c –summary X`(you, from the CLI) is refused — copy-pasting the same summary to three tasks is almost always wrong. Bulk close without the handoff flags still works for the common "I finished a pile of admin tasks" case. The tool surface doesn't expose a bulk variant at all;`kanban_complete`is always single-task-at-a-time for the same reason. ## Inspecting a task currently running For completeness — here's the drawer of a task still in flight (the API implementation from Story 1, claimed by`backend-dev`but not yet complete): ![Claimed, in-flight task](/img/kanban-tutorial/10-drawer-in-flight.png) Status is`Running`. The active run appears in the Run History section with outcome` active`and no`ended_at`. If this worker dies or times out, the dispatcher closes this run with the appropriate outcome and opens a new one on the next claim — the attempt row never disappears. ## Next steps - [Kanban overview](./kanban) — the full data model, event vocabulary, and CLI reference. -` hermes kanban –help`— every subcommand, every flag. -`hermes kanban watch –kinds completed,gave_up,timed_out`— live stream terminal events across the whole board. -`hermes kanban notify-subscribe –platform telegram –chat-id `— get a gateway ping when a specific task finishes. ---  # Persistent Goals # Persistent Goals (`/goal`)` /goal`gives Hermes a standing objective that survives across turns. After every turn a lightweight judge model checks whether the goal is satisfied by the assistant's last response. If not, Hermes automatically feeds a continuation prompt back into the same session and keeps working — until the goal is achieved, you pause or clear it, or the turn budget runs out. It's our take on the Ralph loop**, directly inspired by [Codex CLI 0.128.0's`/goal`](https://github.com/openai/codex) by Eric Traut (OpenAI). The core idea — keep a goal alive across turns and don't stop until it's achieved — is theirs. The implementation here is independent and adapted to Hermes' architecture. ## When to use it Use` /goal`for tasks where you want Hermes to iterate on its own without you re-prompting every turn: - "Fix every lint error in`src/`and verify`ruff check`passes" - "Port feature X from repo Y, including tests, and get CI green" - "Investigate why session IDs sometimes drift on mid-run compression and write up a report" - "Build a small CLI to rename files by their EXIF dates, then test it against the photos/ folder" Tasks where the agent does one turn and stops don't need`/goal. Tasks where you'd otherwise have to say "keep going" three times are where this shines. ## Quick start ``` /goal Fix every failing test in tests/hermes_cli/ and make sure scripts/run_tests.sh passes for that directory ``` What you'll see: 1. Goal accepted — ⊙ Goal set (20-turn budget): `2. Turn 1 runs — Hermes starts working as if you'd sent the goal as a normal message. 3. Judge runs — after the turn, the judge model decides`done`or`continue`. 4. Loop fires if needed — if` continue`, you'll see` ↻ Continuing toward goal (1/20): <judge’s reason>`and Hermes takes the next step automatically. 5. Terminates — eventually you see either`✓ Goal achieved: `or`⏸ Goal paused — N/20 turns used`. ## Commands | Command | What it does | |---|---| |` /goal `| Set (or replace) the standing goal. Kicks off the first turn immediately so you don't need to send a separate message. | |`/goal`or`/goal status`| Show the current goal, its status, and turns used. | |`/goal pause`| Stop the auto-continuation loop without clearing the goal. | |`/goal resume`| Resume the loop (resets the turn counter back to zero). | |`/goal clear`| Drop the goal entirely. | Works identically on the CLI and every gateway platform (Telegram, Discord, Slack, Matrix, Signal, WhatsApp, SMS, iMessage, Webhook, API server, and the web dashboard). ## Adding criteria mid-goal:`/subgoal`While a goal is active you can append extra acceptance criteria with`/subgoal `without resetting the loop. Each call adds one numbered item to the goal's subgoal list; the continuation prompt the agent sees on the next turn includes the original goal plus an "Additional criteria the user added mid-loop" block, and the judge prompt is rewritten so the verdict must consider every subgoal — the goal isn't marked done until the original objective and every subgoal are met. | Command | What it does | |---|---| |`/subgoal `| Append a new criterion to the active goal. Requires an active`/goal`. | |` /subgoal`(no args) | Show the current numbered subgoal list. | |`/subgoal remove `| Remove the Nth subgoal (1-based). | |`/subgoal clear`| Drop every subgoal but keep the original goal intact. | Subgoals are persisted alongside the goal in`SessionDB.state_meta`, so they survive` /resume`. Setting a new` /goal `replaces the goal and clears the subgoal list;`/goal clear`does the same. Use this when you start a loop ("fix the failing tests") and notice partway through that you also want it to "and add a regression test for the bug you just patched" —`/subgoal add a regression test`tightens the success criteria without breaking the running loop. ## Behavior details ### The judge After every turn, Hermes calls an auxiliary model with: - The standing goal text - The agent's most recent final response (last ~4 KB of text) - A system prompt telling the judge to reply with strict JSON:`{“done”: , “reason”: “”}`The judge is deliberately conservative: it marks a goal`done`only when the response explicitly confirms the goal is complete, when the final deliverable is clearly produced, or when the goal is unachievable/blocked (treated as DONE with a block reason so we don't burn budget on impossible tasks). ### Fail-open semantics If the judge errors (network blip, malformed response, unavailable aux client), Hermes treats the verdict as`continue `— a broken judge never wedges progress. The turn budget is the real backstop. ### Turn budget Default is 20 continuation turns (`goals.max_turns`in`config.yaml). When the budget is hit, Hermes auto-pauses and tells you exactly how to proceed: ``` ⏸ Goal paused — 20/20 turns used. Use /goal resume to keep going, or /goal clear to stop. ``` /goal resume`resets the counter to zero, so you can keep going in measured chunks. ### User messages always preempt Any real message you send while a goal is active takes priority over the continuation loop. On the CLI your message lands in`pending_input`ahead of the queued continuation; on the gateway it goes through the adapter FIFO the same way. The judge runs again after your turn — so if your message happens to complete the goal, the judge will catch it and stop. ### Mid-run safety (gateway) While an agent is already running,`/goal status`,` /goal pause`, and` /goal clear `are safe to run — they only touch control-plane state and don't interrupt the current turn. Setting a new goal mid-run (`/goal `) is rejected with a message telling you to` /stop`first, so the old continuation can't race the new one. ### Persistence Goal state lives in`SessionDB.state_meta`keyed by`goal:<session_id>`. That means` /resume`picks up right where you left off — set a goal, close your laptop, come back tomorrow,`/resume`, and the goal is still standing exactly as you left it (active, paused, or done). ### Prompt cache The continuation prompt is a plain user-role message appended to history. It does not mutate the system prompt, swap toolsets, or touch the conversation in any way that invalidates Hermes' prompt cache. Running a 20-turn goal costs the same cache-wise as 20 turns of normal conversation. ## Configuration Add to` /.hermes/config.yaml: ```yaml goals: # Max continuation turns before Hermes auto-pauses and asks you to # /goal resume. Default 20. Lower this if you want tighter loops; # raise it for long-running refactors. max_turns: 20 ``` ### Choosing the judge model The judge uses the goal_judgeauxiliary task. By default it resolves to your main model (see [Auxiliary Models](/user-guide/configuration#auxiliary-models)). If you want to route the judge to a cheap fast model to keep costs down, add an override: ```yaml auxiliary: goal_judge: provider: openrouter model: google/gemini-3-flash-preview ``` The judge call is small (~200 output tokens) and runs once per turn, so a cheap fast model is usually the right call. ## Example walkthrough ``` You: /goal Create four files /tmp/note_{1..4}.txt, one per turn, each containing its number as text ⊙ Goal set (20-turn budget): Create four files /tmp/note_{1..4}.txt, one per turn, each containing its number as text Hermes: Creating /tmp/note_1.txt now. 💻 echo "1" > /tmp/note_1.txt (0.1s) I've created /tmp/note_1.txt with the content "1". I'll continue with the remaining files on the next turn as you specified. ↻ Continuing toward goal (1/20): Only 1 of 4 files has been created; 3 files remain. Hermes: [Continuing toward your standing goal] 💻 echo "2" > /tmp/note_2.txt (0.1s) Created /tmp/note_2.txt. Two more to go. ↻ Continuing toward goal (2/20): 2 of 4 files created; 2 remain. Hermes: [Continuing toward your standing goal] 💻 echo "3" > /tmp/note_3.txt (0.1s) Created /tmp/note_3.txt. ↻ Continuing toward goal (3/20): 3 of 4 files created; 1 remains. Hermes: [Continuing toward your standing goal] 💻 echo "4" > /tmp/note_4.txt (0.1s) All four files have been created: /tmp/note_1.txt through /tmp/note_4.txt, each containing its number. ✓ Goal achieved: All four files were created with the specified content, completing the goal. You: _ ``` Four turns, one/goal`invocation, zero "keep going" prompts from you. ## When the judge gets it wrong No judge is perfect. Two failure modes to watch for: False negative — judge says continue when the goal is actually done. The turn budget catches this. You'll see`⏸ Goal paused`and can`/goal clear`or just send a new message. False positive — judge says done when work remains. You'll see`✓ Goal achieved`but you know better. Send a follow-up message to continue, or re-set the goal more precisely:`/goal `. The judge's system prompt is deliberately conservative to make false positives rarer than false negatives. If you find a judge verdict unconvincing, the reason text in the` ↻ Continuing toward goal`or`✓ Goal achieved`line tells you exactly what the judge saw. That's usually enough to diagnose whether the goal text was ambiguous or the model's response was. ## Attribution`/goal`is Hermes' take on the Ralph loop pattern. The user-facing design — keep a goal alive across turns, don't stop until it's achieved, with create/pause/resume/clear controls — was popularised and shipped in [Codex CLI 0.128.0](https://github.com/openai/codex) by Eric Traut on OpenAI's Codex team. Our implementation is independent (central`CommandDef`registry,`SessionDB.state_meta`persistence, auxiliary-client judge, adapter-FIFO continuation on the gateway side) but the idea is theirs. Credit where credit's due. ---  # Code Execution # Code Execution (Programmatic Tool Calling) The`execute_code`tool lets the agent write Python scripts that call Hermes tools programmatically, collapsing multi-step workflows into a single LLM turn. The script runs in a child process on the agent host, communicating with Hermes over a Unix domain socket RPC. ## How It Works 1. The agent writes a Python script using`from hermes_tools import …`2. Hermes generates a`hermes_tools.py`stub module with RPC functions 3. Hermes opens a Unix domain socket and starts an RPC listener thread 4. The script runs in a child process — tool calls travel over the socket back to Hermes 5. Only the script's`print()output is returned to the LLM; intermediate tool results never enter the context window ```python # The agent can write scripts like: from hermes_tools import web_search, web_extract results = web_search("Python 3.13 features", limit=5) for r in results["data"]["web"]: content = web_extract([r["url"]]) # ... filter and process ... print(summary) ``` Available tools inside scripts:web_search`,` web_extract`,` read_file`,` write_file`,` search_files`,` patch`,` terminal`(foreground only). ## When the Agent Uses This The agent uses`execute_code`when there are: - 3+ tool calls with processing logic between them - Bulk data filtering or conditional branching - Loops over results The key benefit: intermediate tool results never enter the context window — only the final`print()output comes back, dramatically reducing token usage. ## Practical Examples ### Data Processing Pipeline ```python from hermes_tools import search_files, read_file import json # Find all config files and extract database settings matches = search_files("database", path=".", file_glob=".yaml", limit=20) configs = [] for match in matches.get("matches", []): content = read_file(match["path"]) configs.append({"file": match["path"], "preview": content["content"][:200]}) print(json.dumps(configs, indent=2)) ``` ### Multi-Step Web Research ```python from hermes_tools import web_search, web_extract import json # Search, extract, and summarize in one turn results = web_search("Rust async runtime comparison 2025", limit=5) summaries = [] for r in results["data"]["web"]: page = web_extract([r["url"]]) for p in page.get("results", []): if p.get("content"): summaries.append({ "title": r["title"], "url": r["url"], "excerpt": p["content"][:500] }) print(json.dumps(summaries, indent=2)) ``` ### Bulk File Refactoring ```python from hermes_tools import search_files, read_file, patch # Find all Python files using deprecated API and fix them matches = search_files("old_api_call", path="src/", file_glob=".py") fixed = 0 for match in matches.get("matches", []): result = patch( path=match["path"], old_string="old_api_call(", new_string="new_api_call(", replace_all=True ) if "error" not in str(result): fixed += 1 print(f"Fixed {fixed} files out of {len(matches.get('matches', []))} matches") ``` ### Build and Test Pipeline ```python from hermes_tools import terminal, read_file import json # Run tests, parse results, and report result = terminal("cd /project && python -m pytest --tb=short -q 2>&1", timeout=120) output = result.get("output", "") # Parse test output passed = output.count(" passed") failed = output.count(" failed") errors = output.count(" error") report = { "passed": passed, "failed": failed, "errors": errors, "exit_code": result.get("exit_code", -1), "summary": output[-500:] if len(output) > 500 else output } print(json.dumps(report, indent=2)) ``` ## Execution Modeexecute_code`has two execution modes controlled by`code_execution.mode`in`/.hermes/config.yaml`: | Mode | Working directory | Python interpreter | |------|-------------------|--------------------| | `project` (default) | The session's working directory (same as` terminal()`) | Active` VIRTUAL_ENV`/`CONDA_PREFIX`python, falling back to Hermes's own python | |`strict`| A temp staging directory isolated from the user's project |`sys.executable`(Hermes's own python) | When to leave it on`project`: you want` import pandas`,` from my_project import foo`, or relative paths like` open(“.env”)`to work the same way they do in`terminal()`. This is almost always what you want. When to flip to` strict: you need maximum reproducibility — you want the same interpreter every session regardless of which venv the user activated, and you want scripts quarantined from the project tree (no risk of accidentally reading project files through a relative path). ```yaml # ~/.hermes/config.yaml code_execution: mode: project # or "strict" ``` Fallback behavior in project`mode: if`VIRTUAL_ENV`/`CONDA_PREFIX`is unset, broken, or points at a Python older than 3.8, the resolver falls back cleanly to`sys.executable`— it never leaves the agent without a working interpreter. Security-critical invariants are identical across both modes: - environment scrubbing (API keys, tokens, credentials stripped) - tool whitelist (scripts cannot call`execute_code`recursively,`delegate_task`, or MCP tools) - resource limits (timeout, stdout cap, tool-call cap) Switching mode changes where scripts run and which interpreter runs them, not what credentials they can see or which tools they can call. ## Resource Limits | Resource | Limit | Notes | |----------|-------|-------| | Timeout | 5 minutes (300s) | Script is killed with SIGTERM, then SIGKILL after 5s grace | | Stdout | 50 KB | Output truncated with` [output truncated at 50KB]`notice | | Stderr | 10 KB | Included in output on non-zero exit for debugging | | Tool calls | 50 per execution | Error returned when limit reached | All limits are configurable via`config.yaml: ```yaml # In ~/.hermes/config.yaml code_execution: mode: project # project (default) | strict timeout: 300 # Max seconds per script (default: 300) max_tool_calls: 50 # Max tool calls per execution (default: 50) ``` ## How Tool Calls Work Inside Scripts When your script calls a function like web_search(“query”)`: 1. The call is serialized to JSON and sent over a Unix domain socket to the parent process 2. The parent dispatches through the standard` handle_function_call`handler 3. The result is sent back over the socket 4. The function returns the parsed result This means tool calls inside scripts behave identically to normal tool calls — same rate limits, same error handling, same capabilities. The only restriction is that`terminal()`is foreground-only (no`background`or`pty`parameters). ## Error Handling When a script fails, the agent receives structured error information: - Non-zero exit code: stderr is included in the output so the agent sees the full traceback - Timeout: Script is killed and the agent sees`“Script timed out after 300s and was killed.”`- Interruption: If the user sends a new message during execution, the script is terminated and the agent sees`[execution interrupted — user sent a new message]`- Tool call limit: When the 50-call limit is hit, subsequent tool calls return an error message The response always includes`status`(success/error/timeout/interrupted),`output`,` tool_calls_made`, and` duration_seconds`. ## Security :::danger Security Model The child process runs with a minimal environment. API keys, tokens, and credentials are stripped by default. The script accesses tools exclusively via the RPC channel — it cannot read secrets from environment variables unless explicitly allowed. ::: Environment variables containing` KEY`,` TOKEN`,` SECRET`,` PASSWORD`,` CREDENTIAL`,` PASSWD`, or` AUTH `in their names are excluded. Only safe system variables (`PATH`,` HOME`,` LANG`,` SHELL`,` PYTHONPATH`,` VIRTUAL_ENV`, etc.) are passed through. ### Skill Environment Variable Passthrough When a skill declares` required_environment_variables`in its frontmatter, those variables are automatically passed through to both`execute_code`and`terminal`child processes after the skill is loaded. This lets skills use their declared API keys without weakening the security posture for arbitrary code. For non-skill use cases, you can explicitly allowlist variables in`config.yaml: ```yaml terminal: env_passthrough: - MY_CUSTOM_KEY - ANOTHER_TOKEN ``` See the [Security guide](/user-guide/security#environment-variable-passthrough) for full details. ### HERMES`variables in the child The child process receives only a small, fixed set of operational`HERMES_`variables by exact name: -`HERMES_HOME`-`HERMES_PROFILE`-`HERMES_CONFIG`-`HERMES_ENV`(plus`HERMES_RPC_DIR`/`HERMES_RPC_SOCKET`/`TZ`/`HOME`, which Hermes injects explicitly so the RPC channel works). :::note Behavior change Earlier versions passed any variable whose name began with` HERMES_`through to the child. That broad prefix was removed for security hardening: it could leak`HERMES_`-named configuration that doesn't match a secret substring (for example` HERMES_BASE_URL`,` HERMES_KANBAN_DB`, or a` HERMES_WEBHOOK`endpoint) into arbitrary sandboxed code. If an`execute_code`script — or a repo/plugin module it imports at import time — relied on a`HERMES`variable outside the four operational names above, it will now find that variable unset in the child. The drop is intentional, not a bug. ::: Workaround — opt the variable back in explicitly. Both routes pass the variable through`execute_code`and`terminal`children, and neither weakens the secret-stripping guarantee (Hermes-managed provider credentials can never be re-allowed this way): 1. Per-machine, in`config.yaml — add the exact variable name to the passthrough allowlist: ```yaml terminal: env_passthrough: - HERMES_KANBAN_DB - HERMES_BASE_URL ``` 2. Per-skill, in the skill's frontmatter — declare it so it is registered automatically whenever that skill is loaded: ```yaml required_environment_variables: - HERMES_KANBAN_DB ``` Diagnosing it. When the child drops one or more non-allowlisted HERMES_`variables, Hermes emits a one-line`debug`log naming them and pointing at the`env_passthrough `escape hatch. Run with debug logging (`hermes logs –level DEBUG`, or check` ~/.hermes/logs/agent.log`) and look for` execute_code: dropped N non-allowlisted HERMES_ var(s)`if a script behaves as though a`HERMES_`variable is missing. Hermes always writes the script and the auto-generated`hermes_tools.py`RPC stub into a temp staging directory that is cleaned up after execution. In`strict`mode the script also runs there; in`project`mode it runs in the session's working directory (the staging directory stays on`PYTHONPATHso imports still resolve). The child process runs in its own process group so it can be cleanly killed on timeout or interruption. ## execute_code vs terminal | Use Case | execute_code | terminal | |----------|-------------|----------| | Multi-step workflows with tool calls between | ✅ | ❌ | | Simple shell command | ❌ | ✅ | | Filtering/processing large tool outputs | ✅ | ❌ | | Running a build or test suite | ❌ | ✅ | | Looping over search results | ✅ | ❌ | | Interactive/background processes | ❌ | ✅ | | Needs API keys in environment | ⚠️ Only via [passthrough](/user-guide/security#environment-variable-passthrough) | ✅ (most pass through) | Rule of thumb: Useexecute_code`when you need to call Hermes tools programmatically with logic between calls. Use`terminalfor running shell commands, builds, and processes. ## Platform Support Code execution requires Unix domain sockets and is available on Linux and macOS only. It is automatically disabled on Windows — the agent falls back to regular sequential tool calls. ---  # Event Hooks # Event Hooks Hermes has three hook systems that run custom code at key lifecycle points: | System | Registered via | Runs in | Use case | |--------|---------------|---------|----------| | [Gateway hooks](#gateway-event-hooks) |HOOK.yaml`+`handler.py`in`/.hermes/hooks/`| Gateway only | Logging, alerts, webhooks | | [Plugin hooks](#plugin-hooks) |`ctx.register_hook()`in a [plugin](/user-guide/features/plugins) | CLI + Gateway | Tool interception, metrics, guardrails | | [Shell hooks](#shell-hooks) |`hooks:`block in`/.hermes/config.yaml`pointing at shell scripts | CLI + Gateway | Drop-in scripts for blocking, auto-formatting, context injection | All three systems are non-blocking — errors in any hook are caught and logged, never crashing the agent. ## Gateway Event Hooks Gateway hooks fire automatically during gateway operation (Telegram, Discord, Slack, WhatsApp, Teams) without blocking the main agent pipeline. ### Creating a Hook Each hook is a directory under`~/.hermes/hooks/containing two files: ```text ~/.hermes/hooks/ └── my-hook/ ├── HOOK.yaml # Declares which events to listen for └── handler.py # Python handler function ``` #### HOOK.yaml ```yaml name: my-hook description: Log all agent activity to a file events: - agent:start - agent:end - agent:step ``` Theevents`list determines which events trigger your handler. You can subscribe to any combination of events, including wildcards like`command:. #### handler.py ```python import json from datetime import datetime from pathlib import Path LOG_FILE = Path.home() / ".hermes" / "hooks" / "my-hook" / "activity.log" async def handle(event_type: str, context: dict): """Called for each subscribed event. Must be named 'handle'.""" entry = { "timestamp": datetime.now().isoformat(), "event": event_type, context, } with open(LOG_FILE, "a") as f: f.write(json.dumps(entry) + "\n") ``` Handler rules:** - Must be named handle`- Receives`event_type`(string) and`context`(dict) - Can be`async def`or regular`def`— both work - Errors are caught and logged, never crashing the agent ### Available Events | Event | When it fires | Context keys | |-------|---------------|--------------| |`gateway:startup`| Gateway process starts |`platforms`(list of active platform names) | |`session:start`| New messaging session created |`platform`,` user_id`,` session_id`,` session_key`| |`session:end`| Session ended (before reset) |`platform`,` user_id`,` session_key`| |`session:reset`| User ran`/new`or`/reset`|`platform`,` user_id`,` session_key`| |`agent:start`| Agent begins processing a message |`platform`,` user_id`,` session_id`,` message`| |`agent:step`| Each iteration of the tool-calling loop |`platform`,` user_id`,` session_id`,` iteration`,` tool_names`| |`agent:end`| Agent finishes processing |`platform`,` user_id`,` session_id`,` message`,` response`| |`command:`| Any slash command executed |`platform`,` user_id`,` command`,` args`| #### Wildcard Matching Handlers registered for`command:`fire for any`command: `event (`command:model`,` command:reset, etc.). Monitor all slash commands with a single subscription. ### Examples #### Telegram Alert on Long Tasks Send yourself a message when the agent takes more than 10 steps: ```yaml # ~/.hermes/hooks/long-task-alert/HOOK.yaml name: long-task-alert description: Alert when agent is taking many steps events: - agent:step ``` ```python # ~/.hermes/hooks/long-task-alert/handler.py import os import httpx THRESHOLD = 10 BOT_TOKEN = os.getenv("TELEGRAM_BOT_TOKEN") CHAT_ID = os.getenv("TELEGRAM_HOME_CHANNEL") async def handle(event_type: str, context: dict): iteration = context.get("iteration", 0) if iteration == THRESHOLD and BOT_TOKEN and CHAT_ID: tools = ", ".join(context.get("tool_names", [])) text = f"⚠️ Agent has been running for {iteration} steps. Last tools: {tools}" async with httpx.AsyncClient() as client: await client.post( f"https://api.telegram.org/bot{BOT_TOKEN}/sendMessage", json={"chat_id": CHAT_ID, "text": text}, ) ``` #### Command Usage Logger Track which slash commands are used: ```yaml # ~/.hermes/hooks/command-logger/HOOK.yaml name: command-logger description: Log slash command usage events: - command:* ``` ```python # ~/.hermes/hooks/command-logger/handler.py import json from datetime import datetime from pathlib import Path LOG = Path.home() / ".hermes" / "logs" / "command_usage.jsonl" def handle(event_type: str, context: dict): LOG.parent.mkdir(parents=True, exist_ok=True) entry = { "ts": datetime.now().isoformat(), "command": context.get("command"), "args": context.get("args"), "platform": context.get("platform"), "user": context.get("user_id"), } with open(LOG, "a") as f: f.write(json.dumps(entry) + "\n") ``` #### Session Start Webhook POST to an external service on new sessions: ```yaml # ~/.hermes/hooks/session-webhook/HOOK.yaml name: session-webhook description: Notify external service on new sessions events: - session:start - session:reset ``` ```python # ~/.hermes/hooks/session-webhook/handler.py import httpx WEBHOOK_URL = "https://your-service.example.com/hermes-events" async def handle(event_type: str, context: dict): async with httpx.AsyncClient() as client: await client.post(WEBHOOK_URL, json={ "event": event_type, context, }, timeout=5) ``` ### Tutorial: BOOT.md — Run a Startup Checklist on Every Gateway Boot A popular pattern from the community: drop a Markdown checklist at /.hermes/BOOT.md`, and have the agent run it once every time the gateway starts. Useful for "on every boot, check overnight cron failures and ping me on Discord if anything failed," or "summarize the last 24h of deploy.log and post it to Slack #ops." This tutorial shows how to build it yourself as a user-defined hook. Hermes does not ship a built-in BOOT.md hook — you wire up exactly the behavior you want. #### What we're building 1. A file at` /.hermes/BOOT.md`with natural-language startup instructions. 2. A gateway hook that fires on`gateway:startup`, spawns a one-shot agent with your gateway's resolved model/credentials, and runs the BOOT.md instructions. 3. A` [SILENT]`convention so the agent can opt out of sending a message when there's nothing to report. #### Step 1: Write your checklist Create`/.hermes/BOOT.md. Write it as if you were giving instructions to a human assistant: ```markdown # Startup Checklist 1. Run hermes cron list`and check if any scheduled jobs failed overnight. 2. If any failed, send a summary to Discord #ops using the`send_message`tool. 3. Check if`/opt/app/deploy.log`has any ERROR lines from the last 24 hours. If yes, summarize them and include in the same Discord message. 4. If nothing went wrong, reply with only`[SILENT] so no message is sent. ``` The agent sees this as part of its prompt, so anything you can describe in plain language works — tool calls, shell commands, sending messages, summarizing files. #### Step 2: Create the hook ```text ~/.hermes/hooks/boot-md/ ├── HOOK.yaml └── handler.py ``` /.hermes/hooks/boot-md/HOOK.yaml ```yaml name: boot-md description: Run ~/.hermes/BOOT.md on gateway startup events: - gateway:startup ``` /.hermes/hooks/boot-md/handler.py ```python """Run ~/.hermes/BOOT.md on every gateway startup.""" import logging import threading from pathlib import Path logger = logging.getLogger("hooks.boot-md") BOOT_FILE = Path.home() / ".hermes" / "BOOT.md" def _build_prompt(content: str) -> str: return ( "You are running a startup boot checklist. Follow the instructions " "below exactly.\n\n" "---\n" f"{content}\n" "---\n\n" "Execute each instruction. Use the send_message tool to deliver any " "messages to platforms like Discord or Slack.\n" "If nothing needs attention and there is nothing to report, reply " "with ONLY: [SILENT]" ) def _run_boot_agent(content: str) -> None: """Spawn a one-shot agent and execute the checklist. Uses the gateway's resolved model and runtime credentials so this works against custom endpoints, aggregators, and OAuth-based providers alike. """ try: from gateway.run import _resolve_gateway_model, _resolve_runtime_agent_kwargs from run_agent import AIAgent agent = AIAgent( model=_resolve_gateway_model(), _resolve_runtime_agent_kwargs(), platform="gateway", quiet_mode=True, skip_context_files=True, skip_memory=True, max_iterations=20, ) result = agent.run_conversation(_build_prompt(content)) response = result.get("final_response", "") if response and "[SILENT]" not in response: logger.info("boot-md completed: %s", response[:200]) else: logger.info("boot-md completed (nothing to report)") except Exception as e: logger.error("boot-md agent failed: %s", e) async def handle(event_type: str, context: dict) -> None: if not BOOT_FILE.exists(): return content = BOOT_FILE.read_text(encoding="utf-8").strip() if not content: return logger.info("Running BOOT.md (%d chars)", len(content)) # Background thread so gateway startup isn't blocked on a full agent turn. thread = threading.Thread( target=_run_boot_agent, args=(content,), name="boot-md", daemon=True, ) thread.start() ``` The two key lines: - _resolve_gateway_model()`reads the gateway's currently-configured model. -`_resolve_runtime_agent_kwargs()`resolves provider credentials the same way a normal gateway turn does — including API keys, base URLs, OAuth tokens, and credential pools. Without these, a bare`AIAgent()falls back to built-in defaults and will 401 against any non-default endpoint. #### Step 3: Test it Restart the gateway: ```bash hermes gateway restart ``` Watch the logs: ```bash hermes logs --follow --level INFO | grep boot-md ``` You should seeRunning BOOT.md (N chars)`followed by either`boot-md completed: …`(summary of what the agent did) or`boot-md completed (nothing to report)`when the agent replied`[SILENT]`. Delete` /.hermes/BOOT.md`to disable the checklist — the hook stays loaded but silently skips when the file isn't there. #### Extending the pattern - Schedule-aware checklists: key off`datetime.now().weekday() `inside BOOT.md's instructions ("if it's Monday, also check the weekly deploy log"). The instructions are free-form text, so anything the agent can reason about is fair game. - Multiple checklists: point the hook at a different file (`STARTUP.md`,` MORNING.md`, etc.) and register separate hook directories for each. - Non-agent variant: if you don't need a full agent loop, skip` AIAgent`entirely and have the handler post a fixed notification directly via`httpx. Cheaper, faster, and has no provider dependency. #### Why this isn't a built-in An earlier version of Hermes shipped this as a built-in hook and silently spawned an agent with bare defaults on every gateway boot. That surprised users with custom endpoints and made the feature invisible to users who didn't know it was running. Keeping it as a documented pattern — built by you, in your hooks directory — means you see exactly what it does and opt in by writing the files. ### How It Works 1. On gateway startup, HookRegistry.discover_and_load()`scans`/.hermes/hooks/`2. Each subdirectory with`HOOK.yaml`+`handler.py`is loaded dynamically 3. Handlers are registered for their declared events 4. At each lifecycle point,`hooks.emit()`fires all matching handlers 5. Errors in any handler are caught and logged — a broken hook never crashes the agent :::info Gateway hooks only fire in the gateway (Telegram, Discord, Slack, WhatsApp, Teams). The CLI does not load gateway hooks. For hooks that work everywhere, use [plugin hooks](#plugin-hooks). ::: ## Plugin Hooks [Plugins](/user-guide/features/plugins) can register hooks that fire in both CLI and gateway sessions. These are registered programmatically via`ctx.register_hook()`in your plugin's`register()function. For plugin packaging and registration details, see the [Plugins guide](/docs/user-guide/features/plugins). ```python def register(ctx): ctx.register_hook("pre_tool_call", my_tool_observer) ctx.register_hook("post_tool_call", my_tool_logger) ctx.register_hook("pre_llm_call", my_memory_callback) ctx.register_hook("post_llm_call", my_sync_callback) ctx.register_hook("on_session_start", my_init_callback) ctx.register_hook("on_session_end", my_cleanup_callback) ``` General rules for all hooks: - Callbacks receive keyword arguments. Always acceptkwargs `for forward compatibility — new parameters may be added in future versions without breaking your plugin. - If a callback crashes, it's logged and skipped. Other hooks and the agent continue normally. A misbehaving plugin can never break the agent. - Two hooks' return values affect behavior: [`pre_tool_call`](#pre_tool_call) can block the tool, and [`pre_llm_call`](#pre_llm_call) can inject context into the LLM call. All other hooks are fire-and-forget observers. - Observer callbacks receive` telemetry_schema_version`automatically. When present,`turn_id`,` api_request_id`,` task_id`,` session_id`, and` api_call_count`are separate correlation fields. Treat`api_request_id `as an opaque identifier; do not parse its string format. ### Quick reference | Hook | Fires when | Returns | |------|-----------|---------| | [`pre_tool_call`](#pre_tool_call) | Before any tool executes |` {“action”: “block”, “message”: str} `to veto the call | | [`post_tool_call`](#post_tool_call) | After any tool returns | ignored | | [`pre_llm_call`](#pre_llm_call) | Once per turn, before the tool-calling loop |` {“context”: str} `to prepend context to the user message | | [`post_llm_call`](#post_llm_call) | Once per turn, after the tool-calling loop | ignored | | [`on_session_start`](#on_session_start) | New session created (first turn only) | ignored | | [`on_session_end`](#on_session_end) | Session ends | ignored | | [`on_session_finalize`](#on_session_finalize) | CLI/gateway tears down an active session (flush, save, stats) | ignored | | [`on_session_reset`](#on_session_reset) | Gateway swaps in a fresh session key (e.g.` /new`,` /reset`) | ignored | | [`subagent_stop`](#subagent_stop) | A` delegate_task `child has exited | ignored | | [`pre_gateway_dispatch`](#pre_gateway_dispatch) | Gateway received a user message, before auth + dispatch |` {“action”: “skip” | “rewrite” | “allow”, …} `to influence flow | | [`pre_approval_request`](#pre_approval_request) | Dangerous command needs user approval, before the prompt/notification is sent | ignored | | [`post_approval_response`](#post_approval_response) | User responded to an approval prompt (or it timed out) | ignored | | [`transform_tool_result`](#transform_tool_result) | After any tool returns, before the result is handed back to the model |` str`to replace the result,`None `to leave unchanged | | [`transform_terminal_output`](#transform_terminal_output) | Inside the` terminal`tool, before truncation/ANSI-strip/redact |`str`to replace the raw output,`None `to leave unchanged | | [`transform_llm_output`](#transform_llm_output) | After the tool-calling loop completes, before the final response is delivered |` str`to replace the response text,`None`/empty to leave unchanged | --- ###` pre_tool_callFires immediately before every tool execution — built-in tools and plugin tools alike. Callback signature: ```python def my_callback(tool_name: str, args: dict, task_id: str, kwargs): ``` | Parameter | Type | Description | |-----------|------|-------------| |tool_name`|`str`| Name of the tool about to execute (e.g.`“terminal”`,` “web_search”`,` “read_file”`) | |` args`|`dict`| The arguments the model passed to the tool | |`task_id`|`str`| Session/task identifier. Empty string if not set. | Fires: In`model_tools.py`, inside` handle_function_call(), before the tool's handler runs. Fires once per tool call — if the model calls 3 tools in parallel, this fires 3 times. Return value — veto the call: ```python return {"action": "block", "message": "Reason the tool call was blocked"} ``` The agent short-circuits the tool with messageas the error returned to the model. The first matching block directive wins (Python plugins registered first, then shell hooks). Any other return value is ignored, so existing observer-only callbacks keep working unchanged. Use cases: Logging, audit trails, tool call counters, blocking dangerous operations, rate limiting, per-user policy enforcement. Example — tool call audit log: ```python import json, logging from datetime import datetime logger = logging.getLogger(name) def audit_tool_call(tool_name, args, task_id, kwargs): logger.info("TOOL_CALL session=%s tool=%s args=%s", task_id, tool_name, json.dumps(args)[:200]) def register(ctx): ctx.register_hook("pre_tool_call", audit_tool_call) ``` Example — warn on dangerous tools: ```python DANGEROUS = {"terminal", "write_file", "patch"} def warn_dangerous(tool_name, kwargs): if tool_name in DANGEROUS: print(f"⚠ Executing potentially dangerous tool: {tool_name}") def register(ctx): ctx.register_hook("pre_tool_call", warn_dangerous) ``` --- ###post_tool_callFires immediately after every tool execution returns. Callback signature: ```python def my_callback(tool_name: str, args: dict, result: str, task_id: str, duration_ms: int, kwargs): ``` | Parameter | Type | Description | |-----------|------|-------------| |tool_name`|`str`| Name of the tool that just executed | |`args`|`dict`| The arguments the model passed to the tool | |`result`|`str`| The tool's return value (always a JSON string) | |`task_id`|`str`| Session/task identifier. Empty string if not set. | |`duration_ms`|`int`| How long the tool's dispatch took, in milliseconds (measured with`time.monotonic()`around`registry.dispatch()`). | Fires: In` model_tools.py`, inside` handle_function_call()`, after the tool's handler returns. Fires once per tool call. Does not fire if the tool raised an unhandled exception (the error is caught and returned as an error JSON string instead, and` post_tool_call`fires with that error string as`result). Return value: Ignored. Use cases: Logging tool results, metrics collection, tracking tool success/failure rates, latency dashboards, per-tool budget alerts, sending notifications when specific tools complete. Example — track tool usage metrics: ```python from collections import Counter, defaultdict import json _tool_counts = Counter() _error_counts = Counter() _latency_ms = defaultdict(list) def track_metrics(tool_name, result, duration_ms=0, kwargs): _tool_counts[tool_name] += 1 _latency_ms[tool_name].append(duration_ms) try: parsed = json.loads(result) if "error" in parsed: _error_counts[tool_name] += 1 except (json.JSONDecodeError, TypeError): pass def register(ctx): ctx.register_hook("post_tool_call", track_metrics) ``` --- ### pre_llm_callFires once per turn, before the tool-calling loop begins. This is the only hook whose return value is used — it can inject context into the current turn's user message. Callback signature: ```python def my_callback(session_id: str, user_message: str, conversation_history: list, is_first_turn: bool, model: str, platform: str, kwargs): ``` | Parameter | Type | Description | |-----------|------|-------------| |session_id`|`str`| Unique identifier for the current session | |`user_message`|`str`| The user's original message for this turn (before any skill injection) | |`conversation_history`|`list`| Copy of the full message list (OpenAI format:`[{“role”: “user”, “content”: “…”}]`) | |` is_first_turn`|`bool`|`True`if this is the first turn of a new session,`False`on subsequent turns | |`model`|`str`| The model identifier (e.g.`“anthropic/claude-sonnet-4.6”`) | |` platform`|`str`| Where the session is running:`“cli”`,` “telegram”`,` “discord”`, etc. | Fires: In` run_agent.py`, inside` run_conversation()`, after context compression but before the main` while`loop. Fires once per`run_conversation()`call (i.e. once per user turn), not once per API call within the tool loop. Return value: If the callback returns a dict with a`“context”`key, or a plain non-empty string, the text is appended to the current turn's user message. Return`Nonefor no injection. ```python # Inject context return {"context": "Recalled memories:\n- User likes Python\n- Working on hermes-agent"} # Plain string (equivalent) return "Recalled memories:\n- User likes Python" # No injection return None ``` Where context is injected: Always the user message, never the system prompt. This preserves the prompt cache — the system prompt stays identical across turns, so cached tokens are reused. The system prompt is Hermes's territory (model guidance, tool enforcement, personality, skills). Plugins contribute context alongside the user's input. All injected context is ephemeral — added at API call time only. The original user message in the conversation history is never mutated, and nothing is persisted to the session database. When multiple plugins return context, their outputs are joined with double newlines in plugin discovery order (alphabetical by directory name). Use cases: Memory recall, RAG context injection, guardrails, per-turn analytics. Example — memory recall: ```python import httpx MEMORY_API = "https://your-memory-api.example.com" def recall(session_id, user_message, is_first_turn, kwargs): try: resp = httpx.post(f"{MEMORY_API}/recall", json={ "session_id": session_id, "query": user_message, }, timeout=3) memories = resp.json().get("results", []) if not memories: return None text = "Recalled context:\n" + "\n".join(f"- {m['text']}" for m in memories) return {"context": text} except Exception: return None def register(ctx): ctx.register_hook("pre_llm_call", recall) ``` Example — guardrails: ```python POLICY = "Never execute commands that delete files without explicit user confirmation." def guardrails(kwargs): return {"context": POLICY} def register(ctx): ctx.register_hook("pre_llm_call", guardrails) ``` --- ###post_llm_callFires once per turn, after the tool-calling loop completes and the agent has produced a final response. Only fires on successful turns — does not fire if the turn was interrupted. Callback signature: ```python def my_callback(session_id: str, user_message: str, assistant_response: str, conversation_history: list, model: str, platform: str, kwargs): ``` | Parameter | Type | Description | |-----------|------|-------------| |session_id`|`str`| Unique identifier for the current session | |`user_message`|`str`| The user's original message for this turn | |`assistant_response`|`str`| The agent's final text response for this turn | |`conversation_history`|`list`| Copy of the full message list after the turn completed | |`model`|`str`| The model identifier | |`platform`|`str`| Where the session is running | Fires: In`run_agent.py`, inside` run_conversation()`, after the tool loop exits with a final response. Guarded by` if final_response and not interrupted— so it does not fire when the user interrupts mid-turn or the agent hits the iteration limit without producing a response. Return value: Ignored. Use cases: Syncing conversation data to an external memory system, computing response quality metrics, logging turn summaries, triggering follow-up actions. Example — sync to external memory: ```python import httpx MEMORY_API = "https://your-memory-api.example.com" def sync_memory(session_id, user_message, assistant_response, kwargs): try: httpx.post(f"{MEMORY_API}/store", json={ "session_id": session_id, "user": user_message, "assistant": assistant_response, }, timeout=5) except Exception: pass # best-effort def register(ctx): ctx.register_hook("post_llm_call", sync_memory) ``` Example — track response lengths: ```python import logging logger = logging.getLogger(name) def log_response_length(session_id, assistant_response, model, kwargs): logger.info("RESPONSE session=%s model=%s chars=%d", session_id, model, len(assistant_response or "")) def register(ctx): ctx.register_hook("post_llm_call", log_response_length) ``` --- ###on_session_startFires once when a brand-new session is created. Does not fire on session continuation (when the user sends a second message in an existing session). Callback signature: ```python def my_callback(session_id: str, model: str, platform: str, kwargs): ``` | Parameter | Type | Description | |-----------|------|-------------| |session_id`|`str`| Unique identifier for the new session | |`model`|`str`| The model identifier | |`platform`|`str`| Where the session is running | Fires: In`run_agent.py`, inside` run_conversation()`, during the first turn of a new session — specifically after the system prompt is built but before the tool loop starts. The check is` if not conversation_history(no prior messages = new session). Return value: Ignored. Use cases: Initializing session-scoped state, warming caches, registering the session with an external service, logging session starts. Example — initialize a session cache: ```python _session_caches = {} def init_session(session_id, model, platform, kwargs): _session_caches[session_id] = { "model": model, "platform": platform, "tool_calls": 0, "started": import("datetime").datetime.now().isoformat(), } def register(ctx): ctx.register_hook("on_session_start", init_session) ``` --- ###on_session_end`Fires at the very end of every`run_conversation()call, regardless of outcome. Also fires from the CLI's exit handler if the agent was mid-turn when the user quit. Callback signature: ```python def my_callback(session_id: str, completed: bool, interrupted: bool, model: str, platform: str, kwargs): ``` | Parameter | Type | Description | |-----------|------|-------------| |session_id`|`str`| Unique identifier for the session | |`completed`|`bool`|`True`if the agent produced a final response,`False`otherwise | |`interrupted`|`bool`|`True`if the turn was interrupted (user sent new message,`/stop`, or quit) | |` model`|`str`| The model identifier | |`platform`|`str `| Where the session is running | Fires: In two places: 1. `run_agent.py` — at the end of every` run_conversation() `call, after all cleanup. Always fires, even if the turn errored. 2. `cli.py` — in the CLI's atexit handler, but only if the agent was mid-turn (`_agent_running=True`) when the exit occurred. This catches Ctrl+C and` /exit`during processing. In this case,`completed=False`and`interrupted=True`. Return value: Ignored. Use cases: Flushing buffers, closing connections, persisting session state, logging session duration, cleanup of resources initialized in` on_session_start. Example — flush and cleanup: ```python _session_caches = {} def cleanup_session(session_id, completed, interrupted, kwargs): cache = _session_caches.pop(session_id, None) if cache: # Flush accumulated data to disk or external service status = "completed" if completed else ("interrupted" if interrupted else "failed") print(f"Session {session_id} ended: {status}, {cache['tool_calls']} tool calls") def register(ctx): ctx.register_hook("on_session_end", cleanup_session) ``` Example — session duration tracking: ```python import time, logging logger = logging.getLogger(name) _start_times = {} def on_start(session_id, kwargs): _start_times[session_id] = time.time() def on_end(session_id, completed, interrupted, kwargs): start = _start_times.pop(session_id, None) if start: duration = time.time() - start logger.info("SESSION_DURATION session=%s seconds=%.1f completed=%s interrupted=%s", session_id, duration, completed, interrupted) def register(ctx): ctx.register_hook("on_session_start", on_start) ctx.register_hook("on_session_end", on_end) ``` --- ### on_session_finalize`Fires when the CLI or gateway tears down an active session — for example, when the user runs`/new, the gateway GC'd an idle session, or the CLI quit with an active agent. This is the last chance to flush state tied to the outgoing session before its identity is gone. Callback signature: ```python def my_callback(session_id: str | None, platform: str, kwargs): ``` | Parameter | Type | Description | |-----------|------|-------------| | session_id`|`str`or`None`| The outgoing session ID. May be`None`if no active session existed. | |`platform`|`str`|`“cli” `or the messaging platform name (`“telegram”`,` “discord”`, etc.). | Fires: In` cli.py`(on`/new`/ CLI exit) and`gateway/run.py`(when a session is reset or GC'd). Always paired with`on_session_reset`on the gateway side. Return value: Ignored. Use cases: Persist final session metrics before the session ID is discarded, close per-session resources, emit a final telemetry event, drain queued writes. --- ###`on_session_reset`Fires when the gateway swaps in a new session key for an active chat — the user invoked`/new`,` /reset`,` /clear`, or the adapter picked a fresh session after an idle window. This lets plugins react to the fact that conversation state has been wiped without waiting for the next` on_session_start. Callback signature: ```python def my_callback(session_id: str, platform: str, kwargs): ``` | Parameter | Type | Description | |-----------|------|-------------| | session_id`|`str`| The new session's ID (already rotated to the fresh value). | |`platform`|`str`| The messaging platform name. | Fires: In`gateway/run.py`, immediately after the new session key is allocated but before the next inbound message is processed. On the gateway, the order is:` on_session_finalize(old_id)`→ swap →`on_session_reset(new_id)`→`on_session_start(new_id)`on the first inbound turn. Return value: Ignored. Use cases: Reset per-session caches keyed by`session_id`, emit "session rotated" analytics, prime a fresh state bucket. --- See the [Build a Plugin guide](/guides/build-a-hermes-plugin) for the full walkthrough including tool schemas, handlers, and advanced hook patterns. --- ###` subagent_stop`Fires once per child agent after`delegate_taskfinishes. Whether you delegated a single task or a batch of three, this hook fires once for each child, serialised on the parent thread. Callback signature: ```python def my_callback(parent_session_id: str, child_role: str | None, child_summary: str | None, child_status: str, duration_ms: int, kwargs): ``` | Parameter | Type | Description | |-----------|------|-------------| |parent_session_id`|`str`| Session ID of the delegating parent agent | |`child_role`|`str | None `| Orchestrator role tag set on the child (`None`if the feature isn't enabled) | |`child_summary`|`str | None`| The final response the child returned to the parent | |`child_status`|`str`|`“completed”`,` “failed”`,` “interrupted”`, or` “error”`| |`duration_ms`|`int`| Wall-clock time spent running the child, in milliseconds | Fires: In`tools/delegate_tool.py`, after` ThreadPoolExecutor.as_completed()drains all child futures. Firing is marshalled to the parent thread so hook authors don't have to reason about concurrent callback execution. Return value: Ignored. Use cases: Logging orchestration activity, accumulating child durations for billing, writing post-delegation audit records. Example — log orchestrator activity: ```python import logging logger = logging.getLogger(name) def log_subagent(parent_session_id, child_role, child_status, duration_ms, kwargs): logger.info( "SUBAGENT parent=%s role=%s status=%s duration_ms=%d", parent_session_id, child_role, child_status, duration_ms, ) def register(ctx): ctx.register_hook("subagent_stop", log_subagent) ``` :::info With heavy delegation (e.g. orchestrator roles × 5 leaves × nested depth),subagent_stop`fires many times per turn. Keep your callback fast; push expensive work to a background queue. ::: --- ###`pre_gateway_dispatch`Fires once per incoming`MessageEvent in the gateway, after the internal-event guard but before auth/pairing and agent dispatch. This is the interception point for gateway-level message-flow policies (listen-only windows, human handover, per-chat routing, etc.) that don't fit cleanly into any single platform adapter. Callback signature: ```python def my_callback(event, gateway, session_store, kwargs): ``` | Parameter | Type | Description | |-----------|------|-------------| | event`|`MessageEvent`| The normalized inbound message (has`.text`,` .source`,` .message_id`,` .internal`, etc.). | |` gateway`|`GatewayRunner`| The active gateway runner, so plugins can call`gateway.adapters[platform].send(…)`for side-channel replies (owner notifications, etc.). | |`session_store`|`SessionStore`| For silent transcript ingestion via`session_store.append_to_transcript(…)`. | Fires: In` gateway/run.py`, inside` GatewayRunner._handle_message()`, immediately after` is_internal`is computed. Internal events skip the hook entirely (they are system-generated — background-process completions, etc. — and must not be gate-kept by user-facing policy). Return value:`None`or a dict. The first recognized action dict wins; remaining plugin results are ignored. Exceptions in plugin callbacks are caught and logged; the gateway always falls through to normal dispatch on error. | Return | Effect | |--------|--------| |`{“action”: “skip”, “reason”: “…”}`| Drop the message — no agent reply, no pairing flow, no auth. Plugin is assumed to have handled it (e.g. silent-ingested into the transcript). | |`{“action”: “rewrite”, “text”: “new text”}`| Replace`event.text`, then continue normal dispatch with the modified event. Useful for collapsing buffered ambient messages into a single prompt. | |` {“action”: “allow”}`/`None| Normal dispatch — runs the full auth / pairing / agent-loop chain. | Use cases: Listen-only group chats (only respond when tagged; buffer ambient messages into context); human handover (silent-ingest customer messages while owner handles the chat manually); per-profile rate limiting; policy-driven routing. Example — drop unauthorized DMs silently without triggering the pairing code: ```python def deny_unauthorized_dms(event, kwargs): src = event.source if src.chat_type == "dm" and not _is_approved_user(src.user_id): return {"action": "skip", "reason": "unauthorized-dm"} return None def register(ctx): ctx.register_hook("pre_gateway_dispatch", deny_unauthorized_dms) ``` Example — rewrite an ambient-message buffer into a single prompt on mention: ```python _buffers = {} def buffer_or_rewrite(event, kwargs): key = (event.source.platform, event.source.chat_id) buf = _buffers.setdefault(key, []) if _bot_mentioned(event.text): combined = "\n".join(buf + [event.text]) buf.clear() return {"action": "rewrite", "text": combined} buf.append(event.text) return {"action": "skip", "reason": "ambient-buffered"} def register(ctx): ctx.register_hook("pre_gateway_dispatch", buffer_or_rewrite) ``` --- ###pre_approval_requestFires immediately before an approval request is shown to the user — covers every surface: interactive CLI, the Ink TUI, gateway platforms (Telegram, Discord, Slack, WhatsApp, Matrix, etc.), and ACP clients (VS Code, Zed, JetBrains). This is the right place to wire a custom notifier — for example, a macOS menu-bar app that pops an allow/deny notification, or an audit log that records every approval request with context. Callback signature: ```python def my_callback( command: str, description: str, pattern_key: str, pattern_keys: list[str], session_key: str, surface: str, kwargs, ): ``` | Parameter | Type | Description | |-----------|------|-------------| |command`|`str`| The shell command awaiting approval | |`description`|`str`| Human-readable reason(s) the command is flagged (combined when multiple patterns match) | |`pattern_key`|`str`| Primary pattern key that triggered the approval (e.g.`“rm_rf”`,` “sudo”`) | |` pattern_keys`|`list[str]`| All pattern keys that matched | |`session_key`|`str`| Session identifier, useful for scoping notifications per-chat | |`surface`|`str`|`“cli”`for interactive CLI/TUI prompts,`“gateway” `for async platform approvals | Return value: ignored. Hooks here are observer-only; they cannot veto or pre-answer the approval. Use [`pre_tool_call](#pre_tool_call) to block a tool before it reaches the approval system. Use cases: Desktop notifications, push alerts, audit logging, Slack webhooks, escalation routing, metrics. Example — desktop notification on macOS: ```python import subprocess def notify_approval(command, description, session_key, kwargs): title = "Hermes needs approval" body = f"{description}: {command[:80]}" subprocess.Popen([ "osascript", "-e", f'display notification "{body}" with title "{title}"', ]) def register(ctx): ctx.register_hook("pre_approval_request", notify_approval) ``` --- ### post_approval_responseFires after the user responds to an approval prompt (or the prompt times out). Callback signature: ```python def my_callback( command: str, description: str, pattern_key: str, pattern_keys: list[str], session_key: str, surface: str, choice: str, kwargs, ): ``` Same kwargs aspre_approval_request`, plus: | Parameter | Type | Description | |-----------|------|-------------| |` choice`|`str`| One of`“once”`,` “session”`,` “always”`,` “deny”`, or` “timeout”| Return value: ignored. Use cases: Close the matching desktop notification, record the final decision in an audit log, update metrics, roll forward a rate limiter. ```python def log_decision(command, choice, session_key, kwargs): logger.info("approval %s: %s for session %s", choice, command[:60], session_key) def register(ctx): ctx.register_hook("post_approval_response", log_decision) ``` --- ###transform_tool_resultFires after a tool returns and before the result is appended to the conversation. Lets a plugin rewrite ANY tool's result string — not just terminal output — before the model sees it. Callback signature: ```python def my_callback( tool_name: str, arguments: dict, result: str, task_id: str | None, kwargs, ) -> str | None: ``` | Parameter | Type | Description | |-----------|------|-------------| |tool_name`|`str `| Tool that produced the result (`read_file`,` web_extract`,` delegate_task`, …). | |` arguments`|`dict`| Arguments the model called the tool with. | |`result`|`str`| The tool's raw result string, post-truncation and post-ANSI-strip. | |`task_id`|`str | None`| Task/session ID when running inside RL/benchmark environments. | Return value:`str`to replace the result (the returned string is what the model sees),`None`to leave it unchanged. Use cases: Redact organization-specific PII from`web_extract`output, wrap long JSON tool responses in a summary header, inject retrieval-augmented hints into`read_file`results, rewrite`delegate_tasksubagent reports into a project-specific schema. ```python import re SECRET = re.compile(r"sk-[A-Za-z0-9]{32,}") def redact_secrets(tool_name, result, kwargs): if SECRET.search(result): return SECRET.sub("[REDACTED]", result) return None def register(ctx): ctx.register_hook("transform_tool_result", redact_secrets) ``` Applies to every tool. For terminal-only rewriting seetransform_terminal_output`below — it's narrower and runs earlier in the pipeline (pre-truncation, pre-redaction). --- ###`transform_terminal_output`Fires inside the`terminaltool's foreground-output pipeline, before the default 50 KB truncation, ANSI strip, and secret redaction. Lets plugins rewrite the raw stdout/stderr of a shell command before any downstream processing touches it. Callback signature: ```python def my_callback( command: str, output: str, exit_code: int, cwd: str, task_id: str | None, kwargs, ) -> str | None: ``` | Parameter | Type | Description | |-----------|------|-------------| |command`|`str`| The shell command that produced the output. | |`output`|`str`| Raw combined stdout/stderr (may be very large — truncation happens after the hook). | |`exit_code`|`int`| Process exit code. | |`cwd`|`str`| Working directory the command ran in. | Return value:`str`to replace the output,`None `to leave it unchanged. Use cases: Inject summaries for commands that produce massive output (`du -ah`,` find`,` tree), tag output with a project-specific marker so downstream hooks know how to handle it, strip timing noise that flaps between runs and defeats prompt caching. ```python def summarize_find(command, output, kwargs): if command.startswith("find ") and len(output) > 50_000: lines = output.count("\n") head = "\n".join(output.splitlines()[:40]) return f"{head}\n\n[summary: {lines} paths total, showing first 40]" return None def register(ctx): ctx.register_hook("transform_terminal_output", summarize_find) ``` Pairs well with transform_tool_result`(which covers every other tool). --- ###`transform_llm_outputFires once per turn after the tool-calling loop completes and the model has produced a final response, before that response is delivered to the user (CLI, gateway, or programmatic caller). Lets a plugin rewrite the assistant's final text using classical-programming methods — no extra inference tokens burned on SOUL flavor text or a skill-driven transform. Callback signature: ```python def my_callback( response_text: str, session_id: str, model: str, platform: str, kwargs, ) -> str | None: ``` | Parameter | Type | Description | |-----------|------|-------------| |response_text`|`str`| The assistant's final response text for this turn. | |`session_id`|`str`| Session ID for this conversation (may be empty for one-shot runs). | |`model`|`str`| Model name that produced the response (e.g.`anthropic/claude-sonnet-4.6`). | |` platform`|`str `| Delivery platform (`cli`,` telegram`,` discord`, …; empty when unset). | Return value: Non-empty` str`to replace the response text,`None`or empty string to leave it unchanged. First non-empty string wins when multiple plugins register — mirroring`transform_tool_result. Use cases: Apply a personality/vocabulary transform (pirate-speak, Spongebob), redact user-specific identifiers from the final text, append a project-specific signature footer, enforce a house style guide without burning tokens on SOUL instructions. ```python import os, re def spongebob(response_text, kwargs): if os.environ.get("SPONGEBOB_MODE") != "on": return None # pass through unchanged return re.sub(r"!", "!! Tartar sauce!", response_text) def register(ctx): ctx.register_hook("transform_llm_output", spongebob) ``` The hook is guarded on a non-empty, non-interrupted response — it will not fire on stop-button interrupts or empty turns. Exceptions are logged as warnings and do not break agent execution. --- ## Shell Hooks Declare shell-script hooks in your cli-config.yaml`and Hermes will run them as subprocesses whenever the corresponding plugin-hook event fires — in both CLI and gateway sessions. No Python plugin authoring required. Use shell hooks when you want a drop-in, single-file script (Bash, Python, anything with a shebang) to: - Block a tool call — reject dangerous`terminal`commands, enforce per-directory policies, require approval for destructive`write_file`/`patch`operations. - Run after a tool call — auto-format Python or TypeScript files that the agent just wrote, log API calls, trigger a CI workflow. - Inject context into the next LLM turn — prepend`git status `output, the current weekday, or retrieved documents to the user message (see [`pre_llm_call`](#pre_llm_call)). - Observe lifecycle events** — write a log line when a subagent completes (`subagent_stop`) or a session starts (`on_session_start`). Shell hooks are registered by calling` agent.shell_hooks.register_from_config(cfg) `at both CLI startup (`hermes_cli/main.py`) and gateway startup (`gateway/run.py`). They compose naturally with Python plugin hooks — both flow through the same dispatcher. ### Comparison at a glance | Dimension | Shell hooks | [Plugin hooks](#plugin-hooks) | [Gateway hooks](#gateway-event-hooks) | |-----------|-------------|-------------------------------|---------------------------------------| | Declared in |` hooks:`block in`/.hermes/config.yaml`|`register()`in a`plugin.yaml`plugin |`HOOK.yaml`+`handler.py`directory | | Lives under |`/.hermes/agent-hooks/`(by convention) |`/.hermes/plugins//`|`/.hermes/hooks//`| | Language | Any (Bash, Python, Go binary, …) | Python only | Python only | | Runs in | CLI + Gateway | CLI + Gateway | Gateway only | | Events |`VALID_HOOKS`(incl.`subagent_stop`) |` VALID_HOOKS `| Gateway lifecycle (`gateway:startup`,` agent:`,` command:`) | | Can block a tool call | Yes (`pre_tool_call`) | Yes (`pre_tool_call`) | No | | Can inject LLM context | Yes (`pre_llm_call`) | Yes (`pre_llm_call`) | No | | Consent | First-use prompt per` (event, command)pair | Implicit (Python plugin trust) | Implicit (dir trust) | | Inter-process isolation | Yes (subprocess) | No (in-process) | No (in-process) | ### Configuration schema ```yaml hooks: <event_name>: # Must be in VALID_HOOKS - matcher: "<regex>" # Optional; used for pre/post_tool_call only command: "<shell command>" # Required; runs via shlex.split, shell=False timeout: <seconds> # Optional; default 60, capped at 300 hooks_auto_accept: false # See "Consent model" below ``` Event names must be one of the [plugin hook events](#plugin-hooks); typos produce a "Did you mean X?" warning and are skipped. Unknown keys inside a single entry are ignored; missingcommand`is a skip-with-warning.`timeout > 300is clamped with a warning. ### JSON wire protocol Each time the event fires, Hermes spawns a subprocess for every matching hook (matcher permitting), pipes a JSON payload to stdin, and reads stdout back as JSON. stdin — payload the script receives: ```json { "hook_event_name": "pre_tool_call", "tool_name": "terminal", "tool_input": {"command": "rm -rf /"}, "session_id": "sess_abc123", "cwd": "/home/user/project", "extra": {"task_id": "...", "tool_call_id": "..."} } ```tool_name`and`tool_input`are`null `for non-tool events (`pre_llm_call`,` subagent_stop`, session lifecycle). The` extra `dict carries all event-specific kwargs (`user_message`,` conversation_history`,` child_role`,` duration_ms, …). Unserialisable values are stringified rather than omitted. stdout — optional response: ```jsonc // Block a pre_tool_call (both shapes accepted; normalised internally): {"decision": "block", "reason": "Forbidden: rm -rf"} // Claude-Code style {"action": "block", "message": "Forbidden: rm -rf"} // Hermes-canonical // Inject context for pre_llm_call: {"context": "Today is Friday, 2026-04-17"} // Silent no-op — any empty / non-matching output is fine: ``` Malformed JSON, non-zero exit codes, and timeouts log a warning but never abort the agent loop. ### Worked examples #### 1. Auto-format Python files after every write ```yaml # ~/.hermes/config.yaml hooks: post_tool_call: - matcher: "write_file|patch" command: "~/.hermes/agent-hooks/auto-format.sh" ``` ```bash #!/usr/bin/env bash # ~/.hermes/agent-hooks/auto-format.sh payload="$(cat -)" path=$(echo "$payload" | jq -r '.tool_input.path // empty') [[ "$path" == .py ]] && command -v black >/dev/null && black "$path" 2>/dev/null printf '{}\n' ``` The agent's in-context view of the file is not re-read automatically — the reformat only affects the file on disk. Subsequent read_file`calls pick up the formatted version. #### 2. Block destructive`terminalcommands ```yaml hooks: pre_tool_call: - matcher: "terminal" command: "~/.hermes/agent-hooks/block-rm-rf.sh" timeout: 5 ``` ```bash #!/usr/bin/env bash # ~/.hermes/agent-hooks/block-rm-rf.sh payload="$(cat -)" cmd=$(echo "$payload" | jq -r '.tool_input.command // empty') if echo "$cmd" | grep -qE 'rm[[:space:]]+-rf?[[:space:]]+/'; then printf '{"decision": "block", "reason": "blocked: rm -rf / is not permitted"}\n' else printf '{}\n' fi ``` #### 3. Injectgit status`into every turn (Claude-Code`UserPromptSubmitequivalent) ```yaml hooks: pre_llm_call: - command: "~/.hermes/agent-hooks/inject-cwd-context.sh" ``` ```bash #!/usr/bin/env bash # ~/.hermes/agent-hooks/inject-cwd-context.sh cat - >/dev/null # discard stdin payload if status=$(git status --porcelain 2>/dev/null) && [[ -n "$status" ]]; then jq --null-input --arg s "$status" \ '{context: ("Uncommitted changes in cwd:\n" + $s)}' else printf '{}\n' fi ``` Claude Code'sUserPromptSubmit`event is intentionally not a separate Hermes event —`pre_llm_callfires at the same place and already supports context injection. Use it here. #### 4. Log every subagent completion ```yaml hooks: subagent_stop: - command: "~/.hermes/agent-hooks/log-orchestration.sh" ``` ```bash #!/usr/bin/env bash # ~/.hermes/agent-hooks/log-orchestration.sh log=~/.hermes/logs/orchestration.log jq -c '{ts: now, parent: .session_id, extra: .extra}' < /dev/stdin >> "$log" printf '{}\n' ``` ### Consent model Each unique(event, command)`pair prompts the user for approval the first time Hermes sees it, then persists the decision to`/.hermes/shell-hooks-allowlist.json`. Subsequent runs (CLI or gateway) skip the prompt. Three escape hatches bypass the interactive prompt — any one is sufficient: 1.` –accept-hooks`flag on the CLI (e.g.`hermes –accept-hooks chat`) 2.` HERMES_ACCEPT_HOOKS=1`environment variable 3.`hooks_auto_accept: true`in`cli-config.yaml`Non-TTY runs (gateway, cron, CI) need one of these three — otherwise any newly-added hook silently stays un-registered and logs a warning. Script edits are silently trusted. The allowlist keys on the exact command string, not the script's hash, so editing the script on disk does not invalidate consent.`hermes hooks doctor`flags mtime drift so you can spot edits and decide whether to re-approve. ### The`hermes hooks`CLI | Command | What it does | |---------|--------------| |`hermes hooks list`| Dump configured hooks with matcher, timeout, and consent status | |`hermes hooks test [–for-tool X] [–payload-file F]`| Fire every matching hook against a synthetic payload and print the parsed response | |`hermes hooks revoke `| Remove every allowlist entry matching(takes effect on next restart) | |`hermes hooks doctor`| For every configured hook: check exec bit, allowlist status, mtime drift, JSON output validity, and rough execution time | ### Security Shell hooks run with your full user credentials — same trust boundary as a cron entry or a shell alias. Treat the`hooks:`block in`config.yaml`as privileged configuration: - Only reference scripts you wrote or fully reviewed. - Keep scripts inside`/.hermes/agent-hooks/`so the path is easy to audit. - Re-run`hermes hooks doctor`after you pull a shared config to spot newly-added hooks before they register. - If your config.yaml is version-controlled across a team, review PRs that change the`hooks:`section the same way you'd review CI config. ### Ordering and precedence Both Python plugin hooks and shell hooks flow through the same`invoke_hook() `dispatcher. Python plugins are registered first (`discover_and_load()`), shell hooks second (`register_from_config()`), so Python` pre_tool_call`block decisions take precedence in tie cases. The first valid block wins — the aggregator returns as soon as any callback produces`{“action”: “block”, “message”: str} `with a non-empty message. ---  # Batch Processing # Batch Processing Batch processing lets you run the Hermes agent across hundreds or thousands of prompts in parallel, generating structured trajectory data. This is primarily used for training data generation — producing ShareGPT-format trajectories with tool usage statistics that can be used for fine-tuning or evaluation. ## Overview The batch runner (`batch_runner.py) processes a JSONL dataset of prompts, running each through a full agent session with tool access. Each prompt gets its own isolated environment. The output is structured trajectory data with full conversation history, tool call statistics, and reasoning coverage metrics. ## Quick Start ```bash # Basic batch run python batch_runner.py \ --dataset_file=data/prompts.jsonl \ --batch_size=10 \ --run_name=my_first_run \ --model=anthropic/claude-sonnet-4.6 \ --num_workers=4 # Resume an interrupted run python batch_runner.py \ --dataset_file=data/prompts.jsonl \ --batch_size=10 \ --run_name=my_first_run \ --resume # List available toolset distributions python batch_runner.py --list_distributions ``` :::tip Predictable cost at scale Batch runs spin up many concurrent agent sessions, each making model calls and tool calls. A [Nous Portal](/user-guide/features/tool-gateway) subscription bundles model access plus web search, image gen, TTS, and cloud browsers under one bill — useful when you want stable cost-per-trajectory without juggling rate limits across five vendor accounts. Set up with hermes setup –portal`, then point` –model`at a Nous model. ::: ## Dataset Format The input dataset is a JSONL file (one JSON object per line). Each entry must have a`promptfield: ```jsonl {"prompt": "Write a Python function that finds the longest palindromic substring"} {"prompt": "Create a REST API endpoint for user authentication using Flask"} {"prompt": "Debug this error: TypeError: cannot unpack non-iterable NoneType object"} ``` Entries can optionally include: -image`or`docker_image`: A container image to use for this prompt's sandbox (works with Docker, Modal, and Singularity backends) -` cwd`: Working directory override for the task's terminal session ## Configuration Options | Parameter | Default | Description | |-----------|---------|-------------| |` –dataset_file`| (required) | Path to JSONL dataset | |`–batch_size`| (required) | Prompts per batch | |`–run_name`| (required) | Name for this run (used for output dir and checkpointing) | |`–distribution`|`“default”`| Toolset distribution to sample from | |`–model`|`claude-sonnet-4.6`| Model to use | |`–base_url`|`https://openrouter.ai/api/v1`| API base URL | |`–api_key`| (env var) | API key for model | |`–max_turns`|`10`| Maximum tool-calling iterations per prompt | |`–num_workers`|`4`| Parallel worker processes | |`–resume`|`false`| Resume from checkpoint | |`–verbose`|`false`| Enable verbose logging | |`–max_samples`| all | Only process first N samples from dataset | |`–max_tokens`| model default | Maximum tokens per model response | ### Provider Routing (OpenRouter) | Parameter | Description | |-----------|-------------| |`–providers_allowed`| Comma-separated providers to allow (e.g.,`“anthropic,openai”`) | |` –providers_ignored`| Comma-separated providers to ignore (e.g.,`“together,deepinfra”`) | |` –providers_order`| Comma-separated preferred provider order | |`–provider_sort`| Sort by`“price”`,` “throughput”`, or` “latency”`| ### Reasoning Control | Parameter | Description | |-----------|-------------| |`–reasoning_effort`| Effort level:`none`,` minimal`,` low`,` medium`,` high`,` xhigh`| |`–reasoning_disabled`| Completely disable reasoning/thinking tokens | ### Advanced Options | Parameter | Description | |-----------|-------------| |`–ephemeral_system_prompt`| System prompt used during execution but NOT saved to trajectories | |`–log_prefix_chars`| Characters to show in log previews (default: 100) | |`–prefill_messages_file`| Path to JSON file with prefill messages for few-shot priming | ## Toolset Distributions Each prompt gets a randomly sampled set of toolsets from a distribution. This ensures training data covers diverse tool combinations. Use`–list_distributions`to see all available distributions. In the current implementation, distributions assign a probability to each individual toolset. The sampler flips each toolset independently, then guarantees that at least one toolset is enabled. This is different from a hand-authored table of prebuilt combinations. ## Output Format All output goes to`data/<run_name>/: ```text data/my_run/ ├── trajectories.jsonl # Combined final output (all batches merged) ├── batch_0.jsonl # Individual batch results ├── batch_1.jsonl ├── ... ├── checkpoint.json # Resume checkpoint └── statistics.json # Aggregate tool usage stats ``` ### Trajectory Format Each line in trajectories.jsonlis a JSON object: ```json { "prompt_index": 42, "conversations": [ {"from": "human", "value": "Write a function..."}, {"from": "gpt", "value": "I'll create that function...", "tool_calls": [...]}, {"from": "tool", "value": "..."}, {"from": "gpt", "value": "Here's the completed function..."} ], "metadata": { "batch_num": 2, "timestamp": "2026-01-15T10:30:00", "model": "anthropic/claude-sonnet-4.6" }, "completed": true, "partial": false, "api_calls": 3, "toolsets_used": ["terminal", "file"], "tool_stats": { "terminal": {"count": 2, "success": 2, "failure": 0}, "read_file": {"count": 1, "success": 1, "failure": 0} }, "tool_error_counts": { "terminal": 0, "read_file": 0 } } ``` Theconversations`field uses a ShareGPT-like format with`from`and`value`fields. Tool stats are normalized to include all possible tools with zero defaults, ensuring consistent schema across entries for HuggingFace datasets compatibility. ## Checkpointing The batch runner has robust checkpointing for fault tolerance: - Checkpoint file: Saved after each batch completes, tracking which prompt indices are done - Content-based resume: On`–resume`, the runner scans existing batch files and matches completed prompts by their actual text content (not just indices), enabling recovery even if the dataset order changes - Failed prompts: Only successfully completed prompts are marked as done — failed prompts will be retried on resume - Batch merging: On completion, all batch files (including from previous runs) are merged into a single` trajectories.jsonl`### How Resume Works 1. Scan all`batch_.jsonl`files for completed prompts (by content matching) 2. Filter the dataset to exclude already-completed prompts 3. Re-batch the remaining prompts 4. Process only the remaining prompts 5. Merge all batch files (old + new) into final output ## Quality Filtering The batch runner applies automatic quality filtering: - No-reasoning filter: Samples where zero assistant turns contain reasoning (no`<REASONING_SCRATCHPAD>or native thinking tokens) are discarded - Corrupted entry filter: Entries with hallucinated tool names (not in the valid tool list) are filtered out during the final merge - Reasoning statistics: Tracks percentage of turns with/without reasoning across the entire run ## Statistics After completion, the runner prints comprehensive statistics: - Tool usage: Call counts, success/failure rates per tool - Reasoning coverage: Percentage of assistant turns with reasoning - Samples discarded: Count of samples filtered for lacking reasoning - Duration: Total processing time Statistics are also saved tostatistics.jsonfor programmatic analysis. ## Use Cases ### Training Data Generation Generate diverse tool-use trajectories for fine-tuning: ```bash python batch_runner.py \ --dataset_file=data/coding_prompts.jsonl \ --batch_size=20 \ --run_name=coding_v1 \ --model=anthropic/claude-sonnet-4.6 \ --num_workers=8 \ --distribution=default \ --max_turns=15 ``` ### Model Evaluation Evaluate how well a model uses tools across standardized prompts: ```bash python batch_runner.py \ --dataset_file=data/eval_suite.jsonl \ --batch_size=10 \ --run_name=eval_gpt4 \ --model=openai/gpt-4o \ --num_workers=4 \ --max_turns=10 ``` ### Per-Prompt Container Images For benchmarks requiring specific environments, each prompt can specify its own container image: ```jsonl {"prompt": "Install numpy and compute eigenvalues of a 3x3 matrix", "image": "python:3.11-slim"} {"prompt": "Compile this Rust program and run it", "image": "rust:1.75"} {"prompt": "Set up a Node.js Express server", "image": "node:20-alpine", "cwd": "/app"} ``` The batch runner verifies Docker images are accessible before running each prompt. ---  # Voice Mode # Voice Mode Hermes Agent supports full voice interaction across CLI and messaging platforms. Talk to the agent using your microphone, hear spoken replies, and have live voice conversations in Discord voice channels. If you want a practical setup walkthrough with recommended configurations and real usage patterns, see [Use Voice Mode with Hermes](/guides/use-voice-mode-with-hermes). ## Prerequisites Before using voice features, make sure you have: 1. Hermes Agent installed —pip install hermes-agent`(see [Installation](/getting-started/installation)) 2. An LLM provider configured — run`hermes model`or set your preferred provider credentials in`/.hermes/.env`3. A working base setup — run`hermes`to verify the agent responds to text before enabling voice :::tip The`/.hermes/`directory and default`config.yaml`are created automatically the first time you run`hermes`. You only need to create` /.hermes/.env`manually for API keys. ::: :::tip Nous Portal covers both A paid [Nous Portal](/user-guide/features/tool-gateway) subscription supplies the LLM (step 2) and OpenAI TTS via the Tool Gateway — no separate OpenAI key needed. On a fresh install,`hermes setup –portalwires both up at once. ::: ## Overview | Feature | Platform | Description | |---------|----------|-------------| | Interactive Voice | CLI | Press Ctrl+B to record, agent auto-detects silence and responds | | Auto Voice Reply | Telegram, Discord | Agent sends spoken audio alongside text responses | | Voice Channel | Discord | Bot joins VC, listens to users speaking, speaks replies back | ## Requirements ### Python Packages ```bash # CLI voice mode (microphone + audio playback) pip install "hermes-agent[voice]" # Discord + Telegram messaging (includes discord.py[voice] for VC support) pip install "hermes-agent[messaging]" # Premium TTS (ElevenLabs) pip install "hermes-agent[tts-premium]" # Local TTS (NeuTTS, optional) python -m pip install -U neutts[all] # Everything at once pip install "hermes-agent[all]" ``` | Extra | Packages | Required For | |-------|----------|-------------| |voice`|`sounddevice`,` numpy`| CLI voice mode | |`messaging`|`discord.py[voice]`,` python-telegram-bot`,` aiohttp`| Discord & Telegram bots | |`tts-premium`|`elevenlabs`| ElevenLabs TTS provider | Optional local TTS provider: install`neutts`separately with`python -m pip install -U neutts[all]`. On first use it downloads the model automatically. :::info` discord.py[voice]installs PyNaCl (for voice encryption) and opus bindings automatically. This is required for Discord voice channel support. ::: ### System Dependencies ```bash # macOS brew install portaudio ffmpeg opus brew install espeak-ng # for NeuTTS # Ubuntu/Debian sudo apt install portaudio19-dev ffmpeg libopus0 sudo apt install espeak-ng # for NeuTTS ``` | Dependency | Purpose | Required For | |-----------|---------|-------------| | PortAudio | Microphone input and audio playback | CLI voice mode | | ffmpeg | Audio format conversion (MP3 → Opus, PCM → WAV) | All platforms | | Opus | Discord voice codec | Discord voice channels | | espeak-ng | Phonemizer backend | Local NeuTTS provider | ### API Keys Add to/.hermes/.env: ```bash # Speech-to-Text — local provider needs NO key at all # pip install faster-whisper # Free, runs locally, recommended GROQ_API_KEY=your-key # Groq Whisper — fast, free tier (cloud) VOICE_TOOLS_OPENAI_KEY=your-key # OpenAI Whisper — paid (cloud) # Text-to-Speech (optional — Edge TTS and NeuTTS work without any key) ELEVENLABS_API_KEY=* # ElevenLabs — premium quality # VOICE_TOOLS_OPENAI_KEY above also enables OpenAI TTS ``` :::tip If faster-whisper`is installed, voice mode works with zero API keys for STT. The model (~150 MB for`base`) downloads automatically on first use. ::: --- ## CLI Voice Mode Voice mode is available in both the classic CLI (`hermes chat`) and the TUI (`hermes –tui`). Behavior is identical across both — same slash commands, same VAD silence detection, same streaming TTS, same hallucination filter. The TUI additionally forwards crash-forensic logs to` /.hermes/logs/so push-to-talk failures on exotic audio backends can be reported with a full stack trace rather than disappearing silently. ### Quick Start Start the CLI and enable voice mode: ```bash hermes # Start the interactive CLI ``` Then use these commands inside the CLI: ``` /voice Toggle voice mode on/off /voice on Enable voice mode /voice off Disable voice mode /voice tts Toggle TTS output /voice status Show current state ``` ### How It Works 1. Start the CLI withhermes`and enable voice mode with`/voice on`2. Press Ctrl+B — a beep plays (880Hz), recording starts 3. Speak — a live audio level bar shows your input:`● [▁▂▃▅▇▇▅▂] ❯4. Stop speaking — after 3 seconds of silence, recording auto-stops 5. Two beeps play (660Hz) confirming the recording ended 6. Audio is transcribed via Whisper and sent to the agent 7. If TTS is enabled, the agent's reply is spoken aloud 8. Recording automatically restarts — speak again without pressing any key This loop continues until you press Ctrl+B during recording (exits continuous mode) or 3 consecutive recordings detect no speech. :::tip The record key is configurable viavoice.record_key`in`/.hermes/config.yaml`(default:`ctrl+b`). ::: ### Silence Detection Two-stage algorithm detects when you've finished speaking: 1. Speech confirmation — waits for audio above the RMS threshold (200) for at least 0.3s, tolerating brief dips between syllables 2. End detection — once speech is confirmed, triggers after 3.0 seconds of continuous silence If no speech is detected at all for 15 seconds, recording stops automatically. Both` silence_threshold`and`silence_duration`are configurable in`config.yaml`. You can also disable the record start/stop beeps with` voice.beep_enabled: false`. ### Streaming TTS When TTS is enabled, the agent speaks its reply sentence-by-sentence as it generates text — you don't wait for the full response: 1. Buffers text deltas into complete sentences (min 20 chars) 2. Strips markdown formatting and` blocks 3. Generates and plays audio per sentence in real-time ### Hallucination Filter Whisper sometimes generates phantom text from silence or background noise ("Thank you for watching", "Subscribe", etc.). The agent filters these out using a set of 26 known hallucination phrases across multiple languages, plus a regex pattern that catches repetitive variations. --- ## Gateway Voice Reply (Telegram & Discord) If you haven't set up your messaging bots yet, see the platform-specific guides: - [Telegram Setup Guide](../messaging/telegram.md) - [Discord Setup Guide](../messaging/discord.md) Start the gateway to connect to your messaging platforms: ```bash hermes gateway # Start the gateway (connects to configured platforms) hermes gateway setup # Interactive setup wizard for first-time configuration ``` ### Discord: Channels vs DMs The bot supports two interaction modes on Discord: | Mode | How to Talk | Mention Required | Setup | |------|------------|-----------------|-------| | Direct Message (DM) | Open the bot's profile → "Message" | No | Works immediately | | Server Channel | Type in a text channel where the bot is present | Yes (@botname`) | Bot must be invited to the server | DM (recommended for personal use): Just open a DM with the bot and type — no @mention needed. Voice replies and all commands work the same as in channels. Server channels: The bot only responds when you @mention it (e.g.` @hermesbyt4 hello`). Make sure you select the bot user from the mention popup, not the role with the same name. :::tip To disable the mention requirement in server channels, add to` /.hermes/.env: ```bash DISCORD_REQUIRE_MENTION=false ``` Or set specific channels as free-response (no mention needed): ```bash DISCORD_FREE_RESPONSE_CHANNELS=123456789,987654321 ``` ::: ### Commands These work in both Telegram and Discord (DMs and text channels): ``` /voice Toggle voice mode on/off /voice on Voice replies only when you send a voice message /voice tts Voice replies for ALL messages /voice off Disable voice replies /voice status Show current setting ``` ### Modes | Mode | Command | Behavior | |------|---------|----------| | off`|`/voice off`| Text only (default) | |`voice_only`|`/voice on`| Speaks reply only when you send a voice message | |`all`|`/voice tts| Speaks reply to every message | Voice mode setting is persisted across gateway restarts. ### Platform Delivery | Platform | Format | Notes | |----------|--------|-------| | Telegram | Voice bubble (Opus/OGG) | Plays inline in chat. ffmpeg converts MP3 → Opus if needed | | Discord | Native voice bubble (Opus/OGG) | Plays inline like a user voice message. Falls back to file attachment if voice bubble API fails | --- ## Discord Voice Channels The most immersive voice feature: the bot joins a Discord voice channel, listens to users speaking, transcribes their speech, processes through the agent, and speaks the reply back in the voice channel. ### Setup #### 1. Discord Bot Permissions If you already have a Discord bot set up for text (see [Discord Setup Guide](../messaging/discord.md)), you need to add voice permissions. Go to the [Discord Developer Portal](https://discord.com/developers/applications) → your application → Installation → Default Install Settings → Guild Install: Add these permissions to the existing text permissions: | Permission | Purpose | Required | |-----------|---------|----------| | Connect | Join voice channels | Yes | | Speak | Play TTS audio in voice channels | Yes | | Use Voice Activity | Detect when users are speaking | Recommended | Updated Permissions Integer: | Level | Integer | What's Included | |-------|---------|----------------| | Text only |274878286912`| View Channels, Send Messages, Read History, Embeds, Attachments, Threads, Reactions | | Text + Voice |`274881432640| All above + Connect, Speak | Re-invite the bot with the updated permissions URL: ``` https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274881432640 ``` ReplaceYOUR_APP_IDwith your Application ID from the Developer Portal. :::warning Re-inviting the bot to a server it's already in will update its permissions without removing it. You won't lose any data or configuration. ::: #### 2. Privileged Gateway Intents In the [Developer Portal](https://discord.com/developers/applications) → your application → Bot → Privileged Gateway Intents, enable all three: | Intent | Purpose | |--------|---------| | Presence Intent | Detect user online/offline status | | Server Members Intent | Resolve usernames inDISCORD_ALLOWED_USERS`to numeric IDs (conditional) | | Message Content Intent | Read text message content in channels | Message Content Intent is required. Server Members Intent is only needed if your`DISCORD_ALLOWED_USERSlist uses usernames — if you use numeric user IDs, you can leave it OFF. Voice-channel SSRC → user_id mapping comes from Discord's SPEAKING opcode on the voice websocket and does not require the Server Members Intent. #### 3. Opus Codec The Opus codec library must be installed on the machine running the gateway: ```bash # macOS (Homebrew) brew install opus # Ubuntu/Debian sudo apt install libopus0 ``` The bot auto-loads the codec from: - macOS:/opt/homebrew/lib/libopus.dylib`- Linux:`libopus.so.0#### 4. Environment Variables ```bash # ~/.hermes/.env # Discord bot (already configured for text) DISCORD_BOT_TOKEN=your-bot-token DISCORD_ALLOWED_USERS=your-user-id # STT — local provider needs no key (pip install faster-whisper) # GROQ_API_KEY=your-key # Alternative: cloud-based, fast, free tier # TTS — optional. Edge TTS and NeuTTS need no key. # ELEVENLABS_API_KEY=* # Premium quality # VOICE_TOOLS_OPENAI_KEY=* # OpenAI TTS / Whisper ``` ### Start the Gateway ```bash hermes gateway # Start with existing configuration ``` The bot should come online in Discord within a few seconds. ### Commands Use these in the Discord text channel where the bot is present: ``` /voice join Bot joins your current voice channel /voice channel Alias for /voice join /voice leave Bot disconnects from voice channel /voice status Show voice mode and connected channel ``` :::info You must be in a voice channel before running/voice join. The bot joins the same VC you're in. ::: ### How It Works When the bot joins a voice channel, it: 1. Listens to each user's audio stream independently 2. Detects silence — 1.5s of silence after at least 0.5s of speech triggers processing 3. Transcribes the audio via Whisper STT (local, Groq, or OpenAI) 4. Processes through the full agent pipeline (session, tools, memory) 5. Speaks the reply back in the voice channel via TTS ### Text Channel Integration When the bot is in a voice channel: - Transcripts appear in the text channel: [Voice] @user: what you said`- Agent responses are sent as text in the channel AND spoken in the VC - The text channel is the one where`/voice join`was issued ### Echo Prevention The bot automatically pauses its audio listener while playing TTS replies, preventing it from hearing and re-processing its own output. ### Access Control Only users listed in`DISCORD_ALLOWED_USERScan interact via voice. Other users' audio is silently ignored. ```bash # ~/.hermes/.env DISCORD_ALLOWED_USERS=284102345871466496 ``` --- ## Configuration Reference ### config.yaml ```yaml # Voice recording (CLI) voice: record_key: "ctrl+b" # Key to start/stop recording max_recording_seconds: 120 # Maximum recording length auto_tts: false # Auto-enable TTS when voice mode starts beep_enabled: true # Play record start/stop beeps silence_threshold: 200 # RMS level (0-32767) below which counts as silence silence_duration: 3.0 # Seconds of silence before auto-stop # Speech-to-Text stt: enabled: true # set to false to skip auto-transcription — # the gateway still caches the audio file and # passes its path to the agent as part of the # inbound message, useful for custom pipelines # (diarization, alignment, archival, etc.) provider: "local" # "local" (free) | "groq" | "openai" | "mistral" | "xai" local: model: "base" # tiny, base, small, medium, large-v3 # model: "whisper-1" # Legacy: used when provider is not set # Text-to-Speech tts: provider: "edge" # "edge" (free) | "elevenlabs" | "openai" | "neutts" | "minimax" | "mistral" | "gemini" | "xai" | "kittentts" | "piper" edge: voice: "en-US-AriaNeural" # 322 voices, 74 languages elevenlabs: voice_id: "pNInz6obpgDQGcFmaJgB" # Adam model_id: "eleven_multilingual_v2" openai: model: "gpt-4o-mini-tts" voice: "alloy" # alloy, echo, fable, onyx, nova, shimmer base_url: "https://api.openai.com/v1" # optional: override for self-hosted or OpenAI-compatible endpoints neutts: ref_audio: '' ref_text: '' model: neuphonic/neutts-air-q4-gguf device: cpu ``` ### Environment Variables ```bash # Speech-to-Text providers (local needs no key) # pip install faster-whisper # Free local STT — no API key needed GROQ_API_KEY=... # Groq Whisper (fast, free tier) VOICE_TOOLS_OPENAI_KEY=... # OpenAI Whisper (paid) # STT advanced overrides (optional) STT_GROQ_MODEL=whisper-large-v3-turbo # Override default Groq STT model STT_OPENAI_MODEL=whisper-1 # Override default OpenAI STT model GROQ_BASE_URL=https://api.groq.com/openai/v1 # Custom Groq endpoint STT_OPENAI_BASE_URL=https://api.openai.com/v1 # Custom OpenAI STT endpoint # Text-to-Speech providers (Edge TTS and NeuTTS need no key) ELEVENLABS_API_KEY=* # ElevenLabs (premium quality) # VOICE_TOOLS_OPENAI_KEY above also enables OpenAI TTS # Discord voice channel DISCORD_BOT_TOKEN=... DISCORD_ALLOWED_USERS=... ``` ### STT Provider Comparison | Provider | Model | Speed | Quality | Cost | API Key | |----------|-------|-------|---------|------|---------| | Local |base`| Fast (depends on CPU/GPU) | Good | Free | No | | Local |`small`| Medium | Better | Free | No | | Local |`large-v3`| Slow | Best | Free | No | | Groq |`whisper-large-v3-turbo`| Very fast (~0.5s) | Good | Free tier | Yes | | Groq |`whisper-large-v3`| Fast (~1s) | Better | Free tier | Yes | | OpenAI |`whisper-1`| Fast (~1s) | Good | Paid | Yes | | OpenAI |`gpt-4o-transcribe`| Medium (~2s) | Best | Paid | Yes | | Mistral |`voxtral-mini-latest`| Fast | Good | Paid | Yes | | xAI |`grok-stt`| Fast | Good | Paid | Yes | Provider priority (automatic fallback): local > groq > openai ### TTS Provider Comparison | Provider | Quality | Cost | Latency | Key Required | |----------|---------|------|---------|-------------| | Edge TTS | Good | Free | ~1s | No | | ElevenLabs | Excellent | Paid | ~2s | Yes | | OpenAI TTS | Good | Paid | ~1.5s | Yes | | NeuTTS | Good | Free | Depends on CPU/GPU | No | NeuTTS uses the`tts.neuttsconfig block above. --- ## Troubleshooting ### "No audio device found" (CLI) PortAudio is not installed: ```bash brew install portaudio # macOS sudo apt install portaudio19-dev # Ubuntu ``` If you are running Hermes inside Docker on a Linux desktop, the container also needs access to your host audio socket. See the [Docker audio bridge](/user-guide/docker#optional-linux-desktop-audio-bridge) notes for a PulseAudio/PipeWire-compatible setup. ### Bot doesn't respond in Discord server channels The bot requires an @mention by default in server channels. Make sure you: 1. Type@`and select the bot user (with the #discriminator), not the role with the same name 2. Or use DMs instead — no mention needed 3. Or set`DISCORD_REQUIRE_MENTION=false`in`/.hermes/.env`### Bot joins VC but doesn't hear me - Check your Discord user ID is in`DISCORD_ALLOWED_USERS`- Make sure you're not muted in Discord - The bot needs a SPEAKING event from Discord before it can map your audio — start speaking within a few seconds of joining ### Bot hears me but doesn't respond - Verify STT is available: install`faster-whisper`(no key needed) or set`GROQ_API_KEY`/`VOICE_TOOLS_OPENAI_KEY`- Check the LLM model is configured and accessible - Review gateway logs:`tail -f /.hermes/logs/gateway.log`### Bot responds in text but not in voice channel - TTS provider may be failing — check API key and quota - Edge TTS (free, no key) is the default fallback - Check logs for TTS errors ### Whisper returns garbage text The hallucination filter catches most cases automatically. If you're still getting phantom transcripts: - Use a quieter environment - Adjust`silence_thresholdin config (higher = less sensitive) - Try a different STT model ---  # user-guide/features/browser # Browser Automation Hermes Agent includes a full browser automation toolset with multiple backend options: - Browserbase cloud mode via [Browserbase](https://browserbase.com) for managed cloud browsers and anti-bot tooling - Browser Use cloud mode via [Browser Use](https://browser-use.com) as an alternative cloud browser provider - Firecrawl cloud mode via [Firecrawl](https://firecrawl.dev) for cloud browsers with built-in scraping - Camofox local mode via [Camofox](https://github.com/jo-inc/camofox-browser) for local anti-detection browsing (Firefox-based fingerprint spoofing) - Local Chromium-family CDP — connect browser tools to your own Chrome, Brave, Chromium, or Edge instance using/browser connect`- Local browser mode via the`agent-browser`CLI and a local Chromium installation In all modes, the agent can navigate websites, interact with page elements, fill forms, and extract information. ## Overview Pages are represented as accessibility trees (text-based snapshots), making them ideal for LLM agents. Interactive elements get ref IDs (like`@e1`,` @e2) that the agent uses for clicking and typing. Key capabilities: - Multi-provider cloud execution — Browserbase, Browser Use, or Firecrawl — no local browser needed - Local Chromium-family integration — attach to your running Chrome, Brave, Chromium, or Edge browser via CDP for hands-on browsing - Built-in stealth — random fingerprints, CAPTCHA solving, residential proxies (Browserbase) - Session isolation — each task gets its own browser session - Automatic cleanup — inactive sessions are closed after a timeout - Vision analysis — screenshot + AI analysis for visual understanding ## Setup :::tip Nous Subscribers If you have a paid [Nous Portal](https://portal.nousresearch.com) subscription, you can use browser automation through the [Tool Gateway](tool-gateway.md) without any separate API keys. New installs can run hermes setup –portal`to log in and turn on every gateway tool at once; existing installs can pick Nous Subscription as the browser provider via`hermes model`or`hermes tools. ::: ### Browserbase cloud mode To use Browserbase-managed cloud browsers, add: ```bash # Add to ~/.hermes/.env BROWSERBASE_API_KEY=* BROWSERBASE_PROJECT_ID=your-project-id-here ``` Get your credentials at [browserbase.com](https://browserbase.com). ### Browser Use cloud mode To use Browser Use as your cloud browser provider, add: ```bash # Add to ~/.hermes/.env BROWSER_USE_API_KEY=* ``` Get your API key at [browser-use.com](https://browser-use.com). Browser Use provides a cloud browser via its REST API. If both Browserbase and Browser Use credentials are set, Browserbase takes priority. ### Firecrawl cloud mode To use Firecrawl as your cloud browser provider, add: ```bash # Add to ~/.hermes/.env FIRECRAWL_API_KEY=fc-* ``` Get your API key at [firecrawl.dev](https://firecrawl.dev). Then select Firecrawl as your browser provider: ```bash hermes setup tools # → Browser Automation → Firecrawl ``` Optional settings: ```bash # Self-hosted Firecrawl instance (default: https://api.firecrawl.dev) FIRECRAWL_API_URL=http://localhost:3002 # Session TTL in seconds (default: 300) FIRECRAWL_BROWSER_TTL=600 ``` ### Hybrid routing: cloud for public URLs, local for LAN/localhost When a cloud provider is configured, Hermes auto-spawns a local Chromium sidecar** for URLs that resolve to a private/loopback/LAN address (localhost`,` 127.0.0.1`,` 192.168.x.x`,` 10.x.x.x`,` 172.16-31.x.x`,` .local`,` .lan`,` .internal`, IPv6 loopback` ::1`, link-local` 169.254.x.x`). Public URLs continue to use the cloud provider in the same conversation. This solves the common "I'm developing locally but using Browserbase" workflow — the agent can screenshot your dashboard at` http://localhost:3000`AND scrape`https://github.comwithout you switching providers or disabling the SSRF guard. The cloud provider never sees the private URL. The feature is on by default. To disable it (all URLs go to the configured cloud provider, as before): ```yaml # ~/.hermes/config.yaml browser: cloud_provider: browserbase auto_local_for_private_urls: false ``` With auto-routing disabled, private URLs are rejected with“Blocked: URL targets a private or internal address”`unless you also set`browser.allow_private_urls: true`(which lets the cloud provider attempt them — usually won't work since Browserbase etc. can't reach your LAN). Requirements: the local sidecar uses the same`agent-browser `CLI as pure local mode, so you need it installed (`hermes setup tools → Browser Automationauto-installs it). Post-navigation redirects from a public URL onto a private address are still blocked (you can't use a redirect-to-internal trick to reach your LAN through the public path). ### Camofox local mode [Camofox](https://github.com/jo-inc/camofox-browser) is a self-hosted Node.js server wrapping Camoufox (a Firefox fork with C++ fingerprint spoofing). It provides local anti-detection browsing without cloud dependencies. ```bash # Clone the Camofox browser server first git clone https://github.com/jo-inc/camofox-browser cd camofox-browser # Build and start with Docker using the default container settings # (auto-detects arch: aarch64 on M1/M2, x86_64 on Intel) make up # Stop and remove the default container make down # Force a clean rebuild (for example, after upgrading VERSION/RELEASE) make reset # Just download binaries without building make fetch # Override arch or version explicitly make up ARCH=x86_64 make up VERSION=135.0.1 RELEASE=beta.24 ```make upstarts the default container immediately. If you want custom runtime settings such as a larger Node heap, VNC, or a persistent profile directory, build the image first and then run it yourself: ```bash # Build the image without starting the default container make build # Start with persistence, VNC live view, and a larger Node heap mkdir -p ~/.camofox-docker docker run -d \ --name camofox-browser \ --restart unless-stopped \ -p 9377:9377 \ -p 6080:6080 \ -p 5901:5900 \ -e CAMOFOX_PORT=9377 \ -e ENABLE_VNC=1 \ -e VNC_BIND=0.0.0.0 \ -e VNC_RESOLUTION=1920x1080 \ -e MAX_OLD_SPACE_SIZE=2048 \ -v ~/.camofox-docker:/root/.camofox \ camofox-browser:135.0.1-aarch64 ``` With VNC enabled, the browser runs in headed mode and can be watched live in your browser athttp://localhost:6080`(noVNC). You can also connect a native VNC client to`localhost:5901`. If you already ran` make up, stop and remove that default container before starting the custom one: ```bash make down # then run the custom docker run command above ``` Then set in /.hermes/.env: ```bash CAMOFOX_URL=http://localhost:9377 ``` If Camofox is running in Docker and you want it to open web apps served from the host machine, enable loopback rewriting. CAMOFOX_URL`should still point at the host-published control API, but page URLs such as`http://127.0.0.1:3000`must be opened from inside the container as`http://host.docker.internal:3000: ```yaml # ~/.hermes/config.yaml browser: camofox: rewrite_loopback_urls: true loopback_host_alias: host.docker.internal # default; use a LAN IP if needed ``` Equivalent env vars: ```bash CAMOFOX_REWRITE_LOOPBACK_URLS=true CAMOFOX_LOOPBACK_HOST_ALIAS=host.docker.internal ``` The rewrite only applies to page navigation URLs with loopback hosts (localhost`,` 127.0.0.1`,` ::1`). It does not change` CAMOFOX_URL`. Leave it disabled for non-Docker Camofox installs, where the browser already runs on the host and loopback URLs are correct. Or configure via` hermes tools`→ Browser Automation → Camofox. When`CAMOFOX_URL`is set, all browser tools automatically route through Camofox instead of Browserbase or agent-browser. #### Persistent browser sessions By default, each Camofox session gets a random identity — cookies and logins don't survive across agent restarts. To enable persistent browser sessions, add the following to`/.hermes/config.yaml: ```yaml browser: camofox: managed_persistence: true ``` Then fully restart Hermes so the new config is picked up. :::warning Nested path matters Hermes reads browser.camofox.managed_persistence`, not a top-level` managed_persistence. A common mistake is writing: ```yaml # ❌ Wrong — Hermes ignores this managed_persistence: true ``` If the flag is placed at the wrong path, Hermes silently falls back to a random ephemeral userId`and your login state will be lost on every session. ::: ##### What Hermes does - Sends a deterministic profile-scoped`userId`to Camofox so the server can reuse the same Firefox profile across sessions. - Skips server-side context destruction on cleanup, so cookies and logins survive between agent tasks. - Scopes the`userId`to the active Hermes profile, so different Hermes profiles get different browser profiles (profile isolation). ##### What Hermes does not do - It does not force persistence on the Camofox server. Hermes only sends a stable`userId`; the server must honor it by mapping that` userId`to a persistent Firefox profile directory. - If your Camofox server build treats every request as ephemeral (e.g. always calls`browser.newContext()without loading a stored profile), Hermes cannot make those sessions persist. Make sure you are running a Camofox build that implements userId-based profile persistence. ##### Verify it's working 1. Start Hermes and your Camofox server. 2. Open Google (or any login site) in a browser task and sign in manually. 3. End the browser task normally. 4. Start a new browser task. 5. Open the same site again — you should still be signed in. If step 5 logs you out, the Camofox server isn't honoring the stableuserId`. Double-check your config path, confirm you fully restarted Hermes after editing` config.yaml`, and verify your Camofox server version supports persistent per-user profiles. ##### Where state lives Hermes derives the stable` userId`from the profile-scoped directory`/.hermes/browser_auth/camofox/`(or the equivalent under` $HERMES_HOME` for non-default profiles). The actual browser profile data lives on the Camofox server side, keyed by that `userId`. To fully reset a persistent profile, clear it on the Camofox server and remove the corresponding Hermes profile's state directory. #### Externally managed Camofox sessions When another app drives the visible Camofox browser (a desktop assistant, a custom integration, another agent), configure Hermes to operate inside that same identity instead of spawning its own isolated profile. Three knobs control the behavior: | Setting | Env var | Effect | |---------|---------|--------| | `browser.camofox.user_id` | `CAMOFOX_USER_ID` | Camofox `userId` Hermes uses when creating tabs. Setting this opts the session into "externally managed" mode. | | `browser.camofox.session_key` | `CAMOFOX_SESSION_KEY` | `sessionKey` (a.k.a. `listItemId`) sent on tab creation. Used to match an existing tab during adoption. Defaults to a per-task value if unset. | | `browser.camofox.adopt_existing_tab` | `CAMOFOX_ADOPT_EXISTING_TAB` | When true, Hermes calls `GET /tabs?userId=<user_id>` on first use and reuses an existing tab before creating a new one. | Env vars take precedence over `config.yaml`. Either form works: ```yaml browser: camofox: user_id: shared-camofox session_key: visible-tab adopt_existing_tab: true ``` ```bash CAMOFOX_USER_ID=shared-camofox CAMOFOX_SESSION_KEY=visible-tab CAMOFOX_ADOPT_EXISTING_TAB=true ``` What changes when `user_id` is set: - Hermes skips destructive cleanup at task end (same as `managed_persistence: true`). The other app's tab/cookies/profile survive. - Hermes does not call `DELETE /sessions/<user_id>` — that endpoint wipes all user data, so it would nuke the external app's session if it fired. How tab adoption works (when `adopt_existing_tab: true`): 1. On the first browser tool call after a process start, Hermes issues `GET /tabs?userId=<user_id>` (5-second timeout). 2. If any tab in the response has `listItemId == session_key`, Hermes adopts the most recently created one in that group. 3. Otherwise, Hermes adopts the most recently created tab for the user (any `listItemId`). 4. If no tabs exist or the request fails, Hermes falls back to creating a new tab on the next operation. Adoption only fires until `tab_id` is populated for the session. If the external app closes the adopted tab mid-run, the next browser tool call will surface a Camofox error — Hermes does not re-poll for a fresh tab on every call. Picking `session_key`: if you want Hermes to reliably attach to a specific* existing tab, set `session_key` to the `listItemId` the external app used when creating it. If you leave `session_key` unset and only set `user_id`, Hermes generates a per-task `session_key` (`task_<id>`) — Hermes will share cookies and the profile with the external app, but will open its own tab alongside instead of reusing one. Concurrency note: the external app and Hermes can drive the same Camofox `userId` simultaneously, but Camofox does not coordinate per-tab focus between clients. Coordinate ownership at the application layer (e.g. the external app pauses while Hermes runs). #### VNC live view When Camofox runs in headed mode (with a visible browser window), it exposes a VNC port in its health check response. Hermes automatically discovers this and includes the VNC URL in navigation responses, so the agent can share a link for you to watch the browser live. ### Local Chromium-family browser via CDP (`/browser connect`) Instead of a cloud provider, you can attach Hermes browser tools to your own running Chrome, Brave, Chromium, or Edge instance via the Chrome DevTools Protocol (CDP). This is useful when you want to see what the agent is doing in real-time, interact with pages that require your own cookies/sessions, or avoid cloud browser costs. :::note `/browser connect` is an interactive-CLI slash command — it is not dispatched by the gateway. If you try to run it inside a WebUI, Telegram, Discord, or other gateway chat, the message will be sent to the agent as plain text and the command will not execute. Start Hermes from the terminal (`hermes` or `hermes chat`) and issue `/browser connect` there. ::: In the CLI, use: ``` /browser connect # Auto-launch/connect to a local Chromium-family browser at http://127.0.0.1:9222 /browser connect ws://host:port # Connect to a specific CDP endpoint /browser status # Check current connection /browser disconnect # Detach and return to cloud/local mode ``` If a browser isn't already running with remote debugging, Hermes will attempt to auto-launch a supported Chromium-family browser with `--remote-debugging-port=9222`. Detection includes Brave, Google Chrome, Chromium, and Microsoft Edge, with common Linux install paths such as `/opt/brave-bin/brave` and `/snap/bin/brave`. :::tip To start a Chromium-family browser manually with CDP enabled, use a dedicated user-data-dir so the debug port actually comes up even if the browser is already running with your normal profile: ```bash # Linux — Brave brave-browser \ --remote-debugging-port=9222 \ --user-data-dir=$ HOME/.hermes/chrome-debug \ –no-first-run \ –no-default-browser-check & # Linux — Google Chrome google-chrome \ –remote-debugging-port=9222 \ –user-data-dir= $HOME/.hermes/chrome-debug \ --no-first-run \ --no-default-browser-check & # macOS — Brave "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser" \ --remote-debugging-port=9222 \ --user-data-dir="$ HOME/.hermes/chrome-debug“ \ –no-first-run \ –no-default-browser-check & # macOS — Google Chrome “/Applications/Google Chrome.app/Contents/MacOS/Google Chrome” \ –remote-debugging-port=9222 \ –user-data-dir=“$HOME/.hermes/chrome-debug” \ –no-first-run \ –no-default-browser-check & Then launch the Hermes CLI and run `/browser connect`. Why `--user-data-dir`? Without it, launching a Chromium-family browser while a regular instance is already running typically opens a new window on the existing process — and that existing process was not started with `--remote-debugging-port`, so port 9222 never opens. A dedicated user-data-dir forces a fresh browser process where the debug port actually listens. `--no-first-run --no-default-browser-check` skips the first-launch wizard for the fresh profile. ::: When connected via CDP, all browser tools (`browser_navigate`, `browser_click`, etc.) operate on your live browser instance instead of spinning up a cloud session. ### WSL2 + Windows Chrome: prefer MCP over `/browser connect` If Hermes runs inside WSL2 but the Chrome window you want to control runs on the Windows host, `/browser connect` is often not the best path. Why: - `/browser connect` expects Hermes itself to reach a usable CDP endpoint - modern Chrome live-debugging sessions often expose a host-local endpoint that is not directly reachable from WSL the same way a classic `9222` port is - even when Windows Chrome is debuggable, the cleanest integration is often to let a Windows-side browser MCP server attach to Chrome and let Hermes talk to that MCP server For that setup, prefer `chrome-devtools-mcp` through Hermes MCP support. See the MCP guide for the practical setup: - [Use MCP with Hermes](../../guides/use-mcp-with-hermes.md#wsl2-bridge-hermes-in-wsl-to-windows-chrome) ### Local browser mode If you do not set any cloud credentials and don't use `/browser connect`, Hermes can still use the browser tools through a local Chromium install driven by `agent-browser`. ### Optional Environment Variablesbash # Residential proxies for better CAPTCHA solving (default: “true”) BROWSERBASE_PROXIES=true # Advanced stealth with custom Chromium — requires Scale Plan (default: “false”) BROWSERBASE_ADVANCED_STEALTH=false # Session reconnection after disconnects — requires paid plan (default: “true”) BROWSERBASE_KEEP_ALIVE=true # Custom session timeout in seconds (max 21600 = 6 hours) (default: project default) # Examples: 600 (10min), 1800 (30min), 21600 (6h max) BROWSERBASE_SESSION_TIMEOUT=1800 # Inactivity timeout before auto-cleanup in seconds (default: 120) BROWSER_INACTIVITY_TIMEOUT=120 # Extra Chromium launch flags (comma- or newline-separated). Hermes auto-injects # `--no-sandbox,--disable-dev-shm-usage` when it detects root or AppArmor-restricted # unprivileged user namespaces (Ubuntu 23.10+, DGX Spark, many container images), # so most users don’t need to set this. Set it manually only if you need a flag # Hermes doesn’t add automatically; setting it disables the auto-injection. AGENT_BROWSER_ARGS=–no-sandbox `### Install agent-browser CLI`bash npm install -g agent-browser # Or install locally in the repo: npm install :::info The `browser` toolset must be included in your config's `toolsets` list or enabled via `hermes config set toolsets '["hermes-cli", "browser"]'`. ::: ## Available Tools ### `browser_navigate` Navigate to a URL. Must be called before any other browser tool. Initializes the Browserbase session. Navigate to https://github.com/NousResearch :::tip For simple information retrieval, prefer `web_search` or `web_extract` — they are faster and cheaper. Use browser tools when you need to interact with a page (click buttons, fill forms, handle dynamic content). ::: ### `browser_snapshot` Get a text-based snapshot of the current page's accessibility tree. Returns interactive elements with ref IDs like `@e1`, `@e2` for use with `browser_click` and `browser_type`. - `full=false` (default): Compact view showing only interactive elements - `full=true`: Complete page content Snapshots over 8000 characters are automatically summarized by an LLM. ### `browser_click` Click an element identified by its ref ID from the snapshot. Click @e5 to press the “Sign In” button ### `browser_type` Type text into an input field. Clears the field first, then types the new text. Type “hermes agent” into the search field @e3 ### `browser_scroll` Scroll the page up or down to reveal more content. Scroll down to see more results ### `browser_press` Press a keyboard key. Useful for submitting forms or navigation. Press Enter to submit the form Supported keys: `Enter`, `Tab`, `Escape`, `ArrowDown`, `ArrowUp`, and more. ### `browser_back` Navigate back to the previous page in browser history. ### `browser_get_images` List all images on the current page with their URLs and alt text. Useful for finding images to analyze. ### `browser_vision` Take a screenshot and analyze it with vision AI. Use this when text snapshots don't capture important visual information — especially useful for CAPTCHAs, complex layouts, or visual verification challenges. The screenshot is saved persistently and the file path is returned alongside the AI analysis. On messaging platforms (Telegram, Discord, Slack, WhatsApp), you can ask the agent to share the screenshot — it will be sent as a native photo attachment via the `MEDIA:` mechanism. What does the chart on this page show? Screenshots are stored in `~/.hermes/cache/screenshots/` and automatically cleaned up after 24 hours. ### `browser_console` Get browser console output (log/warn/error messages) and uncaught JavaScript exceptions from the current page. Essential for detecting silent JS errors that don't appear in the accessibility tree. Check the browser console for any JavaScript errors Use `clear=True` to clear the console after reading, so subsequent calls only show new messages. `browser_console` also evaluates JavaScript when called with an `expression` argument — same shape as DevTools console, the result comes back parsed (JSON-serialized objects become dicts; primitive values stay primitive). browser_console(expression=“document.querySelector(‘h1’).textContent”) browser_console(expression=“JSON.stringify(performance.timing)”) When a CDP supervisor is active for the current session (typical for any session that's run `browser_navigate` against a CDP-capable backend), evaluation runs over the supervisor's persistent WebSocket — no subprocess startup cost. Falls through to the standard agent-browser CLI path otherwise. Behaviour is identical either way; only latency changes. ### `browser_cdp` Raw Chrome DevTools Protocol passthrough — the escape hatch for browser operations not covered by the other tools. Use for native dialog handling, iframe-scoped evaluation, cookie/network control, or any CDP verb the agent needs. Only available when a CDP endpoint is reachable at session start — meaning `/browser connect` has attached to a running Chrome, Brave, Chromium, or Edge browser, or `browser.cdp_url` is set in `config.yaml`. The default local agent-browser mode, Camofox, and cloud providers (Browserbase, Browser Use, Firecrawl) do not currently expose CDP to this tool — cloud providers have per-session CDP URLs but live-session routing is a follow-up. CDP method reference: https://chromedevtools.github.io/devtools-protocol/ — the agent can `web_extract` a specific method's page to look up parameters and return shape. Common patterns: # List tabs (browser-level, no target_id) browser_cdp(method=“Target.getTargets”) # Handle a native JS dialog on a tab browser_cdp(method=“Page.handleJavaScriptDialog”, params={“accept”: true, “promptText”: “”}, target_id=“”) # Evaluate JS in a specific tab browser_cdp(method=“Runtime.evaluate”, params={“expression”: “document.title”, “returnByValue”: true}, target_id=“”) # Get all cookies browser_cdp(method=“Network.getAllCookies”) Browser-level methods (`Target.`, `Browser.`, `Storage.`) omit `target_id`. Page-level methods (`Page.`, `Runtime.`, `DOM.`, `Emulation.`) require a `target_id` from `Target.getTargets`. Each stateless call is independent — sessions do not persist between calls. Cross-origin iframes: pass `frame_id` (from `browser_snapshot.frame_tree.children[]` where `is_oopif=true`) to route the CDP call through the supervisor's live session for that iframe. This is how `Runtime.evaluate` inside a cross-origin iframe works on Browserbase, where stateless CDP connections would hit signed-URL expiry. Example: browser_cdp( method=“Runtime.evaluate”, params={“expression”: “document.title”, “returnByValue”: True}, frame_id=“<frame_id from browser_snapshot>”, ) Same-origin iframes don't need `frame_id` — use `document.querySelector('iframe').contentDocument` from a top-level `Runtime.evaluate` instead. ### `browser_dialog` Responds to a native JS dialog (`alert` / `confirm` / `prompt` / `beforeunload`). Before this tool existed, dialogs would silently block the page's JavaScript thread and subsequent `browser_` calls would hang or throw; now the agent sees pending dialogs in `browser_snapshot` output and responds explicitly. Workflow: 1. Call `browser_snapshot`. If a dialog is blocking the page, it shows up as `pending_dialogs: [{"id": "d-1", "type": "alert", "message": "..."}]`. 2. Call `browser_dialog(action="accept")` or `browser_dialog(action="dismiss")`. For `prompt()` dialogs, pass `prompt_text="..."` to supply the response. 3. Re-snapshot — `pending_dialogs` is empty; the page's JS thread has resumed. Detection happens automatically via a persistent CDP supervisor — one WebSocket per task that subscribes to Page/Runtime/Target events. The supervisor also populates a `frame_tree` field in the snapshot so the agent can see the iframe structure of the current page, including cross-origin (OOPIF) iframes. Availability matrix: | Backend | Detection via `pending_dialogs` | Response (`browser_dialog` tool) | |---|---|---| | Local Chrome via `/browser connect` or `browser.cdp_url` | ✓ | ✓ full workflow | | Browserbase | ✓ | ✓ full workflow (via injected XHR bridge) | | Camofox / default local agent-browser | ✗ | ✗ (no CDP endpoint) | How it works on Browserbase. Browserbase's CDP proxy auto-dismisses real native dialogs server-side within ~10ms, so we can't use `Page.handleJavaScriptDialog`. The supervisor injects a small script via `Page.addScriptToEvaluateOnNewDocument` that overrides `window.alert`/`confirm`/`prompt` with a synchronous XHR. We intercept those XHRs via `Fetch.enable` — the page's JS thread stays blocked on the XHR until we call `Fetch.fulfillRequest` with the agent's response. `prompt()` return values round-trip back into page JS unchanged. Dialog policy is configured in `config.yaml` under `browser.dialog_policy`: | Policy | Behavior | |--------|----------| | `must_respond` (default) | Capture, surface in snapshot, wait for explicit `browser_dialog()` call. Safety auto-dismiss after `browser.dialog_timeout_s` (default 300s) so a buggy agent can't stall forever. | | `auto_dismiss` | Capture, dismiss immediately. Agent still sees the dialog in `browser_state` history but doesn't have to act. | | `auto_accept` | Capture, accept immediately. Useful when navigating pages with aggressive `beforeunload` prompts. | Frame tree inside `browser_snapshot.frame_tree` is capped to 30 frames and OOPIF depth 2 to keep payloads bounded on ad-heavy pages. A `truncated: true` flag surfaces when limits were hit; agents needing the full tree can use `browser_cdp` with `Page.getFrameTree`. ## Practical Examples ### Filling Out a Web Form User: Sign up for an account on example.com with my email [email protected] Agent workflow: 1. browser_navigate(“https://example.com/signup”) 2. browser_snapshot() → sees form fields with refs 3. browser_type(ref=“@e3”, text=“[email protected]”) 4. browser_type(ref=“@e5”, text=“SecurePass123”) 5. browser_click(ref=“@e8”) → clicks “Create Account” 6. browser_snapshot() → confirms success `### Researching Dynamic Content` User: What are the top trending repos on GitHub right now? Agent workflow: 1. browser_navigate(“https://github.com/trending”) 2. browser_snapshot(full=true) → reads trending repo list 3. Returns formatted results `## Session Recording Automatically record browser sessions as WebM video files:`yaml browser: record_sessions: true # default: false When enabled, recording starts automatically on the first `browser_navigate` and saves to `~/.hermes/browser_recordings/` when the session closes. Works in both local and cloud (Browserbase) modes. Recordings older than 72 hours are automatically cleaned up. ## Stealth Features Browserbase provides automatic stealth capabilities: | Feature | Default | Notes | |---------|---------|-------| | Basic Stealth | Always on | Random fingerprints, viewport randomization, CAPTCHA solving | | Residential Proxies | On | Routes through residential IPs for better access | | Advanced Stealth | Off | Custom Chromium build, requires Scale Plan | | Keep Alive | On | Session reconnection after network hiccups | :::note If paid features aren't available on your plan, Hermes automatically falls back — first disabling `keepAlive`, then proxies — so browsing still works on free plans. ::: ## Session Management - Each task gets an isolated browser session via Browserbase - Sessions are automatically cleaned up after inactivity (default: 2 minutes) - A background thread checks every 30 seconds for stale sessions - Emergency cleanup runs on process exit to prevent orphaned sessions - Sessions are released via the Browserbase API (`REQUEST_RELEASE` status) ## Limitations - Text-based interaction — relies on accessibility tree, not pixel coordinates - Snapshot size — large pages may be truncated or LLM-summarized at 8000 characters - Session timeout — cloud sessions expire based on your provider's plan settings - Cost — cloud sessions consume provider credits; sessions are automatically cleaned up when the conversation ends or after inactivity. Use `/browser connect` for free local browsing. - No file downloads — cannot download files from the browser ---  # user-guide/features/vision # Vision & Image Paste Hermes Agent supports multimodal vision — you can paste images from your clipboard directly into the CLI and ask the agent to analyze, describe, or work with them. Images are sent to the model as base64-encoded content blocks, so any vision-capable model can process them. :::tip Portal subscribers get vision-capable models (Claude, GPT-5, Gemini) in the same catalog — no extra credentials needed. See [Nous Portal](/integrations/nous-portal). ::: ## How It Works 1. Copy an image to your clipboard (screenshot, browser image, etc.) 2. Attach it using one of the methods below 3. Type your question and press Enter 4. The image appears as a `[📎 Image #1]` badge above the input 5. On submit, the image is sent to the model as a vision content block You can attach multiple images before sending — each gets its own badge. Press `Ctrl+C` to clear all attached images. Images are saved to `~/.hermes/images/` as PNG files with timestamped filenames. ## Paste Methods How you attach an image depends on your terminal environment. Not all methods work everywhere — here's the full breakdown: ### `/paste` Command The most reliable explicit image-attach fallback. /paste Type `/paste` and press Enter. Hermes checks your clipboard for an image and attaches it. This is the safest option when your terminal rewrites `Cmd+V`/`Ctrl+V`, or when you copied only an image and there is no bracketed-paste text payload to inspect. ### Ctrl+V / Cmd+V Hermes now treats paste as a layered flow: - normal text paste first - native clipboard / OSC52 text fallback if the terminal did not deliver text cleanly - image attach when the clipboard or pasted payload resolves to an image or image path This means pasted macOS screenshot temp paths and `file://...` image URIs can attach immediately instead of sitting in the composer as raw text. :::warning If your clipboard has only an image (no text), terminals still cannot send binary image bytes directly. Use `/paste` as the explicit image-attach fallback. ::: ### `/terminal-setup` for VS Code / Cursor / Windsurf If you run the TUI inside a local VS Code-family integrated terminal on macOS, Hermes can install the recommended `workbench.action.terminal.sendSequence` bindings for better multiline and undo/redo parity:text /terminal-setup This is especially useful when `Cmd+Enter`, `Cmd+Z`, or `Shift+Cmd+Z` are being intercepted by the IDE. Run it on the local machine only — not inside an SSH session. ## Platform Compatibility | Environment | `/paste` | Cmd/Ctrl+V | `/terminal-setup` | Notes | |---|:---:|:---:|:---:|---| | macOS Terminal / iTerm2 | ✅ | ✅ | n/a | Best experience — native clipboard + screenshot-path recovery | | Apple Terminal | ✅ | ✅ | n/a | If Cmd+←/→/⌫ gets rewritten, use Ctrl+A / Ctrl+E / Ctrl+U fallbacks | | Linux X11 desktop | ✅ | ✅ | n/a | Requires `xclip` (`apt install xclip`) | | Linux Wayland desktop | ✅ | ✅ | n/a | Requires `wl-paste` (`apt install wl-clipboard`) | | WSL2 (Windows Terminal) | ✅ | ✅ | n/a | Uses `powershell.exe` — no extra install needed | | VS Code / Cursor / Windsurf (local) | ✅ | ✅ | ✅ | Recommended for better Cmd+Enter / undo / redo parity | | VS Code / Cursor / Windsurf (SSH) | ❌² | ❌² | ❌³ | Run `/terminal-setup` on the local machine instead | | SSH terminal (any) | ❌² | ❌² | n/a | Remote clipboard not accessible | ² See [SSH & Remote Sessions](#ssh--remote-sessions) below ³ The command writes local IDE keybindings and should not be run from the remote host ## Platform-Specific Setup ### macOS No setup required. Hermes uses `osascript` (built into macOS) to read the clipboard. For faster performance, optionally install `pngpaste`:bash brew install pngpaste ### Linux (X11) Install `xclip`:bash # Ubuntu/Debian sudo apt install xclip # Fedora sudo dnf install xclip # Arch sudo pacman -S xclip ### Linux (Wayland) Modern Linux desktops (Ubuntu 22.04+, Fedora 34+) often use Wayland by default. Install `wl-clipboard`:bash # Ubuntu/Debian sudo apt install wl-clipboard # Fedora sudo dnf install wl-clipboard # Arch sudo pacman -S wl-clipboard `:::tip How to check if you're on Wayland`bash echo $XDG_SESSION_TYPE # “wayland” = Wayland, “x11” = X11, “tty” = no display server ::: ### WSL2 No extra setup required. Hermes detects WSL2 automatically (via `/proc/version`) and uses `powershell.exe` to access the Windows clipboard through .NET's `System.Windows.Forms.Clipboard`. This is built into WSL2's Windows interop — `powershell.exe` is available by default. The clipboard data is transferred as base64-encoded PNG over stdout, so no file path conversion or temp files are needed. :::info WSLg Note If you're running WSLg (WSL2 with GUI support), Hermes tries the PowerShell path first, then falls back to `wl-paste`. WSLg's clipboard bridge only supports BMP format for images — Hermes auto-converts BMP to PNG using Pillow (if installed) or ImageMagick's `convert` command. ::: #### Verify WSL2 clipboard accessbash # 1. Check WSL detection grep -i microsoft /proc/version # 2. Check PowerShell is accessible which powershell.exe # 3. Copy an image, then check powershell.exe -NoProfile -Command “Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.Clipboard]::ContainsImage()” # Should print “True” ## SSH & Remote Sessions Clipboard image paste does not fully work over SSH. When you SSH into a remote machine, the Hermes CLI runs on the remote host. Clipboard tools (`xclip`, `wl-paste`, `powershell.exe`, `osascript`) read the clipboard of the machine they run on — which is the remote server, not your local machine. Your local clipboard image is therefore inaccessible from the remote side. Text can sometimes still bridge through terminal paste or OSC52, but image clipboard access and local screenshot temp paths remain tied to the machine running Hermes. ### Workarounds for SSH 1. Upload the image file — Save the image locally, upload it to the remote server via `scp`, VSCode's file explorer (drag-and-drop), or any file transfer method. Then reference it by path. (A `/attach <filepath>` command is planned for a future release.) 2. Use a URL — If the image is accessible online, just paste the URL in your message. The agent can use `vision_analyze` to look at any image URL directly. 3. X11 forwarding — Connect with `ssh -X` to forward X11. This lets `xclip` on the remote machine access your local X11 clipboard. Requires an X server running locally (XQuartz on macOS, built-in on Linux X11 desktops). Slow for large images. 4. Use a messaging platform — Send images to Hermes via Telegram, Discord, Slack, or WhatsApp. These platforms handle image upload natively and are not affected by clipboard/terminal limitations. ## Why Terminals Can't Paste Images This is a common source of confusion, so here's the technical explanation: Terminals are text-based interfaces. When you press Ctrl+V (or Cmd+V), the terminal emulator: 1. Reads the clipboard for text content 2. Wraps it in [bracketed paste](https://en.wikipedia.org/wiki/Bracketed-paste) escape sequences 3. Sends it to the application through the terminal's text stream If the clipboard contains only an image (no text), the terminal has nothing to send. There is no standard terminal escape sequence for binary image data. The terminal simply does nothing. This is why Hermes uses a separate clipboard check — instead of receiving image data through the terminal paste event, it calls OS-level tools (`osascript`, `powershell.exe`, `xclip`, `wl-paste`) directly via subprocess to read the clipboard independently. ## Supported Models Image paste works with any vision-capable model. The image is sent as a base64-encoded data URL in the OpenAI vision content format:json { “type”: “image_url”, “image_url”: { “url”: “data:image/png;base64,…” } } Most modern models support this format, including GPT-4 Vision, Claude (with vision), Gemini, and open-source multimodal models served through OpenRouter. ## Image Routing (Vision-Capable vs Text-Only Models) When a user attaches an image — from the CLI clipboard, the gateway (Telegram/Discord photo), or any other entry point — Hermes routes it based on whether your current model actually supports vision: | Your model | What happens to the image | |---|---| | Vision-capable (GPT-4V, Claude with vision, Gemini, Qwen-VL, MiMo-VL, etc.) | Sent as real pixels using the provider's native image content format above. No text summary layer. | | Text-only (DeepSeek V3, smaller open-source models, older chat-only endpoints) | Routed through the `vision_analyze` auxiliary tool — an auxiliary vision model describes the image, and the text description is injected into the conversation. | You don't configure this — Hermes looks up your current model's capability in the provider metadata and picks the right path automatically. The practical effect: you can switch between vision and non-vision models mid-session and image handling "just works" without changing your workflow. Text-only models get coherent context about the image rather than a broken multimodal payload they'd have to reject. Which auxiliary model handles the text-description path is configurable under `auxiliary.vision` — see [Auxiliary Models](/user-guide/configuration#auxiliary-models). ### `vision_analyze` has the same dual behavior The `vision_analyze` tool itself follows the same routing. When the active main model is vision-capable and its provider supports image content inside tool results (currently the Anthropic, OpenAI, Azure-OpenAI, and Gemini 3.x stacks), `vision_analyze` short-circuits the auxiliary describer and returns the raw image pixels as a multimodal tool-result envelope. The main model sees the image natively on its next turn — no aux call, no text-summary information loss, no extra latency. For text-only main models (or providers whose tool-result channel doesn't carry images), `vision_analyze` falls back to the legacy path: it asks the configured auxiliary vision model to describe the image and returns the description as plain text. Either way the calling tool signature is the same — the tool decides which path to take at runtime based on the active model. ---  # user-guide/features/image-generation # Image Generation Hermes Agent generates images from text prompts via FAL.ai. Eleven models are supported out of the box, each with different speed, quality, and cost tradeoffs. The active model is user-configurable via `hermes tools` and persists in `config.yaml`. ## Supported Models | Model | Speed | Strengths | Price | |---|---|---|---| | `fal-ai/flux-2/klein/9b` (default) | `<1s` | Fast, crisp text | $0.006/MP | | `fal-ai/flux-2-pro` | ~6s | Studio photorealism | $0.03/MP | | `fal-ai/z-image/turbo` | ~2s | Bilingual EN/CN, 6B params | $0.005/MP | | `fal-ai/nano-banana-pro` | ~8s | Gemini 3 Pro, reasoning depth, text rendering | $0.15/image (1K) | | `fal-ai/gpt-image-1.5` | ~15s | Prompt adherence | $0.034/image | | `fal-ai/gpt-image-2` | ~20s | SOTA text rendering + CJK, world-aware photorealism | $0.04–0.06/image | | `fal-ai/ideogram/v3` | ~5s | Best typography | $0.03–0.09/image | | `fal-ai/recraft/v4/pro/text-to-image` | ~8s | Design, brand systems, production-ready | $0.25/image | | `fal-ai/qwen-image` | ~12s | LLM-based, complex text | $0.02/MP | | `fal-ai/krea/v2/medium/text-to-image` | ~15-25s | Illustration, anime, painting, expressive/artistic styles | $0.030–0.035/image | | `fal-ai/krea/v2/large/text-to-image` | ~25-60s | Photorealism, raw textured looks (motion blur, grain, film) | $0.060–0.065/image | Prices are FAL's pricing at time of writing; check [fal.ai](https://fal.ai/) for current numbers. ## Setup :::tip Nous Subscribers If you have a paid [Nous Portal](https://portal.nousresearch.com) subscription, you can use image generation through the [Tool Gateway](tool-gateway.md) without a FAL API key. Your model selection persists across both paths. New installs can run `hermes setup --portal` to log in and turn on every gateway tool at once; existing installs can pick Nous Subscription as the image-gen backend via `hermes tools`. If the managed gateway returns `HTTP 4xx` for a specific model, that model isn't yet proxied on the portal side — the agent will tell you so, with remediation steps (set `FAL_KEY` for direct access, or pick a different model). ::: ### Get a FAL API Key 1. Sign up at [fal.ai](https://fal.ai/) 2. Generate an API key from your dashboard ### Configure and Pick a Model Run the tools command:bash hermes tools `Navigate to 🎨 Image Generation, pick your backend (Nous Subscription or FAL.ai), then the picker shows all supported models in a column-aligned table — arrow keys to navigate, Enter to select:` Model Speed Strengths Price fal-ai/flux-2/klein/9b <1s Fast, crisp text $0.006/MP ← currently in use fal-ai/flux-2-pro 6s Studio photorealism $0.03/MP fal-ai/z-image/turbo 2s Bilingual EN/CN, 6B $0.005/MP ... ``` Your selection is saved to `config.yaml`: ```yaml image_gen: model: fal-ai/flux-2/klein/9b use_gateway: false # true if using Nous Subscription ``` ### GPT-Image Quality The `fal-ai/gpt-image-1.5` and `fal-ai/gpt-image-2` request quality is pinned to `medium` (~$ 0.034–/`` /`"` escaping; outside quotes get `shlex.quote`. Don't pre-quote placeholder values. #### STT command-provider security The shell command runs under the same user as Hermes with full filesystem access — same trust model as `tts.providers.<name>: type: command` and `HERMES_LOCAL_STT_COMMAND`. Only declare command providers from sources you trust. ### Python plugin providers (STT) For STT engines that aren't built-in AND can't be expressed as a shell command (need a Python SDK, OAuth-refreshing auth, streaming chunks, etc.), register a Python plugin via `ctx.register_transcription_provider()`. The plugin coexists with the 6 built-in providers (`local`, `local_command`, `groq`, `openai`, `mistral`, `xai`) and the `stt.providers.<name>: type: command` registry — built-ins keep their native implementations and always win on name collision; command providers win over plugins of the same name (config is more local than plugin install). #### When to pick which (STT) | Backend has… | Use | |--------------------------------------------------------------|------------------------------------------------------------------| | A single shell command that takes an audio file and emits text | `stt.providers.<name>: type: command` (no Python needed) | | Only the legacy single-command escape hatch is wanted | `HERMES_LOCAL_STT_COMMAND` env var (preserved for back-compat) | | A Python SDK with no CLI | `register_transcription_provider()` plugin | | OAuth-refreshing auth, streaming chunks, voice-list metadata | `register_transcription_provider()` plugin | | A built-in already covers it (`local`, `groq`, `openai`, …) | Set `stt.provider: <name>` — built-ins are inline | #### Resolution order 1. `stt.provider` is a built-in name → built-in dispatch. Always wins. 2. `stt.provider` matches `stt.providers.<name>` with `command:` set → command-provider runner (see [STT custom command providers](#stt-custom-command-providers)). Wins over a same-name plugin. 3. `stt.provider` matches a plugin-registered `TranscriptionProvider` → plugin dispatch: - if the plugin's `is_available()` returns `False` (missing creds or SDK), the call surfaces an unavailability error envelope identifying the plugin — not the generic "No STT provider available" message. - otherwise the plugin's `transcribe()` is called with `model` (from the public `model=` arg, falling back to `stt.<provider>.model`) and `language` (from `stt.<provider>.language`). 4. No match → "No STT provider available" error. #### Per-provider config namespace Plugins read their per-provider configuration from `stt.<provider>` in `config.yaml`, mirroring how built-ins read `stt.openai.model` / `stt.mistral.model`: ```yaml stt: provider: my-stt my-stt: model: whisper-large-v3 language: ja # forwarded as language= to transcribe() # any other plugin-specific keys go here; read them via your # own config.yaml access in init/is_available/transcribe ``` The dispatcher forwards `model` and `language` from this section; everything else, the plugin can read itself. #### Minimal plugin Drop this in `~/.hermes/plugins/my-stt/`: `plugin.yaml`: ```yaml name: my-stt version: 0.1.0 description: "My custom Python STT backend" ``` `init.py`: ```python from agent.transcription_provider import TranscriptionProvider class MySTTProvider(TranscriptionProvider): @property def name(self) -> str: return "my-stt" # what stt.provider matches against @property def display_name(self) -> str: return "My Custom STT" def is_available(self) -> bool: # Return False when credentials/deps are missing — picker skips # this row but the dispatcher still routes here on explicit config. import os return bool(os.environ.get("MY_STT_API_KEY")) def transcribe(self, file_path, *, model=None, language=None, extra): # Return the standard transcribe envelope: # {"success": bool, "transcript": str, "provider": str, "error": str} # Do NOT raise — convert exceptions to the error envelope so the # gateway/CLI caller sees a consistent shape on failure. try: import my_stt_sdk client = my_stt_sdk.Client() text = client.transcribe(open(file_path, "rb")) return { "success": True, "transcript": text, "provider": "my-stt", } except Exception as exc: return { "success": False, "transcript": "", "error": f"my-stt failed: {exc}", "provider": "my-stt", } def register(ctx): ctx.register_transcription_provider(MySTTProvider()) ``` Enable it (`hermes plugins enable my-stt`), set `stt.provider: my-stt` in `config.yaml`, and voice-message transcription will route through your plugin. #### Optional hooks Override these on your provider class for richer integration: - `list_models()` → list of `{id, display, languages, max_audio_seconds}` dicts. - `default_model()` → string returned when the user doesn't override the model. - `get_setup_schema()` → return `{name, badge, tag, env_vars: [{key, prompt, url}]}` to power picker rows in `hermes tools` / `hermes setup` (the picker category for STT is not yet shipped — this metadata is available to plugins for forward compatibility). See `agent/transcription_provider.py` for the full ABC including docstrings. ---  # Messaging Gateway # Messaging Gateway Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin, BlueBubbles (iMessage), QQ, Yuanbao, Microsoft Teams, LINE, ntfy, or your browser. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages. For the full voice feature set — including CLI microphone mode, spoken replies in messaging, and Discord voice-channel conversations — see [Voice Mode](/user-guide/features/voice-mode) and [Use Voice Mode with Hermes](/guides/use-voice-mode-with-hermes). :::tip Bots need both a model provider and tool providers (TTS, web). A [Nous Portal](/integrations/nous-portal) subscription bundles all of them. ::: ## Platform Comparison | Platform | Voice | Images | Files | Threads | Reactions | Typing | Streaming | |----------|:-----:|:------:|:-----:|:-------:|:---------:|:------:|:---------:| | Telegram | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | | Discord | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Slack | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Google Chat | — | ✅ | ✅ | ✅ | — | ✅ | — | | WhatsApp | — | ✅ | ✅ | — | — | ✅ | ✅ | | Signal | — | ✅ | ✅ | — | — | ✅ | ✅ | | SMS | — | — | — | — | — | — | — | | Email | — | ✅ | ✅ | ✅ | — | — | — | | Home Assistant | — | — | — | — | — | — | — | | Mattermost | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | | Matrix | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | DingTalk | — | ✅ | ✅ | — | ✅ | — | ✅ | | Feishu/Lark | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | WeCom | ✅ | ✅ | ✅ | — | — | — | — | | WeCom Callback | — | — | — | — | — | — | — | | Weixin | ✅ | ✅ | ✅ | — | — | ✅ | ✅ | | BlueBubbles | — | ✅ | ✅ | — | ✅ | ✅ | — | | QQ | ✅ | ✅ | ✅ | — | — | ✅ | — | | Yuanbao | ✅ | ✅ | ✅ | — | — | ✅ | ✅ | | Microsoft Teams | — | ✅ | — | ✅ | — | ✅ | — | | LINE | — | ✅ | ✅ | — | — | ✅ | — | | ntfy | — | — | — | — | — | — | — | Voice = TTS audio replies and/or voice message transcription. Images = send/receive images. Files = send/receive file attachments. Threads = threaded conversations. Reactions = emoji reactions on messages. Typing = typing indicator while processing. Streaming = progressive message updates via editing. ## Architecture ```mermaid flowchart TB subgraph Gateway["Hermes Gateway"] subgraph Adapters["Platform adapters"] tg[Telegram] dc[Discord] wa[WhatsApp] sl[Slack] gc[Google Chat] sig[Signal] sms[SMS] em[Email] ha[Home Assistant] mm[Mattermost] mx[Matrix] dt[DingTalk] fs[Feishu/Lark] wc[WeCom] wcb[WeCom Callback] wx[Weixin] bb[BlueBubbles] qq[QQ] yb[Yuanbao] ms[Microsoft Teams] api["API Server<br/>(OpenAI-compatible)"] wh[Webhooks] end store["Session store<br/>per chat"] agent["AIAgent<br/>run_agent.py"] cron["Cron scheduler<br/>ticks every 60s"] end tg --> store dc --> store wa --> store sl --> store gc --> store sig --> store sms --> store em --> store ha --> store mm --> store mx --> store dt --> store fs --> store wc --> store wcb --> store wx --> store bb --> store qq --> store yb --> store ms --> store api --> store wh --> store store --> agent cron --> store ``` Each platform adapter receives messages, routes them through a per-chat session store, and dispatches them to the AIAgent for processing. The gateway also runs the cron scheduler, ticking every 60 seconds to execute any due jobs. ## Quick Setup The easiest way to configure messaging platforms is the interactive wizard: ```bash hermes gateway setup # Interactive setup for all messaging platforms ``` This walks you through configuring each platform with arrow-key selection, shows which platforms are already configured, and offers to start/restart the gateway when done. ## Gateway Commands ```bash hermes gateway # Run in foreground hermes gateway setup # Configure messaging platforms interactively hermes gateway install # Install as a user service (Linux) / launchd service (macOS) sudo hermes gateway install --system # Linux only: install a boot-time system service hermes gateway start # Start the default service hermes gateway stop # Stop the default service hermes gateway status # Check default service status hermes gateway status --system # Linux only: inspect the system service explicitly ``` ## Chat Commands (Inside Messaging) | Command | Description | |---------|-------------| | `/new` or `/reset` | Start a fresh conversation | | `/model [provider:model]` | Show or change the model (supports `provider:model` syntax) | | `/personality [name]` | Set a personality | | `/retry` | Retry the last message | | `/undo` | Remove the last exchange | | `/status` | Show session info | | `/whoami` | Show your slash command access on this scope (admin / user / unrestricted) | | `/stop` | Stop the running agent | | `/approve` | Approve a pending dangerous command | | `/deny` | Reject a pending dangerous command | | `/sethome` | Set this chat as the home channel | | `/compress` | Manually compress conversation context | | `/title [name]` | Set or show the session title | | `/resume [name]` | Resume a previously named session | | `/usage` | Show token usage for this session | | `/insights [days]` | Show usage insights and analytics | | `/reasoning [level\|show\|hide]` | Change reasoning effort or toggle reasoning display | | `/voice [on\|off\|tts\|join\|leave\|status]` | Control messaging voice replies and Discord voice-channel behavior | | `/rollback [number]` | List or restore filesystem checkpoints | | `/background <prompt>` | Run a prompt in a separate background session | | `/reload-mcp` | Reload MCP servers from config | | `/update` | Update Hermes Agent to the latest version | | `/help` | Show available commands | | `/<skill-name>` | Invoke any installed skill | ## Session Management ### Session Persistence Sessions persist across messages until they reset. The agent remembers your conversation context. ### Reset Policies Sessions reset based on configurable policies: | Policy | Default | Description | |--------|---------|-------------| | Daily | 4:00 AM | Reset at a specific hour each day | | Idle | 1440 min | Reset after N minutes of inactivity | | Both | (combined) | Whichever triggers first | Configure per-platform overrides in `~/.hermes/gateway.json`: ```json { "reset_by_platform": { "telegram": { "mode": "idle", "idle_minutes": 240 }, "discord": { "mode": "idle", "idle_minutes": 60 } } } ``` ## Security By default, the gateway denies all users who are not in an allowlist or paired via DM. This is the safe default for a bot with terminal access. ```bash # Restrict to specific users (recommended): TELEGRAM_ALLOWED_USERS=123456789,987654321 DISCORD_ALLOWED_USERS=123456789012345678 SIGNAL_ALLOWED_USERS=+1554567,+1556543 SMS_ALLOWED_USERS=+1554567,+1556543 [email protected],[email protected] MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c MATRIX_ALLOWED_USERS=@alice:matrix.org DINGTALK_ALLOWED_USERS=user-id-1 FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy WECOM_ALLOWED_USERS=user-id-1,user-id-2 WECOM_CALLBACK_ALLOWED_USERS=user-id-1,user-id-2 TEAMS_ALLOWED_USERS=aad-object-id-1,aad-object-id-2 # Or allow GATEWAY_ALLOWED_USERS=123456789,987654321 # Or explicitly allow all users (NOT recommended for bots with terminal access): GATEWAY_ALLOW_ALL_USERS=true ``` ### DM Pairing (Alternative to Allowlists) Instead of manually configuring user IDs, unknown users receive a one-time pairing code when they DM the bot: ```bash # The user sees: "Pairing code: XKGH5N7P" # You approve them with: hermes pairing approve telegram XKGH5N7P # Other pairing commands: hermes pairing list # View pending + approved users hermes pairing revoke telegram 123456789 # Remove access ``` Pairing codes expire after 1 hour, are rate-limited, and use cryptographic randomness. ### Admins vs Regular Users Allowlists answer "can this person reach the bot at all?" The admin / user split answers "now that they're in, what are they allowed to do?" Every allowed user falls into one of two tiers per scope (DM vs group/channel): - Admin — full access. Can run every registered slash command (built-in + plugin) and use every gated capability. - Regular user — restricted access. Can chat with the agent normally, but can only run the slash commands you explicitly enable. The always-allowed floor is `/help` and `/whoami`. The tiers are configured per platform and per scope. DM admin status does not imply group/channel admin status — each scope has its own admin list. What the tiers gate today: slash commands. The split runs through the live command registry, so it covers built-ins and plugin-registered commands without per-feature wiring. Plain chat is not affected — non-admins can still talk to the agent. What may be gated in the future: more capability surfaces (tool access, model switching, expensive operations) will hang off the same admin / user distinction as we add them. Configuring the split now means those future restrictions land cleanly without you having to re-model who's an admin. #### Configuration ```yaml gateway: platforms: discord: extra: allow_from: ["111", "222", "333"] allow_admin_from: ["111"] # admins → all slash commands user_allowed_commands: [status, model] # what non-admins may run # Optional: separate group/channel scope group_allow_admin_from: ["111"] group_user_allowed_commands: [status] ``` Backward compat: if `allow_admin_from` is not set for a scope, the tier split is disabled for that scope and every allowed user has full access. Existing installs keep working with no changes — opt in when you want the distinction. #### Inspecting your access Use `/whoami` from any platform to see the active scope, your tier (admin / user / unrestricted), and which slash commands you can run. See the [Telegram](/user-guide/messaging/telegram#slash-command-access-control) and [Discord](/user-guide/messaging/discord#slash-command-access-control) pages for platform-specific examples. ## Interrupting the Agent Send any message while the agent is working to interrupt it. Key behaviors: - In-progress terminal commands are killed immediately (SIGTERM, then SIGKILL after 1s) - Tool calls are cancelled — only the currently-executing one runs, the rest are skipped - Multiple messages are combined — messages sent during interruption are joined into one prompt - `/stop` command — interrupts without queuing a follow-up message ### Queue vs interrupt vs steer (busy-input mode) By default, messaging a busy agent interrupts it. Two other modes are available: - `queue` — follow-up messages wait and run as the next turn after the current task finishes. - `steer` — follow-up messages are injected into the current run via `/steer`, arriving at the agent after the next tool call. No interrupt, no new turn. Falls back to `queue` behavior if the agent hasn't started yet. ```yaml display: busy_input_mode: steer # or queue, or interrupt (default) busy_ack_enabled: true # set to false to suppress the ⚡/⏳/⏩ chat reply entirely ``` The first time you message a busy agent on any platform, Hermes appends a one-line reminder to the busy-ack explaining the knob (`"💡 First-time tip — …"`). The reminder fires once per install — a flag under `onboarding.seen.busy_input_prompt` latches it. Delete that key to see the tip again. If you find the busy-ack noisy — especially with voice input or rapid-fire messages — set `display.busy_ack_enabled: false`. Your input is still queued/steered/interrupts as normal, only the chat reply is silenced. ## Tool Progress Notifications Control how much tool activity is displayed in `~/.hermes/config.yaml`: ```yaml display: tool_progress: all # off | new | all | verbose tool_progress_command: false # set to true to enable /verbose in messaging ``` When enabled, the bot sends status messages as it works: ```text 💻 `ls -la`... 🔍 web_search... 📄 web_extract... 🐍 execute_code... ``` ## Background Sessions Run a prompt in a separate background session so the agent works on it independently while your main chat stays responsive: ``` /background Check all servers in the cluster and report any that are down ``` Hermes confirms immediately: ``` 🔄 Background task started: "Check all servers in the cluster..." Task ID: bg_143022_a1b2c3 ``` ### How It Works Each `/background` prompt spawns a separate agent instance that runs asynchronously: - Isolated session — the background agent has its own session with its own conversation history. It has no knowledge of your current chat context and receives only the prompt you provide. - Same configuration — inherits your model, provider, toolsets, reasoning settings, and provider routing from the current gateway setup. - Non-blocking — your main chat stays fully interactive. Send messages, run other commands, or start more background tasks while it works. - Result delivery — when the task finishes, the result is sent back to the same chat or channel where you issued the command, prefixed with "✅ Background task complete". If it fails, you'll see "❌ Background task failed" with the error. ### Background Process Notifications When the agent running a background session uses `terminal(background=true)` to start long-running processes (servers, builds, etc.), the gateway can push status updates to your chat. Control this with `display.background_process_notifications` in `~/.hermes/config.yaml`: ```yaml display: background_process_notifications: all # all | result | error | off ``` | Mode | What you receive | |------|-----------------| | `all` | Running-output updates and the final completion message (default) | | `result` | Only the final completion message (regardless of exit code) | | `error` | Only the final message when the exit code is non-zero | | `off` | No process watcher messages at all | You can also set this via environment variable: ```bash HERMES_BACKGROUND_NOTIFICATIONS=result ``` ### Use Cases - Server monitoring — "/background Check the health of all services and alert me if anything is down" - Long builds — "/background Build and deploy the staging environment" while you continue chatting - Research tasks — "/background Research competitor pricing and summarize in a table" - File operations — "/background Organize the photos in ~/Downloads by date into folders" :::tip Background tasks on messaging platforms are fire-and-forget — you don't need to wait or check on them. Results arrive in the same chat automatically when the task finishes. ::: ## Service Management ### Linux (systemd) ```bash hermes gateway install # Install as user service hermes gateway start # Start the service hermes gateway stop # Stop the service hermes gateway status # Check status journalctl --user -u hermes-gateway -f # View logs # Enable lingering (keeps running after logout) sudo loginctl enable-linger $USER # Or install a boot-time system service that still runs as your user sudo hermes gateway install --system sudo hermes gateway start --system sudo hermes gateway status --system journalctl -u hermes-gateway -f ``` Use the user service on laptops and dev boxes. Use the system service on VPS or headless hosts that should come back at boot without relying on systemd linger. Avoid keeping both the user and system gateway units installed at once unless you really mean to. Hermes will warn if it detects both because start/stop/status behavior gets ambiguous. :::info Multiple installations If you run multiple Hermes installations on the same machine (with different `HERMES_HOME` directories), each gets its own systemd service name. The default `~/.hermes` uses `hermes-gateway`; other installations use `hermes-gateway-<hash>`. The `hermes gateway` commands automatically target the correct service for your current `HERMES_HOME`. ::: ### macOS (launchd) ```bash hermes gateway install # Install as launchd agent hermes gateway start # Start the service hermes gateway stop # Stop the service hermes gateway status # Check status tail -f ~/.hermes/logs/gateway.log # View logs ``` The generated plist lives at `~/Library/LaunchAgents/ai.hermes.gateway.plist`. It includes three environment variables: - PATH — your full shell PATH at install time, with the venv `bin/` and `node_modules/.bin` prepended. This ensures user-installed tools (Node.js, ffmpeg, etc.) are available to gateway subprocesses like the WhatsApp bridge. - VIRTUAL_ENV — points to the Python virtualenv so tools can resolve packages correctly. - HERMES_HOME — scopes the gateway to your Hermes installation. :::tip PATH changes after install launchd plists are static — if you install new tools (e.g. a new Node.js version via nvm, or ffmpeg via Homebrew) after setting up the gateway, run `hermes gateway install` again to capture the updated PATH. The gateway will detect the stale plist and reload automatically. ::: :::info Multiple installations Like the Linux systemd service, each `HERMES_HOME` directory gets its own launchd label. The default `~/.hermes` uses `ai.hermes.gateway`; other installations use `ai.hermes.gateway-<suffix>`. ::: ## Platform-Specific Toolsets Each platform has its own toolset: | Platform | Toolset | Capabilities | |----------|---------|--------------| | CLI | `hermes-cli` | Full access | | Telegram | `hermes-telegram` | Full tools including terminal | | Discord | `hermes-discord` | Full tools including terminal | | WhatsApp | `hermes-whatsapp` | Full tools including terminal | | Slack | `hermes-slack` | Full tools including terminal | | Google Chat | `hermes-google_chat` | Full tools including terminal | | Signal | `hermes-signal` | Full tools including terminal | | SMS | `hermes-sms` | Full tools including terminal | | Email | `hermes-email` | Full tools including terminal | | Home Assistant | `hermes-homeassistant` | Full tools + HA device control (ha_list_entities, ha_get_state, ha_call_service, ha_list_services) | | Mattermost | `hermes-mattermost` | Full tools including terminal | | Matrix | `hermes-matrix` | Full tools including terminal | | DingTalk | `hermes-dingtalk` | Full tools including terminal | | Feishu/Lark | `hermes-feishu` | Full tools including terminal | | WeCom | `hermes-wecom` | Full tools including terminal | | WeCom Callback | `hermes-wecom-callback` | Full tools including terminal | | Weixin | `hermes-weixin` | Full tools including terminal | | BlueBubbles | `hermes-bluebubbles` | Full tools including terminal | | QQBot | `hermes-qqbot` | Full tools including terminal | | Yuanbao | `hermes-yuanbao` | Full tools including terminal | | Microsoft Teams | `hermes-teams` | Full tools including terminal | | API Server | `hermes-api-server` | Full tools (drops `clarify`, `send_message`, `text_to_speech` — programmatic access doesn't have an interactive user) | | Webhooks | `hermes-webhook` | Full tools including terminal | ## Operating a multi-platform gateway A gateway typically runs several adapters at once (Telegram + Discord + Slack, etc.). The sections below cover day-2 operations that span all platforms. ### `/platform` command Once the gateway is running, use the `/platform` slash command from any connected CLI session or chat to inspect and steer individual adapters without restarting the whole gateway: ``` /platform list # show all adapters and their state /platform pause <name> # stop dispatching new messages to one adapter /platform resume <name> # re-enable a paused adapter ``` `/platform list` shows whether each adapter is `running`, `paused` (manually), or `paused-by-breaker` (see below). Pausing keeps the adapter loaded and its background loops alive — incoming messages are dropped on the floor, but the connection itself stays open so resume is instant. See also the broader status summary command [`/platforms`](../../reference/slash-commands.md#info). ### Automatic circuit breaker Each adapter is wrapped in a circuit breaker. Repeated retryable failures (network blips, rate-limit replies, 5xx upstream responses, websocket disconnects) cause the breaker to trip — the adapter is auto-paused, an operator notification is sent to the home channel of another live platform when one is configured, and a structured log line is emitted. The breaker does not auto-resume — it stays open until you run `/platform resume <name>` manually. This is intentional: if a platform is in a sustained outage, you don't want the gateway thrashing reconnects. ### Where to look when a platform is paused When an adapter is paused, check: 1. Gateway log (`~/.hermes/logs/gateway.log` or the systemd / launchd unit log). Search for the platform name and `circuit breaker`, `paused`, or `disabled`. The trip event includes the failure count and the last error. 2. `/platform list` output — shows the current state and last reason. 3. The provider's status page (Telegram bot API status, Discord status, etc.). The breaker tripped because the platform was unhealthy; don't try to resume until it's back. Once upstream is healthy, `/platform resume <name>` clears the breaker and re-arms the adapter. ### Restart notifications When the gateway restarts (or is shut down with in-flight sessions), it can send a one-shot "the agent is back" / "the agent was interrupted" message to each platform's home channel. This is controlled per-platform by the `gateway_restart_notification` flag in `gateway-config.yaml`, which defaults to `true`: ```yaml gateway: platforms: telegram: home_chat_id: "123456789" gateway_restart_notification: false # opt out for this platform discord: home_chat_id: "987654321" # gateway_restart_notification omitted → defaults to true ``` Disable it on noisy or low-priority platforms while leaving it on for your primary chat. The notification is sent once per restart, regardless of how many sessions were in flight. ### Session resume across gateway restarts When the gateway shuts down with an in-flight tool call or generation, the affected sessions are flagged as `restart_interrupted`. On the next startup, the gateway schedules an auto-resume for each one — the user gets a short heads-up in the chat ("Send any message after restart and I'll try to resume where you left off.") and the session picks up from the last committed turn when they reply. This behaviour is on by default and is logged at gateway start: ``` Scheduled auto-resume for N restart-interrupted session(s) ``` No configuration is required. If you don't want the heads-up, set `gateway_restart_notification: false` on the platform. ### Mobile-friendly progress defaults Telegram is usually a mobile inbox, so the defaults are tuned for that surface: - `tool_progress` defaults to `off` — no per-tool breadcrumb stream filling up the chat. - `busy_ack_detail` defaults to `off` — busy-state acknowledgments and long-running heartbeats stay terse (no `iteration 21/60` debug detail). - `interim_assistant_messages` stays on — real mid-turn assistant commentary (the model literally telling you what it's about to do) is signal, not noise. - `long_running_notifications` stays on — a single edit-in-place "⏳ Working — N min" bubble updates every few minutes so you have a heartbeat instead of staring at `typing…` for half an hour. Opt out of either of the kept-on defaults or opt back into verbose progress per platform: ```yaml display: platforms: telegram: # Re-enable the tool-progress stream tool_progress: new # Show "iteration N/M, running: tool" in heartbeats and busy acks busy_ack_detail: true # Or quiet them entirely interim_assistant_messages: false long_running_notifications: false ``` ### Progress bubble cleanup (opt-in) Tool-progress messages, the "still working…" heartbeat, and status-callback bubbles can also be auto-deleted after the final response lands. Enable per-platform via `display.platforms.<platform>.cleanup_progress`: ```yaml display: platforms: telegram: cleanup_progress: true discord: cleanup_progress: true ``` Defaults to `false`. Only platforms whose adapter implements `delete_message` honor the setting (currently Telegram and Discord). Failed runs skip cleanup so the bubbles remain as breadcrumbs. ## Next Steps - [Telegram Setup](telegram.md) - [Discord Setup](discord.md) - [Slack Setup](slack.md) - [Google Chat Setup](google_chat.md) - [WhatsApp Setup](whatsapp.md) - [Signal Setup](signal.md) - [SMS Setup (Twilio)](sms.md) - [Email Setup](email.md) - [Home Assistant Integration](homeassistant.md) - [Mattermost Setup](mattermost.md) - [Matrix Setup](matrix.md) - [DingTalk Setup](dingtalk.md) - [Feishu/Lark Setup](feishu.md) - [WeCom Setup](wecom.md) - [WeCom Callback Setup](wecom-callback.md) - [Weixin Setup (WeChat)](weixin.md) - [BlueBubbles Setup (iMessage)](bluebubbles.md) - [QQBot Setup](qqbot.md) - [Yuanbao Setup](yuanbao.md) - [Microsoft Teams Setup](teams.md) - [Teams Meetings Pipeline](teams-meetings.md) - [Open WebUI + API Server](open-webui.md) - [Webhooks](webhooks.md) ---  # Telegram # Telegram Setup Hermes Agent integrates with Telegram as a full-featured conversational bot. Once connected, you can chat with your agent from any device, send voice memos that get auto-transcribed, receive scheduled task results, and use the agent in group chats. The integration is built on [python-telegram-bot](https://python-telegram-bot.org/) and supports text, voice, images, and file attachments. ## Step 1: Create a Bot via BotFather Every Telegram bot requires an API token issued by [@BotFather](https://t.me/BotFather), Telegram's official bot management tool. 1. Open Telegram and search for @BotFather, or visit [t.me/BotFather](https://t.me/BotFather) 2. Send `/newbot` 3. Choose a display name (e.g., "Hermes Agent") — this can be anything 4. Choose a username — this must be unique and end in `bot` (e.g., `my_hermes_bot`) 5. BotFather replies with your API token. It looks like this: ``` 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ ``` :::warning Keep your bot token secret. Anyone with this token can control your bot. If it leaks, revoke it immediately via `/revoke` in BotFather. ::: ## Step 2: Customize Your Bot (Optional) These BotFather commands improve the user experience. Message @BotFather and use: | Command | Purpose | |---------|---------| | `/setdescription` | The "What can this bot do?" text shown before a user starts chatting | | `/setabouttext` | Short text on the bot's profile page | | `/setuserpic` | Upload an avatar for your bot | | `/setcommands` | Define the command menu (the `/` button in chat) | | `/setprivacy` | Control whether the bot sees all group messages (see Step 3) | :::tip For `/setcommands`, a useful starting set: ``` help - Show help information new - Start a new conversation sethome - Set this chat as the home channel ``` ::: ## Step 3: Privacy Mode (Critical for Groups) Telegram bots have a privacy mode that is enabled by default. This is the single most common source of confusion when using bots in groups. With privacy mode ON, your bot can only see: - Messages that start with a `/` command - Replies directly to the bot's own messages - Service messages (member joins/leaves, pinned messages, etc.) - Messages in channels where the bot is an admin With privacy mode OFF, the bot receives every message in the group. ### How to disable privacy mode 1. Message @BotFather 2. Send `/mybots` 3. Select your bot 4. Go to Bot Settings → Group Privacy → Turn off :::warning You must remove and re-add the bot to any group after changing the privacy setting. Telegram caches the privacy state when a bot joins a group, and it will not update until the bot is removed and re-added. ::: :::tip An alternative to disabling privacy mode: promote the bot to group admin. Admin bots always receive all messages regardless of the privacy setting, and this avoids needing to toggle the global privacy mode. ::: ### Observe group chatter without auto-replying For OpenClaw/Yuanbao-style group behavior, configure Telegram so the bot can see ordinary group messages but only responds when directly triggered: ```yaml telegram: allowed_chats: - "-1001234567890" group_allowed_chats: - "-1001234567890" require_mention: true observe_unmentioned_group_messages: true ``` With this mode enabled, unmentioned group messages from explicitly allowlisted chats/topics are appended to the shared chat/topic session transcript as observed context, but they do not dispatch the agent. `allowed_chats` gates where the bot responds; `group_allowed_chats` authorizes the shared group session used for observed context, so use the same chat IDs for this mode. A later `@botname` mention, reply to the bot, or configured mention pattern in that same allowlisted chat/topic can use that observed context. The triggered message is also tagged with `[nickname|user_id]` and gets a per-turn safety prompt so the model treats prior observed lines as context, not instructions addressed to the bot. Equivalent environment variable: ```bash TELEGRAM_ALLOWED_CHATS=-1001234567890 TELEGRAM_GROUP_ALLOWED_CHATS=-1001234567890 TELEGRAM_OBSERVE_UNMENTIONED_GROUP_MESSAGES=true ``` This requires Telegram to deliver ordinary group messages to the gateway, so disable BotFather privacy mode or promote the bot to group admin as described above. ## Step 4: Find Your User ID Hermes Agent uses numeric Telegram user IDs to control access. Your user ID is not your username — it's a number like `123456789`. Method 1 (recommended): Message [@userinfobot](https://t.me/userinfobot) — it instantly replies with your user ID. Method 2: Message [@get_id_bot](https://t.me/get_id_bot) — another reliable option. Save this number; you'll need it for the next step. ## Step 5: Configure Hermes ### Option A: Interactive Setup (Recommended) ```bash hermes gateway setup ``` Select Telegram when prompted. The wizard asks for your bot token and allowed user IDs, then writes the configuration for you. ### Option B: Manual Configuration Add the following to `~/.hermes/.env`: ```bash TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ TELEGRAM_ALLOWED_USERS=123456789 # Comma-separated for multiple users ``` ### Start the Gateway ```bash hermes gateway ``` The bot should come online within seconds. Send it a message on Telegram to verify. ## Sending Generated Files from Docker-backed Terminals If your terminal backend is `docker`, keep in mind that Telegram attachments are sent by the gateway process, not from inside the container. That means the final `MEDIA:/...` path must be readable on the host where the gateway is running. Common pitfall: - the agent writes a file inside Docker to `/workspace/report.txt` - the model emits `MEDIA:/workspace/report.txt` - Telegram delivery fails because `/workspace/report.txt` only exists inside the container, not on the host Recommended pattern: ```yaml terminal: backend: docker docker_volumes: - "/home/user/.hermes/cache/documents:/output" ``` Then: - write files inside Docker to `/output/...` - emit the host-visible path in `MEDIA:`, for example: `MEDIA:/home/user/.hermes/cache/documents/report.txt` If you already have a `docker_volumes:` section, add the new mount to the same list. YAML duplicate keys silently override earlier ones. ### Supported `MEDIA:` file extensions The gateway extracts `MEDIA:/path/to/file` tags from agent replies and ships the referenced file as a platform-native attachment. Supported extensions across all gateway platforms: | Category | Extensions | |---|---| | Images | `png`, `jpg`, `jpeg`, `gif`, `webp`, `bmp`, `tiff`, `svg` | | Audio | `mp3`, `wav`, `ogg`, `m4a`, `opus`, `flac`, `aac` | | Video | `mp4`, `mov`, `webm`, `mkv`, `avi` | | Documents | `pdf`, `txt`, `md`, `csv`, `json`, `xml`, `html`, `yaml`, `yml`, `log` | | Office | `docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp` | | Archives | `zip`, `rar`, `7z`, `tar`, `gz`, `bz2` | | Books / packages | `epub`, `apk`, `ipa` | Anything on this list delivered as a native attachment on platforms that support it (Telegram, Discord, Signal, Slack, WhatsApp, Feishu, Matrix, etc.); on platforms without native support it falls back to a link or plain-text indicator. The bold categories were added in the last few releases — if you were relying on the model saying `here is the file: /path/to/report.docx` instead, swap to `MEDIA:/path/to/report.docx` for native delivery. ## Webhook Mode By default, Hermes connects to Telegram using long polling — the gateway makes outbound requests to Telegram's servers to fetch new updates. This works well for local and always-on deployments. For cloud deployments (Fly.io, Railway, Render, etc.), webhook mode is more cost-effective. These platforms can auto-wake suspended machines on inbound HTTP traffic, but not on outbound connections. Since polling is outbound, a polling bot can never sleep. Webhook mode flips the direction — Telegram pushes updates to your bot's HTTPS URL, enabling sleep-when-idle deployments. | | Polling (default) | Webhook | |---|---|---| | Direction | Gateway → Telegram (outbound) | Telegram → Gateway (inbound) | | Best for | Local, always-on servers | Cloud platforms with auto-wake | | Setup | No extra config | Set `TELEGRAM_WEBHOOK_URL` | | Idle cost | Machine must stay running | Machine can sleep between messages | ### Configuration Add the following to `~/.hermes/.env`: ```bash TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram TELEGRAM_WEBHOOK_SECRET="$(openssl rand -hex 32)" # required # TELEGRAM_WEBHOOK_PORT=8443 # optional, default 8443 ``` | Variable | Required | Description | |----------|----------|-------------| | `TELEGRAM_WEBHOOK_URL` | Yes | Public HTTPS URL where Telegram will send updates. The URL path is auto-extracted (e.g., `/telegram` from the example above). | | `TELEGRAM_WEBHOOK_SECRET` | Yes (when `TELEGRAM_WEBHOOK_URL` is set) | Secret token that Telegram echoes in every webhook request for verification. The gateway refuses to start without it — see [GHSA-3vpc-7q5r-276h](https://github.com/NousResearch/hermes-agent/security/advisories/GHSA-3vpc-7q5r-276h). Generate with `openssl rand -hex 32`. | | `TELEGRAM_WEBHOOK_PORT` | No | Local port the webhook server listens on (default: `8443`). | When `TELEGRAM_WEBHOOK_URL` is set, the gateway starts an HTTP webhook server instead of polling. When unset, polling mode is used — no behavior change from previous versions. ### Cloud deployment example (Fly.io) 1. Add the env vars to your Fly.io app secrets: ```bash fly secrets set TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram fly secrets set TELEGRAM_WEBHOOK_SECRET=$(openssl rand -hex 32) ``` 2. Expose the webhook port in your `fly.toml`: ```toml [[services]] internal_port = 8443 protocol = "tcp" [[services.ports]] handlers = ["tls", "http"] port = 443 ``` 3. Deploy: ```bash fly deploy ``` The gateway log should show: `[telegram] Connected to Telegram (webhook mode)`. ## Proxy Support If Telegram's API is blocked or you need to route traffic through a proxy, set a Telegram-specific proxy URL. This takes priority over the generic `HTTPS_PROXY` / `HTTP_PROXY` env vars. Option 1: config.yaml (recommended) ```yaml telegram: proxy_url: "socks5://127.0.0.1:1080" ``` Option 2: environment variable ```bash TELEGRAM_PROXY=socks5://127.0.0.1:1080 ``` Supported schemes: `http://`, `https://`, `socks5://`. The proxy applies to both the main Telegram connection and the fallback IP transport. If no Telegram-specific proxy is set, the gateway falls back to `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` (or macOS system proxy auto-detection). ## Home Channel Use the `/sethome` command in any Telegram chat (DM or group) to designate it as the home channel. Scheduled tasks (cron jobs) deliver their results to this channel. You can also set it manually in `~/.hermes/.env`: ```bash TELEGRAM_HOME_CHANNEL=-1001234567890 TELEGRAM_HOME_CHANNEL_NAME="My Notes" ``` :::tip Group chat IDs are negative numbers (e.g., `-1001234567890`). Your personal DM chat ID is the same as your user ID. ::: ### Cron deliveries in topic mode If you have topic mode enabled in your bot DM, cron messages delivered to the root chat land in the system-only lobby — replying there opens no session and you see the "main chat is reserved for system commands" notice. Create a dedicated forum topic (e.g. `Cron`) and set: ```bash TELEGRAM_CRON_THREAD_ID=<topic_thread_id> ``` `TELEGRAM_CRON_THREAD_ID` overrides `TELEGRAM_HOME_CHANNEL_THREAD_ID` for cron deliveries only. Replies in that topic continue the topic's existing session. ## Voice Messages ### Incoming Voice (Speech-to-Text) Voice messages you send on Telegram are automatically transcribed by Hermes's configured STT provider and injected as text into the conversation. - `local` uses `faster-whisper` on the machine running Hermes — no API key required - `groq` uses Groq Whisper and requires `GROQ_API_KEY` - `openai` uses OpenAI Whisper and requires `VOICE_TOOLS_OPENAI_KEY` #### Skipping STT: pass the raw audio file to the agent If you'd rather have the agent itself handle audio — for diarization, a custom transcription tool, or just archiving the recording — set `stt.enabled: false` in `~/.hermes/config.yaml`: ```yaml stt: enabled: false ``` With STT disabled, the gateway still downloads the voice/audio attachment into Hermes's audio cache, but does not transcribe it. The agent receives the message with a marker like: ``` [The user sent a voice message: /home/<user>/.hermes/cache/audio/<hash>.ogg] ``` Your tools or skills can then read that path directly (e.g., hand it off to a local diarization pipeline, a richer transcription model, or upload it to long-term storage). The file extension reflects the original format Telegram delivered (`.ogg` for voice notes, `.mp3`/`.m4a`/etc. for audio attachments). This pairs naturally with the [local Bot API server](#large-files-20mb-via-local-bot-api-server) section below, which lifts Telegram's 20MB getFile ceiling to 2GB — useful when the recordings you want to process are longer than a couple of minutes. ### Outgoing Voice (Text-to-Speech) When the agent generates audio via TTS, it's delivered as native Telegram voice bubbles — the round, inline-playable kind. - OpenAI and ElevenLabs produce Opus natively — no extra setup needed - Edge TTS (the default free provider) outputs MP3 and requires ffmpeg to convert to Opus: ```bash # Ubuntu/Debian sudo apt install ffmpeg # macOS brew install ffmpeg ``` Without ffmpeg, Edge TTS audio is sent as a regular audio file (still playable, but uses the rectangular player instead of a voice bubble). Configure the TTS provider in your `config.yaml` under the `tts.provider` key. ## Large Files (>20MB) via Local Bot API Server Telegram's public Bot API caps `getFile` downloads at 20 MB, so any voice note, audio file, video, or document larger than that is silently rejected by Hermes with a "too large" reply. The documented way around this is to run a local [telegram-bot-api](https://github.com/tdlib/telegram-bot-api) daemon — the same server software Telegram uses, but running on your network. A local server raises the file ceiling to 2 GB and Hermes auto-lifts its own internal cap when it sees a custom `base_url` configured. This unlocks workflows like: - Sending long voice memos (45-minute meetings, podcasts) to the bot - Uploading large videos for vision-tool processing - Archiving raw audio for offline pipelines like diarization, alignment, or training data ### Step 1: Obtain Telegram API credentials The local server talks directly to Telegram's MTProto layer (not the public Bot API), so it needs MTProto credentials: 1. Visit [my.telegram.org/apps](https://my.telegram.org/apps) and sign in with your Telegram account. 2. Create a new application (any name and short description will do). 3. Copy the `api_id` and `api_hash` — both are required. ### Step 2: Run the telegram-bot-api server The community-maintained [`aiogram/telegram-bot-api`](https://hub.docker.com/r/aiogram/telegram-bot-api) Docker image is the easiest path. A minimal `docker-compose.yaml` (use `--local` mode to enable the higher limits): ```yaml services: tg-bot-api: image: aiogram/telegram-bot-api:latest container_name: tg-bot-api restart: unless-stopped ports: - "127.0.0.1:8081:8081" # bind to loopback only; see security note environment: TELEGRAM_API_ID: "12345" # your api_id from Step 1 TELEGRAM_API_HASH: "abcdef..." # your api_hash from Step 1 TELEGRAM_LOCAL: "1" # enable --local mode (raises 20MB → 2GB) volumes: - ./tg-bot-api-data:/var/lib/telegram-bot-api ``` Bring it up: ```bash docker compose up -d tg-bot-api docker logs --tail 20 tg-bot-api ``` :::warning Security The local Bot API server takes your bot token in the URL path (e.g. `/bot<TOKEN>/getMe`) with no additional auth. Anyone who can reach the port can fully control your bot — read every message it can see, send messages as it, etc. Bind the container to `127.0.0.1` and/or front it with a reverse proxy on a private network. Never expose port 8081 to the public internet. ::: ### Step 3: Log the bot out of the public API (one-time) A bot can only be active on one Bot API server at a time. If your bot was already running against `api.telegram.org` (which it almost certainly was), you must explicitly log it out there before the local server will accept it: ```bash curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/logOut" # expected response: {"ok":true,"result":true} ``` This is a one-shot migration step — you don't repeat it on every restart. Telegram delivers any messages received after `logOut` through the new server instead. Verify the local server can talk to Telegram on the bot's behalf: ```bash curl "http://127.0.0.1:8081/bot<YOUR_BOT_TOKEN>/getMe" # expected response: {"ok":true,"result":{"id":...,"is_bot":true,...}} ``` ### Step 4: Point Hermes at the local server Add the URLs under `platforms.telegram.extra` in `~/.hermes/config.yaml`: ```yaml platforms: telegram: extra: base_url: "http://127.0.0.1:8081/bot" base_file_url: "http://127.0.0.1:8081/file/bot" local_mode: true # see Step 5 below — only set this if the bot's data # directory is readable by the Hermes process ``` :::caution Use `platforms.telegram.extra`, not `telegram.extra` At the moment only the `platforms.<name>.extra` form is deep-merged into the platform config. Keys placed directly under a top-level `telegram.extra` block are silently dropped. ::: When `base_url` is set, Hermes: - Builds the python-telegram-bot client against the local server - Auto-lifts its internal document/audio size cap from 20 MB → 2 GB - Reports the active limit in the "too large" error message (`Maximum: 2048 MB.`) so it's obvious which mode you're in Restart the gateway and look for a confirmation log line: ```bash hermes gateway restart grep -E "Using custom Telegram base_url|Using Telegram local_mode" ~/.hermes/logs/gateway.log | tail ``` ### Step 5: `local_mode` — file access on disk The local server has two ways to deliver files: 1. Without `--local` (the default): files are served over HTTP at `/file/bot<TOKEN>/<path>`, same as the public Bot API. The 20MB ceiling stays in effect. Useful as a network-fix only (e.g. when `api.telegram.org` is unreachable but you can self-host); not what you want for the size lift. 2. With `--local` (set via `TELEGRAM_LOCAL=1` above): files are written to the server's filesystem and the `getFile` response returns an absolute path instead of an HTTP URL. The 20MB ceiling is lifted. Hermes must then read the bytes from disk, not over HTTP. To make the disk-read path work, set `local_mode: true` in the config above and make sure the Hermes process can read the path the server returns. Two scenarios: - Same machine — telegram-bot-api and Hermes run on the same host. Bind-mount the data volume to a directory that Hermes can read (e.g., `/var/lib/telegram-bot-api`), and make sure the file ownership matches. The container drops privileges to its internal `telegram-bot-api` user (uid varies by image); the simplest fix is to add `user: "<UID>:<GID>"` to the compose service so files are owned by a uid Hermes already runs as. - Different machines — the bot server runs on one host (e.g., a NAS, a separate VM) and Hermes on another. The server's data directory must be shared with the Hermes machine at the same absolute path the server reports (typically `/var/lib/telegram-bot-api`). NFS works well for this; CIFS/SMB with `uid=` mount remapping is friendlier if you don't want to deal with uid mismatches at the filesystem level. If `local_mode: true` is set but Hermes can't `stat` the returned file path (permissions or wrong mount), python-telegram-bot silently falls back to an HTTP `getFile` against the local server — which in `--local` mode responds with `404 Not Found`. The symptom shows up in `gateway.log` as: ``` [Telegram] Failed to cache voice: Not Found telegram.error.InvalidToken: Not Found ``` If you see that, the cap-lift is working but the file-share isn't. Verify `ls -la /var/lib/telegram-bot-api/<TOKEN>/voice/` from the Hermes host as the user the gateway runs as, and confirm a single file is `cat`-able without a permission error. ### Step 6: Test it Send the bot a voice note or audio file that's bigger than 20 MB. Tail the gateway log: ```bash tail -f ~/.hermes/logs/gateway.log | grep -iE "telegram|cache" ``` You should see a `[Telegram] Cached user voice at /home/<user>/.hermes/cache/audio/...` line and no "too large" rejection. Combined with `stt.enabled: false` (above), the path to the original audio file then lands in the agent's inbound message for downstream processing. ## Group Chat Usage Hermes Agent works in Telegram group chats with a few considerations: - Privacy mode determines what messages the bot can see (see [Step 3](#step-3-privacy-mode-critical-for-groups)) - `TELEGRAM_ALLOWED_USERS` still applies — only authorized users can trigger the bot, even in groups - You can keep the bot from responding to ordinary group chatter with `telegram.require_mention: true` - With `telegram.require_mention: true`, group messages are accepted when they are: - replies to one of the bot's messages - `@botusername` mentions - `/command@botusername` (Telegram's bot-menu command form that includes the bot name) - matches for one of your configured regex wake words in `telegram.mention_patterns` - In groups with multiple Hermes bots, `telegram.exclusive_bot_mentions` keeps routing deterministic. When a message explicitly mentions one or more Telegram bot usernames, only the mentioned bot profiles process it; other Hermes bots ignore it before reply and wake-word fallbacks run. This is enabled by default. - Use `telegram.ignored_threads` to keep Hermes silent in specific Telegram forum topics, even when the group would otherwise allow free responses or mention-triggered replies - If `telegram.require_mention` is left unset or false, Hermes keeps the previous open-group behavior and responds to normal group messages it can see ### Multiple Hermes bots in one group If you run several Hermes profiles in the same Telegram group, create one Telegram bot token per profile and start one gateway per profile. Do not reuse the same bot token in multiple running gateways; Telegram will reject concurrent polling for the same token. Recommended group config: ```yaml telegram: require_mention: true exclusive_bot_mentions: true mention_patterns: [] ``` With this setup, a group message like `@research_bot @ops_bot summarize this` is processed by `research_bot` and `ops_bot` only. Other Hermes bots in the group stay silent, even if the message is a reply to one of their earlier messages or would otherwise match a shared wake word. Set `exclusive_bot_mentions: false` only for legacy groups where explicit mentions should not override reply and wake-word triggers. To operate several profiles, run the gateway command once per profile. For example: ```bash # default profile hermes gateway start hermes gateway status hermes gateway stop # named profiles hermes -p research gateway start hermes -p research gateway status hermes -p research gateway stop ``` For a small fixed fleet, use a shell loop or script that calls `hermes gateway <action>` for the default profile and `hermes -p <profile> gateway <action>` for each named profile. This is more reliable than assuming a single process-level command controls every named profile on every service manager. ### Troubleshooting: works in DMs but not groups If the bot responds in a private chat but stays silent in a group, check these gates in order: 1. Telegram delivery: turn off BotFather privacy mode, promote the bot to admin, or mention the bot directly. Hermes cannot respond to group messages that Telegram never delivers to the bot. 2. Rejoin after changing privacy: remove the bot from the group and add it again after changing BotFather privacy settings. Telegram may keep the old delivery behavior for existing memberships. 3. Hermes authorization: make sure the sender is listed in `TELEGRAM_ALLOWED_USERS` or `TELEGRAM_GROUP_ALLOWED_USERS`, or allow the group chat with `TELEGRAM_GROUP_ALLOWED_CHATS`. 4. Mention filters: if `telegram.require_mention: true` is set, normal group chatter is ignored unless the message is a slash command, reply to the bot, `@botusername` mention, or configured `mention_patterns` match. 5. Multi-bot routing:** if a group contains several bots, make sure each Hermes profile uses a unique bot token and keep `exclusive_bot_mentions` enabled unless you intentionally want legacy shared-trigger behavior. Negative chat IDs are normal for Telegram groups and supergroups. If you use chat-scoped authorization, put those IDs in `TELEGRAM_GROUP_ALLOWED_CHATS`, not the sender-user allowlist. ### Example group trigger configuration Add this to `~/.hermes/config.yaml`: ```yaml telegram: require_mention: true exclusive_bot_mentions: true mention_patterns: - "^\\schompy\\b" ignored_threads: - 31 - "42" ``` This example allows all the usual direct triggers plus messages that begin with `chompy`, even if they do not use an `@mention`. Messages in Telegram topics `31` and `42` are always ignored before the mention and free-response checks run. ### Notes on `mention_patterns` - Patterns use Python regular expressions - Matching is case-insensitive - Patterns are checked against both text messages and media captions - Invalid regex patterns are ignored with a warning in the gateway logs rather than crashing the bot - If you want a pattern to match only at the start of a message, anchor it with `^` ## Private Chat Topics (Bot API 9.4) Telegram Bot API 9.4 (February 2026) introduced Private Chat Topics — bots can create forum-style topic threads directly in 1-on-1 DM chats, no supergroup needed. This lets you run multiple isolated workspaces within your existing DM with Hermes. ### Use case If you work on several long-running projects, topics keep their context separate: - Topic "Website" — work on your production web service - Topic "Research" — literature review and paper exploration - Topic "General" — miscellaneous tasks and quick questions Each topic gets its own conversation session, history, and context — completely isolated from the others. ### Configuration :::caution Prerequisites Before adding topics to your config, the user must enable Topics mode in the DM chat with the bot: 1. Open your private chat with the Hermes bot in Telegram 2. Tap the bot's name at the top to open chat info 3. Enable Topics (the toggle to turn the chat into a forum) Without this, Hermes will log `The chat is not a forum` on startup and skip topic creation. This is a Telegram client-side setting — the bot cannot enable it programmatically. ::: Add topics under `platforms.telegram.extra.dm_topics` in `~/.hermes/config.yaml`: ```yaml platforms: telegram: extra: dm_topics: - chat_id: 123456789 # Your Telegram user ID topics: - name: General icon_color: 7322096 - name: Website icon_color: 9367192 - name: Research icon_color: 16766590 skill: arxiv # Auto-load a skill in this topic ``` Fields: | Field | Required | Description | |-------|----------|-------------| | `name` | Yes | Topic display name | | `icon_color` | No | Telegram icon color code (integer) | | `icon_custom_emoji_id` | No | Custom emoji ID for the topic icon | | `skill` | No | Skill to auto-load on new sessions in this topic | | `thread_id` | No | Auto-populated after topic creation — don't set manually | ### How it works 1. On gateway startup, Hermes calls `createForumTopic` for each topic that doesn't have a `thread_id` yet 2. The `thread_id` is saved back to `config.yaml` automatically — subsequent restarts skip the API call 3. Each topic maps to an isolated session key: `agent:main:telegram:dm:{chat_id}:{thread_id}` 4. Messages in each topic have their own conversation history, memory flush, and context window ### Root DM handling By default, messages sent to the root DM (outside any topic) are processed normally. Set `ignore_root_dm: true` to turn the root DM into a lobby — normal messages are silently ignored for users who have DM topics configured, while system commands (`/start`, `/help`, `/status`, etc.) still work. ```yaml platforms: telegram: extra: ignore_root_dm: true dm_topics: - chat_id: 123456789 topics: - name: General ``` The check is per-chat: only users with at least one entry in `dm_topics` will have their root DM affected. Users without configured topics are unaffected. ### Skill binding Topics with a `skill` field automatically load that skill when a new session starts in the topic. This works exactly like typing `/skill-name` at the start of a conversation — the skill content is injected into the first message, and subsequent messages see it in the conversation history. For example, a topic with `skill: arxiv` will have the arxiv skill pre-loaded whenever its session resets (due to idle timeout, daily reset, or manual `/reset`). :::tip Topics created outside of the config (e.g., by manually calling the Telegram API) are discovered automatically when a `forum_topic_created` service message arrives. You can also add topics to the config while the gateway is running — they'll be picked up on the next cache miss. ::: ## Multi-session DM mode (`/topic`) A ChatGPT-style multi-session DM — one bot, many parallel conversations. Unlike the operator-curated `extra.dm_topics` above, this mode is user-driven: no config, no pre-declared topic names. The end user flips it on with `/topic`, then taps the Telegram + button to create as many topics as they want, each one a fully independent Hermes session. ### `/topic` subcommands | Form | Context | Effect | |------|---------|--------| | `/topic` | Root DM, not yet enabled | Check BotFather capabilities, enable multi-session mode, create pinned System topic | | `/topic` | Root DM, already enabled | Show status: unlinked sessions available for restore | | `/topic` | Inside a topic | Show the current topic's session binding | | `/topic help` | Any | Inline usage | | `/topic off` | Root DM | Disable multi-session mode and clear all topic bindings for this chat | | `/topic <session-id>` | Inside a topic | Restore a previous Telegram session into the current topic | Only authorized users (allowlist via `TELEGRAM_ALLOWED_USERS` / platform auth config) can run `/topic`. An unauthorized sender gets a refusal instead of activation. ### DM Topics vs Multi-session DM mode | | `extra.dm_topics` (config-driven) | `/topic` (user-driven) | |---|---|---| | Who activates it | Operator, in `config.yaml` | End user, by sending `/topic` | | Topic list | Fixed set declared in config | User creates/deletes topics freely | | Topic names | Chosen by operator | Chosen by user; auto-renamed to match Hermes session title | | Root DM behavior | Normal chat (lobby if `ignore_root_dm: true`) | Becomes a system lobby (non-command messages are rejected) | | Primary use case | Permanent workspaces with optional skill binding | Ad-hoc parallel sessions | | Persistence | `extra.dm_topics` in config | `telegram_dm_topic_mode` + `telegram_dm_topic_bindings` SQLite tables | Both features can coexist on the same bot — you'd run `/topic` from a user's DM, and `extra.dm_topics` continues to manage operator-declared topics for other chats. ### Prerequisites In @BotFather, open your bot → Bot Settings → Threads Settings: 1. Turn on Threaded Mode (enables `has_topics_enabled`) 2. Do not disable users creating topics (keeps `allows_users_to_create_topics` on) When the user first runs `/topic`, Hermes calls `getMe` to verify both flags. If either is off, Hermes sends a screenshot of the BotFather Threads Settings page and explains what to toggle — no activation happens until prerequisites are met. ### Activation flow From the root DM, send: ``` /topic ``` Hermes will: 1. Check `getMe().has_topics_enabled` and `allows_users_to_create_topics` 2. If both are true, enable multi-session topic mode for this DM 3. Create and pin a System topic for status/commands (best-effort) 4. Reply with a list of previous unlinked Telegram sessions the user can restore After activation, the root DM is a lobby: normal prompts are rejected with guidance pointing at All Messages. System commands (`/status`, `/sessions`, `/usage`, `/help`, etc.) still work in the root. ### Creating a new topic (end-user flow) 1. Open the bot DM in Telegram 2. Tap All Messages at the top of the bot interface, then send any message 3. Telegram creates a new topic for that message 4. Hermes responds inside that topic — the topic is now a standalone session Every topic gets its own conversation history, model state, tool execution, and session ID. The isolation key is `agent:main:telegram:dm:{chat_id}:{thread_id}` — identical to the config-driven DM topics isolation. ### Auto-renamed topics When Hermes generates a session title for a topic (via the auto-title pipeline, after the first exchange), the Telegram topic itself is renamed to match — e.g. "New Topic" becomes "Database migration plan". The rename is best-effort: failures are logged but don't break the session. To disable this and keep your manually-chosen topic names untouched, set: ```yaml gateway: platforms: telegram: extra: disable_topic_auto_rename: true ``` When this flag is on, Hermes still generates an internal session title (used by `hermes sessions`, the TUI, etc.) but never edits the Telegram topic name. Useful when you organise topics by hand under BotFather Threaded Mode and don't want every first reply to overwrite the title. ### `/new` inside a topic Resets the current topic's session (new session ID, fresh history) without touching other topics. Hermes replies with a reminder that for parallel work, creating another topic (via All Messages) is usually what you want. ### Restoring a previous session Inside a topic, send: ``` /topic <session-id> ``` This binds the current topic to an existing Hermes session instead of starting fresh. Useful for continuing a conversation that started before topic mode was enabled. Restrictions: - The target session must belong to the same Telegram user - The target session must not already be bound to another topic Hermes confirms with the session title and replays the last assistant message for context. To discover session IDs, send `/topic` (no argument) in the root DM — Hermes lists the user's unlinked Telegram sessions. ### `/topic` inside a topic (no argument) Shows the current topic's binding: session title, session ID, and hints for `/new` vs creating another topic. ### Under the hood - Activation persists to `telegram_dm_topic_mode(chat_id, user_id, enabled, ...)` in `state.db` - Each topic binding persists to `telegram_dm_topic_bindings(chat_id, thread_id, session_id, ...)` with `ON DELETE CASCADE` on `session_id` — pruning a session automatically clears its topic binding - The topic-mode SQLite migration is opt-in: it runs on the first `/topic` call, never on gateway startup. Until a user runs `/topic` in this profile, `state.db` is unchanged - Each inbound DM message looks up its `(chat_id, thread_id)` binding. If present, the lookup routes the message to the bound session via `SessionStore.switch_session()` so the session-key-to-session-id mapping stays consistent on disk - `/new` inside a topic rewrites the binding row to point at the new session ID, so the next message stays on the fresh session - Topics declared in `extra.dm_topics` are never auto-renamed — the operator-chosen name is preserved even when multi-session mode is enabled - Set `extra.disable_topic_auto_rename: true` to turn off auto-rename for all topics in the chat (ad-hoc topics created via Threaded Mode included) - The General (pinned top) topic in a forum-enabled DM is treated as the root lobby, regardless of whether Telegram delivers its messages with `message_thread_id=1` or with no thread_id - Root-lobby reminders are rate-limited to one message per 30 seconds per chat — a user who forgets topic mode is on and types ten prompts in the root won't get ten replies - BotFather setup screenshots are rate-limited to one send per 5 minutes per chat — repeated `/topic` attempts while Threads Settings are still disabled won't re-upload the same image - `/background <prompt>` started inside a topic delivers its result back to the same topic; background sessions don't trigger auto-rename of the owning topic - `/topic` itself is gated by the bot's user authorization check — unauthorized DMs get a refusal instead of activation ### Disabling multi-session mode Send `/topic off` in the root DM. Hermes flips the row off, clears the chat's `(thread_id → session_id)` bindings, and the root DM reverts to a normal Hermes chat. Existing topics in Telegram aren't deleted — they just stop being gated as independent sessions. Re-run `/topic` later to turn it back on. If you need to clean up by hand (e.g. a bulk reset across many chats), remove the rows directly: ```bash sqlite3 ~/.hermes/state.db \ "UPDATE telegram_dm_topic_mode SET enabled = 0 WHERE chat_id = '<your_chat_id>'; \ DELETE FROM telegram_dm_topic_bindings WHERE chat_id = '<your_chat_id>';" ``` ### Downgrading Hermes If you downgrade to a Hermes version that predates `/topic`, the feature simply stops working — the `telegram_dm_topic_mode` and `telegram_dm_topic_bindings` tables remain in `state.db` but are ignored by older code. DMs revert to the native per-thread isolation (each `message_thread_id` still gets its own session via `build_session_key`), so your existing Telegram topics keep working as parallel sessions. The root DM is no longer a lobby — messages there go into the agent like they used to. Re-upgrading reactivates multi-session mode exactly where it was. ## Group Forum Topic Skill Binding Supergroups with Topics mode enabled (also called "forum topics") already get session isolation per topic — each `thread_id` maps to its own conversation. But you may want to auto-load a skill when messages arrive in a specific group topic, just like DM topic skill binding works. ### Use case A team supergroup with forum topics for different workstreams: - Engineering topic → auto-loads the `software-development` skill - Research topic → auto-loads the `arxiv` skill - General topic → no skill, general-purpose assistant ### Configuration Add topic bindings under `platforms.telegram.extra.group_topics` in `~/.hermes/config.yaml`: ```yaml platforms: telegram: extra: group_topics: - chat_id: -1001234567890 # Supergroup ID topics: - name: Engineering thread_id: 5 skill: software-development - name: Research thread_id: 12 skill: arxiv - name: General thread_id: 1 # No skill — general purpose ``` Fields: | Field | Required | Description | |-------|----------|-------------| | `chat_id` | Yes | The supergroup's numeric ID (negative number starting with `-100`) | | `name` | No | Human-readable label for the topic (informational only) | | `thread_id` | Yes | Telegram forum topic ID — visible in `t.me/c/<group_id>/<thread_id>` links | | `skill` | No | Skill to auto-load on new sessions in this topic | ### How it works 1. When a message arrives in a mapped group topic, Hermes looks up the `chat_id` and `thread_id` in `group_topics` config 2. If a matching entry has a `skill` field, that skill is auto-loaded for the session — identical to DM topic skill binding 3. Topics without a `skill` key get session isolation only (existing behavior, unchanged) 4. Unmapped `thread_id` values or `chat_id` values fall through silently — no error, no skill ### Differences from DM Topics | | DM Topics | Group Topics | |---|---|---| | Config key | `extra.dm_topics` | `extra.group_topics` | | Topic creation | Hermes creates topics via API if `thread_id` is missing | Admin creates topics in Telegram UI | | `thread_id` | Auto-populated after creation | Must be set manually | | `icon_color` / `icon_custom_emoji_id` | Supported | Not applicable (admin controls appearance) | | Skill binding | ✓ | ✓ | | Session isolation | ✓ | ✓ (already built-in for forum topics) | :::tip To find a topic's `thread_id`, open the topic in Telegram Web or Desktop and look at the URL: `https://t.me/c/1234567890/5` — the last number (`5`) is the `thread_id`. The `chat_id` for supergroups is the group ID prefixed with `-100` (e.g., group `1234567890` becomes `-1001234567890`). ::: ## Recent Bot API Features - Bot API 9.4 (Feb 2026): Private Chat Topics — bots can create forum topics in 1-on-1 DM chats via `createForumTopic`. Hermes uses this for two distinct features: operator-curated [Private Chat Topics](#private-chat-topics-bot-api-94) (config-driven, fixed topic list) and user-driven [Multi-session DM mode](#multi-session-dm-mode-topic) (activated by `/topic`, unlimited user-created topics). - Privacy policy: Telegram now requires bots to have a privacy policy. Set one via BotFather with `/setprivacy_policy`, or Telegram may auto-generate a placeholder. This is particularly important if your bot is public-facing. - Bot API 9.5 (Mar 2026): Native streaming via `sendMessageDraft`. Hermes supports Telegram's native streaming-draft API as an opt-in transport for private chats. The default remains the legacy `editMessageText` path because draft previews can visibly collapse and re-render on some Telegram clients. ### Streaming transport (`gateway.streaming.transport`) When streaming is enabled (`gateway.streaming.enabled: true`), Hermes picks one of four transports: | Value | Behaviour | |---|---| | `auto` (default) | Native draft streaming on supported chats (currently Telegram DMs); legacy edit-based path otherwise. Falls back gracefully if a draft frame fails. | | `draft` | Force native drafts. Logs a downgrade and falls back to edit if the chat doesn't support drafts (e.g. groups/topics). | | `edit` | Legacy progressive `editMessageText` polling for every chat type. | | `off` | Disable streaming entirely (final reply only, no progressive updates). | In `~/.hermes/config.yaml`: ```yaml gateway: streaming: enabled: true transport: auto # auto | draft | edit | off ``` What you'll see in DMs with `edit` (default) — the gateway sends a normal preview message and progressively updates it via `editMessageText`, avoiding Telegram's draft-preview collapse/rollback effect. What you'll see in DMs with `auto` or `draft` — Telegram shows an animated draft preview that updates token-by-token. When the reply finishes, it's delivered as a regular message and the draft preview clears naturally on the client. Drafts have no message id, so the final answer is what stays in your chat history. What about groups, supergroups, forum topics? Telegram restricts `sendMessageDraft` to private chats (DMs). The gateway transparently falls back to the edit-based path for everything else — same UX as before. What if a draft frame fails? Any failure (transient network error, server-side rejection, older python-telegram-bot install) flips that response back to the edit-based path for the rest of the stream. The next response gets a fresh attempt. ## Rendering: Tables and Link Previews Telegram's MarkdownV2 has no native table syntax — pipe tables render as backslash-escaped noise if passed through raw. Hermes normalizes markdown tables automatically: - Small tables are flattened into row-group bullets — each row becomes a readable bulleted list under the column headings. Good for 2–4 columns and short cells. - Larger or wider tables fall back to a fenced code block with aligned columns so nothing collapses. A one-line prompt hint is added so the agent knows to prefer prose follow-ups over more tables on Telegram. There's nothing to configure — the adapter picks the right fallback per message. If you want the legacy "always code-block" behavior, disable table normalization by setting `telegram.pretty_tables: false` in `config.yaml` (default: `true`). Link previews. Telegram auto-generates link previews for URLs in bot messages. If you'd rather suppress those (long `/tools` output, agent reply that mentions ten links, etc.): ```yaml gateway: platforms: telegram: extra: disable_link_previews: true ``` When enabled, Hermes attaches Telegram's `LinkPreviewOptions(is_disabled=True)` to every outgoing message and falls back to the legacy `disable_web_page_preview` parameter on older `python-telegram-bot` versions. ## Group Allowlisting Telegram groups and forum chats have two orthogonal gates you can configure: - Sender user IDs (`group_allow_from` / `TELEGRAM_GROUP_ALLOWED_USERS`) — sender-scoped allowlist that applies only to group/forum messages. Use this when you want specific users to be able to invoke the bot in groups without adding them to `TELEGRAM_ALLOWED_USERS` (which would also give them DM access). - Chat IDs (`group_allowed_chats` / `TELEGRAM_GROUP_ALLOWED_CHATS`) — chat-scoped allowlist. Any member of these groups/forums can interact with the bot. Useful for team/support bots where group membership itself is the access signal. ```yaml gateway: platforms: telegram: extra: # Global access (DMs + groups). Users here can always invoke the bot. allow_from: - "123456789" # Sender IDs allowed in groups/forums only. Does NOT grant DM access. group_allow_from: - "987654321" # Entire groups/forums — any member is authorized. group_allowed_chats: - "-1001234567890" ``` Equivalent env vars: ```bash TELEGRAM_ALLOWED_USERS="123456789" TELEGRAM_GROUP_ALLOWED_USERS="987654321" TELEGRAM_GROUP_ALLOWED_CHATS="-1001234567890" ``` Behavior: - `TELEGRAM_ALLOWED_USERS` covers all chat types (DMs, groups, forums). - `TELEGRAM_GROUP_ALLOWED_USERS` only authorizes the listed senders in groups/forums. They still can't DM the bot unless listed in `TELEGRAM_ALLOWED_USERS`. - A chat in `TELEGRAM_GROUP_ALLOWED_CHATS` authorizes every member of that chat, regardless of sender. - Use `` in any of these to allow any sender/chat. - This layers on top of existing mention/pattern triggers and on top of `group_topics` + `ignored_threads`. ### Migration from before PR #17686 Prior to this split, `TELEGRAM_GROUP_ALLOWED_USERS` was the only knob and users put chat IDs in it. For backward compatibility, chat-ID-shaped values (starting with `-`) in `TELEGRAM_GROUP_ALLOWED_USERS` are still honored as chat IDs and a deprecation warning is logged once. Migration: ```bash # Old (still works, but deprecated) TELEGRAM_GROUP_ALLOWED_USERS="-1001234567890" # New TELEGRAM_GROUP_ALLOWED_CHATS="-1001234567890" ``` ### Guest @mention bypass (`guest_mode`) In a typical setup, `group_allowed_chats` is a hard gate: messages from groups outside the list are silently dropped, even if a member explicitly @mentions the bot. That's the right default for support / team bots. For more casual setups — friend group chats where you want the bot mostly silent but occasionally available on explicit ping — enable `guest_mode`: ```yaml gateway: platforms: telegram: extra: group_allowed_chats: - "-1001234567890" # your main allowlisted group guest_mode: true # non-allowlisted groups: allow on @mention only ``` Env equivalent: ```bash TELEGRAM_GUEST_MODE=true ``` Default: `false`. With `guest_mode: true`, a message from a non-allowlisted group is processed only if it explicitly @mentions the bot. The mention is required every turn — there's no session stickiness for guest interactions, so the bot never auto-engages in a friend group thread it isn't pinged into. DMs and allowlisted groups behave exactly as before. ## Slash Command Access Control By default, every allowed user can run every slash command. To split your allowlist into admins (full slash command access) and regular users (only commands you explicitly enable), add `allow_admin_from` and `user_allowed_commands` to the platform's `extra` block: ```yaml gateway: platforms: telegram: extra: # Existing allowlists (unchanged) allow_from: - "123456789" # admin - "555555555" # regular user - "777777777" # regular user # NEW — admins get all slash commands (built-in + plugin) allow_admin_from: - "123456789" # NEW — non-admin allowed users can only run these slash commands. # /help and /whoami are always allowed so users can see their access. user_allowed_commands: - status - model - history # Optional: separate admin/command lists for groups group_allow_admin_from: - "123456789" group_user_allowed_commands: - status ``` Behavior: - A user listed in `allow_admin_from` for a scope (DM or group) can run every registered slash command — built-in commands AND plugin-registered ones — through the live registry. - A user in `allow_from` but not in `allow_admin_from` can only run commands listed in `user_allowed_commands`, plus the always-allowed floor: `/help` and `/whoami`. - Plain chat (non-slash messages) is unaffected. Non-admin users can still talk to the agent normally, they just can't trigger arbitrary commands. - Backward compat: if `allow_admin_from` is not set for a scope, slash command gating is disabled for that scope. Existing installs keep working with no changes. - DM admin status does not imply group admin status. Each scope has its own admin list. - If only `group_allow_admin_from` is set, DM scope stays in unrestricted (backward-compat) mode. Use `/whoami` to see the active scope, your tier (admin / user / unrestricted), and which slash commands you can run. ## Interactive Model Picker When you send `/model` with no arguments in a Telegram chat, Hermes shows an interactive inline keyboard for switching models: 1. Provider selection — buttons showing each available provider with model counts (e.g., "OpenAI (15)", "✓ Anthropic (12)" for the current provider). 2. Model selection — paginated model list with Prev/Next navigation, a Back button to return to providers, and Cancel. The current model and provider are displayed at the top. All navigation happens by editing the same message in-place (no chat clutter). :::tip If you know the exact model name, type `/model <name>` directly to skip the picker. You can also type `/model <name> --global` to persist the change across sessions. ::: ## DNS-over-HTTPS Fallback IPs In some restricted networks, `api.telegram.org` may resolve to an IP that is unreachable. The Telegram adapter includes a fallback IP mechanism that transparently retries connections against alternative IPs while preserving the correct TLS hostname and SNI. ### How it works 1. If `TELEGRAM_FALLBACK_IPS` is set, those IPs are used directly. 2. Otherwise, the adapter automatically queries Google DNS and Cloudflare DNS via DNS-over-HTTPS (DoH) to discover alternative IPs for `api.telegram.org`. 3. IPs returned by DoH that differ from the system DNS result are used as fallbacks. 4. If DoH is also blocked, a hardcoded seed IP (`149.154.167.220`) is used as a last resort. 5. Once a fallback IP succeeds, it becomes "sticky" — subsequent requests use it directly without retrying the primary path first. ### Configuration ```bash # Explicit fallback IPs (comma-separated) TELEGRAM_FALLBACK_IPS=149.154.167.220,149.154.167.221 ``` Or in `~/.hermes/config.yaml`: ```yaml platforms: telegram: extra: fallback_ips: - "149.154.167.220" ``` :::tip You usually don't need to configure this manually. The auto-discovery via DoH handles most restricted-network scenarios. The `TELEGRAM_FALLBACK_IPS` env var is only needed if DoH is also blocked on your network. ::: ## Proxy Support If your network requires an HTTP proxy to reach the internet (common in corporate environments), the Telegram adapter automatically reads standard proxy environment variables and routes all connections through the proxy. ### Supported variables The adapter checks these environment variables in order, using the first one that is set: 1. `HTTPS_PROXY` 2. `HTTP_PROXY` 3. `ALL_PROXY` 4. `https_proxy` / `http_proxy` / `all_proxy` (lowercase variants) ### Configuration Set the proxy in your environment before starting the gateway: ```bash export HTTPS_PROXY=http://proxy.example.com:8080 hermes gateway ``` Or add it to `~/.hermes/.env`: ```bash HTTPS_PROXY=http://proxy.example.com:8080 ``` The proxy applies to both the primary transport and all fallback IP transports. No additional Hermes configuration is needed — if the environment variable is set, it's used automatically. :::note This covers the custom fallback transport layer that Hermes uses for Telegram connections. The standard `httpx` client used elsewhere already respects proxy env vars natively. ::: ## Message Reactions The bot can add emoji reactions to messages as visual processing feedback: - 👀 when the bot starts processing your message - ✅ when the response is delivered successfully - ❌ if an error occurs during processing Reactions are disabled by default. Enable them in `config.yaml`: ```yaml telegram: reactions: true ``` Or via environment variable: ```bash TELEGRAM_REACTIONS=true ``` :::note Unlike Discord (where reactions are additive), Telegram's Bot API replaces all bot reactions in a single call. The transition from 👀 to ✅/❌ happens atomically — you won't see both at once. ::: :::tip If the bot doesn't have permission to add reactions in a group, the reaction calls fail silently and message processing continues normally. ::: ## Per-Channel Prompts Assign ephemeral system prompts to specific Telegram groups or forum topics. The prompt is injected at runtime on every turn — never persisted to transcript history — so changes take effect immediately. ```yaml telegram: channel_prompts: "-1001234567890": | You are a research assistant. Focus on academic sources, citations, and concise synthesis. "42": | This topic is for creative writing feedback. Be warm and constructive. ``` Keys are chat IDs (groups/supergroups) or forum topic IDs. For forum groups, topic-level prompts override the group-level prompt: - Message in topic `42` inside group `-1001234567890` → uses topic `42`'s prompt - Message in topic `99` (no explicit entry) → falls back to group `-1001234567890`'s prompt - Message in a group with no entry → no channel prompt applied Numeric YAML keys are automatically normalized to strings. ## Troubleshooting | Problem | Solution | |---------|----------| | Bot not responding at all | Verify `TELEGRAM_BOT_TOKEN` is correct. Check `hermes gateway` logs for errors. | | Bot responds with "unauthorized" | Your user ID is not in `TELEGRAM_ALLOWED_USERS`. Double-check with @userinfobot. | | Bot ignores group messages | Privacy mode is likely on. Disable it (Step 3) or make the bot a group admin. Remember to remove and re-add the bot after changing privacy. | | Voice messages not transcribed | Verify STT is available: install `faster-whisper` for local transcription, or set `GROQ_API_KEY` / `VOICE_TOOLS_OPENAI_KEY` in `~/.hermes/.env`. | | Voice replies are files, not bubbles | Install `ffmpeg` (needed for Edge TTS Opus conversion). | | Bot token revoked/invalid | Generate a new token via `/revoke` then `/newbot` or `/token` in BotFather. Update your `.env` file. | | Webhook not receiving updates | Verify `TELEGRAM_WEBHOOK_URL` is publicly reachable (test with `curl`). Ensure your platform/reverse proxy routes inbound HTTPS traffic from the URL's port to the local listen port configured by `TELEGRAM_WEBHOOK_PORT` (they do not need to be the same number). Ensure SSL/TLS is active — Telegram only sends to HTTPS URLs. Check firewall rules. | ## Exec Approval When the agent tries to run a potentially dangerous command, it asks you for approval in the chat: > ⚠️ This command is potentially dangerous (recursive delete). Reply "yes" to approve. Reply "yes"/"y" to approve or "no"/"n" to deny. ## Interactive Prompts (clarify) When the agent calls the `clarify` tool — to ask which approach you prefer, get post-task feedback, or check before a non-trivial decision — Telegram renders the question with inline keyboard buttons: > ❓ Which framework should I use for the dashboard? > > [1. Next.js] [2. Remix] [3. Astro] > [✏️ Other (type answer)] Tap a button to answer, or tap Other to type a free-form response (the next message you send becomes the answer). Open-ended `clarify` calls (no preset choices) skip the buttons and just capture your next message. Configure the response timeout via `agent.clarify_timeout` in `~/.hermes/config.yaml` (default `600` seconds). If you don't respond within the timeout, the agent unblocks with a sentinel message and adapts rather than hanging. ## Push notification volume Telegram fires a push notification on every message the bot sends. For long agent turns that emit tool-progress bubbles, streaming updates, and status callbacks, this gets noisy fast. The Telegram adapter has two notification modes: | Mode | Behavior | |------|----------| | `important` (default) | Only final responses, approval prompts, and slash-command confirmations ring. Tool progress, streaming chunks, and status messages are delivered with `disable_notification=true`. | | `all` | Every outgoing message fires a push notification. Legacy behavior; opt in if you genuinely want to hear about every tool call. | Configure in `~/.hermes/config.yaml`: ```yaml display: platforms: telegram: notifications: important # or "all" ``` Env override (handy for quick A/B testing): ```bash HERMES_TELEGRAM_NOTIFICATIONS=all ``` Unknown values log a warning and fall back to `important`. ## Status messages edited in place The Telegram adapter routes recurring agent status callbacks (e.g. "Compressing context…", "Calling tool…") through `send_or_update_status()`, which keeps a `{(chat_id, status_key) → message_id}` cache and edits the existing bubble on subsequent emits instead of appending a new one each time. Distinct `status_key` values get their own messages; distinct chats never collide. If the edit fails (e.g. the user deleted the message, or it's older than Telegram allows for edits), the cache entry is dropped and the next emit posts a fresh message and re-caches its ID. No config required — this is the default Telegram behavior. Other adapters that don't implement `send_or_update_status` fall through to plain `send()` unchanged. ## Pin incoming user message during agent turn When a user sends a message that triggers an agent turn, the Telegram adapter pins that incoming message for the duration of the turn and unpins it when the response is finished — a lightweight visual indicator that the bot is actively working on the message rather than ignoring it. The pin uses `disable_notification=true` to avoid extra pings. No config required. ## Security :::warning Always set `TELEGRAM_ALLOWED_USERS` to restrict who can interact with your bot. Without it, the gateway denies all users by default as a safety measure. ::: Never share your bot token publicly. If compromised, revoke it immediately via BotFather's `/revoke` command. For more details, see the [Security documentation](/user-guide/security). You can also use [DM pairing](/user-guide/messaging#dm-pairing-alternative-to-allowlists) for a more dynamic approach to user authorization. ---  # Discord # Discord Setup Hermes Agent integrates with Discord as a bot, letting you chat with your AI assistant through direct messages or server channels. The bot receives your messages, processes them through the Hermes Agent pipeline (including tool use, memory, and reasoning), and responds in real time. It supports text, voice messages, file attachments, and slash commands. Before setup, here's the part most people want to know: how Hermes behaves once it's in your server. ## How Hermes Behaves | Context | Behavior | |---------|----------| | DMs | Hermes responds to every message. No `@mention` needed. Each DM has its own session. | | Server channels | By default, Hermes only responds when you `@mention` it. If you post in a channel without mentioning it, Hermes ignores the message. | | Free-response channels | You can make specific channels mention-free with `DISCORD_FREE_RESPONSE_CHANNELS`, or disable mentions globally with `DISCORD_REQUIRE_MENTION=false`. Messages in these channels are answered inline — auto-threading is skipped so the channel stays a lightweight chat. | | Threads | Hermes replies in the same thread. Mention rules still apply unless that thread or its parent channel is configured as free-response. Threads stay isolated from the parent channel for session history. | | Shared channels with multiple users | By default, Hermes isolates session history per user inside the channel for safety and clarity. Two people talking in the same channel do not share one transcript unless you explicitly disable that. | | Messages mentioning other users | When `DISCORD_IGNORE_NO_MENTION` is `true` (the default), Hermes stays silent if a message @mentions other users but does not mention the bot. This prevents the bot from jumping into conversations directed at other people. Set to `false` if you want the bot to respond to all messages regardless of who is mentioned. This only applies in server channels, not DMs. | :::tip If you want a normal bot-help channel where people can talk to Hermes without tagging it every time, add that channel to `DISCORD_FREE_RESPONSE_CHANNELS`. ::: ### Discord Gateway Model Hermes on Discord is not a webhook that replies statelessly. It runs through the full messaging gateway, which means each incoming message goes through: 1. authorization (`DISCORD_ALLOWED_USERS`) 2. mention / free-response checks 3. session lookup 4. session transcript loading 5. normal Hermes agent execution, including tools, memory, and slash commands 6. response delivery back to Discord That matters because behavior in a busy server depends on both Discord routing and Hermes session policy. ### Session Model in Discord By default: - each DM gets its own session - each server thread gets its own session namespace - each user in a shared channel gets their own session inside that channel So if Alice and Bob both talk to Hermes in `#research`, Hermes treats those as separate conversations by default even though they are using the same visible Discord channel. This is controlled by `config.yaml`: ```yaml group_sessions_per_user: true ``` Set it to `false` only if you explicitly want one shared conversation for the entire room: ```yaml group_sessions_per_user: false ``` Shared sessions can be useful for a collaborative room, but they also mean: - users share context growth and token costs - one person's long tool-heavy task can bloat everyone else's context - one person's in-flight run can interrupt another person's follow-up in the same room ### Interrupts and Concurrency Hermes tracks running agents by session key. With the default `group_sessions_per_user: true`: - Alice interrupting her own in-flight request only affects Alice's session in that channel - Bob can keep talking in the same channel without inheriting Alice's history or interrupting Alice's run With `group_sessions_per_user: false`: - the whole room shares one running-agent slot for that channel/thread - follow-up messages from different people can interrupt or queue behind each other This guide walks you through the full setup process — from creating your bot on Discord's Developer Portal to sending your first message. ## Step 1: Create a Discord Application 1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) and sign in with your Discord account. 2. Click New Application in the top-right corner. 3. Enter a name for your application (e.g., "Hermes Agent") and accept the Developer Terms of Service. 4. Click Create. You'll land on the General Information page. Note the Application ID — you'll need it later to build the invite URL. ## Step 2: Create the Bot 1. In the left sidebar, click Bot. 2. Discord automatically creates a bot user for your application. You'll see the bot's username, which you can customize. 3. Under Authorization Flow: - Set Public Bot to ON — required to use the Discord-provided invite link (recommended). This allows the Installation tab to generate a default authorization URL. - Leave Require OAuth2 Code Grant set to OFF. :::tip You can set a custom avatar and banner for your bot on this page. This is what users will see in Discord. ::: :::info[Private Bot Alternative] If you prefer to keep your bot private (Public Bot = OFF), you must use the Manual URL method in Step 5 instead of the Installation tab. The Discord-provided link requires Public Bot to be enabled. ::: ## Step 3: Enable Privileged Gateway Intents This is the most critical step in the entire setup. Without the correct intents enabled, your bot will connect to Discord but will not be able to read message content. On the Bot page, scroll down to Privileged Gateway Intents. You'll see three toggles: | Intent | Purpose | Required? | |--------|---------|-----------| | Presence Intent | See user online/offline status | Optional | | Server Members Intent | Access the member list, resolve usernames | Required | | Message Content Intent | Read the text content of messages | Required | Enable both Server Members Intent and Message Content Intent by toggling them ON. - Without Message Content Intent, your bot receives message events but the message text is empty — the bot literally cannot see what you typed. - Without Server Members Intent, the bot cannot resolve usernames for the allowed users list and may fail to identify who is messaging it. :::warning[This is the #1 reason Discord bots don't work] If your bot is online but never responds to messages, the Message Content Intent is almost certainly disabled. Go back to the [Developer Portal](https://discord.com/developers/applications), select your application → Bot → Privileged Gateway Intents, and make sure Message Content Intent is toggled ON. Click Save Changes. ::: Regarding server count: - If your bot is in fewer than 100 servers, you can simply toggle intents on and off freely. - If your bot is in 100 or more servers, Discord requires you to submit a verification application to use privileged intents. For personal use, this is not a concern. Click Save Changes at the bottom of the page. ## Step 4: Get the Bot Token The bot token is the credential Hermes Agent uses to log in as your bot. Still on the Bot page: 1. Under the Token section, click Reset Token. 2. If you have two-factor authentication enabled on your Discord account, enter your 2FA code. 3. Discord will display your new token. Copy it immediately. :::warning[Token shown only once] The token is only displayed once. If you lose it, you'll need to reset it and generate a new one. Never share your token publicly or commit it to Git — anyone with this token has full control of your bot. ::: Store the token somewhere safe (a password manager, for example). You'll need it in Step 8. ## Step 5: Generate the Invite URL You need an OAuth2 URL to invite the bot to your server. There are two ways to do this: ### Option A: Using the Installation Tab (Recommended) :::note[Requires Public Bot] This method requires Public Bot to be set to ON in Step 2. If you set Public Bot to OFF, use the Manual URL method below instead. ::: 1. In the left sidebar, click Installation. 2. Under Installation Contexts, enable Guild Install. 3. For Install Link, select Discord Provided Link. 4. Under Default Install Settings for Guild Install: - Scopes: select `bot` and `applications.commands` - Permissions: select the permissions listed below. ### Option B: Manual URL You can construct the invite URL directly using this format: ``` https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274878286912 ``` Replace `YOUR_APP_ID` with the Application ID from Step 1. ### Required Permissions These are the minimum permissions your bot needs: - View Channels — see the channels it has access to - Send Messages — respond to your messages - Embed Links — format rich responses - Attach Files — send images, audio, and file outputs - Read Message History — maintain conversation context ### Recommended Additional Permissions - Send Messages in Threads — respond in thread conversations - Add Reactions — react to messages for acknowledgment ### Permission Integers | Level | Permissions Integer | What's Included | |-------|-------------------|-----------------| | Minimal | `117760` | View Channels, Send Messages, Read Message History, Attach Files | | Recommended | `274878286912` | All of the above plus Embed Links, Send Messages in Threads, Add Reactions | ## Step 6: Invite to Your Server 1. Open the invite URL in your browser (from the Installation tab or the manual URL you constructed). 2. In the Add to Server dropdown, select your server. 3. Click Continue, then Authorize. 4. Complete the CAPTCHA if prompted. :::info You need the Manage Server permission on the Discord server to invite a bot. If you don't see your server in the dropdown, ask a server admin to use the invite link instead. ::: After authorizing, the bot will appear in your server's member list (it will show as offline until you start the Hermes gateway). ## Step 7: Find Your Discord User ID Hermes Agent uses your Discord User ID to control who can interact with the bot. To find it: 1. Open Discord (desktop or web app). 2. Go to Settings → Advanced → toggle Developer Mode to ON. 3. Close settings. 4. Right-click your own username (in a message, the member list, or your profile) → Copy User ID. Your User ID is a long number like `284102345871466496`. :::tip Developer Mode also lets you copy Channel IDs and Server IDs the same way — right-click the channel or server name and select Copy ID. You'll need a Channel ID if you want to set a home channel manually. ::: ## Step 8: Configure Hermes Agent ### Option A: Interactive Setup (Recommended) Run the guided setup command: ```bash hermes gateway setup ``` Select Discord when prompted, then paste your bot token and user ID when asked. ### Option B: Manual Configuration Add the following to your `~/.hermes/.env` file: ```bash # Required DISCORD_BOT_TOKEN=your-bot-token DISCORD_ALLOWED_USERS=284102345871466496 # Multiple allowed users (comma-separated) # DISCORD_ALLOWED_USERS=284102345871466496,198765432109876543 ``` Then start the gateway: ```bash hermes gateway ``` The bot should come online in Discord within a few seconds. Send it a message — either a DM or in a channel it can see — to test. :::tip You can run `hermes gateway` in the background or as a systemd service for persistent operation. See the deployment docs for details. ::: ## Configuration Reference Discord behavior is controlled through two files: `~/.hermes/.env` for credentials and env-level toggles, and `~/.hermes/config.yaml` for structured settings. Environment variables always take precedence over config.yaml values when both are set. ### Environment Variables (`.env`) | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `DISCORD_BOT_TOKEN` | Yes | — | Bot token from the [Discord Developer Portal](https://discord.com/developers/applications). | | `DISCORD_ALLOWED_USERS` | Yes | — | Comma-separated Discord user IDs allowed to interact with the bot. Without this or `DISCORD_ALLOWED_ROLES`, the gateway denies all users. | | `DISCORD_ALLOWED_ROLES` | No | — | Comma-separated Discord role IDs. Any member with one of these roles is authorized — OR semantics with `DISCORD_ALLOWED_USERS`. Auto-enables the Server Members Intent on connect. Useful when moderation teams churn: new mods get access as soon as the role is granted, no config push needed. | | `DISCORD_HOME_CHANNEL` | No | — | Channel ID where the bot sends proactive messages (cron output, reminders, notifications). | | `DISCORD_HOME_CHANNEL_NAME` | No | `"Home"` | Display name for the home channel in logs and status output. | | `DISCORD_COMMAND_SYNC_POLICY` | No | `"safe"` | Controls native slash-command startup sync. `"safe"` diffs existing global commands and only updates what changed, recreating commands when Discord metadata changes cannot be applied via patch. `"bulk"` preserves the old `tree.sync()` behavior. `"off"` skips startup sync entirely. | | `DISCORD_REQUIRE_MENTION` | No | `true` | When `true`, the bot only responds in server channels when `@mentioned`. Set to `false` to respond to all messages in every channel. | | `DISCORD_THREAD_REQUIRE_MENTION` | No | `false` | When `true`, the in-thread mention shortcut is disabled — threads are gated the same as channels, requiring `@mention` even after the bot has already participated. Use this when multiple bots share a thread and you want each to fire only on explicit `@mention`. | | `DISCORD_FREE_RESPONSE_CHANNELS` | No | — | Comma-separated channel IDs where the bot responds without requiring an `@mention`, even when `DISCORD_REQUIRE_MENTION` is `true`. | | `DISCORD_IGNORE_NO_MENTION` | No | `true` | When `true`, the bot stays silent if a message `@mentions` other users but does not mention the bot. Prevents the bot from jumping into conversations directed at other people. Only applies in server channels, not DMs. | | `DISCORD_AUTO_THREAD` | No | `true` | When `true`, automatically creates a new thread for every `@mention` in a text channel, so each conversation is isolated (similar to Slack behavior). Messages already inside threads or DMs are unaffected. | | `DISCORD_ALLOW_BOTS` | No | `"none"` | Controls how the bot handles messages from other Discord bots. `"none"` — ignore all other bots. `"mentions"` — only accept bot messages that `@mention` Hermes. `"all"` — accept all bot messages. | | `DISCORD_REACTIONS` | No | `true` | When `true`, the bot adds emoji reactions to messages during processing (👀 when starting, ✅ on success, ❌ on error). Set to `false` to disable reactions entirely. | | `DISCORD_IGNORED_CHANNELS` | No | — | Comma-separated channel IDs where the bot never responds, even when `@mentioned`. Takes priority over all other channel settings. | | `DISCORD_ALLOWED_CHANNELS` | No | — | Comma-separated channel IDs. When set, the bot only responds in these channels (plus DMs if allowed). Overrides `config.yaml` `discord.allowed_channels`. Combine with `DISCORD_IGNORED_CHANNELS` to express allow/deny rules. | | `DISCORD_NO_THREAD_CHANNELS` | No | — | Comma-separated channel IDs where the bot responds directly in the channel instead of creating a thread. Only relevant when `DISCORD_AUTO_THREAD` is `true`. | | `DISCORD_HISTORY_BACKFILL` | No | `true` | When `true`, prepend recent channel scrollback (since the bot's last response) to the user message when the bot is mentioned. Recovers context the bot would otherwise miss with `require_mention`. Skipped in DMs and free-response channels. Set to `false` to disable. | | `DISCORD_HISTORY_BACKFILL_LIMIT` | No | `50` | Maximum number of messages to scan backwards when assembling the backfill block. In practice the scan usually stops earlier — at the bot's own last message in the channel. | | `DISCORD_REPLY_TO_MODE` | No | `"first"` | Controls reply-reference behavior: `"off"` — never reply to the original message, `"first"` — reply-reference on the first message chunk only (default), `"all"` — reply-reference on every chunk. | | `DISCORD_ALLOW_MENTION_EVERYONE` | No | `false` | When `false` (default), the bot cannot ping `@everyone` or `@here` even if its response contains those tokens. Set to `true` to opt back in. See [Mention Control](#mention-control) below. | | `DISCORD_ALLOW_MENTION_ROLES` | No | `false` | When `false` (default), the bot cannot ping `@role` mentions. Set to `true` to allow. | | `DISCORD_ALLOW_MENTION_USERS` | No | `true` | When `true` (default), the bot can ping individual users by ID. | | `DISCORD_ALLOW_MENTION_REPLIED_USER` | No | `true` | When `true` (default), replying to a message pings the original author. | | `DISCORD_PROXY` | No | — | Proxy URL for Discord connections (HTTP, WebSocket, REST). Overrides `HTTPS_PROXY`/`ALL_PROXY`. Supports `http://`, `https://`, and `socks5://` schemes. | | `DISCORD_ALLOW_ANY_ATTACHMENT` | No | `false` | When `true`, the bot accepts attachments of any file type (not just the built-in PDF/text/zip/office allowlist). Unknown types are cached to disk and surfaced to the agent as a local path with `application/octet-stream` MIME so it can inspect them with `terminal` / `read_file` / `ffprobe` / etc. | | `DISCORD_MAX_ATTACHMENT_BYTES` | No | `33554432` | Maximum bytes per attachment the gateway will download and cache. Default 32 MiB. Set to `0` for no cap (attachments are held in memory while being written, so unlimited carries a real memory cost). | | `HERMES_DISCORD_TEXT_BATCH_DELAY_SECONDS` | No | `0.6` | Grace window the adapter waits before flushing a queued text chunk. Useful for smoothing streamed output. | | `HERMES_DISCORD_TEXT_BATCH_SPLIT_DELAY_SECONDS` | No | `2.0` | Delay between split chunks when a single message exceeds Discord's length limit. | ### Config File (`config.yaml`) The `discord` section in `~/.hermes/config.yaml` mirrors the env vars above. Config.yaml settings are applied as defaults — if the equivalent env var is already set, the env var wins. ```yaml # Discord-specific settings discord: require_mention: true # Require @mention in server channels thread_require_mention: false # If true, require @mention in threads too (multi-bot threads) free_response_channels: "" # Comma-separated channel IDs (or YAML list) auto_thread: true # Auto-create threads on @mention reactions: true # Add emoji reactions during processing ignored_channels: [] # Channel IDs where bot never responds no_thread_channels: [] # Channel IDs where bot responds without threading history_backfill: true # Prepend recent channel scrollback on mention (default: true) history_backfill_limit: 50 # Max messages to scan backwards (default: 50) channel_prompts: {} # Per-channel ephemeral system prompts allow_mentions: # What the bot is allowed to ping (safe defaults) everyone: false # @everyone / @here pings (default: false) roles: false # @role pings (default: false) users: true # @user pings (default: true) replied_user: true # reply-reference pings the author (default: true) # Session isolation (applies to all gateway platforms, not just Discord) group_sessions_per_user: true # Isolate sessions per user in shared channels ``` #### `discord.require_mention` Type: boolean — Default: `true` When enabled, the bot only responds in server channels when directly `@mentioned`. DMs always get a response regardless of this setting. #### `discord.thread_require_mention` Type: boolean — Default: `false` By default, once the bot has participated in a thread (auto-created on `@mention` or replied in once), it keeps responding to every subsequent message in that thread without needing to be `@mentioned` again. That's the right default for one-on-one conversations. In multi-bot threads where users address one bot per turn, this default becomes a footgun — every other bot in the thread also fires on every message, burning credits and spamming the channel. Set `thread_require_mention: true` to disable the in-thread shortcut and gate threads the same way channels are gated. Explicit `@mentions` still work as before. ```yaml discord: require_mention: true thread_require_mention: true # multi-bot setup ``` #### `discord.free_response_channels` Type: string or list — Default: `""` Channel IDs where the bot responds to all messages without needing an `@mention`. Accepts either a comma-separated string or a YAML list: ```yaml # String format discord: free_response_channels: "1234567890,9876543210" # List format discord: free_response_channels: - 1234567890 - 9876543210 ``` If a thread's parent channel is in this list, the thread also becomes mention-free. Free-response channels also skip auto-threading — the bot replies inline rather than spinning off a new thread per message. This keeps the channel usable as a lightweight chat surface. If you want threading behavior, don't list the channel as free-response (use normal `@mention` flow instead). #### `discord.auto_thread` Type: boolean — Default: `true` When enabled, every `@mention` in a regular text channel automatically creates a new thread for the conversation. This keeps the main channel clean and gives each conversation its own isolated session history. Once a thread is created, subsequent messages in that thread don't require `@mention` — the bot knows it's already participating. Set [`thread_require_mention`](#discordthread_require_mention) to `true` to disable this in-thread shortcut for multi-bot setups. Messages sent in existing threads or DMs are unaffected by this setting. Channels listed in `discord.free_response_channels` or `discord.no_thread_channels` also bypass auto-threading and get inline replies instead. #### `discord.reactions` Type: boolean — Default: `true` Controls whether the bot adds emoji reactions to messages as visual feedback: - 👀 added when the bot starts processing your message - ✅ added when the response is delivered successfully - ❌ added if an error occurs during processing Disable this if you find the reactions distracting or if the bot's role doesn't have the Add Reactions permission. #### `discord.ignored_channels` Type: string or list — Default: `[]` Channel IDs where the bot never responds, even when directly `@mentioned`. This takes the highest priority — if a channel is in this list, the bot silently ignores all messages there, regardless of `require_mention`, `free_response_channels`, or any other setting. ```yaml # String format discord: ignored_channels: "1234567890,9876543210" # List format discord: ignored_channels: - 1234567890 - 9876543210 ``` If a thread's parent channel is in this list, messages in that thread are also ignored. #### `discord.no_thread_channels` Type: string or list — Default: `[]` Channel IDs where the bot responds directly in the channel instead of auto-creating a thread. This only has an effect when `auto_thread` is `true` (the default). In these channels, the bot responds inline like a normal message rather than spawning a new thread. ```yaml discord: no_thread_channels: - 1234567890 # Bot responds inline here ``` Useful for channels dedicated to bot interaction where threads would add unnecessary noise. #### `discord.channel_prompts` Type: mapping — Default: `{}` Per-channel ephemeral system prompts that are injected on every turn in the matching Discord channel or thread without being persisted to transcript history. ```yaml discord: channel_prompts: "1234567890": | This channel is for research tasks. Prefer deep comparisons, citations, and concise synthesis. "9876543210": | This forum is for therapy-style support. Be warm, grounded, and non-judgmental. ``` Behavior: - Exact thread/channel ID matches win. - If a message arrives inside a thread or forum post and that thread has no explicit entry, Hermes falls back to the parent channel/forum ID. - Prompts are applied ephemerally at runtime, so changing them affects future turns immediately without rewriting past session history. #### `discord.history_backfill` Type: boolean — Default: `true` When enabled, the bot recovers missed channel messages on each `@mention`. With `require_mention: true`, the bot only processes messages that tag it directly — everything else in the channel is invisible to the session transcript. History backfill scans backwards through recent channel history when triggered, collecting messages between the bot's last response and the current mention, and includes them as context. Behavior by surface: - Server channels (with `require_mention: true`): backfill scans the channel since the bot's last response. Useful when other participants posted while the bot wasn't addressed. - Threads: backfill scans the thread only — Discord's `channel.history()` on a thread returns only that thread's messages, not the parent channel. This is the right scope because threads are usually self-contained conversations. - DMs: skipped. Every DM message triggers the bot, so the session transcript is already complete — there's no mention gap to fill. - Free-response channels and bot's own auto-created threads: skipped for the same reason — no mention gating means no gap. Per-user sessions (`group_sessions_per_user: true`, the default) also benefit: a user's session is missing the context posted by other channel participants and the user's own messages from before they tagged the bot. Backfill fills both gaps. ```yaml discord: history_backfill: true # default ``` To turn it off: ```yaml discord: history_backfill: false ``` > Note: Messages that arrive while the bot is processing (between a trigger and its response) are not captured. This is an accepted simplification — the user can re-send or tag again. #### `discord.history_backfill_limit` Type: integer — Default: `50` Maximum number of messages to scan backwards when recovering channel context. In practice the scan usually stops much earlier — at the bot's own last message in the channel, which is the natural boundary between turns. This limit is a safety cap for cold starts and long gaps where no prior bot message exists in recent history. ```yaml discord: history_backfill: true history_backfill_limit: 50 ``` #### `group_sessions_per_user` Type: boolean — Default: `true` This is a global gateway setting (not Discord-specific) that controls whether users in the same channel get isolated session histories. When `true`: Alice and Bob talking in `#research` each have their own separate conversation with Hermes. When `false`: the entire channel shares one conversation transcript and one running-agent slot. ```yaml group_sessions_per_user: true ``` See the [Session Model](#session-model-in-discord) section above for the full implications of each mode. #### `display.tool_progress` Type: string — Default: `"all"` — Values: `off`, `new`, `all`, `verbose` Controls whether the bot sends progress messages in the chat while processing (e.g., "Reading file...", "Running terminal command..."). This is a global gateway setting that applies to all platforms. ```yaml display: tool_progress: "all" # off | new | all | verbose ``` - `off` — no progress messages - `new` — only show the first tool call per turn - `all` — show all tool calls (truncated to 40 characters in gateway messages) - `verbose` — show full tool call details (can produce long messages) #### `display.tool_progress_command` Type: boolean — Default: `false` When enabled, makes the `/verbose` slash command available in the gateway, letting you cycle through tool progress modes (`off → new → all → verbose → off`) without editing config.yaml. ```yaml display: tool_progress_command: true ``` ## Slash Command Access Control By default, every allowed user can run every slash command. To split your allowlist into admins (full slash command access) and regular users (only commands you explicitly enable), add `allow_admin_from` and `user_allowed_commands` to the Discord platform's `extra` block: ```yaml gateway: platforms: discord: extra: # Existing user allowlist (unchanged) allow_from: - "123456789012345678" # admin user ID - "999888777666555444" # regular user ID # NEW — admins get all slash commands (built-in + plugin) allow_admin_from: - "123456789012345678" # NEW — non-admin allowed users can only run these slash commands. # /help and /whoami are always allowed so users can see their access. user_allowed_commands: - status - model - history # Optional: separate admin / command lists for server channels group_allow_admin_from: - "123456789012345678" group_user_allowed_commands: - status ``` Behavior: - A user in `allow_admin_from` for a scope (DM or server channel) can run every registered slash command — built-in AND plugin-registered — through the live command registry. - A user not in `allow_admin_from` can only run commands listed in `user_allowed_commands`, plus the always-allowed floor: `/help` and `/whoami`. - Plain chat (non-slash messages) is unaffected. Non-admin users can still talk to the agent normally; they just can't trigger arbitrary commands. - Backward compat: if `allow_admin_from` is not set for a scope, slash command gating is disabled for that scope. Existing installs keep working with no changes. - DM admin status does not imply server-channel admin status. Each scope has its own admin list. Use `/whoami` to see the active scope, your tier (admin / user / unrestricted), and which slash commands you can run. ## Interactive Model Picker Send `/model` with no arguments in a Discord channel to open a dropdown-based model picker: 1. Provider selection — a Select dropdown showing available providers (up to 25). 2. Model selection — a second dropdown with models for the chosen provider (up to 25). The picker times out after 120 seconds. Only authorized users (those in `DISCORD_ALLOWED_USERS`) can interact with it. If you know the model name, type `/model <name>` directly. ## Native Slash Commands for Skills Hermes automatically registers installed skills as native Discord Application Commands. This means skills appear in Discord's autocomplete `/` menu alongside built-in commands. - Each skill becomes a Discord slash command (e.g., `/code-review`, `/ascii-art`) - Skills accept an optional `args` string parameter - Discord has a limit of 100 application commands per bot — if you have more skills than available slots, extra skills are skipped with a warning in the logs - Skills are registered during bot startup alongside built-in commands like `/model`, `/reset`, and `/background` No extra configuration is needed — any skill installed via `hermes skills install` is automatically registered as a Discord slash command on the next gateway restart. ### Disabling Slash Command Registration If you run multiple Hermes gateways against the same Discord application (e.g. staging + production), only one of them should own the global slash-command registration — otherwise the last startup wins and the registrations flap. Turn slash registration off on the "follower" gateway: ```yaml gateway: platforms: discord: extra: slash_commands: false # default: true ``` Leaving this at `true` on the "primary" gateway keeps the normal behavior — global `/`-menu commands for built-ins and installed skills. ## Sending Media (`send_message` + `MEDIA:` tags) The Discord adapter supports native file uploads for every common media type via the `send_message` tool and inline `MEDIA:/path/to/file` tags emitted by the agent: | Type | How it's delivered | |---|---| | Images (PNG/JPG/WebP) | Native Discord image attachment with inline preview | | Animated GIFs | `send_animation` uploads as `animation.gif` so Discord plays it inline (not as a static thumbnail) | | Video (MP4/MOV) | `send_video` — native video player | | Audio / Voice | `send_voice` — native voice message when possible, file attachment otherwise | | Documents (PDF/ZIP/docx/etc.) | `send_document` — native attachment with download button | Discord's per-upload size limit depends on the server's boost tier (25 MB free, up to 500 MB). If Hermes gets an HTTP 413, the adapter falls back to a link pointing at the local cache path rather than failing silently. ## Receiving Arbitrary File Types By default the bot caches uploads that match a built-in allowlist — images, audio, video, PDF, text/markdown/csv/log, JSON/XML/YAML/TOML, zip, docx/xlsx/pptx. Anything else (a `.wav`, a `.bin`, a custom-extension dump) gets logged as `Unsupported document type` and dropped before the agent sees it. To accept arbitrary file types, enable `discord.allow_any_attachment`: ```yaml discord: allow_any_attachment: true # Optional — raise/disable the per-file size cap. Default is 32 MiB. # The whole file is held in memory while being cached, so unlimited # uploads carry a real memory cost. max_attachment_bytes: 33554432 # bytes; 0 = unlimited ``` When the flag is on, any uploaded file is downloaded, cached under `~/.hermes/cache/documents/`, and surfaced to the agent as a `DOCUMENT`-typed message event with `application/octet-stream` MIME. The agent receives a context note pointing at the local path (auto-translated for Docker/Modal sandboxed terminals via `to_agent_visible_cache_path`) and can inspect the file with `terminal` (`ffprobe`, `unzip`, `file`, `strings`, etc.) or `read_file`. The file body is not inlined into the prompt — only the path — so binary uploads don't blow up the context window. Known-text formats already in the allowlist (`.txt`, `.md`, `.log`) continue to have their contents auto-injected up to 100 KiB; that behavior is unchanged when the flag is on. Equivalent env vars: `DISCORD_ALLOW_ANY_ATTACHMENT=true` and `DISCORD_MAX_ATTACHMENT_BYTES=33554432` (or `0` for no cap). :::warning Memory cost of unlimited Disabling the size cap (`max_attachment_bytes: 0`) means a user can drop a multi-GB file on the bot and the gateway will dutifully buffer it through memory while caching to disk. Only set this in trusted single-user installs. For shared bots, keep the default 32 MiB or raise it conservatively. ::: ## Interactive Prompts (clarify) When the agent calls the `clarify` tool — to ask which approach you prefer, get post-task feedback, or check before a non-trivial decision — Discord renders the question with one button per choice: > Which framework should I use for the dashboard? > > [1. Next.js] [2. Remix] [3. Astro] [Other (type answer)] Click a numbered button to answer, or click Other to type a free-form response (the next message you send in that channel becomes the answer). Open-ended `clarify` calls (no preset choices) skip the buttons and just capture your next message. The buttons disable themselves once a choice is made so duplicate clicks don't double-resolve the prompt. Configure the response timeout via `agent.clarify_timeout` in `~/.hermes/config.yaml` (default `600` seconds). If you don't respond within the timeout, the agent unblocks with a sentinel message and adapts rather than hanging. ## Home Channel You can designate a "home channel" where the bot sends proactive messages (such as cron job output, reminders, and notifications). There are two ways to set it: ### Using the Slash Command Type `/sethome` in any Discord channel where the bot is present. That channel becomes the home channel. ### Manual Configuration Add these to your `~/.hermes/.env`: ```bash DISCORD_HOME_CHANNEL=123456789012345678 DISCORD_HOME_CHANNEL_NAME="#bot-updates" ``` Replace the ID with the actual channel ID (right-click → Copy Channel ID with Developer Mode on). ## Voice Messages Hermes Agent supports Discord voice messages: - Incoming voice messages are automatically transcribed using the configured STT provider: local `faster-whisper` (no key), Groq Whisper (`GROQ_API_KEY`), or OpenAI Whisper (`VOICE_TOOLS_OPENAI_KEY`). - Text-to-speech: Use `/voice tts` to have the bot send spoken audio responses alongside text replies. - Discord voice channels: Hermes can also join a voice channel, listen to users speaking, and talk back in the channel. For the full setup and operational guide, see: - [Voice Mode](/user-guide/features/voice-mode) - [Use Voice Mode with Hermes](/guides/use-voice-mode-with-hermes) ### Voice Channel Audio Effects (ambient + verbal acks) When the bot is in a voice channel, you can give it a more conversational feel: a short verbal acknowledgement ("let me look into that") before it starts working, and a subtle ambient "thinking" bed that plays underneath while tools run — the speech ducks the ambient down and swells it back when finished, similar to Grok voice mode. discord.py plays only one audio stream per connection, so Hermes installs a software mixer on the outgoing stream that sums an ambient loop, acknowledgements, and TTS replies into that single stream — they overlap instead of cutting each other off. This is off by default. Enable it in `config.yaml`: ```yaml discord: voice_fx: enabled: true # master switch ambient_enabled: true # idle "thinking" bed while tools run ambient_path: "" # custom loop file (any audio format); "" = built-in synthesised pad ambient_gain: 0.18 # idle bed loudness (0.0–1.0) duck_gain: 0.06 # ambient loudness while the bot is speaking speech_gain: 1.0 # TTS / acknowledgement loudness ack_enabled: true # speak a short phrase before the first tool call of a turn ack_phrases: # picked at random; set to [] to disable the spoken ack - "Let me look into that." - "One moment." - "Checking on that now." ``` Notes: - The acknowledgement fires at most once per turn, only when the bot is in a voice channel and the mixer is active. It uses your configured TTS provider. - `ambient_path` accepts any file `ffmpeg` can decode; it's looped seamlessly. Leave it empty to use the built-in synthesised pad (no asset needed). - All settings live in `config.yaml` (not `.env`) — they're behavioral, not secrets. - When `voice_fx.enabled` is `false`, voice playback uses the original one-shot path and nothing changes. ## Forum Channels Discord forum channels (type 15) don't accept direct messages — every post in a forum must be a thread. Hermes auto-detects forum channels and creates a new thread post whenever it needs to send there, so `send_message`, TTS, images, voice messages, and file attachments all work without special handling from the agent. - Thread name is derived from the first line of the message (markdown heading prefix stripped, capped at 100 chars). When the message is attachment-only, the filename is used as the fallback thread name. - Attachments ride along on the starter message of the new thread — no separate upload step, no partial sends. - One call, one thread: each forum send creates a new thread. Successive sends to the same forum will therefore produce separate threads. - Detection is three-layered: the channel directory cache first, a process-local probe cache second, and a live `GET /channels/{id}` probe as a last resort (whose result is then memoized for the life of the process). Refreshing the directory (`/channels refresh` on platforms that expose it, or a gateway restart) populates the cache with any forum channels created after the bot started. ## Troubleshooting ### Bot is online but not responding to messages Cause: Message Content Intent is disabled. Fix: Go to [Developer Portal](https://discord.com/developers/applications) → your app → Bot → Privileged Gateway Intents → enable Message Content Intent → Save Changes. Restart the gateway. ### "Disallowed Intents" error on startup Cause: Your code requests intents that aren't enabled in the Developer Portal. Fix: Enable all three Privileged Gateway Intents (Presence, Server Members, Message Content) in the Bot settings, then restart. ### Bot can't see messages in a specific channel Cause: The bot's role doesn't have permission to view that channel. Fix: In Discord, go to the channel's settings → Permissions → add the bot's role with View Channel and Read Message History enabled. ### 403 Forbidden errors Cause: The bot is missing required permissions. Fix: Re-invite the bot with the correct permissions using the URL from Step 5, or manually adjust the bot's role permissions in Server Settings → Roles. ### Bot is offline Cause: The Hermes gateway isn't running, or the token is incorrect. Fix: Check that `hermes gateway` is running. Verify `DISCORD_BOT_TOKEN` in your `.env` file. If you recently reset the token, update it. ### "User not allowed" / Bot ignores you Cause: Your User ID isn't in `DISCORD_ALLOWED_USERS`. Fix: Add your User ID to `DISCORD_ALLOWED_USERS` in `~/.hermes/.env` and restart the gateway. ### People in the same channel are sharing context unexpectedly Cause: `group_sessions_per_user` is disabled, or the platform cannot provide a user ID for the messages in that context. Fix: Set this in `~/.hermes/config.yaml` and restart the gateway: ```yaml group_sessions_per_user: true ``` If you intentionally want a shared room conversation, leave it off — just expect shared transcript history and shared interrupt behavior. ## Security :::warning Always set `DISCORD_ALLOWED_USERS` (or `DISCORD_ALLOWED_ROLES`) to restrict who can interact with the bot. Without either, the gateway denies all users by default as a safety measure. Only authorize people you trust — authorized users have full access to the agent's capabilities, including tool use and system access. ::: ### Role-Based Access Control For servers where access is managed by roles instead of individual user lists (moderator teams, support staff, internal tooling), use `DISCORD_ALLOWED_ROLES` — a comma-separated list of role IDs. Any member with one of those roles is authorized. ```bash # ~/.hermes/.env — works alongside or instead of DISCORD_ALLOWED_USERS DISCORD_ALLOWED_ROLES=987654321098765432,876543210987654321 ``` Semantics: - OR with user allowlist. A user is authorized if their ID is in `DISCORD_ALLOWED_USERS` or they have any role in `DISCORD_ALLOWED_ROLES`. - Server Members Intent auto-enabled. When `DISCORD_ALLOWED_ROLES` is set, the bot enables the Members intent on connect — required for Discord to send role information with member records. - Role IDs, not names. Grab them from Discord: User Settings → Advanced → Developer Mode ON, then right-click any role → Copy Role ID. - DM fallback. In DMs the role check scans mutual guilds; a user with an allowed role in any shared server is authorized in DMs too. This is the preferred pattern when the moderation team churns — new moderators get access the moment the role is granted, with no `.env` edit or gateway restart. ### Mention Control By default, Hermes blocks the bot from pinging `@everyone`, `@here`, and role mentions, even if its reply contains those tokens. This prevents a poorly-worded prompt or echoed user content from spamming a whole server. Individual `@user` pings and reply-reference pings (the little "replying to…" chip) stay enabled so normal conversation still works. You can relax these defaults via either env vars or `config.yaml`: ```yaml # ~/.hermes/config.yaml discord: allow_mentions: everyone: false # allow the bot to ping @everyone / @here roles: false # allow the bot to ping @role mentions users: true # allow the bot to ping individual @users replied_user: true # ping the author when replying to their message ``` ```bash # ~/.hermes/.env — env vars win over config.yaml DISCORD_ALLOW_MENTION_EVERYONE=false DISCORD_ALLOW_MENTION_ROLES=false DISCORD_ALLOW_MENTION_USERS=true DISCORD_ALLOW_MENTION_REPLIED_USER=true ``` :::tip Leave `everyone` and `roles` at `false` unless you know exactly why you need them. It is very easy for an LLM to produce the string `@everyone` inside a normal-looking response; without this protection, that would notify every member of your server. ::: For more information on securing your Hermes Agent deployment, see the [Security Guide](../security.md). ---  # Slack # Slack Setup Connect Hermes Agent to Slack as a bot using Socket Mode. Socket Mode uses WebSockets instead of public HTTP endpoints, so your Hermes instance doesn't need to be publicly accessible — it works behind firewalls, on your laptop, or on a private server. :::warning Classic Slack Apps Deprecated Classic Slack apps (using RTM API) were fully deprecated in March 2025. Hermes uses the modern Bolt SDK with Socket Mode. If you have an old classic app, you must create a new one following the steps below. ::: ## Overview | Component | Value | |-----------|-------| | Library | `slack-bolt` / `slack_sdk` for Python (Socket Mode) | | Connection | WebSocket — no public URL required | | Auth tokens needed | Bot Token (`xoxb-`) + App-Level Token (`xapp-`) | | User identification | Slack Member IDs (e.g., `U01ABC2DEF3`) | --- ## Step 1: Create a Slack App The fastest path is to paste a manifest Hermes generates for you. It declares every built-in slash command (`/btw`, `/stop`, `/model`, …), every required OAuth scope, every event subscription, and enables Socket Mode — all at once. ### Option A: From a Hermes-generated manifest (recommended) 1. Generate the manifest: ```bash hermes slack manifest --write ``` This writes `~/.hermes/slack-manifest.json` and prints paste-in instructions. 2. Go to [https://api.slack.com/apps](https://api.slack.com/apps) → Create New App → From an app manifest 3. Pick your workspace, paste the JSON contents, review, click Next → Create 4. Skip ahead to Step 6: Install App to Workspace. The manifest handled scopes, events, and slash commands for you. ### Option B: From scratch (manual) 1. Go to [https://api.slack.com/apps](https://api.slack.com/apps) 2. Click Create New App 3. Choose From scratch 4. Enter an app name (e.g., "Hermes Agent") and select your workspace 5. Click Create App You'll land on the app's Basic Information page. Continue with Steps 2–6 below. --- ## Step 2: Configure Bot Token Scopes Navigate to Features → OAuth & Permissions in the sidebar. Scroll to Scopes → Bot Token Scopes and add the following: | Scope | Purpose | |-------|---------| | `chat:write` | Send messages as the bot | | `app_mentions:read` | Detect when @mentioned in channels | | `channels:history` | Read messages in public channels the bot is in | | `channels:read` | List and get info about public channels | | `groups:history` | Read messages in private channels the bot is invited to | | `im:history` | Read direct message history | | `im:read` | View basic DM info | | `im:write` | Open and manage DMs | | `users:read` | Look up user information | | `files:read` | Read and download attached files, including voice notes/audio | | `files:write` | Upload files (images, audio, documents) | :::caution Missing scopes = missing features Without `channels:history` and `groups:history`, the bot will not receive messages in channels — it will only work in DMs. Without `files:read`, Hermes can chat but cannot reliably read user-uploaded attachments. These are the most commonly missed scopes. ::: Optional scopes: | Scope | Purpose | |-------|---------| | `groups:read` | List and get info about private channels | --- ## Step 3: Enable Socket Mode Socket Mode lets the bot connect via WebSocket instead of requiring a public URL. 1. In the sidebar, go to Settings → Socket Mode 2. Toggle Enable Socket Mode to ON 3. You'll be prompted to create an App-Level Token: - Name it something like `hermes-socket` (the name doesn't matter) - Add the `connections:write` scope - Click Generate 4. Copy the token — it starts with `xapp-`. This is your `SLACK_APP_TOKEN` :::tip You can always find or regenerate app-level tokens under Settings → Basic Information → App-Level Tokens. ::: --- ## Step 4: Subscribe to Events This step is critical — it controls what messages the bot can see. 1. In the sidebar, go to Features → Event Subscriptions 2. Toggle Enable Events to ON 3. Expand Subscribe to bot events and add: | Event | Required? | Purpose | |-------|-----------|---------| | `message.im` | Yes | Bot receives direct messages | | `message.channels` | Yes | Bot receives messages in public channels it's added to | | `message.groups` | Recommended | Bot receives messages in private channels it's invited to | | `app_mention` | Yes | Prevents Bolt SDK errors when bot is @mentioned | 4. Click Save Changes at the bottom of the page :::danger Missing event subscriptions is the #1 setup issue If the bot works in DMs but not in channels, you almost certainly forgot to add `message.channels` (for public channels) and/or `message.groups` (for private channels). Without these events, Slack simply never delivers channel messages to the bot. ::: --- ## Step 5: Enable the Messages Tab This step enables direct messages to the bot. Without it, users see "Sending messages to this app has been turned off" when trying to DM the bot. 1. In the sidebar, go to Features → App Home 2. Scroll to Show Tabs 3. Toggle Messages Tab to ON 4. Check "Allow users to send Slash commands and messages from the messages tab" :::danger Without this step, DMs are completely blocked Even with all the correct scopes and event subscriptions, Slack will not allow users to send direct messages to the bot unless the Messages Tab is enabled. This is a Slack platform requirement, not a Hermes configuration issue. ::: --- ## Step 6: Install App to Workspace 1. In the sidebar, go to Settings → Install App 2. Click Install to Workspace 3. Review the permissions and click Allow 4. After authorization, you'll see a Bot User OAuth Token starting with `xoxb-` 5. Copy this token — this is your `SLACK_BOT_TOKEN` :::tip If you change scopes or event subscriptions later, you must reinstall the app for the changes to take effect. The Install App page will show a banner prompting you to do so. ::: --- ## Step 7: Find User IDs for the Allowlist Hermes uses Slack Member IDs (not usernames or display names) for the allowlist. To find a Member ID: 1. In Slack, click on the user's name or avatar 2. Click View full profile 3. Click the ⋮ (more) button 4. Select Copy member ID Member IDs look like `U01ABC2DEF3`. You need your own Member ID at minimum. --- ## Step 8: Configure Hermes Add the following to your `~/.hermes/.env` file: ```bash # Required SLACK_BOT_TOKEN=xoxb-your-bot-token-here SLACK_APP_TOKEN=xapp-your-app-token-here SLACK_ALLOWED_USERS=U01ABC2DEF3 # Comma-separated Member IDs # Optional SLACK_HOME_CHANNEL=C01234567890 # Default channel for cron/scheduled messages SLACK_HOME_CHANNEL_NAME=general # Human-readable name for the home channel (optional) ``` Or run the interactive setup: ```bash hermes gateway setup # Select Slack when prompted ``` Then start the gateway: ```bash hermes gateway # Foreground hermes gateway install # Install as a user service sudo hermes gateway install --system # Linux only: boot-time system service ``` --- ## Step 9: Invite the Bot to Channels After starting the gateway, you need to invite the bot to any channel where you want it to respond: ``` /invite @Hermes Agent ``` The bot will not automatically join channels. You must invite it to each channel individually. --- ## Slash Commands Every Hermes command (`/btw`, `/stop`, `/new`, `/model`, `/help`, ...) is a native Slack slash command — exactly the way they work on Telegram and Discord. Type `/` in Slack and the autocomplete picker lists every Hermes command with its description. Under the hood: Hermes ships with a generated Slack app manifest (see Step 1, Option A) that declares every command in [`COMMAND_REGISTRY`](https://github.com/NousResearch/hermes-agent/blob/main/hermes_cli/commands.py) as a slash command. In Socket Mode, Slack routes the command event through the WebSocket regardless of the manifest's `url` field. ### Refreshing slash commands after updates When Hermes adds new commands (e.g. after `hermes update`), regenerate the manifest and update your Slack app: ```bash hermes slack manifest --write ``` Then in Slack: 1. Open [https://api.slack.com/apps](https://api.slack.com/apps) → your Hermes app 2. Features → App Manifest → Edit 3. Paste the new contents of `~/.hermes/slack-manifest.json` 4. Save. Slack will prompt to reinstall the app if scopes or slash commands changed. ### Legacy `/hermes <subcommand>` still works For backward compatibility with older manifests, you can still type `/hermes btw run the tests` — Hermes routes it the same way as `/btw run the tests`. Free-form questions also work: `/hermes what's the weather?` is treated as a regular message. ### Using commands inside threads (the `!cmd` prefix) Slack itself blocks native slash commands inside thread replies — try `/queue` in a thread and Slack responds with "/queue is not supported in threads. Sorry!" There is no app-side setting that re-enables them; Slack never delivers them to Hermes. As a workaround, Hermes recognises a leading `!` as an alternate command prefix that works in threads (and anywhere else). Type `!queue`, `!stop`, `!model gpt-5.4`, etc. as a regular thread reply — Hermes treats it identically to the slash form and replies in the same thread. Only the first token is checked against the known command list, so casual messages like `!nice work` pass through to the agent unchanged. ### Advanced: emit only the slash-commands array If you maintain your Slack manifest by hand and just want the slash command list: ```bash hermes slack manifest --slashes-only > /tmp/slashes.json ``` Paste that array into the `features.slash_commands` key of your existing manifest. --- ## How the Bot Responds Understanding how Hermes behaves in different contexts: | Context | Behavior | |---------|----------| | DMs | Bot responds to every message — no @mention needed | | Channels | Bot only responds when @mentioned (e.g., `@Hermes Agent what time is it?`). In channels, Hermes replies in a thread attached to that message. | | Threads | If you @mention Hermes inside an existing thread, it replies in that same thread. Once the bot has an active session in a thread, subsequent replies in that thread do not require @mention — the bot follows the conversation naturally. | :::tip In channels, always @mention the bot to start a conversation. Once the bot is active in a thread, you can reply in that thread without mentioning it. Outside of threads, messages without @mention are ignored to prevent noise in busy channels. ::: --- ## Configuration Options Beyond the required environment variables from Step 8, you can customize Slack bot behavior through `~/.hermes/config.yaml`. ### Thread & Reply Behavior ```yaml platforms: slack: # Controls how multi-part responses are threaded # "off" — never thread replies to the original message # "first" — first chunk threads to user's message (default) # "all" — all chunks thread to user's message reply_to_mode: "first" extra: # Whether to reply in a thread (default: true). # When false, channel messages get direct channel replies instead # of threads. Messages inside existing threads still reply in-thread. reply_in_thread: true # Also post thread replies to the main channel # (Slack's "Also send to channel" feature). # Only the first chunk of the first reply is broadcast. reply_broadcast: false ``` | Key | Default | Description | |-----|---------|-------------| | `platforms.slack.reply_to_mode` | `"first"` | Threading mode for multi-part messages: `"off"`, `"first"`, or `"all"` | | `platforms.slack.extra.reply_in_thread` | `true` | When `false`, channel messages get direct replies instead of threads. Messages inside existing threads still reply in-thread. | | `platforms.slack.extra.reply_broadcast` | `false` | When `true`, thread replies are also posted to the main channel. Only the first chunk is broadcast. | ### Session Isolation ```yaml # Global setting — applies to Slack and all other platforms group_sessions_per_user: true ``` When `true` (the default), each user in a shared channel gets their own isolated conversation session. Two people talking to Hermes in `#general` will have separate histories and contexts. Set to `false` if you want a collaborative mode where the entire channel shares one conversation session. Be aware this means users share context growth and token costs, and one user's `/reset` clears the session for everyone. ### Mention & Trigger Behavior ```yaml slack: # Require @mention in channels (this is the default behavior; # the Slack adapter enforces @mention gating in channels regardless, # but you can set this explicitly for consistency with other platforms) require_mention: true # Prevent thread auto-engagement: only reply to channel messages that # contain an explicit @mention. With this OFF (default), Slack can # "auto-engage" — remembering past mentions in a thread and following # up on bot-message replies, and resuming active sessions without a # fresh mention. With strict_mention ON, every new channel message # must @mention the bot before Hermes will respond. strict_mention: false # Custom mention patterns that trigger the bot # (in addition to the default @mention detection) mention_patterns: - "hey hermes" - "hermes," # Text prepended to every outgoing message reply_prefix: "" ``` :::tip When to use `strict_mention` Set this to `true` in busy workspaces where Slack's default "the bot remembers this thread" behavior surprises users — for example, a long tech-support thread where the bot helped at the start and you'd rather it stay silent unless explicitly pinged again. DMs and active interactive sessions are unaffected. ::: :::info Slack supports both patterns: `@mention` required to start a conversation by default, but you can opt specific channels out via `SLACK_FREE_RESPONSE_CHANNELS` (comma-separated channel IDs) or `slack.free_response_channels` in `config.yaml`. Once the bot has an active session in a thread, subsequent thread replies do not require a mention. In DMs the bot always responds without needing a mention. ::: ### Channel allowlist (`allowed_channels`) Restrict the bot to a fixed set of Slack channels — useful when the bot is invited to many channels but should only respond in a few. When set, messages from channels NOT in this list are silently ignored, even if the bot is `@mentioned`. DMs are exempt from this filter, so authorized users can always reach the bot in a direct message. ```yaml slack: allowed_channels: - "C0123456789" # #ops - "C0987654321" # #incident-response ``` Or via env var (comma-separated): ```bash SLACK_ALLOWED_CHANNELS="C0123456789,C0987654321" ``` Behavior: - Empty / unset → no restriction (fully backward compatible). - Non-empty → channel ID must be on the list, or the message is dropped before any other gating (mention requirement, `free_response_channels`, etc.) runs. - Slack channel IDs start with `C` (public), `G` (private), or `D` (DM). Look them up via the Slack UI's "Open channel details" → "About" panel, or via the API. See also: [admin/user slash command split](../../reference/slash-commands.md#permissions-and-adminuser-split). ### Unauthorized User Handling ```yaml slack: # What happens when an unauthorized user (not in SLACK_ALLOWED_USERS) DMs the bot # "pair" — prompt them for a pairing code (default) # "ignore" — silently drop the message unauthorized_dm_behavior: "pair" ``` You can also set this globally for all platforms: ```yaml unauthorized_dm_behavior: "pair" ``` The platform-specific setting under `slack:` takes precedence over the global setting. ### Voice Transcription ```yaml # Global setting — enable/disable automatic transcription of incoming voice messages stt_enabled: true ``` When `true` (the default), incoming audio messages are automatically transcribed using the configured STT provider before being processed by the agent. ### Full Example ```yaml # Global gateway settings group_sessions_per_user: true unauthorized_dm_behavior: "pair" stt_enabled: true # Slack-specific settings slack: require_mention: true unauthorized_dm_behavior: "pair" # Platform config platforms: slack: reply_to_mode: "first" extra: reply_in_thread: true reply_broadcast: false ``` --- ## Home Channel Set `SLACK_HOME_CHANNEL` to a channel ID where Hermes will deliver scheduled messages, cron job results, and other proactive notifications. To find a channel ID: 1. Right-click the channel name in Slack 2. Click View channel details 3. Scroll to the bottom — the Channel ID is shown there ```bash SLACK_HOME_CHANNEL=C01234567890 ``` Make sure the bot has been invited to the channel (`/invite @Hermes Agent`). --- ## Multi-Workspace Support Hermes can connect to multiple Slack workspaces simultaneously using a single gateway instance. Each workspace is authenticated independently with its own bot user ID. ### Configuration Provide multiple bot tokens as a comma-separated list in `SLACK_BOT_TOKEN`: ```bash # Multiple bot tokens — one per workspace SLACK_BOT_TOKEN=xoxb-workspace1-token,xoxb-workspace2-token,xoxb-workspace3-token # A single app-level token is still used for Socket Mode SLACK_APP_TOKEN=xapp-your-app-token ``` Or in `~/.hermes/config.yaml`: ```yaml platforms: slack: token: "xoxb-workspace1-token,xoxb-workspace2-token" ``` ### OAuth Token File In addition to tokens in the environment or config, Hermes also loads tokens from an OAuth token file at: ``` ~/.hermes/slack_tokens.json ``` This file is a JSON object mapping team IDs to token entries: ```json { "T01ABC2DEF3": { "token": "xoxb-workspace-token-here", "team_name": "My Workspace" } } ``` Tokens from this file are merged with any tokens specified via `SLACK_BOT_TOKEN`. Duplicate tokens are automatically deduplicated. ### How it works - The first token in the list is the primary token, used for the Socket Mode connection (AsyncApp). - Each token is authenticated via `auth.test` on startup. The gateway maps each `team_id` to its own `WebClient` and `bot_user_id`. - When a message arrives, Hermes uses the correct workspace-specific client to respond. - The primary `bot_user_id` (from the first token) is used for backward compatibility with features that expect a single bot identity. --- ## Voice Messages Hermes supports voice on Slack: - Incoming: Voice/audio messages are automatically transcribed using the configured STT provider: local `faster-whisper`, Groq Whisper (`GROQ_API_KEY`), or OpenAI Whisper (`VOICE_TOOLS_OPENAI_KEY`) - Outgoing: TTS responses are sent as audio file attachments --- ## Per-Channel Prompts Assign ephemeral system prompts to specific Slack channels. The prompt is injected at runtime on every turn — never persisted to transcript history — so changes take effect immediately. ```yaml slack: channel_prompts: "C01RESEARCH": | You are a research assistant. Focus on academic sources, citations, and concise synthesis. "C02ENGINEERING": | Code review mode. Be precise about edge cases and performance implications. ``` Keys are Slack channel IDs (find them via channel details → "About" → scroll to bottom). All messages in the matching channel get the prompt injected as an ephemeral system instruction. ## Per-Channel Skill Bindings Auto-load a skill whenever a new session starts in a specific channel or DM. Unlike per-channel prompts (which are injected on every turn), skill bindings inject the skill content as a user message at session start — it becomes part of the conversation history and does not need to be reloaded on subsequent turns. This is ideal for DMs or channels with a dedicated purpose (flashcards, a domain-specific Q&A bot, a support triage channel, etc.) where you don't want the model's own skill selector to decide whether to load on every short reply. ```yaml slack: channel_skill_bindings: # DM channel — always runs in "german-flashcards" mode - id: "D0ATH9TQ0G6" skills: - german-flashcards # Research channel — preload multiple skills in order - id: "C01RESEARCH" skills: - arxiv - writing-plans # Short form: single skill as a string - id: "C02SUPPORT" skill: hubspot-on-demand ``` Notes: - The binding matches by channel ID. For threaded messages in a bound channel, the thread inherits the parent channel's binding. - The skill is loaded only at session start (new session or after auto-reset). If you change the binding, run `/new` or wait for the session to auto-reset for it to take effect. - Combine with `channel_prompts` for per-channel tone/constraints on top of the skill's instructions. ## Troubleshooting | Problem | Solution | |---------|----------| | Bot doesn't respond to DMs | Verify `message.im` is in your event subscriptions and the app is reinstalled | | Bot works in DMs but not in channels | Most common issue. Add `message.channels` and `message.groups` to event subscriptions, reinstall the app, and invite the bot to the channel with `/invite @Hermes Agent` | | Bot doesn't respond to @mentions in channels | 1) Check `message.channels` event is subscribed. 2) Bot must be invited to the channel. 3) Ensure `channels:history` scope is added. 4) Reinstall the app after scope/event changes | | Bot ignores messages in private channels | Add both the `message.groups` event subscription and `groups:history` scope, then reinstall the app and `/invite` the bot | | "Sending messages to this app has been turned off" in DMs | Enable the Messages Tab in App Home settings (see Step 5) | | "not_authed" or "invalid_auth" errors | Regenerate your Bot Token and App Token, update `.env` | | Bot responds but can't post in a channel | Invite the bot to the channel with `/invite @Hermes Agent` | | Bot can chat but can't read uploaded images/files | Add `files:read`, then reinstall the app. Hermes now surfaces attachment access diagnostics in-chat when Slack returns scope/auth/permission failures. | | `missing_scope` error | Add the required scope in OAuth & Permissions, then reinstall the app | | Socket disconnects frequently | Check your network; Bolt auto-reconnects but unstable connections cause lag | | Changed scopes/events but nothing changed | You must reinstall the app to your workspace after any scope or event subscription change | ### Quick Checklist If the bot isn't working in channels, verify all of the following: 1. ✅ `message.channels` event is subscribed (for public channels) 2. ✅ `message.groups` event is subscribed (for private channels) 3. ✅ `app_mention` event is subscribed 4. ✅ `channels:history` scope is added (for public channels) 5. ✅ `groups:history` scope is added (for private channels) 6. ✅ App was reinstalled after adding scopes/events 7. ✅ Bot was invited to the channel (`/invite @Hermes Agent`) 8. ✅ You are @mentioning the bot in your message --- ## Security :::warning Always set `SLACK_ALLOWED_USERS` with the Member IDs of authorized users. Without this setting, the gateway will deny all messages by default as a safety measure. Never share your bot tokens — treat them like passwords. ::: - Tokens should be stored in `~/.hermes/.env` (file permissions `600`) - Rotate tokens periodically via the Slack app settings - Audit who has access to your Hermes config directory - Socket Mode means no public endpoint is exposed — one less attack surface ---  # WhatsApp # WhatsApp Setup Hermes connects to WhatsApp through a built-in bridge based on Baileys. This works by emulating a WhatsApp Web session — not through the official WhatsApp Business API. No Meta developer account or Business verification is required. > Run `hermes gateway setup` and pick WhatsApp for a guided walk-through. :::warning Unofficial API — Ban Risk WhatsApp does not officially support third-party bots outside the Business API. Using a third-party bridge carries a small risk of account restrictions. To minimize risk: - Use a dedicated phone number for the bot (not your personal number) - Don't send bulk/spam messages — keep usage conversational - Don't automate outbound messaging to people who haven't messaged first ::: :::warning WhatsApp Web Protocol Updates WhatsApp periodically updates their Web protocol, which can temporarily break compatibility with third-party bridges. When this happens, Hermes will update the bridge dependency. If the bot stops working after a WhatsApp update, pull the latest Hermes version and re-pair. ::: ## Two Modes | Mode | How it works | Best for | |------|-------------|----------| | Separate bot number (recommended) | Dedicate a phone number to the bot. People message that number directly. | Clean UX, multiple users, lower ban risk | | Personal self-chat | Use your own WhatsApp. You message yourself to talk to the agent. | Quick setup, single user, testing | --- ## Prerequisites - Node.js v18+ and npm — the WhatsApp bridge runs as a Node.js process - A phone with WhatsApp installed (for scanning the QR code) Unlike older browser-driven bridges, the current Baileys-based bridge does not require a local Chromium or Puppeteer dependency stack. --- ## Step 1: Run the Setup Wizard ```bash hermes whatsapp ``` The wizard will: 1. Ask which mode you want (bot or self-chat) 2. Install bridge dependencies if needed 3. Display a QR code in your terminal 4. Wait for you to scan it To scan the QR code: 1. Open WhatsApp on your phone 2. Go to Settings → Linked Devices 3. Tap Link a Device 4. Point your camera at the terminal QR code Once paired, the wizard confirms the connection and exits. Your session is saved automatically. :::tip If the QR code looks garbled, make sure your terminal is at least 60 columns wide and supports Unicode. You can also try a different terminal emulator. ::: --- ## Step 2: Getting a Second Phone Number (Bot Mode) For bot mode, you need a phone number that isn't already registered with WhatsApp. Three options: | Option | Cost | Notes | |--------|------|-------| | Google Voice | Free | US only. Get a number at [voice.google.com](https://voice.google.com). Verify WhatsApp via SMS through the Google Voice app. | | Prepaid SIM | $5–15 one-time | Any carrier. Activate, verify WhatsApp, then the SIM can sit in a drawer. Number must stay active (make a call every 90 days). | | VoIP services | Free–$5/month | TextNow, TextFree, or similar. Some VoIP numbers are blocked by WhatsApp — try a few if the first doesn't work. | After getting the number: 1. Install WhatsApp on a phone (or use WhatsApp Business app with dual-SIM) 2. Register the new number with WhatsApp 3. Run `hermes whatsapp` and scan the QR code from that WhatsApp account --- ## Step 3: Configure Hermes Add the following to your `~/.hermes/.env` file: ```bash # Required WHATSAPP_ENABLED=true WHATSAPP_MODE=bot # "bot" or "self-chat" # Access control — pick ONE of these options: WHATSAPP_ALLOWED_USERS=15551234567 # Comma-separated phone numbers (with country code, no +) # WHATSAPP_ALLOWED_USERS=* # OR use * to allow everyone # WHATSAPP_ALLOW_ALL_USERS=true # OR set this flag instead (same effect as ) ``` :::tip Allow-all shorthand Setting `WHATSAPP_ALLOWED_USERS=` allows all senders (equivalent to `WHATSAPP_ALLOW_ALL_USERS=true`). This is consistent with [Signal group allowlists](/reference/environment-variables). To use the pairing flow instead, remove both variables and rely on the [DM pairing system](/user-guide/security#dm-pairing-system). ::: Optional behavior settings in `~/.hermes/config.yaml`: ```yaml unauthorized_dm_behavior: pair whatsapp: unauthorized_dm_behavior: ignore ``` - `unauthorized_dm_behavior: pair` is the global default. Unknown DM senders get a pairing code. - `whatsapp.unauthorized_dm_behavior: ignore` makes WhatsApp stay silent for unauthorized DMs, which is usually the better choice for a private number. Then start the gateway: ```bash hermes gateway # Foreground hermes gateway install # Install as a user service sudo hermes gateway install --system # Linux only: boot-time system service ``` The gateway starts the WhatsApp bridge automatically using the saved session. --- ## Session Persistence The Baileys bridge saves its session under `~/.hermes/platforms/whatsapp/session`. This means: - Sessions survive restarts — you don't need to re-scan the QR code every time - The session data includes encryption keys and device credentials - Do not share or commit this session directory — it grants full access to the WhatsApp account --- ## Re-pairing If the session breaks (phone reset, WhatsApp update, manually unlinked), you'll see connection errors in the gateway logs. To fix it: ```bash hermes whatsapp ``` This generates a fresh QR code. Scan it again and the session is re-established. The gateway handles temporary disconnections (network blips, phone going offline briefly) automatically with reconnection logic. --- ## Voice Messages Hermes supports voice on WhatsApp: - Incoming: Voice messages (`.ogg` opus) are automatically transcribed using the configured STT provider: local `faster-whisper`, Groq Whisper (`GROQ_API_KEY`), or OpenAI Whisper (`VOICE_TOOLS_OPENAI_KEY`) - Outgoing: TTS responses are sent as MP3 audio file attachments - Agent responses are prefixed with "⚕ Hermes Agent" by default. You can customize or disable this in `config.yaml`: ```yaml # ~/.hermes/config.yaml whatsapp: reply_prefix: "" # Empty string disables the header # reply_prefix: "🤖 My Bot\n──────\n" # Custom prefix (supports \n for newlines) ``` --- ## Message Formatting & Delivery WhatsApp supports streaming (progressive) responses — the bot edits its message in real-time as the AI generates text, just like Discord and Telegram. Internally, WhatsApp is classified as a TIER_MEDIUM platform for delivery capabilities. ### Chunking Long responses are automatically split into multiple messages at 4,096 characters per chunk (WhatsApp's practical display limit). You don't need to configure anything — the gateway handles splitting and sends chunks sequentially. ### WhatsApp-Compatible Markdown Standard Markdown in AI responses is automatically converted to WhatsApp's native formatting: | Markdown | WhatsApp | Renders as | |----------|----------|------------| | `bold` | `bold` | bold | | `strikethrough` | `~strikethrough~` | strikethrough | | `# Heading` | `Heading` | Bold text (no native headings) | | `[link text](url)` | `link text (url)` | Inline URL | Code blocks and inline code are preserved as-is since WhatsApp supports triple-backtick formatting natively. ### Tool Progress When the agent calls tools (web search, file operations, etc.), WhatsApp displays real-time progress indicators showing which tool is running. This is enabled by default — no configuration needed. ### Message Batching (Debounce) WhatsApp delivers each message individually, so a rapid burst (forwarded batches, paste-splits, multi-line text) would otherwise trigger a separate agent invocation per fragment — wasting tokens and producing several disjointed replies. The adapter buffers successive text messages from the same chat and dispatches them as one combined request after a short quiet period (default 5s, extended to 10s for very long fragments). Tune via `config.yaml`: ```yaml # ~/.hermes/config.yaml gateway: platforms: whatsapp: extra: text_batch_delay_seconds: 5.0 # quiet period before flushing a batch text_batch_split_delay_seconds: 10.0 # extended delay near the split threshold ``` Set `text_batch_delay_seconds: 0` to dispatch each message immediately (disables batching). --- ## Troubleshooting | Problem | Solution | |---------|----------| | QR code not scanning | Ensure terminal is wide enough (60+ columns). Try a different terminal. Make sure you're scanning from the correct WhatsApp account (bot number, not personal). | | QR code expires | QR codes refresh every ~20 seconds. If it times out, restart `hermes whatsapp`. | | Session not persisting | Check that `~/.hermes/platforms/whatsapp/session` exists and is writable. If containerized, mount it as a persistent volume. | | Logged out unexpectedly | WhatsApp unlinks devices after long inactivity. Keep the phone on and connected to the network, then re-pair with `hermes whatsapp` if needed. | | Bridge crashes or reconnect loops | Restart the gateway, update Hermes, and re-pair if the session was invalidated by a WhatsApp protocol change. | | Bot stops working after WhatsApp update | Update Hermes to get the latest bridge version, then re-pair. | | macOS: "Node.js not installed" but node works in terminal | launchd services don't inherit your shell PATH. Run `hermes gateway install` to re-snapshot your current PATH into the plist, then `hermes gateway start`. See the [Gateway Service docs](./index.md#macos-launchd) for details. | | Messages not being received | Verify `WHATSAPP_ALLOWED_USERS` includes the sender's number (with country code, no `+` or spaces), or set it to `` to allow everyone. Set `WHATSAPP_DEBUG=true` in `.env` and restart the gateway to see raw message events in `bridge.log`. | | Bot replies to strangers with a pairing code | Set `whatsapp.unauthorized_dm_behavior: ignore` in `~/.hermes/config.yaml` if you want unauthorized DMs to be silently ignored instead. | --- ## Security :::warning Configure access control before going live. Set `WHATSAPP_ALLOWED_USERS` with specific phone numbers (including country code, without the `+`), use `` to allow everyone, or set `WHATSAPP_ALLOW_ALL_USERS=true`. Without any of these, the gateway denies all incoming messages as a safety measure. ::: By default, unauthorized DMs still receive a pairing code reply. If you want a private WhatsApp number to stay completely silent to strangers, set: ```yaml whatsapp: unauthorized_dm_behavior: ignore ``` - The `~/.hermes/platforms/whatsapp/session` directory contains full session credentials — protect it like a password - Set file permissions: `chmod 700 ~/.hermes/platforms/whatsapp/session` - Use a dedicated phone number for the bot to isolate risk from your personal account - If you suspect compromise, unlink the device from WhatsApp → Settings → Linked Devices - Phone numbers in logs are partially redacted, but review your log retention policy ---  # Signal # Signal Setup Hermes connects to Signal through the [signal-cli](https://github.com/AsamK/signal-cli) daemon running in HTTP mode. The adapter streams messages in real-time via SSE (Server-Sent Events) and sends responses via JSON-RPC. Signal is the most privacy-focused mainstream messenger — end-to-end encrypted by default, open-source protocol, minimal metadata collection. This makes it ideal for security-sensitive agent workflows. :::info No New Python Dependencies The Signal adapter uses `httpx` (already a core Hermes dependency) for all communication. No additional Python packages are required. You just need signal-cli installed externally. ::: --- ## Prerequisites - signal-cli — Java-based Signal client ([GitHub](https://github.com/AsamK/signal-cli)) - Java 17+ runtime — required by signal-cli - A phone number with Signal installed (for linking as a secondary device) ### Installing signal-cli ```bash # macOS brew install signal-cli # Linux (download latest release) VERSION=$(curl -Ls -o /dev/null -w %{url_effective} \ https://github.com/AsamK/signal-cli/releases/latest | sed 's/^.\/v//') curl -L -O "https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}.tar.gz" sudo tar xf "signal-cli-${VERSION}.tar.gz" -C /opt sudo ln -sf "/opt/signal-cli-${VERSION}/bin/signal-cli" /usr/local/bin/ ``` :::caution signal-cli is not in apt or snap repositories. The Linux install above downloads directly from [GitHub releases](https://github.com/AsamK/signal-cli/releases). ::: --- ## Step 1: Link Your Signal Account Signal-cli works as a linked device — like WhatsApp Web, but for Signal. Your phone stays the primary device. ```bash # Generate a linking URI (displays a QR code or link) signal-cli link -n "HermesAgent" ``` 1. Open Signal on your phone 2. Go to Settings → Linked Devices 3. Tap Link New Device 4. Scan the QR code or enter the URI --- ## Step 2: Start the signal-cli Daemon ```bash # Replace +1234567890 with your Signal phone number (E.164 format) signal-cli --account +1234567890 daemon --http 127.0.0.1:8080 ``` :::tip Keep this running in the background. You can use `systemd`, `tmux`, `screen`, or run it as a service. ::: Verify it's running: ```bash curl http://127.0.0.1:8080/api/v1/check # Should return: {"versions":{"signal-cli":...}} ``` --- ## Step 3: Configure Hermes The easiest way: ```bash hermes gateway setup ``` Select Signal from the platform menu. The wizard will: 1. Check if signal-cli is installed 2. Prompt for the HTTP URL (default: `http://127.0.0.1:8080`) 3. Test connectivity to the daemon 4. Ask for your account phone number 5. Configure allowed users and access policies ### Manual Configuration Add to `~/.hermes/.env`: ```bash # Required SIGNAL_HTTP_URL=http://127.0.0.1:8080 SIGNAL_ACCOUNT=+1234567890 # Security (recommended) SIGNAL_ALLOWED_USERS=+1234567890,+0987654321 # Comma-separated E.164 numbers or UUIDs # Optional SIGNAL_GROUP_ALLOWED_USERS=groupId1,groupId2 # Enable groups (omit to disable, for all) SIGNAL_HOME_CHANNEL=+1234567890 # Default delivery target for cron jobs ``` Then start the gateway: ```bash hermes gateway # Foreground hermes gateway install # Install as a user service sudo hermes gateway install --system # Linux only: boot-time system service ``` --- ## Access Control ### DM Access DM access follows the same pattern as all other Hermes platforms: 1. `SIGNAL_ALLOWED_USERS` set → only those users can message 2. No allowlist set → unknown users get a DM pairing code (approve via `hermes pairing approve signal CODE`) 3. `SIGNAL_ALLOW_ALL_USERS=true` → anyone can message (use with caution) ### Group Access Group access is controlled by the `SIGNAL_GROUP_ALLOWED_USERS` env var: | Configuration | Behavior | |---------------|----------| | Not set (default) | All group messages are ignored. The bot only responds to DMs. | | Set with group IDs | Only listed groups are monitored (e.g., `groupId1,groupId2`). | | Set to `` | The bot responds in any group it's a member of. | --- ## Features ### Attachments The adapter supports sending and receiving media in both directions. Incoming (user → agent): - Images — PNG, JPEG, GIF, WebP (auto-detected via magic bytes) - Audio — MP3, OGG, WAV, M4A (voice messages transcribed if Whisper is configured) - Documents — PDF, ZIP, and other file types Outgoing (agent → user): The agent can send media files via `MEDIA:` tags in responses. The following delivery methods are supported: - Images — `send_multiple_images` and `send_image_file` send PNG, JPEG, GIF, WebP as native Signal attachments - Voice — `send_voice` sends audio files (OGG, MP3, WAV, M4A, AAC) as attachments - Video — `send_video` sends MP4 video files - Documents — `send_document` sends any file type (PDF, ZIP, etc.) All outgoing media goes through Signal's standard attachment API. Unlike some platforms, Signal does not distinguish between voice messages and file attachments at the protocol level. Attachment size limit: 100 MB (both directions). :::warning Signal servers will rate-limit attachment uploads, the adapter uses a scheduler for multiple image sending that batches images in groups of 32 and throttles uploads to match the Signal server policy. ::: ### Native Formatting, Reply Quotes, and Reactions Signal messages render with native formatting instead of literal markdown characters. The adapter converts markdown (`bold`, `italic`, `code` , `strike`, `||spoiler||`, headings) into Signal `bodyRanges` so the text shows up with real styling on the recipient's client rather than as visible `` / `` characters. Reply quotes. When Hermes replies to a specific message, it now posts a native reply that quotes the original — same UI affordance Signal users see when they use "Reply" themselves. This is automatic for replies generated in response to an inbound message. Reactions. The agent can react to messages via the standard reaction API; reactions surface in Signal as emoji reactions on the referenced message rather than as extra text. None of this requires additional config — it ships on by default in recent signal-cli builds. If yoursignal-cli`version is too old, Hermes falls back to plaintext delivery and logs a one-time warning. ### Typing Indicators The bot sends typing indicators while processing messages, refreshing every 8 seconds. ### Tool Progress Display Signal does not support editing already-sent messages. Hermes therefore suppresses gateway tool-progress bubbles on Signal, even when`/verbose `is enabled and saves a non-`off`mode for the platform. You can still see tool activity in the CLI, and final Signal replies can include normal assistant output. If you need live per-tool progress in chat, use a messaging platform with message editing support. ### Phone Number Redaction All phone numbers are automatically redacted in logs: -`+15551234567`→`+1554567`- This applies to both Hermes gateway logs and the global redaction system ### Note to Self (Single-Number Setup) If you run signal-cli as a linked secondary device on your own phone number (rather than a separate bot number), you can interact with Hermes through Signal's "Note to Self" feature. Just send a message to yourself from your phone — signal-cli picks it up and Hermes responds in the same conversation. How it works: - "Note to Self" messages arrive as`syncMessage.sentMessage`envelopes - The adapter detects when these are addressed to the bot's own account and processes them as regular inbound messages - Echo-back protection (sent-timestamp tracking) prevents infinite loops — the bot's own replies are filtered out automatically No extra configuration needed. This works automatically as long as`SIGNAL_ACCOUNT`matches your phone number. ### Health Monitoring The adapter monitors the SSE connection and automatically reconnects if: - The connection drops (with exponential backoff: 2s → 60s) - No activity is detected for 120 seconds (pings signal-cli to verify) --- ## Troubleshooting | Problem | Solution | |---------|----------| | "Cannot reach signal-cli" during setup | Ensure signal-cli daemon is running:`signal-cli –account +YOUR_NUMBER daemon –http 127.0.0.1:8080`| | Messages not received | Check that`SIGNAL_ALLOWED_USERS`includes the sender's number in E.164 format (with`+`prefix) | | "signal-cli not found on PATH" | Install signal-cli and ensure it's in your PATH, or use Docker | | Connection keeps dropping | Check signal-cli logs for errors. Ensure Java 17+ is installed. | | Group messages ignored | Configure`SIGNAL_GROUP_ALLOWED_USERS`with specific group IDs, orto allow all groups. | | Bot responds to no one | Configure`SIGNAL_ALLOWED_USERS`, use DM pairing, or explicitly allow all users through gateway policy if you want broader access. | | Duplicate messages | Ensure only one signal-cli instance is listening on your phone number | --- ## Security :::warning Always configure access controls. The bot has terminal access by default. Without` SIGNAL_ALLOWED_USERS`or DM pairing, the gateway denies all incoming messages as a safety measure. ::: - Phone numbers are redacted in all log output - Use DM pairing or explicit allowlists for safe onboarding of new users - Keep groups disabled unless you specifically need group support, or allowlist only the groups you trust - Signal's end-to-end encryption protects message content in transit - The signal-cli session data in`/.local/share/signal-cli/`contains account credentials — protect it like a password --- ## Environment Variables Reference | Variable | Required | Default | Description | |----------|----------|---------|-------------| |`SIGNAL_HTTP_URL`| Yes | — | signal-cli HTTP endpoint | |`SIGNAL_ACCOUNT`| Yes | — | Bot phone number (E.164) | |`SIGNAL_ALLOWED_USERS`| No | — | Comma-separated phone numbers/UUIDs | |`SIGNAL_GROUP_ALLOWED_USERS`| No | — | Group IDs to monitor, or``for all (omit to disable groups) | |`SIGNAL_ALLOW_ALL_USERS`| No |`false`| Allow any user to interact (skip allowlist) | |`SIGNAL_HOME_CHANNEL| No | — | Default delivery target for cron jobs | ---  # Email # Email Setup Hermes can receive and reply to emails using standard IMAP and SMTP protocols. Send an email to the agent's address and it replies in-thread — no special client or bot API needed. Works with Gmail, Outlook, Yahoo, Fastmail, or any provider that supports IMAP/SMTP. :::info Gateway adapter only: no external dependencies This page covers the Email gateway adapter, which uses Python's built-inimaplib`,` smtplib`, and` email`modules. No additional packages or external services are required for this gateway path. ::: This is separate from the bundled [Himalaya email skill](/docs/user-guide/skills/bundled/email/email-himalaya), which lets the agent manage email through terminal commands and requires the external`himalaya`CLI plus a Himalaya config file. | Use case | What to configure | External dependency | |---|---|---| | Let people email the Hermes agent and receive replies | Email gateway adapter on this page | None beyond an IMAP/SMTP email account | | Let the agent inspect, compose, move, and manage mailbox messages from terminal tools | Himalaya email skill |`himalaya`CLI and`/.config/himalaya/config.toml| --- ## Prerequisites - A dedicated email account for your Hermes agent (don't use your personal email) - IMAP enabled on the email account - An app password if using Gmail or another provider with 2FA ### Gmail Setup 1. Enable 2-Factor Authentication on your Google Account 2. Go to [App Passwords](https://myaccount.google.com/apppasswords) 3. Create a new App Password (select "Mail" or "Other") 4. Copy the 16-character password — you'll use this instead of your regular password ### Outlook / Microsoft 365 1. Go to [Security Settings](https://account.microsoft.com/security) 2. Enable 2FA if not already active 3. Create an App Password under "Additional security options" 4. IMAP host:outlook.office365.com`, SMTP host:` smtp.office365.com### Other Providers Most email providers support IMAP/SMTP. Check your provider's documentation for: - IMAP host and port (usually port 993 with SSL) - SMTP host and port (usually port 587 with STARTTLS) - Whether app passwords are required --- ## Step 1: Configure Hermes The easiest way: ```bash hermes gateway setup ``` Select Email from the platform menu. The wizard prompts for your email address, password, IMAP/SMTP hosts, and allowed senders. ### Manual Configuration Add to/.hermes/.env: ```bash # Required [email protected] EMAIL_PASSWORD=abcd efgh ijkl mnop # App password (not your regular password) EMAIL_IMAP_HOST=imap.gmail.com EMAIL_SMTP_HOST=smtp.gmail.com # Security (recommended) [email protected],[email protected] # Optional EMAIL_IMAP_PORT=993 # Default: 993 (IMAP SSL) EMAIL_SMTP_PORT=587 # Default: 587 (SMTP STARTTLS) EMAIL_POLL_INTERVAL=15 # Seconds between inbox checks (default: 15) [email protected] # Default delivery target for cron jobs ``` --- ## Step 2: Start the Gateway ```bash hermes gateway # Run in foreground hermes gateway install # Install as a user service sudo hermes gateway install --system # Linux only: boot-time system service ``` On startup, the adapter: 1. Tests IMAP and SMTP connections 2. Marks all existing inbox messages as "seen" (only processes new emails) 3. Starts polling for new messages --- ## How It Works ### Receiving Messages The adapter polls the IMAP inbox for UNSEEN messages at a configurable interval (default: 15 seconds). For each new email: - Subject line is included as context (e.g., [Subject: Deploy to production]`) - Reply emails (subject starting with` Re:`) skip the subject prefix — the thread context is already established - Attachments are cached locally: - Images (JPEG, PNG, GIF, WebP) → available to the vision tool - Documents (PDF, ZIP, etc.) → available for file access - HTML-only emails have tags stripped for plain text extraction - Self-messages are filtered out to prevent reply loops - Automated/noreply senders are silently ignored —` noreply@`,` mailer-daemon@`,` bounce@`,` no-reply@`, and emails with` Auto-Submitted`,` Precedence: bulk`, or` List-Unsubscribe`headers ### Sending Replies Replies are sent via SMTP with proper email threading: - In-Reply-To and References headers maintain the thread - Subject line preserved with`Re:`prefix (no double`Re: Re:`) - Message-ID generated with the agent's domain - Responses are sent as plain text (UTF-8) ### File Attachments The agent can send file attachments in replies. Include` MEDIA:/path/to/file`in the response and the file is attached to the outgoing email. ### Skipping Attachments To ignore all incoming attachments (for malware protection or bandwidth savings), add to your`config.yaml: ```yaml platforms: email: skip_attachments: true ``` When enabled, attachment and inline parts are skipped before payload decoding. The email body text is still processed normally. --- ## Access Control Email access follows the same pattern as all other Hermes platforms: 1. EMAIL_ALLOWED_USERS `set → only emails from those addresses are processed 2. No allowlist set → unknown senders get a pairing code 3. `EMAIL_ALLOW_ALL_USERS=true` → any sender is accepted (use with caution) :::warning Always configure` EMAIL_ALLOWED_USERS`. Without it, anyone who knows the agent's email address could send commands. The agent has terminal access by default. ::: --- ## Troubleshooting | Problem | Solution | |---------|----------| | "IMAP connection failed" at startup | Verify` EMAIL_IMAP_HOST`and`EMAIL_IMAP_PORT`. Ensure IMAP is enabled on the account. For Gmail, enable it in Settings → Forwarding and POP/IMAP. | | "SMTP connection failed" at startup | Verify` EMAIL_SMTP_HOST`and`EMAIL_SMTP_PORT`. Check that your password is correct (use App Password for Gmail). | | Messages not received | Check` EMAIL_ALLOWED_USERS`includes the sender's email. Check spam folder — some providers flag automated replies. | | "Authentication failed" | For Gmail, you must use an App Password, not your regular password. Ensure 2FA is enabled first. | | Duplicate replies | Ensure only one gateway instance is running. Check`hermes gateway status`. | | Slow response | The default poll interval is 15 seconds. Reduce with` EMAIL_POLL_INTERVAL=5`for faster response (but more IMAP connections). | | Replies not threading | The adapter uses In-Reply-To headers. Some email clients (especially web-based) may not thread correctly with automated messages. | --- ## Security :::warning Use a dedicated email account. Don't use your personal email — the agent stores the password in`.env`and has full inbox access via IMAP. ::: - Use App Passwords instead of your main password (required for Gmail with 2FA) - Set`EMAIL_ALLOWED_USERS`to restrict who can interact with the agent - The password is stored in`/.hermes/.env `— protect this file (`chmod 600`) - IMAP uses SSL (port 993) and SMTP uses STARTTLS (port 587) by default — connections are encrypted --- ## Environment Variables Reference | Variable | Required | Default | Description | |----------|----------|---------|-------------| |` EMAIL_ADDRESS`| Yes | — | Agent's email address | |`EMAIL_PASSWORD`| Yes | — | Email password or app password | |`EMAIL_IMAP_HOST`| Yes | — | IMAP server host (e.g.,`imap.gmail.com`) | |` EMAIL_SMTP_HOST`| Yes | — | SMTP server host (e.g.,`smtp.gmail.com`) | |` EMAIL_IMAP_PORT`| No |`993`| IMAP server port | |`EMAIL_SMTP_PORT`| No |`587`| SMTP server port | |`EMAIL_POLL_INTERVAL`| No |`15`| Seconds between inbox checks | |`EMAIL_ALLOWED_USERS`| No | — | Comma-separated allowed sender addresses | |`EMAIL_HOME_ADDRESS`| No | — | Default delivery target for cron jobs | |`EMAIL_ALLOW_ALL_USERS`| No |`false| Allow all senders (not recommended) | ---  # SMS (Twilio) # SMS Setup (Twilio) Hermes connects to SMS through the [Twilio](https://www.twilio.com/) API. People text your Twilio phone number and get AI responses back — same conversational experience as Telegram or Discord, but over standard text messages. :::info Shared Credentials The SMS gateway shares credentials with the optional [telephony skill](/reference/skills-catalog). If you've already set up Twilio for voice calls or one-off SMS, the gateway works with the sameTWILIO_ACCOUNT_SID`,` TWILIO_AUTH_TOKEN`, and` TWILIO_PHONE_NUMBER`. ::: --- ## Prerequisites - Twilio account — [Sign up at twilio.com](https://www.twilio.com/try-twilio) (free trial available) - A Twilio phone number with SMS capability - A publicly accessible server — Twilio sends webhooks to your server when SMS arrives - aiohttp —` pip install ‘hermes-agent[sms]’`--- ## Step 1: Get Your Twilio Credentials 1. Go to the [Twilio Console](https://console.twilio.com/) 2. Copy your Account SID and Auth Token from the dashboard 3. Go to Phone Numbers → Manage → Active Numbers — note your phone number in E.164 format (e.g.,`+15551234567) --- ## Step 2: Configure Hermes ### Interactive setup (recommended) ```bash hermes gateway setup ``` Select SMS (Twilio) from the platform list. The wizard will prompt for your credentials. ### Manual setup Add to /.hermes/.env: ```bash TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx TWILIO_AUTH_TOKEN=your_auth_token_here TWILIO_PHONE_NUMBER=+15551234567 # Security: restrict to specific phone numbers (recommended) SMS_ALLOWED_USERS=+15559876543,+15551112222 # Optional: set a home channel for cron job delivery SMS_HOME_CHANNEL=+15559876543 ``` --- ## Step 3: Configure Twilio Webhook Twilio needs to know where to send incoming messages. In the [Twilio Console](https://console.twilio.com/): 1. Go to Phone Numbers → Manage → Active Numbers 2. Click your phone number 3. Under Messaging → A MESSAGE COMES IN, set: - Webhook: https://your-server:8080/webhooks/twilio`- HTTP Method:`POST:::tip Exposing Your Webhook If you're running Hermes locally, use a tunnel to expose the webhook: ```bash # Using cloudflared cloudflared tunnel --url http://localhost:8080 # Using ngrok ngrok http 8080 ``` Set the resulting public URL as your Twilio webhook. ::: SetSMS_WEBHOOK_URLto the same URL you configured in Twilio. This is required for Twilio signature validation — the adapter will refuse to start without it: ```bash # Must match the webhook URL in your Twilio Console SMS_WEBHOOK_URL=https://your-server:8080/webhooks/twilio ``` The webhook port defaults to8080. Override with: ```bash SMS_WEBHOOK_PORT=3000 ``` --- ## Step 4: Start the Gateway ```bash hermes gateway ``` You should see: ``` [sms] Twilio webhook server listening on 127.0.0.1:8080, from: +15554567 ``` If you see Refusing to start: SMS_WEBHOOK_URL is required`, set` SMS_WEBHOOK_URL`to the public URL configured in your Twilio Console (see Step 3). Text your Twilio number — Hermes will respond via SMS. --- ## Environment Variables | Variable | Required | Description | |----------|----------|-------------| |`TWILIO_ACCOUNT_SID`| Yes | Twilio Account SID (starts with`AC`) | |` TWILIO_AUTH_TOKEN`| Yes | Twilio Auth Token (also used for webhook signature validation) | |`TWILIO_PHONE_NUMBER`| Yes | Your Twilio phone number (E.164 format) | |`SMS_WEBHOOK_URL`| Yes | Public URL for Twilio signature validation — must match the webhook URL in your Twilio Console | |`SMS_WEBHOOK_PORT`| No | Webhook listener port (default:`8080`) | |` SMS_WEBHOOK_HOST`| No | Webhook bind address (default:`127.0.0.1`) | |` SMS_INSECURE_NO_SIGNATURE`| No | Set to`true`to disable signature validation (local dev only — not for production) | |`SMS_ALLOWED_USERS`| No | Comma-separated E.164 phone numbers allowed to chat | |`SMS_ALLOW_ALL_USERS`| No | Set to`true`to allow anyone (not recommended) | |`SMS_HOME_CHANNEL`| No | Phone number for cron job / notification delivery | |`SMS_HOME_CHANNEL_NAME`| No | Display name for the home channel (default:`Home) | --- ## SMS-Specific Behavior - Plain text only — Markdown is automatically stripped since SMS renders it as literal characters - 1600 character limit — Longer responses are split across multiple messages at natural boundaries (newlines, then spaces) - Echo prevention — Messages from your own Twilio number are ignored to prevent loops - Phone number redaction — Phone numbers are redacted in logs for privacy --- ## Security ### Webhook signature validation Hermes validates that inbound webhooks genuinely originate from Twilio by verifying the X-Twilio-Signature `header (HMAC-SHA1). This prevents attackers from injecting forged messages. `SMS_WEBHOOK_URLis required. Set it to the public URL configured in your Twilio Console. The adapter will refuse to start without it. For local development without a public URL, you can disable validation: ```bash # Local dev only — NOT for production SMS_INSECURE_NO_SIGNATURE=true ``` ### User allowlists The gateway denies all users by default. Configure an allowlist: ```bash # Recommended: restrict to specific phone numbers SMS_ALLOWED_USERS=+15559876543,+15551112222 # Or allow all (NOT recommended for bots with terminal access) SMS_ALLOW_ALL_USERS=true ``` :::warning SMS has no built-in encryption. Don't use SMS for sensitive operations unless you understand the security implications. For sensitive use cases, prefer Signal or Telegram. ::: --- ## Troubleshooting ### Messages not arriving 1. Check your Twilio webhook URL is correct and publicly accessible 2. VerifyTWILIO_ACCOUNT_SID`and`TWILIO_AUTH_TOKEN`are correct 3. Check the Twilio Console → Monitor → Logs → Messaging for delivery errors 4. Ensure your phone number is in`SMS_ALLOWED_USERS`(or`SMS_ALLOW_ALL_USERS=true`) ### Replies not sending 1. Check` TWILIO_PHONE_NUMBER`is set correctly (E.164 format with`+) 2. Verify your Twilio account has SMS-capable numbers 3. Check Hermes gateway logs for Twilio API errors ### Webhook port conflicts If port 8080 is already in use, change it: ```bash SMS_WEBHOOK_PORT=3001 ``` Update the webhook URL in Twilio Console to match. ---  # Matrix # Matrix Setup Hermes Agent integrates with Matrix, the open, federated messaging protocol. Matrix lets you run your own homeserver or use a public one like matrix.org — either way, you keep control of your communications. The bot connects via the mautrixPython SDK, processes messages through the Hermes Agent pipeline (including tool use, memory, and reasoning), and responds in real time. It supports text, file attachments, images, audio, video, and optional end-to-end encryption (E2EE). Hermes works with any Matrix homeserver — Synapse, Conduit, Dendrite, or matrix.org. Before setup, here's the part most people want to know: how Hermes behaves once it's connected. ## How Hermes Behaves | Context | Behavior | |---------|----------| | DMs | Hermes responds to every message. No@mention`needed. Each DM has its own session. Set`MATRIX_DM_MENTION_THREADS=true`to start a thread when the bot is`@mentioned`in a DM. | | Rooms | By default, Hermes requires an`@mention`to respond. Set`MATRIX_REQUIRE_MENTION=false`or add room IDs to`MATRIX_FREE_RESPONSE_ROOMS`for free-response rooms. Room invites are auto-accepted. | | Threads | Hermes supports Matrix threads (MSC3440). If you reply in a thread, Hermes keeps the thread context isolated from the main room timeline. Threads where the bot has already participated do not require a mention. | | Auto-threading | By default, Hermes auto-creates a thread for each message it responds to in a room. This keeps conversations isolated. Set`MATRIX_AUTO_THREAD=false`to disable. Set`MATRIX_DM_AUTO_THREAD=true`(default false) to also auto-create threads for DM messages — this is distinct from`MATRIX_DM_MENTION_THREADS`, which only starts a thread when the bot is` @mentioned`in a DM. | | Commands | Hermes accepts normal`/commands`when your Matrix client sends them. If your client reserves`/`for local commands, use`!commands`instead; Hermes normalizes known`!command`aliases to`/command. | | Shared rooms with multiple users | By default, Hermes isolates session history per user inside the room. Two people talking in the same room do not share one transcript unless you explicitly disable that. | :::tip The bot automatically joins rooms when invited. Just invite the bot's Matrix user to any room and it will join and start responding. ::: ### Session Model in Matrix By default: - each DM gets its own session - each thread gets its own session namespace - each user in a shared room gets their own session inside that room This is controlled by config.yaml: ```yaml group_sessions_per_user: true ``` Set it to falseonly if you explicitly want one shared conversation for the entire room: ```yaml group_sessions_per_user: false ``` Shared sessions can be useful for a collaborative room, but they also mean: - users share context growth and token costs - one person's long tool-heavy task can bloat everyone else's context - one person's in-flight run can interrupt another person's follow-up in the same room ### Mention and Threading Configuration You can configure mention and auto-threading behavior via environment variables orconfig.yaml: ```yaml matrix: require_mention: true # Require @mention in rooms (default: true) free_response_rooms: # Rooms exempt from mention requirement - "!abc123:matrix.org" auto_thread: true # Auto-create threads for responses (default: true) dm_mention_threads: false # Create thread when @mentioned in DM (default: false) ``` Or via environment variables: ```bash MATRIX_REQUIRE_MENTION=true MATRIX_FREE_RESPONSE_ROOMS=!abc123:matrix.org,!def456:matrix.org MATRIX_AUTO_THREAD=true MATRIX_DM_MENTION_THREADS=false MATRIX_REACTIONS=true # default: true — emoji reactions during processing ``` :::tip Disabling reactions MATRIX_REACTIONS=false`turns off the processing-lifecycle emoji reactions (👀/✅/❌) the bot posts on inbound messages. Useful for rooms where reaction events are noisy or aren't supported by all participating clients. ::: :::note If you are upgrading from a version that did not have`MATRIX_REQUIRE_MENTION`, the bot previously responded to all messages in rooms. To preserve that behavior, set` MATRIX_REQUIRE_MENTION=false. ::: This guide walks you through the full setup process — from creating your bot account to sending your first message. ## Step 1: Create a Bot Account You need a Matrix user account for the bot. There are several ways to do this: ### Option A: Register on Your Homeserver (Recommended) If you run your own homeserver (Synapse, Conduit, Dendrite): 1. Use the admin API or registration tool to create a new user: ```bash # Synapse example register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008 ``` 2. Choose a username like hermes`— the full user ID will be`@hermes:your-server.org`. ### Option B: Use matrix.org or Another Public Homeserver 1. Go to [Element Web](https://app.element.io) and create a new account. 2. Pick a username for your bot (e.g.,` hermes-bot). ### Option C: Use Your Own Account You can also run Hermes as your own user. This means the bot posts as you — useful for personal assistants. ## Step 2: Get an Access Token Hermes needs an access token to authenticate with the homeserver. You have two options: ### Option A: Access Token (Recommended) The most reliable way to get a token: Via Element: 1. Log in to [Element](https://app.element.io) with the bot account. 2. Go to Settings → Help & About. 3. Scroll down and expand Advanced — the access token is displayed there. 4. Copy it immediately. Via the API: ```bash curl -X POST https://your-server/_matrix/client/v3/login \ -H "Content-Type: application/json" \ -d '{ "type": "m.login.password", "user": "@hermes:your-server.org", "password": "your-password" }' ``` The response includes an access_token`field — copy it. :::warning[Keep your access token safe] The access token gives full access to the bot's Matrix account. Never share it publicly or commit it to Git. If compromised, revoke it by logging out all sessions for that user. ::: ### Option B: Password Login Instead of providing an access token, you can give Hermes the bot's user ID and password. Hermes will log in automatically on startup. This is simpler but means the password is stored in your`.envfile. ```bash MATRIX_USER_ID=@hermes:your-server.org MATRIX_PASSWORD=your-password ``` ## Step 3: Find Your Matrix User ID Hermes Agent uses your Matrix User ID to control who can interact with the bot. Matrix User IDs follow the format@username:server`. To find yours: 1. Open [Element](https://app.element.io) (or your preferred Matrix client). 2. Click your avatar → Settings. 3. Your User ID is displayed at the top of the profile (e.g.,` @alice:matrix.org`). :::tip Matrix User IDs always start with` @`and contain a`:`followed by the server name. For example:`@alice:matrix.org`,` @bob:your-server.com. ::: ## Step 4: Configure Hermes Agent ### Option A: Interactive Setup (Recommended) Run the guided setup command: ```bash hermes gateway setup ``` Select Matrix when prompted, then provide your homeserver URL, access token (or user ID + password), and allowed user IDs when asked. ### Option B: Manual Configuration Add the following to your /.hermes/.envfile: Using an access token: ```bash # Required MATRIX_HOMESERVER=https://matrix.example.org MATRIX_ACCESS_TOKEN=* # Optional: user ID (auto-detected from token if omitted) # MATRIX_USER_ID=@hermes:matrix.example.org # Security: restrict who can interact with the bot MATRIX_ALLOWED_USERS=@alice:matrix.example.org # Multiple allowed users (comma-separated) # MATRIX_ALLOWED_USERS=@alice:matrix.example.org,@bob:matrix.example.org ``` Using password login: ```bash # Required MATRIX_HOMESERVER=https://matrix.example.org MATRIX_USER_ID=@hermes:matrix.example.org MATRIX_PASSWORD=* # Security MATRIX_ALLOWED_USERS=@alice:matrix.example.org ``` Optional behavior settings in/.hermes/config.yaml: ```yaml group_sessions_per_user: true ``` - group_sessions_per_user: truekeeps each participant's context isolated inside shared rooms ### Start the Gateway Once configured, start the Matrix gateway: ```bash hermes gateway ``` The bot should connect to your homeserver and start syncing within a few seconds. Send it a message — either a DM or in a room it has joined — to test. :::tip You can runhermes gateway`in the background or as a systemd service for persistent operation. See the deployment docs for details. ::: ## End-to-End Encryption (E2EE) Hermes supports Matrix end-to-end encryption, so you can chat with your bot in encrypted rooms. ### Requirements E2EE requires the`mautrix`library with encryption extras and the`libolmC library: ```bash # Install mautrix with E2EE support pip install 'mautrix[encryption]' # Or install with hermes extras pip install 'hermes-agent[matrix]' ``` You also needlibolminstalled on your system: ```bash # Debian/Ubuntu sudo apt install libolm-dev # macOS brew install libolm # Fedora sudo dnf install libolm-devel ``` ### Enable E2EE Add to your/.hermes/.env: ```bash MATRIX_ENCRYPTION=true ``` When E2EE is enabled, Hermes: - Stores encryption keys in /.hermes/platforms/matrix/store/`(legacy installs:`/.hermes/matrix/store/) - Uploads device keys on first connection - Decrypts incoming messages and encrypts outgoing messages automatically - Auto-joins encrypted rooms when invited ### Cross-Signing Verification (Recommended) If your Matrix account has cross-signing enabled (the default in Element), set the recovery key so the bot can self-sign its device on startup. Without this, other Matrix clients may refuse to share encryption sessions with the bot after a device key rotation. ```bash MATRIX_RECOVERY_KEY=EsT... your recovery key here ``` Where to find it: In Element, go to Settings → Security & Privacy → Encryption → your recovery key (also called the "Security Key"). This is the key you were asked to save when you first set up cross-signing. On each startup, if MATRIX_RECOVERY_KEY`is set, Hermes imports cross-signing keys from the homeserver's secure secret storage and signs the current device. This is idempotent and safe to leave enabled permanently. :::warning[Deleting the crypto store] If you delete`/.hermes/platforms/matrix/store/crypto.db`, the bot loses its encryption identity. Simply restarting with the same device ID will not fully recover — the homeserver still holds one-time keys signed with the old identity key, and peers cannot establish new Olm sessions. Hermes detects this condition on startup and refuses to enable E2EE, logging:` device XXXX has stale one-time keys on the server signed with a previous identity key. Easiest recovery: generate a new access token (which gets a fresh device ID with no stale key history). See the "Upgrading from a previous version with E2EE" section below. This is the most reliable path and avoids touching the homeserver database. Manual recovery** (advanced — keeps the same device ID): 1. Stop Synapse and delete the old device from its database: ```bash sudo systemctl stop matrix-synapse sudo sqlite3 /var/lib/matrix-synapse/homeserver.db " DELETE FROM e2e_device_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server'; DELETE FROM e2e_one_time_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server'; DELETE FROM e2e_fallback_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server'; DELETE FROM devices WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server'; " sudo systemctl start matrix-synapse ``` Or via the Synapse admin API (note the URL-encoded user ID): ```bash curl -X DELETE -H "Authorization: Bearer ADMIN_TOKEN" \ 'https://your-server/_synapse/admin/v2/users/%40hermes%3Ayour-server/devices/DEVICE_ID' ``` Note: deleting a device via the admin API may also invalidate the associated access token. You may need to generate a new token afterward. 2. Delete the local crypto store and restart Hermes: ```bash rm -f ~/.hermes/platforms/matrix/store/crypto.db* # restart hermes ``` Other Matrix clients (Element, matrix-commander) may cache the old device keys. After recovery, type /discardsession`in Element to force a new encryption session with the bot. ::: :::info If`mautrix[encryption]`is not installed or`libolm`is missing, the bot falls back to a plain (unencrypted) client automatically. You'll see a warning in the logs. ::: ## Home Room You can designate a "home room" where the bot sends proactive messages (such as cron job output, reminders, and notifications). There are two ways to set it: ### Using the Slash Command Type`/sethome`in any Matrix room where the bot is present. That room becomes the home room. If your Matrix client intercepts slash commands, type`!sethome`instead. ### Manual Configuration Add this to your`/.hermes/.env: ```bash MATRIX_HOME_ROOM=!abc123def456:matrix.example.org ``` ## Room allowlist (allowed_rooms) Restrict the bot to a fixed set of Matrix rooms. When set, the bot only responds in rooms whose ID appears in the list — messages from any other room are silently ignored, even if the bot is mentioned. DMs (direct chat rooms) are exempt from this filter, so authorized users can always reach the bot one-on-one. ```yaml matrix: allowed_rooms: - "!abc123def456:matrix.example.org" - "!opsroom789:matrix.example.org" ``` Or via env var (comma-separated): ```bash MATRIX_ALLOWED_ROOMS="!abc123def456:matrix.example.org,!opsroom789:matrix.example.org" ``` Behavior: - Empty / unset → no restriction (default). - Non-empty → room ID must be on the list. The check runs before any other gating (mention requirement, sender allowlist, etc.). - Use the room's internal ID (!abc…:server`), not its alias (`#room:server`). You can find a room's internal ID in Element via Room → Settings → Advanced. See also: [admin/user slash command split](../../reference/slash-commands.md#permissions-and-adminuser-split). :::tip To find a Room ID: in Element, go to the room → Settings → Advanced → the Internal room ID is shown there (starts with` !`). ::: ## Commands in Matrix Hermes supports the same gateway commands in Matrix that it supports on other messaging platforms, including` /commands`,` /model`,` /stop`,` /queue`,` /steer`,` /goal`,` /subgoal`,` /background`,` /bg`,` /btw`,` /tasks`, and` /yolo`. Some Matrix clients reserve leading` /`for local client commands and may not send unknown slash commands to the room. In that case, use`!as a Matrix-safe alias: ```text !commands !model !model gpt-5.5 --provider openrouter !queue continue with the next task !stop ``` Hermes only normalizes!command`when the command is known to the gateway, a registered plugin command, or an installed skill command. Ordinary exclamations such as`!important`remain normal chat messages. ## Troubleshooting ### Bot is not responding to messages Cause: The bot hasn't joined the room, or`MATRIX_ALLOWED_USERS`doesn't include your User ID. Fix: Invite the bot to the room — it auto-joins on invite. Verify your User ID is in`MATRIX_ALLOWED_USERS`(use the full`@user:server `format). Restart the gateway. ### Bot joins rooms but silently drops every message (clock skew) Cause: The host's system clock is set ahead of real time. The Matrix adapter applies a 5-second startup-grace filter (`event_ts < startup_ts - 5`) to ignore events replayed from initial sync. When the wall clock is ahead, every incoming event looks "older than startup" and is dropped before reaching the message handler — the bot appears connected but never replies. See [#12614](https://github.com/NousResearch/hermes-agent/issues/12614). Symptom: Gateway log shows` Matrix: dropped N live events as ‘too old’ more than 30s after startup. Fix: Sync the host clock with NTP and restart the bot: ```bash # Debian/Ubuntu sudo timedatectl set-ntp true timedatectl status # confirm "System clock synchronized: yes" # macOS sudo sntp -sS time.apple.com ``` ### "Failed to authenticate" / "whoami failed" on startup Cause: The access token or homeserver URL is incorrect. Fix: Verify MATRIX_HOMESERVER`points to your homeserver (include`https://`, no trailing slash). Check that` MATRIX_ACCESS_TOKENis valid — try it with curl: ```bash curl -H "Authorization: Bearer YOUR_TOKEN" \ https://your-server/_matrix/client/v3/account/whoami ``` If this returns your user info, the token is valid. If it returns an error, generate a new token. ### "mautrix not installed" error Cause: ThemautrixPython package is not installed. Fix: Install it: ```bash pip install 'mautrix[encryption]' ``` Or with Hermes extras: ```bash pip install 'hermes-agent[matrix]' ``` ### Encryption errors / "could not decrypt event" Cause: Missing encryption keys,libolm`not installed, or the bot's device isn't trusted. Fix: 1. Verify`libolm`is installed on your system (see the E2EE section above). 2. Make sure`MATRIX_ENCRYPTION=true`is set in your`.env`. 3. In your Matrix client (Element), go to the bot's profile -> Sessions -> verify/trust the bot's device. 4. If the bot just joined an encrypted room, it can only decrypt messages sent after it joined. Older messages are inaccessible. ### Upgrading from a previous version with E2EE :::tip If you also manually deleted` crypto.db`, see the "Deleting the crypto store" warning in the E2EE section above — there are additional steps to clear stale one-time keys from the homeserver. ::: If you previously used Hermes with` MATRIX_ENCRYPTION=true`and are upgrading to a version that uses the new SQLite-based crypto store, the bot's encryption identity has changed. Your Matrix client (Element) may cache the old device keys and refuse to share encryption sessions with the bot. Symptoms: The bot connects and shows "E2EE enabled" in the logs, but all messages show "could not decrypt event" and the bot never responds. What's happening: The old encryption state (from the previous`matrix-nio`or serialization-based`mautrixbackend) is incompatible with the new SQLite crypto store. The bot creates a fresh encryption identity, but your Matrix client still has the old keys cached and won't share the room's encryption session with a device whose keys changed. This is a Matrix security feature -- clients treat changed identity keys for the same device as suspicious. Fix (one-time migration): 1. Generate a new access token to get a fresh device ID. The simplest way: ```bash curl -X POST https://your-server/_matrix/client/v3/login \ -H "Content-Type: application/json" \ -d '{ "type": "m.login.password", "identifier": {"type": "m.id.user", "user": "@hermes:your-server.org"}, "password": "*", "initial_device_display_name": "Hermes Agent" }' ``` Copy the newaccess_token`and update`MATRIX_ACCESS_TOKEN`in`/.hermes/.env. 2. Delete old encryption state**: ```bash rm -f ~/.hermes/platforms/matrix/store/crypto.db rm -f ~/.hermes/platforms/matrix/store/crypto_store.* ``` 3. Set your recovery key (if you use cross-signing — most Element users do). Add to /.hermes/.env: ```bash MATRIX_RECOVERY_KEY=EsT... your recovery key here ``` This lets the bot self-sign with cross-signing keys on startup, so Element trusts the new device immediately. Without this, Element may see the new device as unverified and refuse to share encryption sessions. Find your recovery key in Element under Settings → Security & Privacy → Encryption. 4. Force your Matrix client to rotate the encryption session. In Element, open the DM room with the bot and type /discardsession. This forces Element to create a new encryption session and share it with the bot's new device. 5. Restart the gateway: ```bash hermes gateway run ``` If MATRIX_RECOVERY_KEY`is set, you should see`Matrix: cross-signing verified via recovery keyin the logs. 6. Send a new message. The bot should decrypt and respond normally. :::note After migration, messages sent before the upgrade cannot be decrypted -- the old encryption keys are gone. This only affects the transition; new messages work normally. ::: :::tip New installations are not affected. This migration is only needed if you had a working E2EE setup with a previous version of Hermes and are upgrading. Why a new access token? Each Matrix access token is bound to a specific device ID. Reusing the same device ID with new encryption keys causes other Matrix clients to distrust the device (they see changed identity keys as a potential security breach). A new access token gets a new device ID with no stale key history, so other clients trust it immediately. ::: ## Proxy Mode (E2EE on macOS) Matrix E2EE requireslibolm`, which doesn't compile on macOS ARM64 (Apple Silicon). The` hermes-agent[matrix]extra is gated to Linux only. If you're on macOS, proxy mode lets you run E2EE in a Docker container on a Linux VM while the actual agent runs natively on macOS with full access to your local files, memory, and skills. ### How It Works ``` macOS (Host): └─ hermes gateway ├─ api_server adapter ← listens on 0.0.0.0:8642 ├─ AIAgent ← single source of truth ├─ Sessions, memory, skills └─ Local file access (Obsidian, projects, etc.) Linux VM (Docker): └─ hermes gateway (proxy mode) ├─ Matrix adapter ← E2EE decryption/encryption └─ HTTP forward → macOS:8642/v1/chat/completions (no LLM API keys, no agent, no inference) ``` The Docker container only handles Matrix protocol + E2EE. When a message arrives, it decrypts it and forwards the text to the host via a standard HTTP request. The host runs the agent, calls tools, generates a response, and streams it back. The container encrypts and sends the response to Matrix. All sessions are unified — CLI, Matrix, Telegram, and any other platform share the same memory and conversation history. ### Step 1: Configure the Host (macOS) Enable the API server so the host accepts incoming requests from the Docker container. Add to/.hermes/.env: ```bash API_SERVER_ENABLED=true API_SERVER_KEY=your-secret-key-here API_SERVER_HOST=0.0.0.0 ``` - API_SERVER_HOST=0.0.0.0`binds to all interfaces so the Docker container can reach it. -`API_SERVER_KEY`is required for non-loopback binding. Pick a strong random string. - The API server runs on port 8642 by default (change with`API_SERVER_PORT if needed). Start the gateway: ```bash hermes gateway ``` You should see the API server start alongside any other platforms you have configured. Verify it's reachable from the VM: ```bash # From the Linux VM curl http://<mac-ip>:8642/health ``` ### Step 2: Configure the Docker Container (Linux VM) The container needs Matrix credentials and the proxy URL. It does NOT need LLM API keys. docker-compose.yml: ```yaml services: hermes-matrix: build: . environment: # Matrix credentials MATRIX_HOMESERVER: "https://matrix.example.org" MATRIX_ACCESS_TOKEN: "syt_..." MATRIX_ALLOWED_USERS: "@you:matrix.example.org" MATRIX_ENCRYPTION: "true" MATRIX_DEVICE_ID: "HERMES_BOT" # Proxy mode — forward to host agent GATEWAY_PROXY_URL: "http://192.168.1.100:8642" GATEWAY_PROXY_KEY: "your-secret-key-here" volumes: - ./matrix-store:/root/.hermes/platforms/matrix/store ``` Dockerfile: ```dockerfile FROM python:3.11-slim RUN apt-get update && apt-get install -y libolm-dev && rm -rf /var/lib/apt/lists/* RUN pip install 'hermes-agent[matrix]' CMD ["hermes", "gateway"] ``` That's the entire container. No API keys for OpenRouter, Anthropic, or any inference provider. ### Step 3: Start Both 1. Start the host gateway first: ```bash hermes gateway ``` 2. Start the Docker container: ```bash docker compose up -d ``` 3. Send a message in an encrypted Matrix room. The container decrypts it, forwards it to the host, and streams the response back. ### Configuration Reference Proxy mode is configured on the container side (the thin gateway): | Setting | Description | |---------|-------------| | GATEWAY_PROXY_URL`| URL of the remote Hermes API server (e.g.,`http://192.168.1.100:8642`) | |` GATEWAY_PROXY_KEY`| Bearer token for authentication (must match`API_SERVER_KEY`on the host) | |`gateway.proxy_url`| Same as`GATEWAY_PROXY_URL`but in`config.yaml`| The host side needs: | Setting | Description | |---------|-------------| |`API_SERVER_ENABLED`| Set to`true`| |`API_SERVER_KEY`| Bearer token (shared with the container) | |`API_SERVER_HOST`| Set to`0.0.0.0`for network access | |`API_SERVER_PORT`| Port number (default:`8642`) | ### Works for Any Platform Proxy mode is not limited to Matrix. Any platform adapter can use it — set` GATEWAY_PROXY_URL`on any gateway instance and it will forward to the remote agent instead of running one locally. This is useful for any deployment where the platform adapter needs to run in a different environment from the agent (network isolation, E2EE requirements, resource constraints). :::tip Session continuity is maintained via the`X-Hermes-Session-Idheader. The host's API server tracks sessions by this ID, so conversations persist across messages just like they would with a local agent. ::: :::note Limitations (v1): Tool progress messages from the remote agent are not relayed back — the user sees the streamed final response only, not individual tool calls. Dangerous command approval prompts are handled on the host side, not relayed to the Matrix user. These can be addressed in future updates. ::: ### Sync issues / bot falls behind Cause: Long-running tool executions can delay the sync loop, or the homeserver is slow. Fix: The sync loop automatically retries every 5 seconds on error. Check the Hermes logs for sync-related warnings. If the bot consistently falls behind, ensure your homeserver has adequate resources. ### Bot is offline Cause: The Hermes gateway isn't running, or it failed to connect. Fix: Check thathermes gateway`is running. Look at the terminal output for error messages. Common issues: wrong homeserver URL, expired access token, homeserver unreachable. ### "User not allowed" / Bot ignores you Cause: Your User ID isn't in`MATRIX_ALLOWED_USERS`. Fix: Add your User ID to` MATRIX_ALLOWED_USERS`in`/.hermes/.env`and restart the gateway. Use the full`@user:server`format. ## Security :::warning Always set`MATRIX_ALLOWED_USERSto restrict who can interact with the bot. Without it, the gateway denies all users by default as a safety measure. Only add User IDs of people you trust — authorized users have full access to the agent's capabilities, including tool use and system access. ::: For more information on securing your Hermes Agent deployment, see the [Security Guide](../security.md). ## Notes - Any homeserver: Works with Synapse, Conduit, Dendrite, matrix.org, or any spec-compliant Matrix homeserver. No specific homeserver software required. - Federation: If you're on a federated homeserver, the bot can communicate with users from other servers — just add their full@user:server`IDs to`MATRIX_ALLOWED_USERS`. - Auto-join: The bot automatically accepts room invites and joins. It starts responding immediately after joining. - Media support: Hermes can send and receive images, audio, video, and file attachments. Media is uploaded to your homeserver using the Matrix content repository API. - Native voice messages (MSC3245): The Matrix adapter automatically tags outgoing voice messages with the` org.matrix.msc3245.voiceflag. This means TTS responses and voice audio are rendered as native voice bubbles in Element and other clients that support MSC3245, rather than as generic audio file attachments. Incoming voice messages with the MSC3245 flag are also correctly identified and routed to speech-to-text transcription. No configuration is needed — this works automatically. ---  # Mattermost # Mattermost Setup Hermes Agent integrates with Mattermost as a bot, letting you chat with your AI assistant through direct messages or team channels. Mattermost is a self-hosted, open-source Slack alternative — you run it on your own infrastructure, keeping full control of your data. The bot connects via Mattermost's REST API (v4) and WebSocket for real-time events, processes messages through the Hermes Agent pipeline (including tool use, memory, and reasoning), and responds in real time. It supports text, file attachments, images, and slash commands. No external Mattermost library is required — the adapter usesaiohttp`, which is already a Hermes dependency. Before setup, here's the part most people want to know: how Hermes behaves once it's in your Mattermost instance. ## How Hermes Behaves | Context | Behavior | |---------|----------| | DMs | Hermes responds to every message. No` @mention`needed. Each DM has its own session. | | Public/private channels | Hermes responds when you`@mention`it. Without a mention, Hermes ignores the message. | | Threads | If`MATTERMOST_REPLY_MODE=thread`, Hermes replies in a thread under your message. Thread context stays isolated from the parent channel. | | Shared channels with multiple users | By default, Hermes isolates session history per user inside the channel. Two people talking in the same channel do not share one transcript unless you explicitly disable that. | :::tip If you want Hermes to reply as threaded conversations (nested under your original message), set` MATTERMOST_REPLY_MODE=thread`. The default is` off`, which sends flat messages in the channel. ::: ### Session Model in Mattermost By default: - each DM gets its own session - each thread gets its own session namespace - each user in a shared channel gets their own session inside that channel This is controlled by` config.yaml: ```yaml group_sessions_per_user: true ``` Set it to falseonly if you explicitly want one shared conversation for the entire channel: ```yaml group_sessions_per_user: false ``` Shared sessions can be useful for a collaborative channel, but they also mean: - users share context growth and token costs - one person's long tool-heavy task can bloat everyone else's context - one person's in-flight run can interrupt another person's follow-up in the same channel This guide walks you through the full setup process — from creating your bot on Mattermost to sending your first message. ## Step 1: Enable Bot Accounts Bot accounts must be enabled on your Mattermost server before you can create one. 1. Log in to Mattermost as a System Admin. 2. Go to System Console → Integrations → Bot Accounts. 3. Set Enable Bot Account Creation to true. 4. Click Save. :::info If you don't have System Admin access, ask your Mattermost administrator to enable bot accounts and create one for you. ::: ## Step 2: Create a Bot Account 1. In Mattermost, click the ☰ menu (top-left) → Integrations → Bot Accounts. 2. Click Add Bot Account. 3. Fill in the details: - Username: e.g.,hermes`- Display Name: e.g.,`Hermes Agent`- Description: optional - Role:`Memberis sufficient 4. Click Create Bot Account. 5. Mattermost will display the bot token. Copy it immediately. :::warning[Token shown only once] The bot token is only displayed once when you create the bot account. If you lose it, you'll need to regenerate it from the bot account settings. Never share your token publicly or commit it to Git — anyone with this token has full control of the bot. ::: Store the token somewhere safe (a password manager, for example). You'll need it in Step 5. :::tip You can also use a personal access token instead of a bot account. Go to Profile → Security → Personal Access Tokens → Create Token. This is useful if you want Hermes to post as your own user rather than a separate bot user. ::: ## Step 3: Add the Bot to Channels The bot needs to be a member of any channel where you want it to respond: 1. Open the channel where you want the bot. 2. Click the channel name → Add Members. 3. Search for your bot username (e.g.,hermes`) and add it. For DMs, simply open a direct message with the bot — it will be able to respond immediately. ## Step 4: Find Your Mattermost User ID Hermes Agent uses your Mattermost User ID to control who can interact with the bot. To find it: 1. Click your avatar (top-left corner) → Profile. 2. Your User ID is displayed in the profile dialog — click it to copy. Your User ID is a 26-character alphanumeric string like` 3uo8dkh1p7g1mfk49ear5fzs5c`. :::warning Your User ID is not your username. The username is what appears after` @`(e.g.,`@alice). The User ID is a long alphanumeric identifier that Mattermost uses internally. ::: Alternative: You can also get your User ID via the API: ```bash curl -H "Authorization: Bearer YOUR_TOKEN" \ https://your-mattermost-server/api/v4/users/me | jq .id ``` :::tip To get a Channel ID: click the channel name → View Info. The Channel ID is shown in the info panel. You'll need this if you want to set a home channel manually. ::: ## Step 5: Configure Hermes Agent ### Option A: Interactive Setup (Recommended) Run the guided setup command: ```bash hermes gateway setup ``` Select Mattermost when prompted, then paste your server URL, bot token, and user ID when asked. ### Option B: Manual Configuration Add the following to your /.hermes/.envfile: ```bash # Required MATTERMOST_URL=https://mm.example.com MATTERMOST_TOKEN=* MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c # Multiple allowed users (comma-separated) # MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c,8fk2jd9s0a7bncm1xqw4tp6r3e # Optional: reply mode (thread or off, default: off) # MATTERMOST_REPLY_MODE=thread # Optional: respond without @mention (default: true = require mention) # MATTERMOST_REQUIRE_MENTION=false # Optional: channels where bot responds without @mention (comma-separated channel IDs) # MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2 ``` Optional behavior settings in/.hermes/config.yaml: ```yaml group_sessions_per_user: true ``` - group_sessions_per_user: truekeeps each participant's context isolated inside shared channels and threads ### Start the Gateway Once configured, start the Mattermost gateway: ```bash hermes gateway ``` The bot should connect to your Mattermost server within a few seconds. Send it a message — either a DM or in a channel where it's been added — to test. :::tip You can runhermes gateway`in the background or as a systemd service for persistent operation. See the deployment docs for details. ::: ## Home Channel You can designate a "home channel" where the bot sends proactive messages (such as cron job output, reminders, and notifications). There are two ways to set it: ### Using the Slash Command Type`/sethome`in any Mattermost channel where the bot is present. That channel becomes the home channel. ### Manual Configuration Add this to your`/.hermes/.env: ```bash MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mn ``` Replace the ID with the actual channel ID (click the channel name → View Info → copy the ID). ## Reply Mode The MATTERMOST_REPLY_MODE`setting controls how Hermes posts responses: | Mode | Behavior | |------|----------| |`off`(default) | Hermes posts flat messages in the channel, like a normal user. | |`thread`| Hermes replies in a thread under your original message. Keeps channels clean when there's lots of back-and-forth. | Set it in your`/.hermes/.env: ```bash MATTERMOST_REPLY_MODE=thread ``` ## Mention Behavior By default, the bot only responds in channels when @mentioned`. You can change this: | Variable | Default | Description | |----------|---------|-------------| |` MATTERMOST_REQUIRE_MENTION`|`true`| Set to`false`to respond to all messages in channels (DMs always work). | |`MATTERMOST_FREE_RESPONSE_CHANNELS`| _(none)_ | Comma-separated channel IDs where the bot responds without`@mention`, even when require_mention is true. | To find a channel ID in Mattermost: open the channel, click the channel name header, and look for the ID in the URL or channel details. When the bot is` @mentioned`, the mention is automatically stripped from the message before processing. ## Channel allowlist (`allowed_channels`) Restrict the bot to a fixed set of Mattermost channels. When set, the bot only responds in channels whose ID appears in the list — messages from any other channel are silently ignored, even if the bot is` @mentioned. DMs are exempt from this filter, so authorized users can always reach the bot in a direct message. ```yaml mattermost: allowed_channels: - "abc123def456ghi789jkl012mno" # #ops - "xyz987uvw654rst321opq098nml" # #incident-response ``` Or via env var (comma-separated): ```bash MATTERMOST_ALLOWED_CHANNELS="abc123def456ghi789jkl012mno,xyz987uvw654rst321opq098nml" ``` Behavior: - Empty / unset → no restriction (fully backward compatible). - Non-empty → channel ID must be on the list, or the message is dropped before any other gating (mention requirement, MATTERMOST_FREE_RESPONSE_CHANNELS`, etc.) runs. - Find a channel ID via the Mattermost UI → channel header → "View Info", or read it from the channel URL. See also: [admin/user slash command split](../../reference/slash-commands.md#permissions-and-adminuser-split). ## Troubleshooting ### Bot is not responding to messages Cause: The bot is not a member of the channel, or` MATTERMOST_ALLOWED_USERS`doesn't include your User ID. Fix: Add the bot to the channel (channel name → Add Members → search for the bot). Verify your User ID is in`MATTERMOST_ALLOWED_USERS`. Restart the gateway. ### 403 Forbidden errors Cause: The bot token is invalid, or the bot doesn't have permission to post in the channel. Fix: Check that` MATTERMOST_TOKEN`in your`.envfile is correct. Make sure the bot account hasn't been deactivated. Verify the bot has been added to the channel. If using a personal access token, ensure your account has the required permissions. ### WebSocket disconnects / reconnection loops Cause: Network instability, Mattermost server restarts, or firewall/proxy issues with WebSocket connections. Fix: The adapter automatically reconnects with exponential backoff (2s → 60s). Check your server's WebSocket configuration — reverse proxies (nginx, Apache) need WebSocket upgrade headers configured. Verify no firewall is blocking WebSocket connections on your Mattermost server. For nginx, ensure your config includes: ```nginx location /api/v4/websocket { proxy_pass http://mattermost-backend; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 600s; } ``` ### "Failed to authenticate" on startup Cause: The token or server URL is incorrect. Fix: VerifyMATTERMOST_URL`points to your Mattermost server (include`https://`, no trailing slash). Check that` MATTERMOST_TOKENis valid — try it with curl: ```bash curl -H "Authorization: Bearer YOUR_TOKEN" \ https://your-server/api/v4/users/me ``` If this returns your bot's user info, the token is valid. If it returns an error, regenerate the token. ### Bot is offline Cause: The Hermes gateway isn't running, or it failed to connect. Fix: Check thathermes gateway`is running. Look at the terminal output for error messages. Common issues: wrong URL, expired token, Mattermost server unreachable. ### "User not allowed" / Bot ignores you Cause: Your User ID isn't in`MATTERMOST_ALLOWED_USERS`. Fix: Add your User ID to` MATTERMOST_ALLOWED_USERS`in`/.hermes/.env`and restart the gateway. Remember: the User ID is a 26-character alphanumeric string, not your`@username. ## Per-Channel Prompts Assign ephemeral system prompts to specific Mattermost channels. The prompt is injected at runtime on every turn — never persisted to transcript history — so changes take effect immediately. ```yaml mattermost: channel_prompts: "channel_id_abc123": | You are a research assistant. Focus on academic sources, citations, and concise synthesis. "channel_id_def456": | Code review mode. Be precise about edge cases and performance implications. ``` Keys are Mattermost channel IDs (find them in the channel URL or via the API). All messages in the matching channel get the prompt injected as an ephemeral system instruction. ## Security :::warning Always set MATTERMOST_ALLOWED_USERSto restrict who can interact with the bot. Without it, the gateway denies all users by default as a safety measure. Only add User IDs of people you trust — authorized users have full access to the agent's capabilities, including tool use and system access. ::: For more information on securing your Hermes Agent deployment, see the [Security Guide](../security.md). ## Notes - Self-hosted friendly: Works with any self-hosted Mattermost instance. No Mattermost Cloud account or subscription required. - No extra dependencies: The adapter usesaiohttpfor HTTP and WebSocket, which is already included with Hermes Agent. - Team Edition compatible: Works with both Mattermost Team Edition (free) and Enterprise Edition. ---  # user-guide/messaging/homeassistant # Home Assistant Integration Hermes Agent integrates with [Home Assistant](https://www.home-assistant.io/) in two ways: 1. Gateway platform — subscribes to real-time state changes via WebSocket and responds to events 2. Smart home tools — four LLM-callable tools for querying and controlling devices via the REST API ## Setup ### 1. Create a Long-Lived Access Token 1. Open your Home Assistant instance 2. Go to your Profile (click your name in the sidebar) 3. Scroll to Long-Lived Access Tokens 4. Click Create Token, give it a name like "Hermes Agent" 5. Copy the token ### 2. Configure Environment Variables ```bash # Add to ~/.hermes/.env # Required: your Long-Lived Access Token HASS_TOKEN=your-long-lived-access-token # Optional: HA URL (default: http://homeassistant.local:8123) HASS_URL=http://192.168.1.100:8123 ``` :::info Thehomeassistant`toolset is automatically enabled when`HASS_TOKENis set. Both the gateway platform and the device control tools activate from this single token. ::: ### 3. Start the Gateway ```bash hermes gateway ``` Home Assistant will appear as a connected platform alongside any other messaging platforms (Telegram, Discord, etc.). ## Available Tools Hermes Agent registers four tools for smart home control: ###ha_list_entities`List Home Assistant entities, optionally filtered by domain or area. Parameters:** -`domain`(optional) — Filter by entity domain:`light`,` switch`,` climate`,` sensor`,` binary_sensor`,` cover`,` fan`,` media_player`, etc. -` area`(optional) — Filter by area/room name (matches against friendly names):`living room`,` kitchen`,` bedroom, etc. Example: ``` List all lights in the living room ``` Returns entity IDs, states, and friendly names. ### ha_get_state`Get detailed state of a single entity, including all attributes (brightness, color, temperature setpoint, sensor readings, etc.). Parameters: -`entity_id`(required) — The entity to query, e.g.,`light.living_room`,` climate.thermostat`,` sensor.temperatureExample: ``` What's the current state of climate.thermostat? ``` Returns: state, all attributes, last changed/updated timestamps. ###ha_list_services`List available services (actions) for device control. Shows what actions can be performed on each device type and what parameters they accept. Parameters: -`domain`(optional) — Filter by domain, e.g.,`light`,` climate`,` switchExample: ``` What services are available for climate devices? ``` ###ha_call_service`Call a Home Assistant service to control a device. Parameters: -`domain`(required) — Service domain:`light`,` switch`,` climate`,` cover`,` media_player`,` fan`,` scene`,` script`-`service`(required) — Service name:`turn_on`,` turn_off`,` toggle`,` set_temperature`,` set_hvac_mode`,` open_cover`,` close_cover`,` set_volume_level`-`entity_id`(optional) — Target entity, e.g.,`light.living_room`-`data(optional) — Additional parameters as a JSON object Examples: ``` Turn on the living room lights → ha_call_service(domain="light", service="turn_on", entity_id="light.living_room") ``` ``` Set the thermostat to 22 degrees in heat mode → ha_call_service(domain="climate", service="set_temperature", entity_id="climate.thermostat", data={"temperature": 22, "hvac_mode": "heat"}) ``` ``` Set living room lights to blue at 50% brightness → ha_call_service(domain="light", service="turn_on", entity_id="light.living_room", data={"brightness": 128, "color_name": "blue"}) ``` ## Gateway Platform: Real-Time Events The Home Assistant gateway adapter connects via WebSocket and subscribes tostate_changed`events. When a device state changes and matches your filters, it's forwarded to the agent as a message. ### Event Filtering :::warning Required Configuration By default, no events are forwarded. You must configure at least one of`watch_domains`,` watch_entities`, or` watch_all`to receive events. Without filters, a warning is logged at startup and all state changes are silently dropped. ::: Configure which events the agent sees in`/.hermes/config.yaml`under the Home Assistant platform's`extrasection: ```yaml platforms: homeassistant: enabled: true extra: watch_domains: - climate - binary_sensor - alarm_control_panel - light watch_entities: - sensor.front_door_battery ignore_entities: - sensor.uptime - sensor.cpu_usage - sensor.memory_usage cooldown_seconds: 30 ``` | Setting | Default | Description | |---------|---------|-------------| |watch_domains`| (none) | Only watch these entity domains (e.g.,`climate`,` light`,` binary_sensor`) | |` watch_entities`| (none) | Only watch these specific entity IDs | |`watch_all`|`false`| Set to`true`to receive all state changes (not recommended for most setups) | |`ignore_entities`| (none) | Always ignore these entities (applied before domain/entity filters) | |`cooldown_seconds`|`30`| Minimum seconds between events for the same entity | :::tip Start with a focused set of domains —`climate`,` binary_sensor`, and` alarm_control_panel`cover the most useful automations. Add more as needed. Use`ignore_entities`to suppress noisy sensors like CPU temperature or uptime counters. ::: ### Event Formatting State changes are formatted as human-readable messages based on domain: | Domain | Format | |--------|--------| |`climate`| "HVAC mode changed from 'off' to 'heat' (current: 21, target: 23)" | |`sensor`| "changed from 21°C to 22°C" | |`binary_sensor`| "triggered" / "cleared" | |`light`,` switch`,` fan`| "turned on" / "turned off" | |`alarm_control_panel`| "alarm state changed from 'armed_away' to 'triggered'" | | (other) | "changed from 'old' to 'new'" | ### Agent Responses Outbound messages from the agent are delivered as Home Assistant persistent notifications (via`persistent_notification.create`). These appear in the HA notification panel with the title "Hermes Agent". ### Connection Management - WebSocket with 30-second heartbeat for real-time events - Automatic reconnection with backoff: 5s → 10s → 30s → 60s - REST API for outbound notifications (separate session to avoid WebSocket conflicts) - Authorization — HA events are always authorized (no user allowlist needed, since the` HASS_TOKEN`authenticates the connection) ## Security The Home Assistant tools enforce security restrictions: :::warning Blocked Domains The following service domains are blocked to prevent arbitrary code execution on the HA host: -`shell_command`— arbitrary shell commands -`command_line`— sensors/switches that execute commands -`python_script`— scripted Python execution -`pyscript`— broader scripting integration -`hassio`— addon control, host shutdown/reboot -`rest_command`— HTTP requests from HA server (SSRF vector) Attempting to call services in these domains returns an error. ::: Entity IDs are validated against the pattern`^[a-z_][a-z0-9_].[a-z0-9_]+0.10/month credit, no markup on provider rates). You can append routing suffixes to model names: `:fastest` (default), `:cheapest`, or `:provider_name` to force a specific backend. The base URL can be overridden with `HF_BASE_URL`. ### Google Gemini via OAuth (`google-gemini-cli`) The `google-gemini-cli` provider uses Google’s Cloud Code Assist backend — the same API that Google’s own `gemini-cli` tool uses. This supports both the free tier (generous daily quota for personal accounts) and paid tiers (Standard/Enterprise via a GCP project). Quick start: `bash hermes model # → pick "Google Gemini (OAuth)" # → see policy warning, confirm # → browser opens to accounts.google.com, sign in # → done — Hermes auto-provisions your free tier on first request` Hermes ships Google’s public `gemini-cli` desktop OAuth client by default — the same credentials Google includes in their open-source `gemini-cli`. Desktop OAuth clients are not confidential (PKCE provides the security). You do not need to install `gemini-cli` or register your own GCP OAuth client. How auth works: - PKCE Authorization Code flow against `accounts.google.com` - Browser callback at `http://127.0.0.1:8085/oauth2callback` (with ephemeral-port fallback if busy) - Tokens stored at `~/.hermes/auth/google_oauth.json` (chmod 0600, atomic write, cross-process `fcntl` lock) - Automatic refresh 60 s before expiry - Headless environments (SSH, `HERMES_HEADLESS=1`) → paste-mode fallback - Inflight refresh deduplication — two concurrent requests won’t double-refresh - `invalid_grant` (revoked refresh) → credential file wiped, user prompted to re-login How inference works: - Traffic goes to `https://cloudcode-pa.googleapis.com/v1internal:generateContent` (or `:streamGenerateContent?alt=sse` for streaming), NOT the paid `v1beta/openai` endpoint - Request body wrapped `{project, model, user_prompt_id, request}` - OpenAI-shaped `messages[]`, `tools[]`, `tool_choice` are translated to Gemini’s native `contents[]`, `tools[].functionDeclarations`, `toolConfig` shape - Responses translated back to OpenAI shape so the rest of Hermes works unchanged Tiers & project IDs: | Your situation | What to do | |—|—| | Personal Google account, want free tier | Nothing — sign in, start chatting | | Workspace / Standard / Enterprise account | Set `HERMES_GEMINI_PROJECT_ID` or `GOOGLE_CLOUD_PROJECT` to your GCP project ID | | VPC-SC-protected org | Hermes detects `SECURITY_POLICY_VIOLATED` and forces `standard-tier` automatically | Free tier auto-provisions a Google-managed project on first use. No GCP setup required. Quota monitoring: `/gquota` Shows remaining Code Assist quota per model with progress bars: `Gemini Code Assist quota (project: 123-abc) gemini-2.5-pro ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░ 85% gemini-2.5-flash [input] ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░ 92%` :::warning Policy risk Google considers using the Gemini CLI OAuth client with third-party software a policy violation. Some users have reported account restrictions. For the lowest-risk experience, use your own API key via the `gemini` provider instead. Hermes shows an upfront warning and requires explicit confirmation before OAuth begins. ::: Custom OAuth client (optional): If you’d rather register your own Google OAuth client — e.g., to keep quota and consent scoped to your own GCP project — set: `bash HERMES_GEMINI_CLIENT_ID=your-client.apps.googleusercontent.com HERMES_GEMINI_CLIENT_SECRET=... # optional for Desktop clients` Register a Desktop app OAuth client at console.cloud.google.com/apis/credentials with the Generative Language API enabled. ## Custom & Self-Hosted LLM Providers Hermes Agent works with any OpenAI-compatible API endpoint. If a server implements `/v1/chat/completions`, you can point Hermes at it. This means you can use local models, GPU inference servers, multi-provider routers, or any third-party API. ### General Setup Three ways to configure a custom endpoint: Interactive setup (recommended): `bash hermes model # Select "Custom endpoint (self-hosted / VLLM / etc.)" # Enter: API base URL, API key, Model name` Manual config (`config.yaml`): `yaml # In ~/.hermes/config.yaml model: default: your-model-name provider: custom base_url: http://localhost:8000/v1 api_key: your-key-or-leave-empty-for-local` :::warning Legacy env vars `LLM_MODEL` in `.env` is removed — `config.yaml` is the single source of truth for model and endpoint configuration. `OPENAI_BASE_URL` is still honored, but only for the `openai-api` provider (it overrides the OpenAI endpoint for direct API-key access). For other providers and custom endpoints, use `hermes model` or set `model.base_url` in `config.yaml` directly. If you have stale entries in your `.env`, they are automatically cleared on the next `hermes setup` or config migration. ::: Both approaches persist to `config.yaml`, which is the source of truth for model, provider, and base URL. ### Switching Models with `/model` :::warning hermes model vs /model `hermes model` (run from your terminal, outside any chat session) is the full provider setup wizard. Use it to add new providers, run OAuth flows, enter API keys, and configure custom endpoints. `/model` (typed inside an active Hermes chat session) can only switch between providers and models you’ve already set up. It cannot add new providers, run OAuth, or prompt for API keys. If you’ve only configured one provider (e.g. OpenRouter), `/model` will only show models for that provider. To add a new provider: Exit your session (`Ctrl+C` or `/quit`), run `hermes model`, set up the new provider, then start a new session. ::: Once you have at least one custom endpoint configured, you can switch models mid-session: `/model custom:qwen-2.5 # Switch to a model on your custom endpoint /model custom # Auto-detect the model from the endpoint /model openrouter:claude-sonnet-4 # Switch back to a cloud provider` If you have named custom providers configured (see below), use the triple syntax: `/model custom:local:qwen-2.5 # Use the "local" custom provider with model qwen-2.5 /model custom:work:llama3 # Use the "work" custom provider with llama3` When switching providers, Hermes persists the base URL and provider to config so the change survives restarts. When switching away from a custom endpoint to a built-in provider, the stale base URL is automatically cleared. :::tip `/model custom` (bare, no model name) queries your endpoint’s `/models` API and auto-selects the model if exactly one is loaded. Useful for local servers running a single model. ::: Everything below follows this same pattern — just change the URL, key, and model name. — ### Ollama — Local Models, Zero Config Ollama runs open-weight models locally with one command. Best for: quick local experimentation, privacy-sensitive work, offline use. Supports tool calling via the OpenAI-compatible API. `bash # Install and run a model ollama pull qwen2.5-coder:32b ollama serve # Starts on port 11434` Then configure Hermes: `bash hermes model # Select "Custom endpoint (self-hosted / VLLM / etc.)" # Enter URL: http://localhost:11434/v1 # Skip API key (Ollama doesn't need one) # Enter model name (e.g. qwen2.5-coder:32b)` Or configure `config.yaml` directly: `yaml model: default: qwen2.5-coder:32b provider: custom base_url: http://localhost:11434/v1 context_length: 64000 # See warning below` :::caution Ollama defaults to very low context lengths Ollama does not use your model’s full context window by default. Depending on your VRAM, the default is: | Available VRAM | Default context | |––––––––|––––––––| | Less than 24 GB | 4,096 tokens | | 24–48 GB | 32,768 tokens | | 48+ GB | 256,000 tokens | Hermes Agent requires at least 64,000 tokens of context for agent use with tools. Smaller windows are rejected at startup because the system prompt, tool schemas, and working conversation state need enough room for reliable multi-step workflows. How to increase it (pick one): `bash # Option 1: Set server-wide via environment variable (recommended) OLLAMA_CONTEXT_LENGTH=64000 ollama serve # Option 2: For systemd-managed Ollama sudo systemctl edit ollama.service # Add: Environment="OLLAMA_CONTEXT_LENGTH=64000" # Then: sudo systemctl daemon-reload && sudo systemctl restart ollama # Option 3: Bake it into a custom model (persistent per-model) echo -e "FROM qwen2.5-coder:32b\nPARAMETER num_ctx 64000" > Modelfile ollama create qwen2.5-coder-64k -f Modelfile` You cannot set context length through the OpenAI-compatible API (`/v1/chat/completions`). It must be configured server-side or via a Modelfile. This is the #1 source of confusion when integrating Ollama with tools like Hermes. ::: Verify your context is set correctly: `bash ollama ps # Look at the CONTEXT column — it should show your configured value` :::tip List available models with `ollama list`. Pull any model from the Ollama library with `ollama pull <model>`. Ollama handles GPU offloading automatically — no configuration needed for most setups. ::: — ### vLLM — High-Performance GPU Inference vLLM is the standard for production LLM serving. Best for: maximum throughput on GPU hardware, serving large models, continuous batching. `bash pip install vllm vllm serve meta-llama/Llama-3.1-70B-Instruct \ --port 8000 \ --max-model-len 65536 \ --tensor-parallel-size 2 \ --enable-auto-tool-choice \ --tool-call-parser hermes` Then configure Hermes: `bash hermes model # Select "Custom endpoint (self-hosted / VLLM / etc.)" # Enter URL: http://localhost:8000/v1 # Skip API key (or enter one if you configured vLLM with --api-key) # Enter model name: meta-llama/Llama-3.1-70B-Instruct` Context length: vLLM reads the model’s `max_position_embeddings` by default. If that exceeds your GPU memory, it errors and asks you to set `--max-model-len` lower. You can also use `--max-model-len auto` to automatically find the maximum that fits. Set `--gpu-memory-utilization 0.95` (default 0.9) to squeeze more context into VRAM. Tool calling requires explicit flags: | Flag | Purpose | |——|———| | `--enable-auto-tool-choice` | Required for `tool_choice: "auto"` (the default in Hermes) | | `--tool-call-parser <name>` | Parser for the model’s tool call format | Supported parsers: `hermes` (Qwen 2.5, Hermes 2/3), `llama3_json` (Llama 3.x), `mistral`, `deepseek_v3`, `deepseek_v31`, `xlam`, `pythonic`. Without these flags, tool calls won’t work — the model will output tool calls as text. :::tip vLLM supports human-readable sizes: `--max-model-len 64k` (lowercase k = 1000, uppercase K = 1024). ::: — ### SGLang — Fast Serving with RadixAttention SGLang is an alternative to vLLM with RadixAttention for KV cache reuse. Best for: multi-turn conversations (prefix caching), constrained decoding, structured output. `bash pip install "sglang[all]" python -m sglang.launch_server \ --model meta-llama/Llama-3.1-70B-Instruct \ --port 30000 \ --context-length 65536 \ --tp 2 \ --tool-call-parser qwen` Then configure Hermes: `bash hermes model # Select "Custom endpoint (self-hosted / VLLM / etc.)" # Enter URL: http://localhost:30000/v1 # Enter model name: meta-llama/Llama-3.1-70B-Instruct` Context length: SGLang reads from the model’s config by default. Use `--context-length` to override. If you need to exceed the model’s declared maximum, set `SGLANG_ALLOW_OVERWRITE_LONGER_CONTEXT_LEN=1`. Tool calling: Use `--tool-call-parser` with the appropriate parser for your model family: `qwen` (Qwen 2.5), `llama3`, `llama4`, `deepseekv3`, `mistral`, `glm`. Without this flag, tool calls come back as plain text. :::caution SGLang defaults to 128 max output tokens If responses seem truncated, add `max_tokens` to your requests or set `--default-max-tokens` on the server. SGLang’s default is only 128 tokens per response if not specified in the request. ::: — ### llama.cpp / llama-server — CPU & Metal Inference llama.cpp runs quantized models on CPU, Apple Silicon (Metal), and consumer GPUs. Best for: running models without a datacenter GPU, Mac users, edge deployment. `bash # Build and start llama-server cmake -B build && cmake --build build --config Release ./build/bin/llama-server \ --jinja -fa \ -c 64000 \ -ngl 99 \ -m models/qwen2.5-coder-32b-instruct-Q4_K_M.gguf \ --port 8080 --host 0.0.0.0` Context length (`-c`): Recent builds default to `0` which reads the model’s training context from the GGUF metadata. For models with 128k+ training context, this can OOM trying to allocate the full KV cache. Set `-c` explicitly to at least 64,000 tokens for Hermes. If using parallel slots (`-np`), the total context is divided among slots — with `-c 64000 -np 4`, each slot only gets 16k, which is below Hermes’ minimum per active session. Then configure Hermes to point at it: `bash hermes model # Select "Custom endpoint (self-hosted / VLLM / etc.)" # Enter URL: http://localhost:8080/v1 # Skip API key (local servers don't need one) # Enter model name — or leave blank to auto-detect if only one model is loaded` This saves the endpoint to `config.yaml` so it persists across sessions. :::caution `--jinja` is required for tool calling Without `--jinja`, llama-server ignores the `tools` parameter entirely. The model will try to call tools by writing JSON in its response text, but Hermes won’t recognize it as a tool call — you’ll see raw JSON like `{"name": "web_search", ...}` printed as a message instead of an actual search. Native tool calling support (best performance): Llama 3.x, Qwen 2.5 (including Coder), Hermes 2/3, Mistral, DeepSeek, Functionary. All other models use a generic handler that works but may be less efficient. See the llama.cpp function calling docs for the full list. You can verify tool support is active by checking `http://localhost:8080/props` — the `chat_template` field should be present. ::: :::tip Download GGUF models from Hugging Face. Q4_K_M quantization offers the best balance of quality vs. memory usage. ::: — ### LM Studio — Desktop App with Local Models LM Studio is a desktop app for running local models with a GUI. Best for: users who prefer a visual interface, quick model testing, developers on macOS/Windows/Linux. Start the server from the LM Studio app (Developer tab → Start Server), or use the CLI: `bash lms server start # Starts on port 1234 lms load qwen2.5-coder --context-length 64000` Then configure Hermes: `bash hermes model # Select "LM Studio" # Press Enter to use http://localhost:1234/v1 # Pick one of the discovered models # If LM Studio server auth is enabled, enter LM_API_KEY when prompted` Hermes will automatically load a LM Studio model with 64K context length To change context length in LM Studio: 1. Click the gear icon next to the model picker 2. Set “Context Length” to at least 64000 for a smooth experience 3. Reload the model for the change to take effect 4. If your machine cannot fit 64000, consider using a smaller model with larger context lengths. Alternatively, use the CLI: `lms load model-name --context-length 64000` You can use the CLI to estimate if the model will fit: `lms load model-name --context-length 64000 --estimate-only` To set persistent per-model defaults: My Models tab → gear icon on the model → set context size. ::: Tool calling: Supported since LM Studio 0.3.6. Models with native tool-calling training (Qwen 2.5, Llama 3.x, Mistral, Hermes) are auto-detected and shown with a tool badge. Other models use a generic fallback that may be less reliable. — ### WSL2 Networking (Windows Users) Since Hermes Agent requires a Unix environment, Windows users run it inside WSL2. If your model server (Ollama, LM Studio, etc.) runs on the Windows host, you need to bridge the network gap — WSL2 uses a virtual network adapter with its own subnet, so `localhost` inside WSL2 refers to the Linux VM, not the Windows host. :::tip Both in WSL2? No problem. If your model server also runs inside WSL2 (common for vLLM, SGLang, and llama-server), `localhost` works as expected — they share the same network namespace. Skip this section. ::: #### Option 1: Mirrored Networking Mode (Recommended) Available on Windows 11 22H2+, mirrored mode makes `localhost` work bidirectionally between Windows and WSL2 — the simplest fix. 1. Create or edit `%USERPROFILE%\.wslconfig` (e.g., `C:\Users\YourName\.wslconfig`): `ini [wsl2] networkingMode=mirrored` 2. Restart WSL from PowerShell: `powershell wsl --shutdown` 3. Reopen your WSL2 terminal. `localhost` now reaches Windows services: `bash curl http://localhost:11434/v1/models # Ollama on Windows — works` :::note Hyper-V Firewall On some Windows 11 builds, the Hyper-V firewall blocks mirrored connections by default. If `localhost` still doesn’t work after enabling mirrored mode, run this in an Admin PowerShell: `powershell Set-NetFirewallHyperVVMSetting -Name '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -DefaultInboundAction Allow` ::: #### Option 2: Use the Windows Host IP (Windows 10 / older builds) If you can’t use mirrored mode, find the Windows host IP from inside WSL2 and use that instead of `localhost`: `bash # Get the Windows host IP (the default gateway of WSL2's virtual network) ip route show | grep -i default | awk '{ print $3 }' # Example output: 172.29.192.1` Use that IP in your Hermes config: `yaml model: default: qwen2.5-coder:32b provider: custom base_url: http://172.29.192.1:11434/v1 # Windows host IP, not localhost` :::tip Dynamic helper The host IP can change on WSL2 restart. You can grab it dynamically in your shell: `bash export WSL_HOST=$(ip route show | grep -i default | awk '{ print $3 }') echo "Windows host at: $WSL_HOST" curl http://$WSL_HOST:11434/v1/models # Test Ollama` Or use your machine’s mDNS name (requires `libnss-mdns` in WSL2): `bash sudo apt install libnss-mdns curl http://$(hostname).local:11434/v1/models` ::: #### Server Bind Address (Required for NAT Mode) If you’re using Option 2 (NAT mode with the host IP), the model server on Windows must accept connections from outside `127.0.0.1`. By default, most servers only listen on localhost — WSL2 connections in NAT mode come from a different virtual subnet and will be refused. In mirrored mode, `localhost` maps directly so the default `127.0.0.1` binding works fine. | Server | Default bind | How to fix | |––––|———––|————| | Ollama | `127.0.0.1` | Set `OLLAMA_HOST=0.0.0.0` environment variable before starting Ollama (System Settings → Environment Variables on Windows, or edit the Ollama service) | | LM Studio | `127.0.0.1` | Enable “Serve on Network” in the Developer tab → Server settings | | llama-server | `127.0.0.1` | Add `--host 0.0.0.0` to the startup command | | vLLM | `0.0.0.0` | Already binds to all interfaces by default | | SGLang | `127.0.0.1` | Add `--host 0.0.0.0` to the startup command | Ollama on Windows (detailed): Ollama runs as a Windows service. To set `OLLAMA_HOST`: 1. Open System Properties → Environment Variables 2. Add a new System variable: `OLLAMA_HOST` = `0.0.0.0` 3. Restart the Ollama service (or reboot) #### Windows Firewall Windows Firewall treats WSL2 as a separate network (in both NAT and mirrored mode). If connections still fail after the steps above, add a firewall rule for your model server’s port: `powershell # Run in Admin PowerShell — replace PORT with your server's port New-NetFirewallRule -DisplayName "Allow WSL2 to Model Server" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 11434` Common ports: Ollama `11434`, vLLM `8000`, SGLang `30000`, llama-server `8080`, LM Studio `1234`. #### Quick Verification From inside WSL2, test that you can reach your model server: `bash # Replace URL with your server's address and port curl http://localhost:11434/v1/models # Mirrored mode curl http://172.29.192.1:11434/v1/models # NAT mode (use your actual host IP)` If you get a JSON response listing your models, you’re good. Use that same URL as the `base_url` in your Hermes config. — ### Troubleshooting Local Models These issues affect all local inference servers when used with Hermes. #### “Connection refused” from WSL2 to a Windows-hosted model server If you’re running Hermes inside WSL2 and your model server on the Windows host, `http://localhost:<port>` won’t work in WSL2’s default NAT networking mode. See WSL2 Networking above for the fix. #### Tool calls appear as text instead of executing The model outputs something like `{"name": "web_search", "arguments": {...}}` as a message instead of actually calling the tool. Cause: Your server doesn’t have tool calling enabled, or the model doesn’t support it through the server’s tool calling implementation. | Server | Fix | |––––|—–| | llama.cpp | Add `--jinja` to the startup command | | vLLM | Add `--enable-auto-tool-choice --tool-call-parser hermes` | | SGLang | Add `--tool-call-parser qwen` (or appropriate parser) | | Ollama | Tool calling is enabled by default — make sure your model supports it (check with `ollama show model-name`) | | LM Studio | Update to 0.3.6+ and use a model with native tool support | #### Model seems to forget context or give incoherent responses Cause: Context window is too small. When the conversation exceeds the context limit, most servers silently drop older messages. Hermes’s system prompt + tool schemas alone can use 4k–8k tokens. Diagnosis: `bash # Check what Hermes thinks the context is # Look at startup line: "Context limit: X tokens" # Check your server's actual context # Ollama: ollama ps (CONTEXT column) # llama.cpp: curl http://localhost:8080/props | jq '.default_generation_settings.n_ctx' # vLLM: check --max-model-len in startup args` Fix: Set context to at least 64,000 tokens for agent use. See each server’s section above for the specific flag. #### “Context limit: 2048 tokens” at startup Hermes auto-detects context length from your server’s `/v1/models` endpoint. If the server reports a low value (or doesn’t report one at all), Hermes uses the model’s declared limit which may be wrong. Fix: Set it explicitly in `config.yaml`: `yaml model: default: your-model provider: custom base_url: http://localhost:11434/v1 context_length: 64000` #### Responses get cut off mid-sentence Possible causes: 1. Low output cap (`max_tokens`) on the server — SGLang defaults to 128 tokens per response. Set `--default-max-tokens` on the server or configure Hermes with `model.max_tokens` in config.yaml. Note: `max_tokens` controls response length only — it is unrelated to how long your conversation history can be (that is `context_length`). 2. Context exhaustion — The model filled its context window. Increase `model.context_length` or enable context compression in Hermes. — ### LiteLLM Proxy — Multi-Provider Gateway LiteLLM is an OpenAI-compatible proxy that unifies 100+ LLM providers behind a single API. Best for: switching between providers without config changes, load balancing, fallback chains, budget controls. `bash # Install and start pip install "litellm[proxy]" litellm --model anthropic/claude-sonnet-4 --port 4000 # Or with a config file for multiple models: litellm --config litellm_config.yaml --port 4000` Then configure Hermes with `hermes model` → Custom endpoint → `http://localhost:4000/v1`. Example `litellm_config.yaml` with fallback: `yaml model_list: - model_name: "best" litellm_params: model: anthropic/claude-sonnet-4 api_key: sk-ant-... - model_name: "best" litellm_params: model: openai/gpt-4o api_key: sk-... router_settings: routing_strategy: "latency-based-routing"` — ### ClawRouter — Cost-Optimized Routing ClawRouter by BlockRunAI is a local routing proxy that auto-selects models based on query complexity. It classifies requests across 14 dimensions and routes to the cheapest model that can handle the task. Payment is via USDC cryptocurrency (no API keys). `bash # Install and start npx @blockrun/clawrouter # Starts on port 8402` Then configure Hermes with `hermes model` → Custom endpoint → `http://localhost:8402/v1` → model name `blockrun/auto`. Routing profiles: | Profile | Strategy | Savings | |———|–––––|———| | `blockrun/auto` | Balanced quality/cost | 74-100% | | `blockrun/eco` | Cheapest possible | 95-100% | | `blockrun/premium` | Best quality models | 0% | | `blockrun/free` | Free models only | 100% | | `blockrun/agentic` | Optimized for tool use | varies | :::note ClawRouter requires a USDC-funded wallet on Base or Solana for payment. All requests route through BlockRun’s backend API. Run `npx @blockrun/clawrouter doctor` to check wallet status. ::: — ### Other Compatible Providers Any service with an OpenAI-compatible API works. Some popular options: | Provider | Base URL | Notes | |–––––|–––––|—––| | Together AI | `https://api.together.xyz/v1` | Cloud-hosted open models | | Groq | `https://api.groq.com/openai/v1` | Ultra-fast inference | | DeepSeek | `https://api.deepseek.com/v1` | DeepSeek models | | Fireworks AI | `https://api.fireworks.ai/inference/v1` | Fast open model hosting | | GMI Cloud | `https://api.gmi-serving.com/v1` | Managed OpenAI-compatible inference | | Cerebras | `https://api.cerebras.ai/v1` | Wafer-scale chip inference | | Mistral AI | `https://api.mistral.ai/v1` | Mistral models | | OpenAI | `https://api.openai.com/v1` | Direct OpenAI access | | Azure OpenAI | `https://YOUR.openai.azure.com/` | Enterprise OpenAI | | LocalAI | `http://localhost:8080/v1` | Self-hosted, multi-model | | Jan | `http://localhost:1337/v1` | Desktop app with local models | Configure any of these with `hermes model` → Custom endpoint, or in `config.yaml`: `yaml model: default: meta-llama/Llama-3.1-70B-Instruct-Turbo provider: custom base_url: https://api.together.xyz/v1 api_key: your-together-key` — ### Context Length Detection :::note Two settings, easy to confuse `context_length` is the total context window — the combined budget for input and output tokens (e.g. 200,000 for Claude Opus 4.6). Hermes uses this to decide when to compress history and to validate API requests. `model.max_tokens` is the output cap — the maximum number of tokens the model may generate in a single response. It has nothing to do with how long your conversation history can be. The industry-standard name `max_tokens` is a common source of confusion; Anthropic’s native API has since renamed it `max_output_tokens` for clarity. Set `context_length` when auto-detection gets the window size wrong. Set `model.max_tokens` only when you need to limit how long individual responses can be. ::: Hermes uses a multi-source resolution chain to detect the correct context window for your model and provider: 1. Config override — `model.context_length` in config.yaml (highest priority) 2. Custom provider per-model — `custom_providers[].models.<id>.context_length` 3. Persistent cache — previously discovered values (survives restarts) 4. Endpoint `/models` — queries your server’s API (local/custom endpoints) 5. Anthropic `/v1/models` — queries Anthropic’s API for `max_input_tokens` (API-key users only) 6. OpenRouter API — live model metadata from OpenRouter 7. Nous Portal — suffix-matches Nous model IDs against OpenRouter metadata 8. models.dev — community-maintained registry with provider-specific context lengths for 3800+ models across 100+ providers 9. Fallback defaults — broad model family patterns (128K default) For most setups this works out of the box. The system is provider-aware — the same model can have different context limits depending on who serves it (e.g., `claude-opus-4.6` is 1M on Anthropic direct but 128K on GitHub Copilot). To set the context length explicitly, add `context_length` to your model config: `yaml model: default: "qwen3.5:9b" base_url: "http://localhost:8080/v1" context_length: 131072 # tokens` For custom endpoints, you can also set context length per model: `yaml custom_providers: - name: "My Local LLM" base_url: "http://localhost:11434/v1" models: qwen3.5:27b: context_length: 64000 deepseek-r1:70b: context_length: 65536` `hermes model` will prompt for context length when configuring a custom endpoint. Leave it blank for auto-detection. :::tip When to set this manually - You’re using Ollama with a custom `num_ctx` that’s lower than the model’s maximum - You want to limit context below the model’s maximum (e.g., 8k on a 128k model to save VRAM) - You’re running behind a proxy that doesn’t expose `/v1/models` ::: — ### Named Custom Providers If you work with multiple custom endpoints (e.g., a local dev server and a remote GPU server), you can define them as named custom providers in `config.yaml`: yaml custom_providers: - name: local base_url: http://localhost:8080/v1 # api_key omitted — Hermes uses "no-key-required" for keyless local servers - name: work base_url: https://gpu-server.internal.corp/v1 key_env: CORP_API_KEY api_mode: chat_completions # set explicitly by `hermes model` → Custom Endpoint wizard; auto-detection still happens as a fallback - name: anthropic-proxy base_url: https://proxy.example.com/anthropic key_env: ANTHROPIC_PROXY_KEY api_mode: anthropic_messages # for Anthropic-compatible proxies Some OpenAI-compatible endpoints need provider-specific request body fields. Add an `extra_body` map to the matching custom provider and Hermes will merge it into each chat-completions request for that endpoint: `yaml custom_providers: - name: gemma-local base_url: http://localhost:8080/v1 model: google/gemma-4-31b-it extra_body: enable_thinking: true reasoning_effort: high` Use the shape your server documents. For example, vLLM Gemma deployments and some NVIDIA NIM endpoints expect `enable_thinking` under `chat_template_kwargs` instead of as a top-level `extra_body` field: `yaml extra_body: chat_template_kwargs: enable_thinking: true` The `hermes model` → Custom Endpoint wizard now prompts for `api_mode` explicitly and persists your answer to `config.yaml`. URL-based auto-detection (e.g. `/anthropic` paths → `anthropic_messages`) still happens as a fallback when the field is left blank. Native vision for custom-provider models. If your custom endpoint serves a vision-capable model that isn’t in models.dev, set `model.supports_vision: true` so Hermes routes attached images natively (as `image_url` parts) instead of pre-processing them through `vision_analyze`. Single knob — no need to also set `agent.image_input_mode: native`. `yaml model: provider: custom base_url: http://localhost:8080/v1 default: qwen3.6-35b-a3b supports_vision: true # send images natively; otherwise vision_analyze pre-describes them` The same key is honored on per-named-provider models (`custom_providers[].models[].supports_vision`) and accepts standard YAML booleans (`true/false/yes/no/on/off/1/0`). Switch between them mid-session with the triple syntax: `/model custom:local:qwen-2.5 # Use the "local" endpoint with qwen-2.5 /model custom:work:llama3-70b # Use the "work" endpoint with llama3-70b /model custom:anthropic-proxy:claude-sonnet-4 # Use the proxy` You can also select named custom providers from the interactive `hermes model` menu. — ### Cookbook: Together AI, Groq, Perplexity The cloud providers listed in Other Compatible Providers all speak OpenAI’s REST dialect, so they wire up the same way under `custom_providers:`. Three worked recipes follow. Each drops into `~/.hermes/config.yaml` and the matching API key goes in `~/.hermes/.env`. #### Together AI Hosts open-weight models (Llama, MiniMax, Gemma, DeepSeek, Qwen) at prices significantly below first-party APIs. Good default for multi-model fleets. `yaml # ~/.hermes/config.yaml custom_providers: - name: together base_url: https://api.together.xyz/v1 key_env: TOGETHER_API_KEY # api_mode: chat_completions # default — no need to set model: default: MiniMaxAI/MiniMax-M2.7 # or any model from together.ai/models provider: custom:together` `bash # ~/.hermes/.env TOGETHER_API_KEY=your-together-key` Switch models mid-session: `/model custom:together:meta-llama/Llama-3.3-70B-Instruct-Turbo /model custom:together:google/gemma-4-31b-it /model custom:together:deepseek-ai/DeepSeek-V3` Together’s `/v1/models` endpoint works, so `hermes model` can auto-discover available models. #### Groq Ultra-fast inference (~500 tok/s on Llama-3.3-70B). Small catalog but strong for latency-sensitive interactive use. `yaml # ~/.hermes/config.yaml custom_providers: - name: groq base_url: https://api.groq.com/openai/v1 key_env: GROQ_API_KEY model: default: llama-3.3-70b-versatile provider: custom:groq` `bash # ~/.hermes/.env GROQ_API_KEY=your-groq-key` #### Perplexity Useful when you want a model that does live web search and citation automatically. Strict about which models are available — check perplexity.ai/settings/api for the current list. `yaml # ~/.hermes/config.yaml custom_providers: - name: perplexity base_url: https://api.perplexity.ai key_env: PERPLEXITY_API_KEY model: default: sonar provider: custom:perplexity` `bash # ~/.hermes/.env PERPLEXITY_API_KEY=your-perplexity-key` #### Multiple providers in one config The three recipes compose — use all of them together and switch per turn with `/model custom:<name>:<model>`: `yaml custom_providers: - name: together base_url: https://api.together.xyz/v1 key_env: TOGETHER_API_KEY - name: groq base_url: https://api.groq.com/openai/v1 key_env: GROQ_API_KEY - name: perplexity base_url: https://api.perplexity.ai key_env: PERPLEXITY_API_KEY model: default: MiniMaxAI/MiniMax-M2.7 provider: custom:together # boot to Together; switch freely after` :::tip Troubleshooting - `hermes doctor` should print no `Unknown provider` warnings for any of these names after the CLI validator fixes in #15083. - If a provider’s `/v1/models` endpoint is unreachable (Perplexity is the common one), `hermes model` will persist the model with a warning rather than hard-reject — see #15136. - To skip `custom_providers:` entirely and use bare `provider: custom` with `CUSTOM_BASE_URL` env var, see #15103. ::: — ### Choosing the Right Setup | Use Case | Recommended | |–––––|———––| | Just want it to work | OpenRouter (default) or Nous Portal | | Local models, easy setup | Ollama | | Production GPU serving | vLLM or SGLang | | Mac / no GPU | Ollama or llama.cpp | | Multi-provider routing | LiteLLM Proxy or OpenRouter | | Cost optimization | ClawRouter or OpenRouter with `sort: "price"` | | Maximum privacy | Ollama, vLLM, or llama.cpp (fully local) | | Enterprise / Azure | Azure OpenAI with custom endpoint | | Chinese AI models | z.ai (GLM), Kimi/Moonshot (`kimi-coding` or `kimi-coding-cn`), MiniMax, Xiaomi MiMo, or Tencent TokenHub (first-class providers) | :::tip You can switch between providers at any time with `hermes model` — no restart required. Your conversation history, memory, and skills carry over regardless of which provider you use. ::: ## Optional API Keys | Feature | Provider | Env Variable | |———|–––––|–––––––| | Web scraping | Firecrawl | `FIRECRAWL_API_KEY`, `FIRECRAWL_API_URL` | | Browser automation | Browserbase | `BROWSERBASE_API_KEY`, `BROWSERBASE_PROJECT_ID` | | Image generation | FAL | `FAL_KEY` | | Premium TTS voices | ElevenLabs | `ELEVENLABS_API_KEY` | | OpenAI TTS + voice transcription | OpenAI | `VOICE_TOOLS_OPENAI_KEY` | | Mistral TTS + voice transcription | Mistral | `MISTRAL_API_KEY` | | Cross-session user modeling | Honcho | `HONCHO_API_KEY` | | Semantic long-term memory | Supermemory | `SUPERMEMORY_API_KEY` | ### Self-Hosting Firecrawl By default, Hermes uses the Firecrawl cloud API for web search and scraping. If you prefer to run Firecrawl locally, you can point Hermes at a self-hosted instance instead. See Firecrawl’s SELF_HOST.md for complete setup instructions. What you get: No API key required, no rate limits, no per-page costs, full data sovereignty. What you lose: The cloud version uses Firecrawl’s proprietary “Fire-engine” for advanced anti-bot bypassing (Cloudflare, CAPTCHAs, IP rotation). Self-hosted uses basic fetch + Playwright, so some protected sites may fail. Search uses DuckDuckGo instead of Google. Setup: 1. Clone and start the Firecrawl Docker stack (5 containers: API, Playwright, Redis, RabbitMQ, PostgreSQL — requires ~4-8 GB RAM): `bash git clone https://github.com/firecrawl/firecrawl cd firecrawl # In .env, set: USE_DB_AUTHENTICATION=false, HOST=0.0.0.0, PORT=3002 docker compose up -d` 2. Point Hermes at your instance (no API key needed): `bash hermes config set FIRECRAWL_API_URL http://localhost:3002` You can also set both `FIRECRAWL_API_KEY` and `FIRECRAWL_API_URL` if your self-hosted instance has authentication enabled. ## OpenRouter Provider Routing When using OpenRouter, you can control how requests are routed across providers. Add a `provider_routing` section to `~/.hermes/config.yaml`: `yaml provider_routing: sort: "throughput" # "price" (default), "throughput", or "latency" # only: ["anthropic"] # Only use these providers # ignore: ["deepinfra"] # Skip these providers # order: ["anthropic", "google"] # Try providers in this order # require_parameters: true # Only use providers that support all request params # data_collection: "deny" # Exclude providers that may store/train on data` Shortcuts: Append `:nitro` to any model name for throughput sorting (e.g., `anthropic/claude-sonnet-4:nitro`), or `:floor` for price sorting. ## OpenRouter Pareto Code Router OpenRouter ships an experimental coding-model router at `openrouter/pareto-code` that auto-routes requests to the cheapest model meeting a coding-quality bar (ranked by Artificial Analysis). Pick this model and tune the `min_coding_score` knob in `~/.hermes/config.yaml`: `yaml model: provider: openrouter model: openrouter/pareto-code openrouter: min_coding_score: 0.65 # 0.0–1.0; higher = stronger (more expensive) coders. Default 0.65.` Notes: - `min_coding_score` is only sent when `model.model` is `openrouter/pareto-code`. On any other model the value is a no-op. - Set to empty string (or remove the line) to let OpenRouter pick the strongest available coder — its documented behavior when the plugins block is omitted. - Selection is deterministic per score on a given day, but the actual model chosen can shift as the Pareto frontier moves (new models, benchmark updates). - See OpenRouter’s Pareto Router docs for the full router behavior. - To use the Pareto Code router for a specific auxiliary task (compression, vision, etc.) instead of the main agent, set `extra_body.plugins` under that task — see Auxiliary Models → OpenRouter routing & Pareto Code for auxiliary tasks. ## Fallback Providers Configure a chain of backup providers Hermes tries in order when the primary model fails (rate limits, server errors, auth failures). The canonical format is a top-level `fallback_providers:` list: `yaml fallback_providers: - provider: openrouter model: anthropic/claude-sonnet-4 - provider: anthropic model: claude-sonnet-4 # base_url: http://localhost:8000/v1 # optional, for custom endpoints # api_mode: chat_completions # optional override` The legacy single-pair `fallback_model:` dict is still accepted for back-compat: `yaml fallback_model: provider: openrouter model: anthropic/claude-sonnet-4` When activated, the fallback swaps the model and provider mid-session without losing your conversation. The chain is tried entry-by-entry; activation is one-shot per session. Supported providers: `openrouter`, `nous`, `novita`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `gemini`, `google-gemini-cli`, `qwen-oauth`, `huggingface`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `minimax-oauth`, `deepseek`, `nvidia`, `xai`, `xai-oauth`, `ollama-cloud`, `bedrock`, `azure-foundry`, `opencode-zen`, `opencode-go`, `kilocode`, `xiaomi`, `arcee`, `gmi`, `stepfun`, `lmstudio`, `alibaba`, `alibaba-coding-plan`, `tencent-tokenhub`, `custom`. :::tip Fallback is configured exclusively through `config.yaml` — or interactively via `hermes fallback`. For full details on when it triggers, how the chain advances, and how it interacts with auxiliary tasks and delegation, see Fallback Providers. ::: — ## See Also - Configuration — General configuration (directory structure, config precedence, terminal backends, memory, compression, and more) - Environment Variables — Complete reference of all environment variables — # MCP (Model Context Protocol) # MCP (Model Context Protocol) MCP lets Hermes Agent connect to external tool servers so the agent can use tools that live outside Hermes itself — GitHub, databases, file systems, browser stacks, internal APIs, and more. If you have ever wanted Hermes to use a tool that already exists somewhere else, MCP is usually the cleanest way to do it. ## What MCP gives you - Access to external tool ecosystems without writing a native Hermes tool first - Local stdio servers and remote HTTP MCP servers in the same config - Automatic tool discovery and registration at startup - Utility wrappers for MCP resources and prompts when supported by the server - Per-server filtering so you can expose only the MCP tools you actually want Hermes to see ## Quick start 1. Install MCP support (already included if you used the standard install script): `bash cd ~/.hermes/hermes-agent uv pip install -e ".[mcp]"` 2. Add an MCP server to `~/.hermes/config.yaml`: `yaml mcp_servers: filesystem: command: "npx" args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]` 3. Start Hermes: `bash hermes chat` 4. Ask Hermes to use the MCP-backed capability. For example: `text List the files in /home/user/projects and summarize the repo structure.` Hermes will discover the MCP server’s tools and use them like any other tool. ## Catalog: one-click install for Nous-approved MCPs Hermes ships a curated catalog of MCP servers that Nous staff has reviewed and merged. They’re disabled by default — install only what you actually want. `bash hermes mcp # interactive picker (default) hermes mcp catalog # plain-text list, scriptable hermes mcp install n8n # install a catalog entry by name` The picker shows each entry with its current status: `n8n available Manage and inspect n8n workflows from Hermes linear enabled Linear issue/project management (remote OAuth) github installed (disabled) GitHub repo + PR tools` Hit `Enter` on a row to install (and walk through any required credentials), enable, disable, or uninstall. Catalog entries are stored under `optional-mcps/` in the hermes-agent repo — presence in that directory means Nous approval. There is no community submission tier; entries are added by merging a PR. Catalog entries can require: - API key — Hermes prompts at install time and writes the value to `~/.hermes/.env`. Non-secret values (base URLs) go to the same file. - OAuth (remote MCP) — written as `auth: oauth` in your config; the MCP client opens a browser on first connection. - OAuth (third-party provider like Google/GitHub) — Hermes points you at `hermes auth <provider>` if you haven’t authenticated already. ### Tool selection at install time After credentials are configured, Hermes probes the MCP server to list every tool it exposes and presents a checklist: `Select tools for 'linear' (SPACE toggle, ENTER confirm) [x] find_issues Find issues matching a query [x] get_issue Get a single issue [x] create_issue Create a new issue [ ] delete_workspace Delete a Linear workspace ...` The pre-checked rows come from: 1. Your prior selection if you’ve installed this entry before (reinstalls preserve what you had — the manifest’s defaults don’t override it) 2. The manifest’s `tools.default_enabled` if the entry declares one (some catalog entries pre-prune mutating or rarely-useful tools) 3. Everything if neither applies Submit the checklist with ENTER. Only the checked tools end up in `mcp_servers.<name>.tools.include`. If you select everything, no filter is written (cleanest config shape, identical behavior). If the probe fails (server unreachable, OAuth not yet completed, backing service not running), the install still succeeds: the manifest’s `tools.default_enabled` is applied directly (if declared), or no filter is written (if not). Re-run `hermes mcp configure <name>` once the server is reachable to refine. ### Trust model Installing a catalog entry runs whatever the manifest specifies — `git clone`, the entry’s `bootstrap` commands (`pip install`, `npm install`, etc.), and ultimately the MCP server’s own code. Manifests are gated by PR review into the hermes-agent repo, so Nous has reviewed each entry before it shipped — but you should still read the manifest before installing, especially the `source:` field’s repository, the `install.bootstrap:` commands, and any `transport.command:` invocation. Manifests live at `optional-mcps/<name>/manifest.yaml` on GitHub. The picker also prints the manifest’s `source:` URL at install time so you can quickly verify the upstream repo. ### Manifest version compatibility Manifests pin a `manifest_version`. The catalog is forward-compatible: if a PR adds an entry with a newer `manifest_version` than your installed Hermes understands, the picker will surface a warning (`⚠ '<name>' requires a newer Hermes`) for that entry instead of silently hiding it. Run `hermes update` to install the latest Hermes when you see that. ### Runtime `${ENV_VAR}` substitution Inside an entry’s `transport.command`, `transport.args`, `transport.url`, and `headers`, `${VAR}` placeholders are resolved at server-connect time from environment variables (which include everything in `~/.hermes/.env`). This is useful when a catalog entry wants to reference a value the user configured elsewhere — e.g. `${HOME}/foo` or `${MY_PROVIDER_TOKEN}`. Note this is distinct from `${INSTALL_DIR}` in catalog manifests, which is substituted at install-time with the path the catalog cloned the entry’s repo into. ### Updating tool selection later `bash hermes mcp configure linear` Reopens the same checklist with your current selection pre-checked. Use this when you want more tools enabled, or when the server has added new tools that you want to opt into. ### Updating the catalog manifest MCPs are never auto-updated. Re-run `hermes mcp install <name>` to refresh after a Hermes update if a manifest version changed. To add an MCP to the catalog, open a PR against `optional-mcps/`. ## Two kinds of MCP servers ### Stdio servers Stdio servers run as local subprocesses and talk over stdin/stdout. `yaml mcp_servers: github: command: "npx" args: ["-y", "@modelcontextprotocol/server-github"] env: GITHUB_PERSONAL_ACCESS_TOKEN: ""` Use stdio servers when: - the server is installed locally - you want low-latency access to local resources - you are following MCP server docs that show `command`, `args`, and `env` ### HTTP servers HTTP MCP servers are remote endpoints Hermes connects to directly. `yaml mcp_servers: remote_api: url: "https://mcp.example.com/mcp" headers: Authorization: "Bearer "` Use HTTP servers when: - the MCP server is hosted elsewhere - your organization exposes internal MCP endpoints - you do not want Hermes spawning a local subprocess for that integration ### OAuth-authenticated HTTP servers Most hosted MCP servers (Linear, Sentry, Atlassian, Asana, Figma, Stripe, …) require OAuth 2.1 instead of a static bearer token. Set `auth: oauth` and Hermes handles discovery, dynamic client registration, PKCE, token exchange, refresh, and step-up auth via the MCP Python SDK. `yaml mcp_servers: linear: url: "https://mcp.linear.app/mcp" auth: oauth` On first connect, Hermes prints an authorize URL, opens your browser when possible, and waits for the OAuth callback on a local loopback port. Tokens are cached at `~/.hermes/mcp-tokens/<server>.json` with 0o600 perms; subsequent runs reuse them silently until refresh fails. Remote / headless hosts. When Hermes runs on a different machine than your browser, the loopback callback can’t reach your laptop. Two ways to complete the flow: - Paste-back (no setup): on an interactive terminal Hermes prints “Or paste the redirect URL here…” alongside the authorize URL. Open the URL in your browser, approve, copy the full URL the browser ends up on (the redirect will show a connection error — that’s expected), paste it at the prompt. Bare `?code=…&state=…` query strings work too. - SSH port forward: `ssh -N -L <port>:127.0.0.1:<port> user@host` in a separate terminal, then let the redirect flow normally. See OAuth over SSH / Remote Hosts for the full walkthrough, including DCR-less servers (e.g. Slack), pre-registered `client_id`/`client_secret`, scope customization, and re-auth via `hermes mcp login <server>`. Pitfall — providers that don’t support automatic registration (Google Drive, Atlassian). Some servers reject the dynamic client registration step (RFC 7591) that bare `auth: oauth` relies on — Google’s official Drive server (`https://drivemcp.googleapis.com/mcp/v1`) returns a `400 Bad Request`, so no OAuth client is created and no token is acquired. The symptom is subtle: these servers also serve `tools/list` without auth, so `hermes mcp login` can list the tools and look like it worked, but every real tool call later times out. `hermes mcp login` now detects this (it checks that a token actually landed on disk) and tells you to supply your own OAuth client. Create one in the provider’s console and add it to config: `yaml mcp_servers: googledrive: url: "https://drivemcp.googleapis.com/mcp/v1" auth: oauth oauth: client_id: "<your-oauth-client-id>" client_secret: "<your-oauth-client-secret>"` Then run `hermes mcp login googledrive` — with the pre-registered client, Hermes skips registration and runs the normal browser authorization flow. Pitfall — config auto-reload race. When you edit `~/.hermes/config.yaml` from inside a running Hermes session, the CLI auto-reloads MCP connections with a 30s timeout. That’s not enough for an interactive OAuth flow. Add the entry, then run `hermes mcp login <server>` from a fresh terminal — it waits the full 5 minutes for you to complete auth. ## mTLS / client certificates Remote HTTP MCP servers that require mutual TLS (client-certificate authentication) are supported via `client_cert` / `client_key`. Hermes passes the resolved certificate to the underlying HTTP client for the TLS handshake. `client_cert` accepts three shapes: - A single combined PEM path — one file holding both the certificate and the private key: `yaml mcp_servers: internal_api: url: "https://mcp.internal.example.com/mcp" client_cert: "~/.certs/mcp-client.pem"` - A `[cert, key]` 2-tuple — certificate and key in separate files (equivalent to setting `client_cert` + `client_key`): `yaml mcp_servers: internal_api: url: "https://mcp.internal.example.com/mcp" client_cert: ["~/.certs/mcp-client.crt", "~/.certs/mcp-client.key"]` - A `[cert, key, password]` 3-tuple — when the private key is encrypted, the third element is the key passphrase: `yaml mcp_servers: internal_api: url: "https://mcp.internal.example.com/mcp" client_cert: ["~/.certs/mcp-client.crt", "~/.certs/mcp-client.key", "${MCP_KEY_PASSWORD}"]` You can also keep the cert and key fully separate via `client_cert` (combined PEM) plus an explicit `client_key`. Paths support `~` expansion; a missing file raises a clear, server-scoped error rather than an opaque TLS handshake failure. ## Basic configuration reference Hermes reads MCP config from `~/.hermes/config.yaml` under `mcp_servers`. ### Common keys | Key | Type | Meaning | |—|—|—| | `command` | string | Executable for a stdio MCP server | | `args` | list | Arguments for the stdio server | | `env` | mapping | Environment variables passed to the stdio server | | `url` | string | HTTP MCP endpoint | | `headers` | mapping | HTTP headers for remote servers | | `client_cert` | string | list | Client certificate for mTLS — a combined PEM path, or `[cert, key]` / `[cert, key, password]` | | `client_key` | string | Client private-key PEM path (when separate from `client_cert`) | | `timeout` | number | Tool call timeout | | `connect_timeout` | number | Initial connection timeout | | `enabled` | bool | If `false`, Hermes skips the server entirely | | `supports_parallel_tool_calls` | bool | If `true`, tools from this server may run concurrently | | `tools` | mapping | Per-server tool filtering and utility policy | ### Minimal stdio example `yaml mcp_servers: filesystem: command: "npx" args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]` ### Minimal HTTP example `yaml mcp_servers: company_api: url: "https://mcp.internal.example.com" headers: Authorization: "Bearer "` ## Built-in presets For well-known MCP servers, `hermes mcp add` accepts a `--preset` flag that fills in the transport details so you don’t have to look up the command and args. The preset only supplies defaults — anything else (env vars, headers, filtering) you pass on the same command line still wins. | Preset | What it wires up | |—|—| | `codex` | The Codex CLI’s MCP server (`codex mcp-server` over stdio). Requires the `codex` CLI on PATH. | `bash # Add Codex CLI as an MCP server in one line hermes mcp add codex --preset codex` That writes the equivalent of: `yaml mcp_servers: codex: command: "codex" args: ["mcp-server"]` You can pick any local name (`hermes mcp add my-codex --preset codex` is fine); the preset only provides the `command`/`args` defaults. ## How Hermes registers MCP tools Hermes prefixes MCP tools so they do not collide with built-in names: `text mcp_<server_name>_<tool_name>` Examples: | Server | MCP tool | Registered name | |—|—|—| | `filesystem` | `read_file` | `mcp_filesystem_read_file` | | `github` | `create-issue` | `mcp_github_create_issue` | | `my-api` | `query.data` | `mcp_my_api_query_data` | In practice, you usually do not need to call the prefixed name manually — Hermes sees the tool and chooses it during normal reasoning. ## MCP utility tools When supported, Hermes also registers utility tools around MCP resources and prompts: - `list_resources` - `read_resource` - `list_prompts` - `get_prompt` These are registered per server with the same prefix pattern, for example: - `mcp_github_list_resources` - `mcp_github_get_prompt` ### Important These utility tools are now capability-aware: - Hermes only registers resource utilities if the MCP session actually supports resource operations - Hermes only registers prompt utilities if the MCP session actually supports prompt operations So a server that exposes callable tools but no resources/prompts will not get those extra wrappers. ## Per-server filtering You can control which tools each MCP server contributes to Hermes, allowing fine-grained management of your tool namespace. ### Disable a server entirely `yaml mcp_servers: legacy: url: "https://mcp.legacy.internal" enabled: false` If `enabled: false`, Hermes skips the server completely and does not even attempt a connection. ### Whitelist server tools `yaml mcp_servers: github: command: "npx" args: ["-y", "@modelcontextprotocol/server-github"] env: GITHUB_PERSONAL_ACCESS_TOKEN: "" tools: include: [create_issue, list_issues]` Only those MCP server tools are registered. ### Blacklist server tools `yaml mcp_servers: stripe: url: "https://mcp.stripe.com" tools: exclude: [delete_customer]` All server tools are registered except the excluded ones. ### Precedence rule If both are present: `yaml tools: include: [create_issue] exclude: [create_issue, delete_issue]` `include` wins. ### Filter utility tools too You can also separately disable Hermes-added utility wrappers: `yaml mcp_servers: docs: url: "https://mcp.docs.example.com" tools: prompts: false resources: false` That means: - `tools.resources: false` disables `list_resources` and `read_resource` - `tools.prompts: false` disables `list_prompts` and `get_prompt` ### Full example `yaml mcp_servers: github: command: "npx" args: ["-y", "@modelcontextprotocol/server-github"] env: GITHUB_PERSONAL_ACCESS_TOKEN: "" tools: include: [create_issue, list_issues, search_code] prompts: false stripe: url: "https://mcp.stripe.com" headers: Authorization: "Bearer " tools: exclude: [delete_customer] resources: false legacy: url: "https://mcp.legacy.internal" enabled: false` ## What happens if everything is filtered out? If your config filters out all callable tools and disables or omits all supported utilities, Hermes does not create an empty runtime MCP toolset for that server. That keeps the tool list clean. ## Runtime behavior ### Discovery time Hermes discovers MCP servers at startup and registers their tools into the normal tool registry. ### Dynamic Tool Discovery MCP servers can notify Hermes when their available tools change at runtime by sending a `notifications/tools/list_changed` notification. When Hermes receives this notification, it automatically re-fetches the server’s tool list and updates the registry — no manual `/reload-mcp` required. This is useful for MCP servers whose capabilities change dynamically (e.g. a server that adds tools when a new database schema is loaded, or removes tools when a service goes offline). The refresh is lock-protected so rapid-fire notifications from the same server don’t cause overlapping refreshes. Prompt and resource change notifications (`prompts/list_changed`, `resources/list_changed`) are received but not yet acted on. ### Reloading If you change MCP config, use: `text /reload-mcp` This reloads MCP servers from config and refreshes the available tool list. For runtime tool changes pushed by the server itself, see Dynamic Tool Discovery above. ### Toolsets Each configured MCP server also creates a runtime toolset when it contributes at least one registered tool: `text mcp-<server>` That makes MCP servers easier to reason about at the toolset level. ## Security model ### Stdio env filtering For stdio servers, Hermes does not blindly pass your full shell environment. Only explicitly configured `env` plus a safe baseline are passed through. This reduces accidental secret leakage. ### Config-level exposure control The new filtering support is also a security control: - disable dangerous tools you do not want the model to see - expose only a minimal whitelist for a sensitive server - disable resource/prompt wrappers when you do not want that surface exposed ## Example use cases ### GitHub server with a minimal issue-management surface `yaml mcp_servers: github: command: "npx" args: ["-y", "@modelcontextprotocol/server-github"] env: GITHUB_PERSONAL_ACCESS_TOKEN: "" tools: include: [list_issues, create_issue, update_issue] prompts: false resources: false` Use it like: `text Show me open issues labeled bug, then draft a new issue for the flaky MCP reconnection behavior.` ### Stripe server with dangerous actions removed `yaml mcp_servers: stripe: url: "https://mcp.stripe.com" headers: Authorization: "Bearer " tools: exclude: [delete_customer, refund_payment]` Use it like: `text Look up the last 10 failed payments and summarize common failure reasons.` ### Filesystem server for a single project root `yaml mcp_servers: project_fs: command: "npx" args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/my-project"]` Use it like: `text Inspect the project root and explain the directory layout.` ## Troubleshooting ### MCP server not connecting Check: `bash # Verify MCP deps are installed (already included in standard install) cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]" node --version npx --version` Then verify your config and restart Hermes. ### Tools not appearing Possible causes: - the server failed to connect - discovery failed - your filter config excluded the tools - the utility capability does not exist on that server - the server is disabled with `enabled: false` If you are intentionally filtering, this is expected. ### Why didn’t resource or prompt utilities appear? Because Hermes now only registers those wrappers when both are true: 1. your config allows them 2. the server session actually supports the capability This is intentional and keeps the tool list honest. ## Parallel Tool Calls By default, MCP tools run sequentially — one at a time. If your MCP server exposes tools that are safe to run concurrently (e.g. read-only queries, independent API calls), you can opt-in to parallel execution: `yaml mcp_servers: docs: command: "docs-server" supports_parallel_tool_calls: true` When `supports_parallel_tool_calls` is `true`, Hermes may execute multiple tools from that server at the same time within a single tool-call batch, just like it does for built-in read-only tools (web_search, read_file, etc.). :::caution Only enable parallel calls for MCP servers whose tools are safe to run at the same time. If tools read and write shared state, files, databases, or external resources, review the read/write race conditions before enabling this setting. ::: ## MCP Sampling Support MCP servers can request LLM inference from Hermes via the `sampling/createMessage` protocol. This allows an MCP server to ask Hermes to generate text on its behalf — useful for servers that need LLM capabilities but don’t have their own model access. Sampling is enabled by default for all MCP servers (when the MCP SDK supports it). Configure it per-server under the `sampling` key: yaml mcp_servers: my_server: command: "my-mcp-server" sampling: enabled: true # Enable sampling (default: true) model: "openai/gpt-4o" # Override model for sampling requests (optional) max_tokens_cap: 4096 # Max tokens per sampling response (default: 4096) timeout: 30 # Timeout in seconds per request (default: 30) max_rpm: 10 # Rate limit: max requests per minute (default: 10) max_tool_rounds: 5 # Max tool-use rounds in sampling loops (default: 5) allowed_models: [] # Allowlist of model names the server may request (empty = any) log_level: "info" # Audit log level: debug, info, or warning (default: info) The sampling handler includes a sliding-window rate limiter, per-request timeouts, and tool-loop depth limits to prevent runaway usage. Metrics (request count, errors, tokens used) are tracked per server instance. To disable sampling for a specific server: `yaml mcp_servers: untrusted_server: url: "https://mcp.example.com" sampling: enabled: false` ## Running Hermes as an MCP server In addition to connecting to MCP servers, Hermes can also be an MCP server. This lets other MCP-capable agents (Claude Code, Cursor, Codex, or any MCP client) use Hermes’s messaging capabilities — list conversations, read message history, and send messages across all your connected platforms. ### When to use this - You want Claude Code, Cursor, or another coding agent to send and read Telegram/Discord/Slack messages through Hermes - You want a single MCP server that bridges to all of Hermes’s connected messaging platforms at once - You already have a running Hermes gateway with connected platforms ### Quick start `bash hermes mcp serve` This starts a stdio MCP server. The MCP client (not you) manages the process lifecycle. ### MCP client configuration Add Hermes to your MCP client config. For example, in Claude Code’s `~/.claude/claude_desktop_config.json`: `json { "mcpServers": { "hermes": { "command": "hermes", "args": ["mcp", "serve"] } } }` Or if you installed Hermes in a specific location: `json { "mcpServers": { "hermes": { "command": "/home/user/.hermes/hermes-agent/venv/bin/hermes", "args": ["mcp", "serve"] } } }` ### Available tools The MCP server exposes 10 tools, matching OpenClaw’s channel bridge surface plus a Hermes-specific channel browser: | Tool | Description | |——|———––| | `conversations_list` | List active messaging conversations. Filter by platform or search by name. | | `conversation_get` | Get detailed info about one conversation by session key. | | `messages_read` | Read recent message history for a conversation. | | `attachments_fetch` | Extract non-text attachments (images, media) from a specific message. | | `events_poll` | Poll for new conversation events since a cursor position. | | `events_wait` | Long-poll / block until the next event arrives (near-real-time). | | `messages_send` | Send a message through a platform (e.g. `telegram:123456`, `discord:#general`). | | `channels_list` | List available messaging targets across all platforms. | | `permissions_list_open` | List pending approval requests observed during this bridge session. | | `permissions_respond` | Allow or deny a pending approval request. | ### Event system The MCP server includes a live event bridge that polls Hermes’s session database for new messages. This gives MCP clients near-real-time awareness of incoming conversations: `# Poll for new events (non-blocking) events_poll(after_cursor=0) # Wait for next event (blocks up to timeout) events_wait(after_cursor=42, timeout_ms=30000)` Event types: `message`, `approval_requested`, `approval_resolved` The event queue is in-memory and starts when the bridge connects. Older messages are available through `messages_read`. ### Options `bash hermes mcp serve # Normal mode hermes mcp serve --verbose # Debug logging on stderr` ### How it works The MCP server reads conversation data directly from Hermes’s session store (`~/.hermes/sessions/sessions.json` and the SQLite database). A background thread polls the database for new messages and maintains an in-memory event queue. For sending messages, it uses the same `send_message` infrastructure as the Hermes agent itself. The gateway does NOT need to be running for read operations (listing conversations, reading history, polling events). It DOES need to be running for send operations, since the platform adapters need active connections. ### Current limits - The embedded `hermes mcp serve` exposes a stdio-only MCP server today. If you need an HTTP MCP server, run a separate adapter — or, much more commonly, use the MCP client side of Hermes, which already speaks both stdio and HTTP (`url` + `headers` in `mcp_servers.yaml` / `config.yaml`; see HTTP servers above). - Event polling at ~200ms intervals via mtime-optimized DB polling (skips work when files are unchanged) - No `claude/channel` push notification protocol yet - Text-only sends (no media/attachment sending through `messages_send`) ## Related docs - Use MCP with Hermes - CLI Commands - Slash Commands - FAQ — # ACP Editor Integration # ACP Editor Integration Hermes Agent can run as an ACP server, letting ACP-compatible editors talk to Hermes over stdio and render: - chat messages - tool activity - file diffs - terminal commands - approval prompts - streamed thinking / response chunks ACP is a good fit when you want Hermes to behave like an editor-native coding agent instead of a standalone CLI or messaging bot. ## What Hermes exposes in ACP mode Hermes runs with a curated `hermes-acp` toolset designed for editor workflows. It includes: - file tools: `read_file`, `write_file`, `patch`, `search_files` - terminal tools: `terminal`, `process` - web/browser tools - memory, todo, session search - skills - execute_code and delegate_task - vision It intentionally excludes things that do not fit typical editor UX, such as messaging delivery and cronjob management. ## Installation Install Hermes normally, then add the ACP extra: `bash pip install -e '.[acp]'` This installs the `agent-client-protocol` dependency and enables: - `hermes acp` - `hermes-acp` - `python -m acp_adapter` For Zed registry installs, Zed launches Hermes through the official ACP Registry entry. That entry uses a `uvx` distribution that runs: `bash uvx --from 'hermes-agent[acp]==<version>' hermes-acp` Make sure `uv` is available on `PATH` before using the registry install path. ## Launching the ACP server Any of the following starts Hermes in ACP mode: `bash hermes acp` `bash hermes-acp` `bash python -m acp_adapter` Hermes logs to stderr so stdout remains reserved for ACP JSON-RPC traffic. For non-interactive checks: `bash hermes acp --version hermes acp --check` ### Browser tools (optional) Browser tools (`browser_navigate`, `browser_click`, etc.) depend on the `agent-browser` npm package and Chromium, which aren’t part of the Python wheel. Install them with: `bash hermes acp --setup-browser # interactive (prompts before ~400 MB download) hermes acp --setup-browser --yes # accept the download non-interactively` This is the standalone command. The Zed registry’s terminal-auth flow (`hermes acp --setup`) also offers the browser bootstrap as a follow-up question after model selection, so most users never need to run `--setup-browser` directly. What it does: - Installs Node.js 22 LTS into `~/.hermes/node/` if missing - `npm install -g agent-browser @askjo/camofox-browser` into that prefix (no sudo needed — `npm`‘s `--prefix` points at the user-writable Hermes-managed Node) - Installs Playwright Chromium, or uses a detected system Chrome/Chromium when available The bootstrap is idempotent — re-running it is fast and skips work that’s already done. ## Editor setup ### VS Code Install the ACP Client extension. To connect: 1. Open the ACP Client panel from the Activity Bar. 2. Select Hermes Agent from the built-in agent list. 3. Connect and start chatting. If you want to define Hermes manually, add it through VS Code settings under `acp.agents`: `json { "acp.agents": { "Hermes Agent": { "command": "hermes", "args": ["acp"] } } }` ### Zed Zed v0.221.x and newer installs external agents through the official ACP Registry. 1. Open the Agent Panel. 2. Click Add Agent, or run the `zed: acp registry` command. 3. Search for Hermes Agent. 4. Install it and start a new Hermes external-agent thread. Prerequisites: - Configure Hermes provider credentials first with `hermes model`, or set them in `~/.hermes/.env` / `~/.hermes/config.yaml`. - Install `uv` so the registry launcher can run `uvx --from 'hermes-agent[acp]==<version>' hermes-acp`. For local development before the registry entry is available, use a custom agent server in Zed settings: `json { "agent_servers": { "hermes-agent": { "type": "custom", "command": "hermes", "args": ["acp"] } } }` ### JetBrains Use an ACP-compatible plugin and point it at: `text /path/to/hermes-agent/acp_registry` ## Registry manifest The source copy of Hermes’ official ACP Registry metadata lives at: `text acp_registry/agent.json acp_registry/icon.svg` The upstream registry PR copies those files into the top-level `hermes-agent/` directory in `agentclientprotocol/registry`. The registry entry uses a `uvx` distribution that points directly at the `hermes-agent` PyPI release: `text uvx --from 'hermes-agent[acp]==<version>' hermes-acp` The registry CI verifies that the pinned version exists on PyPI, so the manifest’s `version` and uvx `package` pin must always match `pyproject.toml`. `scripts/release.py` keeps them in lockstep automatically. ## Configuration and credentials ACP mode uses the same Hermes configuration as the CLI: - `~/.hermes/.env` - `~/.hermes/config.yaml` - `~/.hermes/skills/` - `~/.hermes/state.db` Provider resolution uses Hermes’ normal runtime resolver, so ACP inherits the currently configured provider and credentials. Hermes also advertises a terminal auth method (`--setup`) for first-run registry clients; this opens Hermes’ interactive model/provider setup. ## Session behavior ACP sessions are tracked by the ACP adapter’s in-memory session manager while the server is running. Each session stores: - session ID - working directory - selected model - current conversation history - cancel event The underlying `AIAgent` still uses Hermes’ normal persistence/logging paths, but ACP `list/load/resume/fork` are scoped to the currently running ACP server process. ## Working directory behavior ACP sessions bind the editor’s cwd to the Hermes task ID so file and terminal tools run relative to the editor workspace, not the server process cwd. ## Approvals Dangerous terminal commands can be routed back to the editor as approval prompts. ACP approval options are simpler than the CLI flow: - allow once - allow always - deny On timeout or error, the approval bridge denies the request. ### Session-scoped edit auto-approval ACP exposes a third tier between allow once and allow always: Allow for session. Picking it from the editor’s permission prompt records the approval inside the current ACP session only — every subsequent matching command in that session goes through without prompting, but a new ACP session (or restarting the editor) resets the slate and re-prompts the first time. | Option | Editor label | Scope | Persisted across restarts | |—|—|—|—| | `allow_once` | Allow once | This one tool call | No | | `allow_session` | Allow for session | All matching calls in this ACP session | No — cleared when the session ends | | `allow_always` | Allow always | All future sessions | Yes (written to the Hermes permanent allowlist) | | `deny` | Deny | This one tool call | No | `allow_session` is the right default for an editor workflow where you trust an agent for the duration of a task but don’t want to grant a long-lived allowlist entry. The safety trade-off is straightforward: the broader the scope, the less the editor will interrupt you, and the more damage a misbehaving agent (or prompt injection) can do before you notice. Start with `allow_once` for unfamiliar commands; promote to `allow_session` once you’ve seen the agent run the same pattern correctly a few times; reserve `allow_always` for truly idempotent commands you trust forever (e.g. `git status`). The ACP bridge maps these options onto Hermes’ internal approval semantics — `allow_always` writes a permanent allowlist entry the same way the CLI does, while `allow_session` only affects the in-process approval cache for the current ACP session. ## Troubleshooting ### ACP agent does not appear in the editor Check: - In Zed, open the ACP Registry with `zed: acp registry` and search for Hermes Agent. - For manual/local development, verify the custom `agent_servers` command points to `hermes acp`. - Hermes is installed and on your PATH. - The ACP extra is installed (`pip install -e '.[acp]'`). - `uv` is installed if launching from the official Zed registry entry. ### ACP starts but immediately errors Try these checks: `bash hermes acp --version hermes acp --check hermes doctor hermes status` ### Missing credentials ACP mode uses Hermes’ existing provider setup. Configure credentials with: `bash hermes model` or by editing `~/.hermes/.env`. Registry clients can also trigger Hermes’ terminal auth flow, which runs the same interactive provider/model setup. ### Zed registry launcher cannot find uv Install `uv` from the official uv installation docs, then retry the Hermes Agent thread from Zed. ## See also - ACP Internals - Provider Runtime Resolution - Tools Runtime — # API Server # API Server The API server exposes hermes-agent as an OpenAI-compatible HTTP endpoint. Any frontend that speaks the OpenAI format — Open WebUI, LobeChat, LibreChat, NextChat, ChatBox, and hundreds more — can connect to hermes-agent and use it as a backend. Your agent handles requests with its full toolset (terminal, file operations, web search, memory, skills) and returns the final response. When streaming, tool progress indicators appear inline so frontends can show what the agent is doing. :::tip One backend covers models + tools Hermes itself needs a configured provider and tool backends for the API server to be useful. A Nous Portal subscription handles both — 300+ models plus web/image/TTS/browser via the Tool Gateway. Run `hermes setup --portal` once before starting the API server and frontends like Open WebUI or LobeChat get a fully tool-equipped backend. ::: ## Quick Start ### 1. Enable the API server Add to `~/.hermes/.env`: `bash API_SERVER_ENABLED=true API_SERVER_KEY=change-me-local-dev # Optional: only if a browser must call Hermes directly # API_SERVER_CORS_ORIGINS=http://localhost:3000` ### 2. Start the gateway `bash hermes gateway` You’ll see: `[API Server] API server listening on http://127.0.0.1:8642` ### 3. Connect a frontend Point any OpenAI-compatible client at `http://localhost:8642/v1`: `bash # Test with curl curl http://localhost:8642/v1/chat/completions \ -H "Authorization: Bearer change-me-local-dev" \ -H "Content-Type: application/json" \ -d '{"model": "hermes-agent", "messages": [{"role": "user", "content": "Hello!"}]}'` Or connect Open WebUI, LobeChat, or any other frontend — see the Open WebUI integration guide for step-by-step instructions. ## Endpoints ### POST /v1/chat/completions Standard OpenAI Chat Completions format. Stateless — the full conversation is included in each request via the `messages` array. Request: `json { "model": "hermes-agent", "messages": [ {"role": "system", "content": "You are a Python expert."}, {"role": "user", "content": "Write a fibonacci function"} ], "stream": false }` Response: `json { "id": "chatcmpl-abc123", "object": "chat.completion", "created": 1710000000, "model": "hermes-agent", "choices": [{ "index": 0, "message": {"role": "assistant", "content": "Here's a fibonacci function..."}, "finish_reason": "stop" }], "usage": {"prompt_tokens": 50, "completion_tokens": 200, "total_tokens": 250} }` Inline image input: user messages may send `content` as an array of `text` and `image_url` parts. Both remote `http(s)` URLs and `data:image/...` URLs are supported: `json { "model": "hermes-agent", "messages": [ { "role": "user", "content": [ {"type": "text", "text": "What is in this image?"}, {"type": "image_url", "image_url": {"url": "https://example.com/cat.png", "detail": "high"}} ] } ] }` Uploaded files (`file` / `input_file` / `file_id`) and non-image `data:` URLs return `400 unsupported_content_type`. Streaming (`"stream": true`): Returns Server-Sent Events (SSE) with token-by-token response chunks. For Chat Completions, the stream uses standard `chat.completion.chunk` events plus Hermes’ custom `hermes.tool.progress` event for tool-start UX. For Responses, the stream uses OpenAI Responses event types such as `response.created`, `response.output_text.delta`, `response.output_item.added`, `response.output_item.done`, and `response.completed`. Tool progress in streams: - Chat Completions: Hermes emits `event: hermes.tool.progress` for tool-start visibility without polluting persisted assistant text. - Responses: Hermes emits spec-native `function_call` and `function_call_output` output items during the SSE stream, so clients can render structured tool UI in real time. ### POST /v1/responses OpenAI Responses API format. Supports server-side conversation state via `previous_response_id` — the server stores full conversation history (including tool calls and results) so multi-turn context is preserved without the client managing it. Request: `json { "model": "hermes-agent", "input": "What files are in my project?", "instructions": "You are a helpful coding assistant.", "store": true }` Response: `json { "id": "resp_abc123", "object": "response", "status": "completed", "model": "hermes-agent", "output": [ {"type": "function_call", "name": "terminal", "arguments": "{\"command\": \"ls\"}", "call_id": "call_1"}, {"type": "function_call_output", "call_id": "call_1", "output": "README.md src/ tests/"}, {"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "Your project has..."}]} ], "usage": {"input_tokens": 50, "output_tokens": 200, "total_tokens": 250} }` Inline image input: `input[].content` can contain `input_text` and `input_image` parts. Both remote URLs and `data:image/...` URLs are supported: `json { "model": "hermes-agent", "input": [ { "role": "user", "content": [ {"type": "input_text", "text": "Describe this screenshot."}, {"type": "input_image", "image_url": "data:image/png;base64,iVBORw0K..."} ] } ] }` Uploaded files (`input_file` / `file_id`) and non-image `data:` URLs return `400 unsupported_content_type`. #### Multi-turn with previous_response_id Chain responses to maintain full context (including tool calls) across turns: `json { "input": "Now show me the README", "previous_response_id": "resp_abc123" }` The server reconstructs the full conversation from the stored response chain — all previous tool calls and results are preserved. Chained requests also share the same session, so multi-turn conversations appear as a single entry in the dashboard and session history. #### Named conversations Use the `conversation` parameter instead of tracking response IDs: `json {"input": "Hello", "conversation": "my-project"} {"input": "What's in src/?", "conversation": "my-project"} {"input": "Run the tests", "conversation": "my-project"}` The server automatically chains to the latest response in that conversation. Like the `/title` command for gateway sessions. ### GET /v1/responses/{id} Retrieve a previously stored response by ID. ### DELETE /v1/responses/{id} Delete a stored response. ### GET /v1/models Lists the agent as an available model. The advertised model name defaults to the profile name (or `hermes-agent` for the default profile). Required by most frontends for model discovery. ### GET /v1/capabilities Returns a machine-readable description of the API server’s stable surface for external UIs, orchestrators, and plugin bridges. `json { "object": "hermes.api_server.capabilities", "platform": "hermes-agent", "model": "hermes-agent", "auth": {"type": "bearer", "required": true}, "features": { "chat_completions": true, "responses_api": true, "run_submission": true, "run_status": true, "run_events_sse": true, "run_stop": true } }` Use this endpoint when integrating dashboards, browser UIs, or control planes so they can discover whether the running Hermes version supports runs, streaming, cancellation, and session continuity without depending on private Python internals. ### GET /health Health check. Returns `{"status": "ok"}`. Also available at GET /v1/health for OpenAI-compatible clients that expect the `/v1/` prefix. ### GET /health/detailed Extended health check that also reports active sessions, running agents, and resource usage. Useful for monitoring/observability tooling. ## Runs API (streaming-friendly alternative) In addition to `/v1/chat/completions` and `/v1/responses`, the server exposes a runs API for long-form sessions where the client wants to subscribe to progress events instead of managing streaming themselves. ### POST /v1/runs Create a new agent run. Returns a `run_id` that can be used to subscribe to progress events. `json { "run_id": "run_abc123", "status": "started" }` Runs accept a simple `input` string and optional `session_id`, `instructions`, `conversation_history`, or `previous_response_id`. When `session_id` is provided, Hermes surfaces it in the run status so external UIs can correlate runs with their own conversation IDs. ### GET /v1/runs/{run_id} Poll the current run state. This is useful for dashboards that need status without holding an SSE connection open, or for UIs that reconnect after navigation. `json { "object": "hermes.run", "run_id": "run_abc123", "status": "completed", "session_id": "space-session", "model": "hermes-agent", "output": "Done.", "usage": {"input_tokens": 50, "output_tokens": 200, "total_tokens": 250} }` Statuses are retained briefly after terminal states (`completed`, `failed`, or `cancelled`) for polling and UI reconciliation. ### GET /v1/runs/{run_id}/events Server-Sent Events stream of the run’s tool-call progress, token deltas, and lifecycle events. Designed for dashboards and thick clients that want to attach/detach without losing state. ### POST /v1/runs/{run_id}/stop Interrupt a running agent turn. The endpoint returns immediately with `{"status": "stopping"}` while Hermes asks the active agent to stop at the next safe interruption point. ### POST /v1/runs/{run_id}/approval Resolve a pending approval for a run that is waiting on a human decision (for example, a tool call gated behind an approval policy). The body carries the approval decision; the run resumes once the decision is recorded. This endpoint is advertised in `/v1/capabilities` as the `run_approval` feature so external UIs can detect support before surfacing an approval prompt. ## Jobs API (background scheduled work) The server exposes a lightweight jobs CRUD surface for managing scheduled / background agent runs from a remote client. All endpoints are gated behind the same bearer auth. ### GET /api/jobs List all scheduled jobs. ### POST /api/jobs Create a new scheduled job. Body accepts the same shape as `hermes cron` — prompt, schedule, skills, provider override, delivery target. ### GET /api/jobs/{job_id} Fetch a single job’s definition and last-run state. ### PATCH /api/jobs/{job_id} Update fields on an existing job (prompt, schedule, etc.). Partial updates are merged. ### DELETE /api/jobs/{job_id} Remove a job. Also cancels any in-flight run. ### POST /api/jobs/{job_id}/pause Pause a job without deleting it. Next-scheduled-run timestamps are suspended until resumed. ### POST /api/jobs/{job_id}/resume Resume a previously paused job. ### POST /api/jobs/{job_id}/run Trigger the job to run immediately, out of schedule. ## Sessions API (session control over REST) External UIs can manage Hermes sessions over REST without standing up the dashboard. All endpoints are gated by `API_SERVER_KEY` and live under `/api/sessions/`. | Method | Path | Description | |––––|——|———––| | `GET` | `/api/sessions` | List sessions (paginated — `limit`, `offset`, `source`, `include_children`) | | `POST` | `/api/sessions` | Create an empty session | | `GET` | `/api/sessions/{id}` | Read session metadata | | `PATCH` | `/api/sessions/{id}` | Update title or `end_reason` | | `DELETE` | `/api/sessions/{id}` | Delete a session | | `GET` | `/api/sessions/{id}/messages` | Message history for a session | | `POST` | `/api/sessions/{id}/fork` | Branch the session via `SessionDB` lineage (matches CLI `/branch` semantics) | | `POST` | `/api/sessions/{id}/chat` | Run one synchronous agent turn | | `POST` | `/api/sessions/{id}/chat/stream` | SSE wrapper over a single turn — emits `assistant.delta`, `tool.started`, `tool.completed`, `run.completed` events | `/v1/capabilities` advertises the full surface via `session_` feature flags and `endpoints.session_` entries so external UIs can detect support and fall back safely. Inline images are supported in `chat` and `chat/stream` payloads (multimodal-aware path). `bash # fork a session and run one turn curl -X POST http://localhost:8642/api/sessions/$ID/fork \ -H "Authorization: Bearer $API_SERVER_KEY" \ -d '{"title": "explore alt path"}' # stream a turn over SSE curl -N -X POST http://localhost:8642/api/sessions/$ID/chat/stream \ -H "Authorization: Bearer $API_SERVER_KEY" \ -d '{"input": "what files changed in the last hour?"}'` ## Skills and toolsets discovery `GET /v1/skills` and `GET /v1/toolsets` let external clients enumerate the agent’s capabilities deterministically over REST instead of asking the model. Both are read-only and gated by `API_SERVER_KEY`. `bash curl http://localhost:8642/v1/skills \ -H "Authorization: Bearer $API_SERVER_KEY" # → [{"name": "github-pr-workflow", "description": "...", "category": "..."}, ...] curl http://localhost:8642/v1/toolsets \ -H "Authorization: Bearer $API_SERVER_KEY" # → [{"name": "core", "label": "...", "description": "...", "enabled": true, # "configured": true, "tools": ["read_file", "write_file", ...]}, ...]` `/v1/skills` returns the same metadata the skills hub uses internally. `/v1/toolsets` returns toolsets resolved for the `api_server` platform with the concrete `tools` list each one expands to. Both are advertised under `endpoints.` in `/v1/capabilities`. ## Long-term memory scoping (`X-Hermes-Session-Key`) Multi-user frontends like Open WebUI need a stable per-channel identifier for long-term memory (Honcho, etc.) that is independent of the transcript-scoped `X-Hermes-Session-Id` (which rotates on `/new`). Pass `X-Hermes-Session-Key` on `/v1/chat/completions`, `/v1/responses`, or `/v1/runs` and Hermes threads it through to `AIAgent(gateway_session_key=...)`, where the Honcho memory provider uses it to derive a stable scope. `http POST /v1/chat/completions HTTP/1.1 Authorization: Bearer * X-Hermes-Session-Id: transcript-alpha X-Hermes-Session-Key: agent:main:webui:dm:user-42` Rules: max 256 chars, control characters (`\r`, `\n`, `\x00`) are rejected, and the value is echoed back on responses (JSON + SSE). `/v1/capabilities` advertises support via `"session_key_header": "X-Hermes-Session-Key"`. Without the key, Honcho’s `per-session` strategy produces a different scope per `session_id` — exactly the behavior Hermes had before. ## System Prompt Handling When a frontend sends a `system` message (Chat Completions) or `instructions` field (Responses API), hermes-agent layers it on top of its core system prompt. Your agent keeps all its tools, memory, and skills — the frontend’s system prompt adds extra instructions. This means you can customize behavior per-frontend without losing capabilities: - Open WebUI system prompt: “You are a Python expert. Always include type hints.” - The agent still has terminal, file tools, web search, memory, etc. ## Authentication Bearer token auth via the `Authorization` header: `Authorization: Bearer ` Configure the key via `API_SERVER_KEY` env var. If you need a browser to call Hermes directly, also set `API_SERVER_CORS_ORIGINS` to an explicit allowlist. :::warning Security The API server gives full access to hermes-agent’s toolset, including terminal commands. `API_SERVER_KEY` is required for every deployment, including the default loopback bind on `127.0.0.1`. Keep `API_SERVER_CORS_ORIGINS` narrow to control browser access when you explicitly allow browser callers. ::: ## Configuration ### Environment Variables | Variable | Default | Description | |–––––|———|———––| | `API_SERVER_ENABLED` | `false` | Enable the API server | | `API_SERVER_PORT` | `8642` | HTTP server port | | `API_SERVER_HOST` | `127.0.0.1` | Bind address (localhost only by default) | | `API_SERVER_KEY` | (required)* | Bearer token for auth | | `API_SERVER_CORS_ORIGINS` | (none) | Comma-separated allowed browser origins | | `API_SERVER_MODEL_NAME` | (profile name) | Model name on `/v1/models`. Defaults to profile name, or `hermes-agent` for default profile. | ### config.yaml `yaml # Not yet supported — use environment variables. # config.yaml support coming in a future release.` ## Security Headers All responses include security headers: - `X-Content-Type-Options: nosniff` — prevents MIME type sniffing - `Referrer-Policy: no-referrer` — prevents referrer leakage ## CORS The API server does not enable browser CORS by default. For direct browser access, set an explicit allowlist: `bash API_SERVER_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000` When CORS is enabled: - Preflight responses include `Access-Control-Max-Age: 600` (10 minute cache) - SSE streaming responses include CORS headers so browser EventSource clients work correctly - `Idempotency-Key` is an allowed request header — clients can send it for deduplication (responses are cached by key for 5 minutes) Most documented frontends such as Open WebUI connect server-to-server and do not need CORS at all. ## Compatible Frontends Any frontend that supports the OpenAI API format works. Tested/documented integrations: | Frontend | Stars | Connection | |–––––|—––|————| | Open WebUI | 126k | Full guide available | | LobeChat | 73k | Custom provider endpoint | | LibreChat | 34k | Custom endpoint in librechat.yaml | | AnythingLLM | 56k | Generic OpenAI provider | | NextChat | 87k | BASE_URL env var | | ChatBox | 39k | API Host setting | | Jan | 26k | Remote model config | | HF Chat-UI | 8k | OPENAI_BASE_URL | | big-AGI | 7k | Custom endpoint | | OpenAI Python SDK | — | `OpenAI(base_url="http://localhost:8642/v1")` | | curl | — | Direct HTTP requests | ## Multi-User Setup with Profiles To give multiple users their own isolated Hermes instance (separate config, memory, skills), use profiles: bash # Create a profile per user hermes profile create alice hermes profile create bob # Configure each profile's API server on a different port. API_SERVER_* are env # vars (not config.yaml keys), so write them to each profile's .env: cat >> ~/.hermes/profiles/alice/.env <<EOF API_SERVER_ENABLED=true API_SERVER_PORT=8643 API_SERVER_KEY=alice-secret EOF cat >> ~/.hermes/profiles/bob/.env <<EOF API_SERVER_ENABLED=true API_SERVER_PORT=8644 API_SERVER_KEY=bob-secret EOF # Start each profile's gateway hermes -p alice gateway & hermes -p bob gateway & Each profile’s API server automatically advertises the profile name as the model ID: - `http://localhost:8643/v1/models` → model `alice` - `http://localhost:8644/v1/models` → model `bob` In Open WebUI, add each as a separate connection. The model dropdown shows `alice` and `bob` as distinct models, each backed by a fully isolated Hermes instance. See the Open WebUI guide for details. ## Limitations - Response storage — stored responses (for `previous_response_id`) are persisted in SQLite and survive gateway restarts. Max 100 stored responses (LRU eviction). - No file upload — inline images are supported on both `/v1/chat/completions` and `/v1/responses`, but uploaded files (`file`, `input_file`, `file_id`) and non-image document inputs are not supported through the API. - Model field is cosmetic — the `model` field in requests is accepted but the actual LLM model used is configured server-side in config.yaml. ## Proxy Mode The API server also serves as the backend for gateway proxy mode. When another Hermes gateway instance is configured with `GATEWAY_PROXY_URL` pointing at this API server, it forwards all messages here instead of running its own agent. This enables split deployments — for example, a Docker container handling Matrix E2EE that relays to a host-side agent. See Matrix Proxy Mode for the full setup guide. — # Honcho Memory # Honcho Memory Honcho is an AI-native memory backend that adds dialectic reasoning and deep user modeling on top of Hermes’s built-in memory system. Instead of simple key-value storage, Honcho maintains a running model of who the user is — their preferences, communication style, goals, and patterns — by reasoning about conversations after they happen. :::info Honcho is a Memory Provider Plugin Honcho is integrated into the Memory Providers system. All features below are available through the unified memory provider interface. ::: ## What Honcho Adds | Capability | Built-in Memory | Honcho | |———–|––––––––|––––| | Cross-session persistence | ✔ File-based MEMORY.md/USER.md | ✔ Server-side with API | | User profile | ✔ Manual agent curation | ✔ Automatic dialectic reasoning | | Session summary | — | ✔ Session-scoped context injection | | Multi-agent isolation | — | ✔ Per-peer profile separation | | Observation modes | — | ✔ Unified or directional observation | | Conclusions (derived insights) | — | ✔ Server-side reasoning about patterns | | Search across history | ✔ FTS5 session search | ✔ Semantic search over conclusions | Dialectic reasoning: After each conversation turn (gated by `dialecticCadence`), Honcho analyzes the exchange and derives insights about the user’s preferences, habits, and goals. These accumulate over time, giving the agent a deepening understanding that goes beyond what the user explicitly stated. The dialectic supports multi-pass depth (1–3 passes) with automatic cold/warm prompt selection — cold start queries focus on general user facts while warm queries prioritize session-scoped context. Session-scoped context: Base context now includes the session summary alongside the user representation and peer card. This gives the agent awareness of what has already been discussed in the current session, reducing repetition and enabling continuity. Multi-agent profiles: When multiple Hermes instances talk to the same user (e.g., a coding assistant and a personal assistant), Honcho maintains separate “peer” profiles. Each peer sees only its own observations and conclusions, preventing cross-contamination of context. ## Setup `bash hermes memory setup # select "honcho" from the provider list` Or configure manually: `yaml # ~/.hermes/config.yaml memory: provider: honcho` `bash echo 'HONCHO_API_KEY=*' >> ~/.hermes/.env` Get an API key at honcho.dev. ## Architecture ### Two-Layer Context Injection Every turn (in `hybrid` or `context` mode), Honcho assembles two layers of context injected into the system prompt: 1. Base context — session summary, user representation, user peer card, AI self-representation, and AI identity card. Refreshed on `contextCadence`. This is the “who is this user” layer. 2. Dialectic supplement — LLM-synthesized reasoning about the user’s current state and needs. Refreshed on `dialecticCadence`. This is the “what matters right now” layer. Both layers are concatenated and truncated to the `contextTokens` budget (if set). ### Cold/Warm Prompt Selection The dialectic automatically selects between two prompt strategies: - Cold start (no base context yet): General query — “Who is this person? What are their preferences, goals, and working style?” - Warm session (base context exists): Session-scoped query — “Given what’s been discussed in this session so far, what context about this user is most relevant?” This happens automatically based on whether base context has been populated. ### Three Orthogonal Config Knobs Cost and depth are controlled by three independent knobs: | Knob | Controls | Default | |——|–––––|———| | `contextCadence` | Turns between `context()` API calls (base layer refresh) | `1` | | `dialecticCadence` | Turns between `peer.chat()` LLM calls (dialectic layer refresh) | `2` (recommended 1–5) | | `dialecticDepth` | Number of `.chat()` passes per dialectic invocation (1–3) | `1` | These are orthogonal — you can have frequent context refreshes with infrequent dialectic, or deep multi-pass dialectic at low frequency. Example: `contextCadence: 1, dialecticCadence: 5, dialecticDepth: 2` refreshes base context every turn, runs dialectic every 5 turns, and each dialectic run makes 2 passes. ### Dialectic Depth (Multi-Pass) When `dialecticDepth` > 1, each dialectic invocation runs multiple `.chat()` passes: - Pass 0: Cold or warm prompt (see above) - Pass 1: Self-audit — identifies gaps in the initial assessment and synthesizes evidence from recent sessions - Pass 2: Reconciliation — checks for contradictions between prior passes and produces a final synthesis Each pass uses a proportional reasoning level (lighter early passes, base level for the main pass). Override per-pass levels with `dialecticDepthLevels` — e.g., `["minimal", "medium", "high"]` for a depth-3 run. Passes bail out early if the prior pass returned strong signal (long, structured output), so depth 3 doesn’t always mean 3 LLM calls. ### Session-Start Prewarm On session init, Honcho fires a dialectic call in the background at the full configured `dialecticDepth` and hands the result directly to turn 1’s context assembly. A single-pass prewarm on a cold peer often returns thin output — multi-pass depth runs the audit/reconcile cycle before the user ever speaks. If prewarm hasn’t landed by turn 1, turn 1 falls back to a synchronous call with a bounded timeout. ### Query-Adaptive Reasoning Level The auto-injected dialectic scales `dialecticReasoningLevel` by query length: +1 level at ≥120 chars, +2 at ≥400, clamped at `reasoningLevelCap` (default `"high"`). Disable with `reasoningHeuristic: false` to pin every auto call to `dialecticReasoningLevel`. Available levels: `minimal`, `low`, `medium`, `high`, `max`. ## Configuration Options Honcho is configured in `~/.honcho/config.json` (global) or `$HERMES_HOME/honcho.json` (profile-local). The setup wizard handles this for you. ### Self-Hosted Honcho with Authentication When pointing Hermes at a self-hosted Honcho server, `hermes honcho setup` (and `hermes memory setup`) ask for a local JWT / bearer token after the base URL. Paste a JWT signed with the server’s `AUTH_JWT_SECRET` (the Honcho compose env var) to enable authenticated access; leave it blank for servers running with `AUTH_USE_AUTH=false`. The local token is stored under the host block (`hosts.<host>.apiKey` in `honcho.json`), separate from any cloud `apiKey`, so you can flip the `Cloud or local?` prompt back to `cloud` later without losing either credential. ### Full Config Reference | Key | Default | Description | |—–|———|———––| | `contextTokens` | `null` (uncapped) | Token budget for auto-injected context per turn. Set to an integer (e.g. 1200) to cap. Truncates at word boundaries | | `contextCadence` | `1` | Minimum turns between `context()` API calls (base layer refresh) | | `dialecticCadence` | `2` | Minimum turns between `peer.chat()` LLM calls (dialectic layer). Recommended 1–5. In `tools` mode, irrelevant — model calls explicitly | | `dialecticDepth` | `1` | Number of `.chat()` passes per dialectic invocation. Clamped to 1–3 | | `dialecticDepthLevels` | `null` | Optional array of reasoning levels per pass, e.g. `["minimal", "low", "medium"]`. Overrides proportional defaults | | `dialecticReasoningLevel` | `'low'` | Base reasoning level: `minimal`, `low`, `medium`, `high`, `max` | | `dialecticDynamic` | `true` | When `true`, model can override reasoning level per-call via tool param | | `dialecticMaxChars` | `600` | Max chars of dialectic result injected into system prompt | | `recallMode` | `'hybrid'` | `hybrid` (auto-inject + tools), `context` (inject only), `tools` (tools only) | | `writeFrequency` | `'async'` | When to flush messages: `async` (background thread), `turn` (sync), `session` (batch on end), or integer N | | `saveMessages` | `true` | Whether to persist messages to Honcho API | | `observationMode` | `'directional'` | `directional` (all on) or `unified` (shared pool). Override with `observation` object for granular control | | `messageMaxChars` | `25000` | Max chars per message sent via `add_messages()`. Chunked if exceeded | | `dialecticMaxInputChars` | `10000` | Max chars for dialectic query input to `peer.chat()` | | `sessionStrategy` | `'per-directory'` | `per-directory`, `per-repo`, `per-session`, or `global` | Session strategy controls how Honcho sessions map to your work: - `per-session` — each `hermes` run gets a fresh session. Clean starts, memory via tools. Recommended for new users. - `per-directory` — one Honcho session per working directory. Context accumulates across runs. - `per-repo` — one session per git repository. - `global` — single session across all directories. Recall mode controls how memory flows into conversations: - `hybrid` — context auto-injected into system prompt AND tools available (model decides when to query). - `context` — auto-injection only, tools hidden. - `tools` — tools only, no auto-injection. Agent must explicitly call `honcho_reasoning`, `honcho_search`, etc. Settings per recall mode: | Setting | `hybrid` | `context` | `tools` | |———|–––––|———–|———| | `writeFrequency` | flushes messages | flushes messages | flushes messages | | `contextCadence` | gates base context refresh | gates base context refresh | irrelevant — no injection | | `dialecticCadence` | gates auto LLM calls | gates auto LLM calls | irrelevant — model calls explicitly | | `dialecticDepth` | multi-pass per invocation | multi-pass per invocation | irrelevant — model calls explicitly | | `contextTokens` | caps injection | caps injection | irrelevant — no injection | | `dialecticDynamic` | gates model override | N/A (no tools) | gates model override | In `tools` mode, the model is fully in control — it calls `honcho_reasoning` when it wants, at whatever `reasoning_level` it picks. Cadence and budget settings only apply to modes with auto-injection (`hybrid` and `context`). ## Observation (Directional vs. Unified) Honcho models a conversation as peers exchanging messages. Each peer has two observation toggles that map 1:1 to Honcho’s `SessionPeerConfig`: | Toggle | Effect | |––––|––––| | `observeMe` | Honcho builds a representation of this peer from its own messages | | `observeOthers` | This peer observes the other peer’s messages (feeds cross-peer reasoning) | Two peers × two toggles = four flags. `observationMode` is a shorthand preset: | Preset | User flags | AI flags | Semantics | |––––|———–|–––––|———–| | `"directional"` (default) | me: on, others: on | me: on, others: on | Full mutual observation. Enables cross-peer dialectic — “what does the AI know about the user, based on what the user said and the AI replied.” | | `"unified"` | me: on, others: off | me: off, others: on | Shared-pool semantics — the AI observes the user’s messages only, the user peer only self-models. Single-observer pool. | Override the preset with an explicit `observation` block for per-peer control: `json "observation": { "user": { "observeMe": true, "observeOthers": true }, "ai": { "observeMe": true, "observeOthers": false } }` Common patterns: | Intent | Config | |––––|––––| | Full observation (most users) | `"observationMode": "directional"` | | AI shouldn’t re-model the user from its own replies | `"ai": {"observeMe": true, "observeOthers": false}` | | Strong persona the AI peer shouldn’t update from self-observation | `"ai": {"observeMe": false, "observeOthers": true}` | Server-side toggles set via the Honcho dashboard win over local defaults — Hermes syncs them back at session init. ## Tools When Honcho is active as the memory provider, five tools become available: | Tool | Purpose | |——|———| | `honcho_profile` | Read or update peer card — pass `card` (list of facts) to update, omit to read | | `honcho_search` | Semantic search over context — raw excerpts, no LLM synthesis | | `honcho_context` | Full session context — summary, representation, card, recent messages | | `honcho_reasoning` | Synthesized answer from Honcho’s LLM — pass `reasoning_level` (minimal/low/medium/high/max) to control depth | | `honcho_conclude` | Create or delete conclusions — pass `conclusion` to create, `delete_id` to remove (PII only) | ## CLI Commands The `hermes honcho` subcommand is only registered when Honcho is the active memory provider (`memory.provider: honcho` in `config.yaml`). On a fresh install, configure Honcho directly with `hermes memory setup honcho` (or run `hermes memory setup` and pick it from the list); the `hermes honcho` subcommand then appears on the next invocation. bash hermes memory setup honcho # Configure Honcho directly (works before activation) hermes honcho status # Connection status, config, and key settings hermes honcho setup # Redirects to `hermes memory setup` (post-activation alias) hermes honcho strategy # Show or set session strategy (per-session/per-directory/per-repo/global) hermes honcho peer # Show or update peer names + dialectic reasoning level hermes honcho mode # Show or set recall mode (hybrid/context/tools) hermes honcho tokens # Show or set token budget for context and dialectic hermes honcho identity # Seed or show the AI peer's Honcho identity hermes honcho sync # Sync Honcho config to all existing profiles hermes honcho peers # Show peer identities across all profiles hermes honcho sessions # List known Honcho session mappings hermes honcho map # Map current directory to a Honcho session name hermes honcho enable # Enable Honcho for the active profile hermes honcho disable # Disable Honcho for the active profile hermes honcho migrate # Step-by-step migration guide from openclaw-honcho ## Migrating from `hermes honcho` If you previously used the standalone `hermes honcho setup`: 1. Your existing configuration (`honcho.json` or `~/.honcho/config.json`) is preserved 2. Your server-side data (memories, conclusions, user profiles) is intact 3. Set `memory.provider: honcho` in config.yaml to reactivate No re-login or re-setup needed. Run `hermes memory setup` and select “honcho” — the wizard detects your existing config. ## Full Documentation See Memory Providers — Honcho for the complete reference. — # user-guide/features/provider-routing # Provider Routing When using OpenRouter as your LLM provider, Hermes Agent supports provider routing — fine-grained control over which underlying AI providers handle your requests and how they’re prioritized. OpenRouter routes requests to many providers (e.g., Anthropic, Google, AWS Bedrock, Together AI). Provider routing lets you optimize for cost, speed, quality, or enforce specific provider requirements. :::tip Traffic routed through Nous Portal still respects per-model routing and priority configs — and Portal subscribers get 10% off token-billed providers. ::: ## Configuration Add a `provider_routing` section to your `~/.hermes/config.yaml`: `yaml provider_routing: sort: "price" # How to rank providers only: [] # Whitelist: only use these providers ignore: [] # Blacklist: never use these providers order: [] # Explicit provider priority order require_parameters: false # Only use providers that support all parameters data_collection: null # Control data collection ("allow" or "deny")` :::info Provider routing only applies when using OpenRouter. It has no effect with direct provider connections (e.g., connecting directly to the Anthropic API). ::: ## Options ### `sort` Controls how OpenRouter ranks available providers for your request. | Value | Description | |—––|———––| | `"price"` | Cheapest provider first | | `"throughput"` | Fastest tokens-per-second first | | `"latency"` | Lowest time-to-first-token first | `yaml provider_routing: sort: "price"` ### `only` Whitelist of provider names. When set, only these providers will be used. All others are excluded. `yaml provider_routing: only: - "Anthropic" - "Google"` ### `ignore` Blacklist of provider names. These providers will never be used, even if they offer the cheapest or fastest option. `yaml provider_routing: ignore: - "Together" - "DeepInfra"` ### `order` Explicit priority order. Providers listed first are preferred. Unlisted providers are used as fallbacks. `yaml provider_routing: order: - "Anthropic" - "Google" - "AWS Bedrock"` ### `require_parameters` When `true`, OpenRouter will only route to providers that support all parameters in your request (like `temperature`, `top_p`, `tools`, etc.). This avoids silent parameter drops. `yaml provider_routing: require_parameters: true` ### `data_collection` Controls whether providers can use your prompts for training. Options are `"allow"` or `"deny"`. `yaml provider_routing: data_collection: "deny"` ## Practical Examples ### Optimize for Cost Route to the cheapest available provider. Good for high-volume usage and development: `yaml provider_routing: sort: "price"` ### Optimize for Speed Prioritize low-latency providers for interactive use: `yaml provider_routing: sort: "latency"` ### Optimize for Throughput Best for long-form generation where tokens-per-second matters: `yaml provider_routing: sort: "throughput"` ### Lock to Specific Providers Ensure all requests go through a specific provider for consistency: `yaml provider_routing: only: - "Anthropic"` ### Avoid Specific Providers Exclude providers you don’t want to use (e.g., for data privacy): `yaml provider_routing: ignore: - "Together" - "Lepton" data_collection: "deny"` ### Preferred Order with Fallbacks Try your preferred providers first, fall back to others if unavailable: `yaml provider_routing: order: - "Anthropic" - "Google" require_parameters: true` ## How It Works Provider routing preferences are passed to the OpenRouter API via the `extra_body.provider` field on every API call. This applies to both: - CLI mode — configured in `~/.hermes/config.yaml`, loaded at startup - Gateway mode — same config file, loaded when the gateway starts The routing config is read from `config.yaml` and passed as parameters when creating the `AIAgent`: `providers_allowed ← from provider_routing.only providers_ignored ← from provider_routing.ignore providers_order ← from provider_routing.order provider_sort ← from provider_routing.sort provider_require_parameters ← from provider_routing.require_parameters provider_data_collection ← from provider_routing.data_collection` :::tip You can combine multiple options. For example, sort by price but exclude certain providers and require parameter support: `yaml provider_routing: sort: "price" ignore: ["Together"] require_parameters: true data_collection: "deny"` ::: ## Default Behavior When no `provider_routing` section is configured (the default), OpenRouter uses its own default routing logic, which generally balances cost and availability automatically. :::tip Provider Routing vs. Fallback Models Provider routing controls which sub-providers within OpenRouter handle your requests. For automatic failover to an entirely different provider when your primary model fails, see Fallback Providers. ::: — # user-guide/features/fallback-providers # Fallback Providers Hermes Agent has three layers of resilience that keep your sessions running when providers hit issues: 1. Credential pools** — rotate across multiple API keys for the same provider (tried first) 2. Primary model fallback — automatically switches to a different provider:model when your main model fails 3. Auxiliary task fallback — independent provider resolution for side tasks like vision, compression, and web extraction Credential pools handle same-provider rotation (e.g., multiple OpenRouter keys). This page covers cross-provider fallback. Both are optional and work independently. ## Primary Model Fallback When your main LLM provider encounters errors — rate limits, server overload, auth failures, connection drops — Hermes can automatically switch to a backup provider:model pair mid-session without losing your conversation. ### Configuration The easiest path is the interactive manager: `bash hermes fallback` `hermes fallback` reuses the provider picker from `hermes model` — same provider list, same credential prompts, same validation. Use the subcommands `add`, `list` (alias `ls`), `remove` (alias `rm`), and `clear` to manage the chain. Changes persist under the top-level `fallback_providers:` list in `config.yaml`. If you’d rather edit the YAML directly, add a top-level `fallback_providers` list to `~/.hermes/config.yaml`: `yaml fallback_providers: - provider: openrouter model: anthropic/claude-sonnet-4` Each entry requires both `provider` and `model`. Entries missing either field are ignored. :::note `fallback_model` vs `fallback_providers` `fallback_providers` (plural, list) is the current config shape and supports multiple fallbacks tried in order. `fallback_model` (singular) is the legacy single-fallback key — Hermes still honors it for back-compat, but `hermes fallback` writes the current `fallback_providers` key and migrates legacy config on write. When both are set, `fallback_providers` takes priority. ::: ### Supported Providers | Provider | Value | Requirements | |–––––|—––|———––| | OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | | Nous Portal | `nous` | `hermes setup --portal` (fresh) or `hermes auth add nous` (OAuth) | | OpenAI Codex | `openai-codex` | `hermes model` (ChatGPT OAuth) | | GitHub Copilot | `copilot` | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN` | | GitHub Copilot ACP | `copilot-acp` | External process (editor integration) | | Anthropic | `anthropic` | `ANTHROPIC_API_KEY` or Claude Code credentials | | z.ai / GLM | `zai` | `GLM_API_KEY` | | Kimi / Moonshot | `kimi-coding` | `KIMI_API_KEY` | | MiniMax | `minimax` | `MINIMAX_API_KEY` | | MiniMax (China) | `minimax-cn` | `MINIMAX_CN_API_KEY` | | DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | | NVIDIA NIM | `nvidia` | `NVIDIA_API_KEY` (optional: `NVIDIA_BASE_URL`) | | GMI Cloud | `gmi` | `GMI_API_KEY` (optional: `GMI_BASE_URL`) | | StepFun | `stepfun` | `STEPFUN_API_KEY` (optional: `STEPFUN_BASE_URL`) | | Ollama Cloud | `ollama-cloud` | `OLLAMA_API_KEY` | | Google Gemini (OAuth) | `google-gemini-cli` | `hermes model` (Google OAuth; optional: `HERMES_GEMINI_PROJECT_ID`) | | Google AI Studio | `gemini` | `GOOGLE_API_KEY` (alias: `GEMINI_API_KEY`) | | xAI (Grok) | `xai` (alias `grok`) | `XAI_API_KEY` (optional: `XAI_BASE_URL`) | | xAI Grok OAuth (SuperGrok) | `xai-oauth` (alias `grok-oauth`) | `hermes model` → xAI Grok OAuth (browser login; SuperGrok subscription) | | AWS Bedrock | `bedrock` | Standard boto3 auth (`AWS_REGION` + `AWS_PROFILE` or `AWS_ACCESS_KEY_ID`) | | Qwen Portal (OAuth) | `qwen-oauth` | `hermes model` (Qwen Portal OAuth; optional: `HERMES_QWEN_BASE_URL`) | | MiniMax (OAuth) | `minimax-oauth` | `hermes model` (MiniMax portal OAuth) | | OpenCode Zen | `opencode-zen` | `OPENCODE_ZEN_API_KEY` | | OpenCode Go | `opencode-go` | `OPENCODE_GO_API_KEY` | | Kilo Code | `kilocode` | `KILOCODE_API_KEY` | | Xiaomi MiMo | `xiaomi` | `XIAOMI_API_KEY` | | Arcee AI | `arcee` | `ARCEEAI_API_KEY` | | GMI Cloud | `gmi` | `GMI_API_KEY` | | Alibaba / DashScope | `alibaba` | `DASHSCOPE_API_KEY` | | Alibaba Coding Plan | `alibaba-coding-plan` | `ALIBABA_CODING_PLAN_API_KEY` (falls back to `DASHSCOPE_API_KEY`) | | Kimi / Moonshot (China) | `kimi-coding-cn` | `KIMI_CN_API_KEY` | | StepFun | `stepfun` | `STEPFUN_API_KEY` | | Tencent TokenHub | `tencent-tokenhub` | `TOKENHUB_API_KEY` | | Microsoft Foundry | `azure-foundry` | `AZURE_FOUNDRY_API_KEY` + `AZURE_FOUNDRY_BASE_URL` | | LM Studio (local) | `lmstudio` | `LM_API_KEY` (or none for local) + `LM_BASE_URL` | | Hugging Face | `huggingface` | `HF_TOKEN` | | Custom endpoint | `custom` | `base_url` + `key_env` (see below) | ### Custom Endpoint Fallback For a custom OpenAI-compatible endpoint, add `base_url` and optionally `key_env`: `yaml fallback_providers: - provider: custom model: my-local-model base_url: http://localhost:8000/v1 key_env: MY_LOCAL_KEY # env var name containing the API key` ### When Fallback Triggers The fallback activates automatically when the primary model fails with: - Rate limits (HTTP 429) — after exhausting retry attempts - Server errors (HTTP 500, 502, 503) — after exhausting retry attempts - Auth failures (HTTP 401, 403) — immediately (no point retrying) - Not found (HTTP 404) — immediately - Invalid responses — when the API returns malformed or empty responses repeatedly When triggered, Hermes: 1. Resolves credentials for the fallback provider 2. Builds a new API client 3. Swaps the model, provider, and client in-place 4. Resets the retry counter and continues the conversation The switch is seamless — your conversation history, tool calls, and context are preserved. The agent continues from exactly where it left off, just using a different model. :::info Per-Turn, Not Per-Session Fallback is turn-scoped: each new user message starts with the primary model restored. If the primary fails mid-turn, fallback activates for that turn only. On the next message, Hermes tries the primary again. Within a single turn, fallback activates at most once — if the fallback also fails, normal error handling takes over (retries, then error message). This prevents cascading failover loops within a turn while giving the primary model a fresh chance every turn. ::: ### Examples OpenRouter as fallback for Anthropic native: `yaml model: provider: anthropic default: claude-sonnet-4-6 fallback_providers: - provider: openrouter model: anthropic/claude-sonnet-4` Nous Portal as fallback for OpenRouter: `yaml model: provider: openrouter default: anthropic/claude-opus-4 fallback_providers: - provider: nous model: nous-hermes-3` Local model as fallback for cloud: `yaml fallback_providers: - provider: custom model: llama-3.1-70b base_url: http://localhost:8000/v1 key_env: LOCAL_API_KEY` Codex OAuth as fallback: `yaml fallback_providers: - provider: openai-codex model: gpt-5.3-codex` ### Where Fallback Works | Context | Fallback Supported | |———|—————––| | CLI sessions | ✔ | | Messaging gateway (Telegram, Discord, etc.) | ✔ | | Subagent delegation | ✔ (subagents inherit the parent fallback chain) | | Cron jobs | ✔ (cron agents inherit configured fallback providers) | | Auxiliary tasks (vision, compression) | ✘ (use their own provider chain — see below) | :::tip There are no environment variables for the primary fallback chain — configure it exclusively through `config.yaml` or `hermes fallback`. This is intentional: fallback configuration is a deliberate choice, not something a stale shell export should override. ::: — ## Auxiliary Task Fallback Hermes uses separate lightweight models for side tasks. Each task has its own provider resolution chain that acts as a built-in fallback system. ### Tasks with Independent Provider Resolution | Task | What It Does | Config Key | |——|———––|———–| | Vision | Image analysis, browser screenshots | `auxiliary.vision` | | Web Extract | Web page summarization | `auxiliary.web_extract` | | Compression | Context compression summaries | `auxiliary.compression` | | Skills Hub | Skill search and discovery | `auxiliary.skills_hub` | | MCP | MCP helper operations | `auxiliary.mcp` | | Approval | Smart command-approval classification | `auxiliary.approval` | | Title Generation | Session title summaries | `auxiliary.title_generation` | | Triage Specifier | `hermes kanban specify` / dashboard ✨ button — fleshes out a one-liner triage task into a real spec | `auxiliary.triage_specifier` | ### Auto-Detection Chain When a task’s provider is set to `"auto"` (the default), Hermes tries providers in order until one works: For text tasks (compression, web extract, etc.): `text OpenRouter → Nous Portal → Custom endpoint → Codex OAuth → API-key providers (z.ai, Kimi, MiniMax, Xiaomi MiMo, Hugging Face, Anthropic) → give up` For vision tasks: `text Main provider (if vision-capable) → OpenRouter → Nous Portal → Codex OAuth → Anthropic → Custom endpoint → give up` If the resolved provider fails at call time, Hermes also has an internal retry: if the provider is not OpenRouter and no explicit `base_url` is set, it tries OpenRouter as a last-resort fallback. ### Configuring Auxiliary Providers Each task can be configured independently in `config.yaml`: `yaml auxiliary: vision: provider: "auto" # auto | openrouter | nous | codex | main | anthropic model: "" # e.g. "openai/gpt-4o" base_url: "" # direct endpoint (takes precedence over provider) api_key: "" # API key for base_url web_extract: provider: "auto" model: "" compression: provider: "auto" model: "" skills_hub: provider: "auto" model: "" mcp: provider: "auto" model: ""` Every task above follows the same provider / model / base_url pattern. Context compression is configured under `auxiliary.compression`: `yaml auxiliary: compression: provider: main # Same provider options as other auxiliary tasks model: google/gemini-3-flash-preview base_url: null # Custom OpenAI-compatible endpoint` And the primary fallback chain uses: `yaml fallback_providers: - provider: openrouter model: anthropic/claude-sonnet-4 # base_url: http://localhost:8000/v1 # Optional custom endpoint` All three — auxiliary, compression, fallback — work the same way: set `provider` to pick who handles the request, `model` to pick which model, and `base_url` to point at a custom endpoint (overrides provider). ### Provider Options for Auxiliary Tasks These options apply to `auxiliary:`, `compression:`, and `fallback_providers:` entries only — `"main"` is not a valid value for your top-level `model.provider`. For custom endpoints, use `provider: custom` in your `model:` section (see AI Providers). | Provider | Description | Requirements | |–––––|———––|———––| | `"auto"` | Try providers in order until one works (default) | At least one provider configured | | `"openrouter"` | Force OpenRouter | `OPENROUTER_API_KEY` | | `"nous"` | Force Nous Portal | `hermes auth` | | `"codex"` | Force Codex OAuth | `hermes model` → Codex | | `"main"` | Use whatever provider the main agent uses (auxiliary tasks only) | Active main provider configured | | `"anthropic"` | Force Anthropic native | `ANTHROPIC_API_KEY` or Claude Code credentials | ### Direct Endpoint Override For any auxiliary task, setting `base_url` bypasses provider resolution entirely and sends requests directly to that endpoint: `yaml auxiliary: vision: base_url: "http://localhost:1234/v1" api_key: "local-key" model: "qwen2.5-vl"` `base_url` takes precedence over `provider`. Hermes uses the configured `api_key` for authentication, falling back to `OPENAI_API_KEY` if not set. It does not reuse `OPENROUTER_API_KEY` for custom endpoints. — ## Auxiliary Capacity-Error Fallback When you set an explicit auxiliary provider (e.g. `auxiliary.vision.provider: glm`), Hermes treats that as your preferred choice — but if the provider literally cannot serve the request because of a capacity error (HTTP 402 payment required, HTTP 429 daily-quota exhaustion, connection failure), Hermes falls back through a layered chain instead of failing silently: 1. Primary aux provider — the one you configured (tried first, always) 2. `auxiliary.<task>.fallback_chain` — your per-task override list, if you wrote one 3. Main agent provider + model — last-resort safety net (always tried, even if you didn’t write a chain) 4. Warn + re-raise — if every layer fails, Hermes logs `Auxiliary <task>: ... all fallbacks exhausted` at WARNING level and re-raises the original error Transient HTTP 429 rate limits (`Retry-After: ...`) are treated as request constraints, not capacity problems — they respect your explicit provider choice and do not trigger the fallback ladder. Only daily/monthly quota exhaustion, payment errors, and connection failures bypass the explicit-provider gate. For users on `provider: auto` (no explicit aux provider), the existing auto-detection chain runs in place of steps 2–3. Its first step is already the main agent model, so `auto` users get the same outcome with zero config. ### Optional: per-task fallback chain If you want a different fallback ordering than “main agent model first”, configure `fallback_chain` explicitly. Each entry needs at least `provider`; `model`, `base_url`, and `api_key` are optional. `yaml auxiliary: vision: provider: glm model: glm-4v-flash fallback_chain: - provider: openrouter model: google/gemini-3-flash-preview - provider: nous model: anthropic/claude-sonnet-4 compression: provider: openrouter fallback_chain: - provider: openai model: gpt-4o-mini` You do not need to configure `fallback_chain` to get fallback — the main-agent safety net runs regardless. Use it only when you specifically want a different order than the default. ### Provider quota errors that trigger fallback Hermes recognizes these as capacity-equivalent to 402 credit exhaustion (not transient rate limits): - Bedrock / LiteLLM: `Too many tokens per day`, `daily limit`, `tokens per day` - Vertex AI / GCP: `quota exceeded`, `resource exhausted`, `RESOURCE_EXHAUSTED` - Generic: `daily quota`, `quota_exceeded` If your provider returns a different phrase for daily-quota exhaustion and Hermes doesn’t trigger fallback, that’s a bug — open an issue with the exact error string. — ## Context Compression Fallback Context compression uses the `auxiliary.compression` config block to control which model and provider handles summarization: `yaml auxiliary: compression: provider: "auto" # auto | openrouter | nous | main model: "google/gemini-3-flash-preview"` :::info Legacy migration Older configs with `compression.summary_model` / `compression.summary_provider` / `compression.summary_base_url` are automatically migrated to `auxiliary.compression.` on first load (config version 17). ::: If no provider is available for compression, Hermes drops middle conversation turns without generating a summary rather than failing the session. — ## Delegation Provider Override Subagents spawned by `delegate_task` inherit the parent agent’s primary fallback chain. You can still route subagents to a different primary provider:model pair for cost optimization: `yaml delegation: provider: "openrouter" # override provider for all subagents model: "google/gemini-3-flash-preview" # override model # base_url: "http://localhost:1234/v1" # or use a direct endpoint # api_key: "local-key"` See Subagent Delegation for full configuration details. — ## Cron Job Providers Cron jobs inherit your configured `fallback_providers` chain (or legacy `fallback_model`) when they create an agent. To use a different primary provider for a cron job, configure `provider` and `model` overrides on the cron job itself: `python cronjob( action="create", schedule="every 2h", prompt="Check server status", provider="openrouter", model="google/gemini-3-flash-preview" )` See Scheduled Tasks (Cron) for full configuration details. — ## Summary | Feature | Fallback Mechanism | Config Location | |———|—————––|––––––––| | Main agent model | `fallback_providers` in config.yaml — per-turn failover on errors (primary restored each turn) | `fallback_providers:` (top-level list) | | Auxiliary tasks (any) — auto users | Full auto-detection chain (main agent model first, then provider chain) on capacity errors | `auxiliary.<task>.provider: auto` | | Auxiliary tasks (any) — explicit provider | `fallback_chain` (if set) → main agent model → warn + raise, on capacity errors only | `auxiliary.<task>.fallback_chain` | | Vision | Layered (see above) + internal OpenRouter retry | `auxiliary.vision` | | Web extraction | Layered (see above) + internal OpenRouter retry | `auxiliary.web_extract` | | Context compression | Layered (see above); degrades to no-summary if all layers unavailable | `auxiliary.compression` | | Skills hub | Layered (see above) | `auxiliary.skills_hub` | | MCP helpers | Layered (see above) | `auxiliary.mcp` | | Approval classification | Layered (see above) | `auxiliary.approval` | | Title generation | Layered (see above) | `auxiliary.title_generation` | | Triage specifier | Layered (see above) | `auxiliary.triage_specifier` | | Delegation | Provider override only (no automatic fallback) | `delegation.provider` / `delegation.model` | | Cron jobs | Per-job provider override only (no automatic fallback) | Per-job `provider` / `model` | — # user-guide/features/credential-pools # Credential Pools Credential pools let you register multiple API keys or OAuth tokens for the same provider. When one key hits a rate limit or billing quota, Hermes automatically rotates to the next healthy key — keeping your session alive without switching providers. This is different from fallback providers, which switch to a different* provider entirely. Credential pools are same-provider rotation; fallback providers are cross-provider failover. Pools are tried first — if all pool keys are exhausted, then the fallback provider activates. :::tip Credential pools are mainly for API-key providers (OpenRouter, Anthropic). A single Nous Portal OAuth covers 300+ models, so most users don’t need a pool when on Portal. ::: ## How It Works Your request → Pick key from pool (round_robin / least_used / fill_first / random) → Send to provider → 429 rate limit? → Plan/usage limit reached (e.g. ChatGPT/Codex "usage limit reached")? → Rotate to next pool key immediately (no retry — the cap won't clear on retry) → Generic / transient 429? → Retry same key once (transient blip) → Second 429 → rotate to next pool key → All keys exhausted → fallback_model (different provider) → 402 billing error? → Immediately rotate to next pool key (24h cooldown) → 401 auth expired? → Try refreshing the token (OAuth) → Refresh failed → rotate to next pool key → Success → continue normally ## Quick Start If you already have an API key set in `.env`, Hermes auto-discovers it as a 1-key pool. To benefit from pooling, add more keys: `bash # Add a second OpenRouter key hermes auth add openrouter --api-key sk-or-v1-your-second-key # Add a second Anthropic key hermes auth add anthropic --type api-key --api-key sk-ant-api03-your-second-key # Add an Anthropic OAuth credential (requires Claude Max plan + extra usage credits) hermes auth add anthropic --type oauth # Opens browser for OAuth login` Check your pools: `bash hermes auth list` Output: `openrouter (2 credentials): #1 OPENROUTER_API_KEY api_key env:OPENROUTER_API_KEY ← #2 backup-key api_key manual anthropic (3 credentials): #1 hermes_pkce oauth hermes_pkce ← #2 claude_code oauth claude_code #3 ANTHROPIC_API_KEY api_key env:ANTHROPIC_API_KEY` The `←` marks the currently selected credential. ## Interactive Management Run `hermes auth` with no subcommand for an interactive wizard: `bash hermes auth` This shows your full pool status and offers a menu: `What would you like to do? 1. Add a credential 2. Remove a credential 3. Reset cooldowns for a provider 4. Set rotation strategy for a provider 5. Exit` For providers that support both API keys and OAuth (Anthropic, Nous, Codex), the add flow asks which type: `anthropic supports both API keys and OAuth login. 1. API key (paste a key from the provider dashboard) 2. OAuth login (authenticate via browser) Type [1/2]:` ## CLI Commands | Command | Description | |———|———––| | `hermes auth` | Interactive pool management wizard | | `hermes auth list` | Show all pools and credentials | | `hermes auth list <provider>` | Show a specific provider’s pool | | `hermes auth add <provider>` | Add a credential (prompts for type and key) | | `hermes auth add <provider> --type api-key --api-key <key>` | Add an API key non-interactively | | `hermes auth add <provider> --type oauth` | Add an OAuth credential via browser login | | `hermes auth remove <provider> <index>` | Remove credential by 1-based index | | `hermes auth reset <provider>` | Clear all cooldowns/exhaustion status | ## Rotation Strategies Configure via `hermes auth` → “Set rotation strategy” or in `config.yaml`: `yaml credential_pool_strategies: openrouter: round_robin anthropic: least_used` | Strategy | Behavior | |–––––|–––––| | `fill_first` (default) | Use the first healthy key until it’s exhausted, then move to the next | | `round_robin` | Cycle through keys evenly, rotating after each selection | | `least_used` | Always pick the key with the lowest request count | | `random` | Random selection among healthy keys | ## Error Recovery The pool handles different errors differently: | Error | Behavior | Cooldown | |—––|–––––|–––––| | 429 Rate Limit | Retry same key once (transient). Second consecutive 429 rotates to next key | 1 hour | | 402 Billing/Quota | Immediately rotate to next key | 24 hours | | 401 Auth Expired | Try refreshing the OAuth token first. Rotate only if refresh fails | — | | All keys exhausted | Fall through to `fallback_model` if configured | — | The `has_retried_429` flag resets on every successful API call, so a single transient 429 doesn’t trigger rotation. ## Custom Endpoint Pools Custom OpenAI-compatible endpoints (Together.ai, RunPod, local servers) get their own pools, keyed by the endpoint name from `custom_providers` in config.yaml. When you set up a custom endpoint via `hermes model`, it auto-generates a name like “Together.ai” or “Local (localhost:8080)”. This name becomes the pool key. `bash # After setting up a custom endpoint via hermes model: hermes auth list # Shows: # Together.ai (1 credential): # #1 config key api_key config:Together.ai ← # Add a second key for the same endpoint: hermes auth add Together.ai --api-key sk-together-second-key` Custom endpoint pools are stored in `auth.json` under `credential_pool` with a `custom:` prefix: `json { "credential_pool": { "openrouter": [...], "custom:together.ai": [...] } }` ## Auto-Discovery Hermes automatically discovers credentials from multiple sources and seeds the pool on startup: | Source | Example | Auto-seeded? | |––––|———|———––| | Environment variables | `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY` | Yes | | OAuth tokens (auth.json) | Codex device code, Nous device code | Yes | | Claude Code credentials | `~/.claude/.credentials.json` | Yes (Anthropic) | | Hermes PKCE OAuth | `~/.hermes/auth.json` | Yes (Anthropic) | | Custom endpoint config | `model.api_key` in config.yaml | Yes (custom endpoints) | | Manual entries | Added via `hermes auth add` | Persisted in auth.json | Auto-seeded entries are updated on each pool load — if you remove an env var, its pool entry is automatically pruned. Manual entries (added via `hermes auth add`) are never auto-pruned. Borrowed runtime secrets (for example env vars, Bitwarden/Vault/keyring/systemd references, and custom config values) are reference-only at the `auth.json` boundary. Hermes can use the resolved value in memory for the current run, but it persists only metadata such as the source ref, label, status, request counters, and a non-reversible fingerprint. Manual entries and Hermes-owned OAuth/device-code state keep the durable tokens they need to refresh. ## Delegation & Subagent Sharing When the agent spawns subagents via `delegate_task`, the parent’s credential pool is automatically shared with children: - Same provider — the child receives the parent’s full pool, enabling key rotation on rate limits - Different provider — the child loads that provider’s own pool (if configured) - No pool configured — the child falls back to the inherited single API key This means subagents benefit from the same rate-limit resilience as the parent, with no extra configuration needed. Per-task credential leasing ensures children don’t conflict with each other when rotating keys concurrently. ## Thread Safety The credential pool uses a threading lock for all state mutations (`select()`, `mark_exhausted_and_rotate()`, `try_refresh_current()`, `mark_used()`). This ensures safe concurrent access when the gateway handles multiple chat sessions simultaneously. ## Architecture For the full data flow diagram, see `docs/credential-pool-flow.excalidraw` in the repository. The credential pool integrates at the provider resolution layer: 1. `agent/credential_pool.py` — Pool manager: storage, selection, rotation, cooldowns 2. `hermes_cli/auth_commands.py` — CLI commands and interactive wizard 3. `hermes_cli/runtime_provider.py` — Pool-aware credential resolution 4. `run_agent.py` — Error recovery: 429/402/401 → pool rotation → fallback ## Storage Pool state is stored in `~/.hermes/auth.json` under the `credential_pool` key: `json { "version": 1, "credential_pool": { "openrouter": [ { "id": "abc123", "label": "OPENROUTER_API_KEY", "auth_type": "api_key", "priority": 0, "source": "env:OPENROUTER_API_KEY", "secret_source": "bitwarden", "secret_fingerprint": "sha256:12ab34cd56ef7890", "last_status": "ok", "request_count": 142 } ], "anthropic": [ { "id": "manual1", "label": "personal-api-key", "auth_type": "api_key", "priority": 0, "source": "manual", "access_token": "sk-ant-api03-..." } ] } }` The OpenRouter entry above was borrowed from an external source, so the raw key is not stored in `auth.json`. The manual Anthropic entry was intentionally added to Hermes’ credential store, so its token remains persistable. Strategies are stored in `config.yaml` (not `auth.json`): `yaml credential_pool_strategies: openrouter: round_robin anthropic: least_used` — # Tips & Best Practices # Tips & Best Practices A quick-wins collection of practical tips that make you immediately more effective with Hermes Agent. Each section targets a different aspect — scan the headers and jump to what’s relevant. :::tip Confused which model to pick? Run `hermes setup --portal` — you get 300+ models including Claude, GPT-5, and Gemini under one subscription. See Nous Portal. ::: — ## Getting the Best Results ### Be Specific About What You Want Vague prompts produce vague results. Instead of “fix the code,” say “fix the TypeError in `api/handlers.py` on line 47 — the `process_request()` function receives `None` from `parse_body()`.” The more context you give, the fewer iterations you need. ### Provide Context Up Front Front-load your request with the relevant details: file paths, error messages, expected behavior. One well-crafted message beats three rounds of clarification. Paste error tracebacks directly — the agent can parse them. ### Use Context Files for Recurring Instructions If you find yourself repeating the same instructions (“use tabs not spaces,” “we use pytest,” “the API is at `/api/v2`”), put them in an `AGENTS.md` file. The agent reads it automatically every session — zero effort after setup. ### Let the Agent Use Its Tools Don’t try to hand-hold every step. Say “find and fix the failing test” rather than “open `tests/test_foo.py`, look at line 42, then…” The agent has file search, terminal access, and code execution — let it explore and iterate. ### Use Skills for Complex Workflows Before writing a long prompt explaining how to do something, check if there’s already a skill for it. Type `/skills` to browse available skills, or just invoke one directly like `/axolotl` or `/github-pr-workflow`. ## CLI Power User Tips ### Multi-Line Input Press Alt+Enter, Ctrl+J, or Shift+Enter to insert a newline without sending. `Shift+Enter` only works when the terminal sends it as a distinct keystroke (Kitty / foot / WezTerm / Ghostty by default; iTerm2 / Alacritty / VS Code terminal once the Kitty keyboard protocol is enabled). The other two work in every terminal. ### Paste Detection The CLI auto-detects multi-line pastes. Just paste a code block or error traceback directly — it won’t send each line as a separate message. The paste is buffered and sent as one message. ### Interrupt and Redirect Press Ctrl+C once to interrupt the agent mid-response. You can then type a new message to redirect it. Double-press Ctrl+C within 2 seconds to force exit. This is invaluable when the agent starts going down the wrong path. ### Resume Sessions with `-c` Forgot something from your last session? Run `hermes -c` to resume exactly where you left off, with full conversation history restored. You can also resume by title: `hermes -r "my research project"`. ### Clipboard Image Paste Press Ctrl+V to paste an image from your clipboard directly into the chat. The agent uses vision to analyze screenshots, diagrams, error popups, or UI mockups — no need to save to a file first. ### Slash Command Autocomplete Type `/` and press Tab to see all available commands. This includes built-in commands (`/compress`, `/model`, `/title`) and every installed skill. You don’t need to memorize anything — Tab completion has you covered. :::tip Use `/verbose` to cycle through tool output display modes: off → new → all → verbose. The “all” mode is great for watching what the agent does; “off” is cleanest for simple Q&A. ::: ## Context Files ### AGENTS.md: Your Project’s Brain Create an `AGENTS.md` in your project root with architecture decisions, coding conventions, and project-specific instructions. This is automatically injected into every session, so the agent always knows your project’s rules. `markdown # Project Context - This is a FastAPI backend with SQLAlchemy ORM - Always use async/await for database operations - Tests go in tests/ and use pytest-asyncio - Never commit .env files` ### SOUL.md: Customize Personality Want Hermes to have a stable default voice? Edit `~/.hermes/SOUL.md` (or `$HERMES_HOME/SOUL.md` if you use a custom Hermes home). Hermes now seeds a starter SOUL automatically and uses that global file as the instance-wide personality source. For a full walkthrough, see Use SOUL.md with Hermes. `markdown # Soul You are a senior backend engineer. Be terse and direct. Skip explanations unless asked. Prefer one-liners over verbose solutions. Always consider error handling and edge cases.` Use `SOUL.md` for durable personality. Use `AGENTS.md` for project-specific instructions. ### .cursorrules Compatibility Already have a `.cursorrules` or `.cursor/rules/.mdc` file? Hermes reads those too. No need to duplicate your coding conventions — they’re loaded automatically from the working directory. ### Discovery Hermes loads the top-level `AGENTS.md` from the current working directory at session start. Subdirectory `AGENTS.md` files are discovered lazily during tool calls (via `subdirectory_hints.py`) and injected into tool results — they are not loaded upfront into the system prompt. :::tip Keep context files focused and concise. Every character counts against your token budget since they’re injected into every single message. ::: ## Memory & Skills ### Memory vs. Skills: What Goes Where Memory is for facts: your environment, preferences, project locations, and things the agent has learned about you. Skills are for procedures: multi-step workflows, tool-specific instructions, and reusable recipes. Use memory for “what,” skills for “how.” ### When to Create Skills If you find a task that takes 5+ steps and you’ll do it again, ask the agent to create a skill for it. Say “save what you just did as a skill called `deploy-staging`.” Next time, just type `/deploy-staging` and the agent loads the full procedure. ### Managing Memory Capacity Memory is intentionally bounded (~2,200 chars for MEMORY.md, ~1,375 chars for USER.md). When it fills up, the agent consolidates entries. You can help by saying “clean up your memory” or “replace the old Python 3.9 note — we’re on 3.12 now.” ### Let the Agent Remember After a productive session, say “remember this for next time” and the agent will save the key takeaways. You can also be specific: “save to memory that our CI uses GitHub Actions with the `deploy.yml` workflow.” :::warning Memory is a frozen snapshot — changes made during a session don’t appear in the system prompt until the next session starts. The agent writes to disk immediately, but the prompt cache isn’t invalidated mid-session. ::: ## Performance & Cost ### Don’t Break the Prompt Cache Most LLM providers cache the system prompt prefix. If you keep your system prompt stable (same context files, same memory), subsequent messages in a session get cache hits that are significantly cheaper. Avoid changing the model or system prompt mid-session. ### Use /compress Before Hitting Limits Long sessions accumulate tokens. When you notice responses slowing down or getting truncated, run `/compress`. This summarizes the conversation history, preserving key context while dramatically reducing token count. Use `/usage` to check where you stand. ### Delegate for Parallel Work Need to research three topics at once? Ask the agent to use `delegate_task` with parallel subtasks. Each subagent runs independently with its own context, and only the final summaries come back — massively reducing your main conversation’s token usage. ### Use execute_code for Batch Operations Instead of running terminal commands one at a time, ask the agent to write a script that does everything at once. “Write a Python script to rename all `.jpeg` files to `.jpg` and run it” is cheaper and faster than renaming files individually. ### Choose the Right Model Use `/model` to switch models mid-session. Use a frontier model (Claude Sonnet/Opus, GPT-4o) for complex reasoning and architecture decisions. Switch to a faster model for simple tasks like formatting, renaming, or boilerplate generation. :::tip Run `/usage` periodically to see your token consumption. Run `/insights` for a broader view of usage patterns over the last 30 days. ::: ## Messaging Tips ### Set a Home Channel Use `/sethome` in your preferred Telegram or Discord chat to designate it as the home channel. Cron job results and scheduled task outputs are delivered here. Without it, the agent has nowhere to send proactive messages. ### Use /title to Organize Sessions Name your sessions with `/title auth-refactor` or `/title research-llm-quantization`. Named sessions are easy to find with `hermes sessions list` and resume with `hermes -r "auth-refactor"`. Unnamed sessions pile up and become impossible to distinguish. ### DM Pairing for Team Access Instead of manually collecting user IDs for allowlists, enable DM pairing. When a teammate DMs the bot, they get a one-time pairing code. You approve it with `hermes pairing approve telegram XKGH5N7P` — simple and secure. ### Tool Progress Display Modes Use `/verbose` to control how much tool activity you see. In messaging platforms, less is usually more — keep it on “new” to see just new tool calls. In the CLI, “all” gives you a satisfying live view of everything the agent does. :::tip On messaging platforms, sessions auto-reset after idle time (default: 24 hours) or daily at 4 AM. Adjust per-platform in `~/.hermes/config.yaml` if you need longer sessions. ::: ## Security ### Use Docker for Untrusted Code When working with untrusted repositories or running unfamiliar code, use Docker or Daytona as your terminal backend. Set `TERMINAL_BACKEND=docker` in your `.env`. Destructive commands inside a container can’t harm your host system. `bash # In your .env: TERMINAL_BACKEND=docker TERMINAL_DOCKER_IMAGE=hermes-sandbox:latest` ### Avoid Windows Encoding Pitfalls On Windows, some default encodings (such as `cp125x`) cannot represent all Unicode characters, which can cause `UnicodeEncodeError` when writing files in tests or scripts. - Prefer opening files with an explicit UTF-8 encoding: `python with open("results.txt", "w", encoding="utf-8") as f: f.write("✓ All good\n")` - In PowerShell, you can also switch the current session to UTF-8 for console and native command output: `powershell $OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)` This keeps PowerShell and child processes on UTF-8 and helps avoid Windows-only failures. ### Review Before Choosing “Always” When the agent triggers a dangerous command approval (`rm -rf`, `DROP TABLE`, etc.), you get four options: once, session, always, deny. Think carefully before choosing “always” — it permanently allowlists that pattern. Start with “session” until you’re comfortable. ### Command Approval Is Your Safety Net Hermes checks every command against a curated list of dangerous patterns before execution. This includes recursive deletes, SQL drops, piping curl to shell, and more. Don’t disable this in production — it exists for good reasons. :::warning When running in a container backend (Docker, Singularity, Modal, Daytona), dangerous command checks are skipped because the container is the security boundary. Make sure your container images are properly locked down. ::: ### Use Allowlists for Messaging Bots Never set `GATEWAY_ALLOW_ALL_USERS=true` on a bot with terminal access. Always use platform-specific allowlists (`TELEGRAM_ALLOWED_USERS`, `DISCORD_ALLOWED_USERS`) or DM pairing to control who can interact with your agent. `bash # Recommended: explicit allowlists per platform TELEGRAM_ALLOWED_USERS=123456789,987654321 DISCORD_ALLOWED_USERS=123456789012345678 # Or use cross-platform allowlist GATEWAY_ALLOWED_USERS=123456789,987654321` — Have a tip that should be on this page? Open an issue or PR — community contributions are welcome.* — # Run Local LLMs on Mac # Run Local LLMs on Mac This guide walks you through running a local LLM server on macOS with an OpenAI-compatible API. You get full privacy, zero API costs, and surprisingly good performance on Apple Silicon. We cover two backends: | Backend | Install | Best at | Format | |———|———|———|––––| | llama.cpp | `brew install llama.cpp` | Fastest time-to-first-token, quantized KV cache for low memory | GGUF | | omlx | omlx.ai | Fastest token generation, native Metal optimization | MLX (safetensors) | Both expose an OpenAI-compatible `/v1/chat/completions` endpoint. Hermes works with either one — just point it at `http://localhost:8080` or `http://localhost:8000`. :::info Apple Silicon only This guide targets Macs with Apple Silicon (M1 and later). Intel Macs will work with llama.cpp but without GPU acceleration — expect significantly slower performance. ::: — ## Choosing a model For getting started, we recommend Qwen3.5-9B — it’s a strong reasoning model that fits comfortably in 8GB+ of unified memory with quantization. | Variant | Size on disk | RAM needed (128K context) | Backend | |———|———––|—————————|———| | Qwen3.5-9B-Q4_K_M (GGUF) | 5.3 GB | ~10 GB with quantized KV cache | llama.cpp | | Qwen3.5-9B-mlx-lm-mxfp4 (MLX) | ~5 GB | ~12 GB | omlx | Memory rule of thumb: model size + KV cache. A 9B Q4 model is ~5 GB. The KV cache at 128K context with Q4 quantization adds ~4-5 GB. With default (f16) KV cache, that balloons to ~16 GB. The quantized KV cache flags in llama.cpp are the key trick for memory-constrained systems. For larger models (27B, 35B), you’ll need 32 GB+ of unified memory. The 9B is the sweet spot for 8-16 GB machines. — ## Option A: llama.cpp llama.cpp is the most portable local LLM runtime. On macOS it uses Metal for GPU acceleration out of the box. ### Install `bash brew install llama.cpp` This gives you the `llama-server` command globally. ### Download the model You need a GGUF-format model. The easiest source is Hugging Face via the `huggingface-cli`: `bash brew install huggingface-cli` Then download: `bash huggingface-cli download unsloth/Qwen3.5-9B-GGUF Qwen3.5-9B-Q4_K_M.gguf --local-dir ~/models` :::tip Gated models Some models on Hugging Face require authentication. Run `huggingface-cli login` first if you get a 401 or 404 error. ::: ### Start the server `bash llama-server -m ~/models/Qwen3.5-9B-Q4_K_M.gguf \ -ngl 99 \ -c 131072 \ -np 1 \ -fa on \ --cache-type-k q4_0 \ --cache-type-v q4_0 \ --host 0.0.0.0` Here’s what each flag does: | Flag | Purpose | |——|———| | `-ngl 99` | Offload all layers to GPU (Metal). Use a high number to ensure nothing stays on CPU. | | `-c 131072` | Context window size (128K tokens). Reduce this if you’re low on memory. | | `-np 1` | Number of parallel slots. Keep at 1 for single-user use — more slots split your memory budget. | | `-fa on` | Flash attention. Reduces memory usage and speeds up long-context inference. | | `--cache-type-k q4_0` | Quantize the key cache to 4-bit. This is the big memory saver. | | `--cache-type-v q4_0` | Quantize the value cache to 4-bit. Together with the above, this cuts KV cache memory by ~75% vs f16. | | `--host 0.0.0.0` | Listen on all interfaces. Use `127.0.0.1` if you don’t need network access. | The server is ready when you see: `main: server is listening on http://0.0.0.0:8080 srv update_slots: all slots are idle` ### Memory optimization for constrained systems The `--cache-type-k q4_0 --cache-type-v q4_0` flags are the most important optimization for systems with limited memory. Here’s the impact at 128K context: | KV cache type | KV cache memory (128K ctx, 9B model) | |—————|–––––––––––––––––––| | f16 (default) | ~16 GB | | q8_0 | ~8 GB | | q4_0 | ~4 GB | On an 8 GB Mac, use `q4_0` KV cache and choose a smaller model that can still fit Hermes’ 64K minimum context. On 16 GB, you can comfortably do 128K context. On 32 GB+, you can run larger models or multiple parallel slots. If you’re still running out of memory, reduce context only while staying at or above Hermes’ 64K minimum; otherwise switch to a smaller model or smaller quantization (Q3_K_M instead of Q4_K_M). ### Test it `bash curl -s http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "Qwen3.5-9B-Q4_K_M.gguf", "messages": [{"role": "user", "content": "Hello!"}], "max_tokens": 50 }' | jq .choices[0].message.content` ### Get the model name If you forget the model name, query the models endpoint: `bash curl -s http://localhost:8080/v1/models | jq '.data[].id'` — ## Option B: MLX via omlx omlx is a macOS-native app that manages and serves MLX models. MLX is Apple’s own machine learning framework, optimized specifically for Apple Silicon’s unified memory architecture. ### Install Download and install from omlx.ai. It provides a GUI for model management and a built-in server. ### Download the model Use the omlx app to browse and download models. Search for `Qwen3.5-9B-mlx-lm-mxfp4` and download it. Models are stored locally (typically in `~/.omlx/models/`). ### Start the server omlx serves models on `http://127.0.0.1:8000` by default. Start serving from the app UI, or use the CLI if available. ### Test it `bash curl -s http://127.0.0.1:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "Qwen3.5-9B-mlx-lm-mxfp4", "messages": [{"role": "user", "content": "Hello!"}], "max_tokens": 50 }' | jq .choices[0].message.content` ### List available models omlx can serve multiple models simultaneously: `bash curl -s http://127.0.0.1:8000/v1/models | jq '.data[].id'` — ## Benchmarks: llama.cpp vs MLX Both backends tested on the same machine (Apple M5 Max, 128 GB unified memory) running the same model (Qwen3.5-9B) at comparable quantization levels (Q4_K_M for GGUF, mxfp4 for MLX). Five diverse prompts, three runs each, backends tested sequentially to avoid resource contention. ### Results | Metric | llama.cpp (Q4_K_M) | MLX (mxfp4) | Winner | |––––|—————––|———––|––––| | TTFT (avg) | 67 ms | 289 ms | llama.cpp (4.3x faster) | | TTFT (p50) | 66 ms | 286 ms | llama.cpp (4.3x faster) | | Generation (avg) | 70 tok/s | 96 tok/s | MLX (37% faster) | | Generation (p50) | 70 tok/s | 96 tok/s | MLX (37% faster) | | Total time (512 tokens) | 7.3s | 5.5s | MLX (25% faster) | ### What this means - llama.cpp excels at prompt processing — its flash attention + quantized KV cache pipeline gets you the first token in ~66ms. If you’re building interactive applications where perceived responsiveness matters (chatbots, autocomplete), this is a meaningful advantage. - MLX generates tokens ~37% faster once it gets going. For batch workloads, long-form generation, or any task where total completion time matters more than initial latency, MLX finishes sooner. - Both backends are extremely consistent — variance across runs was negligible. You can rely on these numbers. ### Which one should you pick? | Use case | Recommendation | |–––––|—————| | Interactive chat, low-latency tools | llama.cpp | | Long-form generation, bulk processing | MLX (omlx) | | Memory-constrained (8-16 GB) | llama.cpp (quantized KV cache is unmatched) | | Serving multiple models simultaneously | omlx (built-in multi-model support) | | Maximum compatibility (Linux too) | llama.cpp | — ## Connect to Hermes Once your local server is running: `bash hermes model` Select Custom endpoint and follow the prompts. It will ask for the base URL and model name — use the values from whichever backend you set up above. — ## Timeouts Hermes automatically detects local endpoints (localhost, LAN IPs) and relaxes its streaming timeouts. No configuration needed for most setups. If you still hit timeout errors (e.g. very large contexts on slow hardware), you can override the streaming read timeout: `bash # In your .env — raise from the 120s default to 30 minutes HERMES_STREAM_READ_TIMEOUT=1800` | Timeout | Default | Local auto-adjustment | Env var override | |———|———|–––––––––––|——————| | Stream read (socket-level) | 120s | Raised to 1800s | `HERMES_STREAM_READ_TIMEOUT` | | Stale stream detection | 180s | Disabled entirely | `HERMES_STREAM_STALE_TIMEOUT` | | API call (non-streaming) | 1800s | No change needed | `HERMES_API_TIMEOUT` | The stream read timeout is the one most likely to cause issues — it’s the socket-level deadline for receiving the next chunk of data. During prefill on large contexts, local models may produce no output for minutes while processing the prompt. The auto-detection handles this transparently. — # Tutorial: Daily Briefing Bot # Tutorial: Build a Daily Briefing Bot In this tutorial, you’ll build a personal briefing bot that wakes up every morning, researches topics you care about, summarizes the findings, and delivers a concise briefing straight to your Telegram or Discord. By the end, you’ll have a fully automated workflow combining web search, cron scheduling, delegation, and messaging delivery — no code required. :::tip This recipe hits web search, summarization, and optional TTS — all bundled in a Portal subscription. The fastest setup is `hermes setup --portal`. See Nous Portal. ::: ## What We’re Building Here’s the flow: 1. 8:00 AM — The cron scheduler triggers your job 2. Hermes spins up a fresh agent session with your prompt 3. Web search pulls the latest news on your topics 4. Summarization distills it into a clean briefing format 5. Delivery sends the briefing to your Telegram or Discord The whole thing runs hands-free. You just read your briefing with your morning coffee. ## Prerequisites Before starting, make sure you have: - Hermes Agent installed — see the Installation guide - Gateway running — the gateway daemon handles cron execution: `bash hermes gateway install # Install as a user service sudo hermes gateway install --system # Linux servers: boot-time system service # or hermes gateway # Run in foreground` - Firecrawl API key — set `FIRECRAWL_API_KEY` in your environment for web search - Messaging configured (optional but recommended) — Telegram or Discord set up with a home channel :::tip No messaging? No problem You can still follow this tutorial using `deliver: "local"`. Briefings will be saved to `~/.hermes/cron/output/` and you can read them anytime. ::: ## Step 1: Test the Workflow Manually Before automating anything, let’s make sure the briefing works. Start a chat session: `bash hermes` Then enter this prompt: `Search for the latest news about AI agents and open source LLMs. Summarize the top 3 stories in a concise briefing format with links.` Hermes will search the web, read through results, and produce something like: ☀️ Your AI Briefing — March 8, 2026 1. Qwen 3 Released with 235B Parameters Alibaba's latest open-weight model matches GPT-4.5 on several benchmarks while remaining fully open source. → https://qwenlm.github.io/blog/qwen3/ 2. LangChain Launches Agent Protocol Standard A new open standard for agent-to-agent communication gains adoption from 15 major frameworks in its first week. → https://blog.langchain.dev/agent-protocol/ 3. EU AI Act Enforcement Begins for General-Purpose Models The first compliance deadlines hit, with open source models receiving exemptions under the 10M parameter threshold. → https://artificialintelligenceact.eu/updates/ --- 3 stories • Sources searched: 8 • Generated by Hermes Agent If this works, you’re ready to automate it. :::tip Iterate on the format Try different prompts until you get output you love. Add instructions like “use emoji headers” or “keep each summary under 2 sentences.” Whatever you settle on goes into the cron job. ::: ## Step 2: Create the Cron Job Now let’s schedule this to run automatically every morning. You can do this in two ways. Before creating cron jobs, ensure Hermes has a default model and provider configured globally. If you want a specific job to use different values, set explicit per-job model/provider overrides when creating it. ### Option A: Natural Language (in chat) Just tell Hermes what you want: `Every morning at 8am, search the web for the latest news about AI agents and open source LLMs. Summarize the top 3 stories in a concise briefing with links. Use a friendly, professional tone. Deliver to telegram.` Hermes will create the cron job for you using the unified `cronjob` tool. ### Option B: CLI Slash Command Use the `/cron` command for more control: `/cron add "0 8 * * " "Search the web for the latest news about AI agents and open source LLMs. Find at least 5 recent articles from the past 24 hours. Summarize the top 3 most important stories in a concise daily briefing format. For each story include: a clear headline, a 2-sentence summary, and the source URL. Use a friendly, professional tone. Format with emoji bullet points and end with a total story count."` ### The Golden Rule: Self-Contained Prompts :::warning Critical concept Cron jobs run in a completely fresh session — no memory of your previous conversations, no context about what you “set up earlier.” Your prompt must contain everything the agent needs to do the job. ::: Bad prompt: `Do my usual morning briefing.` Good prompt: `Search the web for the latest news about AI agents and open source LLMs. Find at least 5 recent articles from the past 24 hours. Summarize the top 3 most important stories in a concise daily briefing format. For each story include: a clear headline, a 2-sentence summary, and the source URL. Use a friendly, professional tone. Format with emoji bullet points.` The good prompt is specific about what to search, how many articles, what format, and what tone. It’s everything the agent needs in one shot. ## Step 3: Customize the Briefing Once the basic briefing works, you can get creative. ### Multi-Topic Briefings Cover several areas in one briefing: /cron add "0 8 * " "Create a morning briefing covering three topics. For each topic, search the web for recent news from the past 24 hours and summarize the top 2 stories with links. Topics: 1. AI and machine learning — focus on open source models and agent frameworks 2. Cryptocurrency — focus on Bitcoin, Ethereum, and regulatory news 3. Space exploration — focus on SpaceX, NASA, and commercial space Format as a clean briefing with section headers and emoji. End with today's date and a motivational quote." ### Using Delegation for Parallel Research For faster briefings, tell Hermes to delegate each topic to a sub-agent: /cron add "0 8 * " "Create a morning briefing by delegating research to sub-agents. Delegate three parallel tasks: 1. Delegate: Search for the top 2 AI/ML news stories from the past 24 hours with links 2. Delegate: Search for the top 2 cryptocurrency news stories from the past 24 hours with links 3. Delegate: Search for the top 2 space exploration news stories from the past 24 hours with links Collect all results and combine them into a single clean briefing with section headers, emoji formatting, and source links. Add today's date as a header." Each sub-agent searches independently and in parallel, then the main agent combines everything into one polished briefing. See the Delegation docs for more on how this works. ### Weekday-Only Schedule Don’t need briefings on weekends? Use a cron expression that targets Monday–Friday: `/cron add "0 8 * 1-5" "Search for the latest AI and tech news..."` ### Twice-Daily Briefings Get a morning overview and an evening recap: `/cron add "0 8 * * " "Morning briefing: search for AI news from the past 12 hours..." /cron add "0 18 * " "Evening recap: search for AI news from the past 12 hours..."` ### Adding Personal Context with Memory If you have memory enabled, you can store preferences that persist across sessions. But remember — cron jobs run in fresh sessions without conversational memory. To add personal context, bake it directly into the prompt: `/cron add "0 8 * " "You are creating a briefing for a senior ML engineer who cares about: PyTorch ecosystem, transformer architectures, open-weight models, and AI regulation in the EU. Skip stories about product launches or funding rounds unless they involve open source. Search for the latest news on these topics. Summarize the top 3 stories with links. Be concise and technical — this reader doesn't need basic explanations."` :::tip Tailor the persona Including details about who the briefing is for* dramatically improves relevance. Tell the agent your role, interests, and what to skip. ::: ## Step 4: Manage Your Jobs ### List All Scheduled Jobs In chat: `/cron list` Or from the terminal: `bash hermes cron list` You’ll see output like: `ID | Name | Schedule | Next Run | Deliver ------------|-------------------|-------------|--------------------|-------- a1b2c3d4 | Morning Briefing | 0 8 * * * | 2026-03-09 08:00 | telegram e5f6g7h8 | Evening Recap | 0 18 * * * | 2026-03-08 18:00 | telegram` ### Remove a Job In chat: `/cron remove a1b2c3d4` Or ask conversationally: `Remove my morning briefing cron job.` Hermes will use `cronjob(action="list")` to find it and `cronjob(action="remove")` to delete it. ### Check Gateway Status Make sure the scheduler is actually running: `bash hermes cron status` If the gateway isn’t running, your jobs won’t execute. Install it as a background service for reliability: `bash hermes gateway install # or on Linux servers sudo hermes gateway install --system` ## Going Further You’ve built a working daily briefing bot. Here are some directions to explore next: - Scheduled Tasks (Cron) — Full reference for schedule formats, repeat limits, and delivery options - Delegation — Deep dive into parallel sub-agent workflows - Messaging Platforms — Set up Telegram, Discord, or other delivery targets - Memory — Persistent context across sessions - Tips & Best Practices — More prompt engineering advice :::tip What else can you schedule? The briefing bot pattern works for anything: competitor monitoring, GitHub repo summaries, weather forecasts, portfolio tracking, server health checks, or even a daily joke. If you can describe it in a prompt, you can schedule it. ::: — # Tutorial: Team Telegram Assistant # Set Up a Team Telegram Assistant This tutorial walks you through setting up a Telegram bot powered by Hermes Agent that multiple team members can use. By the end, your team will have a shared AI assistant they can message for help with code, research, system administration, and anything else — secured with per-user authorization. ## What We’re Building A Telegram bot that: - Any authorized team member can DM for help — code reviews, research, shell commands, debugging - Runs on your server with full tool access — terminal, file editing, web search, code execution - Per-user sessions — each person gets their own conversation context - Secure by default — only approved users can interact, with two authorization methods - Scheduled tasks — daily standups, health checks, and reminders delivered to a team channel — ## Prerequisites Before starting, make sure you have: - Hermes Agent installed on a server or VPS (not your laptop — the bot needs to stay running). Follow the installation guide if you haven’t yet. - A Telegram account for yourself (the bot owner) - An LLM provider configured — at minimum, an API key for OpenAI, Anthropic, or another supported provider in `~/.hermes/.env` :::tip A $5/month VPS is plenty for running the gateway. Hermes itself is lightweight — the LLM API calls are what cost money, and those happen remotely. ::: — ## Step 1: Create a Telegram Bot Every Telegram bot starts with @BotFather — Telegram’s official bot for creating bots. 1. Open Telegram and search for `@BotFather`, or go to t.me/BotFather 2. Send `/newbot` — BotFather will ask you two things: - Display name — what users see (e.g., `Team Hermes Assistant`) - Username — must end in `bot` (e.g., `myteam_hermes_bot`) 3. Copy the bot token — BotFather replies with something like: `Use this token to access the HTTP API: 7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...` Save this token — you’ll need it in the next step. 4. Set a description (optional but recommended): `/setdescription` Choose your bot, then enter something like: `Team AI assistant powered by Hermes Agent. DM me for help with code, research, debugging, and more.` 5. Set bot commands (optional — gives users a command menu): `/setcommands` Choose your bot, then paste: `new - Start a fresh conversation model - Show or change the AI model status - Show session info help - Show available commands stop - Stop the current task` :::warning Keep your bot token secret. Anyone with the token can control the bot. If it leaks, use `/revoke` in BotFather to generate a new one. ::: — ## Step 2: Configure the Gateway You have two options: the interactive setup wizard (recommended) or manual configuration. ### Option A: Interactive Setup (Recommended) `bash hermes gateway setup` This walks you through everything with arrow-key selection. Pick Telegram, paste your bot token, and enter your user ID when prompted. ### Option B: Manual Configuration Add these lines to `~/.hermes/.env`: `bash # Telegram bot token from BotFather TELEGRAM_BOT_TOKEN=7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp... # Your Telegram user ID (numeric) TELEGRAM_ALLOWED_USERS=123456789` ### Finding Your User ID Your Telegram user ID is a numeric value (not your username). To find it: 1. Message @userinfobot on Telegram 2. It instantly replies with your numeric user ID 3. Copy that number into `TELEGRAM_ALLOWED_USERS` :::info Telegram user IDs are permanent numbers like `123456789`. They’re different from your `@username`, which can change. Always use the numeric ID for allowlists. ::: — ## Step 3: Start the Gateway ### Quick Test Run the gateway in the foreground first to make sure everything works: `bash hermes gateway` You should see output like: `[Gateway] Starting Hermes Gateway... [Gateway] Telegram adapter connected [Gateway] Cron scheduler started (tick every 60s)` Open Telegram, find your bot, and send it a message. If it replies, you’re in business. Press `Ctrl+C` to stop. ### Production: Install as a Service For a persistent deployment that survives reboots: `bash hermes gateway install sudo hermes gateway install --system # Linux only: boot-time system service` This creates a background service: a user-level systemd service on Linux by default, a launchd service on macOS, or a boot-time Linux system service if you pass `--system`. `bash # Linux — manage the default user service hermes gateway start hermes gateway stop hermes gateway status # View live logs journalctl --user -u hermes-gateway -f # Keep running after SSH logout sudo loginctl enable-linger $USER # Linux servers — explicit system-service commands sudo hermes gateway start --system sudo hermes gateway status --system journalctl -u hermes-gateway -f` `bash # macOS — manage the service hermes gateway start hermes gateway stop tail -f ~/.hermes/logs/gateway.log` :::tip macOS PATH The launchd plist captures your shell PATH at install time so gateway subprocesses can find tools like Node.js and ffmpeg. If you install new tools later, re-run `hermes gateway install` to update the plist. ::: ### Verify It’s Running `bash hermes gateway status` Then send a test message to your bot on Telegram. You should get a response within a few seconds. — ## Step 4: Set Up Team Access Now let’s give your teammates access. There are two approaches. ### Approach A: Static Allowlist Collect each team member’s Telegram user ID (have them message @userinfobot) and add them as a comma-separated list: `bash # In ~/.hermes/.env TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555` Restart the gateway after changes: `bash hermes gateway stop && hermes gateway start` ### Approach B: DM Pairing (Recommended for Teams) DM pairing is more flexible — you don’t need to collect user IDs upfront. Here’s how it works: 1. Teammate DMs the bot — since they’re not on the allowlist, the bot replies with a one-time pairing code: `🔐 Pairing code: XKGH5N7P Send this code to the bot owner for approval.` 2. Teammate sends you the code (via any channel — Slack, email, in person) 3. You approve it on the server: `bash hermes pairing approve telegram XKGH5N7P` 4. They’re in — the bot immediately starts responding to their messages Managing paired users: `bash # See all pending and approved users hermes pairing list # Revoke someone's access hermes pairing revoke telegram 987654321 # Clear expired pending codes hermes pairing clear-pending` :::tip DM pairing is ideal for teams because you don’t need to restart the gateway when adding new users. Approvals take effect immediately. ::: ### Security Considerations - Never set `GATEWAY_ALLOW_ALL_USERS=true` on a bot with terminal access — anyone who finds your bot could run commands on your server - Pairing codes expire after 1 hour and use cryptographic randomness - Rate limiting prevents brute-force attacks: 1 request per user per 10 minutes, max 3 pending codes per platform - After 5 failed approval attempts, the platform enters a 1-hour lockout - All pairing data is stored with `chmod 0600` permissions — ## Step 5: Configure the Bot ### Set a Home Channel A home channel is where the bot delivers cron job results and proactive messages. Without one, scheduled tasks have nowhere to send output. Option 1: Use the `/sethome` command in any Telegram group or chat where the bot is a member. Option 2: Set it manually in `~/.hermes/.env`: `bash TELEGRAM_HOME_CHANNEL=-1001234567890 TELEGRAM_HOME_CHANNEL_NAME="Team Updates"` To find a channel ID, add @userinfobot to the group — it will report the group’s chat ID. ### Configure Tool Progress Display Control how much detail the bot shows when using tools. In `~/.hermes/config.yaml`: `yaml display: tool_progress: new # off | new | all | verbose` | Mode | What You See | |——|———––| | `off` | Clean responses only — no tool activity | | `new` | Brief status for each new tool call (recommended for messaging) | | `all` | Every tool call with details | | `verbose` | Full tool output including command results | Users can also change this per-session with the `/verbose` command in chat. ### Set Up a Personality with SOUL.md Customize how the bot communicates by editing `~/.hermes/SOUL.md`: For a full guide, see Use SOUL.md with Hermes. `markdown # Soul You are a helpful team assistant. Be concise and technical. Use code blocks for any code. Skip pleasantries — the team values directness. When debugging, always ask for error logs before guessing at solutions.` ### Add Project Context If your team works on specific projects, create context files so the bot knows your stack: `markdown  # Team Context - We use Python 3.12 with FastAPI and SQLAlchemy - Frontend is React with TypeScript - CI/CD runs on GitHub Actions - Production deploys to AWS ECS - Always suggest writing tests for new code` :::info Context files are injected into every session’s system prompt. Keep them concise — every character counts against your token budget. ::: — ## Step 6: Set Up Scheduled Tasks With the gateway running, you can schedule recurring tasks that deliver results to your team channel. ### Daily Standup Summary Message the bot on Telegram: `Every weekday at 9am, check the GitHub repository at github.com/myorg/myproject for: 1. Pull requests opened/merged in the last 24 hours 2. Issues created or closed 3. Any CI/CD failures on the main branch Format as a brief standup-style summary.` The agent creates a cron job automatically and delivers results to the chat where you asked (or the home channel). ### Server Health Check `Every 6 hours, check disk usage with 'df -h', memory with 'free -h', and Docker container status with 'docker ps'. Report anything unusual — partitions above 80%, containers that have restarted, or high memory usage.` ### Managing Scheduled Tasks `bash # From the CLI hermes cron list # View all scheduled jobs hermes cron status # Check if scheduler is running # From Telegram chat /cron list # View jobs /cron remove <job_id> # Remove a job` :::warning Cron job prompts run in completely fresh sessions with no memory of prior conversations. Make sure each prompt contains all the context the agent needs — file paths, URLs, server addresses, and clear instructions. ::: — ## Production Tips ### Use Docker for Safety On a shared team bot, use Docker as the terminal backend so agent commands run in a container instead of on your host: `bash # In ~/.hermes/.env TERMINAL_BACKEND=docker TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20` Or in `~/.hermes/config.yaml`: `yaml terminal: backend: docker container_cpu: 1 container_memory: 5120 container_persistent: true` This way, even if someone asks the bot to run something destructive, your host system is protected. ### Monitor the Gateway `bash # Check if the gateway is running hermes gateway status # Watch live logs (Linux) journalctl --user -u hermes-gateway -f # Watch live logs (macOS) tail -f ~/.hermes/logs/gateway.log` ### Keep Hermes Updated From Telegram, send `/update` to the bot — it will pull the latest version and restart. Or from the server: `bash hermes update hermes gateway stop && hermes gateway start` ### Log Locations | What | Location | |——|–––––| | Gateway logs | `journalctl --user -u hermes-gateway` (Linux) or `~/.hermes/logs/gateway.log` (macOS) | | Cron job output | `~/.hermes/cron/output/{job_id}/{timestamp}.md` | | Cron job definitions | `~/.hermes/cron/jobs.json` | | Pairing data | `~/.hermes/pairing/` | | Session history | `~/.hermes/sessions/` | — ## Going Further You’ve got a working team Telegram assistant. Here are some next steps: - Security Guide — deep dive into authorization, container isolation, and command approval - Messaging Gateway — full reference for gateway architecture, session management, and chat commands - Telegram Setup — platform-specific details including voice messages and TTS - Scheduled Tasks — advanced cron scheduling with delivery options and cron expressions - Context Files — AGENTS.md, SOUL.md, and .cursorrules for project knowledge - Personality — built-in personality presets and custom persona definitions - Add more platforms — the same gateway can simultaneously run Discord, Slack, and WhatsApp — Questions or issues? Open an issue on GitHub — contributions are welcome. — # Using Hermes as a Python Library # Using Hermes as a Python Library Hermes isn’t just a CLI tool. You can import `AIAgent` directly and use it programmatically in your own Python scripts, web applications, or automation pipelines. This guide shows you how. — ## Installation Install Hermes directly from the repository: `bash pip install git+https://github.com/NousResearch/hermes-agent.git` Or with uv: `bash uv pip install git+https://github.com/NousResearch/hermes-agent.git` You can also pin it in your `requirements.txt`: `text hermes-agent @ git+https://github.com/NousResearch/hermes-agent.git` :::tip The same environment variables used by the CLI are required when using Hermes as a library. At minimum, set `OPENROUTER_API_KEY` (or `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` if using direct provider access). ::: — ## Basic Usage The simplest way to use Hermes is the `chat()` method — pass a message, get a string back: `python from run_agent import AIAgent agent = AIAgent( model="anthropic/claude-sonnet-4.6", quiet_mode=True, ) response = agent.chat("What is the capital of France?") print(response)` `chat()` handles the full conversation loop internally — tool calls, retries, everything — and returns just the final text response. :::warning Always set `quiet_mode=True` when embedding Hermes in your own code. Without it, the agent prints CLI spinners, progress indicators, and other terminal output that will clutter your application’s output. ::: — ## Full Conversation Control For more control over the conversation, use `run_conversation()` directly. It returns a dictionary with the full response, message history, and metadata: `python agent = AIAgent( model="anthropic/claude-sonnet-4.6", quiet_mode=True, ) result = agent.run_conversation( user_message="Search for recent Python 3.13 features", task_id="my-task-1", ) print(result["final_response"]) print(f"Messages exchanged: {len(result['messages'])}")` The returned dictionary contains: - `final_response` — The agent’s final text reply - `messages` — The complete message history (system, user, assistant, tool calls) (The `task_id` you pass in is stored on the agent instance for VM isolation but isn’t echoed back in the return dict.) You can also pass a custom system message that overrides the ephemeral system prompt for that call: `python result = agent.run_conversation( user_message="Explain quicksort", system_message="You are a computer science tutor. Use simple analogies.", )` — ## Configuring Tools Control which toolsets the agent has access to using `enabled_toolsets` or `disabled_toolsets`: `python # Only enable web tools (browsing, search) agent = AIAgent( model="anthropic/claude-sonnet-4.6", enabled_toolsets=["web"], quiet_mode=True, ) # Enable everything except terminal access agent = AIAgent( model="anthropic/claude-sonnet-4.6", disabled_toolsets=["terminal"], quiet_mode=True, )` :::tip Use `enabled_toolsets` when you want a minimal, locked-down agent (e.g., only web search for a research bot). Use `disabled_toolsets` when you want most capabilities but need to restrict specific ones (e.g., no terminal access in a shared environment). ::: — ## Multi-turn Conversations Maintain conversation state across multiple turns by passing the message history back in: `python agent = AIAgent( model="anthropic/claude-sonnet-4.6", quiet_mode=True, ) # First turn result1 = agent.run_conversation("My name is Alice") history = result1["messages"] # Second turn — agent remembers the context result2 = agent.run_conversation( "What's my name?", conversation_history=history, ) print(result2["final_response"]) # "Your name is Alice."` The `conversation_history` parameter accepts the `messages` list from a previous result. The agent copies it internally, so your original list is never mutated. — ## Saving Trajectories Enable trajectory saving to capture conversations in ShareGPT format — useful for generating training data or debugging: `python agent = AIAgent( model="anthropic/claude-sonnet-4.6", save_trajectories=True, quiet_mode=True, ) agent.chat("Write a Python function to sort a list") # Saves to trajectory_samples.jsonl in ShareGPT format` Each conversation is appended as a single JSONL line, making it easy to collect datasets from automated runs. — ## Custom System Prompts Use `ephemeral_system_prompt` to set a custom system prompt that guides the agent’s behavior but is not saved to trajectory files (keeping your training data clean): `python agent = AIAgent( model="anthropic/claude-sonnet-4", ephemeral_system_prompt="You are a SQL expert. Only answer database questions.", quiet_mode=True, ) response = agent.chat("How do I write a JOIN query?") print(response)` This is ideal for building specialized agents — a code reviewer, a documentation writer, a SQL assistant — all using the same underlying tooling. — ## Batch Processing For running many prompts in parallel, Hermes includes `batch_runner.py`. It manages concurrent `AIAgent` instances with proper resource isolation: `bash python batch_runner.py --input prompts.jsonl --output results.jsonl` Each prompt gets its own `task_id` and isolated environment. If you need custom batch logic, you can build your own using `AIAgent` directly: python import concurrent.futures from run_agent import AIAgent prompts = [ "Explain recursion", "What is a hash table?", "How does garbage collection work?", ] def process_prompt(prompt): # Create a fresh agent per task for thread safety agent = AIAgent( model="anthropic/claude-sonnet-4", quiet_mode=True, skip_memory=True, ) return agent.chat(prompt) with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor: results = list(executor.map(process_prompt, prompts)) for prompt, result in zip(prompts, results): print(f"Q: {prompt}\nA: {result}\n") :::warning Always create a new `AIAgent` instance per thread or task. The agent maintains internal state (conversation history, tool sessions, iteration counters) that is not thread-safe to share. ::: — ## Integration Examples ### FastAPI Endpoint `python from fastapi import FastAPI from pydantic import BaseModel from run_agent import AIAgent app = FastAPI() class ChatRequest(BaseModel): message: str model: str = "anthropic/claude-sonnet-4" @app.post("/chat") async def chat(request: ChatRequest): agent = AIAgent( model=request.model, quiet_mode=True, skip_context_files=True, skip_memory=True, ) response = agent.chat(request.message) return {"response": response}` ### Discord Bot python import discord from run_agent import AIAgent client = discord.Client(intents=discord.Intents.default()) @client.event async def on_message(message): if message.author == client.user: return if message.content.startswith("!hermes "): query = message.content[8:] agent = AIAgent( model="anthropic/claude-sonnet-4", quiet_mode=True, skip_context_files=True, skip_memory=True, platform="discord", ) response = agent.chat(query) await message.channel.send(response[:2000]) client.run("YOUR_DISCORD_TOKEN") ### CI/CD Pipeline Step `python #!/usr/bin/env python3 """CI step: auto-review a PR diff.""" import subprocess from run_agent import AIAgent diff = subprocess.check_output(["git", "diff", "main...HEAD"]).decode() agent = AIAgent( model="anthropic/claude-sonnet-4", quiet_mode=True, skip_context_files=True, skip_memory=True, disabled_toolsets=["terminal", "browser"], ) review = agent.chat( f"Review this PR diff for bugs, security issues, and style problems:\n\n{diff}" ) print(review)` — ## Key Constructor Parameters | Parameter | Type | Default | Description | |———–|——|———|———––| | `model` | `str` | `""` | Model in OpenRouter format (defaults to empty; resolved from your hermes config at runtime) | | `quiet_mode` | `bool` | `False` | Suppress CLI output | | `enabled_toolsets` | `List[str]` | `None` | Whitelist specific toolsets | | `disabled_toolsets` | `List[str]` | `None` | Blacklist specific toolsets | | `save_trajectories` | `bool` | `False` | Save conversations to JSONL | | `ephemeral_system_prompt` | `str` | `None` | Custom system prompt (not saved to trajectories) | | `max_iterations` | `int` | `90` | Max tool-calling iterations per conversation | | `skip_context_files` | `bool` | `False` | Skip loading AGENTS.md files | | `skip_memory` | `bool` | `False` | Disable persistent memory read/write | | `api_key` | `str` | `None` | API key (falls back to env vars) | | `base_url` | `str` | `None` | Custom API endpoint URL | | `platform` | `str` | `None` | Platform hint (`"discord"`, `"telegram"`, etc.) | — ## Important Notes :::tip - Set `skip_context_files=True` if you don’t want `AGENTS.md` files from the working directory loaded into the system prompt. - Set `skip_memory=True` to prevent the agent from reading or writing persistent memory — recommended for stateless API endpoints. - The `platform` parameter (e.g., `"discord"`, `"telegram"`) injects platform-specific formatting hints so the agent adapts its output style. ::: :::warning - Thread safety: Create one `AIAgent` per thread or task. Never share an instance across concurrent calls. - Resource cleanup: The agent automatically cleans up resources (terminal sessions, browser instances) when a conversation ends. If you’re running in a long-lived process, ensure each conversation completes normally. - Iteration limits: The default `max_iterations=90` is generous. For simple Q&A use cases, consider lowering it (e.g., `max_iterations=10`) to prevent runaway tool-calling loops and control costs. ::: — # Use MCP with Hermes # Use MCP with Hermes This guide shows how to actually use MCP with Hermes Agent in day-to-day workflows. If the feature page explains what MCP is, this guide is about how to get value from it quickly and safely. ## When should you use MCP? Use MCP when: - a tool already exists in MCP form and you do not want to build a native Hermes tool - you want Hermes to operate against a local or remote system through a clean RPC layer - you want fine-grained per-server exposure control - you want to connect Hermes to internal APIs, databases, or company systems without modifying Hermes core Do not use MCP when: - a built-in Hermes tool already solves the job well - the server exposes a huge dangerous tool surface and you are not prepared to filter it - you only need one very narrow integration and a native tool would be simpler and safer ## Mental model Think of MCP as an adapter layer: - Hermes remains the agent - MCP servers contribute tools - Hermes discovers those tools at startup or reload time - the model can use them like normal tools - you control how much of each server is visible That last part matters. Good MCP usage is not just “connect everything.” It is “connect the right thing, with the smallest useful surface.” ## Step 1: install MCP support If you installed Hermes with the standard install script, MCP support is already included (the installer runs `uv pip install -e ".[all]"`). If you installed without extras and need to add MCP separately: `bash cd ~/.hermes/hermes-agent uv pip install -e ".[mcp]"` For npm-based servers, make sure Node.js and `npx` are available. For many Python MCP servers, `uvx` is a nice default. ## Step 2: add one server first Start with a single, safe server. Example: filesystem access to one project directory only. `yaml mcp_servers: project_fs: command: "npx" args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/my-project"]` Then start Hermes: `bash hermes chat` Now ask something concrete: `text Inspect this project and summarize the repo layout.` ## Step 3: verify MCP loaded You can verify MCP in a few ways: - Hermes banner/status should show MCP integration when configured - ask Hermes what tools it has available - use `/reload-mcp` after config changes - check logs if the server failed to connect A practical test prompt: `text Tell me which MCP-backed tools are available right now.` ## Step 4: start filtering immediately Do not wait until later if the server exposes a lot of tools. ### Example: whitelist only what you want `yaml mcp_servers: github: command: "npx" args: ["-y", "@modelcontextprotocol/server-github"] env: GITHUB_PERSONAL_ACCESS_TOKEN: "" tools: include: [list_issues, create_issue, search_code]` This is usually the best default for sensitive systems. ## WSL2: bridge Hermes in WSL to Windows Chrome This is the practical setup when: - Hermes runs inside WSL2 - the browser you want to control is your normal signed-in Chrome on Windows - `/browser connect` is awkward or unreliable from WSL In this setup, Hermes does not connect to Chrome directly. Instead: - Hermes runs in WSL - Hermes starts a local stdio MCP server - that MCP server is launched through Windows interop (`cmd.exe` or `powershell.exe`) - the MCP server attaches to your live Windows Chrome session Mental model: `text Hermes (WSL) -> MCP stdio bridge -> Windows Chrome` ### Why this mode is useful - you keep your real Windows browser profile, cookies, and logins - Hermes stays in its supported Unix environment (WSL2) - browser control is exposed as MCP tools instead of relying on Hermes core browser transport ### Recommended server Use `chrome-devtools-mcp`. If your Windows Chrome already has live remote debugging enabled from `chrome://inspect/#remote-debugging`, add it like this from WSL: `bash hermes mcp add chrome-devtools-win --command cmd.exe --args /c npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics` After saving the server: `bash hermes mcp test chrome-devtools-win` Then start a fresh Hermes session or run: `text /reload-mcp` ### Typical prompt Once loaded, Hermes can use the MCP-prefixed browser tools directly. For example: `text 调用 MCP 工具 mcp_chrome_devtools_win_list_pages，列出当前浏览器标签页。` ### When `/browser connect` is the wrong tool If Hermes runs in WSL and Chrome runs on Windows, `/browser connect` may fail even though Chrome is open and debuggable. Common reasons: - WSL cannot reach the same host-local endpoint Chrome exposes to Windows tools - newer Chrome live-debugging flows are not the same as a classic `ws://localhost:9222` - the browser is easier to attach to from a Windows-side helper like `chrome-devtools-mcp` In those cases, keep `/browser connect` for same-environment setups and use MCP for WSL-to-Windows browser bridging. ### Known pitfalls - Start Hermes from a Windows-mounted path like `/mnt/c/Users/<you>` or `/mnt/c/workspace/...` when using Windows stdio executables through MCP. - If you start Hermes from `/root` or `/home/...`, Windows may emit a `UNC` current-directory warning before the MCP server starts. - If `chrome-devtools-mcp --autoConnect` times out while enumerating pages, reduce background/frozen tabs in Chrome and retry. ### Example: blacklist dangerous actions `yaml mcp_servers: stripe: url: "https://mcp.stripe.com" headers: Authorization: "Bearer " tools: exclude: [delete_customer, refund_payment]` ### Example: disable utility wrappers too `yaml mcp_servers: docs: url: "https://mcp.docs.example.com" tools: prompts: false resources: false` ## What does filtering actually affect? There are two categories of MCP-exposed functionality in Hermes: 1. Server-native MCP tools - filtered with: - `tools.include` - `tools.exclude` 2. Hermes-added utility wrappers - filtered with: - `tools.resources` - `tools.prompts` ### Utility wrappers you may see Resources: - `list_resources` - `read_resource` Prompts: - `list_prompts` - `get_prompt` These wrappers only appear if: - your config allows them, and - the MCP server session actually supports those capabilities So Hermes will not pretend a server has resources/prompts if it does not. ## Common patterns ### Pattern 1: local project assistant Use MCP for a repo-local filesystem or git server when you want Hermes to reason over a bounded workspace. `yaml mcp_servers: fs: command: "npx" args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"] git: command: "uvx" args: ["mcp-server-git", "--repository", "/home/user/project"]` Good prompts: `text Review the project structure and identify where configuration lives.` `text Check the local git state and summarize what changed recently.` ### Pattern 2: GitHub triage assistant `yaml mcp_servers: github: command: "npx" args: ["-y", "@modelcontextprotocol/server-github"] env: GITHUB_PERSONAL_ACCESS_TOKEN: "" tools: include: [list_issues, create_issue, update_issue, search_code] prompts: false resources: false` Good prompts: `text List open issues about MCP, cluster them by theme, and draft a high-quality issue for the most common bug.` `text Search the repo for uses of _discover_and_register_server and explain how MCP tools are registered.` ### Pattern 3: internal API assistant `yaml mcp_servers: internal_api: url: "https://mcp.internal.example.com" headers: Authorization: "Bearer " tools: include: [list_customers, get_customer, list_invoices] resources: false prompts: false` Good prompts: `text Look up customer ACME Corp and summarize recent invoice activity.` This is the sort of place where a strict whitelist is far better than an exclude list. ### Pattern 4: documentation / knowledge servers Some MCP servers expose prompts or resources that are more like shared knowledge assets than direct actions. `yaml mcp_servers: docs: url: "https://mcp.docs.example.com" tools: prompts: true resources: true` Good prompts: `text List available MCP resources from the docs server, then read the onboarding guide and summarize it.` `text List prompts exposed by the docs server and tell me which ones would help with incident response.` ## Tutorial: end-to-end setup with filtering Here is a practical progression. ### Phase 1: add GitHub MCP with a tight whitelist `yaml mcp_servers: github: command: "npx" args: ["-y", "@modelcontextprotocol/server-github"] env: GITHUB_PERSONAL_ACCESS_TOKEN: "" tools: include: [list_issues, create_issue, search_code] prompts: false resources: false` Start Hermes and ask: `text Search the codebase for references to MCP and summarize the main integration points.` ### Phase 2: expand only when needed If you later need issue updates too: `yaml tools: include: [list_issues, create_issue, update_issue, search_code]` Then reload: `text /reload-mcp` ### Phase 3: add a second server with different policy `yaml mcp_servers: github: command: "npx" args: ["-y", "@modelcontextprotocol/server-github"] env: GITHUB_PERSONAL_ACCESS_TOKEN: "" tools: include: [list_issues, create_issue, update_issue, search_code] prompts: false resources: false filesystem: command: "npx" args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]` Now Hermes can combine them: `text Inspect the local project files, then create a GitHub issue summarizing the bug you find.` That is where MCP gets powerful: multi-system workflows without changing Hermes core. ## Safe usage recommendations ### Prefer allowlists for dangerous systems For anything financial, customer-facing, or destructive: - use `tools.include` - start with the smallest set possible ### Disable unused utilities If you do not want the model browsing server-provided resources/prompts, turn them off: `yaml tools: resources: false prompts: false` ### Keep servers scoped narrowly Examples: - filesystem server rooted to one project dir, not your whole home directory - git server pointed at one repo - internal API server with read-heavy tool exposure by default ### Reload after config changes `text /reload-mcp` Do this after changing: - include/exclude lists - enabled flags - resources/prompts toggles - auth headers / env ## Troubleshooting by symptom ### “The server connects but the tools I expected are missing” Possible causes: - filtered by `tools.include` - excluded by `tools.exclude` - utility wrappers disabled via `resources: false` or `prompts: false` - server does not actually support resources/prompts ### “The server is configured but nothing loads” Check: - `enabled: false` was not left in config - command/runtime exists (`npx`, `uvx`, etc.) - HTTP endpoint is reachable - auth env or headers are correct ### “Why do I see fewer tools than the MCP server advertises?” Because Hermes now respects your per-server policy and capability-aware registration. That is expected, and usually desirable. ### “How do I remove an MCP server without deleting the config?” Use: `yaml enabled: false` That keeps the config around but prevents connection and registration. ## Recommended first MCP setups Good first servers for most users: - filesystem - git - GitHub - fetch / documentation MCP servers - one narrow internal API Not-great first servers: - giant business systems with lots of destructive actions and no filtering - anything you do not understand well enough to constrain ## Related docs - MCP (Model Context Protocol) - FAQ - Slash Commands — # Use Voice Mode with Hermes # Use Voice Mode with Hermes This guide is the practical companion to the Voice Mode feature reference. If the feature page explains what voice mode can do, this guide shows how to actually use it well. :::tip Nous Portal bundles both the LLM and TTS through one OAuth — voice mode works end-to-end with no extra credentials. ::: ## What voice mode is good for Voice mode is especially useful when: - you want a hands-free CLI workflow - you want spoken responses in Telegram or Discord - you want Hermes sitting in a Discord voice channel for live conversation - you want quick idea capture, debugging, or back-and-forth while walking around instead of typing ## Choose your voice mode setup There are really three different voice experiences in Hermes. | Mode | Best for | Platform | |—|—|—| | Interactive microphone loop | Personal hands-free use while coding or researching | CLI | | Voice replies in chat | Spoken responses alongside normal messaging | Telegram, Discord | | Live voice channel bot | Group or personal live conversation in a VC | Discord voice channels | A good path is: 1. get text working first 2. enable voice replies second 3. move to Discord voice channels last if you want the full experience ## Step 1: make sure normal Hermes works first Before touching voice mode, verify that: - Hermes starts - your provider is configured - the agent can answer text prompts normally `bash hermes` Ask something simple: `text What tools do you have available?` If that is not solid yet, fix text mode first. ## Step 2: install the right extras ### CLI microphone + playback `bash pip install "hermes-agent[voice]"` ### Messaging platforms `bash pip install "hermes-agent[messaging]"` ### Premium ElevenLabs TTS `bash pip install "hermes-agent[tts-premium]"` ### Local NeuTTS (optional) `bash python -m pip install -U neutts[all]` ### Everything `bash pip install "hermes-agent[all]"` ## Step 3: install system dependencies ### macOS `bash brew install portaudio ffmpeg opus brew install espeak-ng` ### Ubuntu / Debian `bash sudo apt install portaudio19-dev ffmpeg libopus0 sudo apt install espeak-ng` Why these matter: - `portaudio` → microphone input / playback for CLI voice mode - `ffmpeg` → audio conversion for TTS and messaging delivery - `opus` → Discord voice codec support - `espeak-ng` → phonemizer backend for NeuTTS ## Step 4: choose STT and TTS providers Hermes supports both local and cloud speech stacks. ### Easiest / cheapest setup Use local STT and free Edge TTS: - STT provider: `local` - TTS provider: `edge` This is usually the best place to start. ### Environment file example Add to `~/.hermes/.env`: `bash # Cloud STT options (local needs no key) GROQ_API_KEY=* VOICE_TOOLS_OPENAI_KEY=* # Premium TTS (optional) ELEVENLABS_API_KEY=*` ### Provider recommendations #### Speech-to-text - `local` → best default for privacy and zero-cost use - `groq` → very fast cloud transcription - `openai` → good paid fallback #### Text-to-speech - `edge` → free and good enough for most users - `neutts` → free local/on-device TTS - `elevenlabs` → best quality - `openai` → good middle ground - `mistral` → multilingual, native Opus ### If you use `hermes setup` If you choose NeuTTS in the setup wizard, Hermes checks whether `neutts` is already installed. If it is missing, the wizard tells you NeuTTS needs the Python package `neutts` and the system package `espeak-ng`, offers to install them for you, installs `espeak-ng` with your platform package manager, and then runs: `bash python -m pip install -U neutts[all]` If you skip that install or it fails, the wizard falls back to Edge TTS. ## Step 5: recommended config `yaml voice: record_key: "ctrl+b" max_recording_seconds: 120 auto_tts: false beep_enabled: true silence_threshold: 200 silence_duration: 3.0 stt: provider: "local" local: model: "base" tts: provider: "edge" edge: voice: "en-US-AriaNeural"` This is a good conservative default for most people. If you want local TTS instead, switch the `tts` block to: `yaml tts: provider: "neutts" neutts: ref_audio: '' ref_text: '' model: neuphonic/neutts-air-q4-gguf device: cpu` ## Use case 1: CLI voice mode ## Turn it on Start Hermes: `bash hermes` Inside the CLI: `text /voice on` ### Recording flow Default key: - `Ctrl+B` Workflow: 1. press `Ctrl+B` 2. speak 3. wait for silence detection to stop recording automatically 4. Hermes transcribes and responds 5. if TTS is on, it speaks the answer 6. the loop can automatically restart for continuous use ### Useful commands `text /voice /voice on /voice off /voice tts /voice status` ### Good CLI workflows #### Walk-up debugging Say: `text I keep getting a docker permission error. Help me debug it.` Then continue hands-free: - “Read the last error again” - “Explain the root cause in simpler terms” - “Now give me the exact fix” #### Research / brainstorming Great for: - walking around while thinking - dictating half-formed ideas - asking Hermes to structure your thoughts in real time #### Accessibility / low-typing sessions If typing is inconvenient, voice mode is one of the fastest ways to stay in the full Hermes loop. ## Tuning CLI behavior ### Silence threshold If Hermes starts/stops too aggressively, tune: `yaml voice: silence_threshold: 250` Higher threshold = less sensitive. ### Silence duration If you pause a lot between sentences, increase: `yaml voice: silence_duration: 4.0` ### Record key If `Ctrl+B` conflicts with your terminal or tmux habits: `yaml voice: record_key: "ctrl+space"` ## Use case 2: voice replies in Telegram or Discord This mode is simpler than full voice channels. Hermes stays a normal chat bot, but can speak replies. ### Start the gateway `bash hermes gateway` ### Turn on voice replies Inside Telegram or Discord: `text /voice on` or `text /voice tts` ### Modes | Mode | Meaning | |—|—| | `off` | text only | | `voice_only` | speak only when the user sent voice | | `all` | speak every reply | ### When to use which mode - `/voice on` if you want spoken replies only for voice-originating messages - `/voice tts` if you want a full spoken assistant all the time ### Good messaging workflows #### Telegram assistant on your phone Use when: - you are away from your machine - you want to send voice notes and get quick spoken replies - you want Hermes to function like a portable research or ops assistant #### Discord DMs with spoken output Useful when you want private interaction without server-channel mention behavior. ## Use case 3: Discord voice channels This is the most advanced mode. Hermes joins a Discord VC, listens to user speech, transcribes it, runs the normal agent pipeline, and speaks replies back into the channel. ## Required Discord permissions In addition to the normal text-bot setup, make sure the bot has: - Connect - Speak - preferably Use Voice Activity Also enable privileged intents in the Developer Portal: - Presence Intent - Server Members Intent - Message Content Intent ## Join and leave In a Discord text channel where the bot is present: `text /voice join /voice leave /voice status` ### What happens when joined - users speak in the VC - Hermes detects speech boundaries - transcripts are posted in the associated text channel - Hermes responds in text and audio - the text channel is the one where `/voice join` was issued ### Best practices for Discord VC use - keep `DISCORD_ALLOWED_USERS` tight - use a dedicated bot/testing channel at first - verify STT and TTS work in ordinary text-chat voice mode before trying VC mode ## Voice quality recommendations ### Best quality setup - STT: local `large-v3` or Groq `whisper-large-v3` - TTS: ElevenLabs ### Best speed / convenience setup - STT: local `base` or Groq - TTS: Edge ### Best zero-cost setup - STT: local - TTS: Edge ## Common failure modes ### “No audio device found” Install `portaudio`. ### “Bot joins but hears nothing” Check: - your Discord user ID is in `DISCORD_ALLOWED_USERS` - you are not muted - privileged intents are enabled - the bot has Connect/Speak permissions ### “It transcribes but does not speak” Check: - TTS provider config - API key / quota for ElevenLabs or OpenAI - `ffmpeg` install for Edge conversion paths ### “Whisper outputs garbage” Try: - quieter environment - higher `silence_threshold` - different STT provider/model - shorter, clearer utterances ### “It works in DMs but not in server channels” That is often mention policy. By default, the bot needs an `@mention` in Discord server text channels unless configured otherwise. ## Suggested first-week setup If you want the shortest path to success: 1. get text Hermes working 2. install `hermes-agent[voice]` 3. use CLI voice mode with local STT + Edge TTS 4. then enable `/voice on` in Telegram or Discord 5. only after that, try Discord VC mode That progression keeps the debugging surface small. ## Where to read next - Voice Mode feature reference - Messaging Gateway - Discord setup - Telegram setup - Configuration — # Use SOUL.md with Hermes # Use SOUL.md with Hermes `SOUL.md` is the primary identity for your Hermes instance. It’s the first thing in the system prompt — it defines who the agent is, how it speaks, and what it avoids. If you want Hermes to feel like the same assistant every time you talk to it — or if you want to replace the Hermes persona entirely with your own — this is the file to use. ## What SOUL.md is for Use `SOUL.md` for: - tone - personality - communication style - how direct or warm Hermes should be - what Hermes should avoid stylistically - how Hermes should relate to uncertainty, disagreement, and ambiguity In short: - `SOUL.md` is about who Hermes is and how Hermes speaks ## What SOUL.md is not for Do not use it for: - repo-specific coding conventions - file paths - commands - service ports - architecture notes - project workflow instructions Those belong in `AGENTS.md`. A good rule: - if it should apply everywhere, put it in `SOUL.md` - if it only belongs to one project, put it in `AGENTS.md` ## Where it lives Hermes now uses only the global SOUL file for the current instance: `text ~/.hermes/SOUL.md` If you run Hermes with a custom home directory, it becomes: `text $HERMES_HOME/SOUL.md` ## First-run behavior Hermes automatically seeds a starter `SOUL.md` for you if one does not already exist. That means most users now begin with a real file they can read and edit immediately. Important: - if you already have a `SOUL.md`, Hermes does not overwrite it - if the file exists but is empty, Hermes adds nothing from it to the prompt ## How Hermes uses it When Hermes starts a session, it reads `SOUL.md` from `HERMES_HOME`, scans it for prompt-injection patterns, truncates it if needed, and uses it as the agent identity** — slot #1 in the system prompt. This means SOUL.md completely replaces the built-in default identity text. If SOUL.md is missing, empty, or cannot be loaded, Hermes falls back to a built-in default identity. No wrapper language is added around the file. The content itself matters — write the way you want your agent to think and speak. ## A good first edit If you do nothing else, open the file and change just a few lines so it feels like you. For example: `markdown You are direct, calm, and technically precise. Prefer substance over politeness theater. Push back clearly when an idea is weak. Keep answers compact unless deeper detail is useful.` That alone can noticeably change how Hermes feels. ## Example styles ### 1. Pragmatic engineer `markdown You are a pragmatic senior engineer. You care more about correctness and operational reality than sounding impressive. ## Style - Be direct - Be concise unless complexity requires depth - Say when something is a bad idea - Prefer practical tradeoffs over idealized abstractions ## Avoid - Sycophancy - Hype language - Overexplaining obvious things` ### 2. Research partner `markdown You are a thoughtful research collaborator. You are curious, honest about uncertainty, and excited by unusual ideas. ## Style - Explore possibilities without pretending certainty - Distinguish speculation from evidence - Ask clarifying questions when the idea space is underspecified - Prefer conceptual depth over shallow completeness` ### 3. Teacher / explainer `markdown You are a patient technical teacher. You care about understanding, not performance. ## Style - Explain clearly - Use examples when they help - Do not assume prior knowledge unless the user signals it - Build from intuition to details` ### 4. Tough reviewer `markdown You are a rigorous reviewer. You are fair, but you do not soften important criticism. ## Style - Point out weak assumptions directly - Prioritize correctness over harmony - Be explicit about risks and tradeoffs - Prefer blunt clarity to vague diplomacy` ## What makes a strong SOUL.md? A strong `SOUL.md` is: - stable - broadly applicable - specific in voice - not overloaded with temporary instructions A weak `SOUL.md` is: - full of project details - contradictory - trying to micro-manage every response shape - mostly generic filler like “be helpful” and “be clear” Hermes already tries to be helpful and clear. `SOUL.md` should add real personality and style, not restate obvious defaults. ## Suggested structure You do not need headings, but they help. A simple structure that works well: `markdown # Identity Who Hermes is. # Style How Hermes should sound. # Avoid What Hermes should not do. # Defaults How Hermes should behave when ambiguity appears.` ## SOUL.md vs /personality These are complementary. Use `SOUL.md` for your durable baseline. Use `/personality` for temporary mode switches. Examples: - your default SOUL is pragmatic and direct - then for one session you use `/personality teacher` - later you switch back without changing your base voice file ## SOUL.md vs AGENTS.md This is the most common mistake. ### Put this in SOUL.md - “Be direct.” - “Avoid hype language.” - “Prefer short answers unless depth helps.” - “Push back when the user is wrong.” ### Put this in AGENTS.md - “Use pytest, not unittest.” - “Frontend lives in `frontend/`.” - “Never edit migrations directly.” - “The API runs on port 8000.” ## How to edit it `bash nano ~/.hermes/SOUL.md` or `bash vim ~/.hermes/SOUL.md` Then restart Hermes or start a new session. ## A practical workflow 1. Start with the seeded default file 2. Trim anything that does not feel like the voice you want 3. Add 4–8 lines that clearly define tone and defaults 4. Talk to Hermes for a while 5. Adjust based on what still feels off That iterative approach works better than trying to design the perfect personality in one shot. ## Troubleshooting ### I edited SOUL.md but Hermes still sounds the same Check: - you edited `~/.hermes/SOUL.md` or `$HERMES_HOME/SOUL.md` - not some repo-local `SOUL.md` - the file is not empty - your session was restarted after the edit - a `/personality` overlay is not dominating the result ### Hermes is ignoring parts of my SOUL.md Possible causes: - higher-priority instructions are overriding it - the file includes conflicting guidance - the file is too long and got truncated - some of the text resembles prompt-injection content and may be blocked or altered by the scanner ### My SOUL.md became too project-specific Move project instructions into `AGENTS.md` and keep `SOUL.md` focused on identity and style. ## Related docs - Personality & SOUL.md - Context Files - Configuration - Tips & Best Practices — # Build a Hermes Plugin # Build a Hermes Plugin This guide walks through building a complete Hermes plugin from scratch. By the end you’ll have a working plugin with multiple tools, lifecycle hooks, shipped data files, and a bundled skill — everything the plugin system supports. :::info Not sure which guide you need? Hermes has several distinct pluggable interfaces — some use Python `register_*` APIs, others are config-driven or drop-in directories. Use this map first: | If you want to add… | Read | |—|—| | Custom tools, hooks, slash commands, skills, or CLI subcommands | This guide (the general plugin surface) | | An LLM / inference backend (new provider) | Model Provider Plugins | | A gateway channel (Discord/Telegram/IRC/Teams/etc.) | Adding Platform Adapters | | A memory backend (Honcho/Mem0/Supermemory/etc.) | Memory Provider Plugins | | A context-compression engine | Context Engine Plugins | | An image-generation backend | Image Generation Provider Plugins | | A video-generation backend | Video Generation Provider Plugins | | A TTS backend (any CLI — Piper, VoxCPM, Kokoro, voice cloning, …) | TTS custom command providers — config-driven, no Python needed | | An STT backend (custom whisper / ASR CLI) | Voice Message Transcription — set `HERMES_LOCAL_STT_COMMAND` to a shell template | | External tools via MCP (filesystem, GitHub, Linear, any MCP server) | MCP — declare `mcp_servers.<name>` in `config.yaml` | | Gateway event hooks (fire on startup, session events, commands) | Event Hooks — drop `HOOK.yaml` + `handler.py` into `~/.hermes/hooks/<name>/` | | Shell hooks (run a shell command on events) | Shell Hooks — declare under `hooks:` in `config.yaml` | | Additional skill sources (custom GitHub repos, private skill indexes) | Skills — `hermes skills tap add <repo>` · Publishing a tap | | A first-class core inference provider (not a plugin) | Adding Providers | See the full Pluggable interfaces table for a consolidated view of every extension surface including config-driven (TTS, STT, MCP, shell hooks) and drop-in directory (gateway hooks) styles. ::: ## What you’re building A calculator plugin with two tools: - `calculate` — evaluate math expressions (`2**16`, `sqrt(144)`, `pi * 5**2`) - `unit_convert` — convert between units (`100 F → 37.78 C`, `5 km → 3.11 mi`) Plus a hook that logs every tool call, and a bundled skill file. ## Step 1: Create the plugin directory `bash mkdir -p ~/.hermes/plugins/calculator cd ~/.hermes/plugins/calculator` ## Step 2: Write the manifest Create `plugin.yaml`: `yaml name: calculator version: 1.0.0 description: Math calculator — evaluate expressions and convert units provides_tools: - calculate - unit_convert provides_hooks: - post_tool_call` This tells Hermes: “I’m a plugin called calculator, I provide tools and hooks.” The `provides_tools` and `provides_hooks` fields are lists of what the plugin registers. Optional fields you could add: `yaml author: Your Name requires_env: # gate loading on env vars; prompted during install - SOME_API_KEY # simple format — plugin disabled if missing - name: OTHER_KEY # rich format — shows description/url during install description: "Key for the Other service" url: "https://other.com/keys" secret: true` ## Step 3: Write the tool schemas Create `schemas.py` — this is what the LLM reads to decide when to call your tools: python """Tool schemas — what the LLM sees.""" CALCULATE = { "name": "calculate", "description": ( "Evaluate a mathematical expression and return the result. " "Supports arithmetic (+, -, *, /, ), functions (sqrt, sin, cos, " "log, abs, round, floor, ceil), and constants (pi, e). " "Use this for any math the user asks about." ), "parameters": { "type": "object", "properties": { "expression": { "type": "string", "description": "Math expression to evaluate (e.g., '210', 'sqrt(144)')", }, }, "required": ["expression"], }, } UNIT_CONVERT = { "name": "unit_convert", "description": ( "Convert a value between units. Supports length (m, km, mi, ft, in), " "weight (kg, lb, oz, g), temperature (C, F, K), data (B, KB, MB, GB, TB), " "and time (s, min, hr, day)." ), "parameters": { "type": "object", "properties": { "value": { "type": "number", "description": "The numeric value to convert", }, "from_unit": { "type": "string", "description": "Source unit (e.g., 'km', 'lb', 'F', 'GB')", }, "to_unit": { "type": "string", "description": "Target unit (e.g., 'mi', 'kg', 'C', 'MB')", }, }, "required": ["value", "from_unit", "to_unit"], }, } Why schemas matter: The `description` field is how the LLM decides when to use your tool. Be specific about what it does and when to use it. The `parameters` define what arguments the LLM passes. ## Step 4: Write the tool handlers Create `tools.py` — this is the code that actually executes when the LLM calls your tools: python """Tool handlers — the code that runs when the LLM calls each tool.""" import json import math # Safe globals for expression evaluation — no file/network access _SAFE_MATH = { "abs": abs, "round": round, "min": min, "max": max, "pow": pow, "sqrt": math.sqrt, "sin": math.sin, "cos": math.cos, "tan": math.tan, "log": math.log, "log2": math.log2, "log10": math.log10, "floor": math.floor, "ceil": math.ceil, "pi": math.pi, "e": math.e, "factorial": math.factorial, } def calculate(args: dict, kwargs) -> str: """Evaluate a math expression safely. Rules for handlers: 1. Receive args (dict) — the parameters the LLM passed 2. Do the work 3. Return a JSON string — ALWAYS, even on error 4. Accept kwargs for forward compatibility """ expression = args.get("expression", "").strip() if not expression: return json.dumps({"error": "No expression provided"}) try: result = eval(expression, {"builtins": {}}, _SAFE_MATH) return json.dumps({"expression": expression, "result": result}) except ZeroDivisionError: return json.dumps({"expression": expression, "error": "Division by zero"}) except Exception as e: return json.dumps({"expression": expression, "error": f"Invalid: {e}"}) # Conversion tables — values are in base units _LENGTH = {"m": 1, "km": 1000, "mi": 1609.34, "ft": 0.3048, "in": 0.0254, "cm": 0.01} _WEIGHT = {"kg": 1, "g": 0.001, "lb": 0.453592, "oz": 0.0283495} _DATA = {"B": 1, "KB": 1024, "MB": 10242, "GB": 10243, "TB": 1024**4} _TIME = {"s": 1, "ms": 0.001, "min": 60, "hr": 3600, "day": 86400} def _convert_temp(value, from_u, to_u): # Normalize to Celsius c = {"F": (value - 32) * 5/9, "K": value - 273.15}.get(from_u, value) # Convert to target return {"F": c * 9/5 + 32, "K": c + 273.15}.get(to_u, c) def unit_convert(args: dict, **kwargs) -> str: """Convert between units.""" value = args.get("value") from_unit = args.get("from_unit", "").strip() to_unit = args.get("to_unit", "").strip() if value is None or not from_unit or not to_unit: return json.dumps({"error": "Need value, from_unit, and to_unit"}) try: # Temperature if from_unit.upper() in {"C","F","K"} and to_unit.upper() in {"C","F","K"}: result = _convert_temp(float(value), from_unit.upper(), to_unit.upper()) return json.dumps({"input": f"{value} {from_unit}", "result": round(result, 4), "output": f"{round(result, 4)} {to_unit}"}) # Ratio-based conversions for table in (_LENGTH, _WEIGHT, _DATA, _TIME): lc = {k.lower(): v for k, v in table.items()} if from_unit.lower() in lc and to_unit.lower() in lc: result = float(value) * lc[from_unit.lower()] / lc[to_unit.lower()] return json.dumps({"input": f"{value} {from_unit}", "result": round(result, 6), "output": f"{round(result, 6)} {to_unit}"}) return json.dumps({"error": f"Cannot convert {from_unit} → {to_unit}"}) except Exception as e: return json.dumps({"error": f"Conversion failed: {e}"}) Key rules for handlers: 1. Signature: `def my_handler(args: dict, kwargs) -> str` 2. Return: Always a JSON string. Success and errors alike. 3. Never raise: Catch all exceptions, return error JSON instead. 4. Accept `kwargs`: Hermes may pass additional context in the future. ## Step 5: Write the registration Create `init.py` — this wires schemas to handlers: python """Calculator plugin — registration.""" import logging from . import schemas, tools logger = logging.getLogger(name) # Track tool usage via hooks _call_log = [] def _on_post_tool_call(tool_name, args, result, task_id, kwargs): """Hook: runs after every tool call (not just ours).""" _call_log.append({"tool": tool_name, "session": task_id}) if len(_call_log) > 100: _call_log.pop(0) logger.debug("Tool called: %s (session %s)", tool_name, task_id) def register(ctx): """Wire schemas to handlers and register hooks.""" ctx.register_tool(name="calculate", toolset="calculator", schema=schemas.CALCULATE, handler=tools.calculate) ctx.register_tool(name="unit_convert", toolset="calculator", schema=schemas.UNIT_CONVERT, handler=tools.unit_convert) # This hook fires for ALL tool calls, not just ours ctx.register_hook("post_tool_call", _on_post_tool_call) What `register()` does: - Called exactly once at startup - `ctx.register_tool()` puts your tool in the registry — the model sees it immediately - `ctx.register_hook()` subscribes to lifecycle events - `ctx.register_cli_command()` registers a CLI subcommand (e.g. `hermes my-plugin <subcommand>`) - `ctx.register_command()` registers an in-session slash command (e.g. `/myplugin <args>` inside CLI / gateway chat) — see Register slash commands below - `ctx.dispatch_tool(name, arguments)` — call any other tool (built-in or from another plugin) with the parent agent’s context (approvals, credentials, task_id) wired up automatically. Useful from slash-command handlers that need to invoke `terminal`, `read_file`, or any other tool as if the model had called it directly. - If this function crashes, the plugin is disabled but Hermes continues fine `dispatch_tool` example — a slash command that runs a tool: `python def handle_scan(ctx, raw_args: str): """Implement /scan by invoking the terminal tool through the registry.""" result = ctx.dispatch_tool("terminal", {"command": f"find . -name '{raw_args}'"}) return result # returned to the caller's chat UI def register(ctx): # Handlers receive a single raw_args string; close over ctx via a lambda. ctx.register_command( "scan", lambda raw: handle_scan(ctx, raw), description="Find files matching a glob", )` The dispatched tool goes through the normal approval, redaction, and budget pipelines — it’s a real tool invocation, not a shortcut around them. ## Step 6: Test it Start Hermes: `bash hermes` You should see `calculator: calculate, unit_convert` in the banner’s tool list. Try these prompts: `What's 2 to the power of 16? Convert 100 fahrenheit to celsius What's the square root of 2 times pi? How many gigabytes is 1.5 terabytes?` Check plugin status: `/plugins` Output: `Plugins (1): ✓ calculator v1.0.0 (2 tools, 1 hooks)` ### Debugging plugin discovery If your plugin doesn’t show up — or shows up but isn’t loading — set `HERMES_PLUGINS_DEBUG=1` to get verbose discovery logs on stderr: `bash HERMES_PLUGINS_DEBUG=1 hermes plugins list` You’ll see, for every plugin source (bundled, user, project, entry-points): - which directories were scanned and how many manifests each yielded - per manifest: resolved key, name, kind, source, on-disk path - skip reasons: `disabled via config`, `not enabled in config`, `exclusive plugin`, `no plugin.yaml, depth cap reached` - on load: the plugin being imported, plus a one-line summary of what `register(ctx)` registered (tools, hooks, slash commands, CLI commands) - on parse failure: a full traceback for the exception (YAML scanner errors, etc.) - on `register()` failure: a full traceback pointing at the line in your `init.py` that raised The same logs are always written to `~/.hermes/logs/agent.log` at WARNING level (failures only) and DEBUG level (everything) when the env var is set. So if you can’t run with the env var (e.g. from inside the gateway), tail the log file instead: `bash hermes logs --level WARNING | grep -i plugin` Common reasons a plugin doesn’t appear: - Not enabled in config — plugins are opt-in. Run `hermes plugins enable <name>` (the name comes from the `plugins list` output, which can be `<category>/<plugin>` for nested layouts). - Wrong directory layout — must be `~/.hermes/plugins/<plugin-name>/plugin.yaml` (flat) or `~/.hermes/plugins/<category>/<plugin-name>/plugin.yaml` (one level of category nesting, max). Anything deeper is ignored. - Missing `init.py` — the plugin directory needs both `plugin.yaml` and `init.py` with a `register(ctx)` function. - Wrong `kind` — gateway adapters need `kind: platform` in their manifest. Memory providers are auto-detected as `kind: exclusive` and routed through the `memory.provider` config instead of `plugins.enabled`. ## Your plugin’s final structure `~/.hermes/plugins/calculator/ ├── plugin.yaml # "I'm calculator, I provide tools and hooks" ├── init.py # Wiring: schemas → handlers, register hooks ├── schemas.py # What the LLM reads (descriptions + parameter specs) └── tools.py # What runs (calculate, unit_convert functions)` Four files, clear separation: - Manifest declares what the plugin is - Schemas describe tools for the LLM - Handlers implement the actual logic - Registration connects everything ## What else can plugins do? ### Ship data files Put any files in your plugin directory and read them at import time: `python # In tools.py or init.py from pathlib import Path _PLUGIN_DIR = Path(file).parent _DATA_FILE = _PLUGIN_DIR / "data" / "languages.yaml" with open(_DATA_FILE) as f: _DATA = yaml.safe_load(f)` ### Bundle skills Plugins can ship skill files that the agent loads via `skill_view("plugin:skill")`. Register them in your `init.py`: `~/.hermes/plugins/my-plugin/ ├── init.py ├── plugin.yaml └── skills/ ├── my-workflow/ │ └── SKILL.md └── my-checklist/ └── SKILL.md` `python from pathlib import Path def register(ctx): skills_dir = Path(file).parent / "skills" for child in sorted(skills_dir.iterdir()): skill_md = child / "SKILL.md" if child.is_dir() and skill_md.exists(): ctx.register_skill(child.name, skill_md)` The agent can now load your skills with their namespaced name: `python skill_view("my-plugin:my-workflow") # → plugin's version skill_view("my-workflow") # → built-in version (unchanged)` Key properties: - Plugin skills are read-only — they don’t enter `~/.hermes/skills/` and can’t be edited via `skill_manage`. - Plugin skills are not listed in the system prompt’s `<available_skills>` index — they’re opt-in explicit loads. - Bare skill names are unaffected — the namespace prevents collisions with built-in skills. - When the agent loads a plugin skill, a bundle context banner is prepended listing sibling skills from the same plugin. :::tip Legacy pattern The old `shutil.copy2` pattern (copying a skill into `~/.hermes/skills/`) still works but creates name collision risk with built-in skills. Prefer `ctx.register_skill()` for new plugins. ::: ### Gate on environment variables If your plugin needs an API key: `yaml # plugin.yaml — simple format (backwards-compatible) requires_env: - WEATHER_API_KEY` If `WEATHER_API_KEY` isn’t set, the plugin is disabled with a clear message. No crash, no error in the agent — just “Plugin weather disabled (missing: WEATHER_API_KEY)”. When users run `hermes plugins install`, they’re prompted interactively for any missing `requires_env` variables. Values are saved to `.env` automatically. For a better install experience, use the rich format with descriptions and signup URLs: `yaml # plugin.yaml — rich format requires_env: - name: WEATHER_API_KEY description: "API key for OpenWeather" url: "https://openweathermap.org/api" secret: true` | Field | Required | Description | |—––|–––––|———––| | `name` | Yes | Environment variable name | | `description` | No | Shown to user during install prompt | | `url` | No | Where to get the credential | | `secret` | No | If `true`, input is hidden (like a password field) | Both formats can be mixed in the same list. Already-set variables are skipped silently. ### Lazy-install optional Python dependencies If your plugin wraps an SDK that not every user will have installed (a vendor SDK, a heavy ML lib, a platform-specific package), don’t `import` it at the top of the module. Use the `tools.lazy_deps.ensure(...)` helper inside the tool handler — Hermes will install the package on first use, gated by the user’s `security.allow_lazy_installs` config. `python # tools.py from tools.lazy_deps import ensure, FeatureUnavailable def my_tool_handler(args, kwargs): try: ensure("my-plugin.my-backend") # key must be in LAZY_DEPS except FeatureUnavailable as exc: return {"error": str(exc)} import my_backend_sdk # safe now ...` Two rules from the security model in `tools/lazy_deps.py`: | Rule | Why | |—|—| | Your feature key must appear in the in-tree `LAZY_DEPS` allowlist | Prevents a malicious config from coaxing Hermes into installing arbitrary packages — only specs Hermes itself ships are eligible | | Specs are PyPI-by-name only | No `--index-url`, `git+https://`, or file: paths. Pin versions with PEP 440 (`"my-sdk>=1.2,<2"`) inside the allowlist entry | For third-party plugins distributed via pip, declare the optional deps as `[project.optional-dependencies]` extras in your own `pyproject.toml` and tell users to `pip install your-plugin[backend]` — that path doesn’t go through `lazy_deps`. The lazy-install dance is most useful for bundled plugins where shipping a hard dependency on every install would bloat the base Hermes footprint. When `security.allow_lazy_installs: false` is set globally, `ensure()` raises `FeatureUnavailable` immediately with a remediation hint — your plugin should catch it and degrade gracefully (return an error result, not crash the tool loop). ### Thread-safe lazy singletons Plugins often cache an expensive object — an SDK client, an HTTP session, a connection pool — in a module-level variable built on first use: `python _client = None def get_client(): global _client if _client is not None: return _client _client = ExpensiveClient(...) # ← TOCTOU race return _client` This is a footgun. Hermes runs multiple threads in one process (delegated tool calls, background workers, the self-improvement fork), so two threads can hit `get_client()` before `_client` is set, both pass the `is not None` check, both run the expensive build, and the second write clobbers the first — leaking whatever resource the loser opened (connection, file handle, background thread). Don’t hand-roll the lock. Use the helpers in `plugins/plugin_utils.py`: python from plugins.plugin_utils import lazy_singleton, SingletonSlot # Zero-arg accessor → decorate it: @lazy_singleton def get_client(): return ExpensiveClient(load_config()) # runs exactly once client = get_client() # safe across threads get_client.reset() # drop the instance (tests / teardown) # Accessor that takes a build argument → use a slot: _slot: SingletonSlot = SingletonSlot() def get_client(config=None): return _slot.get(lambda: ExpensiveClient(resolve(config))) def reset_client(): _slot.reset() Both serialize concurrent first calls with double-checked locking and run the factory at most once. If the factory raises, nothing is cached and the next call retries. The honcho memory plugin (`plugins/memory/honcho/client.py`) is the reference consumer. > Rule of thumb: any time you write `global _something` followed by a `is None` check and a build, reach for one of these instead. ### Conditional tool availability For tools that depend on optional libraries: `python ctx.register_tool( name="my_tool", schema={...}, handler=my_handler, check_fn=lambda: _has_optional_lib(), # False = tool hidden from model )` ### Overriding a built-in tool To replace a built-in tool with your own implementation (e.g. swap the default browser tool for a headed-Chrome CDP backend, or replace `web_search` with a custom corporate index), pass `override=True`: `python def register(ctx): ctx.register_tool( name="browser_navigate", # same name as the built-in toolset="plugin_my_browser", # your own toolset namespace schema={...}, handler=my_custom_navigate, override=True, # explicit opt-in )` Without `override=True`, the registry rejects any registration that would shadow an existing tool from a different toolset — this prevents accidental overwrites. The override is logged at INFO level so it’s auditable in `~/.hermes/logs/agent.log`. Plugins load after built-in tools, so the registration order is correct: your handler replaces the built-in one. ### Register multiple hooks `python def register(ctx): ctx.register_hook("pre_tool_call", before_any_tool) ctx.register_hook("post_tool_call", after_any_tool) ctx.register_hook("pre_llm_call", inject_memory) ctx.register_hook("on_session_start", on_new_session) ctx.register_hook("on_session_end", on_session_end)` ### Hook reference Each hook is documented in full on the Event Hooks reference — callback signatures, parameter tables, exactly when each fires, and examples. Here’s the summary: | Hook | Fires when | Callback signature | Returns | |——|———–|—————––|———| | `pre_tool_call` | Before any tool executes | `tool_name: str, args: dict, task_id: str` | ignored | | `post_tool_call` | After any tool returns | `tool_name: str, args: dict, result: str, task_id: str, duration_ms: int` | ignored | | `pre_llm_call` | Once per turn, before the tool-calling loop | `session_id: str, user_message: str, conversation_history: list, is_first_turn: bool, model: str, platform: str` | context injection | | `post_llm_call` | Once per turn, after the tool-calling loop (successful turns only) | `session_id: str, user_message: str, assistant_response: str, conversation_history: list, model: str, platform: str` | ignored | | `on_session_start` | New session created (first turn only) | `session_id: str, model: str, platform: str` | ignored | | `on_session_end` | End of every `run_conversation` call + CLI exit | `session_id: str, completed: bool, interrupted: bool, model: str, platform: str` | ignored | | `on_session_finalize` | CLI/gateway tears down an active session | `session_id: str \| None, platform: str` | ignored | | `on_session_reset` | Gateway swaps in a new session key (`/new`, `/reset`) | `session_id: str, platform: str` | ignored | Most hooks are fire-and-forget observers — their return values are ignored. The exception is `pre_llm_call`, which can inject context into the conversation. All callbacks should accept `kwargs` for forward compatibility. If a hook callback crashes, it’s logged and skipped. Other hooks and the agent continue normally. ### `pre_llm_call` context injection This is the only hook whose return value matters. When a `pre_llm_call` callback returns a dict with a `"context"` key (or a plain string), Hermes injects that text into the current turn’s user message. This is the mechanism for memory plugins, RAG integrations, guardrails, and any plugin that needs to provide the model with additional context. #### Return format `python # Dict with context key return {"context": "Recalled memories:\n- User prefers dark mode\n- Last project: hermes-agent"} # Plain string (equivalent to the dict form above) return "Recalled memories:\n- User prefers dark mode" # Return None or don't return → no injection (observer-only) return None` Any non-None, non-empty return with a `"context"` key (or a plain non-empty string) is collected and appended to the user message for the current turn. #### How injection works Injected context is appended to the user message, not the system prompt. This is a deliberate design choice: - Prompt cache preservation — the system prompt stays identical across turns. Anthropic and OpenRouter cache the system prompt prefix, so keeping it stable saves 75%+ on input tokens in multi-turn conversations. If plugins modified the system prompt, every turn would be a cache miss. - Ephemeral — the injection happens at API call time only. The original user message in the conversation history is never mutated, and nothing is persisted to the session database. - The system prompt is Hermes’s territory — it contains model-specific guidance, tool enforcement rules, personality instructions, and cached skill content. Plugins contribute context alongside the user’s input, not by altering the agent’s core instructions. #### Example: Memory recall plugin python """Memory plugin — recalls relevant context from a vector store.""" import httpx MEMORY_API = "https://your-memory-api.example.com" def recall_context(session_id, user_message, is_first_turn, kwargs): """Called before each LLM turn. Returns recalled memories.""" try: resp = httpx.post(f"{MEMORY_API}/recall", json={ "session_id": session_id, "query": user_message, }, timeout=3) memories = resp.json().get("results", []) if not memories: return None # nothing to inject text = "Recalled context from previous sessions:\n" text += "\n".join(f"- {m['text']}" for m in memories) return {"context": text} except Exception: return None # fail silently, don't break the agent def register(ctx): ctx.register_hook("pre_llm_call", recall_context) #### Example: Guardrails plugin `python """Guardrails plugin — enforces content policies.""" POLICY = """You MUST follow these content policies for this session: - Never generate code that accesses the filesystem outside the working directory - Always warn before executing destructive operations - Refuse requests involving personal data extraction""" def inject_guardrails(kwargs): """Injects policy text into every turn.""" return {"context": POLICY} def register(ctx): ctx.register_hook("pre_llm_call", inject_guardrails)` #### Example: Observer-only hook (no injection) `python """Analytics plugin — tracks turn metadata without injecting context.""" import logging logger = logging.getLogger(name) def log_turn(session_id, user_message, model, is_first_turn, kwargs): """Fires before each LLM call. Returns None — no context injected.""" logger.info("Turn: session=%s model=%s first=%s msg_len=%d", session_id, model, is_first_turn, len(user_message or "")) # No return → no injection def register(ctx): ctx.register_hook("pre_llm_call", log_turn)` #### Multiple plugins returning context When multiple plugins return context from `pre_llm_call`, their outputs are joined with double newlines and appended to the user message together. The order follows plugin discovery order (alphabetical by plugin directory name). ### Register CLI commands Plugins can add their own `hermes <plugin>` subcommand tree: python def _my_command(args): """Handler for hermes my-plugin <subcommand>.""" sub = getattr(args, "my_command", None) if sub == "status": print("All good!") elif sub == "config": print("Current config: ...") else: print("Usage: hermes my-plugin <status|config>") def _setup_argparse(subparser): """Build the argparse tree for hermes my-plugin.""" subs = subparser.add_subparsers(dest="my_command") subs.add_parser("status", help="Show plugin status") subs.add_parser("config", help="Show plugin config") subparser.set_defaults(func=_my_command) def register(ctx): ctx.register_tool(...) ctx.register_cli_command( name="my-plugin", help="Manage my plugin", setup_fn=_setup_argparse, handler_fn=_my_command, ) After registration, users can run `hermes my-plugin status`, `hermes my-plugin config`, etc. Memory provider plugins use a convention-based approach instead: add a `register_cli(subparser)` function to your plugin’s `cli.py` file. The memory plugin discovery system finds it automatically — no `ctx.register_cli_command()` call needed. See the Memory Provider Plugin guide for details. Active-provider gating: Memory plugin CLI commands only appear when their provider is the active `memory.provider` in config. If a user hasn’t set up your provider, your CLI commands won’t clutter the help output. ### Register slash commands Plugins can register in-session slash commands — commands users type during a conversation (like `/lcm status` or `/ping`). These work in both CLI and gateway (Telegram, Discord, etc.). `python def _handle_status(raw_args: str) -> str: """Handler for /mystatus — called with everything after the command name.""" if raw_args.strip() == "help": return "Usage: /mystatus [help|check]" return "Plugin status: all systems nominal" def register(ctx): ctx.register_command( "mystatus", handler=_handle_status, description="Show plugin status", )` After registration, users can type `/mystatus` in any session. The command appears in autocomplete, `/help` output, and the Telegram bot menu. Signature: `ctx.register_command(name: str, handler: Callable, description: str = "", args_hint: str = "")` | Parameter | Type | Description | |———–|——|———––| | `name` | `str` | Command name without the leading slash (e.g. `"lcm"`, `"mystatus"`) | | `handler` | `Callable[[str], str \| None]` | Called with the raw argument string. May also be `async`. | | `description` | `str` | Shown in `/help`, autocomplete, and Telegram bot menu | Key differences from `register_cli_command()`: | | `register_command()` | `register_cli_command()` | |—|—|—| | Invoked as | `/name` in a session | `hermes name` in a terminal | | Where it works | CLI sessions, Telegram, Discord, etc. | Terminal only | | Handler receives | Raw args string | argparse `Namespace` | | Use case | Diagnostics, status, quick actions | Complex subcommand trees, setup wizards | Conflict protection: If a plugin tries to register a name that conflicts with a built-in command (`help`, `model`, `new`, etc.), the registration is silently rejected with a log warning. Built-in commands always take precedence. Async handlers: The gateway dispatch automatically detects and awaits async handlers, so you can use either sync or async functions: `python async def _handle_check(raw_args: str) -> str: result = await some_async_operation() return f"Check result: {result}" def register(ctx): ctx.register_command("check", handler=_handle_check, description="Run async check")` ### Dispatch tools from slash commands Slash command handlers that need to orchestrate tools (spawn a subagent via `delegate_task`, call `file_edit`, etc.) should use `ctx.dispatch_tool()` instead of reaching into framework internals. The parent-agent context (workspace hints, spinner, model inheritance) is wired up automatically. `python def register(ctx): def _handle_deliver(raw_args: str): result = ctx.dispatch_tool( "delegate_task", { "goal": raw_args, "toolsets": ["terminal", "file", "web"], }, ) return result ctx.register_command( "deliver", handler=_handle_deliver, description="Delegate a goal to a subagent", )` Signature: `ctx.dispatch_tool(name: str, args: dict, *, parent_agent=None) -> str` | Parameter | Type | Description | |———–|——|———––| | `name` | `str` | Tool name as registered in the tool registry (e.g. `"delegate_task"`, `"file_edit"`) | | `args` | `dict` | Tool arguments, same shape the model would send | | `parent_agent` | `Agent \| None` | Optional override. When omitted, resolves from the current CLI agent (or degrades gracefully in gateway mode) | Runtime behavior: - CLI mode: `parent_agent` is resolved from the active CLI agent so workspace hints, spinner, and model selection inherit as expected. - Gateway mode: There is no CLI agent, so tools degrade gracefully — workspace is read from the configured terminal working directory and no spinner is shown. - Explicit override: If the caller passes `parent_agent=` explicitly, it is respected and not overwritten. This is the public, stable interface for tool dispatch from plugin commands. Plugins should not reach into `ctx._cli_ref.agent` or similar private state. :::tip This guide covers general plugins (tools, hooks, slash commands, CLI commands). The sections below sketch the authoring pattern for each specialized plugin type; each links to its full guide for field reference and examples. ::: ## Specialized plugin types Hermes has five specialized plugin types beyond the general surface. Each ships as a directory under `plugins/<category>/<name>/` (bundled) or `~/.hermes/plugins/<category>/<name>/` (user). The contract differs by category — pick the one you need, then read its full guide. ### Model provider plugins — add an LLM backend Drop a profile into `plugins/model-providers/<name>/`: `python # plugins/model-providers/acme/init.py from providers import register_provider from providers.base import ProviderProfile register_provider(ProviderProfile( name="acme", aliases=("acme-inference",), display_name="Acme Inference", env_vars=("ACME_API_KEY", "ACME_BASE_URL"), base_url="https://api.acme.example.com/v1", auth_type="api_key", default_aux_model="acme-small-fast", fallback_models=("acme-large-v3", "acme-medium-v3"), ))` `yaml # plugins/model-providers/acme/plugin.yaml name: acme-provider kind: model-provider version: 1.0.0 description: Acme Inference — OpenAI-compatible direct API` Lazy-discovered the first time anything calls `get_provider_profile()` or `list_providers()` — `auth.py`, `config.py`, `doctor.py`, `models.py`, `runtime_provider.py`, and the chat_completions transport auto-wire to it. User plugins override bundled ones by name. Full guide: Model Provider Plugins — field reference, overridable hooks (`prepare_messages`, `build_extra_body`, `build_api_kwargs_extras`, `fetch_models`), api_mode selection, auth types, testing. ### Platform plugins — add a gateway channel Drop an adapter into `plugins/platforms/<name>/`: python # plugins/platforms/myplatform/adapter.py from gateway.platforms.base import BasePlatformAdapter class MyPlatformAdapter(BasePlatformAdapter): async def connect(self): ... async def send(self, chat_id, text): ... async def disconnect(self): ... def check_requirements(): import os return bool(os.environ.get("MYPLATFORM_TOKEN")) def _env_enablement(): import os tok = os.getenv("MYPLATFORM_TOKEN", "").strip() if not tok: return None return {"token": tok} def register(ctx): ctx.register_platform( name="myplatform", label="MyPlatform", adapter_factory=lambda cfg: MyPlatformAdapter(cfg), check_fn=check_requirements, required_env=["MYPLATFORM_TOKEN"], # Auto-populate PlatformConfig.extra from env so env-only setups # show up in `hermes gateway status` without SDK instantiation. env_enablement_fn=_env_enablement, # Opt in to cron delivery: `deliver=myplatform` routes to this var. cron_deliver_env_var="MYPLATFORM_HOME_CHANNEL", emoji="💬", platform_hint="You are chatting via MyPlatform. Keep responses concise.", ) `yaml # plugins/platforms/myplatform/plugin.yaml name: myplatform-platform label: MyPlatform kind: platform version: 1.0.0 description: MyPlatform gateway adapter requires_env: - name: MYPLATFORM_TOKEN description: "Bot token from the MyPlatform console" password: true optional_env: - name: MYPLATFORM_HOME_CHANNEL description: "Default channel for cron delivery" password: false` Full guide: Adding Platform Adapters — complete `BasePlatformAdapter` contract, message routing, auth gating, setup wizard integration. Look at `plugins/platforms/irc/` for a stdlib-only working example. ### Memory provider plugins — add a cross-session knowledge backend Drop an implementation of `MemoryProvider` into `plugins/memory/<name>/`: python # plugins/memory/my-memory/init.py from agent.memory_provider import MemoryProvider class MyMemoryProvider(MemoryProvider): @property def name(self) -> str: return "my-memory" def is_available(self) -> bool: import os return bool(os.environ.get("MY_MEMORY_API_KEY")) def initialize(self, session_id: str, **kwargs) -> None: self._session_id = session_id def sync_turn(self, user_content, assistant_content, , session_id="", messages=None) -> None: ... def prefetch(self, query, , session_id="") -> str: ... def get_tool_schemas(self) -> list[dict]: return [] # required @abstractmethod — see full guide def register(ctx): ctx.register_memory_provider(MyMemoryProvider()) Memory providers are single-select — only one is active at a time, chosen via `memory.provider` in `config.yaml`. Full guide: Memory Provider Plugins — full `MemoryProvider` ABC, threading contract, profile isolation, CLI command registration via `cli.py`. ### Context engine plugins — replace the context compressor `python # plugins/context_engine/my-engine/init.py from agent.context_engine import ContextEngine class MyContextEngine(ContextEngine): @property def name(self) -> str: return "my-engine" def update_from_response(self, usage) -> None: ... def should_compress(self, prompt_tokens: int = None) -> bool: ... def compress(self, messages, current_tokens=None, focus_topic=None) -> list: ... def register(ctx): ctx.register_context_engine(MyContextEngine())` Context engines are single-select — chosen via `context.engine` in `config.yaml`. Full guide: Context Engine Plugins. ### Image-generation backends Drop a provider into `plugins/image_gen/<name>/`: `python # plugins/image_gen/my-imggen/init.py from agent.image_gen_provider import ImageGenProvider class MyImageGenProvider(ImageGenProvider): @property def name(self) -> str: return "my-imggen" def is_available(self) -> bool: ... def generate(self, prompt: str, aspect_ratio="landscape", kwargs) -> dict: # returns success_response(...) / error_response(...) ... def register(ctx): ctx.register_image_gen_provider(MyImageGenProvider())` `yaml # plugins/image_gen/my-imggen/plugin.yaml name: my-imggen kind: backend version: 1.0.0 description: Custom image generation backend` Full guide: Image Generation Provider Plugins — full `ImageGenProvider` ABC, `list_models()` / `get_setup_schema()` metadata, `success_response()`/`error_response()` helpers, base64 vs URL output, user overrides, pip distribution. Reference examples: `plugins/image_gen/openai/` (DALL-E / GPT-Image via OpenAI SDK), `plugins/image_gen/openai-codex/`, `plugins/image_gen/xai/` (Grok image gen). ## Non-Python extension surfaces Hermes also accepts extensions that aren’t Python plugins at all. These are shown in the Pluggable interfaces table; the sections below sketch each authoring style briefly. ### MCP servers — register external tools Model Context Protocol (MCP) servers register their own tools into Hermes without any Python plugin. Declare them in `~/.hermes/config.yaml`: `yaml mcp_servers: filesystem: command: "npx" args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"] timeout: 120 linear: url: "https://mcp.linear.app/sse" auth: type: "oauth"` Hermes connects to each server at startup, lists its tools, and registers them alongside built-ins. The LLM sees them exactly like any other tool. Full guide:** MCP. ### Gateway event hooks — fire on lifecycle events Drop a manifest + handler into `~/.hermes/hooks/<name>/`: `yaml # ~/.hermes/hooks/long-task-alert/HOOK.yaml name: long-task-alert description: Send a push notification when a long task finishes events: - agent:end` `python # ~/.hermes/hooks/long-task-alert/handler.py async def handle(event_type: str, context: dict) -> None: if context.get("duration_seconds", 0) > 120: # send notification … pass` Events include `gateway:startup`, `session:start`, `session:end`, `session:reset`, `agent:start`, `agent:step`, `agent:end`, and wildcard `command:`. Errors in hooks are caught and logged — they never block the main pipeline. Full guide: Gateway Event Hooks. ### Shell hooks — run a shell command on tool calls If you just want to run a script when a tool fires (notifications, audit logs, desktop alerts, auto-formatters), use shell hooks in `config.yaml` — no Python required: `yaml hooks: - event: post_tool_call command: "notify-send 'Tool ran: {tool_name}'" when: tools: [terminal, patch, write_file]` Supports all the same events as Python plugin hooks (`pre_tool_call`, `post_tool_call`, `pre_llm_call`, `post_llm_call`, `on_session_start`, `on_session_end`, `pre_gateway_dispatch`) plus structured JSON output for `pre_tool_call` blocking decisions. Full guide: Shell Hooks. ### Skill sources — add a custom skill registry If you maintain a GitHub repo of skills (or want to pull from a community index beyond the built-in sources), add it as a tap: `bash hermes skills tap add myorg/skills-repo hermes skills search my-workflow --source myorg/skills-repo hermes skills install myorg/skills-repo/my-workflow` Publishing your own tap is just a GitHub repo with `skills/<skill-name>/SKILL.md` directories — no server or registry signup needed. Full guides: Skills Hub · Publishing a custom tap (repo layout, minimal example, non-default paths, trust levels). ### TTS / STT via command templates Any CLI that reads/writes audio or text can be plugged in through `config.yaml` — no Python code: `yaml tts: provider: voxcpm providers: voxcpm: type: command command: "voxcpm --ref ~/voice.wav --text-file {input_path} --out {output_path}" output_format: mp3 voice_compatible: true` For STT, point `HERMES_LOCAL_STT_COMMAND` at a shell template. Supported placeholders: `{input_path}`, `{output_path}`, `{format}`, `{voice}`, `{model}`, `{speed}` (TTS); `{input_path}`, `{output_dir}`, `{language}`, `{model}` (STT). Any path-interacting CLI is automatically a plugin. Full guides: TTS custom command providers · STT. ## Distribute via pip For sharing plugins publicly, add an entry point to your Python package: `toml # pyproject.toml [project.entry-points."hermes_agent.plugins"] my-plugin = "my_plugin_package"` `bash pip install hermes-plugin-calculator # Plugin auto-discovered on next hermes startup` ## Distribute for NixOS NixOS users can install your plugin declaratively if you provide a `pyproject.toml` with entry points: Entry-point plugins (recommended for distribution): `nix # User's configuration.nix services.hermes-agent.extraPythonPackages = [ (pkgs.python312Packages.buildPythonPackage { pname = "my-plugin"; version = "1.0.0"; src = pkgs.fetchFromGitHub { owner = "you"; repo = "hermes-my-plugin"; rev = "v1.0.0"; hash = "sha256-..."; # nix-prefetch-url --unpack }; format = "pyproject"; build-system = [ pkgs.python312Packages.setuptools ]; }) ];` Directory plugins (no `pyproject.toml` needed): `nix services.hermes-agent.extraPlugins = [ (pkgs.fetchFromGitHub { owner = "you"; repo = "hermes-my-plugin"; rev = "v1.0.0"; hash = "sha256-..."; }) ];` See the Nix Setup guide for complete documentation including overlay usage and collision checking. ## Common mistakes Handler doesn’t return JSON string: `python # Wrong — returns a dict def handler(args, kwargs): return {"result": 42} # Right — returns a JSON string def handler(args, kwargs): return json.dumps({"result": 42})` Missing `kwargs` in handler signature: `python # Wrong — will break if Hermes passes extra context def handler(args): ... # Right def handler(args, kwargs): ...` Handler raises exceptions: `python # Wrong — exception propagates, tool call fails def handler(args, kwargs): result = 1 / int(args["value"]) # ZeroDivisionError! return json.dumps({"result": result}) # Right — catch and return error JSON def handler(args, kwargs): try: result = 1 / int(args.get("value", 0)) return json.dumps({"result": result}) except Exception as e: return json.dumps({"error": str(e)})` Schema description too vague: `python # Bad — model doesn't know when to use it "description": "Does stuff" # Good — model knows exactly when and how "description": "Evaluate a mathematical expression. Use for arithmetic, trig, logarithms. Supports: +, -, , /, , sqrt, sin, cos, log, pi, e."` — # Automate Anything with Cron # Automate Anything with Cron The daily briefing bot tutorial covers the basics. This guide goes further — five real-world automation patterns you can adapt for your own workflows. For the full feature reference, see Scheduled Tasks (Cron). :::info Key Concept Cron jobs run in fresh agent sessions with no memory of your current chat. Prompts must be completely self-contained — include everything the agent needs to know. ::: :::tip Don’t need the LLM? You have two zero-token options. - Recurring watchdog where the script already produces the exact message (memory alerts, disk alerts, heartbeats): use script-only cron jobs. Same scheduler, no LLM. You can ask Hermes to set one up for you in chat — the `cronjob` tool knows when to pick `no_agent=True` and writes the script for you. - One-shot from a script that’s already running** (CI step, post-commit hook, deploy script, externally-scheduled monitor): use `hermes send` to pipe stdout or a file straight to Telegram / Discord / Slack / etc. without setting up a cron entry. ::: — ## Pattern 1: Website Change Monitor Watch a URL for changes and get notified only when something is different. The `script` parameter is the secret weapon here. A Python script runs before each execution, and its stdout becomes context for the agent. The script handles the mechanical work (fetching, diffing); the agent handles the reasoning (is this change interesting?). Create the monitoring script: `bash mkdir -p ~/.hermes/scripts` python title="~/.hermes/scripts/watch-site.py" import hashlib, json, os, urllib.request URL = "https://example.com/pricing" STATE_FILE = os.path.expanduser("~/.hermes/scripts/.watch-site-state.json") # Fetch current content req = urllib.request.Request(URL, headers={"User-Agent": "Hermes-Monitor/1.0"}) content = urllib.request.urlopen(req, timeout=30).read().decode() current_hash = hashlib.sha256(content.encode()).hexdigest() # Load previous state prev_hash = None if os.path.exists(STATE_FILE): with open(STATE_FILE) as f: prev_hash = json.load(f).get("hash") # Save current state with open(STATE_FILE, "w") as f: json.dump({"hash": current_hash, "url": URL}, f) # Output for the agent if prev_hash and prev_hash != current_hash: print(f"CHANGE DETECTED on {URL}") print(f"Previous hash: {prev_hash}") print(f"Current hash: {current_hash}") print(f"\nCurrent content (first 2000 chars):\n{content[:2000]}") else: print("NO_CHANGE") Set up the cron job: `bash /cron add "every 1h" "If the script output says CHANGE DETECTED, summarize what changed on the page and why it might matter. If it says NO_CHANGE, respond with just [SILENT]." --script ~/.hermes/scripts/watch-site.py --name "Pricing monitor" --deliver telegram` :::tip The [SILENT] Trick When the agent’s final response contains `[SILENT]`, delivery is suppressed. This means you only get notified when something actually happens — no spam on quiet hours. ::: — ## Pattern 2: Weekly Report Compile information from multiple sources into a formatted summary. This runs once a week and delivers to your home channel. `bash /cron add "0 9 * * 1" "Generate a weekly report covering: 1. Search the web for the top 5 AI news stories from the past week 2. Search GitHub for trending repositories in the 'machine-learning' topic 3. Check Hacker News for the most discussed AI/ML posts Format as a clean summary with sections for each source. Include links. Keep it under 500 words — highlight only what matters." --name "Weekly AI digest" --deliver telegram` From the CLI: `bash hermes cron create "0 9 * * 1" \ "Generate a weekly report covering the top AI news, trending ML GitHub repos, and most-discussed HN posts. Format with sections, include links, keep under 500 words." \ --name "Weekly AI digest" \ --deliver telegram` The `0 9 * * 1` is a standard cron expression: 9:00 AM every Monday. — ## Pattern 3: GitHub Repository Watcher Monitor a repository for new issues, PRs, or releases. bash /cron add "every 6h" "Check the GitHub repository NousResearch/hermes-agent for: - New issues opened in the last 6 hours - New PRs opened or merged in the last 6 hours - Any new releases Use the terminal to run gh commands: gh issue list --repo NousResearch/hermes-agent --state open --json number,title,author,createdAt --limit 10 gh pr list --repo NousResearch/hermes-agent --state all --json number,title,author,createdAt,mergedAt --limit 10 Filter to only items from the last 6 hours. If nothing new, respond with [SILENT]. Otherwise, provide a concise summary of the activity." --name "Repo watcher" --deliver discord :::warning Self-Contained Prompts Notice how the prompt includes the exact `gh` commands. The cron agent has no memory of previous runs or your preferences — spell everything out. ::: — ## Pattern 4: Data Collection Pipeline Scrape data at regular intervals, save to files, and detect trends over time. This pattern combines a script (for collection) with the agent (for analysis). python title="~/.hermes/scripts/collect-prices.py" import json, os, urllib.request from datetime import datetime DATA_DIR = os.path.expanduser("~/.hermes/data/prices") os.makedirs(DATA_DIR, exist_ok=True) # Fetch current data (example: crypto prices) url = "https://api.coingecko.com/api/v3/simple/price?ids=bitcoin,ethereum&vs_currencies=usd" data = json.loads(urllib.request.urlopen(url, timeout=30).read()) # Append to history file entry = {"timestamp": datetime.now().isoformat(), "prices": data} history_file = os.path.join(DATA_DIR, "history.jsonl") with open(history_file, "a") as f: f.write(json.dumps(entry) + "\n") # Load recent history for analysis lines = open(history_file).readlines() recent = [json.loads(l) for l in lines[-24:]] # Last 24 data points # Output for the agent print(f"Current: BTC=${data['bitcoin']['usd']}, ETH=${data['ethereum']['usd']}") print(f"Data points collected: {len(lines)} total, showing last {len(recent)}") print(f"\nRecent history:") for r in recent[-6:]: print(f" {r['timestamp']}: BTC=${r['prices']['bitcoin']['usd']}, ETH=${r['prices']['ethereum']['usd']}") `bash /cron add "every 1h" "Analyze the price data from the script output. Report: 1. Current prices 2. Trend direction over the last 6 data points (up/down/flat) 3. Any notable movements (>5% change) If prices are flat and nothing notable, respond with [SILENT]. If there's a significant move, explain what happened." \ --script ~/.hermes/scripts/collect-prices.py \ --name "Price tracker" \ --deliver telegram` The script does the mechanical collection; the agent adds the reasoning layer. — ## Pattern 5: Multi-Skill Workflow Chain skills together for complex scheduled tasks. Skills are loaded in order before the prompt executes. `bash # Use the arxiv skill to find papers, then the obsidian skill to save notes /cron add "0 8 * * " "Search arXiv for the 3 most interesting papers on 'language model reasoning' from the past day. For each paper, create an Obsidian note with the title, authors, abstract summary, and key contribution." \ --skill arxiv \ --skill obsidian \ --name "Paper digest"` From the tool directly: `python cronjob( action="create", skills=["arxiv", "obsidian"], prompt="Search arXiv for papers on 'language model reasoning' from the past day. Save the top 3 as Obsidian notes.", schedule="0 8 * ", name="Paper digest", deliver="local" )` Skills are loaded in order — `arxiv` first (teaches the agent how to search papers), then `obsidian` (teaches how to write notes). The prompt ties them together. — ## Managing Your Jobs `bash # List all active jobs /cron list # Trigger a job immediately (for testing) /cron run <job_id> # Pause a job without deleting it /cron pause <job_id> # Edit a running job's schedule or prompt /cron edit <job_id> --schedule "every 4h" /cron edit <job_id> --prompt "Updated task description" # Add or remove skills from an existing job /cron edit <job_id> --skill arxiv --skill obsidian /cron edit <job_id> --clear-skills # Remove a job permanently /cron remove <job_id>` — ## Delivery Targets The `--deliver` flag controls where results go: | Target | Example | Use case | |––––|———|–––––| | `origin` | `--deliver origin` | Same chat that created the job (default) | | `local` | `--deliver local` | Save to local file only | | `telegram` | `--deliver telegram` | Your Telegram home channel | | `discord` | `--deliver discord` | Your Discord home channel | | `slack` | `--deliver slack` | Your Slack home channel | | Specific chat | `--deliver telegram:-1001234567890` | A specific Telegram group | | Threaded | `--deliver telegram:-1001234567890:17585` | A specific Telegram topic thread | — ## Tips Make prompts self-contained. The agent in a cron job has no memory of your conversations. Include URLs, repo names, format preferences, and delivery instructions directly in the prompt. Use `[SILENT]` liberally. For monitoring jobs, always include instructions like “if nothing changed, respond with `[SILENT]`.” This prevents notification noise. Use scripts for data collection. The `script` parameter lets a Python script handle the boring parts (HTTP requests, file I/O, state tracking). The agent only sees the script’s stdout and applies reasoning to it. This is cheaper and more reliable than having the agent do the fetching itself. Test with `/cron run`. Before waiting for the schedule to trigger, use `/cron run <job_id>` to execute immediately and verify the output looks right. Schedule expressions. Supported formats: relative delays (`30m`), intervals (`every 2h`), standard cron expressions (`0 9 * `), and ISO timestamps (`2025-06-15T09:00:00`). Natural language like `daily at 9am` is not supported — use `0 9 * ` instead. — For the complete cron reference — all parameters, edge cases, and internals — see Scheduled Tasks (Cron).* — # Working with Skills # Working with Skills Skills are on-demand knowledge documents that teach Hermes how to handle specific tasks — from generating ASCII art to managing GitHub PRs. This guide walks you through using them day to day. For the full technical reference, see Skills System. — ## Finding Skills Every Hermes installation ships with bundled skills. See what’s available: `bash # In any chat session: /skills # Or from the CLI: hermes skills list` This shows a compact list with names and descriptions: `ascii-art Generate ASCII art using pyfiglet, cowsay, boxes... arxiv Search and retrieve academic papers from arXiv... github-pr-workflow Full PR lifecycle — create branches, commit... plan Plan mode — inspect context, write a markdown... excalidraw Create hand-drawn style diagrams using Excalidraw...` ### Searching for a Skill `bash # Search by keyword /skills search docker /skills search music` ### The Skills Hub Official optional skills (heavier or niche skills not active by default) are available via the Hub: `bash # Browse official optional skills /skills browse # Search the hub /skills search blockchain` — ## Using a Skill Every installed skill is automatically a slash command. Just type its name: `bash # Load a skill and give it a task /ascii-art Make a banner that says "HELLO WORLD" /plan Design a REST API for a todo app /github-pr-workflow Create a PR for the auth refactor # Just the skill name (no task) loads it and lets you describe what you need /excalidraw` You can also trigger skills through natural conversation — ask Hermes to use a specific skill, and it will load it via the `skill_view` tool. ### Progressive Disclosure Skills use a token-efficient loading pattern. The agent doesn’t load everything at once: 1. `skills_list()` — compact list of all skills (~3k tokens). Loaded at session start. 2. `skill_view(name)` — full SKILL.md content for one skill. Loaded when the agent decides it needs that skill. 3. `skill_view(name, file_path)` — a specific reference file within the skill. Only loaded if needed. This means skills don’t cost tokens until they’re actually used. — ## Installing from the Hub Official optional skills ship with Hermes but aren’t active by default. Install them explicitly: `bash # Install an official optional skill hermes skills install official/research/arxiv # Install from the hub in a chat session /skills install official/creative/songwriting-and-ai-music # Install a single-file SKILL.md directly from any HTTP(S) URL hermes skills install https://sharethis.chat/SKILL.md /skills install https://example.com/SKILL.md --name my-skill` What happens: 1. The skill directory is copied to `~/.hermes/skills/` 2. It appears in your `skills_list` output 3. It becomes available as a slash command :::tip Installed skills take effect in new sessions. If you want it available in the current session, use `/reset` to start fresh, or add `--now` to invalidate the prompt cache immediately (costs more tokens on the next turn). ::: ### Verifying Installation `bash # Check it's there hermes skills list | grep arxiv # Or in chat /skills search arxiv` — ## Plugin-Provided Skills Plugins can bundle their own skills using namespaced names (`plugin:skill`). This prevents name collisions with built-in skills. `bash # Load a plugin skill by its qualified name skill_view("superpowers:writing-plans") # Built-in skill with the same base name is unaffected skill_view("writing-plans")` Plugin skills are not listed in the system prompt and don’t appear in `skills_list`. They’re opt-in — load them explicitly when you know a plugin provides one. When loaded, the agent sees a banner listing sibling skills from the same plugin. For how to ship skills in your own plugin, see Build a Hermes Plugin → Bundle skills. — ## Configuring Skill Settings Some skills declare configuration they need in their frontmatter: `yaml metadata: hermes: config: - key: tenor.api_key description: "Tenor API key for GIF search" prompt: "Enter your Tenor API key" url: "https://developers.google.com/tenor/guides/quickstart"` When a skill with config is first loaded, Hermes prompts you for the values. They’re stored in `config.yaml` under `skills.config.`. Manage skill config from the CLI: `bash # Interactive config for a specific skill hermes skills config gif-search # View all skill config hermes config show | grep '^skills\.config'` — ## Creating Your Own Skill Skills are just markdown files with YAML frontmatter. Creating one takes under five minutes. ### 1. Create the Directory `bash mkdir -p ~/.hermes/skills/my-category/my-skill` ### 2. Write SKILL.md markdown title="~/.hermes/skills/my-category/my-skill/SKILL.md" --- name: my-skill description: Brief description of what this skill does version: 1.0.0 metadata: hermes: tags: [my-tag, automation] category: my-category --- # My Skill ## When to Use Use this skill when the user asks about [specific topic] or needs to [specific task]. ## Procedure 1. First, check if [prerequisite] is available 2. Run `command --with-flags` 3. Parse the output and present results ## Pitfalls - Common failure: [description]. Fix: [solution] - Watch out for [edge case] ## Verification Run `check-command` to confirm the result is correct. ### 3. Add Reference Files (Optional) Skills can include supporting files the agent loads on demand: `my-skill/ ├── SKILL.md # Main skill document ├── references/ │ ├── api-docs.md # API reference the agent can consult │ └── examples.md # Example inputs/outputs ├── templates/ │ └── config.yaml # Template files the agent can use └── scripts/ └── setup.sh # Scripts the agent can execute` Reference these in your SKILL.md: markdown For API details, load the reference: `skill_view("my-skill", "references/api-docs.md")` ### 4. Test It Start a new session and try your skill: `bash hermes chat -q "/my-skill help me with the thing"` The skill appears automatically — no registration needed. Drop it in `~/.hermes/skills/` and it’s live. :::info The agent can also create and update skills itself using `skill_manage`. After solving a complex problem, Hermes may offer to save the approach as a skill for next time. ::: — ## Per-Platform Skill Management Control which skills are available on which platforms: `bash hermes skills` This opens an interactive TUI where you can enable or disable skills per platform (CLI, Telegram, Discord, etc.). Useful when you want certain skills only available in specific contexts — for example, keeping development skills off Telegram. — ## Skills vs Memory Both are persistent across sessions, but they serve different purposes: | | Skills | Memory | |—|—|—| | What | Procedural knowledge — how to do things | Factual knowledge — what things are | | When | Loaded on demand, only when relevant | Injected into every session automatically | | Size | Can be large (hundreds of lines) | Should be compact (key facts only) | | Cost | Zero tokens until loaded | Small but constant token cost | | Examples | “How to deploy to Kubernetes” | “User prefers dark mode, lives in PST” | | Who creates | You, the agent, or installed from Hub | The agent, based on conversations | Rule of thumb: If you’d put it in a reference document, it’s a skill. If you’d put it on a sticky note, it’s memory. — ## Tips Keep skills focused. A skill that tries to cover “all of DevOps” will be too long and too vague. A skill that covers “deploy a Python app to Fly.io” is specific enough to be genuinely useful. Let the agent create skills. After a complex multi-step task, Hermes will often offer to save the approach as a skill. Say yes — these agent-authored skills capture the exact workflow including pitfalls that were discovered along the way. Use categories. Organize skills into subdirectories (`~/.hermes/skills/devops/`, `~/.hermes/skills/research/`, etc.). This keeps the list manageable and helps the agent find relevant skills faster. Update skills when they go stale. If you use a skill and hit issues not covered by it, tell Hermes to update the skill with what you learned. Skills that aren’t maintained become liabilities. — For the complete skills reference — frontmatter fields, conditional activation, external directories, and more — see Skills System.* — # Delegation & Parallel Work # Delegation & Parallel Work Hermes can spawn isolated child agents to work on tasks in parallel. Each subagent gets its own conversation, terminal session, and toolset. Only the final summary comes back — intermediate tool calls never enter your context window. For the full feature reference, see Subagent Delegation. — ## When to Delegate Good candidates for delegation: - Reasoning-heavy subtasks (debugging, code review, research synthesis) - Tasks that would flood your context with intermediate data - Parallel independent workstreams (research A and B simultaneously) - Fresh-context tasks where you want the agent to approach without bias Use something else: - Single tool call → just use the tool directly - Mechanical multi-step work with logic between steps → `execute_code` - Tasks needing user interaction → subagents can’t use `clarify` - Quick file edits → do them directly - Durable long-running work that must outlive the current turn → `cronjob` or `terminal(background=True, notify_on_complete=True)`. `delegate_task` is synchronous: if the parent turn is interrupted, active children are cancelled and their work is discarded. — ## Pattern: Parallel Research Research three topics simultaneously and get structured summaries back: `Research these three topics in parallel: 1. Current state of WebAssembly outside the browser 2. RISC-V server chip adoption in 2025 3. Practical quantum computing applications Focus on recent developments and key players.` Behind the scenes, Hermes uses: python delegate_task(tasks=[ { "goal": "Research WebAssembly outside the browser in 2025", "context": "Focus on: runtimes (Wasmtime, Wasmer), cloud/edge use cases, WASI progress", "toolsets": ["web"] }, { "goal": "Research RISC-V server chip adoption", "context": "Focus on: server chips shipping, cloud providers adopting, software ecosystem", "toolsets": ["web"] }, { "goal": "Research practical quantum computing applications", "context": "Focus on: error correction breakthroughs, real-world use cases, key companies", "toolsets": ["web"] } ]) All three run concurrently. Each subagent searches the web independently and returns a summary. The parent agent then synthesizes them into a coherent briefing. — ## Pattern: Code Review Delegate a security review to a fresh-context subagent that approaches the code without preconceptions: `Review the authentication module at src/auth/ for security issues. Check for SQL injection, JWT validation problems, password handling, and session management. Fix anything you find and run the tests.` The key is the `context` field — it must include everything the subagent needs: `python delegate_task( goal="Review src/auth/ for security issues and fix any found", context="""Project at /home/user/webapp. Python 3.11, Flask, PyJWT, bcrypt. Auth files: src/auth/login.py, src/auth/jwt.py, src/auth/middleware.py Test command: pytest tests/auth/ -v Focus on: SQL injection, JWT validation, password hashing, session management. Fix issues found and verify tests pass.""", toolsets=["terminal", "file"] )` :::warning The Context Problem Subagents know absolutely nothing about your conversation. They start completely fresh. If you delegate “fix the bug we were discussing,” the subagent has no idea what bug you mean. Always pass file paths, error messages, project structure, and constraints explicitly. ::: — ## Pattern: Compare Alternatives Evaluate multiple approaches to the same problem in parallel, then pick the best: `I need to add full-text search to our Django app. Evaluate three approaches in parallel: 1. PostgreSQL tsvector (built-in) 2. Elasticsearch via django-elasticsearch-dsl 3. Meilisearch via meilisearch-python For each: setup complexity, query capabilities, resource requirements, and maintenance overhead. Compare them and recommend one.` Each subagent researches one option independently. Because they’re isolated, there’s no cross-contamination — each evaluation stands on its own merits. The parent agent gets all three summaries and makes the comparison. — ## Pattern: Multi-File Refactoring Split a large refactoring task across parallel subagents, each handling a different part of the codebase: python delegate_task(tasks=[ { "goal": "Refactor all API endpoint handlers to use the new response format", "context": """Project at /home/user/api-server. Files: src/handlers/users.py, src/handlers/auth.py, src/handlers/billing.py Old format: return {"data": result, "status": "ok"} New format: return APIResponse(data=result, status=200).to_dict() Import: from src.responses import APIResponse Run tests after: pytest tests/handlers/ -v""", "toolsets": ["terminal", "file"] }, { "goal": "Update all client SDK methods to handle the new response format", "context": """Project at /home/user/api-server. Files: sdk/python/client.py, sdk/python/models.py Old parsing: result = response.json()["data"] New parsing: result = response.json()["data"] (same key, but add status code checking) Also update sdk/python/tests/test_client.py""", "toolsets": ["terminal", "file"] }, { "goal": "Update API documentation to reflect the new response format", "context": """Project at /home/user/api-server. Docs at: docs/api/. Format: Markdown with code examples. Update all response examples from old format to new format. Add a 'Response Format' section to docs/api/overview.md explaining the schema.""", "toolsets": ["terminal", "file"] } ]) :::tip Each subagent gets its own terminal session. They can work on the same project directory without stepping on each other — as long as they’re editing different files. If two subagents might touch the same file, handle that file yourself after the parallel work completes. ::: — ## Pattern: Gather Then Analyze Use `execute_code` for mechanical data gathering, then delegate the reasoning-heavy analysis: python # Step 1: Mechanical gathering (execute_code is better here — no reasoning needed) execute_code(""" from hermes_tools import web_search, web_extract results = [] for query in ["AI funding Q1 2026", "AI startup acquisitions 2026", "AI IPOs 2026"]: r = web_search(query, limit=5) for item in r["data"]["web"]: results.append({"title": item["title"], "url": item["url"], "desc": item["description"]}) # Extract full content from top 5 most relevant urls = [r["url"] for r in results[:5]] content = web_extract(urls) # Save for the analysis step import json with open("/tmp/ai-funding-data.json", "w") as f: json.dump({"search_results": results, "extracted": content["results"]}, f) print(f"Collected {len(results)} results, extracted {len(content['results'])} pages") """) # Step 2: Reasoning-heavy analysis (delegation is better here) delegate_task( goal="Analyze AI funding data and write a market report", context="""Raw data at /tmp/ai-funding-data.json contains search results and extracted web pages about AI funding, acquisitions, and IPOs in Q1 2026. Write a structured market report: key deals, trends, notable players, and outlook. Focus on deals over $100M.""", toolsets=["terminal", "file"] ) This is often the most efficient pattern: `execute_code` handles the 10+ sequential tool calls cheaply, then a subagent does the single expensive reasoning task with a clean context. — ## Toolset Selection Choose toolsets based on what the subagent needs: | Task type | Toolsets | Why | |———–|–––––|—–| | Web research | `["web"]` | web_search + web_extract only | | Code work | `["terminal", "file"]` | Shell access + file operations | | Full-stack | `["terminal", "file", "web"]` | Everything except messaging | | Read-only analysis | `["file"]` | Can only read files, no shell | Restricting toolsets keeps the subagent focused and prevents accidental side effects (like a research subagent running shell commands). — ## Constraints - Default 3 parallel tasks: batches default to 3 concurrent subagents (configurable via `delegation.max_concurrent_children` in config.yaml, no hard ceiling, only a floor of 1) - Nested delegation is opt-in: leaf subagents (default) cannot call `delegate_task`, `clarify`, `memory`, `send_message`, or `execute_code`. Orchestrator subagents (`role="orchestrator"`) retain `delegate_task` for further delegation, but only when `delegation.max_spawn_depth` is raised above the default of 1 (floor 1, no ceiling); the other four remain blocked. Disable globally via `delegation.orchestrator_enabled: false`. ### Tuning Concurrency and Depth | Config | Default | Range | Effect | |––––|———|—––|––––| | `max_concurrent_children` | 3 | >=1 | Parallel batch size per `delegate_task` call | | `max_spawn_depth` | 1 | >=1 | How many delegation levels can spawn further | Example: running 30 parallel workers with nested subagents: `yaml delegation: max_concurrent_children: 30 max_spawn_depth: 2` - Separate terminals — each subagent gets its own terminal session with separate working directory and state - No conversation history — subagents see only the `goal` and `context` the parent agent passes when calling `delegate_task` - Default 50 iterations — set `max_iterations` lower for simple tasks to save cost - Not durable — `delegate_task` is synchronous and runs inside the parent turn. If the parent is interrupted (new user message, `/stop`, `/new`), all active children are cancelled (`status="interrupted"`) and their work is discarded. For work that must outlive the current turn, use `cronjob` or `terminal(background=True, notify_on_complete=True)`. — ## Tips Be specific in goals. “Fix the bug” is too vague. “Fix the TypeError in api/handlers.py line 47 where process_request() receives None from parse_body()” gives the subagent enough to work with. Include file paths. Subagents don’t know your project structure. Always include absolute paths to relevant files, the project root, and the test command. Use delegation for context isolation. Sometimes you want a fresh perspective. Delegating forces you to articulate the problem clearly, and the subagent approaches it without the assumptions that built up in your conversation. Check results. Subagent summaries are just that — summaries. If a subagent says “fixed the bug and tests pass,” verify by running the tests yourself or reading the diff. — For the complete delegation reference — all parameters, ACP integration, and advanced configuration — see Subagent Delegation. — # Tutorial: GitHub PR Review Agent # Tutorial: Build a GitHub PR Review Agent The problem: Your team opens PRs faster than you can review them. PRs sit for days waiting for eyeballs. Junior devs merge bugs because nobody had time to check. You spend your mornings catching up on diffs instead of building. The solution: An AI agent that watches your repos around the clock, reviews every new PR for bugs, security issues, and code quality, and sends you a summary — so you only spend time on PRs that actually need human judgment. What you’ll build: ┌───────────────────────────────────────────────────────────────────┐ │ │ │ Cron Timer ──▶ Hermes Agent ──▶ GitHub API ──▶ Review │ │ (every 2h) + gh CLI (PR diffs) delivery │ │ + skill (Telegram, │ │ + memory Discord, │ │ local) │ │ │ └───────────────────────────────────────────────────────────────────┘ This guide uses cron jobs to poll for PRs on a schedule — no server or public endpoint needed. Works behind NAT and firewalls. :::tip Want real-time reviews instead? If you have a public endpoint available, check out Automated GitHub PR Comments with Webhooks — GitHub pushes events to Hermes instantly when PRs are opened or updated. ::: — ## Prerequisites - Hermes Agent installed — see the Installation guide - Gateway running for cron jobs: `bash hermes gateway install # Install as a service # or hermes gateway # Run in foreground` - GitHub CLI (`gh`) installed and authenticated: `bash # Install brew install gh # macOS sudo apt install gh # Ubuntu/Debian # Authenticate gh auth login` - Messaging configured (optional) — Telegram or Discord :::tip No messaging? No problem Use `deliver: "local"` to save reviews to `~/.hermes/cron/output/`. Great for testing before wiring up notifications. ::: — ## Step 1: Verify the Setup Make sure Hermes can access GitHub. Start a chat: `bash hermes` Test with a simple command: `Run: gh pr list --repo NousResearch/hermes-agent --state open --limit 3` You should see a list of open PRs. If this works, you’re ready. — ## Step 2: Try a Manual Review Still in the chat, ask Hermes to review a real PR: `Review this pull request. Read the diff, check for bugs, security issues, and code quality. Be specific about line numbers and quote problematic code. Run: gh pr diff 3888 --repo NousResearch/hermes-agent` Hermes will: 1. Execute `gh pr diff` to fetch the code changes 2. Read through the entire diff 3. Produce a structured review with specific findings If you’re happy with the quality, time to automate it. — ## Step 3: Create a Review Skill A skill gives Hermes consistent review guidelines that persist across sessions and cron runs. Without one, review quality varies. `bash mkdir -p ~/.hermes/skills/code-review` Create `~/.hermes/skills/code-review/SKILL.md`: markdown --- name: code-review description: Review pull requests for bugs, security issues, and code quality --- # Code Review Guidelines When reviewing a pull request: ## What to Check 1. Bugs — Logic errors, off-by-one, null/undefined handling 2. Security — Injection, auth bypass, secrets in code, SSRF 3. Performance — N+1 queries, unbounded loops, memory leaks 4. Style — Naming conventions, dead code, missing error handling 5. Tests — Are changes tested? Do tests cover edge cases? ## Output Format For each finding: - File:Line — exact location - Severity — Critical / Warning / Suggestion - What's wrong — one sentence - Fix — how to fix it ## Rules - Be specific. Quote the problematic code. - Don't flag style nitpicks unless they affect readability. - If the PR looks good, say so. Don't invent problems. - End with: APPROVE / REQUEST_CHANGES / COMMENT Verify it loaded — start `hermes` and you should see `code-review` in the skills list at startup. — ## Step 4: Teach It Your Conventions This is what makes the reviewer actually useful. Start a session and teach Hermes your team’s standards: `Remember: In our backend repo, we use Python with FastAPI. All endpoints must have type annotations and Pydantic models. We don't allow raw SQL — only SQLAlchemy ORM. Test files go in tests/ and must use pytest fixtures.` Remember: In our frontend repo, we use TypeScript with React. No `any` types allowed. All components must have props interfaces. We use React Query for data fetching, never useEffect for API calls. These memories persist forever — the reviewer will enforce your conventions without being told each time. — ## Step 5: Create the Automated Cron Job Now wire it all together. Create a cron job that runs every 2 hours: bash hermes cron create "0 /2 * " \ "Check for new open PRs and review them. Repos to monitor: - myorg/backend-api - myorg/frontend-app Steps: 1. Run: gh pr list --repo REPO --state open --limit 5 --json number,title,author,createdAt 2. For each PR created or updated in the last 4 hours: - Run: gh pr diff NUMBER --repo REPO - Review the diff using the code-review guidelines 3. Format output as: ## PR Reviews — today ### [repo] #[number]: [title] Author: [name] | Verdict: APPROVE/REQUEST_CHANGES/COMMENT [findings] If no new PRs found, say: No new PRs to review." \ --name "pr-review" \ --deliver telegram \ --skill code-review Verify it’s scheduled: `bash hermes cron list` ### Other useful schedules | Schedule | When | |–––––|——| | `0 /2 * * ` | Every 2 hours | | `0 9,13,17 * 1-5` | Three times a day, weekdays only | | `0 9 * * 1` | Weekly Monday morning roundup | | `30m` | Every 30 minutes (high-traffic repos) | — ## Step 6: Run It On Demand Don’t want to wait for the schedule? Trigger it manually: `bash hermes cron run pr-review` Or from within a chat session: `/cron run pr-review` — ## Going Further ### Post Reviews Directly to GitHub Instead of delivering to Telegram, have the agent comment on the PR itself: Add this to your cron prompt: `After reviewing, post your review: - For issues: gh pr review NUMBER --repo REPO --comment --body "YOUR_REVIEW" - For critical issues: gh pr review NUMBER --repo REPO --request-changes --body "YOUR_REVIEW" - For clean PRs: gh pr review NUMBER --repo REPO --approve --body "Looks good"` :::caution Make sure `gh` has a token with `repo` scope. Reviews are posted as whoever `gh` is authenticated as. ::: ### Weekly PR Dashboard Create a Monday morning overview of all your repos: `bash hermes cron create "0 9 * * 1" \ "Generate a weekly PR dashboard: - myorg/backend-api - myorg/frontend-app - myorg/infra For each repo show: 1. Open PR count and oldest PR age 2. PRs merged this week 3. Stale PRs (older than 5 days) 4. PRs with no reviewer assigned Format as a clean summary." \ --name "weekly-dashboard" \ --deliver telegram` ### Multi-Repo Monitoring Scale up by adding more repos to the prompt. The agent processes them sequentially — no extra setup needed. — ## Troubleshooting ### “gh: command not found” The gateway runs in a minimal environment. Ensure `gh` is in the system PATH and restart the gateway. ### Reviews are too generic 1. Add the `code-review` skill (Step 3) 2. Teach Hermes your conventions via memory (Step 4) 3. The more context it has about your stack, the better the reviews ### Cron job doesn’t run `bash hermes gateway status # Is the gateway running? hermes cron list # Is the job enabled?` ### Rate limits GitHub allows 5,000 API requests/hour for authenticated users. Each PR review uses ~3-5 requests (list + diff + optional comments). Even reviewing 100 PRs/day stays well within limits. — ## What’s Next? - Webhook-Based PR Reviews — get instant reviews when PRs are opened (requires a public endpoint) - Daily Briefing Bot — combine PR reviews with your morning news digest - Build a Plugin — wrap the review logic into a shareable plugin - Profiles — run a dedicated reviewer profile with its own memory and config - Fallback Providers — ensure reviews run even when one provider is down — # Contributing # Contributing Thank you for contributing to Hermes Agent! This guide covers setting up your dev environment, understanding the codebase, and getting your PR merged. ## Contribution Priorities We value contributions in this order: 1. Bug fixes — crashes, incorrect behavior, data loss 2. Cross-platform compatibility — macOS, different Linux distros, WSL2 3. Security hardening — shell injection, prompt injection, path traversal 4. Performance and robustness — retry logic, error handling, graceful degradation 5. New skills — broadly useful ones (see Creating Skills) 6. New tools — rarely needed; most capabilities should be skills 7. Documentation — fixes, clarifications, new examples ## Common contribution paths - Building a custom/local tool without modifying Hermes core? Start with Build a Hermes Plugin - Building a new built-in core tool for Hermes itself? Start with Adding Tools - Building a new skill? Start with Creating Skills - Building a new inference provider? Start with Adding Providers ## Development Setup ### Prerequisites | Requirement | Notes | |———––|—––| | Git | With the `git-lfs` extension installed | | Python 3.11+ | uv will install it if missing | | uv | Fast Python package manager (install) | | Node.js 20+ | Optional — needed for browser tools and WhatsApp bridge (matches root `package.json` engines) | ### Clone and Install `bash git clone https://github.com/NousResearch/hermes-agent.git cd hermes-agent # Create venv with Python 3.11 uv venv venv --python 3.11 export VIRTUAL_ENV="$(pwd)/venv" # Install with all extras (messaging, cron, CLI menus, dev tools) uv pip install -e ".[all,dev]" # Optional: browser tools npm install` ### Configure for Development `bash mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills} cp cli-config.yaml.example ~/.hermes/config.yaml touch ~/.hermes/.env # Add at minimum an LLM provider key: echo 'OPENROUTER_API_KEY=sk-or-v1-your-key' >> ~/.hermes/.env` ### Run `bash # Symlink for global access mkdir -p ~/.local/bin ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes # Verify hermes doctor hermes chat -q "Hello"` ### Run Tests `bash pytest tests/ -v` ## Code Style - PEP 8 with practical exceptions (no strict line length enforcement) - Comments: Only when explaining non-obvious intent, trade-offs, or API quirks - Error handling: Catch specific exceptions. Use `logger.warning()`/`logger.error()` with `exc_info=True` for unexpected errors - Cross-platform: Never assume Unix (see below) - Profile-safe paths: Never hardcode `~/.hermes` — use `get_hermes_home()` from `hermes_constants` for code paths and `display_hermes_home()` for user-facing messages. See AGENTS.md for full rules. ## Cross-Platform Compatibility Hermes officially supports Linux, macOS, WSL2, and native Windows (via PowerShell install). Native Windows uses Git Bash (from Git for Windows) for shell commands. A few features require POSIX kernel primitives and are gated: the dashboard’s embedded PTY terminal pane (`/chat` tab) is WSL2-only. If you’re doing Windows-heavy dev, run the Windows-footgun lint (`scripts/check-windows-footguns.py`) before pushing. When contributing code, keep these rules in mind: - Don’t add unguarded `signal.SIGKILL` references. It’s not defined on Windows. Either route through `gateway.status.terminate_pid(pid, force=True)` (the centralized primitive that does `taskkill /T /F` on Windows and SIGKILL on POSIX), or fall back with `getattr(signal, "SIGKILL", signal.SIGTERM)`. - Catch `OSError` alongside `ProcessLookupError` on `os.kill(pid, 0)` probes. Windows raises `OSError` (WinError 87, “parameter is incorrect”) for an already-gone PID instead of `ProcessLookupError`. - Don’t force the terminal to POSIX semantics. `os.setsid`, `os.killpg`, `os.getpgid`, `os.fork` all raise on Windows — gate them with `if sys.platform != "win32":` or `if os.name != "nt":`. - Open files with an explicit `encoding="utf-8"`. The Python default on Windows is the system locale (often cp1252), which mojibakes or crashes on non-Latin text. - Use `pathlib.Path` / `os.path.join` — never manually concat with `/`. This matters less for strings the OS gives us back and more for strings we construct to hand to subprocesses. Key patterns: ### 1. `termios` and `fcntl` are Unix-only Always catch both `ImportError` and `NotImplementedError`: `python try: from simple_term_menu import TerminalMenu menu = TerminalMenu(options) idx = menu.show() except (ImportError, NotImplementedError): # Fallback: numbered menu for i, opt in enumerate(options): print(f" {i+1}. {opt}") idx = int(input("Choice: ")) - 1` ### 2. File encoding Some environments may save `.env` files in non-UTF-8 encodings: `python try: load_dotenv(env_path) except UnicodeDecodeError: load_dotenv(env_path, encoding="latin-1")` ### 3. Process management `os.setsid()`, `os.killpg()`, and signal handling differ across platforms: `python import platform if platform.system() != "Windows": kwargs["preexec_fn"] = os.setsid` ### 4. Path separators Use `pathlib.Path` instead of string concatenation with `/`. ## Security Considerations Hermes has terminal access. Security matters. ### Existing Protections | Layer | Implementation | |—––|—————| | Sudo password piping | Uses `shlex.quote()` to prevent shell injection | | Dangerous command detection | Regex patterns in `tools/approval.py` with user approval flow | | Cron prompt injection | Scanner blocks instruction-override patterns | | Write deny list | Protected paths resolved via `os.path.realpath()` to prevent symlink bypass | | Skills guard | Security scanner for hub-installed skills | | Code execution sandbox | Child process runs with API keys stripped | | Container hardening | Docker: all capabilities dropped, no privilege escalation, PID limits | ### Contributing Security-Sensitive Code - Always use `shlex.quote()` when interpolating user input into shell commands - Resolve symlinks with `os.path.realpath()` before access control checks - Don’t log secrets - Catch broad exceptions around tool execution - Test on all platforms if your change touches file paths or processes ## Pull Request Process ### Branch Naming `fix/description # Bug fixes feat/description # New features docs/description # Documentation test/description # Tests refactor/description # Code restructuring` ### Before Submitting 1. Run tests: `pytest tests/ -v` 2. Test manually: Run `hermes` and exercise the code path you changed 3. Check cross-platform impact: Consider macOS and different Linux distros 4. Keep PRs focused: One logical change per PR ### PR Description Include: - What changed and why - How to test it - What platforms you tested on - Reference any related issues ### Commit Messages We use Conventional Commits: `<type>(<scope>): <description>` | Type | Use for | |——|———| | `fix` | Bug fixes | | `feat` | New features | | `docs` | Documentation | | `test` | Tests | | `refactor` | Code restructuring | | `chore` | Build, CI, dependency updates | Scopes: `cli`, `gateway`, `tools`, `skills`, `agent`, `install`, `whatsapp`, `security` Examples: `fix(cli): prevent crash in save_config_value when model is a string feat(gateway): add WhatsApp multi-user session isolation fix(security): prevent shell injection in sudo password piping` ## Reporting Issues - Use GitHub Issues - Include: OS, Python version, Hermes version (`hermes version`), full error traceback - Include steps to reproduce - Check existing issues before creating duplicates - For security vulnerabilities, please report privately ## Community - Discord: discord.gg/NousResearch - GitHub Discussions: For design proposals and architecture discussions - Skills Hub: Upload specialized skills and share with the community ## License By contributing, you agree that your contributions will be licensed under the MIT License. — # Architecture # Architecture This page is the top-level map of Hermes Agent internals. Use it to orient yourself in the codebase, then dive into subsystem-specific docs for implementation details. ## System Overview text ┌─────────────────────────────────────────────────────────────────────┐ │ Entry Points │ │ │ │ CLI (cli.py) Gateway (gateway/run.py) ACP (acp_adapter/) │ │ Batch Runner API Server Python Library │ └──────────┬──────────────┬───────────────────────┬───────────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ AIAgent (run_agent.py) │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Prompt │ │ Provider │ │ Tool │ │ │ │ Builder │ │ Resolution │ │ Dispatch │ │ │ │ (prompt_ │ │ (runtime_ │ │ (model_ │ │ │ │ builder.py) │ │ provider.py)│ │ tools.py) │ │ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ │ │ │ │ ┌──────┴───────┐ ┌──────┴───────┐ ┌──────┴───────┐ │ │ │ Compression │ │ 3 API Modes │ │ Tool Registry│ │ │ │ & Caching │ │ chat_compl. │ │ (registry.py)│ │ │ │ │ │ codex_resp. │ │ 70+ tools │ │ │ │ │ │ anthropic │ │ 28 toolsets │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────┴─────────────────┴─────────────────┴───────────────────────┘ │ │ ▼ ▼ ┌───────────────────┐ ┌──────────────────────┐ │ Session Storage │ │ Tool Backends │ │ (SQLite + FTS5) │ │ Terminal (6 backends) │ │ hermes_state.py │ │ Browser (5 backends) │ │ gateway/session.py│ │ Web (4 backends) │ └───────────────────┘ │ MCP (dynamic) │ │ File, Vision, etc. │ └──────────────────────┘ ## Directory Structure text hermes-agent/ ├── run_agent.py # AIAgent — core conversation loop (large file) ├── cli.py # HermesCLI — interactive terminal UI (large file) ├── model_tools.py # Tool discovery, schema collection, dispatch ├── toolsets.py # Tool groupings and platform presets ├── hermes_state.py # SQLite session/state database with FTS5 ├── hermes_constants.py # HERMES_HOME, profile-aware paths ├── batch_runner.py # Batch trajectory generation │ ├── agent/ # Agent internals │ ├── prompt_builder.py # System prompt assembly │ ├── context_engine.py # ContextEngine ABC (pluggable) │ ├── context_compressor.py # Default engine — lossy summarization │ ├── prompt_caching.py # Anthropic prompt caching │ ├── auxiliary_client.py # Auxiliary LLM for side tasks (vision, summarization) │ ├── model_metadata.py # Model context lengths, token estimation │ ├── models_dev.py # models.dev registry integration │ ├── anthropic_adapter.py # Anthropic Messages API format conversion │ ├── display.py # KawaiiSpinner, tool preview formatting │ ├── skill_commands.py # Skill slash commands │ ├── memory_manager.py # Memory manager orchestration │ ├── memory_provider.py # Memory provider ABC │ └── trajectory.py # Trajectory saving helpers │ ├── hermes_cli/ # CLI subcommands and setup │ ├── main.py # Entry point — all `hermes` subcommands (large file) │ ├── config.py # DEFAULT_CONFIG, OPTIONAL_ENV_VARS, migration │ ├── commands.py # COMMAND_REGISTRY — central slash command definitions │ ├── auth.py # PROVIDER_REGISTRY, credential resolution │ ├── runtime_provider.py # Provider → api_mode + credentials │ ├── models.py # Model catalog, provider model lists │ ├── model_switch.py # /model command logic (CLI + gateway shared) │ ├── setup.py # Interactive setup wizard (large file) │ ├── skin_engine.py # CLI theming engine │ ├── skills_config.py # hermes skills — enable/disable per platform │ ├── skills_hub.py # /skills slash command │ ├── tools_config.py # hermes tools — enable/disable per platform │ ├── plugins.py # PluginManager — discovery, loading, hooks │ ├── callbacks.py # Terminal callbacks (clarify, sudo, approval) │ └── gateway.py # hermes gateway start/stop │ ├── tools/ # Tool implementations (one file per tool) │ ├── registry.py # Central tool registry │ ├── approval.py # Dangerous command detection │ ├── terminal_tool.py # Terminal orchestration │ ├── process_registry.py # Background process management │ ├── file_tools.py # read_file, write_file, patch, search_files │ ├── web_tools.py # web_search, web_extract │ ├── browser_tool.py # 10 browser automation tools │ ├── code_execution_tool.py # execute_code sandbox │ ├── delegate_tool.py # Subagent delegation │ ├── mcp_tool.py # MCP client (large file) │ ├── credential_files.py # File-based credential passthrough │ ├── env_passthrough.py # Env var passthrough for sandboxes │ ├── ansi_strip.py # ANSI escape stripping │ └── environments/ # Terminal backends (local, docker, ssh, modal, daytona, singularity) │ ├── gateway/ # Messaging platform gateway │ ├── run.py # GatewayRunner — message dispatch (large file) │ ├── session.py # SessionStore — conversation persistence │ ├── delivery.py # Outbound message delivery │ ├── pairing.py # DM pairing authorization │ ├── hooks.py # Hook discovery and lifecycle events │ ├── mirror.py # Cross-session message mirroring │ ├── status.py # Token locks, profile-scoped process tracking │ ├── builtin_hooks/ # Extension point for always-registered hooks (none shipped) │ └── platforms/ # 20 adapters: telegram, discord, slack, whatsapp, │ # signal, matrix, mattermost, email, sms, │ # dingtalk, feishu, wecom, wecom_callback, weixin, │ # bluebubbles, qqbot, homeassistant, webhook, api_server, │ # yuanbao │ ├── acp_adapter/ # ACP server (VS Code / Zed / JetBrains) ├── cron/ # Scheduler (jobs.py, scheduler.py) ├── plugins/memory/ # Memory provider plugins ├── plugins/context_engine/ # Context engine plugins ├── skills/ # Bundled skills (always available) ├── optional-skills/ # Official optional skills (install explicitly) ├── website/ # Docusaurus documentation site └── tests/ # Pytest suite (~25,000 tests across ~1,250 files) ## Data Flow ### CLI Session `text User input → HermesCLI.process_input() → AIAgent.run_conversation() → prompt_builder.build_system_prompt() → runtime_provider.resolve_runtime_provider() → API call (chat_completions / codex_responses / anthropic_messages) → tool_calls? → model_tools.handle_function_call() → loop → final response → display → save to SessionDB` ### Gateway Message `text Platform event → Adapter.on_message() → MessageEvent → GatewayRunner._handle_message() → authorize user → resolve session key → create AIAgent with session history → AIAgent.run_conversation() → deliver response back through adapter` ### Cron Job `text Scheduler tick → load due jobs from jobs.json → create fresh AIAgent (no history) → inject attached skills as context → run job prompt → deliver response to target platform → update job state and next_run` ## Recommended Reading Order If you are new to the codebase: 1. This page — orient yourself 2. Agent Loop Internals — how AIAgent works 3. Prompt Assembly — system prompt construction 4. Provider Runtime Resolution — how providers are selected 5. Adding Providers — practical guide to adding a new provider 6. Tools Runtime — tool registry, dispatch, environments 7. Session Storage — SQLite schema, FTS5, session lineage 8. Gateway Internals — messaging platform gateway 9. Context Compression & Prompt Caching — compression and caching 10. ACP Internals — IDE integration ## Major Subsystems ### Agent Loop The synchronous orchestration engine (`AIAgent` in `run_agent.py`). Handles provider selection, prompt construction, tool execution, retries, fallback, callbacks, compression, and persistence. Supports three API modes for different provider backends. → Agent Loop Internals ### Prompt System Prompt construction and maintenance across the conversation lifecycle: - `system_prompt.py` + `prompt_builder.py` — assembles the ordered system-prompt tiers (`stable` → `context` → `volatile`): identity/tool guidance/skills, context files, then memory/profile/timestamp blocks - `prompt_caching.py` — Applies Anthropic cache breakpoints for prefix caching - `context_compressor.py` — Summarizes middle conversation turns when context exceeds thresholds → Prompt Assembly, Context Compression & Prompt Caching ### Provider Resolution A shared runtime resolver used by CLI, gateway, cron, ACP, and auxiliary calls. Maps `(provider, model)` tuples to `(api_mode, api_key, base_url)`. Handles 18+ providers, OAuth flows, credential pools, and alias resolution. → Provider Runtime Resolution ### Tool System Central tool registry (`tools/registry.py`) with 70+ registered tools across ~28 toolsets. Each tool file self-registers at import time. The registry handles schema collection, dispatch, availability checking, and error wrapping. Terminal tools support 6 backends (local, Docker, SSH, Daytona, Modal, Singularity). → Tools Runtime ### Session Persistence SQLite-based session storage with FTS5 full-text search. Sessions have lineage tracking (parent/child across compressions), per-platform isolation, and atomic writes with contention handling. → Session Storage ### Messaging Gateway Long-running process with 20 platform adapters, unified session routing, user authorization (allowlists + DM pairing), slash command dispatch, hook system, cron ticking, and background maintenance. → Gateway Internals ### Plugin System Three discovery sources: `~/.hermes/plugins/` (user), `.hermes/plugins/` (project), and pip entry points. Plugins register tools, hooks, and CLI commands through a context API. Two specialized plugin types exist: memory providers (`plugins/memory/`) and context engines (`plugins/context_engine/`). Both are single-select — only one of each can be active at a time, configured via `hermes plugins` or `config.yaml`. → Plugin Guide, Memory Provider Plugin ### Cron First-class agent tasks (not shell tasks). Jobs store in JSON, support multiple schedule formats, can attach skills and scripts, and deliver to any platform. → Cron Internals ### ACP Integration Exposes Hermes as an editor-native agent over stdio/JSON-RPC for VS Code, Zed, and JetBrains. → ACP Internals ### Trajectories Generates ShareGPT-format trajectories from agent sessions for training data generation. → Trajectories & Training Format ## Design Principles | Principle | What it means in practice | |———–|–––––––––––––| | Prompt stability | System prompt doesn’t change mid-conversation. No cache-breaking mutations except explicit user actions (`/model`). | | Observable execution | Every tool call is visible to the user via callbacks. Progress updates in CLI (spinner) and gateway (chat messages). | | Interruptible | API calls and tool execution can be cancelled mid-flight by user input or signals. | | Platform-agnostic core | One AIAgent class serves CLI, gateway, ACP, batch, and API server. Platform differences live in the entry point, not the agent. | | Loose coupling | Optional subsystems (MCP, plugins, memory providers, RL environments) use registry patterns and check_fn gating, not hard dependencies. | | Profile isolation | Each profile (`hermes -p <name>`) gets its own HERMES_HOME, config, memory, sessions, and gateway PID. Multiple profiles run concurrently. | ## File Dependency Chain `text tools/registry.py (no deps — imported by all tool files) ↑ tools/.py (each calls registry.register() at import time) ↑ model_tools.py (imports tools/registry + triggers tool discovery) ↑ run_agent.py, cli.py, batch_runner.py, environments/` This chain means tool registration happens at import time, before any agent instance is created. Any `tools/.py` file with a top-level `registry.register()` call is auto-discovered — no manual import list needed. — # Agent Loop Internals # Agent Loop Internals The core orchestration engine is `run_agent.py`’s `AIAgent` class — a large file that handles everything from prompt assembly to tool dispatch to provider failover. ## Core Responsibilities `AIAgent` is responsible for: - Assembling the effective system prompt and tool schemas via `prompt_builder.py` - Selecting the correct provider/API mode (chat_completions, codex_responses, anthropic_messages) - Making interruptible model calls with cancellation support - Executing tool calls (sequentially or concurrently via thread pool) - Maintaining conversation history in OpenAI message format - Handling compression, retries, and fallback model switching - Tracking iteration budgets across parent and child agents - Flushing persistent memory before context is lost ## Two Entry Points `python # Simple interface — returns final response string response = agent.chat("Fix the bug in main.py") # Full interface — returns dict with messages, metadata, usage stats result = agent.run_conversation( user_message="Fix the bug in main.py", system_message=None, # auto-built if omitted conversation_history=None, # auto-loaded from session if omitted task_id="task_abc123" )` `chat()` is a thin wrapper around `run_conversation()` that extracts the `final_response` field from the result dict. ## API Modes Hermes supports three API execution modes, resolved from provider selection, explicit args, and base URL heuristics: | API mode | Used for | Client type | |–––––|–––––|———––| | `chat_completions` | OpenAI-compatible endpoints (OpenRouter, custom, most providers) | `openai.OpenAI` | | `codex_responses` | OpenAI Codex / Responses API | `openai.OpenAI` with Responses format | | `anthropic_messages` | Native Anthropic Messages API | `anthropic.Anthropic` via adapter | The mode determines how messages are formatted, how tool calls are structured, how responses are parsed, and how caching/streaming works. All three converge on the same internal message format (OpenAI-style `role`/`content`/`tool_calls` dicts) before and after API calls. Mode resolution order: 1. Explicit `api_mode` constructor arg (highest priority) 2. Provider-specific detection (e.g., `anthropic` provider → `anthropic_messages`) 3. Base URL heuristics (e.g., `api.anthropic.com` → `anthropic_messages`) 4. Default: `chat_completions` ## Turn Lifecycle Each iteration of the agent loop follows this sequence: text run_conversation() 1. Generate task_id if not provided 2. Append user message to conversation history 3. Build or reuse cached system prompt (prompt_builder.py) 4. Check if preflight compression is needed (>50% context) 5. Build API messages from conversation history - chat_completions: OpenAI format as-is - codex_responses: convert to Responses API input items - anthropic_messages: convert via anthropic_adapter.py 6. Inject ephemeral prompt layers (budget warnings, context pressure) 7. Apply prompt caching markers if on Anthropic 8. Make interruptible API call (_interruptible_api_call) 9. Parse response: - If tool_calls: execute them, append results, loop back to step 5 - If text response: persist session, flush memory if needed, return ### Message Format All messages use OpenAI-compatible format internally: `python {"role": "system", "content": "..."} {"role": "user", "content": "..."} {"role": "assistant", "content": "...", "tool_calls": [...]} {"role": "tool", "tool_call_id": "...", "content": "..."}` Reasoning content (from models that support extended thinking) is stored in `assistant_msg["reasoning"]` and optionally displayed via the `reasoning_callback`. ### Message Alternation Rules The agent loop enforces strict message role alternation: - After the system message: `User → Assistant → User → Assistant → ...` - During tool calling: `Assistant (with tool_calls) → Tool → Tool → ... → Assistant` - Never two assistant messages in a row - Never two user messages in a row - Only `tool` role can have consecutive entries (parallel tool results) Providers validate these sequences and will reject malformed histories. ## Interruptible API Calls API requests are wrapped in `_interruptible_api_call()` which runs the actual HTTP call in a background thread while monitoring an interrupt event: `text ┌────────────────────────────────────────────────────┐ │ Main thread API thread │ │ │ │ wait on: HTTP POST │ │ - response ready ───▶ to provider │ │ - interrupt event │ │ - timeout │ └────────────────────────────────────────────────────┘` When interrupted (user sends new message, `/stop` command, or signal): - The API thread is abandoned (response discarded) - The agent can process the new input or shut down cleanly - No partial response is injected into conversation history ## Tool Execution ### Sequential vs Concurrent When the model returns tool calls: - Single tool call → executed directly in the main thread - Multiple tool calls → executed concurrently via `ThreadPoolExecutor` - Exception: tools marked as interactive (e.g., `clarify`) force sequential execution - Results are reinserted in the original tool call order regardless of completion order ### Execution Flow `text for each tool_call in response.tool_calls: 1. Resolve handler from tools/registry.py 2. Fire pre_tool_call plugin hook 3. Check if dangerous command (tools/approval.py) - If dangerous: invoke approval_callback, wait for user 4. Execute handler with args + task_id 5. Fire post_tool_call plugin hook 6. Append {"role": "tool", "content": result} to history` ### Agent-Level Tools Some tools are intercepted by `run_agent.py` before reaching `handle_function_call()`: | Tool | Why intercepted | |——|––––––––––| | `todo` | Reads/writes agent-local task state | | `memory` | Writes to persistent memory files with character limits | | `session_search` | Queries session history via the agent’s session DB | | `delegate_task` | Spawns subagent(s) with isolated context | These tools modify agent state directly and return synthetic tool results without going through the registry. ## Callback Surfaces `AIAgent` supports platform-specific callbacks that enable real-time progress in the CLI, gateway, and ACP integrations: | Callback | When fired | Used by | |–––––|———–|———| | `tool_progress_callback` | Before/after each tool execution | CLI spinner, gateway progress messages | | `thinking_callback` | When model starts/stops thinking | CLI “thinking…” indicator | | `reasoning_callback` | When model returns reasoning content | CLI reasoning display, gateway reasoning blocks | | `clarify_callback` | When `clarify` tool is called | CLI input prompt, gateway interactive message | | `step_callback` | After each complete agent turn | Gateway step tracking, ACP progress | | `stream_delta_callback` | Each streaming token (when enabled) | CLI streaming display | | `tool_gen_callback` | When tool call is parsed from stream | CLI tool preview in spinner | | `status_callback` | State changes (thinking, executing, etc.) | ACP status updates | ## Budget and Fallback Behavior ### Iteration Budget The agent tracks iterations via `IterationBudget`: - Default: 90 iterations (configurable via `agent.max_turns`) - Each agent gets its own budget. Subagents get independent budgets capped at `delegation.max_iterations` (default 50) — total iterations across parent + subagents can exceed the parent’s cap - At 100%, the agent stops and returns a summary of work done ### Fallback Model When the primary model fails (429 rate limit, 5xx server error, 401/403 auth error): 1. Check `fallback_providers` list in config 2. Try each fallback in order 3. On success, continue the conversation with the new provider 4. On 401/403, attempt credential refresh before failing over The fallback system also covers auxiliary tasks independently — vision, compression, and web extraction each have their own fallback chain configurable via the `auxiliary.` config section. ## Compression and Persistence ### When Compression Triggers - Preflight (before API call): If conversation exceeds 50% of model’s context window - Gateway auto-compression: If conversation exceeds 85% (more aggressive, runs between turns) ### What Happens During Compression 1. Memory is flushed to disk first (preventing data loss) 2. Middle conversation turns are summarized into a compact summary 3. The last N messages are preserved intact (`compression.protect_last_n`, default: 20) 4. Tool call/result message pairs are kept together (never split) 5. A new session lineage ID is generated (compression creates a “child” session) ### Session Persistence After each turn: - Messages are saved to the session store (SQLite via `hermes_state.py`) - Memory changes are flushed to `MEMORY.md` / `USER.md` - The session can be resumed later via `/resume` or `hermes chat --resume` ## Key Source Files | File | Purpose | |——|———| | `run_agent.py` | AIAgent class — the complete agent loop | | `agent/prompt_builder.py` | System prompt assembly from memory, skills, context files, personality | | `agent/context_engine.py` | ContextEngine ABC — pluggable context management | | `agent/context_compressor.py` | Default engine — lossy summarization algorithm | | `agent/prompt_caching.py` | Anthropic prompt caching markers and cache metrics | | `agent/auxiliary_client.py` | Auxiliary LLM client for side tasks (vision, summarization) | | `model_tools.py` | Tool schema collection, `handle_function_call()` dispatch | ## Related Docs - Provider Runtime Resolution - Prompt Assembly - Context Compression & Prompt Caching - Tools Runtime - Architecture Overview — # Prompt Assembly # Prompt Assembly Hermes deliberately separates: - cached system prompt state - ephemeral API-call-time additions This is one of the most important design choices in the project because it affects: - token usage - prompt caching effectiveness - session continuity - memory correctness Primary files: - `run_agent.py` - `agent/prompt_builder.py` - `tools/memory_tool.py` ## Cached system prompt layers The cached system prompt is assembled as three ordered tiers (see `agent/system_prompt.py`): 1. stable — identity (`SOUL.md` or fallback), tool/model guidance, skills prompt, environment hints, platform hints 2. context — caller-supplied `system_message` plus project context files (`.hermes.md` / `AGENTS.md` / `CLAUDE.md` / `.cursorrules`) 3. volatile — built-in memory snapshot (`MEMORY.md`), user profile snapshot (`USER.md`), external memory-provider block, timestamp/session/model/provider line The final system prompt is then joined as: `stable` → `context` → `volatile`. This ordering matters for precedence discussions: - skills are part of the stable tier - memory/profile snapshots are part of the volatile tier - both are still in the cached system prompt (they are not injected as ad-hoc mid-turn overlays) When `skip_context_files` is set (e.g., subagent delegation), SOUL.md is not loaded and the hardcoded `DEFAULT_AGENT_IDENTITY` is used instead. ### Concrete example: assembled system prompt Here is a simplified view of what the final system prompt looks like when all layers are present (comments show the source of each section): # Layer 1: Agent Identity (from ~/.hermes/SOUL.md) You are Hermes, an AI assistant created by Nous Research. You are an expert software engineer and researcher. You value correctness, clarity, and efficiency. ... # Layer 2: Tool-aware behavior guidance You have persistent memory across sessions. Save durable facts using the memory tool: user preferences, environment details, tool quirks, and stable conventions. Memory is injected into every turn, so keep it compact and focused on facts that will still matter later. ... When the user references something from a past conversation or you suspect relevant cross-session context exists, use session_search to recall it before asking them to repeat themselves. # Tool-use enforcement (for GPT/Codex models only) You MUST use your tools to take action — do not describe what you would do or plan to do without actually doing it. ... # Layer 3: Honcho static block (when active) [Honcho personality/context data] # Layer 4: Optional system message (from config or API) [User-configured system message override] # Layer 5: Frozen MEMORY snapshot ## Persistent Memory - User prefers Python 3.12, uses pyproject.toml - Default editor is nvim - Working on project "atlas" in ~/code/atlas - Timezone: US/Pacific # Layer 6: Frozen USER profile snapshot ## User Profile - Name: Alice - GitHub: alice-dev # Layer 7: Skills index ## Skills (mandatory) Before replying, scan the skills below. If one clearly matches your task, load it with skill_view(name) and follow its instructions. ... <available_skills> software-development: - code-review: Structured code review workflow - test-driven-development: TDD methodology research: - arxiv: Search and summarize arXiv papers </available_skills> # Layer 8: Context files (from project directory) # Project Context The following project context files have been loaded and should be followed: ## AGENTS.md This is the atlas project. Use pytest for testing. The main entry point is src/atlas/main.py. Always run `make lint` before committing. # Layer 9: Timestamp + session Current time: 2026-03-30T14:30:00-07:00 Session: abc123 # Layer 10: Platform hint You are a CLI AI Agent. Try not to use markdown but simple text renderable inside a terminal. ## How SOUL.md appears in the prompt `SOUL.md` lives at `~/.hermes/SOUL.md` and serves as the agent’s identity — the very first section of the system prompt. The loading logic in `prompt_builder.py` works as follows: `python # From agent/prompt_builder.py (simplified) def load_soul_md() -> Optional[str]: soul_path = get_hermes_home() / "SOUL.md" if not soul_path.exists(): return None content = soul_path.read_text(encoding="utf-8").strip() content = _scan_context_content(content, "SOUL.md") # Security scan content = _truncate_content(content, "SOUL.md") # Cap at 20k chars return content` When `load_soul_md()` returns content, it replaces the hardcoded `DEFAULT_AGENT_IDENTITY`. The `build_context_files_prompt()` function is then called with `skip_soul=True` to prevent SOUL.md from appearing twice (once as identity, once as a context file). If `SOUL.md` doesn’t exist, the system falls back to: You are Hermes Agent, an intelligent AI assistant created by Nous Research. You are helpful, knowledgeable, and direct. You assist users with a wide range of tasks including answering questions, writing and editing code, analyzing information, creative work, and executing actions via your tools. You communicate clearly, admit uncertainty when appropriate, and prioritize being genuinely useful over being verbose unless otherwise directed below. Be targeted and efficient in your exploration and investigations. ## How context files are injected `build_context_files_prompt()` uses a priority system — only one project context type is loaded (first match wins): python # From agent/prompt_builder.py (simplified) def build_context_files_prompt(cwd=None, skip_soul=False): cwd_path = Path(cwd).resolve() # Priority: first match wins — only ONE project context loaded project_context = ( _load_hermes_md(cwd_path) # 1. .hermes.md / HERMES.md (walks to git root) or _load_agents_md(cwd_path) # 2. AGENTS.md (cwd only) or _load_claude_md(cwd_path) # 3. CLAUDE.md (cwd only) or _load_cursorrules(cwd_path) # 4. .cursorrules / .cursor/rules/.mdc ) sections = [] if project_context: sections.append(project_context) # SOUL.md from HERMES_HOME (independent of project context) if not skip_soul: soul_content = load_soul_md() if soul_content: sections.append(soul_content) if not sections: return "" return ( "# Project Context\n\n" "The following project context files have been loaded " "and should be followed:\n\n" + "\n".join(sections) ) ### Context file discovery details | Priority | Files | Search scope | Notes | |–––––|—––|———––|—––| | 1 | `.hermes.md`, `HERMES.md` | CWD up to git root | Hermes-native project config | | 2 | `AGENTS.md` | CWD only | Common agent instruction file | | 3 | `CLAUDE.md` | CWD only | Claude Code compatibility | | 4 | `.cursorrules`, `.cursor/rules/.mdc` | CWD only | Cursor compatibility | All context files are: - Security scanned — checked for prompt injection patterns (invisible unicode, “ignore previous instructions”, credential exfiltration attempts) - Truncated — capped at 20,000 characters using 70/20 head/tail ratio with a truncation marker - YAML frontmatter stripped — `.hermes.md` frontmatter is removed (reserved for future config overrides) ## API-call-time-only layers These are intentionally not* persisted as part of the cached system prompt: - `ephemeral_system_prompt` - prefill messages - gateway-derived session context overlays - later-turn Honcho/external recall injected into the current-turn user message `pre_llm_call` plugin context also lands in this API-call-time path: it is appended to the current turn’s user message, not written into the cached system prompt. When multiple plugins return context, Hermes concatenates those context blocks (see Hooks → `pre_llm_call`). This separation keeps the stable prefix stable for caching. ## Memory snapshots Local memory and user profile data are captured in the system prompt’s volatile tier. Mid-session writes update disk state but do not mutate the already-built cached system prompt until a rebuild path runs (new session, or explicit invalidation/rebuild flow such as compression-triggered rebuild). ## Context files `agent/prompt_builder.py` scans and sanitizes project context files using a priority system — only one type is loaded (first match wins): 1. `.hermes.md` / `HERMES.md` (walks to git root) 2. `AGENTS.md` (CWD at startup; subdirectories discovered progressively during the session via `agent/subdirectory_hints.py`) 3. `CLAUDE.md` (CWD only) 4. `.cursorrules` / `.cursor/rules/.mdc` (CWD only) `SOUL.md` is loaded separately via `load_soul_md()` for the identity slot. When it loads successfully, `build_context_files_prompt(skip_soul=True)` prevents it from appearing twice. Long files are truncated before injection. ## Skills index The skills system contributes a compact skills index to the prompt when skills tooling is available. ## Supported prompt customization surfaces Most users should treat `agent/prompt_builder.py` as implementation code, not a configuration surface. The supported customization path is to change the prompt inputs Hermes already loads, rather than editing Python templates in place. ### Use these surfaces first - `~/.hermes/SOUL.md` — replace the built-in default identity block with your own agent persona and standing behavior. - `~/.hermes/MEMORY.md` and `~/.hermes/USER.md` — provide durable cross-session facts and user profile data that should be snapshotted into new sessions. - Project context files such as `.hermes.md`, `HERMES.md`, `AGENTS.md`, `CLAUDE.md`, or `.cursorrules` — inject repo-specific working rules. - Skills — package reusable workflows and references without editing core prompt code. - Optional system prompt config / API overrides — add deployment-specific instruction text without forking Hermes. - Ephemeral overlays such as `HERMES_EPHEMERAL_SYSTEM_PROMPT` or prefill messages — add turn-scoped guidance that should not become part of the cached prompt prefix. ### When to edit code instead Edit `agent/prompt_builder.py` only if you are intentionally maintaining a fork or contributing upstream behavior changes. That file assembles the prompt plumbing, cache boundaries, and injection order for every session. Direct edits there are global product changes, not per-user prompt customization. In other words: - if you want a different assistant identity, edit `SOUL.md` - if you want different repo rules, edit project context files - if you want reusable operating procedures, add or modify skills - if you want to change how Hermes assembles prompts for everyone, change Python and treat it as a code contribution ## Why prompt assembly is split this way The architecture is intentionally optimized to: - preserve provider-side prompt caching - avoid mutating history unnecessarily - keep memory semantics understandable - let gateway/ACP/CLI add context without poisoning persistent prompt state ## Related docs - Context Compression & Prompt Caching - Session Storage - Gateway Internals — # developer-guide/context-compression-and-caching # Context Compression and Caching Hermes Agent uses a dual compression system and Anthropic prompt caching to manage context window usage efficiently across long conversations. Source files: `agent/context_engine.py` (ABC), `agent/context_compressor.py` (default engine), `agent/prompt_caching.py`, `gateway/run.py` (session hygiene), `run_agent.py` (search for `_compress_context`) ## Pluggable Context Engine Context management is built on the `ContextEngine` ABC (`agent/context_engine.py`). The built-in `ContextCompressor` is the default implementation, but plugins can replace it with alternative engines (e.g., Lossless Context Management). `yaml context: engine: "compressor" # default — built-in lossy summarization engine: "lcm" # example — plugin providing lossless context` The engine is responsible for: - Deciding when compaction should fire (`should_compress()`) - Performing compaction (`compress()`) - Optionally exposing tools the agent can call (e.g., `lcm_grep`) - Tracking token usage from API responses Selection is config-driven via `context.engine` in `config.yaml`. The resolution order: 1. Check `plugins/context_engine/<name>/` directory 2. Check general plugin system (`register_context_engine()`) 3. Fall back to built-in `ContextCompressor` Plugin engines are never auto-activated — the user must explicitly set `context.engine` to the plugin’s name. The default `"compressor"` always uses the built-in. Configure via `hermes plugins` → Provider Plugins → Context Engine, or edit `config.yaml` directly. For building a context engine plugin, see Context Engine Plugins. ## Dual Compression System Hermes has two separate compression layers that operate independently: ┌──────────────────────────┐ Incoming message │ Gateway Session Hygiene │ Fires at 85% of context ─────────────────► │ (pre-agent, rough est.) │ Safety net for large sessions └─────────────┬────────────┘ │ ▼ ┌──────────────────────────┐ │ Agent ContextCompressor │ Fires at 50% of context (default) │ (in-loop, real tokens) │ Normal context management └──────────────────────────┘ ### 1. Gateway Session Hygiene (85% threshold) Located in `gateway/run.py` (search for `Session hygiene: auto-compress`). This is a safety net that runs before the agent processes a message. It prevents API failures when sessions grow too large between turns (e.g., overnight accumulation in Telegram/Discord). - Threshold: Fixed at 85% of model context length - Token source: Prefers actual API-reported tokens from last turn; falls back to rough character-based estimate (`estimate_messages_tokens_rough`) - Fires: Only when `len(history) >= 4` and compression is enabled - Purpose: Catch sessions that escaped the agent’s own compressor The gateway hygiene threshold is intentionally higher than the agent’s compressor. Setting it at 50% (same as the agent) caused premature compression on every turn in long gateway sessions. ### 2. Agent ContextCompressor (50% threshold, configurable) Located in `agent/context_compressor.py`. This is the primary compression system that runs inside the agent’s tool loop with access to accurate, API-reported token counts. ## Configuration All compression settings are read from `config.yaml` under the `compression` key: yaml compression: enabled: true # Enable/disable compression (default: true) threshold: 0.50 # Fraction of context window (default: 0.50 = 50%) target_ratio: 0.20 # How much of threshold to keep as tail (default: 0.20) protect_last_n: 20 # Minimum protected tail messages (default: 20) codex_gpt55_autoraise: true # gpt-5.5 on Codex OAuth: raise trigger to 85% (default: true) # Summarization model/provider configured under auxiliary: auxiliary: compression: model: null # Override model for summaries (default: auto-detect) provider: auto # Provider: "auto", "openrouter", "nous", "main", etc. base_url: null # Custom OpenAI-compatible endpoint ### Parameter Details | Parameter | Default | Range | Description | |———–|———|—––|———––| | `threshold` | `0.50` | 0.0-1.0 | Compression triggers when prompt tokens ≥ `threshold × context_length` | | `target_ratio` | `0.20` | 0.10-0.80 | Controls tail protection token budget: `threshold_tokens × target_ratio` | | `protect_last_n` | `20` | ≥1 | Minimum number of recent messages always preserved | | `protect_first_n` | `3` | (hardcoded) | System prompt + first exchange always preserved | | `codex_gpt55_autoraise` | `true` | bool | Raise the trigger to 85% for gpt-5.5 on the ChatGPT Codex OAuth route (see below). Set `false` to keep the global `threshold` | ### Codex gpt-5.5 threshold autoraise The ChatGPT Codex OAuth backend hard-caps gpt-5.5 at a 272K context window (the same slug exposes 1.05M on OpenAI’s direct API and OpenRouter, and 400K on GitHub Copilot). At the default 50% trigger, compaction would fire at ~136K — half the window the model can actually use. When the active route is Codex OAuth (`provider: openai-codex`) and the model is gpt-5.5, Hermes raises the trigger to 85% (~231K) and prints a one-time notice with the opt-out command. Only this exact route is affected; gpt-5.5 on any other provider keeps your global `threshold`. To opt back down to the global value: `bash hermes config set compression.codex_gpt55_autoraise false` ### Computed Values (for a 200K context model at defaults) `context_length = 200,000 threshold_tokens = 200,000 × 0.50 = 100,000 tail_token_budget = 100,000 × 0.20 = 20,000 max_summary_tokens = min(200,000 × 0.05, 12,000) = 10,000` :::note Threshold is derived from the MAIN model’s context window `threshold_tokens` is always `threshold × context_length`, where `context_length` is the main agent model’s context window — never the auxiliary/summary model’s. On a 262,144-token model at the default `0.50`, the threshold is `262,144 × 0.50 = 131,072`. That number being close to a common “128K context” is a coincidence of the percentage, not a sign that the auxiliary model’s window is the trigger. The auxiliary model’s context window is a separate concern — see the “Summary model context length” warning below for how it affects whether a summary can be produced, not when compression fires. ::: ## Compression Algorithm The `ContextCompressor.compress()` method follows a 4-phase algorithm: ### Phase 1: Prune Old Tool Results (cheap, no LLM call) Old tool results (>200 chars) outside the protected tail are replaced with: `[Old tool output cleared to save context space]` This is a cheap pre-pass that saves significant tokens from verbose tool outputs (file contents, terminal output, search results). ### Phase 2: Determine Boundaries ┌─────────────────────────────────────────────────────────────┐ │ Message list │ │ │ │ [0..2] ← protect_first_n (system + first exchange) │ │ [3..N] ← middle turns → SUMMARIZED │ │ [N..end] ← tail (by token budget OR protect_last_n) │ │ │ └─────────────────────────────────────────────────────────────┘ Tail protection is token-budget based: walks backward from the end, accumulating tokens until the budget is exhausted. Falls back to the fixed `protect_last_n` count if the budget would protect fewer messages. Boundaries are aligned to avoid splitting tool_call/tool_result groups. The `_align_boundary_backward()` method walks past consecutive tool results to find the parent assistant message, keeping groups intact. ### Phase 3: Generate Structured Summary :::warning Summary model context length The summary model must have a context window at least as large as the main agent model’s. The entire middle section is sent to the summary model in a single `call_llm(task="compression")` call. If the summary model’s context is smaller, the API returns a context-length error — `_generate_summary()` catches it, logs a warning, and returns `None`. The compressor then drops the middle turns without a summary, silently losing conversation context. This is the most common cause of degraded compaction quality. ::: The middle turns are summarized using the auxiliary LLM with a structured template: ## Goal [What the user is trying to accomplish] ## Constraints & Preferences [User preferences, coding style, constraints, important decisions] ## Progress ### Done [Completed work — specific file paths, commands run, results] ### In Progress [Work currently underway] ### Blocked [Any blockers or issues encountered] ## Key Decisions [Important technical decisions and why] ## Relevant Files [Files read, modified, or created — with brief note on each] ## Next Steps [What needs to happen next] ## Critical Context [Specific values, error messages, configuration details] Summary budget scales with the amount of content being compressed: - Formula: `content_tokens × 0.20` (the `_SUMMARY_RATIO` constant) - Minimum: 2,000 tokens - Maximum: `min(context_length × 0.05, 12,000)` tokens ### Phase 4: Assemble Compressed Messages The compressed message list is: 1. Head messages (with a note appended to system prompt on first compression) 2. Summary message (role chosen to avoid consecutive same-role violations) 3. Tail messages (unmodified) Orphaned tool_call/tool_result pairs are cleaned up by `_sanitize_tool_pairs()`: - Tool results referencing removed calls → removed - Tool calls whose results were removed → stub result injected ### Iterative Re-compression On subsequent compressions, the previous summary is passed to the LLM with instructions to update it rather than summarize from scratch. This preserves information across multiple compactions — items move from “In Progress” to “Done”, new progress is added, and obsolete information is removed. The `_previous_summary` field on the compressor instance stores the last summary text for this purpose. ## Before/After Example ### Before Compression (45 messages, ~95K tokens) [0] system: "You are a helpful assistant..." (system prompt) [1] user: "Help me set up a FastAPI project" [2] assistant: <tool_call> terminal: mkdir project </tool_call> [3] tool: "directory created" [4] assistant: <tool_call> write_file: main.py </tool_call> [5] tool: "file written (2.3KB)" ... 30 more turns of file editing, testing, debugging ... [38] assistant: <tool_call> terminal: pytest </tool_call> [39] tool: "8 passed, 2 failed\n..." (5KB output) [40] user: "Fix the failing tests" [41] assistant: <tool_call> read_file: tests/test_api.py </tool_call> [42] tool: "import pytest\n..." (3KB) [43] assistant: "I see the issue with the test fixtures..." [44] user: "Great, also add error handling" ### After Compression (25 messages, ~45K tokens) [0] system: "You are a helpful assistant... [Note: Some earlier conversation turns have been compacted...]" [1] user: "Help me set up a FastAPI project" [2] assistant: "[CONTEXT COMPACTION] Earlier turns were compacted... ## Goal Set up a FastAPI project with tests and error handling ## Progress ### Done - Created project structure: main.py, tests/, requirements.txt - Implemented 5 API endpoints in main.py - Wrote 10 test cases in tests/test_api.py - 8/10 tests passing ### In Progress - Fixing 2 failing tests (test_create_user, test_delete_user) ## Relevant Files - main.py — FastAPI app with 5 endpoints - tests/test_api.py — 10 test cases - requirements.txt — fastapi, pytest, httpx ## Next Steps - Fix failing test fixtures - Add error handling" [3] user: "Fix the failing tests" [4] assistant: <tool_call> read_file: tests/test_api.py </tool_call> [5] tool: "import pytest\n..." [6] assistant: "I see the issue with the test fixtures..." [7] user: "Great, also add error handling" ## Prompt Caching (Anthropic) Source: `agent/prompt_caching.py` Reduces input token costs by ~75% on multi-turn conversations by caching the conversation prefix. Uses Anthropic’s `cache_control` breakpoints. ### Strategy: system_and_3 Anthropic allows a maximum of 4 `cache_control` breakpoints per request. Hermes uses the “system_and_3” strategy: `Breakpoint 1: System prompt (stable across all turns) Breakpoint 2: 3rd-to-last non-system message ─┐ Breakpoint 3: 2nd-to-last non-system message ├─ Rolling window Breakpoint 4: Last non-system message ─┘` ### How It Works `apply_anthropic_cache_control()` deep-copies the messages and injects `cache_control` markers: `python # Cache marker format marker = {"type": "ephemeral"} # Or for 1-hour TTL: marker = {"type": "ephemeral", "ttl": "1h"}` The marker is applied differently based on content type: | Content Type | Where Marker Goes | |———––|—————––| | String content | Converted to `[{"type": "text", "text": ..., "cache_control": ...}]` | | List content | Added to the last element’s dict | | None/empty | Added as `msg["cache_control"]` | | Tool messages | Added as `msg["cache_control"]` (native Anthropic only) | ### Cache-Aware Design Patterns 1. Stable system prompt: The system prompt is breakpoint 1 and cached across all turns. Avoid mutating it mid-conversation (compression appends a note only on the first compaction). 2. Message ordering matters: Cache hits require prefix matching. Adding or removing messages in the middle invalidates the cache for everything after. 3. Compression cache interaction: After compression, the cache is invalidated for the compressed region but the system prompt cache survives. The rolling 3-message window re-establishes caching within 1-2 turns. 4. TTL selection: Default is `5m` (5 minutes). Use `1h` for long-running sessions where the user takes breaks between turns. ### Enabling Prompt Caching Prompt caching is automatically enabled when: - The model is an Anthropic Claude model (detected by model name) - The provider supports `cache_control` (native Anthropic API or OpenRouter) `yaml # config.yaml — TTL is configurable (must be "5m" or "1h") prompt_caching: cache_ttl: "5m"` The CLI shows caching status at startup: `💾 Prompt caching: ENABLED (Claude via OpenRouter, 5m TTL)` ## Context Pressure Warnings Intermediate context-pressure warnings have been removed (see the iteration-budget block in `run_agent.py`, which notes: “No intermediate pressure warnings — they caused models to ‘give up’ prematurely on complex tasks”). Compression fires when prompt tokens reach the configured `compression.threshold` (default 50%) with no prior warning step; gateway session hygiene fires as the secondary safety net at 85% of the model’s context window. — # Gateway Internals # Gateway Internals The messaging gateway is the long-running process that connects Hermes to 20+ external messaging platforms through a unified architecture. ## Key Files | File | Purpose | |——|———| | `gateway/run.py` | `GatewayRunner` — main loop, slash commands, message dispatch (large file; check git for current LOC) | | `gateway/session.py` | `SessionStore` — conversation persistence and session key construction | | `gateway/delivery.py` | Outbound message delivery to target platforms/channels | | `gateway/pairing.py` | DM pairing flow for user authorization | | `gateway/channel_directory.py` | Maps chat IDs to human-readable names for cron delivery | | `gateway/hooks.py` | Hook discovery, loading, and lifecycle event dispatch | | `gateway/mirror.py` | Cross-session message mirroring for `send_message` | | `gateway/status.py` | Token lock management for profile-scoped gateway instances | | `gateway/builtin_hooks/` | Extension point for always-registered hooks (none shipped) | | `gateway/platforms/` | Platform adapters (one per messaging platform) | ## Architecture Overview text ┌─────────────────────────────────────────────────┐ │ GatewayRunner │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Telegram │ │ Discord │ │ Slack │ │ │ │ Adapter │ │ Adapter │ │ Adapter │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ │ └─────────────┼─────────────┘ │ │ ▼ │ │ _handle_message() │ │ │ │ │ ┌───────────┼───────────┐ │ │ ▼ ▼ ▼ │ │ Slash command AIAgent Queue/BG │ │ dispatch creation sessions │ │ │ │ │ ▼ │ │ SessionStore │ │ (SQLite persistence) │ └───────┴─────────────┴─────────────┴─────────────┘ ## Message Flow When a message arrives from any platform: 1. Platform adapter receives raw event, normalizes it into a `MessageEvent` 2. Base adapter checks active session guard: - If agent is running for this session → queue message, set interrupt event - If `/approve`, `/deny`, `/stop` → bypass guard (dispatched inline) 3. GatewayRunner._handle_message() receives the event: - Resolve session key via `_session_key_for_source()` (format: `agent:main:{platform}:{chat_type}:{chat_id}`) - Check authorization (see Authorization below) - Check if it’s a slash command → dispatch to command handler - Check if agent is already running → intercept commands like `/stop`, `/status` - Otherwise → create `AIAgent` instance and run conversation 4. Response is sent back through the platform adapter ### Session Key Format Session keys encode the full routing context: `agent:main:{platform}:{chat_type}:{chat_id}` For example: `agent:main:telegram:private:123456789` Thread-aware platforms (Telegram forum topics, Discord threads, Slack threads) may include thread IDs in the chat_id portion. Never construct session keys manually — always use `build_session_key()` from `gateway/session.py`. ### Two-Level Message Guard When an agent is actively running, incoming messages pass through two sequential guards: 1. Level 1 — Base adapter (`gateway/platforms/base.py`): Checks `_active_sessions`. If the session is active, queues the message in `_pending_messages` and sets an interrupt event. This catches messages before* they reach the gateway runner. 2. Level 2 — Gateway runner (`gateway/run.py`): Checks `_running_agents`. Intercepts specific commands (`/stop`, `/new`, `/queue`, `/status`, `/approve`, `/deny`) and routes them appropriately. Everything else triggers `running_agent.interrupt()`. Commands that must reach the runner while the agent is blocked (like `/approve`) are dispatched inline via `await self._message_handler(event)` — they bypass the background task system to avoid race conditions. ## Authorization The gateway uses a multi-layer authorization check, evaluated in order: 1. Per-platform allow-all flag (e.g., `TELEGRAM_ALLOW_ALL_USERS`) — if set, all users on that platform are authorized 2. Platform allowlist (e.g., `TELEGRAM_ALLOWED_USERS`) — comma-separated user IDs 3. DM pairing — authenticated users can pair new users via a pairing code 4. Global allow-all (`GATEWAY_ALLOW_ALL_USERS`) — if set, all users across all platforms are authorized 5. Default: deny — unauthorized users are rejected ### DM Pairing Flow `text Admin: /pair Gateway: "Pairing code: ABC123. Share with the user." New user: ABC123 Gateway: "Paired! You're now authorized."` Pairing state is persisted in `gateway/pairing.py` and survives restarts. ## Slash Command Dispatch All slash commands in the gateway flow through the same resolution pipeline: 1. `resolve_command()` from `hermes_cli/commands.py` maps input to canonical name (handles aliases, prefix matching) 2. The canonical name is checked against `GATEWAY_KNOWN_COMMANDS` 3. Handler in `_handle_message()` dispatches based on canonical name 4. Some commands are gated on config (`gateway_config_gate` on `CommandDef`) ### Running-Agent Guard Commands that must NOT execute while the agent is processing are rejected early: `python if _quick_key in self._running_agents: if canonical == "model": return "⏳ Agent is running — wait for it to finish or /stop first."` Bypass commands (`/stop`, `/new`, `/approve`, `/deny`, `/queue`, `/status`) have special handling. ## Config Sources The gateway reads configuration from multiple sources: | Source | What it provides | |––––|—————–| | `~/.hermes/.env` | API keys, bot tokens, platform credentials | | `~/.hermes/config.yaml` | Model settings, tool configuration, display options | | Environment variables | Override any of the above | Unlike the CLI (which uses `load_cli_config()` with hardcoded defaults), the gateway reads `config.yaml` directly via YAML loader. This means config keys that exist in the CLI’s defaults dict but not in the user’s config file may behave differently between CLI and gateway. ## Platform Adapters Each messaging platform has an adapter in `gateway/platforms/`: text gateway/platforms/ ├── base.py # BaseAdapter — shared logic for all platforms ├── telegram.py # Telegram Bot API (long polling or webhook) ├── discord.py # Discord bot via discord.py ├── slack.py # Slack Socket Mode ├── whatsapp.py # WhatsApp Business Cloud API ├── signal.py # Signal via signal-cli REST API ├── matrix.py # Matrix via mautrix (optional E2EE) ├── mattermost.py # Mattermost WebSocket API ├── email.py # Email via IMAP/SMTP ├── sms.py # SMS via Twilio ├── dingtalk.py # DingTalk WebSocket ├── feishu.py # Feishu/Lark WebSocket or webhook ├── wecom.py # WeCom (WeChat Work) callback ├── weixin.py # Weixin (personal WeChat) via iLink Bot API ├── bluebubbles.py # Apple iMessage via BlueBubbles macOS server ├── qqbot/ # QQ Bot (Tencent QQ) via Official API v2 (sub-package: adapter.py, crypto.py, keyboards.py, …) ├── yuanbao.py # Yuanbao (Tencent) DM/group adapter ├── feishu_comment.py # Feishu document/drive comment-reply handler ├── msgraph_webhook.py # Microsoft Graph change-notification webhook (Teams, Outlook, etc.) ├── webhook.py # Inbound/outbound webhook adapter ├── api_server.py # REST API server adapter └── homeassistant.py # Home Assistant conversation integration Adapters implement a common interface: - `connect()` / `disconnect()` — lifecycle management - `send_message()` — outbound message delivery - `on_message()` — inbound message normalization → `MessageEvent` ### Token Locks Adapters that connect with unique credentials call `acquire_scoped_lock()` in `connect()` and `release_scoped_lock()` in `disconnect()`. This prevents two profiles from using the same bot token simultaneously. ## Delivery Path Outgoing deliveries (`gateway/delivery.py`) handle: - Direct reply — send response back to the originating chat - Home channel delivery — route cron job outputs and background results to a configured home channel - Explicit target delivery — `send_message` tool specifying `telegram:-1001234567890`, or the `hermes send` CLI wrapping the same tool for shell scripts - Cross-platform delivery — deliver to a different platform than the originating message Cron job deliveries are NOT mirrored into gateway session history — they live in their own cron session only. This is a deliberate design choice to avoid message alternation violations. ## Hooks Gateway hooks are Python modules that respond to lifecycle events: ### Gateway Hook Events | Event | When fired | |—––|———–| | `gateway:startup` | Gateway process starts | | `session:start` | New conversation session begins | | `session:end` | Session completes or times out | | `session:reset` | User resets session with `/new` | | `agent:start` | Agent begins processing a message | | `agent:step` | Agent completes one tool-calling iteration | | `agent:end` | Agent finishes and returns response | | `command:` | Any slash command is executed | Hooks are discovered from `gateway/builtin_hooks/` (an extension point — currently empty in the shipped distribution; `_register_builtin_hooks()` is a no-op stub) and `~/.hermes/hooks/` (user-installed). Each hook is a directory with a `HOOK.yaml` manifest and `handler.py`. ## Memory Provider Integration When a memory provider plugin (e.g., Honcho) is enabled: 1. Gateway creates an `AIAgent` per message with the session ID 2. The `MemoryManager` initializes the provider with the session context 3. Provider tools (e.g., `honcho_profile`, `viking_search`) are routed through: `text AIAgent._invoke_tool() → self._memory_manager.handle_tool_call(name, args) → provider.handle_tool_call(name, args)` 4. On session end/reset, `on_session_end()` fires for cleanup and final data flush ### Memory Flush Lifecycle When a session is reset, resumed, or expires: 1. Built-in memories are flushed to disk 2. Memory provider’s `on_session_end()` hook fires 3. A temporary `AIAgent` runs a memory-only conversation turn 4. Context is then discarded or archived ## Background Maintenance The gateway runs periodic maintenance alongside message handling: - Cron ticking — checks job schedules and fires due jobs - Session expiry — cleans up abandoned sessions after timeout - Memory flush — proactively flushes memory before session expiry - Cache refresh — refreshes model lists and provider status ## Process Management The gateway runs as a long-lived process, managed via: - `hermes gateway start` / `hermes gateway stop` — manual control - `systemctl` (Linux) or `launchctl` (macOS) — service management - PID file at `~/.hermes/gateway.pid` — profile-scoped process tracking Profile-scoped vs global: `start_gateway()` uses profile-scoped PID files. `hermes gateway stop` stops only the current profile’s gateway. `hermes gateway stop --all` uses global `ps aux` scanning to kill all gateway processes (used during updates). ## Related Docs - Session Storage - Cron Internals - ACP Internals - Agent Loop Internals - Messaging Gateway (User Guide) — # developer-guide/session-storage # Session Storage Hermes Agent uses a SQLite database (`~/.hermes/state.db`) to persist session metadata, full message history, and model configuration across CLI and gateway sessions. This replaces the earlier per-session JSONL file approach. Source file: `hermes_state.py` ## Architecture Overview `~/.hermes/state.db (SQLite, WAL mode) ├── sessions — Session metadata, token counts, billing ├── messages — Full message history per session ├── messages_fts — FTS5 virtual table (content + tool_name + tool_calls) ├── messages_fts_trigram — FTS5 virtual table with trigram tokenizer (CJK / substring search) ├── state_meta — Key/value metadata table └── schema_version — Single-row table tracking migration state` Key design decisions: - WAL mode for concurrent readers + one writer (gateway multi-platform) - FTS5 virtual table for fast text search across all session messages - Session lineage via `parent_session_id` chains (compression-triggered splits) - Source tagging (`cli`, `telegram`, `discord`, etc.) for platform filtering - Batch runner and RL trajectories are NOT stored here (separate systems) ## SQLite Schema ### Sessions Table sql CREATE TABLE IF NOT EXISTS sessions ( id TEXT PRIMARY KEY, source TEXT NOT NULL, user_id TEXT, model TEXT, model_config TEXT, system_prompt TEXT, parent_session_id TEXT, started_at REAL NOT NULL, ended_at REAL, end_reason TEXT, message_count INTEGER DEFAULT 0, tool_call_count INTEGER DEFAULT 0, input_tokens INTEGER DEFAULT 0, output_tokens INTEGER DEFAULT 0, cache_read_tokens INTEGER DEFAULT 0, cache_write_tokens INTEGER DEFAULT 0, reasoning_tokens INTEGER DEFAULT 0, billing_provider TEXT, billing_base_url TEXT, billing_mode TEXT, estimated_cost_usd REAL, actual_cost_usd REAL, cost_status TEXT, cost_source TEXT, pricing_version TEXT, title TEXT, api_call_count INTEGER DEFAULT 0, FOREIGN KEY (parent_session_id) REFERENCES sessions(id) ); CREATE INDEX IF NOT EXISTS idx_sessions_source ON sessions(source); CREATE INDEX IF NOT EXISTS idx_sessions_parent ON sessions(parent_session_id); CREATE INDEX IF NOT EXISTS idx_sessions_started ON sessions(started_at DESC); CREATE UNIQUE INDEX IF NOT EXISTS idx_sessions_title_unique ON sessions(title) WHERE title IS NOT NULL; ### Messages Table `sql CREATE TABLE IF NOT EXISTS messages ( id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL REFERENCES sessions(id), role TEXT NOT NULL, content TEXT, tool_call_id TEXT, tool_calls TEXT, tool_name TEXT, timestamp REAL NOT NULL, token_count INTEGER, finish_reason TEXT, reasoning TEXT, reasoning_content TEXT, reasoning_details TEXT, codex_reasoning_items TEXT, codex_message_items TEXT ); CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_id, timestamp);` Notes: - `tool_calls` is stored as a JSON string (serialized list of tool call objects) - `reasoning_details`, `codex_reasoning_items`, and `codex_message_items` are stored as JSON strings - `reasoning` stores the raw reasoning text for providers that expose it - Timestamps are Unix epoch floats (`time.time()`) ### FTS5 Full-Text Search `sql CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5( content, content=messages, content_rowid=id );` The FTS5 table is kept in sync via three triggers that fire on INSERT, UPDATE, and DELETE of the `messages` table: sql CREATE TRIGGER IF NOT EXISTS messages_fts_insert AFTER INSERT ON messages BEGIN INSERT INTO messages_fts(rowid, content) VALUES (new.id, new.content); END; CREATE TRIGGER IF NOT EXISTS messages_fts_delete AFTER DELETE ON messages BEGIN INSERT INTO messages_fts(messages_fts, rowid, content) VALUES('delete', old.id, old.content); END; CREATE TRIGGER IF NOT EXISTS messages_fts_update AFTER UPDATE ON messages BEGIN INSERT INTO messages_fts(messages_fts, rowid, content) VALUES('delete', old.id, old.content); INSERT INTO messages_fts(rowid, content) VALUES (new.id, new.content); END; ## Schema Version and Migrations Current schema version: 11 The `schema_version` table stores a single integer. Simple column additions are handled declaratively by `_reconcile_columns()` (which diffs live columns against `SCHEMA_SQL` and ADDs any missing ones). The version-gated chain is reserved for data migrations and index/FTS changes that can’t be expressed declaratively: | Version | Change | |———|––––| | 1 | Initial schema (sessions, messages, FTS5) | | 2 | Add `finish_reason` column to messages | | 3 | Add `title` column to sessions | | 4 | Add unique index on `title` (NULLs allowed, non-NULL must be unique) | | 5 | Add billing columns: `cache_read_tokens`, `cache_write_tokens`, `reasoning_tokens`, `billing_provider`, `billing_base_url`, `billing_mode`, `estimated_cost_usd`, `actual_cost_usd`, `cost_status`, `cost_source`, `pricing_version` | | 6 | Add reasoning columns to messages: `reasoning`, `reasoning_details`, `codex_reasoning_items` | | 7 | Add `reasoning_content` column to messages | | 8 | Add `api_call_count` column to sessions | | 9 | Add `codex_message_items` column to messages for Codex Responses message id/phase replay | | 10 | Add `messages_fts_trigram` virtual table (trigram tokenizer for CJK / substring search) and backfill existing rows | | 11 | Re-index `messages_fts` and `messages_fts_trigram` to cover `tool_name` + `tool_calls` and switch from external-content to inline mode; drop old triggers and backfill every message row | Declarative column adds use `ALTER TABLE ADD COLUMN` wrapped in try/except to handle the column-already-exists case (idempotent). The version number is bumped after each successful migration block. ## Write Contention Handling Multiple hermes processes (gateway + CLI sessions + worktree agents) share one `state.db`. The `SessionDB` class handles write contention with: - Short SQLite timeout (1 second) instead of the default 30s - Application-level retry with random jitter (20-150ms, up to 15 retries) - BEGIN IMMEDIATE transactions to surface lock contention at transaction start - Periodic WAL checkpoints every 50 successful writes (PASSIVE mode) This avoids the “convoy effect” where SQLite’s deterministic internal backoff causes all competing writers to retry at the same intervals. `_WRITE_MAX_RETRIES = 15 _WRITE_RETRY_MIN_S = 0.020 # 20ms _WRITE_RETRY_MAX_S = 0.150 # 150ms _CHECKPOINT_EVERY_N_WRITES = 50` ## Common Operations ### Initialize `python from hermes_state import SessionDB db = SessionDB() # Default: ~/.hermes/state.db db = SessionDB(db_path=Path("/tmp/test.db")) # Custom path` ### Create and Manage Sessions `python # Create a new session db.create_session( session_id="sess_abc123", source="cli", model="anthropic/claude-sonnet-4.6", user_id="user_1", parent_session_id=None, # or previous session ID for lineage ) # End a session db.end_session("sess_abc123", end_reason="user_exit") # Reopen a session (clear ended_at/end_reason) db.reopen_session("sess_abc123")` ### Store Messages `python msg_id = db.append_message( session_id="sess_abc123", role="assistant", content="Here's the answer...", tool_calls=[{"id": "call_1", "function": {"name": "terminal", "arguments": "{}"}}], token_count=150, finish_reason="stop", reasoning="Let me think about this...", )` ### Retrieve Messages `python # Raw messages with all metadata messages = db.get_messages("sess_abc123") # OpenAI conversation format (for API replay) conversation = db.get_messages_as_conversation("sess_abc123") # Returns: [{"role": "user", "content": "..."}, {"role": "assistant", ...}]` ### Session Titles `python # Set a title (must be unique among non-NULL titles) db.set_session_title("sess_abc123", "Fix Docker Build") # Resolve by title (returns most recent in lineage) session_id = db.resolve_session_by_title("Fix Docker Build") # Auto-generate next title in lineage next_title = db.get_next_title_in_lineage("Fix Docker Build") # Returns: "Fix Docker Build #2"` ## Full-Text Search The `search_messages()` method supports FTS5 query syntax with automatic sanitization of user input. ### Basic Search `python results = db.search_messages("docker deployment")` ### FTS5 Query Syntax | Syntax | Example | Meaning | |––––|———|———| | Keywords | `docker deployment` | Both terms (implicit AND) | | Quoted phrase | `"exact phrase"` | Exact phrase match | | Boolean OR | `docker OR kubernetes` | Either term | | Boolean NOT | `python NOT java` | Exclude term | | Prefix | `deploy` | Prefix match | ### Filtered Search `python # Search only CLI sessions results = db.search_messages("error", source_filter=["cli"]) # Exclude gateway sessions results = db.search_messages("bug", exclude_sources=["telegram", "discord"]) # Search only user messages results = db.search_messages("help", role_filter=["user"])` ### Search Results Format Each result includes: - `id`, `session_id`, `role`, `timestamp` - `snippet` — FTS5-generated snippet with `>>>match<<<` markers - `context` — 1 message before and after the match (content truncated to 200 chars) - `source`, `model`, `session_started` — from the parent session The `_sanitize_fts5_query()` method handles edge cases: - Strips unmatched quotes and special characters - Wraps hyphenated terms in quotes (`chat-send` → `"chat-send"`) - Removes dangling boolean operators (`hello AND` → `hello`) ## Session Lineage Sessions can form chains via `parent_session_id`. This happens when context compression triggers a session split in the gateway. ### Query: Find Session Lineage `sql -- Find all ancestors of a session WITH RECURSIVE lineage AS ( SELECT * FROM sessions WHERE id = ? UNION ALL SELECT s.* FROM sessions s JOIN lineage l ON s.id = l.parent_session_id ) SELECT id, title, started_at, parent_session_id FROM lineage; -- Find all descendants of a session WITH RECURSIVE descendants AS ( SELECT * FROM sessions WHERE id = ? UNION ALL SELECT s.* FROM sessions s JOIN descendants d ON s.parent_session_id = d.id ) SELECT id, title, started_at FROM descendants;` ### Query: Recent Sessions with Preview `sql SELECT s., COALESCE( (SELECT SUBSTR(m.content, 1, 63) FROM messages m WHERE m.session_id = s.id AND m.role = 'user' AND m.content IS NOT NULL ORDER BY m.timestamp, m.id LIMIT 1), '' ) AS preview, COALESCE( (SELECT MAX(m2.timestamp) FROM messages m2 WHERE m2.session_id = s.id), s.started_at ) AS last_active FROM sessions s ORDER BY s.started_at DESC LIMIT 20;` ### Query: Token Usage Statistics `sql -- Total tokens by model SELECT model, COUNT() as session_count, SUM(input_tokens) as total_input, SUM(output_tokens) as total_output, SUM(estimated_cost_usd) as total_cost FROM sessions WHERE model IS NOT NULL GROUP BY model ORDER BY total_cost DESC; -- Sessions with highest token usage SELECT id, title, model, input_tokens + output_tokens AS total_tokens, estimated_cost_usd FROM sessions ORDER BY total_tokens DESC LIMIT 10;` ## Export and Cleanup `python # Export a single session with messages data = db.export_session("sess_abc123") # Export all sessions (with messages) as list of dicts all_data = db.export_all(source="cli") # Delete old sessions (only ended sessions) deleted_count = db.prune_sessions(older_than_days=90) deleted_count = db.prune_sessions(older_than_days=30, source="telegram") # Clear messages but keep the session record db.clear_messages("sess_abc123") # Delete session and all messages db.delete_session("sess_abc123")` ## Database Location Default path: `~/.hermes/state.db` This is derived from `hermes_constants.get_hermes_home()` which resolves to `~/.hermes/` by default, or the value of `HERMES_HOME` environment variable. The database file, WAL file (`state.db-wal`), and shared-memory file (`state.db-shm`) are all created in the same directory. — # Provider Runtime Resolution # Provider Runtime Resolution Hermes has a shared provider runtime resolver used across: - CLI - gateway - cron jobs - ACP - auxiliary model calls Primary implementation: - `hermes_cli/runtime_provider.py` — credential resolution, `_resolve_custom_runtime()` - `hermes_cli/auth.py` — provider registry, `resolve_provider()` - `hermes_cli/model_switch.py` — shared `/model` switch pipeline (CLI + gateway) - `agent/auxiliary_client.py` — auxiliary model routing - `providers/` — ABC + registry entry points (`ProviderProfile`, `register_provider`, `get_provider_profile`, `list_providers`) - `plugins/model-providers/<name>/` — per-provider plugins (bundled) that declare `api_mode`, `base_url`, `env_vars`, `fallback_models` and register themselves into the registry on first access. User plugins at `$HERMES_HOME/plugins/model-providers/<name>/` override bundled ones of the same name. `get_provider_profile()` in `providers/` returns a `ProviderProfile` for a given provider id. `runtime_provider.py` calls this at resolution time to get the canonical `base_url`, `env_vars` priority list, `api_mode`, and `fallback_models` without needing to duplicate that data in multiple files. Adding a new plugin under `plugins/model-providers/<your-provider>/` (or `$HERMES_HOME/plugins/model-providers/<your-provider>/`) that calls `register_provider()` is enough for `runtime_provider.py` to pick it up — no branch needed in the resolver itself. If you are trying to add a new first-class inference provider, read Adding Providers and the Model Provider Plugin guide alongside this page. ## Resolution precedence At a high level, provider resolution uses: 1. explicit CLI/runtime request 2. `config.yaml` model/provider config 3. environment variables 4. provider-specific defaults or auto resolution That ordering matters because Hermes treats the saved model/provider choice as the source of truth for normal runs. This prevents a stale shell export from silently overriding the endpoint a user last selected in `hermes model`. ## Providers Current provider families include (see `plugins/model-providers/` for the complete bundled set): - OpenRouter - Nous Portal - OpenAI Codex - Copilot / Copilot ACP - Anthropic (native) - Google / Gemini (`gemini`, `google-gemini-cli`) - Alibaba / DashScope (`alibaba`, `alibaba-coding-plan`) - DeepSeek - Z.AI - Kimi / Moonshot (`kimi-coding`, `kimi-coding-cn`) - MiniMax (`minimax`, `minimax-cn`, `minimax-oauth`) - Kilo Code - Hugging Face - OpenCode Zen / OpenCode Go - AWS Bedrock - Azure Foundry - NVIDIA NIM - xAI (Grok) - Arcee - GMI Cloud - StepFun - Qwen OAuth - Xiaomi - Ollama Cloud - LM Studio - Tencent TokenHub - Custom (`provider: custom`) — first-class provider for any OpenAI-compatible endpoint - Named custom providers (`custom_providers` list in config.yaml) ## Output of runtime resolution The runtime resolver returns data such as: - `provider` - `api_mode` - `base_url` - `api_key` - `source` - provider-specific metadata like expiry/refresh info ## Why this matters This resolver is the main reason Hermes can share auth/runtime logic between: - `hermes chat` - gateway message handling - cron jobs running in fresh sessions - ACP editor sessions - auxiliary model tasks ## OpenRouter and custom OpenAI-compatible base URLs Hermes contains logic to avoid leaking the wrong API key to a custom endpoint when multiple provider keys exist (e.g. `OPENROUTER_API_KEY` and `OPENAI_API_KEY`). Each provider’s API key is scoped to its own base URL: - `OPENROUTER_API_KEY` is only sent to `openrouter.ai` endpoints - `OPENAI_API_KEY` is used for custom endpoints and as a fallback Hermes also distinguishes between: - a real custom endpoint selected by the user - the OpenRouter fallback path used when no custom endpoint is configured That distinction is especially important for: - local model servers - non-OpenRouter OpenAI-compatible APIs - switching providers without re-running setup - config-saved custom endpoints that should keep working even when `OPENAI_BASE_URL` is not exported in the current shell ## Native Anthropic path Anthropic is not just “via OpenRouter” anymore. When provider resolution selects `anthropic`, Hermes uses: - `api_mode = anthropic_messages` - the native Anthropic Messages API - `agent/anthropic_adapter.py` for translation Credential resolution for native Anthropic now prefers refreshable Claude Code credentials over copied env tokens when both are present. In practice that means: - Claude Code credential files are treated as the preferred source when they include refreshable auth - manual `ANTHROPIC_TOKEN` / `CLAUDE_CODE_OAUTH_TOKEN` values still work as explicit overrides - Hermes preflights Anthropic credential refresh before native Messages API calls - Hermes still retries once on a 401 after rebuilding the Anthropic client, as a fallback path ## OpenAI Codex path Codex uses a separate Responses API path: - `api_mode = codex_responses` - dedicated credential resolution and auth store support ## Auxiliary model routing Auxiliary tasks such as: - vision - web extraction summarization - context compression summaries - skills hub operations - MCP helper operations - memory flushes can use their own provider/model routing rather than the main conversational model. When an auxiliary task is configured with provider `main`, Hermes resolves that through the same shared runtime path as normal chat. In practice that means: - env-driven custom endpoints still work - custom endpoints saved via `hermes model` / `config.yaml` also work - auxiliary routing can tell the difference between a real saved custom endpoint and the OpenRouter fallback ## Fallback models Hermes supports a configured fallback provider chain — a list of `(provider, model)` entries tried in order when the primary model encounters errors. The legacy single-pair `fallback_model` dict is still accepted for back-compat (and migrated on first write). ### How it works internally 1. Storage: `AIAgent.init` stores the `fallback_model` dict and sets `_fallback_activated = False`. 2. Trigger points: `_try_activate_fallback()` is called from three places in the main retry loop in `run_agent.py`: - After max retries on invalid API responses (None choices, missing content) - On non-retryable client errors (HTTP 401, 403, 404) - After max retries on transient errors (HTTP 429, 500, 502, 503) 3. Activation flow (`_try_activate_fallback`): - Returns `False` immediately if already activated or not configured - Calls `resolve_provider_client()` from `auxiliary_client.py` to build a new client with proper auth - Determines `api_mode`: `codex_responses` for openai-codex, `anthropic_messages` for anthropic, `chat_completions` for everything else - Swaps in-place: `self.model`, `self.provider`, `self.base_url`, `self.api_mode`, `self.client`, `self._client_kwargs` - For anthropic fallback: builds a native Anthropic client instead of OpenAI-compatible - Re-evaluates prompt caching (enabled for Claude models on OpenRouter) - Sets `_fallback_activated = True` — prevents firing again - Resets retry count to 0 and continues the loop 4. Config flow: - CLI: `cli.py` reads `CLI_CONFIG["fallback_model"]` → passes to `AIAgent(fallback_model=...)` - Gateway: `gateway/run.py._load_fallback_model()` reads `config.yaml` → passes to `AIAgent` - Validation: both `provider` and `model` keys must be non-empty, or fallback is disabled ### What does NOT support fallback - Subagent delegation (`tools/delegate_tool.py`): subagents inherit the parent’s provider but not the fallback config - Auxiliary tasks: use their own independent provider auto-detection chain (see Auxiliary model routing above) Cron jobs do support fallback: `run_job()` reads `fallback_providers` (or legacy `fallback_model`) from `config.yaml` and passes it to `AIAgent(fallback_model=...)`, matching the gateway’s `_load_fallback_model()` pattern. See Cron Internals. ### Test coverage Fallback behavior is exercised across several suites: - `tests/run_agent/test_fallback_credential_isolation.py` — credential isolation between primary and fallback - `tests/hermes_cli/test_fallback_cmd.py` — the `/fallback` CLI command - `tests/gateway/test_fallback_eviction.py` — gateway eviction of failed providers ## Related docs - Agent Loop Internals - ACP Internals - Context Compression & Prompt Caching — # Adding Tools # Adding Tools Before writing a tool, ask yourself: should this be a skill instead? :::warning Built-in Core Tools Only This page is for adding a built-in Hermes tool to the repository itself. If you want a personal, project-local, or otherwise custom tool without modifying Hermes core, use the plugin route instead: - Plugins - Build a Hermes Plugin Default to plugins for most custom tool creation. Only follow this page when you explicitly want to ship a new built-in tool in `tools/` and `toolsets.py`. ::: Make it a Skill when the capability can be expressed as instructions + shell commands + existing tools (arXiv search, git workflows, Docker management, PDF processing). Make it a Tool when it requires end-to-end integration with API keys, custom processing logic, binary data handling, or streaming (browser automation, TTS, vision analysis). ## Overview Adding a tool touches 2 files: 1. `tools/your_tool.py` — handler, schema, check function, `registry.register()` call 2. `toolsets.py` — add tool name to `_HERMES_CORE_TOOLS` (or a specific toolset) Any `tools/*.py` file with a top-level `registry.register()` call is auto-discovered at startup — no manual import list required. ## Step 1: Create the Built-in Tool File Every tool file follows the same structure: python # tools/weather_tool.py """Weather Tool -- look up current weather for a location.""" import json import os import logging logger = logging.getLogger(name) # --- Availability check --- def check_weather_requirements() -> bool: """Return True if the tool's dependencies are available.""" return bool(os.getenv("WEATHER_API_KEY")) # --- Handler --- def weather_tool(location: str, units: str = "metric") -> str: """Fetch weather for a location. Returns JSON string.""" api_key = os.getenv("WEATHER_API_KEY") if not api_key: return json.dumps({"error": "WEATHER_API_KEY not configured"}) try: # ... call weather API ... return json.dumps({"location": location, "temp": 22, "units": units}) except Exception as e: return json.dumps({"error": str(e)}) # --- Schema --- WEATHER_SCHEMA = { "name": "weather", "description": "Get current weather for a location.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "City name or coordinates (e.g. 'London' or '51.5,-0.1')" }, "units": { "type": "string", "enum": ["metric", "imperial"], "description": "Temperature units (default: metric)", "default": "metric" } }, "required": ["location"] } } # --- Registration --- from tools.registry import registry registry.register( name="weather", toolset="weather", schema=WEATHER_SCHEMA, handler=lambda args, kw: weather_tool( location=args.get("location", ""), units=args.get("units", "metric")), check_fn=check_weather_requirements, requires_env=["WEATHER_API_KEY"], ) ### Key Rules :::danger Important - Handlers MUST return a JSON string (via `json.dumps()`), never raw dicts - Errors MUST be returned as `{"error": "message"}`, never raised as exceptions - The `check_fn` is called when building tool definitions — if it returns `False`, the tool is silently excluded - The `handler` receives `(args: dict, kwargs)` where `args` is the LLM’s tool call arguments ::: ## Step 2: Add the Built-in Tool to a Toolset In `toolsets.py`, add the tool name: `python # If it should be available on all platforms (CLI + messaging): _HERMES_CORE_TOOLS = [ ... "weather", # <-- add here ] # Or create a new standalone toolset: "weather": { "description": "Weather lookup tools", "tools": ["weather"], "includes": [] },` ## Step 3: Add Discovery Import (No longer needed) Tool modules with a top-level `registry.register()` call are auto-discovered by `discover_builtin_tools()` in `tools/registry.py`. No manual import list to maintain — just create your file in `tools/` and it’s picked up at startup. ## Async Handlers If your handler needs async code, mark it with `is_async=True`: `python async def weather_tool_async(location: str) -> str: async with aiohttp.ClientSession() as session: ... return json.dumps(result) registry.register( name="weather", toolset="weather", schema=WEATHER_SCHEMA, handler=lambda args, kw: weather_tool_async(args.get("location", "")), check_fn=check_weather_requirements, is_async=True, # registry calls _run_async() automatically )` The registry handles async bridging transparently — you never call `asyncio.run()` yourself. ## Handlers That Need task_id Tools that manage per-session state receive `task_id` via `kwargs`: `python def _handle_weather(args, kw): task_id = kw.get("task_id") return weather_tool(args.get("location", ""), task_id=task_id) registry.register( name="weather", ... handler=_handle_weather, )` ## Agent-Loop Intercepted Tools Some tools (`todo`, `memory`, `session_search`, `delegate_task`) need access to per-session agent state. These are intercepted by `run_agent.py` before reaching the registry. The registry still holds their schemas, but `dispatch()` returns a fallback error if the intercept is bypassed. ## Optional: Setup Wizard Integration If your tool requires an API key, add it to `hermes_cli/config.py`: `python OPTIONAL_ENV_VARS = { ... "WEATHER_API_KEY": { "description": "Weather API key for weather lookup", "prompt": "Weather API key", "url": "https://weatherapi.com/", "tools": ["weather"], "password": True, }, }` ## Checklist - [ ] Tool file created with handler, schema, check function, and registration - [ ] Added to appropriate toolset in `toolsets.py` - [ ] Confirmed this really should be a built-in/core tool and not a plugin - [ ] Handler returns JSON strings, errors returned as `{"error": "..."}` - [ ] Optional: API key added to `OPTIONAL_ENV_VARS` in `hermes_cli/config.py` - [ ] Optional: Added to `toolset_distributions.py` for batch processing - [ ] Tested with `hermes chat -q "Use the weather tool for London"` — # Adding Providers # Adding Providers Hermes can already talk to any OpenAI-compatible endpoint through the custom provider path. Do not add a built-in provider unless you want first-class UX for that service: - provider-specific auth or token refresh - a curated model catalog - setup / `hermes model` menu entries - provider aliases for `provider:model` syntax - a non-OpenAI API shape that needs an adapter If the provider is just “another OpenAI-compatible base URL and API key”, a named custom provider may be enough. ## The mental model A built-in provider has to line up across a few layers: 1. `hermes_cli/auth.py` decides how credentials are found. 2. `hermes_cli/runtime_provider.py` turns that into runtime data: - `provider` - `api_mode` - `base_url` - `api_key` - `source` 3. `run_agent.py` uses `api_mode` to decide how requests are built and sent. 4. `hermes_cli/models.py` and `hermes_cli/main.py` make the provider show up in the CLI. (`hermes_cli/setup.py` delegates to `main.py` automatically — no changes needed there.) 5. `agent/auxiliary_client.py` and `agent/model_metadata.py` keep side tasks and token budgeting working. The important abstraction is `api_mode`. - Most providers use `chat_completions`. - Codex uses `codex_responses`. - Anthropic uses `anthropic_messages`. - A new non-OpenAI protocol usually means adding a new adapter and a new `api_mode` branch. ## Choose the implementation path first ### Path A — OpenAI-compatible provider Use this when the provider accepts standard chat-completions style requests. Typical work: - add auth metadata - add model catalog / aliases - add runtime resolution - add CLI menu wiring - add aux-model defaults - add tests and user docs You usually do not need a new adapter or a new `api_mode`. ### Path B — Native provider Use this when the provider does not behave like OpenAI chat completions. Examples in-tree today: - `codex_responses` - `anthropic_messages` This path includes everything from Path A plus: - a provider adapter in `agent/` - `run_agent.py` branches for request building, dispatch, usage extraction, interrupt handling, and response normalization - adapter tests ## File checklist ### Required for every built-in provider 1. `hermes_cli/auth.py` 2. `hermes_cli/models.py` 3. `hermes_cli/runtime_provider.py` 4. `hermes_cli/main.py` 5. `agent/auxiliary_client.py` 6. `agent/model_metadata.py` 7. tests 8. user-facing docs under `website/docs/` :::tip `hermes_cli/setup.py` does not** need changes. The setup wizard delegates provider/model selection to `select_provider_and_model()` in `main.py` — any provider added there is automatically available in `hermes setup`. ::: ### Additional for native / non-OpenAI providers 10. `agent/<provider>_adapter.py` 11. `run_agent.py` 12. `pyproject.toml` if a provider SDK is required ## Fast path: Simple API-key providers If your provider is just an OpenAI-compatible endpoint that authenticates with a single API key, you do not need to touch `auth.py`, `runtime_provider.py`, `main.py`, or any of the other files in the full checklist below. All you need is: 1. A plugin directory under `plugins/model-providers/<your-provider>/` containing: - `init.py` — calls `register_provider(profile)` at module-level - `plugin.yaml` — manifest (name, kind: model-provider, version, description) 2. That’s it. Provider plugins auto-load the first time anything calls `get_provider_profile()` or `list_providers()` — bundled plugins (this repo) and user plugins at `$HERMES_HOME/plugins/model-providers/` both get picked up. When you add a plugin and it calls `register_provider()`, the following wire up automatically: 1. `PROVIDER_REGISTRY` entry in `auth.py` (credential resolution, env-var lookup) 2. `api_mode` set to `chat_completions` 3. `base_url` sourced from the config or the declared env var 4. `env_vars` checked in priority order for the API key 5. `fallback_models` list registered for the provider 6. `--provider` CLI flag accepts the provider id 7. `hermes model` menu includes the provider 8. `hermes setup` wizard delegates to `main.py` automatically 9. `provider:model` alias syntax works 10. Runtime resolver returns the correct `base_url` and `api_key` 11. `--provider <name>` CLI flag accepts the provider id 12. Fallback model activation can switch into the provider cleanly User plugins at `$HERMES_HOME/plugins/model-providers/<name>/` override bundled plugins of the same name (last-writer-wins in `register_provider()`) — so third parties can monkey-patch or replace any built-in profile without editing the repo. See `plugins/model-providers/nvidia/` or `plugins/model-providers/gmi/` as a template, and the full Model Provider Plugin guide for field reference, hook idioms, and end-to-end examples. ## Full path: OAuth and complex providers Use the full checklist below when your provider needs any of the following: - OAuth or token refresh (Nous Portal, Codex, Google Gemini, Qwen Portal, Copilot) - A non-OpenAI API shape that requires a new adapter (Anthropic Messages, Codex Responses) - Custom endpoint detection or multi-region probing (z.ai, Kimi) - A curated static model catalog or live `/models` fetch - Provider-specific `hermes model` menu entries with bespoke auth flows ## Step 1: Pick one canonical provider id Choose a single provider id and use it everywhere. Examples from the repo: - `openai-codex` - `kimi-coding` - `minimax-cn` That same id should appear in: - `PROVIDER_REGISTRY` in `hermes_cli/auth.py` - `_PROVIDER_LABELS` in `hermes_cli/models.py` - `_PROVIDER_ALIASES` in both `hermes_cli/auth.py` and `hermes_cli/models.py` - CLI `--provider` choices in `hermes_cli/main.py` - setup / model selection branches - auxiliary-model defaults - tests If the id differs between those files, the provider will feel half-wired: auth may work while `/model`, setup, or runtime resolution silently misses it. ## Step 2: Add auth metadata in `hermes_cli/auth.py` For API-key providers, add a `ProviderConfig` entry to `PROVIDER_REGISTRY` with: - `id` - `name` - `auth_type="api_key"` - `inference_base_url` - `api_key_env_vars` - optional `base_url_env_var` Also add aliases to `_PROVIDER_ALIASES`. Use the existing providers as templates: - simple API-key path: Z.AI, MiniMax - API-key path with endpoint detection: Kimi, Z.AI - native token resolution: Anthropic - OAuth / auth-store path: Nous, OpenAI Codex Questions to answer here: - What env vars should Hermes check, and in what priority order? - Does the provider need base-URL overrides? - Does it need endpoint probing or token refresh? - What should the auth error say when credentials are missing? If the provider needs something more than “look up an API key”, add a dedicated credential resolver instead of shoving logic into unrelated branches. ## Step 3: Add model catalog and aliases in `hermes_cli/models.py` Update the provider catalog so the provider works in menus and in `provider:model` syntax. Typical edits: - `_PROVIDER_MODELS` - `_PROVIDER_LABELS` - `_PROVIDER_ALIASES` - provider display order inside `list_available_providers()` - `provider_model_ids()` if the provider supports a live `/models` fetch If the provider exposes a live model list, prefer that first and keep `_PROVIDER_MODELS` as the static fallback. This file is also what makes inputs like these work: `text anthropic:claude-sonnet-4-6 kimi:model-name` If aliases are missing here, the provider may authenticate correctly but still fail in `/model` parsing. ## Step 4: Resolve runtime data in `hermes_cli/runtime_provider.py` `resolve_runtime_provider()` is the shared path used by CLI, gateway, cron, ACP, and helper clients. Add a branch that returns a dict with at least: `python { "provider": "your-provider", "api_mode": "chat_completions", # or your native mode "base_url": "https://...", "api_key": "...", "source": "env|portal|auth-store|explicit", "requested_provider": requested_provider, }` If the provider is OpenAI-compatible, `api_mode` should usually stay `chat_completions`. Be careful with API-key precedence. Hermes already contains logic to avoid leaking an OpenRouter key to unrelated endpoints. A new provider should be equally explicit about which key goes to which base URL. ## Step 5: Wire the CLI in `hermes_cli/main.py` A provider is not discoverable until it shows up in the interactive `hermes model` flow. Update these in `hermes_cli/main.py`: - `provider_labels` dict - `providers` list in `select_provider_and_model()` - provider dispatch (`if selected_provider == ...`) - `--provider` argument choices - login/logout choices if the provider supports those flows - a `_model_flow_<provider>()` function, or reuse `_model_flow_api_key_provider()` if it fits :::tip `hermes_cli/setup.py` does not need changes — it calls `select_provider_and_model()` from `main.py`, so your new provider appears in both `hermes model` and `hermes setup` automatically. ::: ## Step 6: Keep auxiliary calls working Two files matter here: ### `agent/auxiliary_client.py` Add a cheap / fast default aux model to `_API_KEY_PROVIDER_AUX_MODELS` if this is a direct API-key provider. Auxiliary tasks include things like: - vision summarization - web extraction summarization - context compression summaries - session-search summaries - memory flushes If the provider has no sensible aux default, side tasks may fall back badly or use an expensive main model unexpectedly. ### `agent/model_metadata.py` Add context lengths for the provider’s models so token budgeting, compression thresholds, and limits stay sane. ## Step 7: If the provider is native, add an adapter and `run_agent.py` support If the provider is not plain chat completions, isolate the provider-specific logic in `agent/<provider>_adapter.py`. Keep `run_agent.py` focused on orchestration. It should call adapter helpers, not hand-build provider payloads inline all over the file. A native provider usually needs work in these places: ### New adapter file Typical responsibilities: - build the SDK / HTTP client - resolve tokens - convert OpenAI-style conversation messages to the provider’s request format - convert tool schemas if needed - normalize provider responses back into what `run_agent.py` expects - extract usage and finish-reason data ### `run_agent.py` Search for `api_mode` and audit every switch point. At minimum, verify: - `init` chooses the new `api_mode` - client construction works for the provider - `_build_api_kwargs()` knows how to format requests - `_interruptible_api_call()` dispatches to the right client call - interrupt / client rebuild paths work - response validation accepts the provider’s shape - finish-reason extraction is correct - token-usage extraction is correct - fallback-model activation can switch into the new provider cleanly - summary-generation and memory-flush paths still work Also search `run_agent.py` for `self.client.`. Any code path that assumes the standard OpenAI client exists can break when a native provider uses a different client object or `self.client = None`. ### Prompt caching and provider-specific request fields Prompt caching and provider-specific knobs are easy to regress. Examples already in-tree: - Anthropic has a native prompt-caching path - OpenRouter gets provider-routing fields - not every provider should receive every request-side option When you add a native provider, double-check that Hermes is only sending fields that provider actually understands. ## Step 8: Tests At minimum, touch the tests that guard provider wiring. Common places: - `tests/hermes_cli/test_runtime_provider_resolution.py` - `tests/cli/test_cli_provider_resolution.py` - `tests/hermes_cli/test_model_switch_custom_providers.py` (and adjacent `tests/hermes_cli/test_model_switch_.py`) - `tests/hermes_cli/test_setup_model_provider.py` - `tests/run_agent/test_provider_parity.py` - `tests/run_agent/test_run_agent.py` - `tests/test_<provider>_adapter.py` for a native provider For docs-only examples, the exact file set may differ. The point is to cover: - auth resolution - CLI menu / provider selection - runtime provider resolution - agent execution path - provider:model parsing - any adapter-specific message conversion Run tests with xdist disabled: `bash source venv/bin/activate python -m pytest tests/hermes_cli/test_runtime_provider_resolution.py tests/cli/test_cli_provider_resolution.py tests/hermes_cli/test_setup_model_provider.py tests/run_agent/test_provider_parity.py -n0 -q` For deeper changes, run the full suite before pushing: `bash source venv/bin/activate python -m pytest tests/ -n0 -q` ## Step 9: Live verification After tests, run a real smoke test. `bash source venv/bin/activate python -m hermes_cli.main chat -q "Say hello" --provider your-provider --model your-model` Also test the interactive flows if you changed menus: `bash source venv/bin/activate python -m hermes_cli.main model python -m hermes_cli.main setup` For native providers, verify at least one tool call too, not just a plain text response. ## Step 10: Update user-facing docs If the provider is meant to ship as a first-class option, update the user docs too: - `website/docs/getting-started/quickstart.md` - `website/docs/user-guide/configuration.md` - `website/docs/reference/environment-variables.md` A developer can wire the provider perfectly and still leave users unable to discover the required env vars or setup flow. ## OpenAI-compatible provider checklist Use this if the provider is standard chat completions. - [ ] `ProviderConfig` added in `hermes_cli/auth.py` - [ ] aliases added in `hermes_cli/auth.py` and `hermes_cli/models.py` - [ ] model catalog added in `hermes_cli/models.py` - [ ] runtime branch added in `hermes_cli/runtime_provider.py` - [ ] CLI wiring added in `hermes_cli/main.py` (setup.py inherits automatically) - [ ] aux model added in `agent/auxiliary_client.py` - [ ] context lengths added in `agent/model_metadata.py` - [ ] runtime / CLI tests updated - [ ] user docs updated ## Native provider checklist Use this when the provider needs a new protocol path. - [ ] everything in the OpenAI-compatible checklist - [ ] adapter added in `agent/<provider>_adapter.py` - [ ] new `api_mode` supported in `run_agent.py` - [ ] interrupt / rebuild path works - [ ] usage and finish-reason extraction works - [ ] fallback path works - [ ] adapter tests added - [ ] live smoke test passes ## Common pitfalls ### 1. Adding the provider to auth but not to model parsing That makes credentials resolve correctly while `/model` and `provider:model` inputs fail. ### 2. Forgetting that `config["model"]` can be a string or a dict A lot of provider-selection code has to normalize both forms. ### 3. Assuming a built-in provider is required If the service is just OpenAI-compatible, a custom provider may already solve the user problem with less maintenance. ### 4. Forgetting auxiliary paths The main chat path can work while summarization, memory flushes, or vision helpers fail because aux routing was never updated. ### 5. Native-provider branches hiding in `run_agent.py` Search for `api_mode` and `self.client.`. Do not assume the obvious request path is the only one. ### 6. Sending OpenRouter-only knobs to other providers Fields like provider routing belong only on the providers that support them. ### 7. Updating `hermes model` but not `hermes setup` Both flows need to know about the provider. ## Good search targets while implementing If you are hunting for all the places a provider touches, search these symbols: - `PROVIDER_REGISTRY` - `_PROVIDER_ALIASES` - `_PROVIDER_MODELS` - `resolve_runtime_provider` - `_model_flow_` - `select_provider_and_model` - `api_mode` - `_API_KEY_PROVIDER_AUX_MODELS` - `self.client.` ## Related docs - Provider Runtime Resolution - Architecture - Contributing — # developer-guide/adding-platform-adapters # Adding a Platform Adapter This guide covers adding a new messaging platform to the Hermes gateway. A platform adapter connects Hermes to an external messaging service (Telegram, Discord, WeCom, etc.) so users can interact with the agent through that service. :::tip There are two ways to add a platform: - Plugin (recommended for community/third-party): Drop a plugin directory into `~/.hermes/plugins/` — zero core code changes needed. See Plugin Path below. - Built-in: Modify 20+ files across code, config, and docs. Use the Built-in Checklist below. ::: ## Architecture Overview `User ↔ Messaging Platform ↔ Platform Adapter ↔ Gateway Runner ↔ AIAgent` Every adapter extends `BasePlatformAdapter` from `gateway/platforms/base.py` and implements: - `connect()` — Establish connection (WebSocket, long-poll, HTTP server, etc.) (abstract)* - `disconnect()` — Clean shutdown (abstract) - `send()` — Send a text message to a chat (abstract) - `send_typing()` — Show typing indicator (optional override) - `get_chat_info()` — Return chat metadata (optional override) Inbound messages are received by the adapter and forwarded via `self.handle_message(event)`, which the base class routes to the gateway runner. ## Plugin Path (Recommended) The plugin system lets you add a platform adapter without modifying any core Hermes code. Your plugin is a directory with two files: `~/.hermes/plugins/my-platform/ plugin.yaml # Plugin metadata adapter.py # Adapter class + register() entry point` ### plugin.yaml Plugin metadata. The `requires_env` and `optional_env` blocks auto-populate `hermes config` UI entries (see Surfacing Env Vars below). `yaml name: my-platform label: My Platform kind: platform version: 1.0.0 description: My custom messaging platform adapter author: Your Name requires_env: - MY_PLATFORM_TOKEN # bare string works - name: MY_PLATFORM_CHANNEL # or rich dict for better UX description: "Channel to join" prompt: "Channel" password: false optional_env: - name: MY_PLATFORM_HOME_CHANNEL description: "Default channel for cron delivery" password: false` ### adapter.py python import os from gateway.platforms.base import ( BasePlatformAdapter, SendResult, MessageEvent, MessageType, ) from gateway.config import Platform, PlatformConfig class MyPlatformAdapter(BasePlatformAdapter): def init(self, config: PlatformConfig): super().init(config, Platform("my_platform")) extra = config.extra or {} self.token = os.getenv("MY_PLATFORM_TOKEN") or extra.get("token", "") async def connect(self) -> bool: # Connect to the platform API, start listeners self._mark_connected() return True async def disconnect(self) -> None: self._mark_disconnected() async def send(self, chat_id, content, reply_to=None, metadata=None): # Send message via platform API return SendResult(success=True, message_id="...") async def get_chat_info(self, chat_id): return {"name": chat_id, "type": "dm"} def check_requirements() -> bool: return bool(os.getenv("MY_PLATFORM_TOKEN")) def validate_config(config) -> bool: extra = getattr(config, "extra", {}) or {} return bool(os.getenv("MY_PLATFORM_TOKEN") or extra.get("token")) def _env_enablement() -> dict | None: token = os.getenv("MY_PLATFORM_TOKEN", "").strip() channel = os.getenv("MY_PLATFORM_CHANNEL", "").strip() if not (token and channel): return None seed = {"token": token, "channel": channel} home = os.getenv("MY_PLATFORM_HOME_CHANNEL") if home: seed["home_channel"] = {"chat_id": home, "name": "Home"} return seed def register(ctx): """Plugin entry point — called by the Hermes plugin system.""" ctx.register_platform( name="my_platform", label="My Platform", adapter_factory=lambda cfg: MyPlatformAdapter(cfg), check_fn=check_requirements, validate_config=validate_config, required_env=["MY_PLATFORM_TOKEN"], install_hint="pip install my-platform-sdk", # Env-driven auto-configuration — seeds PlatformConfig.extra from # env vars before adapter construction. See "Env-Driven Auto- # Configuration" section below. env_enablement_fn=_env_enablement, # Cron home-channel delivery support. Lets deliver=my_platform cron # jobs route without editing cron/scheduler.py. See "Cron Delivery" # section below. cron_deliver_env_var="MY_PLATFORM_HOME_CHANNEL", # Per-platform user authorization env vars allowed_users_env="MY_PLATFORM_ALLOWED_USERS", allow_all_env="MY_PLATFORM_ALLOW_ALL_USERS", # Message length limit for smart chunking (0 = no limit) max_message_length=4000, # LLM guidance injected into system prompt platform_hint=( "You are chatting via My Platform. " "It supports markdown formatting." ), # Display emoji="💬", ) # Optional: register platform-specific tools ctx.register_tool( name="my_platform_search", toolset="my_platform", schema={...}, handler=my_search_handler, ) ### Configuration Users configure the platform in `config.yaml`: `yaml gateway: platforms: my_platform: enabled: true extra: token: "..." channel: "#general"` Or via environment variables (which the adapter reads in `init`). ### What the Plugin System Handles Automatically When you call `ctx.register_platform()`, the following integration points are handled for you — no core code changes needed: | Integration point | How it works | |—|—| | Gateway adapter creation | Registry checked before built-in if/elif chain | | Config parsing | `Platform._missing_()` accepts any platform name | | Connected platform validation | Registry `validate_config()` called | | User authorization | `allowed_users_env` / `allow_all_env` checked | | Env-only auto-enable | `env_enablement_fn` seeds `PlatformConfig.extra` + `home_channel` | | YAML config bridge | `apply_yaml_config_fn` translates `config.yaml` keys into env vars / extras | | Cron delivery | `cron_deliver_env_var` makes `deliver=<name>` work | | `hermes config` UI entries | `requires_env` / `optional_env` in `plugin.yaml` auto-populate | | send_message tool | Routes through live gateway adapter | | Webhook cross-platform delivery | Registry checked for known platforms | | `/update` command access | `allow_update_command` flag | | Channel directory | Plugin platforms included in enumeration | | System prompt hints | `platform_hint` injected into LLM context | | Message chunking | `max_message_length` for smart splitting | | PII redaction | `pii_safe` flag | | `hermes status` | Shows plugin platforms with `(plugin)` tag | | `hermes gateway setup` | Plugin platforms appear in setup menu | | `hermes tools` / `hermes skills` | Plugin platforms in per-platform config | | Token lock (multi-profile) | Use `acquire_scoped_lock()` in your `connect()` | | Orphaned config warning | Descriptive log when plugin is missing | ## Env-Driven Auto-Configuration Most users set up a platform by dropping env vars into `~/.hermes/.env` rather than editing `config.yaml`. The `env_enablement_fn` hook lets your plugin pick those env vars up before the adapter is constructed, so `hermes gateway status`, `get_connected_platforms()`, and cron delivery see the correct state without instantiating the platform SDK. python def _env_enablement() -> dict | None: """Seed PlatformConfig.extra from env vars. Called by the platform registry during load_gateway_config(). Return None when the platform isn't minimally configured — the caller then skips auto-enabling. Return a dict to seed extras. The special 'home_channel' key is extracted and becomes a proper HomeChannel dataclass on the PlatformConfig; every other key is merged into PlatformConfig.extra. """ token = os.getenv("MY_PLATFORM_TOKEN", "").strip() channel = os.getenv("MY_PLATFORM_CHANNEL", "").strip() if not (token and channel): return None seed = {"token": token, "channel": channel} home = os.getenv("MY_PLATFORM_HOME_CHANNEL") if home: seed["home_channel"] = { "chat_id": home, "name": os.getenv("MY_PLATFORM_HOME_CHANNEL_NAME", "Home"), } return seed def register(ctx): ctx.register_platform( name="my_platform", label="My Platform", adapter_factory=lambda cfg: MyPlatformAdapter(cfg), check_fn=check_requirements, validate_config=validate_config, env_enablement_fn=_env_enablement, # ... other fields ) ## YAML→env Config Bridge Some users prefer setting `config.yaml` keys (`my_platform.require_mention`, `my_platform.allowed_channels`, etc.) over env vars. The `apply_yaml_config_fn` hook lets your plugin own this translation instead of forcing core `gateway/config.py` to know your platform’s YAML schema. python import os def _apply_yaml_config(yaml_cfg: dict, platform_cfg: dict) -> dict | None: """Translate config.yaml `my_platform:` keys into env vars / extras. yaml_cfg — the full top-level parsed config.yaml dict platform_cfg — the platform's own sub-dict (yaml_cfg.get("my_platform", {})) May mutate os.environ directly (use `not os.getenv(...)` guards to preserve env > YAML precedence) and/or return a dict to merge into PlatformConfig.extra. Return None or {} for no extras. """ if "require_mention" in platform_cfg and not os.getenv("MY_PLATFORM_REQUIRE_MENTION"): os.environ["MY_PLATFORM_REQUIRE_MENTION"] = str(platform_cfg["require_mention"]).lower() allowed = platform_cfg.get("allowed_channels") if allowed is not None and not os.getenv("MY_PLATFORM_ALLOWED_CHANNELS"): if isinstance(allowed, list): allowed = ",".join(str(v) for v in allowed) os.environ["MY_PLATFORM_ALLOWED_CHANNELS"] = str(allowed) return None # nothing extra to merge into PlatformConfig.extra def register(ctx): ctx.register_platform( name="my_platform", ..., apply_yaml_config_fn=_apply_yaml_config, ) The hook is invoked during `load_gateway_config()` after the generic shared-key loop (which handles common keys like `unauthorized_dm_behavior`, `notice_delivery`, `reply_prefix`, `require_mention`, etc.) and before `_apply_env_overrides()`, so your plugin only needs to bridge platform-specific keys. Exceptions raised by the hook are swallowed and logged at debug level — a misbehaving plugin never aborts gateway config load. ## Cron Delivery To let `deliver=my_platform` cron jobs route to a configured home channel, set `cron_deliver_env_var` to the env var name that holds the default chat/room/channel ID: `python ctx.register_platform( name="my_platform", ... cron_deliver_env_var="MY_PLATFORM_HOME_CHANNEL", )` The scheduler reads this env var when resolving the home target for `deliver=my_platform` jobs, and also treats the platform as a valid cron target in `_KNOWN_DELIVERY_PLATFORMS`-style checks. If your `env_enablement_fn` seeds a `home_channel` dict (see above), that takes precedence — `cron_deliver_env_var` is the fallback for cron jobs that run before env seeding. ### Out-of-process cron delivery `cron_deliver_env_var` makes your platform a recognized `deliver=` target. To make the actual send succeed when the cron job runs in a separate process from the gateway (i.e., `hermes cron run` separate from `hermes gateway`), register a `standalone_sender_fn`: `python async def _standalone_send( pconfig, chat_id, message, , thread_id=None, media_files=None, force_document=False, ): """Open an ephemeral connection / acquire a fresh token, send, and close.""" # ... open connection, send message, return result ... return {"success": True, "message_id": "..."} # or {"error": "..."} ctx.register_platform( name="my_platform", ... cron_deliver_env_var="MY_PLATFORM_HOME_CHANNEL", standalone_sender_fn=_standalone_send, )` Why this hook is necessary: built-in platforms (Telegram, Discord, Slack, etc.) ship direct REST helpers in `tools/send_message_tool.py` so cron can deliver without holding the gateway in the same process. Plugin platforms historically depended on `_gateway_runner_ref()`, which returns `None` outside the gateway process, so without `standalone_sender_fn` the cron-side send fails with `No live adapter for platform '<name>'`. The function receives the same `pconfig` and `chat_id` that the live adapter would, plus optional `thread_id`, `media_files`, and `force_document` keyword arguments. Returning `{"success": True, "message_id": ...}` is treated as a successful delivery; returning `{"error": "..."}` surfaces the message in cron’s `delivery_errors`. Exceptions raised inside the function are caught by the dispatcher and reported as `Plugin standalone send failed: <reason>`. Reference implementations live in `plugins/platforms/{irc,teams,google_chat}/adapter.py`. ## Surfacing Env Vars in `hermes config` `hermes_cli/config.py` scans `plugins/platforms//plugin.yaml` at import time and auto-populates `OPTIONAL_ENV_VARS` from `requires_env` and (optional) `optional_env` blocks. Use the rich-dict form to contribute proper descriptions, prompts, password flags, and URLs — the CLI setup UI picks them up for free. yaml # plugins/platforms/my_platform/plugin.yaml name: my_platform-platform label: My Platform kind: platform version: 1.0.0 description: > My Platform gateway adapter for Hermes Agent. author: Your Name requires_env: - name: MY_PLATFORM_TOKEN description: "Bot API token from the My Platform console" prompt: "My Platform bot token" url: "https://my-platform.example.com/bots" password: true - name: MY_PLATFORM_CHANNEL description: "Channel to join (e.g. #hermes)" prompt: "Channel" password: false optional_env: - name: MY_PLATFORM_HOME_CHANNEL description: "Default channel for cron delivery (defaults to MY_PLATFORM_CHANNEL)" prompt: "Home channel (or empty)" password: false - name: MY_PLATFORM_ALLOWED_USERS description: "Comma-separated user IDs allowed to talk to the bot" prompt: "Allowed users (comma-separated)" password: false Supported dict keys: `name` (required), `description`, `prompt`, `url`, `password` (bool; auto-detected from `_TOKEN` / `_SECRET` / `_KEY` / `_PASSWORD` / `_JSON` suffix when omitted), `category` (defaults to `"messaging"`). Bare-string entries (`- MY_PLATFORM_TOKEN`) still work — they get a generic description auto-derived from the plugin’s `label`. If a hardcoded entry for the same var already exists in `OPTIONAL_ENV_VARS`, it wins (back-compat); the plugin.yaml form acts as the fallback. ## Platform-Specific Slow-LLM UX Some platforms have constraints that change how a slow LLM response should be presented: - LINE issues a single-use reply token* that expires roughly 60 seconds after the inbound event. Replying with that token is free; falling back to the metered Push API is not. If the LLM hasn’t finished by the deadline, the choice is “burn paid Push quota” or “do something cleverer with the reply token before it expires.” - WhatsApp marks a session inactive after 24h, after which only template messages are accepted. - SMS has no concept of typing indicators or progressive updates — long responses just look like the bot is offline. These are real constraints the base `BasePlatformAdapter` can’t anticipate. The plugin surface intentionally leaves the room for an adapter to layer platform-specific UX on top of the base typing loop without expanding the kwarg list. ### Pattern: subclass `_keep_typing` to layer mid-flight UX `BasePlatformAdapter._keep_typing` is the typing-indicator heartbeat — it runs as a background task while the LLM is generating, and is cancelled when the response is delivered. To layer a platform-specific behavior at a threshold (e.g. send a “still thinking” bubble at 45s), override `_keep_typing` in your adapter, schedule your own task alongside `super()._keep_typing()`, and tear it down in `finally`: python class LineAdapter(BasePlatformAdapter): async def _keep_typing(self, chat_id: str, *args, **kwargs) -> None: if self.slow_response_threshold <= 0: await super()._keep_typing(chat_id, *args, **kwargs) return async def _fire_at_threshold() -> None: try: await asyncio.sleep(self.slow_response_threshold) except asyncio.CancelledError: raise # Platform-specific work here — for LINE, send a Template # Buttons "Get answer" bubble using the cached reply token # so the user can fetch the cached response later via a # fresh (free) reply token from the postback callback. await self._send_slow_response_button(chat_id) side_task = asyncio.create_task(_fire_at_threshold()) try: await super()._keep_typing(chat_id, args, kwargs) finally: if not side_task.done(): side_task.cancel() try: await side_task except (asyncio.CancelledError, Exception): pass Key points: - Always `await super()._keep_typing(...)`. The typing heartbeat is independently useful — don’t replace it, layer on top of it. - Tear down the side task in `finally`. When the LLM finishes (or `/stop` cancels the run), the gateway cancels the typing task. Your side task must observe that cancellation too, otherwise it lingers and may fire after the response was already delivered. - Pair with `interrupt_session_activity` to resolve any orphan UX state when the user issues `/stop`. For LINE, this means transitioning the postback cache entry from `PENDING` to `ERROR` so the persistent “Get answer” button delivers a “Run was interrupted” message instead of looping. ### Pattern: subclass `send` to route through a cache instead of sending immediately If your slow-response UX caches the response for later retrieval (LINE’s postback flow), your `send` override needs to recognize three modes: 1. Pending postback active for this chat → cache the response under the request_id, don’t send anything visible. 2. System busy-ack (`⚡ Interrupting`, `⏳ Queued`, `⏩ Steered`) → bypass the cache and send visibly so the user sees the gateway’s response to their input. 3. Normal response → send via reply-token-or-push as usual. `python async def send(self, chat_id: str, content: str, kw) -> SendResult: if _is_system_bypass(content): return await self._send_text_chunks(chat_id, content, force_push=False) pending_rid = self._pending_buttons.get(chat_id) if pending_rid: self._cache.set_ready(pending_rid, content) return SendResult(success=True, message_id=pending_rid) return await self._send_text_chunks(chat_id, content, force_push=False)` `_SYSTEM_BYPASS_PREFIXES` are the gateway’s own busy-acknowledgment prefixes (`⚡`, `⏳`, `⏩`, `💾`). Always let those through visibly, regardless of cached UX state. ### When this pattern is appropriate Use the typing-loop override approach when: - The platform’s outbound API has a hard time-window constraint (single-use reply token, expiring sticky session, etc.) AND - A visible mid-flight bubble* is acceptable UX on that platform. Use the simpler `slow_response_threshold = 0` always-Push path when: - The platform doesn’t have a meaningful free vs. paid distinction, OR - The user community prefers “loading… loading… DONE” silence-then-response over an interactive intermediate bubble. LINE supports both: the threshold defaults to 45s for free postback fetch, and `LINE_SLOW_RESPONSE_THRESHOLD=0` reverts to “always Push fallback.” ### Reference Implementation See `plugins/platforms/line/adapter.py` for the full LINE postback implementation — a `RequestCache` state machine (`PENDING → READY → DELIVERED`, plus `ERROR` for `/stop`), a `_keep_typing` override that fires the Template Buttons bubble at threshold, a `send` override that routes through the cache, and an `interrupt_session_activity` override that resolves orphan PENDING entries. ### Reference Implementations (Plugin Path) See `plugins/platforms/irc/` in the repo for a complete working example — a full async IRC adapter with zero external dependencies. `plugins/platforms/teams/` covers Bot Framework / Adaptive Cards, `plugins/platforms/google_chat/` covers OAuth-based REST APIs, and `plugins/platforms/line/` covers webhook-driven Messaging APIs with platform-specific slow-LLM UX. — ## Step-by-Step Checklist (Built-in Path) :::note This checklist is for adding a platform directly to the Hermes core codebase — typically done by core contributors for officially supported platforms. Community/third-party platforms should use the Plugin Path above. ::: ### 1. Platform Enum Add your platform to the `Platform` enum in `gateway/config.py`: `python class Platform(str, Enum): # ... existing platforms ... NEWPLAT = "newplat"` ### 2. Adapter File Create `gateway/platforms/newplat.py`: python from gateway.config import Platform, PlatformConfig from gateway.platforms.base import ( BasePlatformAdapter, MessageEvent, MessageType, SendResult, ) def check_newplat_requirements() -> bool: """Return True if dependencies are available.""" return SOME_SDK_AVAILABLE class NewPlatAdapter(BasePlatformAdapter): def init(self, config: PlatformConfig): super().init(config, Platform.NEWPLAT) # Read config from config.extra dict extra = config.extra or {} self._api_key = extra.get("api_key") or os.getenv("NEWPLAT_API_KEY", "") async def connect(self) -> bool: # Set up connection, start polling/webhook self._mark_connected() return True async def disconnect(self) -> None: self._running = False self._mark_disconnected() async def send(self, chat_id, content, reply_to=None, metadata=None): # Send message via platform API return SendResult(success=True, message_id="...") async def get_chat_info(self, chat_id): return {"name": chat_id, "type": "dm"} For inbound messages, build a `MessageEvent` and call `self.handle_message(event)`: `python source = self.build_source( chat_id=chat_id, chat_name=name, chat_type="dm", # or "group" user_id=user_id, user_name=user_name, ) event = MessageEvent( text=content, message_type=MessageType.TEXT, source=source, message_id=msg_id, ) await self.handle_message(event)` ### 3. Gateway Config (`gateway/config.py`) Three touchpoints: 1. `get_connected_platforms()` — Add a check for your platform’s required credentials 2. `load_gateway_config()` — Add token env map entry: `Platform.NEWPLAT: "NEWPLAT_TOKEN"` 3. `_apply_env_overrides()` — Map all `NEWPLAT_` env vars to config ### 4. Gateway Runner (`gateway/run.py`) Five touchpoints: 1. `_create_adapter()` — Add an `elif platform == Platform.NEWPLAT:` branch 2. `_is_user_authorized()` allowed_users map — `Platform.NEWPLAT: "NEWPLAT_ALLOWED_USERS"` 3. `_is_user_authorized()` allow_all map — `Platform.NEWPLAT: "NEWPLAT_ALLOW_ALL_USERS"` 4. Early env check `_any_allowlist` tuple — Add `"NEWPLAT_ALLOWED_USERS"` 5. Early env check `_allow_all` tuple — Add `"NEWPLAT_ALLOW_ALL_USERS"` 6. `_UPDATE_ALLOWED_PLATFORMS` frozenset — Add `Platform.NEWPLAT` ### 5. Cross-Platform Delivery 1. `gateway/platforms/webhook.py` — Add `"newplat"` to the delivery type tuple 2. `cron/scheduler.py` — Add to `_KNOWN_DELIVERY_PLATFORMS` frozenset and `_deliver_result()` platform map ### 6. CLI Integration 1. `hermes_cli/config.py` — Add all `NEWPLAT_` vars to `_EXTRA_ENV_KEYS` 2. `hermes_cli/gateway.py` — Add entry to `_PLATFORMS` list with key, label, emoji, token_var, setup_instructions, and vars 3. `hermes_cli/platforms.py` — Add `PlatformInfo` entry with label and default_toolset (used by `skills_config` and `tools_config` TUIs) 4. `hermes_cli/setup.py` — Add `_setup_newplat()` function (can delegate to `gateway.py`) and add tuple to the messaging platforms list 5. `hermes_cli/status.py` — Add platform detection entry: `"NewPlat": ("NEWPLAT_TOKEN", "NEWPLAT_HOME_CHANNEL")` 6. `hermes_cli/dump.py` — Add `"newplat": "NEWPLAT_TOKEN"` to platform detection dict ### 7. Tools 1. `tools/send_message_tool.py` — Add `"newplat": Platform.NEWPLAT` to platform map 2. `tools/cronjob_tools.py` — Add `newplat` to the delivery target description string ### 8. Toolsets 1. `toolsets.py` — Add `"hermes-newplat"` toolset definition with `_HERMES_CORE_TOOLS` 2. `toolsets.py` — Add `"hermes-newplat"` to the `"hermes-gateway"` includes list ### 9. Optional: Platform Hints `agent/prompt_builder.py` — If your platform has specific rendering limitations (no markdown, message length limits, etc.), add an entry to the `_PLATFORM_HINTS` dict. This injects platform-specific guidance into the system prompt: `python _PLATFORM_HINTS = { # ... "newplat": ( "You are chatting via NewPlat. It supports markdown formatting " "but has a 4000-character message limit." ), }` Not all platforms need hints — only add one if the agent’s behavior should differ. ### 10. Tests Create `tests/gateway/test_newplat.py` covering: - Adapter construction from config - Message event building - Send method (mock the external API) - Platform-specific features (encryption, routing, etc.) ### 11. Documentation | File | What to add | |——|———––| | `website/docs/user-guide/messaging/newplat.md` | Full platform setup page | | `website/docs/user-guide/messaging/index.md` | Platform comparison table, architecture diagram, toolsets table, security section, next-steps link | | `website/docs/reference/environment-variables.md` | All NEWPLAT_ env vars | | `website/docs/reference/toolsets-reference.md` | hermes-newplat toolset | | `website/docs/integrations/index.md` | Platform link | | `website/sidebars.ts` | Sidebar entry for the docs page | | `website/docs/developer-guide/architecture.md` | Adapter count + listing | | `website/docs/developer-guide/gateway-internals.md` | Adapter file listing | ## Parity Audit Before marking a new platform PR as complete, run a parity audit against an established platform: `bash # Find every .py file mentioning the reference platform search_files "bluebubbles" output_mode="files_only" file_glob=".py" # Find every .py file mentioning the new platform search_files "newplat" output_mode="files_only" file_glob=".py" # Any file in the first set but not the second is a potential gap` Repeat for `.md` and `.ts` files. Investigate each gap — is it a platform enumeration (needs updating) or a platform-specific reference (skip)? ## Common Patterns ### Long-Poll Adapters If your adapter uses long-polling (like Telegram or Weixin), use a polling loop task: `python async def connect(self): self._poll_task = asyncio.create_task(self._poll_loop()) self._mark_connected() async def _poll_loop(self): while self._running: messages = await self._fetch_updates() for msg in messages: await self.handle_message(self._build_event(msg))` ### Callback/Webhook Adapters If the platform pushes messages to your endpoint (like WeCom Callback), run an HTTP server: `python async def connect(self): self._app = web.Application() self._app.router.add_post("/callback", self._handle_callback) # ... start aiohttp server self._mark_connected() async def _handle_callback(self, request): event = self._build_event(await request.text()) await self._message_queue.put(event) return web.Response(text="success") # Acknowledge immediately` For platforms with tight response deadlines (e.g., WeCom’s 5-second limit), always acknowledge immediately and deliver the agent’s reply proactively via API later. Agent sessions run 3–30 minutes — inline replies within a callback response window are not feasible. ### Token Locks If the adapter holds a persistent connection with a unique credential, add a scoped lock to prevent two profiles from using the same credential: `python from gateway.status import acquire_scoped_lock, release_scoped_lock async def connect(self): if not acquire_scoped_lock("newplat", self._token): logger.error("Token already in use by another profile") return False # ... connect async def disconnect(self): release_scoped_lock("newplat", self._token)` ## Reference Implementations | Adapter | Pattern | Complexity | Good reference for | |———|———|————|—————––| | `bluebubbles.py` | REST + webhook | Medium | Simple REST API integration | | `weixin.py` | Long-poll + CDN | High | Media handling, encryption | | `wecom_callback.py` | Callback/webhook | Medium | HTTP server, AES crypto, multi-app | | `telegram.py` | Long-poll + Bot API | High | Full-featured adapter with groups, threads | — # Creating Skills # Creating Skills Skills are the preferred way to add new capabilities to Hermes Agent. They’re easier to create than tools, require no code changes to the agent, and can be shared with the community. ## Should it be a Skill or a Tool? Make it a Skill when: - The capability can be expressed as instructions + shell commands + existing tools - It wraps an external CLI or API that the agent can call via `terminal` or `web_extract` - It doesn’t need custom Python integration or API key management baked into the agent - Examples: arXiv search, git workflows, Docker management, PDF processing, email via CLI tools Make it a Tool when: - It requires end-to-end integration with API keys, auth flows, or multi-component configuration - It needs custom processing logic that must execute precisely every time - It handles binary data, streaming, or real-time events - Examples: browser automation, TTS, vision analysis ## Skill Directory Structure Bundled skills live in `skills/` organized by category. Official optional skills use the same structure in `optional-skills/`: `text skills/ ├── research/ │ └── arxiv/ │ ├── SKILL.md # Required: main instructions │ └── scripts/ # Optional: helper scripts │ └── search_arxiv.py ├── productivity/ │ └── ocr-and-documents/ │ ├── SKILL.md │ ├── scripts/ │ └── references/ └── ...` ## SKILL.md Format markdown --- name: my-skill description: Brief description (shown in skill search results) version: 1.0.0 author: Your Name license: MIT platforms: [macos, linux] # Optional — restrict to specific OS platforms # Valid: macos, linux, windows # Omit to load on all platforms (default) metadata: hermes: tags: [Category, Subcategory, Keywords] related_skills: [other-skill-name] requires_toolsets: [web] # Optional — only show when these toolsets are active requires_tools: [web_search] # Optional — only show when these tools are available fallback_for_toolsets: [browser] # Optional — hide when these toolsets are active fallback_for_tools: [browser_navigate] # Optional — hide when these tools exist config: # Optional — config.yaml settings the skill needs - key: my.setting description: "What this setting controls" default: "sensible-default" prompt: "Display prompt for setup" required_environment_variables: # Optional — env vars the skill needs - name: MY_API_KEY prompt: "Enter your API key" help: "Get one at https://example.com" required_for: "API access" --- # Skill Title Brief intro. ## When to Use Trigger conditions — when should the agent load this skill? ## Quick Reference Table of common commands or API calls. ## Procedure Step-by-step instructions the agent follows. ## Pitfalls Known failure modes and how to handle them. ## Verification How the agent confirms it worked. ### Platform-Specific Skills Skills can restrict themselves to specific operating systems using the `platforms` field: `yaml platforms: [macos] # macOS only (e.g., iMessage, Apple Reminders) platforms: [macos, linux] # macOS and Linux platforms: [windows] # Windows only` When set, the skill is automatically hidden from the system prompt, `skills_list()`, and slash commands on incompatible platforms. If omitted or empty, the skill loads on all platforms (backward compatible). ### Conditional Skill Activation Skills can declare dependencies on specific tools or toolsets. This controls whether the skill appears in the system prompt for a given session. `yaml metadata: hermes: requires_toolsets: [web] # Hide if the web toolset is NOT active requires_tools: [web_search] # Hide if web_search tool is NOT available fallback_for_toolsets: [browser] # Hide if the browser toolset IS active fallback_for_tools: [browser_navigate] # Hide if browser_navigate IS available` | Field | Behavior | |—––|–––––| | `requires_toolsets` | Skill is hidden when ANY listed toolset is not available | | `requires_tools` | Skill is hidden when ANY listed tool is not available | | `fallback_for_toolsets` | Skill is hidden when ANY listed toolset is available | | `fallback_for_tools` | Skill is hidden when ANY listed tool is available | **Use case for `fallback_for_`: Create a skill that serves as a workaround when a primary tool isn’t available. For example, a `duckduckgo-search` skill with `fallback_for_tools: [web_search]` only shows when the web search tool (which requires an API key) is not configured. Use case for `requires_`: Create a skill that only makes sense when certain tools are present. For example, a web scraping workflow skill with `requires_toolsets: [web]` won’t clutter the prompt when web tools are disabled. ### Environment Variable Requirements Skills can declare environment variables they need. When a skill is loaded via `skill_view`, its required vars are automatically registered for passthrough into sandboxed execution environments (terminal, execute_code). `yaml required_environment_variables: - name: TENOR_API_KEY prompt: "Tenor API key" # Shown when prompting user help: "Get your key at https://tenor.com" # Help text or URL required_for: "GIF search functionality" # What needs this var` Each entry supports: - `name` (required) — the environment variable name - `prompt` (optional) — prompt text when asking the user for the value - `help` (optional) — help text or URL for obtaining the value - `required_for` (optional) — describes which feature needs this variable Users can also manually configure passthrough variables in `config.yaml`: `yaml terminal: env_passthrough: - MY_CUSTOM_VAR - ANOTHER_VAR` See `skills/apple/` for examples of macOS-only skills. ## Secure Setup on Load Use `required_environment_variables` when a skill needs an API key or token. Missing values do not hide the skill from discovery. Instead, Hermes prompts for them securely when the skill is loaded in the local CLI. `yaml required_environment_variables: - name: TENOR_API_KEY prompt: Tenor API key help: Get a key from https://developers.google.com/tenor required_for: full functionality` The user can skip setup and keep loading the skill. Hermes never exposes the raw secret value to the model. Gateway and messaging sessions show local setup guidance instead of collecting secrets in-band. :::tip Sandbox Passthrough When your skill is loaded, any declared `required_environment_variables` that are set are automatically passed through to `execute_code` and `terminal` sandboxes — including remote backends like Docker and Modal. Your skill’s scripts can access `$TENOR_API_KEY` (or `os.environ["TENOR_API_KEY"]` in Python) without the user needing to configure anything extra. See Environment Variable Passthrough for details. ::: Legacy `prerequisites.env_vars` remains supported as a backward-compatible alias. ### Config Settings (config.yaml) Skills can declare non-secret settings that are stored in `config.yaml` under the `skills.config` namespace. Unlike environment variables (which are secrets stored in `.env`), config settings are for paths, preferences, and other non-sensitive values. `yaml metadata: hermes: config: - key: myplugin.path description: Path to the plugin data directory default: "~/myplugin-data" prompt: Plugin data directory path - key: myplugin.domain description: Domain the plugin operates on default: "" prompt: Plugin domain (e.g., AI/ML research)` Each entry supports: - `key` (required) — dotpath for the setting (e.g., `myplugin.path`) - `description` (required) — explains what the setting controls - `default` (optional) — default value if the user doesn’t configure it - `prompt` (optional) — prompt text shown during `hermes config migrate`; falls back to `description` How it works: 1. Storage: Values are written to `config.yaml` under `skills.config.<key>`: `yaml skills: config: myplugin: path: ~/my-data` 2. Discovery: `hermes config migrate` scans all enabled skills, finds unconfigured settings, and prompts the user. Settings also appear in `hermes config show` under “Skill Settings.” 3. Runtime injection: When a skill loads, its config values are resolved and appended to the skill message: `[Skill config (from ~/.hermes/config.yaml): myplugin.path = /home/user/my-data ]` The agent sees the configured values without needing to read `config.yaml` itself. 4. Manual setup: Users can also set values directly: `bash hermes config set skills.config.myplugin.path ~/my-data` :::tip When to use which Use `required_environment_variables` for API keys, tokens, and other secrets (stored in `~/.hermes/.env`, never shown to the model). Use `config` for paths, preferences, and non-sensitive settings (stored in `config.yaml`, visible in config show). ::: ### Credential File Requirements (OAuth tokens, etc.) Skills that use OAuth or file-based credentials can declare files that need to be mounted into remote sandboxes. This is for credentials stored as files (not env vars) — typically OAuth token files produced by a setup script. `yaml required_credential_files: - path: google_token.json description: Google OAuth2 token (created by setup script) - path: google_client_secret.json description: Google OAuth2 client credentials` Each entry supports: - `path` (required) — file path relative to `~/.hermes/` - `description` (optional) — explains what the file is and how it’s created When loaded, Hermes checks if these files exist. Missing files trigger `setup_needed`. Existing files are automatically: - Mounted into Docker containers as read-only bind mounts - Synced into Modal sandboxes (at creation + before each command, so mid-session OAuth works) - Available on local backend without any special handling :::tip When to use which Use `required_environment_variables` for simple API keys and tokens (strings stored in `~/.hermes/.env`). Use `required_credential_files` for OAuth token files, client secrets, service account JSON, certificates, or any credential that’s a file on disk. ::: See the `skills/productivity/google-workspace/SKILL.md` for a complete example using both. ## Skill Guidelines ### No External Dependencies Prefer stdlib Python, curl, and existing Hermes tools (`web_extract`, `terminal`, `read_file`). If a dependency is needed, document installation steps in the skill. ### Progressive Disclosure Put the most common workflow first. Edge cases and advanced usage go at the bottom. This keeps token usage low for common tasks. ### Include Helper Scripts For XML/JSON parsing or complex logic, include helper scripts in `scripts/` — don’t expect the LLM to write parsers inline every time. ### Deliver media as documents (`[[as_document]]`) If your skill produces a high-resolution screenshot, chart, or any image where lossy preview compression would hurt — emit the literal directive `[[as_document]]` somewhere in the response (commonly the last line). The gateway strips the directive and delivers every extracted media path in that response as a downloadable file attachment instead of an inline image bubble. See Skill output and media delivery for the full semantics. #### Referencing bundled scripts from SKILL.md When a skill is loaded, the activation message exposes the absolute skill directory as `[Skill directory: /abs/path]` and also substitutes two template tokens anywhere in the SKILL.md body: | Token | Replaced with | |—|—| | `${HERMES_SKILL_DIR}` | Absolute path to the skill’s directory | | `${HERMES_SESSION_ID}` | The active session id (left in place if there is no session) | So a SKILL.md can tell the agent to run a bundled script directly with: `markdown To analyse the input, run: node ${HERMES_SKILL_DIR}/scripts/analyse.js <input>` The agent sees the substituted absolute path and invokes the `terminal` tool with a ready-to-run command — no path math, no extra `skill_view` round-trip. Disable substitution globally with `skills.template_vars: false` in `config.yaml`. #### Inline shell snippets (opt-in) Skills can also embed inline shell snippets written as !`cmd` in the SKILL.md body. When enabled, each snippet’s stdout is inlined into the message before the agent reads it, so skills can inject dynamic context: markdown Current date: !`date -u +%Y-%m-%d` Git branch: !`git -C ${HERMES_SKILL_DIR} rev-parse --abbrev-ref HEAD` This is off by default — any snippet in a SKILL.md runs on the host without approval, so only enable it for skill sources you trust: `yaml # config.yaml skills: inline_shell: true inline_shell_timeout: 10 # seconds per snippet` Snippets run with the skill directory as their working directory, and output is capped at 4000 characters. Failures (timeouts, non-zero exits) show up as a short `[inline-shell error: ...]` marker instead of breaking the whole skill. ### Test It Run the skill and verify the agent follows the instructions correctly: `bash hermes chat --toolsets skills -q "Use the X skill to do Y"` ## Where Should the Skill Live? Bundled skills (in `skills/`) ship with every Hermes install. They should be broadly useful to most users: - Document handling, web research, common dev workflows, system administration - Used regularly by a wide range of people If your skill is official and useful but not universally needed (e.g., a paid service integration, a heavyweight dependency), put it in `optional-skills/` — it ships with the repo, is discoverable via `hermes skills browse` (labeled “official”), and installs with built-in trust. If your skill is specialized, community-contributed, or niche, it’s better suited for a Skills Hub** — upload it to a registry and share it via `hermes skills install`. ## Publishing Skills ### To the Skills Hub `bash hermes skills publish skills/my-skill --to github --repo owner/repo` ### To a Custom Repository Add your repo as a tap: `bash hermes skills tap add owner/repo` Users can then search and install from your repository. ## Security Scanning All hub-installed skills go through a security scanner that checks for: - Data exfiltration patterns - Prompt injection attempts - Destructive commands - Shell injection Trust levels: - `builtin` — ships with Hermes (always trusted) - `official` — from `optional-skills/` in the repo (built-in trust, no third-party warning) - `trusted` — from openai/skills, anthropics/skills, huggingface/skills - `community` — non-dangerous findings can be overridden with `--force`; `dangerous` verdicts remain blocked Hermes can now consume third-party skills from multiple external discovery models: - direct GitHub identifiers (for example `openai/skills/k8s`) - `skills.sh` identifiers (for example `skills-sh/vercel-labs/json-render/json-render-react`) - well-known endpoints served from `/.well-known/skills/index.json` If you want your skills to be discoverable without a GitHub-specific installer, consider serving them from a well-known endpoint in addition to publishing them in a repo or marketplace. — # Extending the CLI # Extending the CLI Hermes exposes protected extension hooks on `HermesCLI` so wrapper CLIs can add widgets, keybindings, and layout customizations without overriding the 1000+ line `run()` method. This keeps your extension decoupled from internal changes. ## Extension points There are five extension seams available: | Hook | Purpose | Override when… | |——|———|——————| | `_get_extra_tui_widgets()` | Inject widgets into the layout | You need a persistent UI element (panel, status line, mini-player) | | `_register_extra_tui_keybindings(kb, *, input_area)` | Add keyboard shortcuts | You need hotkeys (toggle panels, transport controls, modal shortcuts) | | `_build_tui_layout_children(widgets)` | Full control over widget ordering | You need to reorder or wrap existing widgets (rare) | | `process_command()` | Add custom slash commands | You need `/mycommand` handling (pre-existing hook) | | `_build_tui_style_dict()` | Custom prompt_toolkit styles | You need custom colors or styling (pre-existing hook) | The first three are new protected hooks. The last two already existed. ## Quick start: a wrapper CLI python #!/usr/bin/env python3 """my_cli.py — Example wrapper CLI that extends Hermes.""" from cli import HermesCLI from prompt_toolkit.layout import FormattedTextControl, Window from prompt_toolkit.filters import Condition class MyCLI(HermesCLI): def init(self, kwargs): super().init(**kwargs) self._panel_visible = False def _get_extra_tui_widgets(self): """Add a toggleable info panel above the status bar.""" cli_ref = self return [ Window( FormattedTextControl(lambda: "📊 My custom panel content"), height=1, filter=Condition(lambda: cli_ref._panel_visible), ), ] def _register_extra_tui_keybindings(self, kb, , input_area): """F2 toggles the custom panel.""" cli_ref = self @kb.add("f2") def _toggle_panel(event): cli_ref._panel_visible = not cli_ref._panel_visible def process_command(self, cmd: str) -> bool: """Add a /panel slash command.""" if cmd.strip().lower() == "/panel": self._panel_visible = not self._panel_visible state = "visible" if self._panel_visible else "hidden" print(f"Panel is now {state}") return True return super().process_command(cmd) if name == "main": cli = MyCLI() cli.run() Run it: `bash cd ~/.hermes/hermes-agent source .venv/bin/activate python my_cli.py` ## Hook reference ### `_get_extra_tui_widgets()` Returns a list of prompt_toolkit widgets to insert into the TUI layout. Widgets appear between the spacer and the status bar — above the input area but below the main output. `python def _get_extra_tui_widgets(self) -> list: return [] # default: no extra widgets` Each widget should be a prompt_toolkit container (e.g., `Window`, `ConditionalContainer`, `HSplit`). Use `ConditionalContainer` or `filter=Condition(...)` to make widgets toggleable. `python from prompt_toolkit.layout import ConditionalContainer, Window, FormattedTextControl from prompt_toolkit.filters import Condition def _get_extra_tui_widgets(self): return [ ConditionalContainer( Window(FormattedTextControl("Status: connected"), height=1), filter=Condition(lambda: self._show_status), ), ]` ### `_register_extra_tui_keybindings(kb, , input_area)` Called after Hermes registers its own keybindings and before the layout is built. Add your keybindings to `kb`. `python def _register_extra_tui_keybindings(self, kb, , input_area): pass # default: no extra keybindings` Parameters: - `kb` — The `KeyBindings` instance for the prompt_toolkit application - `input_area` — The main `TextArea` widget, if you need to read or manipulate user input `python def _register_extra_tui_keybindings(self, kb, , input_area): cli_ref = self @kb.add("f3") def _clear_input(event): input_area.text = "" @kb.add("f4") def _insert_template(event): input_area.text = "/search "` Avoid conflicts with built-in keybindings: `Enter` (submit), `Escape Enter` (newline), `Ctrl-C` (interrupt), `Ctrl-D` (exit), `Tab` (auto-suggest accept). Function keys F2+ and Ctrl-combinations are generally safe. ### `_build_tui_layout_children(**widgets)` Override this only when you need full control over widget ordering. Most extensions should use `_get_extra_tui_widgets()` instead. `python def _build_tui_layout_children(self, , sudo_widget, secret_widget, approval_widget, clarify_widget, model_picker_widget=None, spinner_widget=None, spacer, status_bar, input_rule_top, image_bar, input_area, input_rule_bot, voice_status_bar, completions_menu) -> list:` The default implementation returns (any `None` widgets are filtered out): python [ Window(height=0), # anchor sudo_widget, # sudo password prompt (conditional) secret_widget, # secret input prompt (conditional) approval_widget, # dangerous command approval (conditional) clarify_widget, # clarify question UI (conditional) model_picker_widget, # model picker overlay (conditional) spinner_widget, # thinking spinner (conditional) spacer, # fills remaining vertical space self._get_extra_tui_widgets(), # YOUR WIDGETS GO HERE status_bar, # model/token/context status line input_rule_top, # ─── border above input image_bar, # attached images indicator input_area, # user text input input_rule_bot, # ─── border below input voice_status_bar, # voice mode status (conditional) completions_menu, # autocomplete dropdown ] ## Layout diagram The default layout from top to bottom: 1. Output area — scrolling conversation history 2. Spacer 3. Extra widgets — from `_get_extra_tui_widgets()` 4. Status bar — model, context %, elapsed time 5. Image bar — attached image count 6. Input area — user prompt 7. Voice status — recording indicator 8. Completions menu — autocomplete suggestions ## Tips - Invalidate the display after state changes: call `self._invalidate()` to trigger a prompt_toolkit redraw. - Access agent state: `self.agent`, `self.model`, `self.conversation_history` are all available. - Custom styles: Override `_build_tui_style_dict()` and add entries for your custom style classes. - Slash commands: Override `process_command()`, handle your commands, and call `super().process_command(cmd)` for everything else. - Don’t override `run()` unless absolutely necessary — the extension hooks exist specifically to avoid that coupling. — # CLI Commands Reference # CLI Commands Reference This page covers the terminal commands you run from your shell. For in-chat slash commands, see Slash Commands Reference. ## Global entrypoint `bash hermes [global-options] <command> [subcommand/options]` ### Global options | Option | Description | |––––|———––| | `--version`, `-V` | Show version and exit. | | `--profile <name>`, `-p <name>` | Select which Hermes profile to use for this invocation. Overrides the sticky default set by `hermes profile use`. | | `--resume <session>`, `-r <session>` | Resume a previous session by ID or title. | | `--continue [name]`, `-c [name]` | Resume the most recent session, or the most recent session matching a title. | | `--worktree`, `-w` | Start in an isolated git worktree for parallel-agent workflows. | | `--yolo` | Bypass dangerous-command approval prompts. | | `--pass-session-id` | Include the session ID in the agent’s system prompt. | | `--ignore-user-config` | Ignore `~/.hermes/config.yaml` and fall back to built-in defaults. Credentials in `.env` are still loaded. | | `--ignore-rules` | Skip auto-injection of `AGENTS.md`, `SOUL.md`, `.cursorrules`, memory, and preloaded skills. | | `--tui` | Launch the TUI instead of the classic CLI. Equivalent to `HERMES_TUI=1`. Always wins over `display.interface`. | | `--cli` | Force the classic prompt_toolkit REPL. Use this to override `display.interface: tui` for a single invocation. | | `--dev` | With `--tui`: run the TypeScript sources directly via `tsx` instead of the prebuilt bundle (for TUI contributors). | ## Top-level commands | Command | Purpose | |———|———| | `hermes chat` | Interactive or one-shot chat with the agent. | | `hermes model` | Interactively choose the default provider and model. | | `hermes fallback` | Manage fallback providers tried when the primary model errors. | | `hermes gateway` | Run or manage the messaging gateway service. | | `hermes proxy` | Local OpenAI-compatible proxy that attaches OAuth provider credentials. See Subscription Proxy. | | `hermes lsp` | Manage Language Server Protocol integration (semantic diagnostics for write_file/patch). | | `hermes setup` | Interactive setup wizard for all or part of the configuration. | | `hermes whatsapp` | Configure and pair the WhatsApp bridge. | | `hermes slack` | Slack helpers (currently: generate the app manifest with every command as a native slash). | | `hermes auth` | Manage credentials — add, list, remove, reset, set strategy. Handles OAuth flows for Codex/Nous/Anthropic. | | `hermes login` / `logout` | Deprecated — use `hermes auth` instead. | | `hermes send` | Send a one-shot message to a configured messaging platform (Telegram, Discord, Slack, Signal, SMS, …). Useful from shell scripts, cron jobs, CI hooks, and monitoring daemons — no agent loop, no LLM. | | `hermes secrets` | Manage external secret sources (currently Bitwarden Secrets Manager) for pulling API keys at process startup instead of from `~/.hermes/.env`. | | `hermes migrate` | Diagnose and (optionally) rewrite `config.yaml` to replace references to retired models or deprecated settings (e.g. `migrate xai`). | | `hermes status` | Show agent, auth, and platform status. | | `hermes cron` | Inspect and tick the cron scheduler. | | `hermes kanban` | Multi-profile collaboration board (tasks, links, dispatcher). | | `hermes webhook` | Manage dynamic webhook subscriptions for event-driven activation. | | `hermes hooks` | Inspect, approve, or remove shell-script hooks declared in `config.yaml`. | | `hermes doctor` | Diagnose config and dependency issues. | | `hermes security audit` | On-demand supply-chain audit (OSV.dev) for the venv, plugin requirements, and pinned MCP servers. | | `hermes dump` | Copy-pasteable setup summary for support/debugging. | | `hermes prompt-size` | Show a byte breakdown of the system prompt + tool schemas (skills index, memory, profile). Runs offline. | | `hermes debug` | Debug tools — upload logs and system info for support. | | `hermes backup` | Back up Hermes home directory to a zip file. | | `hermes checkpoints` | Inspect / prune / clear `~/.hermes/checkpoints/` (the shadow store used by `/rollback`). Run with no args for a status overview. | | `hermes import` | Restore a Hermes backup from a zip file. | | `hermes logs` | View, tail, and filter agent/gateway/error log files. | | `hermes config` | Show, edit, migrate, and query configuration files. | | `hermes pairing` | Approve or revoke messaging pairing codes. | | `hermes skills` | Browse, install, publish, audit, and configure skills. | | `hermes bundles` | Group several skills under a single `/<name>` slash command. See Skill Bundles. | | `hermes curator` | Background skill maintenance — status, run, pause, pin. See Curator. | | `hermes memory` | Configure external memory provider. Plugin-specific subcommands (e.g. `hermes honcho`) register automatically when their provider is active. | | `hermes acp` | Run Hermes as an ACP server for editor integration. | | `hermes mcp` | Manage MCP server configurations and run Hermes as an MCP server. | | `hermes plugins` | Manage Hermes Agent plugins (install, enable, disable, remove). | | `hermes portal` | Nous Portal status, subscription link, and Tool Gateway routing. See Tool Gateway. | | `hermes tools` | Configure enabled tools per platform. | | `hermes computer-use` | Install or check the cua-driver backend (macOS Computer Use). | | `hermes sessions` | Browse, export, prune, rename, and delete sessions. | | `hermes insights` | Show token/cost/activity analytics. | | `hermes claw` | OpenClaw migration helpers. | | `hermes dashboard` | Launch the web dashboard for managing config, API keys, and sessions. | | `hermes profile` | Manage profiles — multiple isolated Hermes instances. | | `hermes completion` | Print shell completion scripts (bash/zsh/fish). | | `hermes version` | Show version information. | | `hermes update` | Pull latest code and reinstall dependencies (git installs), or check PyPI and `pip install --upgrade` (pip installs). `--check` previews without installing; `--backup` takes a pre-pull `HERMES_HOME` snapshot. | | `hermes uninstall` | Remove Hermes from the system. | ## `hermes chat` `bash hermes chat [options]` Common options: | Option | Description | |––––|———––| | `-q`, `--query "..."` | One-shot, non-interactive prompt. | | `-m`, `--model <model>` | Override the model for this run. | | `-t`, `--toolsets <csv>` | Enable a comma-separated set of toolsets. | | `--provider <provider>` | Force a provider: `auto`, `openrouter`, `nous`, `openai-codex`, `copilot-acp`, `copilot`, `anthropic`, `gemini`, `google-gemini-cli`, `huggingface`, `novita` (aliases `novita-ai`, `novitaai`), `openai-api`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `minimax-oauth`, `kilocode`, `xiaomi`, `arcee`, `gmi`, `alibaba`, `alibaba-coding-plan` (alias `alibaba_coding`), `deepseek`, `nvidia`, `ollama-cloud`, `xai` (alias `grok`), `xai-oauth` (alias `grok-oauth`), `qwen-oauth`, `bedrock`, `opencode-zen`, `opencode-go`, `azure-foundry`, `lmstudio`, `stepfun`, `tencent-tokenhub` (alias `tencent`, `tokenhub`). | | `-s`, `--skills <name>` | Preload one or more skills for the session (can be repeated or comma-separated). | | `-v`, `--verbose` | Verbose output. | | `-Q`, `--quiet` | Programmatic mode: suppress banner/spinner/tool previews. | | `--image <path>` | Attach a local image to a single query. | | `--resume <session>` / `--continue [name]` | Resume a session directly from `chat`. | | `--worktree` | Create an isolated git worktree for this run. | | `--checkpoints` | Enable filesystem checkpoints before destructive file changes. | | `--yolo` | Skip approval prompts. | | `--pass-session-id` | Pass the session ID into the system prompt. | | `--ignore-user-config` | Ignore `~/.hermes/config.yaml` and use built-in defaults. Credentials in `.env` are still loaded. Useful for isolated CI runs, reproducible bug reports, and third-party integrations. | | `--ignore-rules` | Skip auto-injection of `AGENTS.md`, `SOUL.md`, `.cursorrules`, persistent memory, and preloaded skills. Combine with `--ignore-user-config` for a fully isolated run. | | `--source <tag>` | Session source tag for filtering (default: `cli`). Use `tool` for third-party integrations that should not appear in user session lists. | | `--max-turns <N>` | Maximum tool-calling iterations per conversation turn (default: 90, or `agent.max_turns` in config). | Examples: `bash hermes hermes chat -q "Summarize the latest PRs" hermes chat --provider openrouter --model anthropic/claude-sonnet-4.6 hermes chat --toolsets web,terminal,skills hermes chat --quiet -q "Return only JSON" hermes chat --worktree -q "Review this repo and open a PR" hermes chat --ignore-user-config --ignore-rules -q "Repro without my personal setup"` ### `hermes -z <prompt>` — scripted one-shot For programmatic callers (shell scripts, CI, cron, parent processes piping in a prompt), `hermes -z` is the purest one-shot entry point: single prompt in, final response text out, nothing else on stdout or stderr. No banner, no spinner, no tool previews, no `Session:` line — just the agent’s final reply as plain text. `bash hermes -z "What's the capital of France?" # → Paris. # Parent scripts can cleanly capture the response: answer=$(hermes -z "summarize this" < /path/to/file.txt)` Per-run overrides (no mutation to `~/.hermes/config.yaml`): | Flag | Equivalent env var | Purpose | |—|—|—| | `-m` / `--model <model>` | `HERMES_INFERENCE_MODEL` | Override the model for this run | | `--provider <provider>` | (none) | Override the provider for this run | `bash hermes -z "…" --provider openrouter --model openai/gpt-5.5 # or: HERMES_INFERENCE_MODEL=anthropic/claude-sonnet-4.6 hermes -z "…"` Same agent, same tools, same skills — just strips every interactive / cosmetic layer. If you need tool output in the transcript too, use `hermes chat -q` instead; `-z` is explicitly for “I only want the final answer”. ## `hermes model` Interactive provider + model selector. This is the command for adding new providers, setting up API keys, and running OAuth flows. Run it from your terminal — not from inside an active Hermes chat session. `bash hermes model` Use this when you want to: - add a new provider (OpenRouter, Anthropic, Copilot, DeepSeek, custom, etc.) - log into OAuth-backed providers (Anthropic, Copilot, Codex, Nous Portal) - enter or update API keys - pick from provider-specific model lists - configure a custom/self-hosted endpoint - save the new default into config :::warning hermes model vs /model — know the difference `hermes model` (run from your terminal, outside any Hermes session) is the full provider setup wizard. It can add new providers, run OAuth flows, prompt for API keys, and configure endpoints. `/model` (typed inside an active Hermes chat session) can only switch between providers and models you’ve already set up. It cannot add new providers, run OAuth, or prompt for API keys. If you need to add a new provider: Exit your Hermes session first (`Ctrl+C` or `/quit`), then run `hermes model` from your terminal prompt. ::: ### `/model` slash command (mid-session) Switch between already-configured models without leaving a session: `/model # Show current model and available options /model claude-sonnet-4 # Switch model (auto-detects provider) /model zai:glm-5 # Switch provider and model /model custom:qwen-2.5 # Use model on your custom endpoint /model custom # Auto-detect model from custom endpoint /model custom:local:qwen-2.5 # Use a named custom provider /model openrouter:anthropic/claude-sonnet-4 # Switch back to cloud` By default, `/model` changes apply to the current session only. Add `--global` to persist the change to `config.yaml`: `/model claude-sonnet-4 --global # Switch and save as new default` :::info What if I only see OpenRouter models? If you’ve only configured OpenRouter, `/model` will only show OpenRouter models. To add another provider (Anthropic, DeepSeek, Copilot, etc.), exit your session and run `hermes model` from the terminal. ::: Provider and base URL changes are persisted to `config.yaml` automatically. When switching away from a custom endpoint, the stale base URL is cleared to prevent it leaking into other providers. ## `hermes gateway` `bash hermes gateway <subcommand>` Subcommands: | Subcommand | Description | |————|———––| | `run` | Run the gateway in the foreground. Recommended for WSL, Docker, and Termux. | | `start` | Start the installed systemd/launchd background service. | | `stop` | Stop the service (or foreground process). | | `restart` | Restart the service. | | `status` | Show service status. | | `list` | List all profiles and whether each profile’s gateway is currently running (with PID where available). Handy when you run multiple profiles side-by-side and want a single overview. | | `install` | Install as a systemd (Linux) or launchd (macOS) background service. | | `uninstall` | Remove the installed service. | | `setup` | Interactive messaging-platform setup. | Options: | Option | Description | |––––|———––| | `--all` | On `start` / `restart` / `stop`: act on every profile’s gateway, not just the active `HERMES_HOME`. Useful if you run multiple profiles side-by-side and want to restart them all after `hermes update`. | | `--no-supervise` | On `run`: inside the s6-overlay Docker image, opt out of auto-supervision and use pre-s6 foreground semantics — gateway runs as the container’s main process with no auto-restart. No-op outside the s6 image. Equivalent to setting `HERMES_GATEWAY_NO_SUPERVISE=1`. | :::tip WSL users Use `hermes gateway run` instead of `hermes gateway start` — WSL’s systemd support is unreliable. Wrap it in tmux for persistence: `tmux new -s hermes 'hermes gateway run'`. See WSL FAQ for details. ::: ## `hermes lsp` `bash hermes lsp <subcommand>` Manage the Language Server Protocol integration. LSP runs real language servers (pyright, gopls, rust-analyzer, …) in the background and feeds their diagnostics into the post-write check used by `write_file` and `patch`. Gated on git workspace detection — LSP only runs when the cwd or edited file is inside a git worktree. Subcommands: | Subcommand | Description | |————|———––| | `status` | Show service state, configured servers, install status. | | `list` | Print the registry of supported servers. Pass `--installed-only` to skip missing ones. | | `install <id>` | Eagerly install one server’s binary. | | `install-all` | Install every server with a known auto-install recipe. | | `restart` | Tear down running clients so the next edit re-spawns. | | `which <id>` | Print the resolved binary path for one server. | See LSP — Semantic Diagnostics for the full guide, supported languages, and configuration knobs. ## `hermes setup` `bash hermes setup [model|tts|terminal|gateway|tools|agent] [--non-interactive] [--reset] [--quick] [--reconfigure] [--portal]` Easiest path: `hermes setup --portal` — OAuth into Nous Portal and opt into the Tool Gateway in one shot. First run: launches the first-time wizard. Returning user (already configured): drops straight into the full reconfigure wizard — every prompt shows your current value as its default, press Enter to keep or type a new value. No menu. Jump into one section instead of the full wizard: | Section | Description | |———|———––| | `model` | Provider and model setup. | | `terminal` | Terminal backend and sandbox setup. | | `gateway` | Messaging platform setup. | | `tools` | Enable/disable tools per platform. | | `agent` | Agent behavior settings. | Options: | Option | Description | |––––|———––| | `--quick` | On returning-user runs: only prompt for items that are missing or unset. Skip items you already have configured. | | `--non-interactive` | Use defaults / environment values without prompts. | | `--reset` | Reset configuration to defaults before setup. | | `--reconfigure` | Backwards-compat alias — bare `hermes setup` on an existing install now does this by default. | | `--portal` | One-shot Nous Portal setup: log in via OAuth, set Nous as the inference provider, and opt into the Tool Gateway. Skips the rest of the wizard. | ## `hermes portal` `bash hermes portal [status|open|tools]` Inspect Nous Portal auth, Tool Gateway routing, and reach the subscription page. Subcommand-less invocation runs `status`. | Subcommand | Description | |————|———––| | `status` (default) | Portal auth state + per-tool Tool Gateway routing summary. Also shown when no subcommand is given. | | `open` | Open `portal.nousresearch.com/manage-subscription` in your default browser. | | `tools` | List every Tool Gateway partner (Firecrawl, FAL, OpenAI TTS, Browser Use, Modal) and which are routed via Nous. | For configuration of the gateway itself, see Tool Gateway. For the one-shot setup path, see `hermes setup --portal` above. ## `hermes whatsapp` `bash hermes whatsapp` Runs the WhatsApp pairing/setup flow, including mode selection and QR-code pairing. ## `hermes slack` `bash hermes slack manifest # print manifest to stdout hermes slack manifest --write # write to ~/.hermes/slack-manifest.json hermes slack manifest --slashes-only # just the features.slash_commands array` Generates a Slack app manifest that registers every gateway command in `COMMAND_REGISTRY` (`/btw`, `/stop`, `/model`, …) as a first-class Slack slash command — matching Discord and Telegram parity. Paste the output into your Slack app config at https://api.slack.com/apps → your app → Features → App Manifest → Edit, then Save. Slack prompts for reinstall if scopes or slash commands changed. | Flag | Default | Purpose | |——|———|———| | `--write [PATH]` | stdout | Write to a file instead of stdout. Bare `--write` writes `$HERMES_HOME/slack-manifest.json`. | | `--name NAME` | `Hermes` | Bot display name in Slack. | | `--description DESC` | default blurb | Bot description shown in the Slack app directory. | | `--slashes-only` | off | Emit only `features.slash_commands` for merging into a manually-maintained manifest. | Run `hermes slack manifest --write` again after `hermes update` to pick up any new commands. ## `hermes send` `bash hermes send --to <target> "message text" hermes send --to <target> --file <path> echo "message" | hermes send --to <target> hermes send --list [platform]` Send a one-shot message to a configured messaging platform without spinning up an agent or gateway loop. Reuses the gateway’s already-configured credentials (`~/.hermes/.env` + `~/.hermes/config.yaml`) so ops scripts, cron jobs, CI hooks, and monitoring daemons can post status updates without reimplementing each platform’s REST client. For bot-token platforms (Telegram, Discord, Slack, Signal, SMS, WhatsApp-CloudAPI) no running gateway is required — `hermes send` talks directly to the platform’s REST endpoint. Plugin platforms that need a persistent adapter still require a live gateway. | Option | Description | |––––|———––| | `-t`, `--to <TARGET>` | Delivery target. Formats: `platform` (uses home channel), `platform:chat_id`, `platform:chat_id:thread_id`, or `platform:#channel-name`. Examples: `telegram`, `telegram:-1001234567890`, `discord:#ops`, `slack:C0123ABCD`, `signal:+15551234567`. | | `-f`, `--file <PATH>` | Read the message body from `PATH`. Pass `-` to force reading from stdin. | | `-s`, `--subject <LINE>` | Prepend a subject/header line before the message body. | | `-l`, `--list [platform]` | List configured targets across all platforms (or only the given platform). | | `-q`, `--quiet` | Suppress stdout on success — useful in scripts (rely on exit code only). | | `--json` | Emit raw JSON result instead of human-readable output. | If neither a positional `message` argument nor `--file` is provided, `hermes send` reads from stdin when it is not a TTY. Exit codes: `0` on success, `1` on delivery/backend failure, `2` on usage errors. Examples: `bash hermes send --to telegram "deploy finished" echo "RAM 92%" | hermes send --to telegram:-1001234567890 hermes send --to discord:#ops --file /tmp/report.md hermes send --to slack:#eng --subject "[CI]" --file build.log hermes send --list # all platforms hermes send --list telegram # filter by platform` ## `hermes secrets` `bash hermes secrets bitwarden <subcommand> hermes secrets bw <subcommand> # short alias` Pull API keys from an external secret manager at process startup instead of storing them in `~/.hermes/.env`. Currently supports Bitwarden Secrets Manager. See the full guide: Bitwarden integration. `bitwarden` (alias `bw`) subcommands: | Subcommand | Description | |————|———––| | `setup` | Interactive wizard: install the pinned `bws` binary, store an access token, and pick a project. Accepts `--project-id`, `--access-token`, and `--server-url` for non-interactive use. | | `status` | Show current config, binary path/version, and last fetch info. | | `sync` | Fetch secrets now and report what changed. Add `--apply` to actually export the secrets into the current shell’s environment (default is dry-run). | | `install` | Download and verify the pinned `bws` binary. `--force` re-downloads even if a managed copy already exists. | | `disable` | Turn off the Bitwarden integration. | ## `hermes migrate` `bash hermes migrate <type>` Diagnose and (optionally) rewrite the active `config.yaml` to replace references to retired models or deprecated settings. A timestamped backup of the original `config.yaml` is taken before any rewrite (skip with `--no-backup`). | Subcommand | Description | |————|———––| | `xai` | Scan `config.yaml` for references to xAI models scheduled for retirement on May 15, 2026 and (with `--apply`) rewrite them in-place to the official replacements per the xAI migration guide. Defaults to dry-run. | Common flags for migration subcommands: | Flag | Description | |——|———––| | `--apply` | Rewrite `config.yaml` in-place (default: dry-run, no writes). | | `--no-backup` | Skip the timestamped backup of `config.yaml` when applying. | > Not to be confused with `hermes claw migrate` (one-shot import of OpenClaw configuration into Hermes) — `hermes migrate` is the top-level config-rewrite command. ## `hermes proxy` `bash hermes proxy <subcommand>` Run a local OpenAI-compatible HTTP server that forwards requests to an OAuth-authenticated upstream provider (e.g. Nous Portal, xAI). External apps can point at the proxy with any bearer token; the proxy attaches your real OAuth credentials on the way out. See Subscription Proxy for the full guide. | Subcommand | Description | |————|———––| | `start` | Run the proxy in the foreground. Flags: `--provider <nous\|xai>` (default `nous`), `--host <addr>` (default `127.0.0.1`; use `0.0.0.0` to expose on LAN), `--port <int>` (default `8645`). | | `status` | Show which proxy upstreams are ready (credentials present, OAuth valid). | | `providers` | List available proxy upstream providers. | ## `hermes security` `bash hermes security <subcommand>` On-demand vulnerability scan against OSV.dev. Covers the Hermes venv (installed PyPI distributions), Python dependencies declared by plugins under `~/.hermes/plugins/`, and pinned `npx`/`uvx` MCP servers in `config.yaml`. Does NOT scan globally-installed packages or editor/browser extensions. | Subcommand | Description | |————|———––| | `audit` | Run a one-shot supply-chain audit. | `audit` flags: | Flag | Default | Description | |——|———|———––| | `--json` | off | Emit machine-readable JSON instead of human-readable text. | | `--fail-on <level>` | `critical` | Exit non-zero when any finding meets this severity (`low`, `moderate`, `high`, `critical`). | | `--skip-venv` | off | Skip scanning the Hermes Python venv. | | `--skip-plugins` | off | Skip scanning plugin requirements files. | | `--skip-mcp` | off | Skip scanning pinned MCP servers in `config.yaml`. | ## `hermes login` / `hermes logout` (Deprecated) :::caution `hermes login` has been removed. Use `hermes auth` to manage OAuth credentials, `hermes model` to select a provider, or `hermes setup` for full interactive setup. ::: ## `hermes auth` Manage credential pools for same-provider key rotation. See Credential Pools for full documentation. bash hermes auth # Interactive wizard hermes auth list # Show all pools hermes auth list openrouter # Show specific provider hermes auth add openrouter --api-key sk-or-v1-xxx # Add API key hermes auth add anthropic --type oauth # Add OAuth credential hermes auth remove openrouter 2 # Remove by index hermes auth reset openrouter # Clear cooldowns hermes auth status anthropic # Show auth status for a provider hermes auth logout anthropic # Log out and clear stored auth state hermes auth spotify # Authenticate Hermes with Spotify via PKCE Subcommands: `add`, `list`, `remove`, `reset`, `status`, `logout`, `spotify`. When called with no subcommand, launches the interactive management wizard. ## `hermes status` `bash hermes status [--all] [--deep]` | Option | Description | |––––|———––| | `--all` | Show all details in a shareable redacted format. | | `--deep` | Run deeper checks that may take longer. | ## `hermes cron` `bash hermes cron <list|create|edit|pause|resume|run|remove|status|tick>` | Subcommand | Description | |————|———––| | `list` | Show scheduled jobs. | | `create` / `add` | Create a scheduled job from a prompt, optionally attaching one or more skills via repeated `--skill`. | | `edit` | Update a job’s schedule, prompt, name, delivery, repeat count, or attached skills. Supports `--clear-skills`, `--add-skill`, and `--remove-skill`. | | `pause` | Pause a job without deleting it. | | `resume` | Resume a paused job and compute its next future run. | | `run` | Trigger a job on the next scheduler tick. | | `remove` | Delete a scheduled job. | | `status` | Check whether the cron scheduler is running. | | `tick` | Run due jobs once and exit. | ## `hermes kanban` `bash hermes kanban [--board <slug>] <action> [options]` Multi-profile, multi-project collaboration board. Each install can host many boards (one per project, repo, or domain); each board is a standalone queue with its own SQLite DB and dispatcher scope. New installs start with one board called `default`, whose DB is `~/.hermes/kanban.db` for back-compat; additional boards live at `~/.hermes/kanban/boards/<slug>/kanban.db`. The gateway-embedded dispatcher sweeps every board per tick. Global flags (apply to every action below): | Flag | Purpose | |——|———| | `--board <slug>` | Operate on a specific board. Defaults to the current board (set via `hermes kanban boards switch`, the `HERMES_KANBAN_BOARD` env var, or `default`). | This is the human / scripting surface. Agent workers spawned by the dispatcher drive the board through a dedicated `kanban_` toolset (`kanban_show`, `kanban_complete`, `kanban_block`, `kanban_create`, `kanban_link`, `kanban_comment`, `kanban_heartbeat`; orchestrator profiles also get `kanban_list` and `kanban_unblock`) instead of shelling to `hermes kanban`. Workers have `HERMES_KANBAN_BOARD` pinned in their env so they physically cannot see other boards. | Action | Purpose | |––––|———| | `init` | Create `kanban.db` if missing. Idempotent. | | `boards list` / `boards ls` | List all boards with task counts. `--json`, `--all` (include archived). | | `boards create <slug>` | Create a new board. Flags: `--name`, `--description`, `--icon`, `--color`, `--switch` (make active). Slug is kebab-case, auto-downcased. | | `boards switch <slug>` / `boards use` | Persist `<slug>` as the active board (writes `~/.hermes/kanban/current`). | | `boards show` / `boards current` | Print the currently-active board’s name, DB path, and task counts. | | `boards rename <slug> "<name>"` | Change a board’s display name. Slug is immutable. | | `boards rm <slug>` | Archive (default) or hard-delete a board. `--delete` skips the archive step. Archived boards move to `boards/_archived/<slug>-<ts>/`. Refused for `default`. | | `create "<title>"` | Create a new task on the active board. Flags: `--body`, `--assignee`, `--parent` (repeatable), `--workspace scratch\|worktree\|dir:<path>`, `--tenant`, `--priority`, `--triage`, `--idempotency-key`, `--max-runtime`, `--max-retries`, `--skill` (repeatable). | | `list` / `ls` | List tasks on the active board. Filter with `--mine`, `--assignee`, `--status`, `--tenant`, `--archived`, `--json`. | | `show <id>` | Show a task with comments and events. `--json` for machine output. | | `assign <id> <profile>` | Assign or reassign. Use `none` to unassign. Refused while task is running. | | `link <parent> <child>` | Add a dependency. Cycle-detected. Both tasks must be on the same board. | | `unlink <parent> <child>` | Remove a dependency. | | `claim <id>` | Atomically claim a ready task. Prints resolved workspace path. | | `comment <id> "<text>"` | Append a comment. The next worker that claims the task reads it as part of its `kanban_show()` response. | | `complete <id>` | Mark task done. Flags: `--result`, `--summary`, `--metadata`. | | `block <id> "<reason>"` | Mark task blocked for human input. Also appends the reason as a comment. | | `schedule <id> "<reason>"` | Park time-delay/follow-up work in `scheduled` so it is not shown as a human blocker. | | `unblock <id>` | Return a blocked or scheduled task to ready (or `todo` if dependencies are still open). | | `archive <id>` | Hide from default list. `gc` will remove scratch workspaces. | | `tail <id>` | Follow a task’s event stream. | | `dispatch` | One dispatcher pass on the active board. Flags: `--dry-run`, `--max N`, `--failure-limit N`, `--json`. | | `context <id>` | Print the full context a worker would see (title + body + parent results + comments). | | `specify <id>` / `specify --all` | Flesh out a triage-column task into a concrete spec (title + body with goal, approach, acceptance criteria) via the auxiliary LLM, then promote it to `todo`. Flags: `--tenant` (scope `--all` to one tenant), `--author`, `--json`. Configure the model under `auxiliary.triage_specifier` in `config.yaml`. | | `decompose <id>` / `decompose --all` | Fan a triage-column task out into a graph of child tasks routed to specialist profiles by description. Falls back to specify-style single-task promotion when the LLM decides the task doesn’t benefit from fan-out. Same flags as `specify`. Configure the decomposer model under `auxiliary.kanban_decomposer` in `config.yaml`; `kanban.orchestrator_profile` only controls who owns the root/orchestration task after fan-out. Also runs automatically every dispatcher tick when `kanban.auto_decompose: true` (the default). See Auto vs Manual orchestration. | | `gc` | Remove scratch workspaces for archived tasks. | Examples: `bash # Create a second board and put a task on it without switching away. hermes kanban boards create atm10-server --name "ATM10 Server" --icon 🎮 hermes kanban --board atm10-server create "Restart server" --assignee ops # Switch the active board for subsequent calls. hermes kanban boards switch atm10-server hermes kanban list # shows atm10-server tasks # Archive a board (recoverable) or hard-delete it. hermes kanban boards rm atm10-server hermes kanban boards rm atm10-server --delete` Board resolution order (highest precedence first): `--board <slug>` flag → `HERMES_KANBAN_BOARD` env var → `~/.hermes/kanban/current` file → `default`. All actions are also available as a slash command in the gateway (`/kanban …`), with the same argument surface — including `boards` subcommands and the `--board` flag. For the full design — comparison with Cline Kanban / Paperclip / NanoClaw / Gemini Enterprise, eight collaboration patterns, four user stories, concurrency correctness proof — see `docs/hermes-kanban-v1-spec.pdf` in the repository or the Kanban user guide. ## `hermes webhook` `bash hermes webhook <subscribe|list|remove|test>` Manage dynamic webhook subscriptions for event-driven agent activation. Requires the webhook platform to be enabled in config — if not configured, prints setup instructions. | Subcommand | Description | |————|———––| | `subscribe` / `add` | Create a webhook route. Returns the URL and HMAC secret to configure on your service. | | `list` / `ls` | Show all agent-created subscriptions. | | `remove` / `rm` | Delete a dynamic subscription. Static routes from config.yaml are not affected. | | `test` | Send a test POST to verify a subscription is working. | ### `hermes webhook subscribe` `bash hermes webhook subscribe <name> [options]` | Option | Description | |––––|———––| | `--prompt` | Prompt template with `{dot.notation}` payload references. | | `--events` | Comma-separated event types to accept (e.g. `issues,pull_request`). Empty = all. | | `--description` | Human-readable description. | | `--skills` | Comma-separated skill names to load for the agent run. | | `--deliver` | Delivery target: `log` (default), `telegram`, `discord`, `slack`, `github_comment`. | | `--deliver-chat-id` | Target chat/channel ID for cross-platform delivery. | | `--secret` | Custom HMAC secret. Auto-generated if omitted. | | `--deliver-only` | Skip the agent — deliver the rendered `--prompt` as the literal message. Zero LLM cost, sub-second delivery. Requires `--deliver` to be a real target (not `log`). | Subscriptions persist to `~/.hermes/webhook_subscriptions.json` and are hot-reloaded by the webhook adapter without a gateway restart. ## `hermes doctor` `bash hermes doctor [--fix]` | Option | Description | |––––|———––| | `--fix` | Attempt automatic repairs where possible. | ## `hermes dump` `bash hermes dump [--show-keys]` Outputs a compact, plain-text summary of your entire Hermes setup. Designed to be copy-pasted into Discord, GitHub issues, or Telegram when asking for support — no ANSI colors, no special formatting, just data. | Option | Description | |––––|———––| | `--show-keys` | Show redacted API key prefixes (first and last 4 characters) instead of just `set`/`not set`. | ### What it includes | Section | Details | |———|———| | Header | Hermes version, release date, git commit hash | | Environment | OS, Python version, OpenAI SDK version | | Identity | Active profile name, HERMES_HOME path | | Model | Configured default model and provider | | Terminal | Backend type (local, docker, ssh, etc.) | | API keys | Presence check for all 22 provider/tool API keys | | Features | Enabled toolsets, MCP server count, memory provider | | Services | Gateway status, configured messaging platforms | | Workload | Cron job counts, installed skill count | | Config overrides | Any config values that differ from defaults | ### Example output --- hermes dump --- version: 0.8.0 (2026.4.8) [af4abd2f] os: Linux 6.14.0-37-generic x86_64 python: 3.11.14 openai_sdk: 2.24.0 profile: default hermes_home: ~/.hermes model: anthropic/claude-opus-4.6 provider: openrouter terminal: local api_keys: openrouter set openai not set anthropic set nous not set firecrawl set ... features: toolsets: all mcp_servers: 0 memory_provider: built-in gateway: running (systemd) platforms: telegram, discord cron_jobs: 3 active / 5 total skills: 42 config_overrides: agent.max_turns: 250 compression.threshold: 0.85 display.streaming: True --- end dump --- ### When to use - Reporting a bug on GitHub — paste the dump into your issue - Asking for help in Discord — share it in a code block - Comparing your setup to someone else’s - Quick sanity check when something isn’t working :::tip `hermes dump` is specifically designed for sharing. For interactive diagnostics, use `hermes doctor`. For a visual overview, use `hermes status`. ::: ## `hermes debug` `bash hermes debug share [options]` Upload a debug report (system info + recent logs) to a paste service and get a shareable URL. Useful for quick support requests — includes everything a helper needs to diagnose your issue. | Option | Description | |––––|———––| | `--lines <N>` | Number of log lines to include per log file (default: 200). | | `--expire <days>` | Paste expiry in days (default: 7). | | `--local` | Print the report locally instead of uploading. | The report includes system info (OS, Python version, Hermes version), recent agent and gateway logs (512 KB limit per file), and redacted API key status. Keys are always redacted — no secrets are uploaded. Paste services tried in order: paste.rs, dpaste.com. ### Examples `bash hermes debug share # Upload debug report, print URL hermes debug share --lines 500 # Include more log lines hermes debug share --expire 30 # Keep paste for 30 days hermes debug share --local # Print report to terminal (no upload)` ## `hermes backup` `bash hermes backup [options]` Create a zip archive of your Hermes configuration, skills, sessions, and data. The backup excludes the hermes-agent codebase itself. | Option | Description | |––––|———––| | `-o`, `--output <path>` | Output path for the zip file (default: `~/hermes-backup-<timestamp>.zip`). | | `-q`, `--quick` | Quick snapshot: only critical state files (config.yaml, state.db, .env, auth, cron jobs). Much faster than a full backup. | | `-l`, `--label <name>` | Label for the snapshot (only used with `--quick`). | The backup uses SQLite’s `backup()` API for safe copying, so it works correctly even when Hermes is running (WAL-mode safe). What’s excluded from the zip: - `.db-wal`, `.db-shm`, `.db-journal` — SQLite’s WAL / shared-memory / journal sidecars. The `.db` file already got a consistent snapshot via `sqlite3.backup()`; shipping the live sidecars alongside it would let a restore see a half-committed state. - `checkpoints/` — per-session trajectory caches. Hash-keyed and regenerated per session; wouldn’t port cleanly to another install anyway. - The `hermes-agent` code itself (this is a user-data backup, not a repo snapshot). ### Examples `bash hermes backup # Full backup to ~/hermes-backup-.zip hermes backup -o /tmp/hermes.zip # Full backup to specific path hermes backup --quick # Quick state-only snapshot hermes backup --quick --label "pre-upgrade" # Quick snapshot with label` ## `hermes checkpoints` `bash hermes checkpoints [COMMAND]` Inspect and manage the shadow git store at `~/.hermes/checkpoints/` — the storage layer behind the in-session `/rollback` command. Safe to run any time; does not require the agent to be running. | Subcommand | Description | |————|———––| | `status` (default) | Show total size, project count, and per-project breakdown. Bare `hermes checkpoints` is equivalent. | | `list` | Alias for `status`. | | `prune` | Force a cleanup sweep — delete orphan and stale projects, GC the store, enforce the size cap. Ignores the 24h idempotency marker. | | `clear` | Delete the entire checkpoint base. Irreversible; asks for confirmation unless `-f`. | | `clear-legacy` | Delete only the `legacy-<timestamp>/` archives produced by the v1→v2 migration. | ### Options | Option | Subcommand | Description | |––––|————|———––| | `--limit N` | `status`, `list` | Max projects to list (default 20). | | `--retention-days N` | `prune` | Drop projects whose `last_touch` is older than N days (default 7). | | `--max-size-mb N` | `prune` | After the orphan/stale pass, drop the oldest commit per project until total store size ≤ N MB (default 500). | | `--keep-orphans` | `prune` | Skip deleting projects whose working directory no longer exists. | | `-f`, `--force` | `clear`, `clear-legacy` | Skip the confirmation prompt. | ### Examples `bash hermes checkpoints # status overview hermes checkpoints prune --retention-days 3 # aggressive cleanup hermes checkpoints prune --max-size-mb 200 # tighten size cap once hermes checkpoints clear-legacy -f # drop v1 archive dirs hermes checkpoints clear -f # wipe everything` See Checkpoints and `/rollback` for the full architecture and the in-session commands. ## `hermes import` `bash hermes import <zipfile> [options]` Restore a previously created Hermes backup into your Hermes home directory. All files in the archive overwrite existing files in your Hermes home; `--force` only skips the confirmation prompt that fires when the target already has a Hermes installation. | Option | Description | |––––|———––| | `-f`, `--force` | Skip the existing-installation confirmation prompt. | :::warning Stop the gateway before importing to avoid conflicts with running processes. ::: ### Examples `bash hermes import ~/hermes-backup-20260423.zip # Prompts before overwriting existing config hermes import ~/hermes-backup-20260423.zip --force # Overwrite without prompting` ## `hermes logs` `bash hermes logs [log_name] [options]` View, tail, and filter Hermes log files. All logs are stored in `~/.hermes/logs/` (or `<profile>/logs/` for non-default profiles). ### Log files | Name | File | What it captures | |——|——|—————–| | `agent` (default) | `agent.log` | All agent activity — API calls, tool dispatch, session lifecycle (INFO and above) | | `errors` | `errors.log` | Warnings and errors only — a filtered subset of agent.log | | `gateway` | `gateway.log` | Messaging gateway activity — platform connections, message dispatch, webhook events | | `gui` | `gui.log` | Dashboard / TUI-gateway / PTY-bridge / websocket events | | `desktop` | `desktop.log` | Electron desktop app — boot, backend spawn output, and recent Python tracebacks | ### Options | Option | Description | |––––|———––| | `log_name` | Which log to view: `agent` (default), `errors`, `gateway`, or `list` to show available files with sizes. | | `-n`, `--lines <N>` | Number of lines to show (default: 50). | | `-f`, `--follow` | Follow the log in real time, like `tail -f`. Press Ctrl+C to stop. | | `--level <LEVEL>` | Minimum log level to show: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. | | `--session <ID>` | Filter lines containing a session ID substring. | | `--since <TIME>` | Show lines from a relative time ago: `30m`, `1h`, `2d`, etc. Supports `s` (seconds), `m` (minutes), `h` (hours), `d` (days). | | `--component <NAME>` | Filter by component: `gateway`, `agent`, `tools`, `cli`, `cron`. | ### Examples `bash # View the last 50 lines of agent.log (default) hermes logs # Follow agent.log in real time hermes logs -f # View the last 100 lines of gateway.log hermes logs gateway -n 100 # Show only warnings and errors from the last hour hermes logs --level WARNING --since 1h # Filter by a specific session hermes logs --session abc123 # Follow errors.log, starting from 30 minutes ago hermes logs errors --since 30m -f # List all log files with their sizes hermes logs list` ### Filtering Filters can be combined. When multiple filters are active, a log line must pass all of them to be shown: `bash # WARNING+ lines from the last 2 hours containing session "tg-12345" hermes logs --level WARNING --since 2h --session tg-12345` Lines without a parseable timestamp are included when `--since` is active (they may be continuation lines from a multi-line log entry). Lines without a detectable level are included when `--level` is active. ### Log rotation Hermes uses Python’s `RotatingFileHandler`. Old logs are rotated automatically — look for `agent.log.1`, `agent.log.2`, etc. The `hermes logs list` subcommand shows all log files including rotated ones. ## `hermes prompt-size` `bash hermes prompt-size [--platform <name>] [--json]` Reports the fixed prompt budget for a fresh session — what gets sent on every API call before any conversation content. Useful when a downstream adapter or proxy has a tighter prompt budget than the model’s context window, or when you want to see which block (skills index, memory, profile) dominates. It builds the same system prompt the agent would, then breaks it down: - System prompt total — full assembled prompt (identity, guidance, skills index, context files, memory, profile, timestamp). - Skills index — the `<available_skills>` block. This is often the largest single block when many skills are installed. - Memory and user profile — your `MEMORY.md` / `USER.md` snapshots. - Prompt tiers — stable / context / volatile, matching how Hermes layers the prompt for cache-friendliness. - Tool schemas — the JSON for all enabled tools (the other half of the fixed per-call payload). Runs entirely offline — no API call, works with no credentials configured. `bash # Human-readable breakdown for the CLI platform (default) hermes prompt-size # Simulate a messaging platform's prompt (different platform hint) hermes prompt-size --platform telegram # Machine-readable output for scripts hermes prompt-size --json` :::tip The skills index and tool schemas scale with how many skills and tools you have enabled. To shrink the prompt, disable unused toolsets (`hermes tools`) or uninstall skills you don’t need (`hermes skills`). Context files (AGENTS.md, .cursorrules) in your current directory also count toward the total. ::: ## `hermes config` `bash hermes config <subcommand>` Subcommands: | Subcommand | Description | |————|———––| | `show` | Show current config values. | | `edit` | Open `config.yaml` in your editor. | | `set <key> <value>` | Set a config value. | | `path` | Print the config file path. | | `env-path` | Print the `.env` file path. | | `check` | Check for missing or stale config. | | `migrate` | Add newly introduced options interactively. | ## `hermes pairing` `bash hermes pairing <list|approve|revoke|clear-pending>` | Subcommand | Description | |————|———––| | `list` | Show pending and approved users. | | `approve <platform> <code>` | Approve a pairing code. | | `revoke <platform> <user-id>` | Revoke a user’s access. | | `clear-pending` | Clear pending pairing codes. | ## `hermes skills` `bash hermes skills <subcommand>` Subcommands: | Subcommand | Description | |————|———––| | `browse` | Paginated browser for skill registries. | | `search` | Search skill registries. | | `install` | Install a skill. | | `inspect` | Preview a skill without installing it. | | `list` | List installed skills. | | `check` | Check installed hub skills for upstream updates. | | `update` | Reinstall hub skills with upstream changes when available. | | `audit` | Re-scan installed hub skills. | | `uninstall` | Remove a hub-installed skill. | | `reset` | Un-stick a bundled skill flagged as `user_modified` by clearing its manifest entry. With `--restore`, also replaces the user copy with the bundled version. | | `opt-out` | Stop bundled skills from being seeded into the active profile. Writes a `.no-bundled-skills` marker so the installer, `hermes update`, and any sync skip bundled-skill seeding. Safe by default — nothing on disk is touched. With `--remove`, also deletes already-present bundled skills that are unmodified (user-edited, hub-installed, and hand-written skills are never removed; previews and confirms first, `--yes` to skip). | | `opt-in` | Undo `opt-out` by removing the `.no-bundled-skills` marker so bundled skills are seeded again on the next `hermes update`. With `--sync`, re-seed immediately. | | `publish` | Publish a skill to a registry. | | `snapshot` | Export/import skill configurations. | | `tap` | Manage custom skill sources. | | `config` | Interactive enable/disable configuration for skills by platform. | Common examples: bash hermes skills browse hermes skills browse --source official hermes skills search react --source skills-sh hermes skills search https://mintlify.com/docs --source well-known hermes skills inspect official/security/1password hermes skills inspect skills-sh/vercel-labs/json-render/json-render-react hermes skills install official/migration/openclaw-migration hermes skills install skills-sh/anthropics/skills/pdf --force hermes skills install https://sharethis.chat/SKILL.md # Direct URL (single-file SKILL.md) hermes skills install https://example.com/SKILL.md --name my-skill # Override name when frontmatter has none hermes skills check hermes skills update hermes skills config hermes skills reset google-workspace hermes skills reset google-workspace --restore --yes hermes skills opt-out # stop future bundled-skill seeding (nothing deleted) hermes skills opt-out --remove --yes # also delete UNMODIFIED bundled skills hermes skills opt-in --sync # undo: remove marker and re-seed now Notes: - `--force` can override non-dangerous policy blocks for third-party/community skills. - `--force` does not override a `dangerous` scan verdict. - `--source skills-sh` searches the public `skills.sh` directory. - `--source well-known` lets you point Hermes at a site exposing `/.well-known/skills/index.json`. - `--source browse-sh` searches browse.sh’s catalog of 200+ site-specific browser-automation skills. Identifiers look like `browse-sh/airbnb.com/search-listings-ddgioa`. - Passing an `http(s)://…/.md` URL installs a single-file SKILL.md directly. When frontmatter has no `name:` and the URL slug isn’t a valid identifier, an interactive terminal prompts for a name; non-interactive surfaces (`/skills install` inside the TUI, gateway platforms) require `--name <x>` instead. ## `hermes bundles` `bash hermes bundles <subcommand>` Skill bundles group several skills under one `/<bundle-name>` slash command. Invoking the bundle loads every referenced skill into a single combined user message. Storage: `~/.hermes/skill-bundles/<slug>.yaml`. See Skill Bundles for the YAML schema and behavior. Subcommands: | Subcommand | Description | |————|———––| | `list` | List installed bundles (default when no subcommand given) | | `show <name>` | Show one bundle’s name, description, skills, and file path | | `create <name>` | Create a new bundle. Pass `--skill <id>` (repeat) or omit for interactive entry. `--description`, `--instruction`, `--force` available. | | `delete <name>` | Remove a bundle file | | `reload` | Re-scan `~/.hermes/skill-bundles/` and report added/removed bundles | Examples: `bash hermes bundles create backend-dev \ --skill github-code-review \ --skill test-driven-development \ --skill github-pr-workflow \ -d "Backend feature work" hermes bundles list hermes bundles show backend-dev hermes bundles delete backend-dev` In a chat session, `/bundles` lists installed bundles and `/<bundle-name>` loads one. ## `hermes curator` `bash hermes curator <subcommand>` The curator is an auxiliary-model background task that periodically reviews agent-created skills, prunes stale ones, consolidates overlaps, and archives obsolete skills. Bundled and hub-installed skills are never touched. Archives are recoverable; auto-deletion never happens. | Subcommand | Description | |————|———––| | `status` | Show curator status and skill stats | | `run` | Trigger a curator review now (blocks until the LLM pass finishes) | | `run --background` | Start the LLM pass in a background thread and return immediately | | `run --dry-run` | Preview only — produce the review report with no mutations | | `backup` | Take a manual tar.gz snapshot of `~/.hermes/skills/` (curator also snapshots automatically before every real run) | | `rollback` | Restore `~/.hermes/skills/` from a snapshot (defaults to newest) | | `rollback --list` | List available snapshots | | `rollback --id <ts>` | Restore a specific snapshot by id | | `rollback -y` | Skip the confirmation prompt | | `pause` | Pause the curator until resumed | | `resume` | Resume a paused curator | | `pin <skill>` | Pin a skill so the curator never auto-transitions it | | `unpin <skill>` | Unpin a skill | | `restore <skill>` | Restore an archived skill | | `archive <skill>` | Archive a skill manually | | `prune` | Manually prune skills the curator would normally clean up | | `list-archived` | List archived skills (recoverable via `restore`) | On a fresh install the first scheduled pass is deferred by one full `interval_hours` (7 days by default) — the gateway will not curate immediately on the first tick after `hermes update`. Use `hermes curator run --dry-run` to preview before that happens. See Curator for behavior and config. ## `hermes fallback` `bash hermes fallback <subcommand>` Manage the fallback provider chain. Fallback providers are tried in order when the primary model fails with rate-limit, overload, or connection errors. | Subcommand | Description | |————|———––| | `list` (alias: `ls`) | Show the current fallback chain (default when no subcommand) | | `add` | Pick a provider + model (same picker as `hermes model`) and append to the chain | | `remove` (alias: `rm`) | Pick an entry to delete from the chain | | `clear` | Remove all fallback entries | See Fallback Providers. ## `hermes hooks` `bash hermes hooks <subcommand>` Inspect shell-script hooks declared in `~/.hermes/config.yaml`, test them against synthetic payloads, and manage the first-use consent allowlist at `~/.hermes/shell-hooks-allowlist.json`. | Subcommand | Description | |————|———––| | `list` (alias: `ls`) | List configured hooks with matcher, timeout, and consent status | | `test <event>` | Fire every hook matching `<event>` against a synthetic payload | | `revoke` (aliases: `remove`, `rm`) | Remove a command’s allowlist entries (takes effect on next restart) | | `doctor` | Check each configured hook: exec bit, allowlist, mtime drift, JSON validity, and synthetic run timing | See Hooks for event signatures and payload shapes. ## `hermes memory` `bash hermes memory <subcommand>` Set up and manage external memory provider plugins. Available providers: honcho, openviking, mem0, hindsight, holographic, retaindb, byterover, supermemory. Only one external provider can be active at a time. Built-in memory (MEMORY.md/USER.md) is always active. Subcommands: | Subcommand | Description | |————|———––| | `setup` | Interactive provider selection and configuration. | | `status` | Show current memory provider config. | | `off` | Disable external provider (built-in only). | :::info Provider-specific subcommands When an external memory provider is active, it may register its own top-level `hermes <provider>` command for provider-specific management (e.g. `hermes honcho` when Honcho is active). Inactive providers do not expose their subcommands. Run `hermes --help` to see what’s currently wired in. ::: ## `hermes acp` `bash hermes acp` Starts Hermes as an ACP (Agent Client Protocol) stdio server for editor integration. Related entrypoints: `bash hermes-acp python -m acp_adapter` Install support first: `bash pip install -e '.[acp]'` See ACP Editor Integration and ACP Internals. ## `hermes mcp` `bash hermes mcp <subcommand>` Manage MCP (Model Context Protocol) server configurations and run Hermes as an MCP server. | Subcommand | Description | |————|———––| | (none)* or `picker` | Interactive catalog picker — browse Nous-approved MCPs and install/enable/disable. | | `catalog` | List Nous-approved MCPs (plain text, scriptable). | | `install <name>` | Install a catalog entry (e.g. `hermes mcp install n8n`). | | `serve [-v\|--verbose]` | Run Hermes as an MCP server — expose conversations to other agents. | | `add <name> [--url URL] [--command CMD] [--args ...] [--auth oauth\|header]` | Add a custom MCP server with automatic tool discovery. | | `remove <name>` (alias: `rm`) | Remove an MCP server from config. | | `list` (alias: `ls`) | List configured MCP servers. | | `test <name>` | Test connection to an MCP server. | | `configure <name>` (alias: `config`) | Toggle tool selection for a server. | | `login <name>` | Force re-authentication for an OAuth-based MCP server. | See MCP Config Reference, Use MCP with Hermes, and MCP Server Mode. ## `hermes plugins` `bash hermes plugins [subcommand]` Unified plugin management — general plugins, memory providers, and context engines in one place. Running `hermes plugins` with no subcommand opens a composite interactive screen with two sections: - General Plugins — multi-select checkboxes to enable/disable installed plugins - Provider Plugins — single-select configuration for Memory Provider and Context Engine. Press ENTER on a category to open a radio picker. | Subcommand | Description | |————|———––| | (none) | Composite interactive UI — general plugin toggles + provider plugin configuration. | | `install <identifier> [--force]` | Install a plugin from a Git URL or `owner/repo`. | | `update <name>` | Pull latest changes for an installed plugin. | | `remove <name>` (aliases: `rm`, `uninstall`) | Remove an installed plugin. | | `enable <name>` | Enable a disabled plugin. | | `disable <name>` | Disable a plugin without removing it. | | `list` (alias: `ls`) | List installed plugins with enabled/disabled status. | Provider plugin selections are saved to `config.yaml`: - `memory.provider` — active memory provider (empty = built-in only) - `context.engine` — active context engine (`"compressor"` = built-in default) General plugin disabled list is stored in `config.yaml` under `plugins.disabled`. See Plugins and Build a Hermes Plugin. ## `hermes tools` `bash hermes tools [--summary]` | Option | Description | |––––|———––| | `--summary` | Print the current enabled-tools summary and exit. | Without `--summary`, this launches the interactive per-platform tool configuration UI. ## `hermes computer-use` `bash hermes computer-use <subcommand>` Subcommands: | Subcommand | Description | |————|———––| | `install` | Run the upstream cua-driver installer (macOS only). | | `install --upgrade` | Re-run the installer even if cua-driver is already on PATH. The upstream script always pulls the latest release, so this performs an in-place upgrade. | | `status` | Print whether `cua-driver` is on `$PATH` and which version is installed. | `hermes computer-use install` is the stable entry point for installing the cua-driver binary used by the `computer_use` toolset. It runs the same upstream installer that `hermes tools` invokes when you first enable Computer Use, so it’s safe to use for re-running the install if the toolset toggle didn’t trigger it (for example, on returning-user setups). `hermes update` automatically re-runs the upstream installer at the end of the update if cua-driver is on PATH, so most users will not need to call `--upgrade` manually. Use it when upstream ships a fix you want right now without waiting for the next Hermes update. ## `hermes sessions` `bash hermes sessions <subcommand>` Subcommands: | Subcommand | Description | |————|———––| | `list` | List recent sessions. | | `browse` | Interactive session picker with search and resume. | | `export <output> [--session-id ID]` | Export sessions to JSONL. | | `delete <session-id>` | Delete one session. | | `prune` | Delete old sessions. | | `stats` | Show session-store statistics. | | `rename <session-id> <title>` | Set or change a session title. | ## `hermes insights` `bash hermes insights [--days N] [--source platform]` | Option | Description | |––––|———––| | `--days <n>` | Analyze the last `n` days (default: 30). | | `--source <platform>` | Filter by source such as `cli`, `telegram`, or `discord`. | ## `hermes claw` `bash hermes claw migrate [options]` Migrate your OpenClaw setup to Hermes. Reads from `~/.openclaw` (or a custom path) and writes to `~/.hermes`. Automatically detects legacy directory names (`~/.clawdbot`, `~/.moltbot`) and config filenames (`clawdbot.json`, `moltbot.json`). | Option | Description | |––––|———––| | `--dry-run` | Preview what would be migrated without writing anything. | | `--preset <name>` | Migration preset: `full` (all compatible settings) or `user-data` (excludes infrastructure config). Neither preset imports secrets — pass `--migrate-secrets` explicitly. | | `--overwrite` | Overwrite existing Hermes files on conflicts (default: refuse to apply when the plan has conflicts). | | `--migrate-secrets` | Include API keys in migration. Required even under `--preset full`. | | `--no-backup` | Skip the pre-migration zip snapshot of `~/.hermes/` (by default a single restore-point archive is written to `~/.hermes/backups/pre-migration-.zip` before apply; restorable with `hermes import`). | | `--source <path>` | Custom OpenClaw directory (default: `~/.openclaw`). | | `--workspace-target <path>` | Target directory for workspace instructions (AGENTS.md). | | `--skill-conflict <mode>` | Handle skill name collisions: `skip` (default), `overwrite`, or `rename`. | | `--yes` | Skip the confirmation prompt. | ### What gets migrated The migration covers 30+ categories across persona, memory, skills, model providers, messaging platforms, agent behavior, session policies, MCP servers, TTS, and more. Items are either directly imported into Hermes equivalents or archived for manual review. Directly imported: SOUL.md, MEMORY.md, USER.md, AGENTS.md, skills (4 source directories), default model, custom providers, MCP servers, messaging platform tokens and allowlists (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost), agent defaults (reasoning effort, compression, human delay, timezone, sandbox), session reset policies, approval rules, TTS config, browser settings, tool settings, exec timeout, command allowlist, gateway config, and API keys from 3 sources. Archived for manual review: Cron jobs, plugins, hooks/webhooks, memory backend (QMD), skills registry config, UI/identity, logging, multi-agent setup, channel bindings, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md. API key resolution checks three sources in priority order: config values → `~/.openclaw/.env` → `auth-profiles.json`. All token fields handle plain strings, env templates (`${VAR}`), and SecretRef objects. For the complete config key mapping, SecretRef handling details, and post-migration checklist, see the full migration guide. ### Examples `bash # Preview what would be migrated hermes claw migrate --dry-run # Full migration (all compatible settings, no secrets) hermes claw migrate --preset full # Full migration including API keys hermes claw migrate --preset full --migrate-secrets # Migrate user data only (no secrets), overwrite conflicts hermes claw migrate --preset user-data --overwrite # Migrate from a custom OpenClaw path hermes claw migrate --source /home/user/old-openclaw` ## `hermes dashboard` `bash hermes dashboard [options]` Launch the web dashboard — a browser-based UI for managing configuration, API keys, and monitoring sessions. Requires `pip install hermes-agent[web]` (FastAPI + Uvicorn). The embedded browser Chat tab is always available and additionally needs the `pty` extra (`pip install 'hermes-agent[web,pty]'`) plus a POSIX PTY environment such as Linux, macOS, or WSL2. See Web Dashboard for full documentation. | Option | Default | Description | |––––|———|———––| | `--port` | `9119` | Port to run the web server on | | `--host` | `127.0.0.1` | Bind address | | `--no-open` | — | Don’t auto-open the browser | | `--insecure` | off | Allow binding to non-localhost hosts. Exposes dashboard credentials on the network; use only behind trusted network controls. | | `--stop` | — | Stop running `hermes dashboard` processes and exit. | | `--status` | — | List running `hermes dashboard` processes and exit. | `bash # Default — opens browser to http://127.0.0.1:9119 hermes dashboard # Custom port, no browser hermes dashboard --port 8080 --no-open` ## `hermes profile` `bash hermes profile <subcommand>` Manage profiles — multiple isolated Hermes instances, each with its own config, sessions, skills, and home directory. | Subcommand | Description | |————|———––| | `list` | List all profiles. | | `use <name>` | Set a sticky default profile. | | `create <name> [--clone] [--clone-all] [--clone-from <source>] [--no-alias]` | Create a new profile. `--clone` copies config, `.env`, and `SOUL.md` from the active profile. `--clone-all` copies all state. `--clone-from` specifies a source profile. | | `delete <name> [-y]` | Delete a profile. | | `show <name>` | Show profile details (home directory, config, etc.). | | `alias <name> [--remove] [--name NAME]` | Manage wrapper scripts for quick profile access. | | `rename <old> <new>` | Rename a profile. | | `export <name> [-o FILE]` | Export a profile to a `.tar.gz` archive (local backup). | | `import <archive> [--name NAME]` | Import a profile from a `.tar.gz` archive (local restore). | | `install <source> [--name N] [--alias] [--force] [-y]` | Install a profile distribution from a git URL or local directory. | | `update <name> [--force-config] [-y]` | Re-pull a distribution; preserves user data (memories, sessions, auth). | | `info <name>` | Show a profile’s distribution manifest (version, requirements, source). | Examples: `bash hermes profile list hermes profile create work --clone hermes profile use work hermes profile alias work --name h-work hermes profile export work -o work-backup.tar.gz hermes profile import work-backup.tar.gz --name restored hermes profile install github.com/user/my-distro --alias hermes profile update work hermes -p work chat -q "Hello from work profile"` ## `hermes completion` `bash hermes completion [bash|zsh|fish]` Print a shell completion script to stdout. Source the output in your shell profile for tab-completion of Hermes commands, subcommands, and profile names. Examples: `bash # Bash hermes completion bash >> ~/.bashrc # Zsh hermes completion zsh >> ~/.zshrc # Fish hermes completion fish > ~/.config/fish/completions/hermes.fish` ## `hermes update` `bash hermes update [--gateway] [--check] [--no-backup] [--backup] [--yes]` Pulls the latest `hermes-agent` code and reinstalls dependencies in your venv, then re-runs the post-install hooks (MCP servers, skills sync, completion install). Safe to run on a live install. pip installs: `hermes update` detects pip-based installations automatically — it queries PyPI for the latest release and runs `pip install --upgrade hermes-agent` instead of `git pull`. PyPI releases track tagged versions (major/minor releases), not every commit on `main`. Use `--check` to see if a newer PyPI release is available without installing. git installs: `hermes update` pulls the configured update branch (default: `main`). If your checkout is on another branch, Hermes may check out the update branch before pulling. Commit branch work before updating when you want to keep it outside the update autostash flow. | Option | Description | |––––|———––| | `--gateway` | Internal mode used by the messaging `/update` command. Uses file-based IPC for prompts and progress streaming instead of reading from terminal stdin. Not a gateway restart flag. | | `--check` | Check whether an update is available without pulling, installing dependencies, or restarting anything. | | `--no-backup` | Skip the pre-update backup for this run, even if `updates.pre_update_backup` is enabled in `config.yaml`. | | `--backup` | Create a labeled pre-update snapshot of `HERMES_HOME` (config, auth, sessions, skills, pairing data) before pulling. Default is off — the previous always-backup behavior was adding minutes to every update on large homes. Flip it on permanently via `updates.pre_update_backup: true` in `config.yaml`. | | `--yes`, `-y` | Assume yes for interactive prompts such as config migration and stash restore. API-key entry is skipped; run `hermes config migrate` separately for those. | Additional behavior: - Gateway restart. After a successful update, Hermes attempts to restart all running gateway profiles automatically so they pick up the new code. Use `hermes gateway restart` when you want to restart a gateway without applying an update. - Local source changes. For git installs, dirty tracked files and untracked files are auto-stashed before branch checkout or pull (`git stash push --include-untracked`). Interactive terminal updates ask before restoring the stash. Non-interactive updates restore it by default; set `updates.non_interactive_local_changes: discard` only on managed installs where local source edits should be thrown away after a successful pull. If stash restore conflicts or the pull fails, the stash is left in place for manual recovery. - npm lockfile churn. Before stashing or switching branches, Hermes makes a best-effort cleanup of tracked `package-lock.json` diffs produced by npm install/build steps. Commit or manually stash intentional lockfile edits before running `hermes update`. - Pairing data snapshot. Even when `--backup` is off, `hermes update` takes a lightweight snapshot of `~/.hermes/pairing/` and the Feishu comment rules before `git pull`. You can roll it back with `hermes backup restore --state pre-update` if a pull rewrites a file you were editing. - Legacy `hermes.service` warning. If Hermes detects a pre-rename `hermes.service` systemd unit (instead of the current `hermes-gateway.service`), it prints a one-time migration hint so you can avoid flap-loop issues. - Exit codes. `0` on success, `1` on pull/install/post-install errors, `2` on unexpected working-tree changes that block `git pull`. ## Maintenance commands | Command | Description | |———|———––| | `hermes version` | Print version information. | | `hermes update` | Pull latest changes and reinstall dependencies. | | `hermes postinstall` | Internal bootstrap. Runs once after `pip install hermes-agent` (or `hermes update` on pip installs) to install non-Python dependencies that pip cannot provide — Node.js runtime, headless browser, ripgrep, ffmpeg — and then trigger `hermes setup` if the profile has not been configured yet. Safe to re-run idempotently. | | `hermes uninstall [--full] [--gui] [--yes]` | Remove Hermes, optionally deleting all config/data. `--gui` removes only the desktop Chat GUI, leaving the agent intact; `--full` also deletes config/data; `--yes` skips prompts. | ## See also - Slash Commands Reference - CLI Interface - Sessions - Skills System - Skins & Themes — # Slash Commands Reference # Slash Commands Reference Hermes has two slash-command surfaces, both driven by a central `COMMAND_REGISTRY` in `hermes_cli/commands.py`: - Interactive CLI slash commands — dispatched by `cli.py`, with autocomplete from the registry - Messaging slash commands — dispatched by `gateway/run.py`, with help text and platform menus generated from the registry Installed skills are also exposed as dynamic slash commands on both surfaces. That includes bundled skills like `/plan`, which opens plan mode and saves markdown plans under `.hermes/plans/` relative to the active workspace/backend working directory. ## Permissions and admin/user split Every messaging platform that supports a per-user allowlist (Telegram, Discord, Slack, Matrix, Mattermost, Signal, …) also supports a two-tier slash command split: admins get every registered command, regular users only get the names you list in `user_allowed_commands` (plus the always-allowed floor `/help` and `/whoami`). Configure `allow_admin_from` and `user_allowed_commands` (and the per-group equivalents `group_allow_admin_from` / `group_user_allowed_commands`) inside the platform’s `extra:` block in `~/.hermes/gateway-config.yaml`. See the per-platform docs for examples — the structure is identical across platforms: - Telegram - Discord - Slack - Matrix - Mattermost - Signal If `allow_admin_from` is unset for a scope, that scope stays in unrestricted backward-compat mode — every allowed user can run every command. ## Interactive CLI slash commands Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-insensitive. ### Session | Command | Description | |———|———––| | `/new [name]` (alias: `/reset`) | Start a new session (fresh session ID + history). Optional `[name]` sets the initial session title — e.g. `/new my-experiment` opens a fresh session already titled `my-experiment` so it’s easy to find later with `/resume` or `/sessions`. Append `now`, `--yes`, or `-y` to skip the confirmation modal — e.g. `/reset now`, `/new --yes my-experiment`. | | `/clear` | Clear screen and start a new session | | `/history` | Show conversation history | | `/save` | Save the current conversation | | `/retry` | Retry the last message (resend to agent) | | `/undo` | Remove the last user/assistant exchange | | `/title` | Set a title for the current session (usage: /title My Session Name) | | `/compress [here [N] \| focus topic]` | Manually compress conversation context (flush memories + summarize). `/compress here [N]` summarizes everything except the most recent N exchanges (default 2), kept verbatim — pick your own compression boundary. A focus topic narrows what a full summary preserves. | | `/rollback` | List or restore filesystem checkpoints (usage: /rollback [number]) | | `/snapshot [create\|restore <id>\|prune]` (alias: `/snap`) | Create or restore state snapshots of Hermes config/state. `create [label]` saves a snapshot, `restore <id>` reverts to it, `prune [N]` removes old snapshots, or list all with no args. | | `/stop` | Kill all running background processes | | `/queue <prompt>` (alias: `/q`) | Queue a prompt for the next turn (doesn’t interrupt the current agent response). | | `/steer <prompt>` | Inject a mid-run note that arrives at the agent after the next tool call — no interrupt, no new user turn. The text is appended to the last tool result’s content once the current tool completes, giving the agent new context without breaking the current tool-calling loop. Use this to nudge direction mid-task (e.g. “focus on the auth module” while the agent is running tests). | | `/goal <text>` | Set a standing goal Hermes works toward across turns — our take on the Ralph loop. After each turn an auxiliary judge model decides whether the goal is done; if not, Hermes auto-continues. Subcommands: `/goal status`, `/goal pause`, `/goal resume`, `/goal clear`. Budget defaults to 20 turns (`goals.max_turns`); any real user message preempts the continuation loop, and state survives `/resume`. See Persistent Goals for the full walkthrough. | | `/subgoal <text>` | Append a user-supplied criterion to the active goal mid-loop. The continuation prompt surfaces all subgoals to the agent verbatim, and the judge factors them into its DONE/CONTINUE verdict — so the goal isn’t marked done until the original goal and every subgoal are met. Subcommands: `/subgoal` (list), `/subgoal remove <N>`, `/subgoal clear`. Requires an active `/goal`. | | `/resume [name]` | Resume a previously-named session | | `/sessions` (TUI alias: `/switch`) | Classic CLI: browse and resume previous sessions in an interactive picker. TUI: open the live session switcher for currently open TUI sessions. Use `/sessions new` in the TUI to start another live session immediately. | | `/redraw` | Force a full UI repaint (recovers from terminal drift after tmux resize, mouse selection artifacts, etc.) | | `/status` | Show session info — model, provider, profile, session ID, working directory, title, created/updated timestamps, token totals, agent-running state — followed by a local Session recap block (recent user/assistant turn counts, tool result count, top tools used, last few files touched, the latest user prompt, and the latest assistant reply). The recap is computed locally from the in-memory conversation; no LLM call, no prompt-cache impact. | | `/agents` (alias: `/tasks`) | Show active agents and running tasks across the current session. | | `/background <prompt>` (alias: `/bg`, `/btw`) | Run a prompt in a separate background session. The agent processes your prompt independently — your current session stays free for other work. Results appear as a panel when the task finishes. See CLI Background Sessions. | | `/branch [name]` (alias: `/fork`) | Branch the current session (explore a different path) | | `/handoff <platform>` | CLI only. Hand the current session off to a messaging platform (Telegram, Discord, Slack, WhatsApp, Signal, Matrix). The gateway picks it up immediately, creates a fresh thread on platforms that support threads (Telegram topics, Discord text-channel threads, Slack message-anchored threads), re-binds the destination to your CLI session_id so the full role-aware transcript replays, and forges a synthetic user turn so the agent confirms it’s working in the new place. Your CLI exits cleanly on success with a `/resume` hint; resume locally any time with `/resume <title>`. Refused mid-turn. Requires the gateway to be running and a home channel configured for the target platform (`/sethome` from the destination chat). See Cross-Platform Handoff. | ### Configuration | Command | Description | |———|———––| | `/config` | Show current configuration | | `/model [model-name]` | Show or change the current model. Supports: `/model claude-sonnet-4`, `/model provider:model` (switch providers), `/model custom:model` (custom endpoint), `/model custom:name:model` (named custom provider), `/model custom` (auto-detect from endpoint), and user-defined aliases (`/model fav`, `/model grok` — see Custom model aliases). Use `--global` to persist the change to config.yaml. Note: `/model` can only switch between already-configured providers. To add a new provider, exit the session and run `hermes model` from your terminal. | | `/codex-runtime [auto\|codex_app_server\|on\|off]` | Toggle the optional Codex app-server runtime for OpenAI/Codex models. `auto` (default) uses Hermes’ standard chat completions; `codex_app_server` hands turns to a `codex app-server` subprocess for native shell, apply_patch, ChatGPT subscription auth, and migrated Codex plugins. Effective on next session. | | `/personality` | Set a predefined personality | | `/verbose` | Cycle tool progress display: off → new → all → verbose. Can be enabled for messaging via config. | | `/fast [normal\|fast\|status]` | Toggle fast mode — OpenAI Priority Processing / Anthropic Fast Mode. Options: `normal`, `fast`, `status`. | | `/reasoning` | Manage reasoning effort and display (usage: /reasoning [level|show|hide]) | | `/skin` | Show or change the display skin/theme | | `/statusbar` (alias: `/sb`) | Toggle the context/model status bar on or off | | `/voice [on\|off\|tts\|status]` | Toggle CLI voice mode and spoken playback. Recording uses `voice.record_key` (default: `Ctrl+B`). | | `/yolo` | Toggle YOLO mode — skip all dangerous command approval prompts. | | `/footer [on\|off\|status]` | Toggle the gateway runtime-metadata footer on final replies (shows model, context %, and cwd). | | `/busy [queue\|steer\|interrupt\|status]` | CLI-only: control what pressing Enter does while Hermes is working — queue the new message, steer mid-turn, or interrupt immediately. | | `/indicator [kaomoji\|emoji\|unicode\|ascii]` | CLI-only: pick the TUI busy-indicator style. | ### Tools & Skills | Command | Description | |———|———––| | `/tools [list\|disable\|enable] [name...]` | Manage tools: list available tools, or disable/enable specific tools for the current session. Disabling a tool removes it from the agent’s toolset and triggers a session reset. | | `/toolsets` | List available toolsets | | `/browser [connect\|disconnect\|status]` | Manage a local Chromium-family CDP connection. `connect` attaches browser tools to a running Chrome, Brave, Chromium, or Edge instance (default: `http://127.0.0.1:9222`). `disconnect` detaches. `status` shows current connection. Auto-launches a supported Chromium-family browser if no debugger is detected. | | `/skills` | Search, install, inspect, or manage skills from online registries | | `/bundles` | List configured skill bundles — `/<name>` slash aliases that preload several skills at once. Configure under `bundles:` in `~/.hermes/config.yaml`. See Skill Bundles. | | `/cron` | Manage scheduled tasks (list, add/create, edit, pause, resume, run, remove) | | `/curator` | Background skill maintenance — `status`, `run`, `pin`, `archive`. See Curator. | | `/kanban <action>` | Drive the multi-profile, multi-project collaboration board without leaving chat. Full `hermes kanban` surface is available: `/kanban list`, `/kanban show t_abc`, `/kanban create "title" --assignee X`, `/kanban comment t_abc "text"`, `/kanban unblock t_abc`, `/kanban dispatch`, etc. Multi-board support included: `/kanban boards list`, `/kanban boards create <slug>`, `/kanban boards switch <slug>`, `/kanban --board <slug> <action>`. See Kanban slash command. | | `/reload-mcp` (alias: `/reload_mcp`) | Reload MCP servers from config.yaml | | `/reload-skills` (alias: `/reload_skills`) | Re-scan `~/.hermes/skills/` for newly installed or removed skills | | `/reload` | Reload `.env` variables into the running session (picks up new API keys without restarting) | | `/plugins` | List installed plugins and their status | ### Info | Command | Description | |———|———––| | `/help` | Show this help message | | `/version` | Show Hermes Agent version, build, and environment info. | | `/usage` | Show token usage, cost breakdown, session duration, and — when available from the active provider — an Account limits section with remaining quota / credits / plan usage pulled live from the provider’s API. | | `/insights` | Show usage insights and analytics (last 30 days) | | `/platforms` (alias: `/gateway`) | Show gateway/messaging platform status (CLI-only summary view). | | `/platform <list\|pause\|resume> [name]` | Operate a running gateway platform. `/platform list` lists every adapter and its state (running, paused-by-breaker, manually-paused); `/platform pause <name>` stops dispatching new messages to that adapter without unloading it; `/platform resume <name>` re-enables it. The gateway also auto-pauses an adapter when its circuit breaker trips on repeated retryable failures (network / rate-limit / 5xx) — use `/platform resume <name>` to clear the breaker once the upstream is healthy. Available wherever the gateway is reachable (CLI session, Telegram, Discord, …). | | `/paste` | Attach a clipboard image | | `/copy [number]` | Copy the last assistant response to clipboard (or the Nth-from-last with a number). CLI-only. | | `/image <path>` | Attach a local image file for your next prompt. | | `/debug` | Upload debug report (system info + logs) and get shareable links. Also available in messaging. | | `/profile` | Show active profile name and home directory | | `/gquota` | Show Google Gemini Code Assist quota usage with progress bars (only available when the `google-gemini-cli` provider is active). | ### Exit | Command | Description | |———|———––| | `/quit` | Exit the CLI (also: `/exit`). | ### Dynamic CLI slash commands | Command | Description | |———|———––| | `/<skill-name>` | Load any installed skill as an on-demand command. Example: `/gif-search`, `/github-pr-workflow`, `/excalidraw`. | | `/skills ...` | Search, browse, inspect, install, audit, publish, and configure skills from registries and the official optional-skills catalog. | ### Quick Commands User-defined quick commands map a short slash command to either a shell command or another slash command. Configure them in `~/.hermes/config.yaml`: `yaml quick_commands: status: type: exec command: systemctl status hermes-agent deploy: type: exec command: scripts/deploy.sh inbox: type: alias target: /gmail unread` Then type `/status`, `/deploy`, or `/inbox` in the CLI or a messaging platform. Quick commands are resolved at dispatch time and may not appear in every built-in autocomplete/help table. String-only prompt shortcuts are not supported as quick commands. Put longer reusable prompts in a skill, or use `type: alias` to point at an existing slash command. ### Custom model aliases Define your own short names for models you use often, then reach them with `/model <alias>` in the CLI or any messaging platform. Aliases work identically in both, on session-only (default) and `--global` switches. Two config formats are supported: Full form — pin an exact model, provider, and optionally a base URL. Put this in `~/.hermes/config.yaml`: `yaml model_aliases: fav: model: claude-sonnet-4.6 provider: anthropic grok: model: grok-4 provider: x-ai ollama-qwen: model: qwen3-coder:30b provider: custom base_url: http://localhost:11434/v1` Short form — `provider/model` in one string. Set from the shell without editing YAML: `bash hermes config set model.aliases.fav anthropic/claude-opus-4.6 hermes config set model.aliases.grok x-ai/grok-4` Then in chat: `/model fav # session-only /model grok --global # also persists current-model change to config.yaml` User aliases take precedence over built-in short names, so naming an alias `sonnet`, `kimi`, `opus`, etc. will shadow the built-in. Alias names are case-insensitive. ### Alias Resolution Commands support prefix matching: typing `/h` resolves to `/help`, `/mod` resolves to `/model`. When a prefix is ambiguous (matches multiple commands), the first match in registry order wins. Full command names and registered aliases always take priority over prefix matches. ## Messaging slash commands The messaging gateway supports the following built-in commands inside Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant, and Teams chats: | Command | Description | |———|———––| | `/start` | Platform-protocol command. Many chat platforms (Telegram, Discord, …) send `/start` automatically the first time a user opens a bot conversation. Hermes acknowledges the ping silently — no agent reply, no session burn — so first-contact handshakes don’t waste a turn. You can also send it explicitly to confirm the gateway is reachable. | | `/new` | Start a new conversation. | | `/reset` | Reset conversation history. | | `/status` | Show session info, followed by a local Session recap block (recent turn counts, top tools used, files touched, latest prompt + reply). | | `/stop` | Kill all running background processes and interrupt the running agent. | | `/model [provider:model]` | Show or change the model. Supports provider switches (`/model zai:glm-5`), custom endpoints (`/model custom:model`), named custom providers (`/model custom:local:qwen`), auto-detect (`/model custom`), and user-defined aliases (`/model fav`, `/model grok` — see Custom model aliases). Use `--global` to persist the change to config.yaml. Note: `/model` can only switch between already-configured providers. To add a new provider or set up API keys, use `hermes model` from your terminal (outside the chat session). | | `/codex-runtime [auto\|codex_app_server\|on\|off]` | Toggle the optional Codex app-server runtime. Persists to `model.openai_runtime` in config.yaml and evicts the cached agent so the next message picks up the new runtime. Effective on next session. | | `/personality [name]` | Set a personality overlay for the session. | | `/fast [normal\|fast\|status]` | Toggle fast mode — OpenAI Priority Processing / Anthropic Fast Mode. | | `/retry` | Retry the last message. | | `/undo` | Remove the last exchange. | | `/sethome` (alias: `/set-home`) | Mark the current chat as the platform home channel for deliveries. | | `/compress [here [N] \| focus topic]` | Manually compress conversation context. `/compress here [N]` keeps the most recent N exchanges (default 2) verbatim and summarizes the rest. A focus topic narrows what a full summary preserves. | | `/topic [off\|help\|session-id]` | Telegram DM only. Manage user-managed multi-session topic mode. `/topic` enables it or shows status; `/topic off` disables it and clears bindings; `/topic help` shows usage; `/topic <session-id>` inside a topic restores a previous session. See Multi-session DM mode. | | `/title [name]` | Set or show the session title. | | `/resume [name]` | Resume a previously named session. | | `/usage` | Show token usage, estimated cost breakdown (input/output), context window state, session duration, and — when available from the active provider — an Account limits section with remaining quota / credits pulled live from the provider’s API. | | `/insights [days]` | Show usage analytics. | | `/reasoning [level\|show\|hide]` | Change reasoning effort or toggle reasoning display. | | `/voice [on\|off\|tts\|join\|channel\|leave\|status]` | Control spoken replies in chat. `join`/`channel`/`leave` manage Discord voice-channel mode. | | `/rollback [number]` | List or restore filesystem checkpoints. | | `/background <prompt>` | Run a prompt in a separate background session. Results are delivered back to the same chat when the task finishes. See Messaging Background Sessions. | | `/queue <prompt>` (alias: `/q`) | Queue a prompt for the next turn without interrupting the current one. | | `/steer <prompt>` | Inject a message after the next tool call without interrupting — the model picks it up on its next iteration rather than as a new turn. | | `/goal <text>` | Set a standing goal Hermes works toward across turns — our take on the Ralph loop. A judge model checks after each turn; if not done, Hermes auto-continues until it is, you pause/clear it, or the turn budget (default 20) is hit. Subcommands: `/goal status`, `/goal pause`, `/goal resume`, `/goal clear`. Safe to run mid-agent for status/pause/clear; setting a new goal requires `/stop` first. See Persistent Goals. | | `/footer [on\|off\|status]` | Toggle the runtime-metadata footer on final replies (shows model, context %, and cwd). | | `/curator [status\|run\|pin\|archive]` | Background skill maintenance controls. | | `/kanban <action>` | Drive the multi-profile, multi-project collaboration board from chat — identical argument surface to the CLI. Bypasses the running-agent guard, so `/kanban unblock t_abc`, `/kanban comment t_abc "…"`, `/kanban list --mine`, `/kanban boards switch <slug>`, etc. work mid-turn. `/kanban create …` auto-subscribes the originating chat to the new task’s terminal events. See Kanban slash command. | | `/reload-mcp` (alias: `/reload_mcp`) | Reload MCP servers from config. | | `/yolo` | Toggle YOLO mode — skip all dangerous command approval prompts. | | `/commands [page]` | Browse all commands and skills (paginated). | | `/approve [session\|always]` | Approve and execute a pending dangerous command. `session` approves for this session only; `always` adds to permanent allowlist. | | `/deny` | Reject a pending dangerous command. | | `/update` | Update Hermes Agent to the latest version. | | `/restart` | Gracefully restart the gateway after draining active runs. When the gateway comes back online, it sends a confirmation to the requester’s chat/thread. | | `/debug` | Upload debug report (system info + logs) and get shareable links. | | `/help` | Show messaging help. | | `/<skill-name>` | Invoke any installed skill by name. | ## Notes - `/skin`, `/snapshot`, `/gquota`, `/reload`, `/tools`, `/toolsets`, `/browser`, `/config`, `/cron`, `/skills`, `/platforms`, `/paste`, `/image`, `/statusbar`, `/plugins`, `/busy`, `/indicator`, `/redraw`, `/clear`, `/history`, `/save`, `/copy`, `/handoff`, and `/quit` are CLI-only commands. - `/verbose` is CLI-only by default, but can be enabled for messaging platforms by setting `display.tool_progress_command: true` in `config.yaml`. When enabled, it cycles the `display.tool_progress` mode and saves to config. - `/sethome`, `/update`, `/restart`, `/approve`, `/deny`, `/topic`, and `/commands` are messaging-only commands. - `/status`, `/version`, `/background`, `/queue`, `/steer`, `/voice`, `/reload-mcp`, `/reload-skills`, `/rollback`, `/debug`, `/fast`, `/footer`, `/curator`, `/kanban`, `/sessions`, and `/yolo` work in both the CLI and the messaging gateway. - `/voice join`, `/voice channel`, and `/voice leave` are only meaningful on Discord. - In the TUI, `/sessions` shows live sessions in the current TUI process. Use `/resume [name]` or `hermes --tui --resume <id-or-title>` for saved or closed transcripts. ## Confirmation prompts for destructive commands The CLI prompts before running slash commands that throw away unsaved session state. The current destructive set is: | Command | What it destroys | |———|——————| | `/clear` | Clears the screen and starts a fresh session — current session ID and in-memory history are gone. | | `/new` / `/reset` | Starts a fresh session (new session ID + empty history). | | `/undo` | Removes the last user/assistant exchange from history. | | `/exit --delete` / `/quit --delete` | Exits and permanently deletes the current session’s SQLite history and on-disk transcripts. | For each of these the CLI opens a three-choice modal: Approve Once (proceed this time), Always Approve (proceed and persist `approvals.destructive_slash_confirm: false` so future destructive commands run without prompting), or Cancel. Inline skip: append `now`, `--yes`, or `-y` to bypass the modal for a single invocation — e.g. `/reset now`, `/new --yes my-session`, `/clear -y`, `/undo -y`. Useful when the modal doesn’t render correctly on your terminal (see issue #30768 for native Windows PowerShell) or when scripting against the CLI. Set `approvals.destructive_slash_confirm: false` in `~/.hermes/config.yaml` to disable the prompts globally; set it back to `true` to re-enable. See Security — Destructive slash command confirmation for context. — # reference/profile-commands # Profile Commands Reference This page covers all commands related to Hermes profiles. For general CLI commands, see CLI Commands Reference. ## `hermes profile` `bash hermes profile <subcommand>` Top-level command for managing profiles. Running `hermes profile` without a subcommand shows help. | Subcommand | Description | |————|———––| | `list` | List all profiles. | | `use` | Set the active (default) profile. | | `create` | Create a new profile. | | `describe` | Read or set a profile’s description (used by the kanban orchestrator for routing). | | `delete` | Delete a profile. | | `show` | Show details about a profile. | | `alias` | Regenerate the shell alias for a profile. | | `rename` | Rename a profile. | | `export` | Export a profile to a tar.gz archive. | | `import` | Import a profile from a tar.gz archive. | | `install` | Install a profile distribution from a git URL or local directory. See Profile Distributions. | | `update` | Re-pull a distribution-managed profile and re-apply its bundle. | | `info` | Show distribution metadata for a profile (origin URL, commit, last update). | ## `hermes profile list` `bash hermes profile list` Lists all profiles. The currently active profile is marked with ``. Example: `bash $ hermes profile list default * work dev personal` No options. ## `hermes profile use` `bash hermes profile use <name>` Sets `<name>` as the active profile. All subsequent `hermes` commands (without `-p`) will use this profile. | Argument | Description | |–––––|———––| | `<name>` | Profile name to activate. Use `default` to return to the base profile. | Example: `bash hermes profile use work hermes profile use default` ## `hermes profile create` `bash hermes profile create <name> [options]` Creates a new profile. | Argument / Option | Description | |—————––|———––| | `<name>` | Name for the new profile. Must be a valid directory name (alphanumeric, hyphens, underscores). | | `--clone` | Copy `config.yaml`, `.env`, and `SOUL.md` from the current profile. | | `--clone-all` | Copy everything (config, memories, skills, sessions, state) from the current profile. | | `--clone-from <profile>` | Clone from a specific profile instead of the current one. Used with `--clone` or `--clone-all`. | | `--no-alias` | Skip wrapper script creation. | | `--description "<text>"` | One- or two-sentence description of what this profile is good at. Used by the kanban orchestrator to route tasks based on role instead of profile name alone. Skip and add later via `hermes profile describe`. Persisted in `<profile_dir>/profile.yaml`. | | `--no-skills` | Create an empty profile with zero bundled skills enabled. Writes a `.no-bundled-skills` marker into the profile so future `hermes update` runs won’t re-seed the bundled set, and refuses to combine with `--clone` / `--clone-all` (which would copy skills in anyway). Useful for narrow orchestrator profiles or sandbox profiles that should not inherit the full skill catalog. To toggle this on an already-created profile (including the default `~/.hermes`), use `hermes skills opt-out` / `hermes skills opt-in`. | Creating a profile does not make that profile directory the default project/workspace directory for terminal commands. If you want a profile to start in a specific project, set `terminal.cwd` in that profile’s `config.yaml`. Examples: `bash # Blank profile — needs full setup hermes profile create mybot # Clone config only from current profile hermes profile create work --clone # Clone everything from current profile hermes profile create backup --clone-all # Clone config from a specific profile hermes profile create work2 --clone --clone-from work` ## `hermes profile describe` `bash hermes profile describe [<name>] [options]` Read or set a profile’s description. The description is consumed by the kanban orchestrator to route tasks based on what each profile is good at, rather than guessing from the profile name alone. Persisted in `<profile_dir>/profile.yaml` so it survives reboots and is shared with the gateway. With no flags, prints the current description (or `(no description set for '<name>')` if empty). | Argument / Option | Description | |—————––|———––| | `<name>` | Profile to describe. Required unless `--all --auto` is used. | | `--text "<text>"` | Set the description to this exact text (user-authored). Overwrites any existing description. | | `--auto` | Auto-generate a 1-2 sentence description via the auxiliary LLM, based on the profile’s installed skills, configured model, and name. Configure the model under `auxiliary.profile_describer` in `config.yaml`. Auto-generated descriptions are marked `description_auto: true` so the dashboard can flag them for review. | | `--overwrite` | With `--auto`, replace user-authored descriptions too (default: skip profiles whose description was set explicitly). | | `--all` | With `--auto`, sweep every profile missing a description. | Examples: `bash # Read the current description hermes profile describe researcher # Set it explicitly hermes profile describe researcher --text "Reads source code and writes findings." # Let the LLM generate one hermes profile describe researcher --auto # Fill in descriptions for every profile that doesn't have one hermes profile describe --all --auto` ## `hermes profile delete` `bash hermes profile delete <name> [options]` Deletes a profile and removes its shell alias. | Argument / Option | Description | |—————––|———––| | `<name>` | Profile to delete. | | `--yes`, `-y` | Skip confirmation prompt. | Example: `bash hermes profile delete mybot hermes profile delete mybot --yes` :::warning This permanently deletes the profile’s entire directory including all config, memories, sessions, and skills. Cannot delete the currently active profile. ::: ## `hermes profile show` `bash hermes profile show <name>` Displays details about a profile including its home directory, configured model, gateway status, skills count, and configuration file status. This shows the profile’s Hermes home directory, not the terminal working directory. Terminal commands start from `terminal.cwd` (or the launch directory on the local backend when `cwd: "."`). | Argument | Description | |–––––|———––| | `<name>` | Profile to inspect. | Example: `bash $ hermes profile show work Profile: work Path: ~/.hermes/profiles/work Model: anthropic/claude-sonnet-4 (anthropic) Gateway: stopped Skills: 12 .env: exists SOUL.md: exists Alias: ~/.local/bin/work` ## `hermes profile alias` `bash hermes profile alias <name> [options]` Regenerates the shell alias script at `~/.local/bin/<name>`. Useful if the alias was accidentally deleted or if you need to update it after moving your Hermes installation. | Argument / Option | Description | |—————––|———––| | `<name>` | Profile to create/update the alias for. | | `--remove` | Remove the wrapper script instead of creating it. | | `--name <alias>` | Custom alias name (default: profile name). | Example: `bash hermes profile alias work # Creates/updates ~/.local/bin/work hermes profile alias work --name mywork # Creates ~/.local/bin/mywork hermes profile alias work --remove # Removes the wrapper script` ## `hermes profile rename` `bash hermes profile rename <old-name> <new-name>` Renames a profile. Updates the directory and shell alias. | Argument | Description | |–––––|———––| | `<old-name>` | Current profile name. | | `<new-name>` | New profile name. | Example: `bash hermes profile rename mybot assistant # ~/.hermes/profiles/mybot → ~/.hermes/profiles/assistant # ~/.local/bin/mybot → ~/.local/bin/assistant` ## `hermes profile export` `bash hermes profile export <name> [options]` Exports a profile as a compressed tar.gz archive. | Argument / Option | Description | |—————––|———––| | `<name>` | Profile to export. | | `-o`, `--output <path>` | Output file path (default: `<name>.tar.gz`). | Example: `bash hermes profile export work # Creates work.tar.gz in the current directory hermes profile export work -o ./work-2026-03-29.tar.gz` ## `hermes profile import` `bash hermes profile import <archive> [options]` Imports a profile from a tar.gz archive. | Argument / Option | Description | |—————––|———––| | `<archive>` | Path to the tar.gz archive to import. | | `--name <name>` | Name for the imported profile (default: inferred from archive). | Example: `bash hermes profile import ./work-2026-03-29.tar.gz # Infers profile name from the archive hermes profile import ./work-2026-03-29.tar.gz --name work-restored` ## Distribution commands :::tip New to distributions? Start with the Profile Distributions user guide — it covers the why, when, and how with full examples. The sections below are a dry CLI reference for when you know what you want. ::: Distributions turn a profile into a shareable, versioned artifact published as a git repository. A recipient installs the distribution with a single command and can update it in place later without touching their local memories, sessions, or credentials. `auth.json` and `.env` are never part of a distribution — they stay on the installing user’s machine. The recipient’s user data (memories, sessions, auth, their own edits to `.env`) is always preserved across the initial install and subsequent updates. :::info `hermes profile export` / `import` are still the right commands for local backup and restore of a profile on your own machine. Distribution (`install` / `update` / `info`) is a separate concept: ship a profile via git so someone else can install it. ::: ### `hermes profile install` `bash hermes profile install <source> [--name <name>] [--alias] [--force] [--yes]` Installs a profile distribution from a git URL or a local directory. | Option | Description | |––––|———––| | `<source>` | Git URL (`github.com/user/repo`, `https://...`, `git@...`, `ssh://`, `git://`) or a local directory containing `distribution.yaml` at its root. | | `--name NAME` | Override the profile name from the manifest. | | `--alias` | Also create a shell wrapper (e.g. `telemetry` → `hermes -p telemetry`). | | `--force` | Overwrite an existing profile of the same name. User data is still preserved. | | `-y`, `--yes` | Skip the manifest-preview confirmation prompt. | The installer shows the manifest, lists required env vars, and warns about cron jobs before asking for confirmation. Required env vars go into a `.env.EXAMPLE` file you copy to `.env` and fill in. Examples: `bash # Install from a GitHub repo (shorthand) hermes profile install github.com/kyle/telemetry-distribution --alias # Install from a full HTTPS git URL hermes profile install https://github.com/kyle/telemetry-distribution.git # Install from SSH hermes profile install [email protected]:kyle/telemetry-distribution.git # Install from a local directory during development hermes profile install ./telemetry/` ### `hermes profile update` `bash hermes profile update <name> [--force-config] [--yes]` Re-clones the distribution from its recorded source and applies updates. Distribution-owned files (SOUL.md, skills/, cron/, mcp.json) are overwritten; user data (memories, sessions, auth, .env) is never touched. `config.yaml` is preserved by default to keep your local overrides. Pass `--force-config` to reset it to the distribution’s shipped config. ### `hermes profile info` `bash hermes profile info <name>` Prints the profile’s distribution manifest — name, version, required Hermes version, author, env var requirements, the source URL/path, and the `Installed:` timestamp recorded when the distribution was last `install`-ed or `update`-d. Useful for checking what a shared profile needs before installing it, and for spotting “this profile was installed 6 months ago and hasn’t been updated.” `hermes profile list` also shows the distribution name and version in a `Distribution` column, and `hermes profile show <name>` / `delete <name>` surface the source URL so you can tell at a glance which profiles came from a git repo vs. were created locally. ### Private distributions A private git repository works as a distribution source with no extra configuration — the install shells out to your normal `git` binary, so whatever authentication your shell is already set up for (SSH key, `git credential` helper, GitHub CLI’s stored HTTPS credentials) applies transparently. bash # Uses your SSH key, the same as any other `git clone` hermes profile install [email protected]:your-org/internal-assistant.git # Uses your git credential helper hermes profile install https://github.com/your-org/internal-assistant.git If a clone prompts for credentials interactively in your terminal during install, that prompt flows through. Set up your auth the way you’d normally use `git clone` against the same repo first, then install. ### Distribution manifest (`distribution.yaml`) Every distribution has a `distribution.yaml` at the root of its repository: `yaml name: telemetry version: 0.1.0 description: "Compliance monitoring harness" hermes_requires: ">=0.12.0" author: "Your Name" license: "MIT" env_requires: - name: OPENAI_API_KEY description: "OpenAI API key" required: true - name: GRAPHITI_MCP_URL description: "Memory graph URL" required: false default: "http://127.0.0.1:8000/sse" distribution_owned: # optional; defaults to SOUL.md, config.yaml, # mcp.json, skills/, cron/, distribution.yaml - SOUL.md - skills/compliance/ - cron/` `hermes_requires` supports `>=`, `<=`, `==`, `!=`, `>`, `<`, or a bare version (treated as `>=`). Install fails with a clear error if the current Hermes version doesn’t satisfy the spec. `distribution_owned` is optional. If set, only those paths are replaced on update; anything else in the profile stays user-owned. If omitted, the defaults above apply. ### Publishing a distribution Authoring a distribution is just a git push: 1. In your profile directory, create `distribution.yaml` with at least `name` and `version`. 2. Initialize a git repo (or use an existing one) and push to GitHub / GitLab / any host Hermes can clone from. 3. Tell recipients to run `hermes profile install <your-repo-url>`. Use git tags for versioned releases — recipients who clone `HEAD` get your latest state, and you can always bump `version:` in the manifest. ## `hermes -p` / `hermes --profile` `bash hermes -p <name> <command> [options] hermes --profile <name> <command> [options]` Global flag to run any Hermes command under a specific profile without changing the sticky default. This overrides the active profile for the duration of the command. | Option | Description | |––––|———––| | `-p <name>`, `--profile <name>` | Profile to use for this command. | Examples: `bash hermes -p work chat -q "Check the server status" hermes --profile dev gateway start hermes -p personal skills list hermes -p work config edit` ## `hermes completion` `bash hermes completion <shell>` Generates shell completion scripts. Includes completions for profile names and profile subcommands. | Argument | Description | |–––––|———––| | `<shell>` | Shell to generate completions for: `bash`, `zsh`, or `fish`. | Examples: `bash # Install completions hermes completion bash >> ~/.bashrc hermes completion zsh >> ~/.zshrc hermes completion fish > ~/.config/fish/completions/hermes.fish # Reload shell source ~/.bashrc` After installation, tab completion works for: - `hermes profile <TAB>` — subcommands (list, use, create, etc.) - `hermes profile use <TAB>` — profile names - `hermes -p <TAB>` — profile names ## See also - Profiles User Guide - CLI Commands Reference - FAQ — Profiles section — # Environment Variables # Environment Variables Reference All variables go in `~/.hermes/.env`. You can also set them with `hermes config set VAR value`. ## LLM Providers | Variable | Description | |–––––|———––| | `OPENROUTER_API_KEY` | OpenRouter API key (recommended for flexibility) | | `OPENROUTER_BASE_URL` | Override the OpenRouter-compatible base URL | | `HERMES_OPENROUTER_CACHE` | Enable OpenRouter response caching (`1`/`true`/`yes`/`on`). Overrides `openrouter.response_cache` in config.yaml. See Response Caching. | | `HERMES_OPENROUTER_CACHE_TTL` | Cache TTL in seconds (1-86400). Overrides `openrouter.response_cache_ttl` in config.yaml. | | `NOUS_BASE_URL` | Override Nous Portal base URL (rarely needed; development/testing only) | | `NOUS_INFERENCE_BASE_URL` | Override Nous inference endpoint directly | | `OPENAI_API_KEY` | API key for custom OpenAI-compatible endpoints (used with `OPENAI_BASE_URL`) | | `OPENAI_BASE_URL` | Base URL for custom endpoint (VLLM, SGLang, etc.) | | `LM_API_KEY` | API key for LM Studio (`lmstudio` provider). Often a placeholder for local servers | | `LM_BASE_URL` | LM Studio base URL (default: `http://localhost:1234/v1`) | | `COPILOT_GITHUB_TOKEN` | GitHub token for Copilot API — first priority (OAuth `gho_` or fine-grained PAT `github_pat_`; classic PATs `ghp_` are not supported) | | `GH_TOKEN` | GitHub token — second priority for Copilot (also used by `gh` CLI) | | `GITHUB_TOKEN` | GitHub token — third priority for Copilot | | `HERMES_COPILOT_ACP_COMMAND` | Override Copilot ACP CLI binary path (default: `copilot`) | | `COPILOT_CLI_PATH` | Alias for `HERMES_COPILOT_ACP_COMMAND` | | `HERMES_COPILOT_ACP_ARGS` | Override Copilot ACP arguments (default: `--acp --stdio`) | | `COPILOT_ACP_BASE_URL` | Override Copilot ACP base URL | | `COPILOT_API_BASE_URL` | Override the Copilot API base URL (`copilot` provider) | | `GLM_API_KEY` | z.ai / ZhipuAI GLM API key (z.ai) | | `ZAI_API_KEY` | Alias for `GLM_API_KEY` | | `Z_AI_API_KEY` | Alias for `GLM_API_KEY` | | `GLM_BASE_URL` | Override z.ai base URL (default: `https://api.z.ai/api/paas/v4`) | | `KIMI_API_KEY` | Kimi / Moonshot AI API key (moonshot.ai) | | `KIMI_CODING_API_KEY` | Alias key for the `kimi-coding` provider (accepted alongside `KIMI_API_KEY`) | | `KIMI_BASE_URL` | Override Kimi base URL (default: `https://api.moonshot.ai/v1`) | | `KIMI_CN_API_KEY` | Kimi / Moonshot China API key (moonshot.cn) | | `ARCEEAI_API_KEY` | Arcee AI API key (chat.arcee.ai) | | `ARCEE_BASE_URL` | Override Arcee base URL (default: `https://api.arcee.ai/api/v1`) | | `GMI_API_KEY` | GMI Cloud API key (gmicloud.ai) | | `GMI_BASE_URL` | Override GMI Cloud base URL (default: `https://api.gmi-serving.com/v1`) | | `MINIMAX_API_KEY` | MiniMax API key — global endpoint (minimax.io). Not used by `minimax-oauth` (OAuth path uses browser login instead). | | `MINIMAX_BASE_URL` | Override MiniMax base URL (default: `https://api.minimax.io/anthropic` — Hermes uses MiniMax’s Anthropic Messages-compatible endpoint). Not used by `minimax-oauth`. | | `MINIMAX_CN_API_KEY` | MiniMax API key — China endpoint (minimaxi.com). Not used by `minimax-oauth` (OAuth path uses browser login instead). | | `MINIMAX_CN_BASE_URL` | Override MiniMax China base URL (default: `https://api.minimaxi.com/anthropic`). Not used by `minimax-oauth`. | | `KILOCODE_API_KEY` | Kilo Code API key (kilo.ai) | | `KILOCODE_BASE_URL` | Override Kilo Code base URL (default: `https://api.kilo.ai/api/gateway`) | | `XIAOMI_API_KEY` | Xiaomi MiMo API key (platform.xiaomimimo.com) | | `XIAOMI_BASE_URL` | Override Xiaomi MiMo base URL (default: `https://api.xiaomimimo.com/v1`) | | `TOKENHUB_API_KEY` | Tencent TokenHub API key (tokenhub.tencentmaas.com) | | `TOKENHUB_BASE_URL` | Override Tencent TokenHub base URL (default: `https://tokenhub.tencentmaas.com/v1`) | | `AZURE_FOUNDRY_API_KEY` | Microsoft Foundry / Azure OpenAI API key (ai.azure.com). Not needed when `model.auth_mode: entra_id` | | `AZURE_FOUNDRY_BASE_URL` | Microsoft Foundry endpoint URL (e.g. `https://<resource>.openai.azure.com/openai/v1` for OpenAI-style, or `https://<resource>.services.ai.azure.com/anthropic` for Anthropic-style) | | `AZURE_ANTHROPIC_KEY` | Azure Anthropic API key for `provider: anthropic` + `base_url` pointing at a Microsoft Foundry Claude deployment (alternative to `ANTHROPIC_API_KEY` when both Anthropic and Azure Anthropic are configured) | | `AZURE_TENANT_ID` | Entra ID tenant ID (service-principal flows; honored by `azure-identity` when `model.auth_mode: entra_id`) | | `AZURE_CLIENT_ID` | Entra ID client ID (service principal, workload identity, or user-assigned managed identity) | | `AZURE_CLIENT_SECRET` | Service principal secret used by `EnvironmentCredential` | | `AZURE_CLIENT_CERTIFICATE_PATH` | Service principal certificate (alternative to `AZURE_CLIENT_SECRET`) | | `AZURE_FEDERATED_TOKEN_FILE` | Federated token file path for AKS Workload Identity / OIDC flows | | `AZURE_AUTHORITY_HOST` | Sovereign-cloud authority override (e.g. `https://login.microsoftonline.us` for Azure Government). See Azure Foundry guide | | `IDENTITY_ENDPOINT` / `MSI_ENDPOINT` | Managed Identity endpoint for App Service, Functions, and Container Apps; VMs usually use IMDS instead and do not set these | | `HF_TOKEN` | Hugging Face token for Inference Providers (huggingface.co/settings/tokens) | | `HF_BASE_URL` | Override Hugging Face base URL (default: `https://router.huggingface.co/v1`) | | `GOOGLE_API_KEY` | Google AI Studio API key (aistudio.google.com/app/apikey) | | `GEMINI_API_KEY` | Alias for `GOOGLE_API_KEY` | | `GEMINI_BASE_URL` | Override Google AI Studio base URL | | `HERMES_GEMINI_CLIENT_ID` | OAuth client ID for `google-gemini-cli` PKCE login (optional; defaults to Google’s public gemini-cli client) | | `HERMES_GEMINI_CLIENT_SECRET` | OAuth client secret for `google-gemini-cli` (optional) | | `HERMES_GEMINI_PROJECT_ID` | GCP project ID for paid Gemini tiers (free tier auto-provisions) | | `ANTHROPIC_API_KEY` | Anthropic Console API key (console.anthropic.com) | | `ANTHROPIC_BASE_URL` | Override the Anthropic API base URL | | `ANTHROPIC_TOKEN` | Manual or legacy Anthropic OAuth/setup-token override | | `DASHSCOPE_API_KEY` | Qwen Cloud (Alibaba DashScope) API key for Qwen models (modelstudio.console.alibabacloud.com) | | `DASHSCOPE_BASE_URL` | Custom DashScope base URL (default: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`; use `https://dashscope.aliyuncs.com/compatible-mode/v1` for mainland-China region) | | `ALIBABA_CODING_PLAN_API_KEY` | Qwen Coding Plan API key (`alibaba-coding-plan` provider) | | `ALIBABA_CODING_PLAN_BASE_URL` | Override the Qwen Coding Plan base URL | | `DEEPSEEK_API_KEY` | DeepSeek API key for direct DeepSeek access (platform.deepseek.com) | | `DEEPSEEK_BASE_URL` | Custom DeepSeek API base URL | | `NOVITA_API_KEY` | NovitaAI API key — AI-native cloud for Model API, Agent Sandbox, and GPU Cloud (novita.ai/settings/key-management) | | `NOVITA_BASE_URL` | Override NovitaAI base URL (default: `https://api.novita.ai/openai/v1`) | | `NVIDIA_API_KEY` | NVIDIA NIM API key — Nemotron and open models (build.nvidia.com) | | `NVIDIA_BASE_URL` | Override NVIDIA base URL (default: `https://integrate.api.nvidia.com/v1`; set to `http://localhost:8000/v1` for a local NIM endpoint) | | `STEPFUN_API_KEY` | StepFun API key — Step-series models (platform.stepfun.com) | | `STEPFUN_BASE_URL` | Override StepFun base URL (default: `https://api.stepfun.com/v1`) | | `OLLAMA_API_KEY` | Ollama Cloud API key — managed Ollama catalog without local GPU (ollama.com/settings/keys) | | `OLLAMA_BASE_URL` | Override Ollama Cloud base URL (default: `https://ollama.com/v1`) | | `XAI_API_KEY` | xAI (Grok) API key for chat + TTS + web search (console.x.ai) | | `XAI_BASE_URL` | Override xAI base URL (default: `https://api.x.ai/v1`) | | `MISTRAL_API_KEY` | Mistral API key for Voxtral TTS and Voxtral STT (console.mistral.ai) | | `AWS_REGION` | AWS region for Bedrock inference (e.g. `us-east-1`, `eu-central-1`). Read by boto3. | | `AWS_PROFILE` | AWS named profile for Bedrock authentication (reads `~/.aws/credentials`). Leave unset to use default boto3 credential chain. | | `BEDROCK_BASE_URL` | Override Bedrock runtime base URL (default: `https://bedrock-runtime.us-east-1.amazonaws.com`; usually leave unset and use `AWS_REGION` instead) | | `HERMES_QWEN_BASE_URL` | Qwen Portal base URL override (default: `https://portal.qwen.ai/v1`) | | `OPENCODE_ZEN_API_KEY` | OpenCode Zen API key — pay-as-you-go access to curated models (opencode.ai) | | `OPENCODE_ZEN_BASE_URL` | Override OpenCode Zen base URL | | `OPENCODE_GO_API_KEY` | OpenCode Go API key — PATH`(install via`hermes tools`). | :::note Honcho tools (`honcho_profile`,` honcho_search`,` honcho_context`,` honcho_reasoning`,` honcho_conclude`) are no longer built-in. They are available via the Honcho memory provider plugin at` plugins/memory/honcho/`. See [Memory Providers](../user-guide/features/memory-providers.md) for installation and usage. ::: ##` image_gen`toolset | Tool | Description | Requires environment | |------|-------------|----------------------| |`image_generate`| Generate high-quality images from text prompts using FAL.ai. The underlying model is user-configured (default: FLUX 2 Klein 9B, sub-1s generation) and is not selectable by the agent. Returns a single image URL. Display it using… | FAL_KEY | ##`kanban `toolset Registered when the agent is either (a) spawned by the kanban dispatcher (`HERMES_KANBAN_TASK`env set) or (b) running in a profile that explicitly enables the`kanban`toolset. Task-scoped workers use lifecycle tools for their assigned task; orchestrator profiles additionally get board-routing tools like`kanban_list`and`kanban_unblock`. See [Kanban Multi-Agent](/user-guide/features/kanban) for the full workflow. | Tool | Description | Requires environment | |------|-------------|----------------------| |` kanban_show`| Show the active kanban task assigned to this worker (title, description, comments, dependencies). |`HERMES_KANBAN_TASK`or`kanban`toolset | |`kanban_list`| List board tasks with filters. Orchestrator-only; hidden from dispatcher-spawned task workers. | profile with`kanban`toolset | |`kanban_complete`| Mark the current task done with a structured handoff payload (results, artifacts, follow-ups). |`HERMES_KANBAN_TASK`or`kanban`toolset | |`kanban_block`| Block the current task on a question for the user — the dispatcher pauses, surfaces the question, and resumes once a human replies. |`HERMES_KANBAN_TASK`or`kanban`toolset | |`kanban_heartbeat`| Send a progress heartbeat during a long-running operation so the dispatcher knows the worker is still alive. |`HERMES_KANBAN_TASK`or`kanban`toolset | |`kanban_comment`| Add a comment to the task thread without changing its state — useful for surfacing intermediate findings. |`HERMES_KANBAN_TASK`or`kanban`toolset | |`kanban_create`| Fan out child tasks from the current task. Used by orchestrators and follow-up-spawning workers. |`HERMES_KANBAN_TASK`or`kanban`toolset | |`kanban_link`| Link tasks with a parent → child dependency edge. |`HERMES_KANBAN_TASK`or`kanban`toolset | |`kanban_unblock`| Return a blocked task to`ready`. Orchestrator-only; hidden from dispatcher-spawned task workers. | profile with` kanban`toolset | ##`memory`toolset | Tool | Description | Requires environment | |------|-------------|----------------------| |`memory`| Save important information to persistent memory that survives across sessions. Your memory appears in your system prompt at session start -- it's how you remember things about the user and your environment between conversations. WHEN TO SA… | — | ##`messaging`toolset | Tool | Description | Requires environment | |------|-------------|----------------------| |`send_message`| Send a message to a connected messaging platform, or list available targets. IMPORTANT: When the user asks to send to a specific channel or person (not just a bare platform name), call send_message(action='list') FIRST to see available tar… | — | ##`moa`toolset | Tool | Description | Requires environment | |------|-------------|----------------------| |`mixture_of_agents`| Route a hard problem through multiple frontier LLMs collaboratively. Makes 5 API calls (4 reference models + 1 aggregator) with maximum reasoning effort — use sparingly for genuinely difficult problems. Best for: complex math, advanced alg… | OPENROUTER_API_KEY | ##`session_search`toolset | Tool | Description | Requires environment | |------|-------------|----------------------| |`session_search`| Search past sessions stored in the local session DB, or scroll inside one. FTS5-backed retrieval; returns actual messages from the DB (no LLM calls). Three shapes: discovery (pass`query`), scroll (pass` session_id`+`around_message_id`), browse (no args). | — | ##` skills`toolset | Tool | Description | Requires environment | |------|-------------|----------------------| |`skill_manage`| Manage skills (create, update, delete). Skills are your procedural memory — reusable approaches for recurring task types. New skills go to ~/.hermes/skills/; existing skills can be modified wherever they live. Actions: create (full SKILL.m… | — | |`skill_view`| Skills allow for loading information about specific tasks and workflows, as well as scripts and templates. Load a skill's full content or access its linked files (references, templates, scripts). First call returns SKILL.md content plus a… | — | |`skills_list`| List available skills (name + description). Use skill_view(name) to load full content. | — | ##`terminal`toolset | Tool | Description | Requires environment | |------|-------------|----------------------| |`process`| Manage background processes started with terminal(background=true). Actions: 'list' (show all), 'poll' (check status + new output), 'log' (full output with pagination), 'wait' (block until done or timeout), 'kill' (terminate), 'write' (sen… | — | |`terminal`| Execute shell commands on a Linux environment. Filesystem persists between calls. Set`background=true`for long-running servers. Set`notify_on_complete=true`(with`background=true`) to get an automatic notification when the process finishes — no polling needed. Do NOT use cat/head/tail — use read_file. Do NOT use grep/rg/find — use search_files. | — | ##` todo`toolset | Tool | Description | Requires environment | |------|-------------|----------------------| |`todo`| Manage your task list for the current session. Use for complex tasks with 3+ steps or when the user provides multiple tasks. Call with no parameters to read the current list. Writing: - Provide 'todos' array to create/update items - merge=… | — | ##`vision`toolset | Tool | Description | Requires environment | |------|-------------|----------------------| |`vision_analyze`| Analyze images using AI vision. On vision-capable main models, returns the raw image pixels as a multimodal tool result so the model sees them natively on its next turn. On text-only main models, falls back to an auxiliary vision model that describes the image and returns the description as text. Tool signature is identical either way. | — | ##`video`toolset Opt-in toolset (not loaded in the default`hermes-cli`set). Add via`–toolsets video`or include`video`in your`toolsets:`config. | Tool | Description | Requires environment | |------|-------------|----------------------| |`video_analyze`| Analyze video content from a URL or file path — captions, scene breakdowns, key timestamps, and visual descriptions. | — | ##`video_gen`toolset Opt-in toolset (not loaded in the default`hermes-cli`set). Add via`–toolsets video_gen`or enable it in`hermes tools`→ Video Generation, which also walks you through picking a backend. Backends ship as plugins under`plugins/video_gen//`: - xAI Grok-Imagine — text-to-video and image-to-video (SuperGrok OAuth or` XAI_API_KEY`). - FAL.ai — Veo 3.1, Pixverse v6, Kling O3 (requires` FAL_KEY`). The single` video_generate`tool covers both modalities — pass`image_urlto animate a still, omit it to generate from text alone. The active backend auto-routes to the right endpoint. The tool's description is rebuilt at session start to reflect the active backend's actual capabilities (modalities, aspect ratios, resolutions, duration range, max reference images, audio support). See [Video Generation Provider Plugins](/developer-guide/video-gen-provider-plugin) for backend authoring. | Tool | Description | Requires environment | |------|-------------|----------------------| |video_generate`| Generate a video from a text prompt (text-to-video) or animate a still image (image-to-video) using the user's configured video generation backend. Pass`image_url`to animate that image; omit it to generate from text alone. The backend auto-routes to the right endpoint. Returns either an HTTP URL or an absolute file path in the`video`field. | Active`video_gen`plugin + its credential (e.g.`XAI_API_KEY`,` FAL_KEY`) | ##` web`toolset | Tool | Description | Requires environment | |------|-------------|----------------------| |`web_search`| Search the web for information. Returns up to 5 results by default with titles, URLs, and descriptions. Accepts an optional`limit`(1-100, default 5). The query is passed through to the configured backend, so operators such as`site:domain`,` filetype:pdf`,` intitle:word`,` -term`, and` “exact phrase”`may work when the backend supports them. | EXA_API_KEY or PARALLEL_API_KEY or FIRECRAWL_API_KEY or TAVILY_API_KEY | |`web_extract`| Extract content from web page URLs. Returns page content in markdown format. Also works with PDF URLs — pass the PDF link directly and it converts to markdown text. Pages under 5000 chars return full markdown; larger pages are LLM-summarized. | EXA_API_KEY or PARALLEL_API_KEY or FIRECRAWL_API_KEY or TAVILY_API_KEY | ##`x_search`toolset | Tool | Description | Requires environment | |------|-------------|----------------------| |`x_search`| Search X (Twitter) posts, profiles, and threads using xAI's built-in`x_search`Responses tool. Use this for current discussion, reactions, or claims on X rather than general web pages. Off by default — opt in via`hermes tools`→ 🐦 X (Twitter) Search. Schema is only registered when xAI credentials are configured (check_fn-gated). | XAI_API_KEY or xAI Grok OAuth (SuperGrok / Premium+) login | ##`tts`toolset | Tool | Description | Requires environment | |------|-------------|----------------------| |`text_to_speech`| Convert text to speech audio. Returns a MEDIA: path that the platform delivers as a voice message. On Telegram it plays as a voice bubble, on Discord/WhatsApp as an audio attachment. In CLI mode, saves to ~/voice-memos/. Voice and provider… | — | ##`discord`toolset Registered on the`hermes-discord`platform toolset (gateway only). Uses the same bot token as the messaging adapter. | Tool | Description | Requires environment | |------|-------------|----------------------| |`discord`| Read and participate in a Discord server. Actions include`search_members`,` fetch_messages`,` send_message`,` react`,` fetch_channel`,` list_channels`, and more. |` DISCORD_BOT_TOKEN`| ##`discord_admin`toolset Registered on the`hermes-discord`platform toolset. Moderation actions require the bot to hold the matching Discord permissions. | Tool | Description | Requires environment | |------|-------------|----------------------| |`discord_admin`| Manage a Discord server via the REST API: list guilds/channels/roles, create/edit/delete channels, manage role grants, timeouts, kicks, and bans. |`DISCORD_BOT_TOKEN`+ bot permissions | ##`spotify`toolset Registered by the bundled`spotify`plugin. Requires an OAuth token — run`hermes spotify setup`once to authorize. | Tool | Description | Requires environment | |------|-------------|----------------------| |`spotify_playback`| Control Spotify playback, inspect the active playback state, or fetch recently played tracks. | Spotify OAuth | |`spotify_devices`| List Spotify Connect devices or transfer playback to a different device. | Spotify OAuth | |`spotify_queue`| Inspect the user's Spotify queue or add an item to it. | Spotify OAuth | |`spotify_search`| Search the Spotify catalog for tracks, albums, artists, playlists, shows, or episodes. | Spotify OAuth | |`spotify_playlists`| List, inspect, create, update, and modify Spotify playlists. | Spotify OAuth | |`spotify_albums`| Fetch Spotify album metadata or album tracks. | Spotify OAuth | |`spotify_library`| List, save, or remove the user's saved Spotify tracks or albums. | Spotify OAuth | ##`hermes-yuanbao`toolset Registered only on the`hermes-yuanbao`platform toolset. Yuanbao is Tencent's chat app; these tools drive its DM/group/sticker APIs. | Tool | Description | Requires environment | |------|-------------|----------------------| |`yb_query_group_info`| Query basic info about a group (called "派/Pai" in the app): name, owner, member count. | Yuanbao credentials | |`yb_query_group_members`| Query members of a group (for`@`-mentions, finding a user by name, listing bots). | Yuanbao credentials | |` yb_send_dm`| Send a private/direct message to a user in a group, with optional media files. | Yuanbao credentials | |`yb_search_sticker`| Search the built-in Yuanbao sticker (TIM face) catalogue by keyword. | Yuanbao credentials | |`yb_send_sticker| Send a built-in sticker to the current Yuanbao chat. | Yuanbao credentials | ---  # Toolsets Reference # Toolsets Reference Toolsets are named bundles of tools that control what the agent can do. They're the primary mechanism for configuring tool availability per platform, per session, or per task. ## How Toolsets Work Every tool belongs to exactly one toolset. When you enable a toolset, all tools in that bundle become available to the agent. Toolsets come in three kinds: - Core — A single logical group of related tools (e.g.,file`bundles`read_file`,` write_file`,` patch`,` search_files`) - Composite — Combines multiple core toolsets for a common scenario (e.g.,` debugging`bundles file, terminal, and web tools) - Platform — A complete tool configuration for a specific deployment context (e.g.,`hermes-cliis the default for interactive CLI sessions) ## Configuring Toolsets ### Per-session (CLI) ```bash hermes chat --toolsets web,file,terminal hermes chat --toolsets debugging # composite — expands to file + terminal + web hermes chat --toolsets all # everything ``` ### Per-platform (config.yaml) ```yaml toolsets: - hermes-cli # default for CLI # - hermes-telegram # override for Telegram gateway ``` ### Interactive management ```bash hermes tools # curses UI to enable/disable per platform ``` Or in-session: ``` /tools list /tools disable browser /tools enable homeassistant ``` ## Core Toolsets | Toolset | Tools | Purpose | |---------|-------|---------| |browser`|`browser_back`,` browser_cdp`,` browser_click`,` browser_console`,` browser_dialog`,` browser_get_images`,` browser_navigate`,` browser_press`,` browser_scroll`,` browser_snapshot`,` browser_type`,` browser_vision`,` web_search`| Core browser automation. Includes`web_search`as a fallback for quick lookups.`browser_cdp`and`browser_dialog`are gated at runtime — registered only when a CDP endpoint is reachable at session start (via`/browser connect`,` browser.cdp_url`config, Browserbase, or Camofox).`browser_dialog`works together with the`pending_dialogs`and`frame_tree`fields that`browser_snapshot`adds when a CDP supervisor is attached. | |`clarify`|`clarify`| Ask the user a question when the agent needs clarification. | |`code_execution`|`execute_code`| Run Python scripts that call Hermes tools programmatically. | |`cronjob`|`cronjob`| Schedule and manage recurring tasks. | |`debugging `| composite (`file`+`terminal`+`web`) | Debug bundle — file, process/terminal, web extract/search. | |` delegation`|`delegate_task`| Spawn isolated subagent instances for parallel work. | |`discord`|`discord`| Core Discord text/embed/DM actions (gateway-only). Active on the`hermes-discord`toolset. | |`discord_admin`|`discord_admin`| Discord moderation (bans, role changes, channel management). Active on the`hermes-discord`toolset; requires the bot to hold the relevant Discord permissions. | |`feishu_doc`|`feishu_doc_read`| Read Feishu/Lark document content. Used by the Feishu document-comment intelligent-reply handler. | |`feishu_drive`|`feishu_drive_add_comment`,` feishu_drive_list_comments`,` feishu_drive_list_comment_replies`,` feishu_drive_reply_comment`| Feishu/Lark drive comment operations. Scoped to the comment agent; not exposed on`hermes-cli`or other messaging toolsets. | |`file`|`patch`,` read_file`,` search_files`,` write_file`| File reading, writing, searching, and editing. | |`homeassistant`|`ha_call_service`,` ha_get_state`,` ha_list_entities`,` ha_list_services`| Smart home control via Home Assistant. Only available when`HASS_TOKEN`is set. | |`computer_use`|`computer_use`| Background macOS desktop control via cua-driver — does not steal cursor/focus. Works with any tool-capable model. macOS only; requires`cua-driver`on`HOME/.local/bin:$PATH“manually. ::: #### Python version too old Cause: Hermes requires Python 3.11 or newer. Solution: ```bash 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. #### Terminal commands saynode: 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: ```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.shdirectly) rather than the whole rc file. To disable the auto-source behaviour (strict login-shell semantics only): ```yaml terminal: auto_source_bashrc: false ``` ####uv: command not found`Cause: The`uvpackage manager isn't installed or not in PATH. Solution: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh source ~/.bashrc ``` #### Permission denied errors during install Cause: Insufficient permissions to write to the install directory. Solution: ```bash # 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 ``` --- ### Provider & Model Issues ####/model`only shows one provider / can't switch providers Cause:`/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 modelfrom your terminal to add new providers: ```bash # 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 viahermes 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 `(inside session) | | Switch to different configured provider |`/model provider:model(inside session) | ::: #### API key not working Cause: Key is missing, expired, incorrectly set, or for the wrong provider. Solution: ```bash # 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/.envfor conflicting entries. ::: #### Model not available / model not found Cause: The model identifier is incorrect or not available on your provider. Solution: ```bash # 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 ``` #### Rate limiting (429 errors) Cause: You've exceeded your provider's rate limits. Solution: Wait a moment and retry. For sustained usage, consider: - Upgrading your provider plan - Switching to a different model or provider - Usinghermes chat –provider to route to a different backend #### Context length exceeded Cause: The conversation has grown too long for the model's context window, or Hermes detected the wrong context length for your model. Solution: ```bash # 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` /usageduring a session. To fix context detection, set it explicitly: ```yaml # 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: ```yaml custom_providers: - name: "My Server" base_url: "http://localhost:11434/v1" models: qwen3.5:27b: context_length: 64000 ``` See [Context Length Detection](../integrations/providers.md#context-length-detection) for how auto-detection works and all override options. --- ### Terminal Issues #### Command blocked as dangerous 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: - Ask the agent to use a safer alternative - See the full list of dangerous patterns in the [Security docs](../user-guide/security.md) :::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 gateway Cause: The messaging gateway runs without an interactive terminal, so`sudo`cannot prompt for a password. Solution: - Avoid`sudo`in messaging — ask the agent to find alternatives - If you must use`sudo`, configure passwordless sudo for specific commands in` /etc/sudoers`- Or switch to the terminal interface for administrative tasks:`hermes chat#### Docker backend not connecting Cause: Docker daemon isn't running or the user lacks permissions. Solution: ```bash # 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 ``` --- ### Messaging Issues #### Bot not responding to messages Cause: The bot isn't running, isn't authorized, or your user isn't in the allowlist. Solution: ```bash # 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 ``` #### Messages not delivering Cause: Network issues, bot token expired, or platform webhook misconfiguration. Solution: - Verify your bot token is valid withhermes gateway setup`- Check gateway logs:`cat /.hermes/logs/gateway.log | tail -50`- For webhook-based platforms (Slack, WhatsApp), ensure your server is publicly accessible #### Allowlist confusion — who can talk to the bot? Cause: 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.yamlunder your gateway's settings. See the [Messaging docs](../user-guide/messaging/index.md). #### Gateway won't start Cause: Missing dependencies, port conflicts, or misconfigured tokens. Solution: ```bash # 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 ``` #### WSL: Gateway keeps disconnecting orhermes gateway startfails Cause: 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: ```bash # 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: 1. Open/etc/wsl.conf(create it if it doesn't exist) 2. Add: ```ini [boot] systemd=true ``` 3. From PowerShell:wsl –shutdown`4. Reopen your WSL terminal 5. Verify:`systemctl 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: 1. Create a task that runs`wsl -d Ubuntu – bash -lc ‘hermes gateway run’ `2. Set it to trigger on user logon ::: #### macOS: Node.js / ffmpeg / other tools not found by gateway 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: ```bash 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: ```bash /usr/libexec/PlistBuddy -c "Print :EnvironmentVariables:PATH" \ ~/Library/LaunchAgents/ai.hermes.gateway.plist ``` --- ### Performance Issues #### Slow responses Cause: Large model, distant API server, or heavy system prompt with many tools. Solution: - Try a faster/smaller model: hermes chat –model openrouter/meta-llama/llama-3.1-8b-instruct`- Reduce active toolsets:`hermes chat -t “terminal”- Check your network latency to the provider - For local models, ensure you have enough GPU VRAM #### High token usage Cause: Long conversations, verbose system prompts, or many tool calls accumulating context. Solution: ```bash # Compress the conversation to reduce tokens /compress # Check session token usage /usage ``` :::tip Use/compressregularly during long sessions. It summarizes the conversation history and reduces token usage significantly while preserving context. ::: #### Session getting too long Cause: Extended conversations accumulate messages and tool outputs, approaching context limits. Solution: ```bash # 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 ``` --- ### MCP Issues #### MCP server not connecting Cause: Server binary not found, wrong command path, or missing runtime. Solution: ```bash # 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.yamlMCP configuration: ```yaml mcp_servers: filesystem: command: "npx" args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"] ``` #### Tools not showing up from MCP server 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: - Check gateway/agent logs for MCP connection errors - Ensure the server responds to thetools/list`RPC method - Review any`tools.include`,` tools.exclude`,` tools.resources`,` tools.prompts`, or` enabled`settings under that server - Remember that resource/prompt utility tools are only registered when the session actually supports those capabilities - Use`/reload-mcpafter changing config ```bash # 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: - [MCP (Model Context Protocol)](/user-guide/features/mcp) - [Use MCP with Hermes](/guides/use-mcp-with-hermes) - [MCP Config Reference](/reference/mcp-config-reference) #### MCP timeout errors Cause: The MCP server is taking too long to respond, or it crashed during execution. Solution: - Increase the timeout in your MCP server config if supported - Check if the MCP server process is still running - For remote HTTP MCP servers, check network connectivity :::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 ### How do profiles differ from just setting HERMES_HOME? Profiles are a managed layer on top ofHERMES_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. ### Can two profiles share the same bot token? 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](https://t.me/BotFather) to make additional bots. ### Do profiles share memory or sessions? 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. ### What happens when I run`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. ### How many profiles can I run? 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. --- ## Workflows & Patterns ### Using different models for different tasks (multi-model workflows) 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: ```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` /modelin the CLI: ```bash /model google/gemini-3-flash-preview # switch for this session # ... write your content ... /model openai/gpt-5.4 # switch back ``` See [Subagent Delegation](../user-guide/features/delegation.md) for more on how delegation works. ### Running multiple agents on one WhatsApp number (per-chat binding) 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: 1. Use a single profile with personality switching. Create differentAGENTS.md`context files or use the`/personalitycommand to change behavior per chat. The agent sees which chat it's in and can adapt. 2. 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. 3. 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. 4. 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](../user-guide/profiles.md) and [WhatsApp setup](../user-guide/messaging/whatsapp.md) for more details. ### Controlling what shows up in Telegram (hiding logs and reasoning) Scenario: You see gateway exec logs, Hermes reasoning, and tool call details in Telegram instead of just the final output. Solution: Thedisplay.tool_progress`setting in`config.yaml controls how much tool activity is shown: ```yaml 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` /verbosecommand (if enabled): ```yaml display: tool_progress_command: true # enables /verbose in the gateway ``` ### Managing skills on Telegram (slash command limit) 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, buthermes skills config`settings don't seem to take effect. Solution: Use`hermes skills config`to disable skills per-platform. This writes to`config.yaml: ```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 restartor 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. ::: ### Shared thread sessions (multiple users, one conversation) 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: 1. 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. 2. 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. 3. 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. ### Exporting Hermes to another machine 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: 1. Install Hermes Agent on the new machine: ```bash curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash ``` 2. On the source machine, create a full backup: ```bash 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-.zip. 3. Copy the zip to the new machine and import it: ```bash # On the source machine scp ~/hermes-backup-<timestamp>.zip newmachine:~/ # On the new machine hermes import ~/hermes-backup-<timestamp>.zip ``` 4. On the new machine, run hermes setupto verify API keys and provider config are working. ### Moving a single profile to another machine Scenario: You want to move or share one specific profile — not your full installation. ```bash # 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: ```bash rsync -av --exclude='hermes-agent' ~/.hermes/ newmachine:~/.hermes/ ``` :::tiphermes 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`. ::: ### Permission denied when reloading shell after install 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: ```bash # 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: ```bash echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc ``` ### Error 400 on first agent run 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: ```bash # 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. --- ## Still Stuck? If your issue isn't covered here: 1. Search existing issues: [GitHub Issues](https://github.com/NousResearch/hermes-agent/issues) 2. Ask the community: [Nous Research Discord](https://discord.gg/nousresearch) 3. File a bug report: Include your OS, Python version (python3 –version`), Hermes version (`hermes –version`), and the full error message ---  # ACP Internals # ACP Internals The ACP adapter wraps Hermes' synchronous` AIAgent`in an async JSON-RPC stdio server. Key implementation files: -`acp_adapter/entry.py`-`acp_adapter/server.py`-`acp_adapter/session.py`-`acp_adapter/events.py`-`acp_adapter/permissions.py`-`acp_adapter/tools.py`-`acp_adapter/auth.py`-`acp_registry/agent.json## Boot flow ```text hermes acp / hermes-acp / python -m acp_adapter -> acp_adapter.entry.main() -> parse --version / --check / --setup before server startup -> load ~/.hermes/.env -> configure stderr logging -> construct HermesACPAgent -> acp.run_agent(agent, use_unstable_protocol=True) ``` The Zed ACP Registry path launches the same adapter throughuvx –from ‘hermes-agent[acp]==’ hermes-acp`, pointed at the` hermes-agent`PyPI release. Stdout is reserved for ACP JSON-RPC transport. Human-readable logs go to stderr. ## Major components ###`HermesACPAgent acp_adapter/server.py`implements the ACP agent protocol. Responsibilities: - initialize / authenticate - new/load/resume/fork/list/cancel session methods - prompt execution - session model switching - wiring sync AIAgent callbacks into ACP async notifications ###`SessionManager acp_adapter/session.py`tracks live ACP sessions. Each session stores: -`session_id`-`agent`-`cwd`-`model`-`history`-`cancel_event`The manager is thread-safe and supports: - create - get - remove - fork - list - cleanup - cwd updates ### Event bridge`acp_adapter/events.py`converts AIAgent callbacks into ACP`session_update`events. Bridged callbacks: -`tool_progress_callback`-`thinking_callback`(currently set to`None`in the ACP bridge — reasoning is forwarded through`step_callback`instead) -`step_callback`Because`AIAgentruns in a worker thread while ACP I/O lives on the main event loop, the bridge uses: ```python asyncio.run_coroutine_threadsafe(...) ``` ### Permission bridgeacp_adapter/permissions.py`adapts dangerous terminal approval prompts into ACP permission requests. Mapping: -`allow_once`-> Hermes`once`-`allow_always`-> Hermes`always`- reject options -> Hermes`deny`Timeouts and bridge failures deny by default. ### Tool rendering helpers`acp_adapter/tools.py`maps Hermes tools to ACP tool kinds and builds editor-facing content. Examples: -`patch`/`write_file`-> file diffs -`terminal`-> shell command text -`read_file`/`search_files-> text previews - large results -> truncated text blocks for UI safety ## Session lifecycle ```text new_session(cwd) -> create SessionState -> create AIAgent(platform="acp", enabled_toolsets=["hermes-acp"]) -> bind task_id/session_id to cwd override prompt(..., session_id) -> extract text from ACP content blocks -> reset cancel event -> install callbacks + approval bridge -> run AIAgent in ThreadPoolExecutor -> update session history -> emit final agent message chunk ``` ### Cancelationcancel(session_id)`: - sets the session cancel event - calls` agent.interrupt()`when available - causes the prompt response to return`stop_reason=“cancelled”`### Forking`fork_session()`deep-copies message history into a new live session, preserving conversation state while giving the fork its own session ID and cwd. ## Provider/auth behavior ACP does not implement its own auth store. Instead it reuses Hermes' runtime resolver: -`acp_adapter/auth.py`-`hermes_cli/runtime_provider.py `So ACP advertises and uses the currently configured Hermes provider/credentials. It also always advertises a terminal setup auth method (`hermes-setup`, args` –setup) so first-run registry clients can open Hermes' interactive model/provider configuration before starting a normal ACP session. ## Working directory binding ACP sessions carry an editor cwd. The session manager binds that cwd to the ACP session ID via task-scoped terminal/file overrides, so file and terminal tools operate relative to the editor workspace. ## Duplicate same-name tool calls The event bridge tracks tool IDs FIFO per tool name, not just one ID per name. This is important for: - parallel same-name calls - repeated same-name calls in one step Without FIFO queues, completion events would attach to the wrong tool invocation. ## Approval callback restoration ACP temporarily installs an approval callback on the terminal tool during prompt execution, then restores the previous callback afterward. This avoids leaving ACP session-specific approval handlers installed globally forever. ## Current limitations - ACP sessions are persisted to the shared /.hermes/state.db`(SessionDB) and transparently restored across process restarts; they appear in`session_search`- non-text prompt blocks are currently ignored for request text extraction - editor-specific UX varies by ACP client implementation ## Related files -`tests/acp/`— ACP test suite -`toolsets.py`—`hermes-acp`toolset definition -`hermes_cli/main.py`—`hermes acp`CLI subcommand -`pyproject.toml`—`[acp]`optional dependency +`hermes-acp `script ---  # Browser CDP Supervisor # Browser CDP Supervisor The CDP supervisor closes two long-standing gaps in Hermes' browser tooling: 1. Native JS dialogs (`alert`/`confirm`/`prompt`/`beforeunload`) block the page's JS thread. Without supervision, the agent has no way to know a dialog is open — subsequent tool calls hang or throw opaque errors. 2. Cross-origin iframes (OOPIFs) are invisible to top-level` Runtime.evaluate`. The agent can see iframe nodes in the DOM snapshot but can't click, type, or eval inside them without a CDP session attached to the child target. The supervisor solves both by holding a persistent WebSocket to the backend's CDP endpoint per browser task, surfacing pending dialogs and frame structure into` browser_snapshot`, and exposing a` browser_dialog`tool for explicit responses. ## Backend support | Backend | Dialog detect | Dialog respond | Frame tree | OOPIF`Runtime.evaluate`via`browser_cdp(frame_id=…) `| |---|---|---|---|---| | Local Chrome (`–remote-debugging-port`) /` /browser connect`| ✓ | ✓ full workflow | ✓ | ✓ | | Browserbase | ✓ (via bridge) | ✓ full workflow (via bridge) | ✓ | ✓ | | Camofox | ✗ no CDP (REST-only) | ✗ | partial via DOM snapshot | ✗ | Browserbase quirk. Browserbase's CDP proxy uses Playwright internally and auto-dismisses native dialogs within ~10ms, so`Page.handleJavaScriptDialog`can't keep up. The supervisor injects a bridge script via`Page.addScriptToEvaluateOnNewDocument`that overrides`window.alert`/`confirm`/`prompt `with a synchronous XHR to a magic host (`hermes-dialog-bridge.invalid`).` Fetch.enable`intercepts those XHRs before they touch the network — the dialog becomes a`Fetch.requestPaused`event the supervisor captures, and`respond_to_dialog`fulfills via`Fetch.fulfillRequest`with a JSON body the injected script decodes. From the page's perspective,`prompt()`still returns the agent-supplied string. From the agent's perspective, it's the same`browser_dialog(action=…)`API either way. Camofox is unsupported — no CDP surface, REST-only. ## Architecture ### CDPSupervisor One`asyncio.Task`running in a background daemon thread per Hermes`task_id`. Holds a persistent WebSocket to the backend's CDP endpoint. Maintains: - Dialog queue —` List[PendingDialog]`with`{id, type, message, default_prompt, session_id, opened_at}`- Frame tree —`Dict[frame_id, FrameInfo]`with parent relationships, URL, origin, whether cross-origin child session - Session map —`Dict[session_id, SessionInfo]`so interaction tools can route to the right attached session for OOPIF operations - Recent console errors — ring buffer of the last 50 for diagnostics Subscribes on attach: -`Page.enable`—`javascriptDialogOpening`,` frameAttached`,` frameNavigated`,` frameDetached`-`Runtime.enable`—`executionContextCreated`,` consoleAPICalled`,` exceptionThrown`-`Target.setAutoAttach {autoAttach: true, flatten: true}`— surfaces child OOPIF targets; supervisor enables`Page`+`Runtime`on each Thread-safe state access via a snapshot lock; tool handlers (sync) read the frozen snapshot without awaiting. ### Lifecycle - Start:`SupervisorRegistry.get_or_start(task_id, cdp_url)`— called by`browser_navigate`, Browserbase session create,` /browser connect`. Idempotent. - Stop: session teardown or` /browser disconnect`. Cancels the asyncio task, closes the WebSocket, discards state. - Rebind: if the CDP URL changes (user reconnects to a new Chrome), the old supervisor is stopped and a fresh one started — state is never reused across endpoints. ### Dialog policy Configurable via` config.yaml`under`browser.dialog_policy`: - `must_respond` (default) — capture, surface in` browser_snapshot`, wait for explicit` browser_dialog(action=…)`call. After a 300s safety timeout with no response, auto-dismiss and log. Prevents a buggy agent from stalling forever. -`auto_dismiss`— record and dismiss immediately; agent sees it after the fact via`browser_state`inside`browser_snapshot`. -` auto_accept`— record and accept (useful for`beforeunload`where the workflow wants to navigate away cleanly). Policy is per-task; no per-dialog overrides. ## Agent surface ###`browser_dialogtool ``` browser_dialog(action, prompt_text=None, dialog_id=None) ``` -action=“accept”`/`“dismiss”`→ responds to the specified or sole pending dialog (required) -`prompt_text=…`→ text to supply to a`prompt()`dialog -`dialog_id=…`→ disambiguate when multiple dialogs are queued (rare) Tool is response-only. The agent reads pending dialogs from`browser_snapshot`output before calling. ###`browser_snapshot extension Adds three optional fields to the existing snapshot output when a supervisor is attached: ```json { "pending_dialogs": [ {"id": "d-1", "type": "alert", "message": "Hello", "opened_at": 1650000000.0} ], "recent_dialogs": [ {"id": "d-1", "type": "alert", "message": "...", "opened_at": 1650000000.0, "closed_at": 1650000000.1, "closed_by": "remote"} ], "frame_tree": { "top": {"frame_id": "FRAME_A", "url": "https://example.com/", "origin": "https://example.com"}, "children": [ {"frame_id": "FRAME_B", "url": "about:srcdoc", "is_oopif": false}, {"frame_id": "FRAME_C", "url": "https://ads.example.net/", "is_oopif": true, "session_id": "SID_C"} ], "truncated": false } } ``` - pending_dialogs` — dialogs currently blocking the page's JS thread. The agent must call` browser_dialog(action=…) `to respond. Empty on Browserbase because their CDP proxy auto-dismisses within ~10ms. - `recent_dialogs` — ring buffer of up to 20 recently-closed dialogs with a` closed_by`tag:`“agent”`(we responded),`“auto_policy”`(local auto_dismiss/auto_accept),`“watchdog”`(must_respond timeout hit), or`“remote” `(browser/backend closed it on us, e.g. Browserbase). This is how agents on Browserbase still get visibility into what happened. - `frame_tree` — frame structure including cross-origin (OOPIF) children. Capped at 30 entries + OOPIF depth 2 to bound snapshot size on ad-heavy pages.` truncated: true`surfaces when limits were hit; agents needing the full tree can use`browser_cdp`with`Page.getFrameTree`. No new tool schema surface for any of these — the agent reads the snapshot it already requests. ### Availability gating Both surfaces gate on` _browser_cdp_check`(supervisor can only run when a CDP endpoint is reachable). On Camofox / no-backend sessions, the dialog tool is hidden and the snapshot omits the new fields — no schema bloat. ## Cross-origin iframe interaction`browser_cdp(frame_id=…)`routes CDP calls (notably`Runtime.evaluate`) through the supervisor's already-connected WebSocket using the OOPIF's child` sessionId`. Agents pick frame_ids out of` browser_snapshot.frame_tree.children[]`where`is_oopif=true`and pass them to`browser_cdp`. For same-origin iframes (no dedicated CDP session), the agent uses` contentWindow`/`contentDocument`from a top-level`Runtime.evaluate`instead — the supervisor surfaces an error pointing at that fallback when`frame_id`belongs to a non-OOPIF. On Browserbase, this is the only reliable path for iframe interaction — stateless CDP connections (opened per`browser_cdp`call) hit signed-URL expiry, while the supervisor's long-lived connection keeps a valid session. ## File layout -`tools/browser_supervisor.py`—`CDPSupervisor`,` SupervisorRegistry`,` PendingDialog`,` FrameInfo`-`tools/browser_dialog_tool.py`—`browser_dialog`tool handler -`tools/browser_tool.py`—`browser_navigate`start-hook,`browser_snapshot`merge,`/browser connect`reattach,`_cleanup_browser_session`teardown -`toolsets.py`— registers`browser_dialog`in`browser`,` hermes-acp`,` hermes-api-server`, and core toolsets (gated on CDP reachability) -` hermes_cli/config.py`—`browser.dialog_policy`and`browser.dialog_timeout_s`defaults ## Non-goals - Detection/interaction for Camofox (upstream gap; tracked separately) - Streaming dialog/frame events live to the user (would require gateway hooks) - Persisting dialog history across sessions (in-memory only) - Per-iframe dialog policies (agent can express this via`dialog_id`) - Replacing` browser_cdp `— it stays as the escape hatch for the long tail (cookies, viewport, network throttling) ## Testing Unit tests (`tests/tools/test_browser_supervisor.py`) use an asyncio mock CDP server that speaks enough of the protocol to exercise all state transitions: attach, enable, navigate, dialog fire, dialog dismiss, frame attach/detach, child target attach, session teardown. Real-backend E2E (Browserbase + local Chromium-family browser) is manual — exercise via` /browser connect`to a live Chromium-family browser and run the dialog/frame test cases described above. ---  # Context Engine Plugins # Building a Context Engine Plugin Context engine plugins replace the built-in`ContextCompressor`with an alternative strategy for managing conversation context. For example, a Lossless Context Management (LCM) engine that builds a knowledge DAG instead of lossy summarization. ## How it works The agent's context management is built on the`ContextEngine `ABC (`agent/context_engine.py`). The built-in` ContextCompressoris the default implementation. Plugin engines must implement the same interface. Only one context engine can be active at a time. Selection is config-driven: ```yaml # config.yaml context: engine: "compressor" # default built-in engine: "lcm" # activates a plugin engine named "lcm" ``` Plugin engines are never auto-activated — the user must explicitly setcontext.engine`to the plugin's name. ## Directory structure Each context engine lives in`plugins/context_engine//: ``` plugins/context_engine/lcm/ ├── init.py # exports the ContextEngine subclass ├── plugin.yaml # metadata (name, description, version) └── ... # any other modules your engine needs ``` ## The ContextEngine ABC Your engine must implement these required methods: ```python from agent.context_engine import ContextEngine class LCMEngine(ContextEngine): @property def name(self) -> str: """Short identifier, e.g. 'lcm'. Must match config.yaml value.""" return "lcm" def update_from_response(self, usage: dict) -> None: """Called after every LLM call with the usage dict. Update self.last_prompt_tokens, self.last_completion_tokens, self.last_total_tokens from the response. """ def should_compress(self, prompt_tokens: int = None) -> bool: """Return True if compaction should fire this turn.""" def compress(self, messages: list, current_tokens: int = None, focus_topic: str = None) -> list: """Compact the message list and return a new (possibly shorter) list. The returned list must be a valid OpenAI-format message sequence. ``focus_topic`` is an optional topic string from manual ``/compress <focus>``; engines that support guided compression should prioritise preserving information related to it, others may ignore it. """ ``` ### Class attributes your engine must maintain The agent reads these directly for display and logging: ```python last_prompt_tokens: int = 0 last_completion_tokens: int = 0 last_total_tokens: int = 0 threshold_tokens: int = 0 # when compression triggers context_length: int = 0 # model's full context window compression_count: int = 0 # how many times compress() has run ``` ### Optional methods These have sensible defaults in the ABC. Override as needed: | Method | Default | Override when | |--------|---------|--------------| | on_session_start(session_id, kwargs)`| No-op | You need to load persisted state (DAG, DB) | |`on_session_end(session_id, messages)`| No-op | You need to flush state, close connections | |`on_session_reset()`| Resets token counters | You have per-session state to clear | |`update_model(model, context_length, …)`| Updates context_length + threshold | You need to recalculate budgets on model switch | |`get_tool_schemas()`| Returns`[]`| Your engine provides agent-callable tools (e.g.,`lcm_grep`) | |` handle_tool_call(name, args, kwargs)`| Returns error JSON | You implement tool handlers | |`should_compress_preflight(messages)`| Returns`False`| You can do a cheap pre-API-call estimate | |`get_status()`| Standard token/threshold dict | You have custom metrics to expose | ## Engine tools Context engines can expose tools the agent calls directly. Return schemas from`get_tool_schemas()`and handle calls in`handle_tool_call(): ```python def get_tool_schemas(self): return [{ "name": "lcm_grep", "description": "Search the context knowledge graph", "parameters": { "type": "object", "properties": { "query": {"type": "string", "description": "Search query"} }, "required": ["query"], }, }] def handle_tool_call(self, name, args, kwargs): if name == "lcm_grep": results = self._search_dag(args["query"]) return json.dumps({"results": results}) return json.dumps({"error": f"Unknown tool: {name}"}) ``` Engine tools are injected into the agent's tool list at startup and dispatched automatically — no registry registration needed. ## Registration ### Via directory (recommended) Place your engine in plugins/context_engine//`. The` init.py`must export a`ContextEnginesubclass. The discovery system finds and instantiates it automatically. ### Via general plugin system A general plugin can also register a context engine: ```python def register(ctx): engine = LCMEngine(context_length=200000) ctx.register_context_engine(engine) ``` Only one engine can be registered. A second plugin attempting to register is rejected with a warning. ## Lifecycle ``` 1. Engine instantiated (plugin load or directory discovery) 2. on_session_start() — conversation begins 3. update_from_response() — after each API call 4. should_compress() — checked each turn 5. compress() — called when should_compress() returns True 6. on_session_end() — session boundary (CLI exit, /reset, gateway expiry) ```on_session_reset()`is called on`/new`or`/reset`to clear per-session state without a full shutdown. ## Configuration Users select your engine via`hermes plugins`→ Provider Plugins → Context Engine, or by editing`config.yaml: ```yaml context: engine: "lcm" # must match your engine's name property ``` The compression `config block (`compression.threshold`,` compression.protect_last_n`, etc.) is specific to the built-in` ContextCompressor`. Your engine should define its own config format if needed, reading from` config.yamlduring initialization. ## Testing ```python from agent.context_engine import ContextEngine def test_engine_satisfies_abc(): engine = YourEngine(context_length=200000) assert isinstance(engine, ContextEngine) assert engine.name == "your-name" def test_compress_returns_valid_messages(): engine = YourEngine(context_length=200000) msgs = [{"role": "user", "content": "hello"}] result = engine.compress(msgs) assert isinstance(result, list) assert all("role" in m for m in result) ``` Seetests/agent/test_context_engine.pyfor the full ABC contract test suite. ## See also - [Context Compression and Caching](/developer-guide/context-compression-and-caching) — how the built-in compressor works - [Memory Provider Plugins](/developer-guide/memory-provider-plugin) — analogous single-select plugin system for memory - [Plugins](/user-guide/features/plugins) — general plugin system overview ---  # Cron Internals # Cron Internals The cron subsystem provides scheduled task execution — from simple one-shot delays to recurring cron-expression jobs with skill injection and cross-platform delivery. ## Key Files | File | Purpose | |------|---------| |cron/jobs.py`| Job model, storage, atomic read/write to`jobs.json`| |`cron/scheduler.py`| Scheduler loop — due-job detection, execution, repeat tracking | |`tools/cronjob_tools.py`| Model-facing`cronjob`tool registration and handler | |`gateway/run.py`| Gateway integration — cron ticking in the long-running loop | |`hermes_cli/cron.py`| CLI`hermes cron`subcommands | ## Scheduling Model Four schedule formats are supported: | Format | Example | Behavior | |--------|---------|----------| | Relative delay |`30m`,` 2h`,` 1d`| One-shot, fires after the specified duration | | Interval |`every 2h`,` every 30m`| Recurring, fires at regular intervals | | Cron expression** |`0 9 * * `| Standard 5-field cron syntax (minute, hour, day, month, weekday) | | ISO timestamp |`2025-01-15T09:00:00`| One-shot, fires at the exact time | The model-facing surface is a single`cronjob`tool with action-style operations:`create`,` list`,` update`,` pause`,` resume`,` run`,` remove`. ## Job Storage Jobs are stored in` /.hermes/cron/jobs.jsonwith atomic write semantics (write to temp file, then rename). Each job record contains: ```json { "id": "a1b2c3d4e5f6", "name": "Daily briefing", "prompt": "Summarize today's AI news and funding rounds", "schedule": { "kind": "cron", "expr": "0 9 * ", "display": "0 9 * " }, "skills": ["ai-funding-daily-report"], "deliver": "telegram:-1001234567890", "repeat": { "times": null, "completed": 42 }, "state": "scheduled", "enabled": true, "next_run_at": "2025-01-16T09:00:00Z", "last_run_at": "2025-01-15T09:00:00Z", "last_status": "ok", "created_at": "2025-01-01T00:00:00Z", "model": null, "provider": null, "script": null } ``` ### Job Lifecycle States | State | Meaning | |-------|---------| |scheduled`| Active, will fire at next scheduled time | |`paused`| Suspended — won't fire until resumed | |`completed`| Repeat count exhausted or one-shot that has fired | |`running`| Currently executing (transient state) | ### Backward Compatibility Older jobs may have a single`skill`field instead of the`skills`array. The scheduler normalizes this at load time — single`skill`is promoted to`skills: [skill]. ## Scheduler Runtime ### Tick Cycle The scheduler runs on a periodic tick (default: every 60 seconds): ```text tick() 1. Acquire scheduler lock (prevents overlapping ticks) 2. Load all jobs from jobs.json 3. Filter to due jobs (next_run <= now AND state == "scheduled") 4. For each due job: a. Set state to "running" b. Create fresh AIAgent session (no conversation history) c. Load attached skills in order (injected as user messages) d. Run the job prompt through the agent e. Deliver the response to the configured target f. Update run_count, compute next_run g. If repeat count exhausted → state = "completed" h. Otherwise → state = "scheduled" 5. Write updated jobs back to jobs.json 6. Release scheduler lock ``` ### Gateway Integration In gateway mode, the scheduler runs in a dedicated background thread (start_cron_ticker`in`gateway/run.py`) that calls` scheduler.tick()`every 60 seconds alongside message handling. In CLI mode, cron jobs only fire when`hermes cron`commands are run or during active CLI sessions. ### Fresh Session Isolation Each cron job runs in a completely fresh agent session: - No conversation history from previous runs - No memory of previous cron executions (unless persisted to memory/files) - The prompt must be self-contained — cron jobs cannot ask clarifying questions - The`cronjob`toolset is disabled (recursion guard) ## Skill-Backed Jobs A cron job can attach one or more skills via the`skillsfield. At execution time: 1. Skills are loaded in the specified order 2. Each skill's SKILL.md content is injected as context 3. The job's prompt is appended as the task instruction 4. The agent processes the combined skill context + prompt This enables reusable, tested workflows without pasting full instructions into cron prompts. For example: ``` Create a daily funding report → attach "ai-funding-daily-report" skill ``` ### Script-Backed Jobs Jobs can also attach a Python script via thescriptfield. The script runs before* each agent turn, and its stdout is injected into the prompt as context. This enables data collection and change detection patterns: ```python # ~/.hermes/scripts/check_competitors.py import requests, json # Fetch competitor release notes, diff against last run # Print summary to stdout — agent analyzes and reports ``` The script timeout defaults to 120 seconds.get_script_timeout()`resolves the limit through a three-layer chain: 1. Module-level override —`SCRIPT_TIMEOUT`(for tests/monkeypatching). Only used when it differs from the default. 2. Environment variable —`HERMES_CRON_SCRIPT_TIMEOUT`3. Config —`cron.script_timeout_seconds`in`config.yaml`(read via`load_config()`) 4. Default — 120 seconds ### Provider Recovery` run_job()`passes the user's configured fallback providers and credential pool into the`AIAgent`instance: - Fallback providers — reads`fallback_providers`(list) or`fallback_model`(legacy dict) from`config.yaml`, matching the gateway's` load_fallback_model()`pattern. Passed as`fallback_model=`to`AIAgent.init`, which normalizes both formats into a fallback chain. - Credential pool — loads via` load_pool(provider)`from`agent.credential_pool `using the resolved runtime provider name. Only passed when the pool has credentials (`pool.has_credentials()`). Enables same-provider key rotation on 429/rate-limit errors. This mirrors the gateway's behavior — without it, cron agents would fail on rate limits without attempting recovery. ## Delivery Model Cron job results can be delivered to any supported platform: | Target | Syntax | Example | |--------|--------|---------| | Origin chat |` origin`| Deliver to the chat where the job was created | | Local file |`local`| Save to`/.hermes/cron/output/`| | Telegram |`telegram`or`telegram:<chat_id>`|`telegram:-1001234567890`| | Discord |`discord`or`discord:#channel`|`discord:#engineering`| | Slack |`slack`| Deliver to Slack home channel | | WhatsApp |`whatsapp`| Deliver to WhatsApp home | | Signal |`signal`| Deliver to Signal | | Matrix |`matrix`| Deliver to Matrix home room | | Mattermost |`mattermost`| Deliver to Mattermost home | | Email |`email`| Deliver via email | | SMS |`sms`| Deliver via SMS | | Home Assistant |`homeassistant`| Deliver to HA conversation | | DingTalk |`dingtalk`| Deliver to DingTalk | | Feishu |`feishu`| Deliver to Feishu | | WeCom |`wecom`| Deliver to WeCom | | Weixin |`weixin`| Deliver to Weixin (WeChat) | | BlueBubbles |`bluebubbles`| Deliver to iMessage via BlueBubbles | | QQ Bot |`qqbot`| Deliver to QQ (Tencent) via Official API v2 | For Telegram topics, use the format`telegram:<chat_id>:<thread_id>`(e.g.,`telegram:-1001234567890:17585`). ### Response Wrapping By default (`cron.wrap_response: true`), cron deliveries are wrapped with: - A header identifying the cron job name and task - A footer noting the agent cannot see the delivered message in conversation The` [SILENT]`prefix in a cron response suppresses delivery entirely — useful for jobs that only need to write to files or perform side effects. ### Session Isolation Cron deliveries are NOT mirrored into gateway session conversation history. They exist only in the cron job's own session. This prevents message alternation violations in the target chat's conversation. ## Recursion Guard Cron-run sessions have the`cronjob `toolset disabled. This prevents: - A scheduled job from creating new cron jobs - Recursive scheduling that could explode token usage - Accidental mutation of the job schedule from within a job ## Locking The scheduler uses cross-process file-based locking (`fcntl.flock`on Unix,`msvcrt.locking`on Windows) to prevent overlapping ticks from executing the same due-job batch twice — even between the gateway's in-process ticker and a standalone`hermes cron`/ manual`tick()`call. If the lock cannot be acquired,`tick()`returns 0 immediately. ## CLI Interface The`hermes cronCLI provides direct job management: ```bash hermes cron list # Show all jobs hermes cron create # Interactive job creation (alias: add) hermes cron edit <job_id> # Edit job configuration hermes cron pause <job_id> # Pause a running job hermes cron resume <job_id> # Resume a paused job hermes cron run <job_id> # Trigger immediate execution hermes cron remove <job_id> # Delete a job ``` ## Related Docs - [Cron Feature Guide](/user-guide/features/cron) - [Gateway Internals](./gateway-internals.md) - [Agent Loop Internals](./agent-loop.md) ---  # Image Generation Provider Plugins # Building an Image Generation Provider Plugin Image-gen provider plugins register a backend that services everyimage_generate`tool call — DALL·E, gpt-image, Grok, Flux, Imagen, Stable Diffusion, fal, Replicate, a local ComfyUI rig, anything. Built-in providers (OpenAI, OpenAI-Codex, xAI) all ship as plugins. You can add a new one, or override a bundled one, by dropping a directory into`plugins/image_gen//. :::tip Image-gen is one of several backend plugins Hermes supports. The others (with more specialized ABCs) are [Memory Provider Plugins](/developer-guide/memory-provider-plugin), [Context Engine Plugins](/developer-guide/context-engine-plugin), and [Model Provider Plugins](/developer-guide/model-provider-plugin). General tool/hook/CLI plugins live in [Build a Hermes Plugin](/guides/build-a-hermes-plugin). ::: ## How discovery works Hermes scans for image-gen backends in three places: 1. Bundled — /plugins/image_gen//`(auto-loaded with`kind: backend`, always available) 2. User —` /.hermes/plugins/image_gen//`(opt-in via`plugins.enabled`) 3. Pip — packages declaring a` hermes_agent.plugins`entry point Each plugin's`register(ctx)`function calls`ctx.register_image_gen_provider(…)`— that puts it into the registry in`agent/image_gen_registry.py`. The active provider is picked by` image_gen.provider`in`config.yaml`;` hermes tools`walks users through selection. The`image_generate`tool wrapper asks the registry for the active provider and dispatches there. If no provider is registered, the tool surfaces a helpful error pointing at`hermes tools. ## Directory structure ``` plugins/image_gen/my-backend/ ├── init.py # ImageGenProvider subclass + register() └── plugin.yaml # Manifest with kind: backend ``` A bundled plugin is complete at this point. User plugins at ~/.hermes/plugins/image_gen//`need to be added to`plugins.enabled`in`config.yaml`(or run`hermes plugins enable `). ## The ImageGenProvider ABC Subclass` agent.image_gen_provider.ImageGenProvider`. The only required members are the` name`property and the`generate()method — everything else has sane defaults: ```python # plugins/image_gen/my-backend/init.py from typing import Any, Dict, List, Optional import os from agent.image_gen_provider import ( DEFAULT_ASPECT_RATIO, ImageGenProvider, error_response, resolve_aspect_ratio, save_b64_image, success_response, ) class MyBackendImageGenProvider(ImageGenProvider): @property def name(self) -> str: # Stable id used in image_gen.provider config. Lowercase, no spaces. return "my-backend" @property def display_name(self) -> str: # Human label shown inhermes tools`. Defaults to name.title() if omitted. return "My Backend" def is_available(self) -> bool: # Return False if credentials or deps are missing. # The tool's availability gate calls this before dispatch. if not os.environ.get("MY_BACKEND_API_KEY"): return False try: import my_backend_sdk # noqa: F401 except ImportError: return False return True def list_models(self) -> List[Dict[str, Any]]: # Catalog shown in` hermes tools`model picker. return [ { "id": "my-model-fast", "display": "My Model (Fast)", "speed": "~5s", "strengths": "Quick iteration", "price": "$0.01/image", }, { "id": "my-model-hq", "display": "My Model (HQ)", "speed": "~30s", "strengths": "Highest fidelity", "price": "$0.04/image", }, ] def default_model(self) -> Optional[str]: return "my-model-fast" def get_setup_schema(self) -> Dict[str, Any]: # Metadata for the`hermes toolspicker — keys to prompt for at setup. return { "name": "My Backend", "badge": "paid", # optional; shown as a short tag in the picker "tag": "One-line description shown under the name", "env_vars": [ { "key": "MY_BACKEND_API_KEY", "prompt": "My Backend API key", "url": "https://my-backend.example.com/api-keys", }, ], } def generate( self, prompt: str, aspect_ratio: str = DEFAULT_ASPECT_RATIO, kwargs: Any, ) -> Dict[str, Any]: prompt = (prompt or "").strip() aspect_ratio = resolve_aspect_ratio(aspect_ratio) if not prompt: return error_response( error="Prompt is required", error_type="invalid_input", provider=self.name, prompt="", aspect_ratio=aspect_ratio, ) # Model selection precedence: env var → config → default. The helper # _resolve_model() in the built-in openai plugin is a good reference. model_id = kwargs.get("model") or self.default_model() or "my-model-fast" try: import my_backend_sdk client = my_backend_sdk.Client(api_key=os.environ["MY_BACKEND_API_KEY"]) result = client.generate( prompt=prompt, model=model_id, aspect_ratio=aspect_ratio, ) # Two shapes supported: # - URL string: return it asimage# - base64 data: save under $HERMES_HOME/cache/images/ via save_b64_image() if result.get("image_b64"): path = save_b64_image( result["image_b64"], prefix=self.name, extension="png", ) image = str(path) else: image = result["image_url"] return success_response( image=image, model=model_id, prompt=prompt, aspect_ratio=aspect_ratio, provider=self.name, ) except Exception as exc: return error_response( error=str(exc), error_type=type(exc).name, provider=self.name, model=model_id, prompt=prompt, aspect_ratio=aspect_ratio, ) def register(ctx) -> None: """Plugin entry point — called once at load time.""" ctx.register_image_gen_provider(MyBackendImageGenProvider()) ``` ## plugin.yaml ```yaml name: my-backend version: 1.0.0 description: My image backend — text-to-image via My Backend SDK author: Your Name kind: backend requires_env: - MY_BACKEND_API_KEY ```kind: backend`is what routes the plugin to the image-gen registration path.`requires_env`is prompted during`hermes plugins install`. ## ABC reference Full contract in` agent/image_gen_provider.py`. The methods you'll typically override: | Member | Required | Default | Purpose | |---|---|---|---| |` name`| ✅ | — | Stable id used in`image_gen.provider`config | |`display_name`| — |`name.title()`| Label shown in`hermes tools`| |`is_available()`| — |`True`| Gate for missing creds/deps | |`list_models()`| — |`[]`| Catalog for`hermes tools`model picker | |`default_model()`| — | first from`list_models()`| Fallback when no model is configured | |`get_setup_schema()`| — | minimal | Picker metadata + env-var prompts | |`generate(prompt, aspect_ratio, kwargs)`| ✅ | — | The call | ## Response format`generate()`must return a dict built via`success_response()`or`error_response()`. Both live in` agent/image_gen_provider.py. Success: ```python success_response( image=<url-or-absolute-path>, model=<model-id>, prompt=<echoed-prompt>, aspect_ratio="landscape" | "square" | "portrait", provider=<your-provider-name>, extra={...}, # optional backend-specific fields ) ``` Error: ```python error_response( error="human-readable message", error_type="provider_error" | "invalid_input" | "<exception class name>", provider=<your-provider-name>, model=<model-id>, prompt=<prompt>, aspect_ratio=<resolved aspect>, ) ``` The tool wrapper JSON-serializes the dict and hands it to the LLM. Errors are surfaced as the tool result; the LLM decides how to explain them to the user. ## Handling base64 vs URL output Some backends return image URLs (fal, Replicate); others return base64 payloads (OpenAI gpt-image-2). For the base64 case, use save_b64_image()`— it writes to`$HERMES_HOME/cache/images/.`and returns the absolute`Path`. Pass that path (as` str`) as` image=`in`success_response()`. Gateway delivery (Telegram photo bubble, Discord attachment) recognizes both URLs and absolute paths. ## User overrides Drop a user plugin at` /.hermes/plugins/image_gen//`with the same`name`property as a bundled one and enable it via`hermes plugins enable `— the registry is last-writer-wins, so your version replaces the built-in. Useful for pointing an`openaiplugin at a private proxy, or swapping in a custom model catalog. ## Testing ```bash export HERMES_HOME=/tmp/hermes-imggen-test mkdir -p $HERMES_HOME/plugins/image_gen/my-backend # …copy init.py + plugin.yaml into that dir… export MY_BACKEND_API_KEY=your-test-key hermes plugins enable my-backend # Pick it as the active provider echo "image_gen:" >> $HERMES_HOME/config.yaml echo " provider: my-backend" >> $HERMES_HOME/config.yaml # Exercise it hermes -z "Generate an image of a corgi in a spacesuit" ``` Or interactively:hermes tools`→ "Image Generation" → select`my-backend `→ enter API key if prompted. ## Reference implementations - `plugins/image_gen/openai/init.py` — gpt-image-2 at low/medium/high tiers as three virtual model IDs sharing one API model with different` quality `params. Good example of tiered models under a single backend + config.yaml precedence chain. - `plugins/image_gen/xai/init.py` — Grok Imagine via xAI. Different shape (URL output, simpler catalog). - `plugins/image_gen/openai-codex/init.py — Codex-style Responses API variant reusing the OpenAI SDK with a different routing base URL. ## Distribute via pip ```toml # pyproject.toml [project.entry-points."hermes_agent.plugins"] my-backend-imggen = "my_backend_imggen_package" ``` my_backend_imggen_package`must expose a top-level`registerfunction. See [Distribute via pip](/guides/build-a-hermes-plugin#distribute-via-pip) in the general plugin guide for the full setup. ## Related pages - [Image Generation](/user-guide/features/image-generation) — user-facing feature documentation - [Plugins overview](/user-guide/features/plugins) — all plugin types at a glance - [Build a Hermes Plugin](/guides/build-a-hermes-plugin) — general tools/hooks/slash commands guide ---  # Memory Provider Plugins # Building a Memory Provider Plugin Memory provider plugins give Hermes Agent persistent, cross-session knowledge beyond the built-in MEMORY.md and USER.md. This guide covers how to build one. :::tip Memory providers are one of two provider plugin types. The other is [Context Engine Plugins](/developer-guide/context-engine-plugin), which replace the built-in context compressor. Both follow the same pattern: single-select, config-driven, managed viahermes plugins`. ::: ## Directory Structure Each memory provider lives in` plugins/memory//: ``` plugins/memory/my-provider/ ├── init.py # MemoryProvider implementation + register() entry point ├── plugin.yaml # Metadata (name, description, hooks) └── README.md # Setup instructions, config reference, tools ``` ## The MemoryProvider ABC Your plugin implements the MemoryProvider`abstract base class from`agent/memory_provider.py: ```python from agent.memory_provider import MemoryProvider class MyMemoryProvider(MemoryProvider): @property def name(self) -> str: return "my-provider" def is_available(self) -> bool: """Check if this provider can activate. NO network calls.""" return bool(os.environ.get("MY_API_KEY")) def initialize(self, session_id: str, kwargs) -> None: """Called once at agent startup. kwargs always includes: hermes_home (str): Active HERMES_HOME path. Use for storage. """ self._api_key = os.environ.get("MY_API_KEY", "") self._session_id = session_id # ... implement remaining methods ``` ## Required Methods ### Core Lifecycle | Method | When Called | Must Implement? | |--------|-----------|-----------------| | name`(property) | Always | Yes | |`is_available()`| Agent init, before activation | Yes — no network calls | |`initialize(session_id, kwargs)`| Agent startup | Yes | |`get_tool_schemas()`| After init, for tool injection | Yes | |`handle_tool_call(tool_name, args, kwargs)`| When agent uses your tools | Yes (if you have tools) | ### Config | Method | Purpose | Must Implement? | |--------|---------|-----------------| |`get_config_schema()`| Declare config fields for`hermes memory setup`| Yes | |`save_config(values, hermes_home)`| Write non-secret config to native location | Yes** (unless env-var-only) | ### Optional Hooks | Method | When Called | Use Case | |--------|-----------|----------| |`system_prompt_block()`| System prompt assembly | Static provider info | |`prefetch(query, , session_id=“”)`| Before each API call | Return recalled context | |`queue_prefetch(query)`| After each turn | Pre-warm for next turn | |`sync_turn(user, assistant, , session_id=“”)`| After each completed turn | Persist conversation | |`on_session_end(messages)`| Conversation ends | Final extraction/flush | |`on_pre_compress(messages)`| Before context compression | Save insights before discard | |`on_memory_write(action, target, content)`| Built-in memory writes | Mirror to your backend | |`shutdown()`| Process exit | Clean up connections | ## Config Schema`get_config_schema()`returns a list of field descriptors used by`hermes memory setup: ```python def get_config_schema(self): return [ { "key": "api_key", "description": "My Provider API key", "secret": True, # → written to .env "required": True, "env_var": "MY_API_KEY", # explicit env var name "url": "https://my-provider.com/keys", # where to get it }, { "key": "region", "description": "Server region", "default": "us-east", "choices": ["us-east", "eu-west", "ap-south"], }, { "key": "project", "description": "Project identifier", "default": "hermes", }, ] ``` Fields with secret: True`and`env_var`go to`.env`. Non-secret fields are passed to` save_config()`. :::tip Minimal vs Full Schema Every field in` get_config_schema()`is prompted during`hermes memory setup`. Providers with many options should keep the schema minimal — only include fields the user must configure (API key, required credentials). Document optional settings in a config file reference (e.g.` $HERMES_HOME/myprovider.json`) rather than prompting for them all during setup. This keeps the setup wizard fast while still supporting advanced configuration. See the Supermemory provider for an example — it only prompts for the API key; all other options live in `supermemory.json`. ::: ## Save Config ```python def save_config(self, values: dict, hermes_home: str) -> None: """Write non-secret config to your native location.""" import json from pathlib import Path config_path = Path(hermes_home) / "my-provider.json" config_path.write_text(json.dumps(values, indent=2)) ``` For env-var-only providers, leave the default no-op. ## Plugin Entry Point ```python def register(ctx) -> None: """Called by the memory plugin discovery system.""" ctx.register_memory_provider(MyMemoryProvider()) ``` ## plugin.yaml ```yaml name: my-provider version: 1.0.0 description: "Short description of what this provider does." hooks: - on_session_end # list hooks you implement ``` ## Threading Contract `sync_turn()` MUST be non-blocking. If your backend has latency (API calls, LLM processing), run the work in a daemon thread: ```python def sync_turn(self, user_content, assistant_content, , session_id="", messages=None): def _sync(): try: self._api.ingest(user_content, assistant_content, session_id=session_id, messages=messages) except Exception as e: logger.warning("Sync failed: %s", e) if self._sync_thread and self._sync_thread.is_alive(): self._sync_thread.join(timeout=5.0) self._sync_thread = threading.Thread(target=_sync, daemon=True) self._sync_thread.start() ``` `messages` is optional OpenAI-style conversation context as of the completed turn. When present, it includes user/assistant messages, assistant tool calls, and tool result messages. Providers that do not need raw turn context can omit the `messages` parameter; Hermes will continue calling them with the legacy signature. Cloud providers should document what parts of `messages` are sent off-device. Tool calls and tool results may contain file paths, command output, or other workspace data. ## Profile Isolation All storage paths must use the `hermes_home` kwarg from `initialize()`, not hardcoded `~/.hermes`: ```python # CORRECT — profile-scoped from hermes_constants import get_hermes_home data_dir = get_hermes_home() / "my-provider" # WRONG — shared across all profiles data_dir = Path("~/.hermes/my-provider").expanduser() ``` ## Testing See `tests/agent/test_memory_provider.py` and adjacent memory tests (`tests/agent/test_memory_session_switch.py`, `tests/agent/test_memory_user_id.py`, `tests/run_agent/test_memory_provider_init.py`) for end-to-end patterns. ```python from agent.memory_manager import MemoryManager mgr = MemoryManager() mgr.add_provider(my_provider) mgr.initialize_all(session_id="test-1", platform="cli") # Test tool routing result = mgr.handle_tool_call("my_tool", {"action": "add", "content": "test"}) # Test lifecycle mgr.sync_all("user msg", "assistant msg") mgr.on_session_end([]) mgr.shutdown_all() ``` ## Adding CLI Commands Memory provider plugins can register their own CLI subcommand tree (e.g. `hermes my-provider status`, `hermes my-provider config`). This uses a convention-based discovery system — no changes to core files needed. ### How it works 1. Add a `cli.py` file to your plugin directory 2. Define a `register_cli(subparser)` function that builds the argparse tree 3. The memory plugin system discovers it at startup via `discover_plugin_cli_commands()` 4. Your commands appear under `hermes <provider-name> <subcommand>` Active-provider gating: Your CLI commands only appear when your provider is the active `memory.provider` in config. If a user hasn't configured your provider, your commands won't show in `hermes --help`. ### Example ```python # plugins/memory/my-provider/cli.py def my_command(args): """Handler dispatched by argparse.""" sub = getattr(args, "my_command", None) if sub == "status": print("Provider is active and connected.") elif sub == "config": print("Showing config...") else: print("Usage: hermes my-provider <status|config>") def register_cli(subparser) -> None: """Build the hermes my-provider argparse tree. Called by discover_plugin_cli_commands() at argparse setup time. """ subs = subparser.add_subparsers(dest="my_command") subs.add_parser("status", help="Show provider status") subs.add_parser("config", help="Show provider config") subparser.set_defaults(func=my_command) ``` ### Reference implementation See `plugins/memory/honcho/cli.py` for a full example with 13 subcommands, cross-profile management (`--target-profile`), and config read/write. ### Directory structure with CLI ``` plugins/memory/my-provider/ ├── init.py # MemoryProvider implementation + register() ├── plugin.yaml # Metadata ├── cli.py # register_cli(subparser) — CLI commands └── README.md # Setup instructions ``` ## Single Provider Rule Only one external memory provider can be active at a time. If a user tries to register a second, the MemoryManager rejects it with a warning. This prevents tool schema bloat and conflicting backends. ---  # Model Provider Plugins # Building a Model Provider Plugin Model provider plugins declare an inference backend — an OpenAI-compatible endpoint, an Anthropic Messages server, a Codex-style Responses API, or a Bedrock-native surface — that Hermes can route `AIAgent` calls through. Every built-in provider (OpenRouter, Anthropic, GMI, DeepSeek, Nvidia, …) ships as one of these plugins. Third parties can add their own by dropping a directory under `$ HERMES_HOME/plugins/model-providers/`with zero changes to the repo. :::tip Model provider plugins are the third kind of provider plugin. The others are [Memory Provider Plugins](/developer-guide/memory-provider-plugin) (cross-session knowledge) and [Context Engine Plugins](/developer-guide/context-engine-plugin) (context compression strategies). All three follow the same "drop a directory, declare a profile, no repo edits" pattern. ::: ## How discovery works`providers/init.py._discover_providers()`runs lazily the first time any code calls`get_provider_profile()`or`list_providers()`. Discovery order: 1. Bundled plugins —` /plugins/model-providers//`— ship with Hermes 2. User plugins —` $HERMES_HOME/plugins/model-providers/<name>/` — drop in any directory; no restart required for subsequent sessions 3. Legacy single-file — `<repo>/providers/<name>.py` — back-compat for out-of-tree editable installs User plugins override bundled plugins of the same name because `register_provider()` is last-writer-wins. Drop a `$ HERMES_HOME/plugins/model-providers/gmi/directory to replace the built-in GMI profile without touching the repo. ## Directory structure ``` plugins/model-providers/my-provider/ ├── init.py # Calls register_provider(profile) at module-level ├── plugin.yaml # kind: model-provider + metadata (optional but recommended) └── README.md # Setup instructions (optional) ``` The only required file isinit.py`.` plugin.yaml`is used by`hermes pluginsfor introspection and by the general PluginManager to route the plugin to the right loader; without it, the general loader falls back to a source-text heuristic. ## Minimal example — a simple API-key provider ```python # plugins/model-providers/acme-inference/init.py from providers import register_provider from providers.base import ProviderProfile acme = ProviderProfile( name="acme-inference", aliases=("acme",), display_name="Acme Inference", description="Acme — OpenAI-compatible direct API", signup_url="https://acme.example.com/keys", env_vars=("ACME_API_KEY", "ACME_BASE_URL"), base_url="https://api.acme.example.com/v1", auth_type="api_key", default_aux_model="acme-small-fast", fallback_models=( "acme-large-v3", "acme-medium-v3", "acme-small-fast", ), ) register_provider(acme) ``` ```yaml # plugins/model-providers/acme-inference/plugin.yaml name: acme-inference kind: model-provider version: 1.0.0 description: Acme Inference — OpenAI-compatible direct API author: Your Name ``` That's it. After dropping these two files, the following auto-wire with no other edits: | Integration | Where | What it gets | |---|---|---| | Credential resolution |hermes_cli/auth.py`|`PROVIDER_REGISTRY[“acme-inference”]`populated from profile | |`–provider`CLI flag |`hermes_cli/main.py`| Accepts`acme-inference`| |`hermes model`picker |`hermes_cli/models.py`| Appears in`CANONICAL_PROVIDERS`, model list fetched from` {base_url}/models`| |`hermes doctor`|`hermes_cli/doctor.py`| Health check for`ACME_API_KEY`+`{base_url}/models`probe | |`hermes setup`|`hermes_cli/config.py`|`ACME_API_KEY`appears in`OPTIONAL_ENV_VARS`and the setup wizard | | URL reverse-mapping |`agent/model_metadata.py`| Hostname → provider name for auto-detection | | Auxiliary model |`agent/auxiliary_client.py`| Uses`default_aux_model`for compression / summarization | | Runtime resolution |`hermes_cli/runtime_provider.py`| Returns correct`base_url`,` api_key`,` api_mode`| | Transport |`agent/transports/chat_completions.py`| Profile path generates kwargs via`prepare_messages`/`build_extra_body`/`build_api_kwargs_extras`| ## ProviderProfile fields Full definition in`providers/base.py`. The most useful ones: | Field | Type | Purpose | |---|---|---| |` name`| str | Canonical id — matches`model.provider`in`config.yaml`and the`–provider`flag | |`aliases`|`tuple[str, …]`| Alternative names resolved by`get_provider_profile()`(e.g.`grok`→`xai`) | |` api_mode`| str |`chat_completions`\|`codex_responses`\|`anthropic_messages`\|`bedrock_converse`| |`display_name`| str | Human label shown in`hermes model`picker | |`description`| str | Picker subtitle | |`signup_url`| str | Shown during first-run setup ("get an API key here") | |`env_vars`|`tuple[str, …]`| API-key env vars in priority order; a final`_BASE_URL`entry is used as the user base-URL override | |`base_url`| str | Default inference endpoint | |`models_url`| str | Explicit catalog URL (falls back to`{base_url}/models`) | |` auth_type`| str |`api_key`\|`oauth_device_code`\|`oauth_external`\|`copilot`\|`aws_sdk`\|`external_process`| |`fallback_models`|`tuple[str, …]`| Curated list shown when live catalog fetch fails | |`default_headers`|`dict[str, str]`| Sent on every request (e.g. Copilot's`Editor-Version`) | |` fixed_temperature`| Any |`None`= use caller's value;`OMIT_TEMPERATURE`sentinel = don't send temperature at all (Kimi) | |`default_max_tokens`|`int | None`| Provider-level max_tokens cap (Nvidia: 16384) | |`default_aux_model`| str | Cheap model for auxiliary tasks (compression, vision, summarization) | ## Overridable hooks Subclass`ProviderProfilefor non-trivial quirks: ```python from typing import Any from providers.base import ProviderProfile class AcmeProfile(ProviderProfile): def prepare_messages(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]: """Provider-specific message preprocessing. Runs after codex sanitization, before developer-role swap. Default: pass-through.""" # Example: Qwen normalizes plain-text content to a list-of-parts # array and injects cache_control; Kimi rewrites tool-call JSON return messages def build_extra_body(self, *, session_id=None, **context) -> dict: """Provider-specific extra_body fields merged into the API call. Context includes: session_id, provider_preferences, model, base_url, reasoning_config. Default: empty dict.""" # Example: OpenRouter's provider-preferences block, # Gemini's thinking_config translation. return {} def build_api_kwargs_extras(self, *, reasoning_config=None, **context): """Returns (extra_body_additions, top_level_kwargs). Needed when some fields go top-level (Kimi's reasoning_effort) and some go in extra_body (OpenRouter's reasoning dict). Default: ({}, {}).""" return {}, {} def fetch_models(self, , api_key=None, timeout=8.0) -> list[str] | None: """Live catalog fetch. Default hits {models_url or base_url}/models with Bearer auth. Override for: custom auth (Anthropic), no REST endpoint (Bedrock → None), or public/unauthenticated catalogs (OpenRouter).""" return super().fetch_models(api_key=api_key, timeout=timeout) ``` ## Hook reference examples Look at these bundled plugins for idioms: | Plugin | Why look | |---|---| |plugins/model-providers/openrouter/`| Aggregator with provider preferences, public model catalog | |`plugins/model-providers/gemini/`|`thinking_config`translation (native + OpenAI-compat nested forms) | |`plugins/model-providers/kimi-coding/`|`OMIT_TEMPERATURE`,` extra_body.thinking`, top-level` reasoning_effort`| |`plugins/model-providers/qwen-oauth/`| Message normalization,`cache_control`injection, VL high-res | |`plugins/model-providers/nous/`| Attribution tags, "omit reasoning when disabled" | |`plugins/model-providers/custom/`| Ollama`num_ctx`+`think: false`quirks | |`plugins/model-providers/bedrock/`|`api_mode=“bedrock_converse”`,` fetch_models`returns None (no REST endpoint) | ## User overrides — replace a built-in without editing the repo Say you want to point`gmi`at your private staging endpoint for testing. Create`/.hermes/plugins/model-providers/gmi/init.py: ```python from providers import register_provider from providers.base import ProviderProfile register_provider(ProviderProfile( name="gmi", aliases=("gmi-cloud", "gmicloud"), env_vars=("GMI_API_KEY",), base_url="https://gmi-staging.internal.example.com/v1", auth_type="api_key", default_aux_model="google/gemini-3.1-flash-lite-preview", )) ``` Next session, get_provider_profile(“gmi”).base_url`returns the staging URL. No repo patch, no rebuild. Because user plugins are discovered after bundled ones, the user`register_provider() `call wins. ## api_mode selection Four values are recognized. Hermes picks one based on: 1. User explicit override (`config.yaml model.api_mode `when set) 2. OpenCode's per-model dispatch (`opencode_model_api_mode`for Zen and Go) 3. URL auto-detection —`/anthropic`suffix →`anthropic_messages`,` api.openai.com`→`codex_responses`,` api.x.ai`→`codex_responses`,` /coding`on Kimi domains →`chat_completions`4. Profile`api_mode` as a fallback when URL detection finds nothing 5. Default` chat_completions`Set`profile.api_mode`to match the default your provider ships — it acts as a hint. User URL overrides still win. ## Auth types |`auth_type`| Meaning | Who uses it | |---|---|---| |`api_key`| Single env var carries a static API key | Most providers | |`oauth_device_code`| Device-code OAuth flow | — | |`oauth_external`| User signs in elsewhere, tokens land in`auth.json`| Anthropic OAuth, MiniMax OAuth, Gemini Cloud Code, Qwen Portal, Nous Portal | |`copilot`| GitHub Copilot token refresh cycle |`copilot`plugin only | |`aws_sdk`| AWS SDK credential chain (IAM role, profile, env) |`bedrock`plugin only | |`external_process`| Auth handled by a subprocess the agent spawns |`copilot-acp`plugin only |`auth_type`gates which codepaths treat your provider as a "simple api-key provider" — if it's not`api_key`, the PluginManager still records the manifest but Hermes' CLI-level automation (doctor checks,` –provider`flag, setup wizard delegation) may skip over it. ## Discovery timing Provider discovery is lazy — triggered by the first`get_provider_profile()`or`list_providers() `call in the process. In practice this happens early at startup (`auth.py`module load extends`PROVIDER_REGISTRYeagerly). If you need to verify your plugin loaded, run: ```bash hermes doctor ``` — a successfulauth_type=“api_key”`profile appears under the Provider Connectivity section with a`/modelsprobe. For programmatic inspection: ```python from providers import list_providers for p in list_providers(): print(p.name, p.base_url, p.api_mode) ``` ## Testing your plugin PointHERMES_HOMEat a temp directory so you don't pollute your real config: ```bash export HERMES_HOME=/tmp/hermes-plugin-test mkdir -p $HERMES_HOME/plugins/model-providers/my-provider cat > $HERMES_HOME/plugins/model-providers/my-provider/init.py <<'EOF' from providers import register_provider from providers.base import ProviderProfile register_provider(ProviderProfile( name="my-provider", env_vars=("MY_API_KEY",), base_url="https://api.my-provider.example.com/v1", auth_type="api_key", )) EOF export MY_API_KEY=your-test-key hermes -z "hello" --provider my-provider -m some-model ``` ## General PluginManager integration The generalPluginManager`(the thing`hermes plugins`operates on) sees model-provider plugins but does not import them —`providers/init.py`owns their lifecycle. The manager records the manifest for introspection and categorizes by`kind: model-provider`. When you drop an unlabeled user plugin into` $HERMES_HOME/plugins/`that happens to call`register_provider`with a`ProviderProfile`, the manager auto-coerces it to` kind: model-provider`via a source-text heuristic — so the plugin still routes correctly even without`plugin.yaml`. ## Distribute via pip Like any Hermes plugin, model providers can ship as a pip package. Add an entry point to your` pyproject.toml: ```toml [project.entry-points."hermes_agent.plugins"] acme-inference = "acme_hermes_plugin:register" ``` …where acme_hermes_plugin:register`is a function that calls`register_provider(profile)`. The general PluginManager picks up entry-point plugins during` discover_and_load()`. For` kind: model-providerpip plugins, you still need to declare the kind in your manifest (or rely on the source-text heuristic). See [Building a Hermes Plugin](/guides/build-a-hermes-plugin#distribute-via-pip) for the full entry-points setup. ## Related pages - [Provider Runtime](/developer-guide/provider-runtime) — resolution precedence + where each layer reads the profile - [Adding Providers](/developer-guide/adding-providers) — end-to-end checklist for new inference backends (covers both the fast plugin path and the full CLI/auth integration) - [Memory Provider Plugins](/developer-guide/memory-provider-plugin) - [Context Engine Plugins](/developer-guide/context-engine-plugin) - [Building a Hermes Plugin](/guides/build-a-hermes-plugin) — general plugin authoring ---  # Plugin LLM Access # Plugin LLM Accessctx.llmis the supported way for a plugin to make an LLM call. Chat completion, structured extraction, sync, async, with or without images — same surface, same trust gate, same host-owned credentials. Plugins reach for this when they need to do something that involves the model but isn't part of the agent's conversation. A hook that rewrites a tool error into something a non-engineer can read. A gateway adapter that translates an inbound message before queuing it. A slash command that summarises a long paste. A scheduled job that scores yesterday's activity and writes one line to a status board. A pre-filter that decides whether a message is worth waking the agent up for at all. These are jobs the agent shouldn't be in the loop on. They want one LLM call, a typed answer, and to be done. ## The smallest possible call ```python result = ctx.llm.complete(messages=[{"role": "user", "content": "ping"}]) return result.text ``` That's the whole API in one line. No keys, no provider config, no SDK initialisation. The plugin runs against whatever provider and model the user is currently using — when they switch providers, the plugin follows them automatically. ## A more complete chat example ```python result = ctx.llm.complete( messages=[ {"role": "system", "content": "Rewrite errors as one short sentence a non-engineer can act on."}, {"role": "user", "content": traceback_text}, ], max_tokens=64, purpose="hooks.error-rewrite", ) return result.text ```purpose`is a free-form audit string — it shows up in`agent.log`and in`result.auditso operators can see which plugin made which call. Optional but recommended for anything that fires often. ## Structured output When the plugin needs a typed answer, switch to the structured lane: ```python result = ctx.llm.complete_structured( instructions="Score this support reply for urgency (0–1) and pick a category.", input=[{"type": "text", "text": message_body}], json_schema=TRIAGE_SCHEMA, purpose="support.triage", temperature=0.0, max_tokens=128, ) if result.parsed["urgency"] > 0.8: await dispatch_to_oncall(result.parsed["category"], message_body) ``` The host requests JSON output from the provider, parses it locally as a fallback, validates against your schema ifjsonschema`is installed, and hands back a Python object on`result.parsed`. If the model couldn't produce valid JSON,` result.parsed`is`None`and`result.text`carries the raw response. ## What this lane gives you One call, four shapes.`complete()`for chat,`complete_structured()`for typed JSON,`acomplete()`and`acomplete_structured()`for asyncio. Same arguments, same result objects. * Host-owned credentials. OAuth tokens, refresh flows, the credential pool, per-task aux overrides — every credential concept Hermes already has applies. The plugin never sees a token; the host attributes the call back through`result.audit`. * Bounded. Single sync or async call. No streaming, no tool loops, no conversation state to manage. State the input, get the result, return. * Fail-closed trust. A plugin you've never configured cannot pick its own provider, model, agent, or stored credential. The default posture is "use what the user is using." Operators opt in to specific overrides, per plugin, in` config.yaml`. ## Quick start Two complete plugins below — one chat, one structured. Both ship inside a single` register(ctx)`function and need zero outside configuration to run against whatever model the user has active. ### Chat completion —`/tldr```python def register(ctx): ctx.register_command( name="tldr", handler=lambda raw: _tldr(ctx, raw), description="Summarise the supplied text in one paragraph.", args_hint="<text>", ) def _tldr(ctx, raw_args: str) -> str: text = raw_args.strip() if not text: return "Usage: /tldr <text to summarise>" result = ctx.llm.complete( messages=[ {"role": "system", "content": "Summarise the user's text in one tight paragraph. No preamble."}, {"role": "user", "content": text}, ], max_tokens=256, temperature=0.3, purpose="tldr", ) return result.text ```result.text`is the model's response;`result.usage`carries token counts;`result.provider`and`result.model`carry attribution. ### Structured extraction —`/paste-to-tasks ```python def register(ctx): ctx.register_command( name="paste-to-tasks", handler=lambda raw: _paste_to_tasks(ctx, raw), description="Turn freeform meeting notes into structured tasks.", args_hint="<text>", ) _TASKS_SCHEMA = { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "owner": {"type": "string"}, "action": {"type": "string"}, "due": {"type": "string", "description": "ISO date or empty"}, }, "required": ["action"], }, }, }, "required": ["tasks"], } def _paste_to_tasks(ctx, raw_args: str) -> str: if not raw_args.strip(): return "Usage: /paste-to-tasks <meeting notes>" result = ctx.llm.complete_structured( instructions=( "Extract concrete action items from these meeting notes. " "One task per actionable line. If no owner is named, leave 'owner' blank." ), input=[{"type": "text", "text": raw_args}], json_schema=_TASKS_SCHEMA, schema_name="meeting.tasks", purpose="paste-to-tasks", temperature=0.0, max_tokens=512, ) if result.parsed is None: return f"Couldn't parse a response. Raw output:\n{result.text}" lines = [f"- [{t.get('owner') or '?'}] {t['action']}" for t in result.parsed["tasks"]] return "\n".join(lines) or "(no tasks found)" ``` A third worked example, this time with image input, lives in the [hermes-example-plugins`](https://github.com/NousResearch/hermes-example-plugins/tree/main/plugin-llm-example) repo (companion repo for reference plugins — not bundled with hermes-agent itself). For the async surface (`acomplete()`/`acomplete_structured()`with`asyncio.gather()`), see [`plugin-llm-async-example`](https://github.com/NousResearch/hermes-example-plugins/tree/main/plugin-llm-async-example) in the same repo. ## When to use which | You want… | Reach for | |---|---| | A free-form text response (translation, summary, rewrite, generation) |` complete()`| | A multi-turn prompt (system + few-shot examples + user) |`complete()`| | A typed dict back, validated against a schema |`complete_structured()`| | Image-or-text input with a typed dict back |`complete_structured()`| | The same call from async code (gateway adapters, async hooks) |`acomplete()`/`acomplete_structured()`| Everything else — provider selection, model resolution, auth, fallback, timeout, vision routing — is the same across all four. ## API surface`ctx.llm`is an instance of`agent.plugin_llm.PluginLlm`. ###` complete()```python result = ctx.llm.complete( messages=[{"role": "user", "content": "Hi"}], provider=None, # optional, gated — Hermes provider id (e.g. "openrouter") model=None, # optional, gated — whatever string that provider expects temperature=None, max_tokens=None, timeout=None, # seconds agent_id=None, # optional, gated profile=None, # optional, gated — explicit auth-profile name purpose="optional-audit-string", ) # → PluginLlmCompleteResult(text, provider, model, agent_id, usage, audit) ``` Plain chat completion.messages`is the standard OpenAI shape — a list of`{“role”: “…”, “content”: “…”}`dicts. Multi-turn prompts (system + few-shot user/assistant pairs + final user) work exactly as they would with the OpenAI SDK.`provider=`and`model= `are independent and follow the same shape as the host's main config (`model.provider`+`model.model`). Set just` model=`to use the user's active provider with a different model on it. Set both to switch providers entirely. Either argument without operator opt-in raises`PluginLlmTrustError`. ###` complete_structured()```python result = ctx.llm.complete_structured( instructions="What you want extracted.", input=[ {"type": "text", "text": "..."}, {"type": "image", "data": b"...", "mime_type": "image/png"}, {"type": "image", "url": "https://..."}, ], json_schema={...}, # optional — triggers parsed result + validation json_mode=False, # set True without a schema to ask for JSON anyway schema_name=None, # optional human-readable schema name system_prompt=None, provider=None, # optional, gated model=None, # optional, gated temperature=None, max_tokens=None, timeout=None, agent_id=None, profile=None, purpose=None, ) # → PluginLlmStructuredResult(text, provider, model, agent_id, # usage, parsed, content_type, audit) ``` Inputs are typed text or image blocks (raw bytes get base64 encoded as adata:`URL automatically). When`json_schema`or`json_mode=True`is supplied, the host requests JSON output via`response_format`, parses it locally as a fallback, and validates against your schema if` jsonschema`is installed. `result.content_type == “json”`—`result.parsed`is a Python object that matches your schema. `result.content_type == “text”`— parsing or validation failed; inspect`result.textfor the raw model response. ### Async ```python result = await ctx.llm.acomplete(messages=...) result = await ctx.llm.acomplete_structured(instructions=..., input=...) ``` Same arguments and result types as their sync counterparts. Use these from gateway adapters, async hooks, or any plugin code already running on an asyncio loop. ### Result attributes ```python @dataclass class PluginLlmCompleteResult: text: str # the assistant's response provider: str # e.g. "openrouter", "anthropic" model: str # whatever the provider returned for this call agent_id: str # whose model/auth was used usage: PluginLlmUsage # tokens + cache + cost estimate audit: Dict[str, Any] # plugin_id, purpose, profile @dataclass class PluginLlmStructuredResult(PluginLlmCompleteResult): parsed: Optional[Any] # JSON object when content_type == "json" content_type: str # "json" or "text" # audit also carries schema_name when supplied ```usage`carries`input_tokens`,` output_tokens`,` total_tokens`,` cache_read_tokens`,` cache_write_tokens`, and` cost_usd`when the provider returns those fields. ## Trust gate The default behaviour is fail-closed. With no`plugins.entries `config block, a plugin can: * run any of the four methods against the user's active provider and model, * set request-shaping arguments (`temperature`,` max_tokens`,` timeout`,` system_prompt`,` purpose`,` messages`,` instructions`,` input`,` json_schema`), …and that's it.` provider=`,` model=`,` agent_id=`, and` profile=`arguments raise`PluginLlmTrustError`until the operator opts in. Most plugins never need this section. A plugin that just calls`ctx.llm.complete(messages=…)with no overrides runs against whatever the user has active and works zero-config. The block below is only relevant when a plugin specifically wants to pin to a different model or provider than the user. ```yaml plugins: entries: my-plugin: llm: # Allow this plugin to choose a different Hermes provider # (must be one Hermes already knows about — same names as #hermes modeland config.yaml model.provider). allow_provider_override: true # Optionally restrict which providers. Use [""] for any. allowed_providers: - openrouter - anthropic # Allow this plugin to ask for a specific model. allow_model_override: true # Optionally restrict which models. Use [""] for any. # Models are matched literally against whatever string the # plugin sends — Hermes does not look anything up. allowed_models: - openai/gpt-4o-mini - anthropic/claude-3-5-haiku # Allow cross-agent calls (rare). allow_agent_id_override: false # Allow the plugin to request a specific stored auth profile # (e.g. a different OAuth account on the same provider). allow_profile_override: false ``` The plugin id is the manifestname: `field for flat plugins, or the path-derived key for nested plugins (`image_gen/openai`,` memory/honcho`, etc.). ### What the gate enforces | Override | Default | Config key | | --------------- | ------- | -------------------------------- | |` provider=`| denied |`allow_provider_override: true`| | ↳ allowlist | — |`allowed_providers: […]`| |`model=`| denied |`allow_model_override: true`| | ↳ allowlist | — |`allowed_models: […]`| |`agent_id=`| denied |`allow_agent_id_override: true`| |`profile=`| denied |`allow_profile_override: true`| Each override is independently gated. Granting`allow_model_override`does not also grant`allow_provider_override`— a plugin trusted to pick a model is still pinned to the user's active provider unless it gets the provider gate as well. ### What the gate does NOT need to enforce * Request-shaping arguments —`temperature`,` max_tokens`,` timeout`,` system_prompt`,` purpose`,` messages`,` instructions`,` input`,` json_schema`,` schema_name`,` json_mode`— are always allowed; they don't pick credentials or routes. * The default deny posture means an unconfigured plugin can still do useful work — it just runs against the active provider and model. Operators only need to think about`plugins.entries`for plugins that want finer routing. ## What the host owns A complete list of the things`ctx.llm`does for the plugin so you don't have to: * Provider resolution. Reads`model.provider`+`model.model`from the user's config (or the explicit overrides when trusted). * Auth. Pulls API keys, OAuth tokens, or refresh tokens from`/.hermes/auth.json`/ env, including the credential pool when one is configured. The plugin never sees them. * Vision routing. When image input is supplied and the user's active text model is text-only, the host falls back to the configured vision model automatically. * Fallback chain. If the user's primary provider 5xxs or 429s, the request goes through Hermes' usual aggregator-aware fallback before it returns an error to the plugin. * Timeout. Honours your`timeout=`argument, falling back to`auxiliary..timeout`config or the global aux default. * JSON shaping. Sends`response_format`to the provider when you ask for JSON, then re-parses locally from a code-fenced response if the provider returned one. * Schema validation. Validates against your`json_schema`when`jsonschema`is installed; logs a debug line and skips strict validation otherwise. * Audit log. Each call writes one INFO line to`agent.log`with the plugin id, provider/model, purpose, and token totals. ## What the plugin owns * Request shape.`messages`for chat,`instructions`+`input`for structured. The plugin builds the prompt; the host runs it. * Schema. Whatever shape you want back. The host doesn't infer it for you. * Error handling.`complete_structured()`raises`ValueError`on empty inputs and on schema-validation failure.`PluginLlmTrustError`fires when the trust gate denies an override. Anything else (provider 5xx, no credentials configured, timeout) raises whatever`auxiliary_client.call_llm()`raises. * Cost. Every call runs against the user's paid provider. Don't loop on`complete()`for every gateway message without thinking about token spend. ## Where this fits in the plugin surface Existing`ctx.`methods extend an existing Hermes subsystem: |`ctx.register_tool`| adds a tool the agent can call | |`ctx.register_platform`| wires a new gateway adapter | |`ctx.register_image_gen_provider`| replaces an image-gen backend | |`ctx.register_memory_provider`| replaces the memory backend | |`ctx.register_context_engine`| replaces the context compressor | |`ctx.register_hook`| observes a lifecycle event |`ctx.llm`is the first surface that lets a plugin run the same model the user is talking to, out of band, without any of the above. That's its only job. If your plugin needs to register a tool the agent invokes, use`register_tool`. If it needs to react to a lifecycle event, use` register_hook`. If it needs to make its own model call — for any reason, structured or not —` ctx.llm`. ## Reference * Implementation: [`agent/plugin_llm.py`](https://github.com/NousResearch/hermes-agent/blob/main/agent/plugin_llm.py) * Tests: [`tests/agent/test_plugin_llm.py`](https://github.com/NousResearch/hermes-agent/blob/main/tests/agent/test_plugin_llm.py) * Reference plugins (companion repo): * [`plugin-llm-example`](https://github.com/NousResearch/hermes-example-plugins/tree/main/plugin-llm-example) — sync structured extraction with image input * [`plugin-llm-async-example`](https://github.com/NousResearch/hermes-example-plugins/tree/main/plugin-llm-async-example) — async with` asyncio.gather()* Auxiliary client (the engine under the hood): see [Provider Runtime](/developer-guide/provider-runtime). ---  # Programmatic Integration # Programmatic Integration Hermes ships three protocols for driving the agent from external programs — IDE plugins, custom UIs, CI pipelines, embedded sub-agents. Pick the one that matches your transport and consumer. | Protocol | Transport | Best for | Defined by | |----------|-----------|----------|------------| | ACP | JSON-RPC over stdio | IDE clients (VS Code, Zed, JetBrains) that already speak the [Agent Client Protocol](https://github.com/zed-industries/agent-client-protocol) |acp_adapter/`| | TUI gateway | JSON-RPC over stdio (or WebSocket) | Custom hosts that want fine-grained control of sessions, slash commands, approvals, and streaming events |`tui_gateway/server.py`| | API server | HTTP + Server-Sent Events | OpenAI-compatible frontends (Open WebUI, LobeChat, LibreChat…) and language-agnostic web clients |`gateway/platforms/api_server.py`| All three drive the same`AIAgent`core. They differ only in wire format and which set of features they expose. --- ## ACP (Agent Client Protocol)`hermes acp`starts a stdio JSON-RPC server speaking ACP. Used in production by VS Code (Zed Industries' ACP extension), Zed, and any JetBrains IDE with an ACP plugin. Capabilities exposed: session creation, prompt submission, streaming agent message chunks, tool-call events, permission requests, session fork, cancel, and authentication. Tool output is rendered into ACP`Diff`/`ToolCallcontent blocks the IDE understands. Full lifecycle, event bridge, and approval flow: [ACP Internals](./acp-internals). ```bash hermes acp # serve ACP on stdio hermes acp --bootstrap # print install snippet for an ACP-capable IDE ``` --- ## TUI Gateway JSON-RPCtui_gateway/server.py `is the protocol the Ink TUI (`hermes –tui`) and the embedded dashboard PTY bridge talk to. Any external host can speak the same protocol over stdio (or WebSocket via` tui_gateway/ws.py). ### Method catalog (selected) ``` prompt.submit prompt.background session.steer session.create session.list session.active_list session.activate session.close session.interrupt session.history session.compress session.branch session.title session.usage session.status clarify.respond sudo.respond secret.respond approval.respond config.set / config.get commands.catalog command.resolve command.dispatch cli.exec reload.mcp reload.env process.stop delegation.status subagent.interrupt spawn_tree.save / list / load terminal.resize clipboard.paste image.attach ``` session.active_list`,` session.activate`, and` session.close`are the process-local live-session controls used by the TUI session switcher. Use`session.list`/`/resume`for saved transcript discovery; use the active-session methods only for sessions that are currently open in the TUI gateway process. ### Events streamed back`message.delta`,` message.complete`,` tool.start`,` tool.progress`,` tool.complete`,` approval.request`,` clarify.request`,` sudo.request`,` secret.request`,` gateway.ready`, plus session lifecycle and error events. ### Pi-style RPC mapping Every command in the Pi-mono RPC spec ([issue #360](https://github.com/NousResearch/hermes-agent/issues/360)) has a TUI-gateway equivalent: | Pi command | Hermes equivalent | |------------|-------------------| |` prompt`|`prompt.submit`(or ACP`session/prompt`) | |` steer`|`session.steer`| |`follow_up`|`prompt.submit`queued after current turn | |`abort`|`session.interrupt`| |`set_model`|`command.dispatch`for`/model provider:model`(mid-session, persistent) | |`compact`|`session.compress`| |`get_state`|`session.status`| |`get_messages`|`session.history`| |`switch_session`|`session.resume`| |`fork`|`session.branch`| |`ui_request`/`ui_response`|`clarify.respond`/`sudo.respond`/`secret.respond`/`approval.respond`| --- ## OpenAI-Compatible API Server`gateway/platforms/api_server.py exposes hermes over HTTP for any client that already speaks the OpenAI format. Useful when you want a web frontend, a curl-driven CI runner, or a non-Python consumer. Endpoints: ``` POST /v1/chat/completions OpenAI Chat Completions (streaming via SSE) POST /v1/responses OpenAI Responses API (stateful) POST /v1/runs Start a run, returns run_id (202) GET /v1/runs/{id} Run status GET /v1/runs/{id}/events SSE stream of lifecycle events POST /v1/runs/{id}/approval Resolve a pending approval POST /v1/runs/{id}/stop Interrupt the run GET /v1/capabilities Machine-readable feature flags GET /v1/models Lists hermes-agent GET /health, /health/detailed ``` Setup, headers (X-Hermes-Session-Id`,` X-Hermes-Session-Key), and frontend wiring: [API Server](../user-guide/features/api-server). --- ## Which one should I use? - You're writing an IDE plugin and the IDE already speaks ACP → ACP. Zero protocol work on the IDE side. - You're writing a custom desktop / web / TUI host and want every Hermes feature (slash commands, approvals, clarify, multi-agent, session branching) → TUI gateway JSON-RPC. - You want any OpenAI-compatible frontend, a language-agnostic HTTP client, or curl-driven automation → API server. - You want a Python in-process embed without a subprocess → import run_agent.AIAgent`directly. See [Agent Loop](./agent-loop). --- ## Model hot-swapping Mid-session model switching works on every surface — it's the`/model`slash command under the hood. - CLI / TUI:`/model claude-sonnet-4`or`/model openrouter:anthropic/claude-sonnet-4.6`- TUI gateway RPC:`command.dispatch`with`{“command”: “/model claude-sonnet-4”}`- ACP: the IDE sends the slash command as a prompt; the agent dispatches it - API server: include a`model`field in the request body or set`X-Hermes-Model`Provider-aware resolution (the same model name picks the right format for whatever provider you're on) is built in. See`hermes_cli/model_switch.py`. --- ## A note on` –mode rpc`Hermes does not have a`–mode rpcflag. The three protocols above already cover the use cases — ACP for IDE-protocol clients, the TUI gateway for stdio JSON-RPC hosts, and the API server for HTTP. If you find a real gap that none of them fill, open an issue with the concrete consumer you're building. ---  # Tools Runtime # Tools Runtime Hermes tools are self-registering functions grouped into toolsets and executed through a central registry/dispatch system. Primary files: -tools/registry.py`-`model_tools.py`-`toolsets.py`-`tools/terminal_tool.py`-`tools/environments/`## Tool registration model Each tool module calls`registry.register(…)`at import time.`model_tools.py`is responsible for importing/discovering tool modules and building the schema list used by the model. ### How`registry.register()`works Every tool file in`tools/`calls`registry.register()at module level to declare itself. The function signature is: ```python registry.register( name="terminal", # Unique tool name (used in API schemas) toolset="terminal", # Toolset this tool belongs to schema={...}, # OpenAI function-calling schema (description, parameters) handler=handle_terminal, # The function that executes when the tool is called check_fn=check_terminal, # Optional: returns True/False for availability requires_env=["SOME_VAR"], # Optional: env vars needed (for UI display) is_async=False, # Whether the handler is an async coroutine description="Run commands", # Human-readable description emoji="💻", # Emoji for spinner/progress display ) ``` Each call creates aToolEntry`stored in the singleton`ToolRegistry._tools`dict keyed by tool name. If a name collision occurs across toolsets, a warning is logged and the later registration wins. ### Discovery:`discover_builtin_tools()`When`model_tools.py`is imported, it calls`discover_builtin_tools()`from`tools/registry.py`. This function scans every` tools/.py`file using AST parsing to find modules that contain top-level`registry.register()calls, then imports them: ```python # tools/registry.py (simplified) def discover_builtin_tools(tools_dir=None): tools_path = Path(tools_dir) if tools_dir else Path(file).parent for path in sorted(tools_path.glob(".py")): if path.name in {"init.py", "registry.py", "mcp_tool.py"}: continue if _module_registers_tools(path): # AST check for top-level registry.register() importlib.import_module(f"tools.{path.stem}") ``` This auto-discovery means new tool files are picked up automatically — no manual list to maintain. The AST check only matches top-levelregistry.register()`calls (not calls inside functions), so helper modules in`tools/`are not imported. Each import triggers the module's`registry.register()`calls. Errors in optional tools (e.g., missing`fal_client`for image generation) are caught and logged — they don't prevent other tools from loading. After core tool discovery, MCP tools and plugin tools are also discovered: 1. MCP tools —`tools.mcp_tool.discover_mcp_tools()`reads MCP server config and registers tools from external servers. 2. Plugin tools —`hermes_cli.plugins.discover_plugins() `loads user/project/pip plugins that may register additional tools. ## Tool availability checking (`check_fn`) Each tool can optionally provide a` check_fn`— a callable that returns`True`when the tool is available and`False`otherwise. Typical checks include: - API key present — e.g.,`lambda: bool(os.environ.get(“SERP_API_KEY”))`for web search - Service running — e.g., checking if the Honcho server is configured - Binary installed — e.g., verifying`playwright`is available for browser tools When`registry.get_definitions()`builds the schema list for the model, it runs each tool's`check_fn(): ```python # Simplified from registry.py if entry.check_fn: try: available = bool(entry.check_fn()) except Exception: available = False # Exceptions = unavailable if not available: continue # Skip this tool entirely ``` Key behaviors: - Check results are cached per-call — if multiple tools share the same check_fn`, it only runs once. - Exceptions in` check_fn()`are treated as "unavailable" (fail-safe). - The`is_toolset_available()`method checks whether a toolset's`check_fn `passes, used for UI display and toolset resolution. ## Toolset resolution Toolsets are named bundles of tools. Hermes resolves them through: - explicit enabled/disabled toolset lists - platform presets (`hermes-cli`,` hermes-telegram`, etc.) - dynamic MCP toolsets - curated special-purpose sets like` hermes-acp`### How`get_tool_definitions()`filters tools The main entry point is`model_tools.get_tool_definitions(enabled_toolsets, disabled_toolsets, quiet_mode)`: 1. If` enabled_toolsets`is provided — only tools from those toolsets are included. Each toolset name is resolved via`resolve_toolset()`which expands composite toolsets into individual tool names. 2. If`disabled_toolsets`is provided — start with ALL toolsets, then subtract the disabled ones. 3. If neither — include all known toolsets. 4. Registry filtering — the resolved tool name set is passed to`registry.get_definitions()`, which applies` check_fn`filtering and returns OpenAI-format schemas. 5. Dynamic schema patching — after filtering,`execute_code`and`browser_navigate`schemas are dynamically adjusted to only reference tools that actually passed filtering (prevents model hallucination of unavailable tools). ### Legacy toolset names Old toolset names with`_tools`suffixes (e.g.,`web_tools`,` terminal_tools`) are mapped to their modern tool names via` _LEGACY_TOOLSET_MAP`for backward compatibility. ## Dispatch At runtime, tools are dispatched through the central registry, with agent-loop exceptions for some agent-level tools such as memory/todo/session-search handling. ### Dispatch flow: model tool_call → handler execution When the model returns a`tool_call, the flow is: ``` Model response with tool_call ↓ run_agent.py agent loop ↓ model_tools.handle_function_call(name, args, task_id, user_task) ↓ [Agent-loop tools?] → handled directly by agent loop (todo, memory, session_search, delegate_task) ↓ [Plugin pre-hook] → invoke_hook("pre_tool_call", ...) ↓ registry.dispatch(name, args, kwargs) ↓ Look up ToolEntry by name ↓ [Async handler?] → bridge via _run_async() [Sync handler?] → call directly ↓ Return result string (or JSON error) ↓ [Plugin post-hook] → invoke_hook("post_tool_call", ...) ``` ### Error wrapping All tool execution is wrapped in error handling at two levels: 1. registry.dispatch()` — catches any exception from the handler and returns` {“error”: “Tool execution failed: ExceptionType: message”} `as JSON. 2. `handle_function_call()` — wraps the entire dispatch in a secondary try/except that returns` {“error”: “Error executing tool_name: message”}`. This ensures the model always receives a well-formed JSON string, never an unhandled exception. ### Agent-loop tools Four tools are intercepted before registry dispatch because they need agent-level state (TodoStore, MemoryStore, etc.): -` todo`— planning/task tracking -`memory`— persistent memory writes -`session_search`— cross-session recall -`delegate_task`— spawns subagent sessions These tools' schemas are still registered in the registry (for`get_tool_definitions`), but their handlers return a stub error if dispatch somehow reaches them directly. ### Async bridging When a tool handler is async,` _run_async()`bridges it to the sync dispatch path: - CLI path (no running loop) — uses a persistent event loop to keep cached async clients alive - Gateway path (running loop) — spins up a disposable thread with`asyncio.run()`- Worker threads (parallel tools) — uses per-thread persistent loops stored in thread-local storage ## The DANGEROUS_PATTERNS approval flow The terminal tool integrates a dangerous-command approval system defined in`tools/approval.py`: 1. Pattern detection —` DANGEROUS_PATTERNS`is a list of`(regex, description) `tuples covering destructive operations: - Recursive deletes (`rm -rf`) - Filesystem formatting (`mkfs`,` dd`) - SQL destructive operations (`DROP TABLE`,` DELETE FROM`without`WHERE`) - System config overwrites (`> /etc/`) - Service manipulation (`systemctl stop`) - Remote code execution (`curl | sh`) - Fork bombs, process kills, etc. 2. Detection — before executing any terminal command,` detect_dangerous_command(command)`checks against all patterns. 3. Approval prompt — if a match is found: - CLI mode — an interactive prompt asks the user to approve, deny, or allow permanently - Gateway mode — an async approval callback sends the request to the messaging platform - Smart approval — optionally, an auxiliary LLM can auto-approve low-risk commands that match patterns (e.g.,`rm -rf node_modules/`is safe but matches "recursive delete") 4. Session state — approvals are tracked per-session. Once you approve "recursive delete" for a session, subsequent`rm -rf`commands don't re-prompt. 5. Permanent allowlist — the "allow permanently" option writes the pattern to`config.yaml`'s` command_allowlist, persisting across sessions. ## Terminal/runtime environments The terminal system supports multiple backends: - local - docker - ssh - singularity - modal - daytona It also supports: - per-task cwd overrides - background process management - PTY mode - approval callbacks for dangerous commands ## Concurrency Tool calls may execute sequentially or concurrently depending on the tool mix and interaction requirements. ## Related docs - [Toolsets Reference](../reference/toolsets-reference.md) - [Built-in Tools Reference](../reference/tools-reference.md) - [Agent Loop Internals](./agent-loop.md) - [ACP Internals](./acp-internals.md) ---  # developer-guide/trajectory-format.md # Trajectory Format Hermes Agent saves conversation trajectories in ShareGPT-compatible JSONL format for use as training data, debugging artifacts, and reinforcement learning datasets. Source files: agent/trajectory.py`,` run_agent.py`(search for`_save_trajectory`),` batch_runner.py`## File Naming Convention Trajectories are written to files in the current working directory: | File | When | |------|------| |`trajectory_samples.jsonl `| Conversations that completed successfully (`completed=True`) | |` failed_trajectories.jsonl `| Conversations that failed or were interrupted (`completed=False`) | The batch runner (`batch_runner.py`) writes to a custom output file per batch (e.g.,` batch_001_output.jsonl`) with additional metadata fields. You can override the filename via the` filename`parameter in`save_trajectory()`. ## JSONL Entry Format Each line in the file is a self-contained JSON object. There are two variants: ### CLI/Interactive Format (from` _save_trajectory) ```json { "conversations": [ ... ], "timestamp": "2026-03-30T14:22:31.456789", "model": "anthropic/claude-sonnet-4.6", "completed": true } ``` ### Batch Runner Format (from batch_runner.py) ```json { "prompt_index": 42, "conversations": [ ... ], "metadata": { "prompt_source": "gsm8k", "difficulty": "hard" }, "completed": true, "partial": false, "api_calls": 7, "toolsets_used": ["code_tools", "file_tools"], "tool_stats": { "terminal": {"count": 3, "success": 3, "failure": 0}, "read_file": {"count": 2, "success": 2, "failure": 0}, "write_file": {"count": 0, "success": 0, "failure": 0} }, "tool_error_counts": { "terminal": 0, "read_file": 0, "write_file": 0 } } ``` The tool_stats`and`tool_error_counts`dictionaries are normalized to include ALL possible tools (from`model_tools.TOOL_TO_TOOLSET_MAP`) with zero defaults, ensuring consistent schema across entries for HuggingFace dataset loading. ## Conversations Array (ShareGPT Format) The` conversations`array uses ShareGPT role conventions: | API Role | ShareGPT`from`| |----------|-----------------| | system |`“system”`| | user |`“human”`| | assistant |`“gpt”`| | tool |`“tool”| ### Complete Example ```json { "conversations": [ { "from": "system", "value": "You are a function calling AI model. You are provided with function signatures within <tools> </tools> XML tags. You may call one or more functions to assist with the user query. If available tools are not relevant in assisting with user query, just respond in natural conversational language. Don't make assumptions about what values to plug into functions. After calling & executing the functions, you will be provided with function results within <tool_response> </tool_response> XML tags. Here are the available tools:\n<tools>\n[{\"name\": \"terminal\", \"description\": \"Execute shell commands\", \"parameters\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}}, \"required\": null}]\n</tools>\nFor each function call return a JSON object, with the following pydantic model json schema for each:\n{'title': 'FunctionCall', 'type': 'object', 'properties': {'name': {'title': 'Name', 'type': 'string'}, 'arguments': {'title': 'Arguments', 'type': 'object'}}, 'required': ['name', 'arguments']}\nEach function call should be enclosed within <tool_call> </tool_call> XML tags.\nExample:\n<tool_call>\n{'name': <function-name>,'arguments': <args-dict>}\n</tool_call>" }, { "from": "human", "value": "What Python version is installed?" }, { "from": "gpt", "value": "<think>\nThe user wants to know the Python version. I should run python3 --version.\n</think>\n<tool_call>\n{\"name\": \"terminal\", \"arguments\": {\"command\": \"python3 --version\"}}\n</tool_call>" }, { "from": "tool", "value": "<tool_response>\n{\"tool_call_id\": \"call_abc123\", \"name\": \"terminal\", \"content\": \"Python 3.11.6\"}\n</tool_response>" }, { "from": "gpt", "value": "<think>\nGot the version. I can now answer the user.\n</think>\nPython 3.11.6 is installed on this system." } ], "timestamp": "2026-03-30T14:22:31.456789", "model": "anthropic/claude-sonnet-4.6", "completed": true } ``` ## Normalization Rules ### Reasoning Content Markup The trajectory converter normalizes ALL reasoning into `tags, regardless of how the model originally produced it: 1. Native thinking tokens (`msg[“reasoning”]`field from providers like Anthropic, OpenAI o-series): Wrapped as`\n{reasoning}\n\n`and prepended before the content. 2. REASONING_SCRATCHPAD XML (when native thinking is disabled and the model reasons via system-prompt-instructed XML):`<REASONING_SCRATCHPAD>`tags are converted tovia`convert_scratchpad_to_think()`. 3. Empty think blocks: Every` gpt`turn is guaranteed to have ablock. If no reasoning was produced, an empty block is inserted:`\n\n`— this ensures consistent format for training data. ### Tool Call Normalization Tool calls from the API format (with`tool_call_id, function name, arguments as JSON string) are converted to XML-wrapped JSON: ``` <tool_call> {"name": "terminal", "arguments": {"command": "ls -la"}} </tool_call> ``` - Arguments are parsed from JSON strings back to objects (not double-encoded) - If JSON parsing fails (shouldn't happen — validated during conversation), an empty {}`is used with a warning logged - Multiple tool calls in one assistant turn produce multiple`<tool_call>`blocks in a single`gpt`message ### Tool Response Normalization All tool results following an assistant message are grouped into a single`toolturn with XML-wrapped JSON responses: ``` <tool_response> {"tool_call_id": "call_abc123", "name": "terminal", "content": "output here"} </tool_response> ``` - If tool content looks like JSON (starts with{`or`[`), it's parsed so the content field contains a JSON object/array rather than a string - Multiple tool results are joined with newlines in one message - The tool name is matched by position against the parent assistant's` tool_calls`array ### System Message The system message is generated at save time (not taken from the conversation). It follows the Hermes function-calling prompt template with: - Preamble explaining the function-calling protocol -XML block containing the JSON tool definitions - Schema reference for`FunctionCall`objects -`<tool_call>`example Tool definitions include`name`,` description`,` parameters`, and` required`(set to`nullto match the canonical format). ## Loading Trajectories Trajectories are standard JSONL — load with any JSON-lines reader: ```python import json def load_trajectories(path: str): """Load trajectory entries from a JSONL file.""" entries = [] with open(path, "r", encoding="utf-8") as f: for line in f: line = line.strip() if line: entries.append(json.loads(line)) return entries # Filter to successful completions only successful = [e for e in load_trajectories("trajectory_samples.jsonl") if e.get("completed")] # Extract just the conversations for training training_data = [e["conversations"] for e in successful] ``` ### Loading for HuggingFace Datasets ```python from datasets import load_dataset ds = load_dataset("json", data_files="trajectory_samples.jsonl") ``` The normalizedtool_statsschema ensures all entries have the same columns, preventing Arrow schema mismatch errors during dataset loading. ## Controlling Trajectory Saving In the CLI, trajectory saving is controlled by: ```yaml # config.yaml agent: save_trajectories: true # default: false ``` Or via the–save-trajectories`flag. When the agent initializes with`save_trajectories=True`, the` _save_trajectory()method is called at the end of each conversation turn. The batch runner always saves trajectories (that's its primary purpose). Samples with zero reasoning across all turns are automatically discarded by the batch runner to avoid polluting training data with non-reasoning examples. ---  # Video Generation Provider Plugins # Building a Video Generation Provider Plugin Video-gen provider plugins register a backend that services everyvideo_generate`tool call. Built-in providers (xAI, FAL) ship as plugins. Add a new one, or override a bundled one, by dropping a directory into`plugins/video_gen//`. :::tip Video-gen mirrors [Image Generation Provider Plugins](/developer-guide/image-gen-provider-plugin) almost line-for-line — if you've built an image-gen backend, you already know the shape. The main differences: a` capabilities()`method advertising modalities/aspect-ratios/durations, and a routing convention (pass`image_url`to use image-to-video, omit it to use text-to-video — the provider picks the right endpoint internally). ::: ## The unified surface (one tool, two modalities) The`video_generate`tool exposes two modalities through one parameter: - Text-to-video — call with`prompt`only. The provider routes to its text-to-video endpoint. - Image-to-video — call with`prompt`+`image_url`. The provider routes to its image-to-video endpoint. Edit and extend are intentionally out of scope. Most backends don't support them and the inconsistency would force per-backend prose into the agent's tool description. ## How discovery works Hermes scans for video-gen backends in three places: 1. Bundled —` /plugins/video_gen//`(auto-loaded with`kind: backend`) 2. User —` /.hermes/plugins/video_gen//`(opt-in via`plugins.enabled`) 3. Pip** — packages declaring a` hermes_agent.plugins`entry point Each plugin's`register(ctx)`function calls`ctx.register_video_gen_provider(…)`. The active provider is picked by` video_gen.provider`in`config.yaml`;` hermes tools`→ Video Generation walks users through selection. Unlike`image_generate, there is no in-tree legacy backend — every provider is a plugin. ## Directory structure ``` plugins/video_gen/my-backend/ ├── init.py # VideoGenProvider subclass + register() └── plugin.yaml # Manifest with kind: backend ``` ## The VideoGenProvider ABC Subclass agent.video_gen_provider.VideoGenProvider`. Required:` name`property and`generate()method. ```python # plugins/video_gen/my-backend/init.py from typing import Any, Dict, List, Optional import os from agent.video_gen_provider import ( VideoGenProvider, error_response, success_response, ) class MyVideoGenProvider(VideoGenProvider): @property def name(self) -> str: return "my-backend" @property def display_name(self) -> str: return "My Backend" def is_available(self) -> bool: return bool(os.environ.get("MY_API_KEY")) def list_models(self) -> List[Dict[str, Any]]: # Each entry is a model FAMILY — a name the user picks once. # Your provider's generate() routes within the family based on # whether image_url was passed. return [ { "id": "fast", "display": "Fast", "speed": "~30s", "strengths": "Cheapest tier", "price": "$0.05/s", "modalities": ["text", "image"], # advisory }, ] def default_model(self) -> Optional[str]: return "fast" def capabilities(self) -> Dict[str, Any]: return { "modalities": ["text", "image"], "aspect_ratios": ["16:9", "9:16"], "resolutions": ["720p", "1080p"], "min_duration": 1, "max_duration": 10, "supports_audio": False, "supports_negative_prompt": True, "max_reference_images": 0, } def get_setup_schema(self) -> Dict[str, Any]: return { "name": "My Backend", "badge": "paid", "tag": "Short description shown inhermes tools", "env_vars": [ { "key": "MY_API_KEY", "prompt": "My Backend API key", "url": "https://mybackend.example.com/keys", }, ], } def generate( self, prompt: str, *, model: Optional[str] = None, image_url: Optional[str] = None, reference_image_urls: Optional[List[str]] = None, duration: Optional[int] = None, aspect_ratio: str = "16:9", resolution: str = "720p", negative_prompt: Optional[str] = None, audio: Optional[bool] = None, seed: Optional[int] = None, kwargs: Any, # always ignore unknown kwargs for forward-compat ) -> Dict[str, Any]: # ROUTE: image_url presence picks the endpoint. if image_url: endpoint = "my-backend/image-to-video" modality_used = "image" else: endpoint = "my-backend/text-to-video" modality_used = "text" # ... call your API ... return success_response( video="https://your-cdn/output.mp4", model=model or "fast", prompt=prompt, modality=modality_used, aspect_ratio=aspect_ratio, duration=duration or 5, provider=self.name, ) def register(ctx) -> None: ctx.register_video_gen_provider(MyVideoGenProvider()) ``` ## The plugin manifest ```yaml # plugins/video_gen/my-backend/plugin.yaml name: my-backend version: 1.0.0 description: "My video generation backend" author: Your Name kind: backend requires_env: - MY_API_KEY ``` ## The video_generate`schema The tool exposes one schema across every backend. Providers ignore parameters they don't support. | Parameter | What it does | |---|---| |`prompt`| Text instruction (required) | |`image_url`| When set → image-to-video; when omitted → text-to-video | |`reference_image_urls`| Style/character refs (provider-dependent) | |`duration`| Seconds — provider clamps | |`aspect_ratio`|`“16:9”`,` “9:16”`,` “1:1”`, ... — provider clamps | |` resolution`|`“480p”`/`“540p”`/`“720p”`/`“1080p”`— provider clamps | |`negative_prompt`| Content to avoid (Pixverse/Kling only) | |`audio`| Native audio (Veo3 / Pixverse pricing tier) | |`seed`| Reproducibility | |`model`| Override the active model/family | The provider's`capabilities()`advertises which of these are honored. The agent sees the active backend's capabilities in the tool description, dynamically rebuilt when the user changes backend via`hermes tools`. ## Model families and endpoint routing (the FAL pattern) When your backend has multiple endpoints per "model" — like FAL, where every family (Veo 3.1, Pixverse v6, Kling O3) has both a` /text-to-video`and an`/image-to-video`URL — represent each family** as one catalog entry. Your`generate()`picks the right endpoint based on whether`image_urlwas passed: ```python FAMILIES = { "veo3.1": { "text_endpoint": "fal-ai/veo3.1", "image_endpoint": "fal-ai/veo3.1/image-to-video", # ... family-specific capability flags ... }, } def generate(self, prompt, *, image_url=None, model=None, kwargs): family_id, family = _resolve_family(model) endpoint = family["image_endpoint"] if image_url else family["text_endpoint"] # ... build payload from family's declared capability flags, call endpoint ... ``` The user picksveo3.1`once in`hermes tools`. The agent never thinks about endpoints — it just passes (or doesn't pass)` image_url`. ## Selection precedence For per-instance model knobs (see` plugins/video_gen/fal/init.py`): 1.` model=`keyword from the tool call 2.`VIDEO_MODEL`env var 3.`video_gen..model`in`config.yaml`4.`video_gen.model`in`config.yaml`(when it's one of your IDs) 5. Provider's`default_model()`## Response shape`success_response()`and`error_response()`produce the dict shape every backend returns. Use them — don't hand-roll the dict. Success keys:`success`,` video`(URL or absolute path),`model`,` prompt`,` modality `(`“text”`or`“image”`),` aspect_ratio`,` duration`,` provider`, plus` extra`. Error keys:` success`,` video`(None),`error`,` error_type`,` model`,` prompt`,` aspect_ratio`,` provider`. ## Where to save artifacts If your backend returns base64, use` save_b64_video()`to write under`(echo -n ‘{“service”:“api”,“environment”:“prod”,“version”:“2.1.0”,“deployer”:“ci”,“health_url”:“https://api.example.com/health”}’ | openssl dgst -sha256 -hmac ‘your-secret’ | cut -d’ ’ -f2)“ \ -d ‘{“service”:“api”,“environment”:“prod”,“version”:“2.1.0”,“deployer”:“ci”,“health_url”:“https://api.example.com/health”}’ `### Alert Triage Correlate monitoring alerts with recent changes to draft a response. Works with Datadog, PagerDuty, Grafana, or any alerting system that can POST JSON. Trigger: API call (webhook)`bash hermes webhook subscribe alert-triage \ –prompt “Monitoring alert received: Alert: {alert.name} Severity: {alert.severity} Service: {alert.service} Message: {alert.message} Timestamp: {alert.timestamp} Investigate: 1. Search the web for known issues with this error pattern 2. Check if this correlates with any recent deployments or config changes 3. Draft a triage summary with: - Likely root cause - Suggested first response steps - Escalation recommendation (P1-P4) Be concise. This goes to the on-call channel.” \ –deliver slack `### Uptime Monitor Check endpoints every 30 minutes. Only notify when something is down. Trigger:** Schedule (every 30 min)`python title=“/.hermes/scripts/check-uptime.py” import urllib.request, json, time ENDPOINTS = [ {“name”: “API”, “url”: “https://api.example.com/health”}, {“name”: “Web”, “url”: “https://www.example.com”}, {“name”: “Docs”, “url”: “https://docs.example.com”}, ] results = [] for ep in ENDPOINTS: try: start = time.time() req = urllib.request.Request(ep[“url”], headers={“User-Agent”: “Hermes-Monitor/1.0”}) resp = urllib.request.urlopen(req, timeout=10) elapsed = round((time.time() - start) * 1000) results.append({“name”: ep[“name”], “status”: resp.getcode(), “ms”: elapsed}) except Exception as e: results.append({“name”: ep[“name”], “status”: “DOWN”, “error”: str(e)}) down = [r for r in results if r.get(“status”) == “DOWN” or (isinstance(r.get(“status”), int) and r[“status”] >= 500)] if down: print(“OUTAGE DETECTED”) for r in down: print(f“ {r[‘name’]}: {r.get(‘error’, f’HTTP {r["status"]}’)} “) print(f”\nAll results: {json.dumps(results, indent=2)}“) else: print(“NO_ISSUES”) bash hermes cron create “every 30m” \ “If the script reports OUTAGE DETECTED, summarize which services are down and suggest likely causes. If NO_ISSUES, respond with [SILENT].” \ –script /.hermes/scripts/check-uptime.py \ –name “Uptime monitor” \ –deliver telegram `--- ## Research & Intelligence ### Competitive Repository Scout Monitor competitor repos for interesting PRs, features, and architectural decisions. Trigger: Schedule (daily)`bash hermes cron create “0 8 * * ” \ “Scout these AI agent repositories for notable activity in the last 24 hours: Repos to check: - anthropics/claude-code - openai/codex - All-Hands-AI/OpenHands - Aider-AI/aider For each repo: 1. gh pr list –repo –state all –json number,title,author,createdAt,mergedAt –limit 15 2. gh issue list –repo –state open –json number,title,labels,createdAt –limit 10 Focus on: - New features being developed - Architectural changes - Integration patterns we could learn from - Security fixes that might affect us too Skip routine dependency bumps and CI fixes. If nothing notable, respond with [SILENT]. If there are findings, organize by repo with brief analysis of each item.” \ –skill competitive-pr-scout \ –name “Competitor scout” \ –deliver telegram `### AI News Digest Weekly roundup of AI/ML developments. Trigger: Schedule (weekly)`bash hermes cron create “0 9 * 1” \ “Generate a weekly AI news digest covering the past 7 days: 1. Search the web for major AI announcements, model releases, and research breakthroughs 2. Search for trending ML repositories on GitHub 3. Check arXiv for highly-cited papers on language models and agents Structure: ## Headlines (3-5 major stories) ## Notable Papers (2-3 papers with one-sentence summaries) ## Open Source (interesting new repos or major releases) ## Industry Moves (funding, acquisitions, launches) Keep each item to 1-2 sentences. Include links. Total under 600 words.” \ –name “Weekly AI digest” \ –deliver telegram `### Paper Digest with Notes Daily arXiv scan that saves summaries to your note-taking system. Trigger: Schedule (daily)`bash hermes cron create “0 8 * * ” \ “Search arXiv for the 3 most interesting papers on ‘language model reasoning’ OR ‘tool-use agents’ from the past day. For each paper, create an Obsidian note with the title, authors, abstract summary, key contribution, and potential relevance to Hermes Agent development.” \ –skill arxiv –skill obsidian \ –name “Paper digest” \ –deliver local `--- ## GitHub Event Automations ### Issue Auto-Labeling Automatically label and respond to new issues. Trigger: GitHub webhook`bash hermes webhook subscribe github-issues \ –events “issues” \ –prompt “New GitHub issue received: Repository: {repository.full_name} Issue #{issue.number}: {issue.title} Author: {issue.user.login} Action: {action} Body: {issue.body} Labels: {issue.labels} If this is a new issue (action=opened): 1. Read the issue title and body carefully 2. Suggest appropriate labels (bug, feature, docs, security, question) 3. If it’s a bug report, check if you can identify the affected component from the description 4. Post a helpful initial response acknowledging the issue If this is a label or assignment change, respond with [SILENT].” \ –deliver github_comment `### CI Failure Analysis Analyze CI failures and post diagnostics on the PR. Trigger: GitHub webhook`yaml # config.yaml route platforms: webhook: enabled: true extra: routes: ci-failure: events: [“check_run”] secret: “ci-secret” prompt: | CI check failed: Repository: {repository.full_name} Check: {check_run.name} Status: {check_run.conclusion} PR: #{check_run.pull_requests.0.number} Details URL: {check_run.details_url} If conclusion is “failure”: 1. Fetch the log from the details URL if accessible 2. Identify the likely cause of failure 3. Suggest a fix If conclusion is “success”, respond with [SILENT]. deliver: “github_comment” deliver_extra: repo: “{repository.full_name}” pr_number: “{check_run.pull_requests.0.number}” `### Auto-Port Changes Across Repos When a PR merges in one repo, automatically port the equivalent change to another. Trigger: GitHub webhook`bash hermes webhook subscribe auto-port \ –events “pull_request” \ –prompt “PR merged in the source repository: Repository: {repository.full_name} PR #{pull_request.number}: {pull_request.title} Author: {pull_request.user.login} Action: {action} Merge commit: {pull_request.merge_commit_sha} If action is ‘closed’ and pull_request.merged is true: 1. Fetch the diff: curl -sL {pull_request.diff_url} 2. Analyze what changed 3. Determine if this change needs to be ported to the Go SDK equivalent 4. If yes, create a branch, apply the equivalent changes, and open a PR on the target repo 5. Reference the original PR in the new PR description If action is not ‘closed’ or not merged, respond with [SILENT].” \ –skill github-pr-workflow \ –deliver log `--- ## Business Operations ### Stripe Payment Monitoring Track payment events and get summaries of failures. Trigger: API call (webhook)`bash hermes webhook subscribe stripe-payments \ –events “payment_intent.succeeded,payment_intent.payment_failed,charge.dispute.created” \ –prompt “Stripe event received: Event type: {type} Amount: {data.object.amount} cents ({data.object.currency}) Customer: {data.object.customer} Status: {data.object.status} For payment_intent.payment_failed: - Identify the failure reason from {data.object.last_payment_error} - Suggest whether this is a transient issue (retry) or permanent (contact customer) For charge.dispute.created: - Flag as urgent - Summarize the dispute details For payment_intent.succeeded: - Brief confirmation only Keep responses concise for the ops channel.” \ –deliver slack `### Daily Revenue Summary Compile key business metrics every morning. Trigger: Schedule (daily)`bash hermes cron create “0 8 * ” \ “Generate a morning business metrics summary. Search the web for: 1. Current Bitcoin and Ethereum prices 2. S&P 500 status (pre-market or previous close) 3. Any major tech/AI industry news from the last 12 hours Format as a brief morning briefing, 3-4 bullet points max. Deliver as a clean, scannable message.” \ –name “Morning briefing” \ –deliver telegram `--- ## Multi-Skill Workflows ### Security Audit Pipeline Combine multiple skills for a comprehensive weekly security review. Trigger: Schedule (weekly)`bash hermes cron create “0 3 * * 0” \ “Run a comprehensive security audit of the hermes-agent codebase. 1. Check for dependency vulnerabilities (pip audit, npm audit) 2. Search the codebase for common security anti-patterns: - Hardcoded secrets or API keys - SQL injection vectors (string formatting in queries) - Path traversal risks (user input in file paths without validation) - Unsafe deserialization (pickle.loads, yaml.load without SafeLoader) 3. Review recent commits (last 7 days) for security-relevant changes 4. Check if any new environment variables were added without being documented Write a security report with findings categorized by severity (Critical, High, Medium, Low). If nothing found, report a clean bill of health.” \ –skill codebase-security-audit \ –name “Weekly security audit” \ –deliver telegram `### Content Pipeline Research, draft, and prepare content on a schedule. Trigger: Schedule (weekly)`bash hermes cron create “0 10 * * 3” \ “Research and draft a technical blog post outline about a trending topic in AI agents. 1. Search the web for the most discussed AI agent topics this week 2. Pick the most interesting one that’s relevant to open-source AI agents 3. Create an outline with: - Hook/intro angle - 3-4 key sections - Technical depth appropriate for developers - Conclusion with actionable takeaway 4. Save the outline to ~/drafts/blog-(free | awk ‘/^Mem:/ {printf “%d”, $3 * 100 / $2}’) if [ “$ram_pct” -ge 85 ]; then echo “RAM ${ram_pct}% on $(hostname)" fi # Empty stdout = silent tick; no message sent. ''', ) # 2. Schedule it — no_agent=True skips the LLM on every tick cronjob( action="create", schedule="every 5m", script="memory-watchdog.sh", no_agent=True, deliver="telegram", name="memory-watchdog", ) ``` From that point on every tick is free: the scheduler runs the script, pipes its stdout to Telegram if non-empty, and never touches a model. ### What the agent decides for you When you phrase a request like "alert me when X" or "every N minutes check Y and tell me if Z", Hermes' `cronjob` tool description tells it to reach for `no_agent=True` whenever the message content is fully determined by the script. It falls back to the normal LLM-driven path when the request needs reasoning ("summarize the new issues", "pick the most interesting headlines", "draft a friendly reminder"). You don't have to specify `--no-agent` yourself. Just describe the behavior. ### Managing watchdogs from chat The agent can pause, resume, edit, and remove jobs the same way it creates them: > You: stop the memory watchdog for tonight > > Hermes: (calls `cronjob(action='pause', job_id='abc123')`) > > Paused. Resume with "turn it back on" or via `hermes cron resume abc123`. > You: change it to every 15 minutes > > Hermes: (calls `cronjob(action='update', job_id='abc123', schedule='every 15m')`) The full lifecycle (create / list / update / pause / resume / run-now / remove) is available to the agent without you learning any CLI commands. ## Create One from the CLI Prefer the shell? The CLI path gives you the same result with three commands: ```bash # 1. Write your script cat > ~/.hermes/scripts/memory-watchdog.sh <<'EOF' #!/usr/bin/env bash # Alert when RAM usage is over 85%. Silent otherwise. RAM_PCT=$ (free | awk ‘/^Mem:/ {printf “%d”, $3 * 100 / $2}’) if [ “$RAM_PCT” -ge 85 ]; then echo “⚠ RAM ${RAM_PCT}% on $(hostname)" fi # Empty stdout = silent run; no message sent. EOF chmod +x ~/.hermes/scripts/memory-watchdog.sh # 2. Schedule it hermes cron create "every 5m" \ --no-agent \ --script memory-watchdog.sh \ --deliver telegram \ --name "memory-watchdog" # 3. Verify hermes cron list hermes cron run <job_id> # fire it once to test ``` That's the whole thing. No prompt, no skill, no model. ## How Script Output Maps to Delivery | Script behavior | Result | |-----------------|--------| | Exit 0, non-empty stdout | stdout is delivered verbatim | | Exit 0, empty stdout | Silent tick — no delivery | | Exit 0, stdout contains `{"wakeAgent": false}` on the last line | Silent tick (shared gate with LLM jobs) | | Non-zero exit code | Error alert is delivered (so a broken watchdog doesn't fail silently) | | Script timeout | Error alert is delivered | The "silent when empty" behavior is the key to the classic watchdog pattern: the script is free to run every minute, but the channel only sees a message when something actually needs attention. ## Script Rules Scripts must live in `~/.hermes/scripts/`. This is enforced at both job-creation time and run time — absolute paths, `~/` expansion, and path-traversal patterns (`../`) are rejected. The same directory is shared with the pre-check script gate used by LLM jobs. Interpreter choice is by file extension: | Extension | Interpreter | |-----------|-------------| | `.sh`, `.bash` | `/bin/bash` | | anything else | `sys.executable` (current Python) | We intentionally do NOT honour `#!/...` shebangs — keeping the interpreter set explicit and small reduces the surface the scheduler trusts. ## Schedule Syntax Same as all other cron jobs: ```bash hermes cron create "every 5m" # interval hermes cron create "every 2h" hermes cron create "0 9 * * " # standard cron: 9am daily hermes cron create "30m" # one-shot: run once in 30 minutes ``` See the [cron feature reference](/user-guide/features/cron) for the full syntax. ## Delivery Targets `--deliver` accepts everything the gateway knows about. Some common shapes: ```bash --deliver telegram # platform home channel --deliver telegram:-1001234567890 # specific chat --deliver telegram:-1001234567890:17585 # specific Telegram forum topic --deliver discord:#ops --deliver slack:#engineering --deliver signal:+15551234567 --deliver local # just save to ~/.hermes/cron/output/ ``` No running gateway is required at script-run time for bot-token platforms (Telegram, Discord, Slack, Signal, SMS, WhatsApp) — the tool calls each platform's REST endpoint directly using the credentials already in `~/.hermes/.env` / `~/.hermes/config.yaml`. ## Editing and Lifecycle ```bash hermes cron list # see all jobs hermes cron pause <job_id> # stop firing, keep definition hermes cron resume <job_id> hermes cron edit <job_id> --schedule "every 10m" # adjust cadence hermes cron edit <job_id> --agent # flip to LLM mode hermes cron edit <job_id> --no-agent --script … # flip back hermes cron remove <job_id> # delete it ``` Everything that works on LLM jobs (pause, resume, manual trigger, delivery target changes) works on no-agent jobs too. ## Worked Example: Disk Space Alert ```bash cat > ~/.hermes/scripts/disk-alert.sh <<'EOF' #!/usr/bin/env bash # Alert when / or /home is over 90% full. THRESHOLD=90 df -h / /home 2>/dev/null | awk -v t="$ THRESHOLD” ’ NR > 1 && $5+0 >= t { printf “⚠ Disk %s full on %s\n”, $5, $6 } ’ EOF chmod +x ~/.hermes/scripts/disk-alert.sh hermes cron create “/15 * * ” \ –no-agent \ –script disk-alert.sh \ –deliver telegram \ –name “disk-alert” Silent when both filesystems are under 90%; fires exactly one line per over-threshold filesystem when one fills up. ## Comparison with Other Patterns | Approach | What runs | When to use | |----------|-----------|-------------| | `cronjob --no-agent` (this page) | Your script on Hermes' schedule | Recurring watchdogs / alerts / metrics that don't need reasoning | | `cronjob` (default, LLM) | Agent with optional pre-check script | When the message content requires reasoning over data | | OS cron + `curl` to a [webhook subscription](/user-guide/messaging/webhooks) | Your script on the OS schedule | When Hermes might be unhealthy (the thing you're monitoring) | For critical system-health watchdogs that must fire even when the gateway is down, use OS-level cron with a plain `curl` to a Hermes webhook subscription (or any external alerting endpoint) — those run as independent OS processes and don't depend on Hermes being up. The in-gateway scheduler is the right choice when the thing being monitored is external. ## Related - [Automate Anything with Cron](/guides/automate-with-cron) — LLM-driven cron patterns. - [Scheduled Tasks (Cron) reference](/user-guide/features/cron) — full schedule syntax, lifecycle, delivery routing. - [Webhook Subscriptions](/user-guide/messaging/webhooks) — fire-and-forget HTTP entry points for external schedulers. - [Gateway Internals](/developer-guide/gateway-internals) — delivery-router internals. ---  # Cron Troubleshooting # Cron Troubleshooting When a cron job isn't behaving as expected, work through these checks in order. Most issues fall into one of four categories: timing, delivery, permissions, or skill loading. --- ## Jobs Not Firing ### Check 1: Verify the job exists and is activebash hermes cron list Look for the job and confirm its state is `[active]` (not `[paused]` or `[completed]`). If it shows `[completed]`, the repeat count may be exhausted — edit the job to reset it. ### Check 2: Confirm the schedule is correct A misformatted schedule silently defaults to one-shot or is rejected entirely. Test your expression: | Your expression | Should evaluate to | |----------------|-------------------| | `0 9 * ` | 9:00 AM every day | | `0 9 * 1` | 9:00 AM every Monday | | `every 2h` | Every 2 hours from now | | `30m` | 30 minutes from now | | `2025-06-01T09:00:00` | June 1, 2025 at 9:00 AM UTC | If the job fires once and then disappears from the list, it's a one-shot schedule (`30m`, `1d`, or an ISO timestamp) — expected behavior. ### Check 3: Is the gateway running? Cron jobs are fired by the gateway's background ticker thread, which ticks every 60 seconds. A regular CLI chat session does not automatically fire cron jobs. If you're expecting jobs to fire automatically, you need a running gateway (`hermes gateway` for foreground, or `hermes gateway start` for the installed service). For one-off debugging, you can manually trigger a tick with `hermes cron tick`. ### Check 4: Check the system clock and timezone Jobs use the local timezone. If your machine's clock is wrong or in a different timezone than expected, jobs will fire at the wrong times. Verify:bash date hermes cron list # Compare next_run times with local time --- ## Delivery Failures ### Check 1: Verify the deliver target is correct Delivery targets are case-sensitive and require the correct platform to be configured. A misconfigured target silently drops the response. | Target | Requires | |--------|----------| | `telegram` | `TELEGRAM_BOT_TOKEN` in `~/.hermes/.env` | | `discord` | `DISCORD_BOT_TOKEN` in `~/.hermes/.env` | | `slack` | `SLACK_BOT_TOKEN` in `~/.hermes/.env` | | `whatsapp` | WhatsApp gateway configured | | `signal` | Signal gateway configured | | `matrix` | Matrix homeserver configured | | `email` | SMTP configured in `config.yaml` | | `sms` | SMS provider configured | | `local` | Write access to `~/.hermes/cron/output/` | | `origin` | Delivers to the chat where the job was created | Other supported platforms include `mattermost`, `homeassistant`, `dingtalk`, `feishu`, `wecom`, `weixin`, `bluebubbles`, `qqbot`, and `webhook`. You can also target a specific chat with `platform:chat_id` syntax (e.g., `telegram:-1001234567890`). If delivery fails, the job still runs — it just won't send anywhere. Check `hermes cron list` for updated `last_error` field (if available). ### Check 2: Check `[SILENT]` usage If your cron job produces no output or the agent responds with `[SILENT]`, delivery is suppressed. This is intentional for monitoring jobs — but make sure your prompt isn't accidentally suppressing everything. A prompt that says "respond with [SILENT] if nothing changed" will silently swallow non-empty responses too. Check your conditional logic. ### Check 3: Platform token permissions Each messaging platform bot needs specific permissions to receive messages. If delivery silently fails: - Telegram: Bot must be an admin in the target group/channel - Discord: Bot must have permission to send in the target channel - Slack: Bot must be added to the workspace and have `chat:write` scope ### Check 4: Response wrapping By default, cron responses are wrapped with a header and footer (`cron.wrap_response: true` in `config.yaml`). Some platforms or integrations may not handle this well. To disable:yaml cron: wrap_response: false `--- ## Skill Loading Failures ### Check 1: Verify skills are installed`bash hermes skills list Skills must be installed before they can be attached to cron jobs. If a skill is missing, install it first with `hermes skills install <skill-name>` or via `/skills` in the CLI. ### Check 2: Check skill name vs. skill folder name Skill names are case-sensitive and must match the installed skill's folder name. If your job specifies `ai-funding-daily-report` but the skill folder is `ai-funding-daily-report`, confirm the exact name from `hermes skills list`. ### Check 3: Skills that require interactive tools Cron jobs run with the `cronjob`, `messaging`, and `clarify` toolsets disabled. This prevents recursive cron creation, direct message sending (delivery is handled by the scheduler), and interactive prompts. If a skill relies on these toolsets, it won't work in a cron context. Check the skill's documentation to confirm it works in non-interactive (headless) mode. ### Check 4: Multi-skill ordering When using multiple skills, they load in order. If Skill A depends on context from Skill B, make sure B loads first:bash /cron add “0 9 * * ” “…” –skill context-skill –skill target-skill In this example, `context-skill` loads before `target-skill`. --- ## Job Errors and Failures ### Check 1: Review recent job output If a job ran and failed, you may see error context in: 1. The chat where the job delivers (if delivery succeeded) 2. `~/.hermes/logs/agent.log` for scheduler messages (or `errors.log` for warnings) 3. The job's `last_run` metadata via `hermes cron list` ### Check 2: Common error patterns "No such file or directory" for scripts The `script` path must be an absolute path (or relative to the Hermes config directory). Verify:bash ls /.hermes/scripts/your-script.py # Must exist hermes cron edit <job_id> –script /.hermes/scripts/your-script.py "Skill not found" at job execution The skill must be installed on the machine running the scheduler. If you move between machines, skills don't automatically sync — reinstall them with `hermes skills install <skill-name>`. Job runs but delivers nothing Likely a delivery target issue (see Delivery Failures above) or a silently suppressed response (`[SILENT]`). Job hangs or times out The scheduler uses an inactivity-based timeout (default 600s, configurable via `HERMES_CRON_TIMEOUT` env var, `0` for unlimited). The agent can run as long as it's actively calling tools — the timer only fires after sustained inactivity. Long-running jobs should use scripts to handle data collection and deliver only the result. ### Check 3: Lock contention The scheduler uses file-based locking to prevent overlapping ticks. If two gateway instances are running (or a CLI session conflicts with a gateway), jobs may be delayed or skipped. Kill duplicate gateway processes:bash ps aux | grep hermes # Kill duplicate processes, keep only one ### Check 4: Permissions on jobs.json Jobs are stored in `~/.hermes/cron/jobs.json`. If this file is not readable/writable by your user, the scheduler will fail silently:bash ls -la /.hermes/cron/jobs.json chmod 600 /.hermes/cron/jobs.json # Your user should own it --- ## Performance Issues ### Slow job startup Each cron job creates a fresh AIAgent session, which may involve provider authentication and model loading. For time-sensitive schedules, add buffer time (e.g., `0 8 * ` instead of `0 9 * `). ### Too many overlapping jobs The scheduler executes jobs sequentially within each tick. If multiple jobs are due at the same time, they run one after another. Consider staggering schedules (e.g., `0 9 * ` and `5 9 * ` instead of both at `0 9 * `) to avoid delays. ### Large script output Scripts that dump megabytes of output will slow down the agent and may hit token limits. Filter/summarize at the script level — emit only what the agent needs to reason about. --- ## Diagnostic Commandsbash hermes cron list # Show all jobs, states, next_run times hermes cron run <job_id> # Schedule for next tick (for testing) hermes cron edit <job_id> # Fix configuration issues hermes logs # View recent Hermes logs hermes skills list # Verify installed skills --- ## Getting More Help If you've worked through this guide and the issue persists: 1. Run the job with `hermes cron run <job_id>` (fires on next gateway tick) and watch for errors in the chat output 2. Check `~/.hermes/logs/agent.log` for scheduler messages and `~/.hermes/logs/errors.log` for warnings 3. Open an issue at [github.com/NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent) with: - The job ID and schedule - The delivery target - What you expected vs. what happened - Relevant error messages from the logs --- For the complete cron reference, see [Automate Anything with Cron](/guides/automate-with-cron) and [Scheduled Tasks (Cron)](/user-guide/features/cron).* ---  # Google Gemini # Google Gemini Hermes Agent supports Google Gemini as a native provider using the Google AI Studio / Gemini API — not the OpenAI-compatible endpoint. This lets Hermes translate its internal OpenAI-shaped message and tool loop into Gemini's native `generateContent` API while preserving tool calling, streaming, multimodal inputs, and Gemini-specific response metadata. Hermes also supports a separate Google Gemini (OAuth) provider that uses the same Cloud Code Assist backend as Google's Gemini CLI. Use the API-key provider (`gemini`) for the lowest-risk official API path. ## Prerequisites - Google AI Studio API key — create one at [aistudio.google.com/apikey](https://aistudio.google.com/apikey) - Billing-enabled Google Cloud project — recommended for agent use. Gemini's free tier is too small for long-running agent sessions because Hermes may make several model calls per user turn. - Hermes installed — no extra Python package is required for the native Gemini provider. :::tip API key path Set `GOOGLE_API_KEY` or `GEMINI_API_KEY`. Hermes checks both names for the `gemini` provider. ::: ## Quick Startbash # Add your Gemini API key echo “GOOGLE_API_KEY=…” >> /.hermes/.env # Select Gemini as your provider hermes model # → Choose “More providers…” → “Google AI Studio” # → Hermes checks your key tier and shows Gemini models # → Select a model # Start chatting hermes chat `If you prefer direct config editing, use the native Gemini API base URL:`yaml model: default: gemini-3-flash-preview provider: gemini base_url: https://generativelanguage.googleapis.com/v1beta ## Configuration After running `hermes model`, your `~/.hermes/config.yaml` will contain:yaml model: default: gemini-3-flash-preview provider: gemini base_url: https://generativelanguage.googleapis.com/v1beta And in `~/.hermes/.env`:bash GOOGLE_API_KEY=… `### Native Gemini API The recommended endpoint is:`text https://generativelanguage.googleapis.com/v1beta Hermes detects this endpoint and creates its native Gemini adapter. Internally, Hermes still keeps the agent loop in OpenAI-shaped messages, then translates each request to Gemini's native schema: - `messages[]` → Gemini `contents[]` - system prompts → Gemini `systemInstruction` - tool schemas → Gemini `functionDeclarations` - tool results → Gemini `functionResponse` parts - streaming responses → OpenAI-shaped stream chunks for the Hermes loop :::note Gemini 3 thought signatures For Gemini 3 tool use, Hermes preserves the `thoughtSignature` values attached to function-call parts and replays them on the next tool turn. That covers the validation-critical path for multi-step agent workflows. Gemini 3 may also attach thought signatures to other response parts. Hermes' native adapter is optimized for agent tool loops today, so it does not yet replay every non-tool-call signature with full part-level fidelity. ::: ### Prefer the Native Endpoint Google also exposes an OpenAI-compatible endpoint:text https://generativelanguage.googleapis.com/v1beta/openai/ For Hermes agent sessions, prefer the native Gemini endpoint above. Hermes includes a native Gemini adapter so it can map multi-turn tool use, tool-call results, streaming, multimodal inputs, and Gemini response metadata directly onto Gemini's `generateContent` API. The OpenAI-compatible endpoint is still useful when you specifically need OpenAI API compatibility. If you previously set `GEMINI_BASE_URL` to the `/openai` URL, remove it or change it:bash GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta ### OAuth Provider Hermes also has a `google-gemini-cli` provider:bash hermes model # → Choose “Google Gemini (OAuth)” This uses browser PKCE login and the Cloud Code Assist backend. It can be useful for users who want Gemini CLI-style OAuth, but Hermes shows an explicit warning because Google may treat use of the Gemini CLI OAuth client from third-party software as a policy violation. For production or lowest-risk usage, prefer the API-key provider above. ## Available Models The `hermes model` picker shows Gemini models maintained in Hermes' provider registry. Common choices include: | Model | ID | Notes | |-------|----|-------| | Gemini 3.1 Pro Preview | `gemini-3.1-pro-preview` | Most capable preview model when available | | Gemini 3 Pro Preview | `gemini-3-pro-preview` | Strong reasoning and coding model | | Gemini 3 Flash Preview | `gemini-3-flash-preview` | Recommended default balance of speed and capability | | Gemini 3.1 Flash Lite Preview | `gemini-3.1-flash-lite-preview` | Fastest / lowest-cost option when available | Model availability changes over time. If a model disappears or is not enabled for your key, run `hermes model` again and pick one from the current list. :::info Model IDs Use Gemini's native model IDs such as `gemini-3-flash-preview`, not OpenRouter-style IDs like `google/gemini-3-flash-preview`, when `provider: gemini`. ::: ### Latest Aliases Google publishes moving aliases for the Pro and Flash Gemini families. `gemini-pro-latest` and `gemini-flash-latest` are useful when you want Google to advance the model automatically without changing your Hermes config. | Alias | Currently tracks | Notes | |-------|------------------|-------| | `gemini-pro-latest` | Latest Gemini Pro model | Best when you want Google's current Pro default | | `gemini-flash-latest` | Latest Gemini Flash model | Best when you want Google's current Flash default |yaml model: default: gemini-pro-latest provider: gemini base_url: https://generativelanguage.googleapis.com/v1beta If you need strict reproducibility, prefer explicit model IDs such as `gemini-3.1-pro-preview` or `gemini-3-flash-preview`. ### Gemma via the Gemini API Google also exposes Gemma models through the Gemini API. Hermes recognizes these as Google models, but hides very low-throughput Gemma entries from the default model picker so new users do not accidentally select an evaluation-tier model for a long-running agent session. Useful evaluation IDs include: | Model | ID | Notes | |-------|----|-------| | Gemma 4 31B IT | `gemma-4-31b-it` | Larger Gemma model; useful for compatibility and quality evaluation | | Gemma 4 26B A4B IT | `gemma-4-26b-a4b-it` | Smaller active-parameter variant when available | These models are best treated as evaluation options on Gemini API keys. Google's Gemma API pricing is free-tier-only and the usage caps are low compared with production Gemini models, so sustained Hermes agent use should normally move to a paid Gemini model, a self-hosted deployment, or another provider with appropriate quota. To use a Gemma model that is hidden from the picker, set it directly:yaml model: default: gemma-4-31b-it provider: gemini base_url: https://generativelanguage.googleapis.com/v1beta ## Switching Models Mid-Session Use the `/model` command during a conversation:text /model gemini-3-flash-preview /model gemini-flash-latest /model gemini-3-pro-preview /model gemini-pro-latest /model gemma-4-31b-it /model gemini-3.1-flash-lite-preview If you have not configured Gemini yet, exit the session and run `hermes model` first. `/model` switches among already-configured providers and models; it does not collect new API keys. ## Diagnosticsbash hermes doctor The doctor checks: - Whether `GOOGLE_API_KEY` or `GEMINI_API_KEY` is available - Whether Gemini OAuth credentials exist for `google-gemini-cli` - Whether configured provider credentials can be resolved For OAuth quota usage, run this inside a Hermes session:text /gquota `/gquota` applies to the `google-gemini-cli` OAuth provider, not the AI Studio API-key provider. ## Gateway (Messaging Platforms) Gemini works with all Hermes gateway platforms (Telegram, Discord, Slack, WhatsApp, LINE, Feishu, etc.). Configure Gemini as your provider, then start the gateway normally:bash hermes gateway setup hermes gateway start The gateway reads `config.yaml` and uses the same Gemini provider configuration. ## Troubleshooting ### "Gemini native client requires an API key" Hermes could not find a usable API key. Add one of these to `~/.hermes/.env`:bash GOOGLE_API_KEY=… # or GEMINI_API_KEY=… Then run `hermes model` again. ### "This Google API key is on the free tier" Hermes probes Gemini API keys during setup. Free-tier quotas can be exhausted after a handful of agent turns because tool use, retries, compression, and auxiliary tasks may require multiple model calls. Enable billing on the Google Cloud project attached to your key, regenerate the key if needed, then run:bash hermes model ### "404 model not found" The selected model is not available for your account, region, or key. Run `hermes model` again and pick another Gemini model from the current list. ### Gemma model is not shown in `hermes model` Hermes may hide low-throughput Gemma models from the picker by default. If you intentionally want to evaluate one, set the model ID directly in `~/.hermes/config.yaml`. ### "429 quota exceeded" on Gemma Gemma models exposed through the Gemini API are useful for evaluation, but their Gemini API free-tier caps are low. Use them for compatibility testing, then switch to a paid Gemini model or another provider for sustained agent sessions. ### OpenAI-compatible endpoint is configured Check `~/.hermes/.env` for:bash GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/ `Change it to the native endpoint or remove the override:`bash GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta ### OAuth login warning The `google-gemini-cli` provider uses a Gemini CLI / Cloud Code Assist OAuth flow. Hermes warns before starting it because this is distinct from the official AI Studio API-key path. Use `provider: gemini` with `GOOGLE_API_KEY` for the official API-key integration. ### Tool calling fails with schema errors Upgrade Hermes and rerun `hermes model`. The native Gemini adapter sanitizes tool schemas for Gemini's stricter function-declaration format; older builds or custom endpoints may not. ## Related - [AI Providers](/integrations/providers) - [Configuration](/user-guide/configuration) - [Fallback Providers](/user-guide/features/fallback-providers) - [AWS Bedrock](/guides/aws-bedrock) — native cloud-provider integration using AWS credentials ---  # Run Hermes Locally with Ollama — Zero API Cost # Run Hermes Locally with Ollama — Zero API Cost ## The Problem Cloud LLM APIs charge per token. A heavy coding session can cost $5–20. For personal projects, learning, or privacy-sensitive work, that adds up — and you're sending every conversation to a third party. ## What This Guide Solves You'll set up Hermes Agent running entirely on your own hardware, using [Ollama](https://ollama.com) as the model backend. No API keys, no subscriptions, no data leaving your machine. Once configured, Hermes works exactly like it does with OpenRouter or Anthropic — terminal commands, file editing, web browsing, delegation — but the model runs locally. By the end, you'll have: - Ollama serving one or more open-weight models - Hermes connected to Ollama as a custom endpoint - A working local agent that can edit files, run commands, and browse the web - Optional: a Telegram/Discord bot powered entirely by your own hardware ## What You Need | Component | Minimum | Recommended | |-----------|---------|-------------| | RAM | 8 GB (for 3B models) | 32+ GB (for 27B+ models) | | Storage | 5 GB free | 30+ GB (for multiple models) | | CPU | 4 cores | 8+ cores (AMD EPYC, Ryzen, Intel Xeon) | | GPU | Not required | NVIDIA GPU with 8+ GB VRAM speeds things up significantly | :::tip CPU-only works, but expect slower responses Ollama runs on CPU-only servers. A 9B model on a modern 8-core CPU gives ~10 tokens/sec. A 31B model on CPU is slower (~2–5 tokens/sec) — each response takes 30–120 seconds, but it works. A GPU dramatically improves this. For CPU-only setups, widen the API timeout via the env var (it's not a `config.yaml` key):bash # /.hermes/.env HERMES_API_TIMEOUT=1800 # 30 minutes — generous for slow local models `::: ## Step 1: Install Ollama`bash curl -fsSL https://ollama.com/install.sh | sh `Verify it's running:`bash ollama –version curl http://localhost:11434/api/tags # Should return {“models”:[]} ## Step 2: Pull a Model Choose based on your hardware: | Model | Size on Disk | RAM Needed | Tool Calling | Best For | |-------|-------------|------------|:------------:|----------| | `gemma4:31b` | ~20 GB | 24+ GB | Yes | Best quality — strong tool use and reasoning | | `gemma2:27b` | ~16 GB | 20+ GB | No | Conversational tasks, no tool use | | `gemma2:9b` | ~5 GB | 8+ GB | No | Fast chat, Q&A — cannot call tools | | `llama3.2:3b` | ~2 GB | 4+ GB | No | Lightweight quick answers only | :::warning Tool calling matters Hermes is an agentic assistant — it edits files, runs commands, and browses the web through tool calls. Models without tool-call support can only chat; they can't take actions. For the full Hermes experience, use a model that supports tools (like `gemma4:31b`). ::: Pull your chosen model:bash ollama pull gemma4:31b :::info Multiple models You can pull several models and switch between them inside Hermes with `/model`. Ollama loads the active model into memory on demand and unloads idle ones automatically. ::: Verify the model works:bash curl http://localhost:11434/v1/chat/completions \ -H “Content-Type: application/json” \ -d ‘{ “model”: “gemma4:31b”, “messages”: [{“role”: “user”, “content”: “Say hello”}], “max_tokens”: 50 }’ `You should see a JSON response with the model's reply. ## Step 3: Configure Hermes Run the Hermes setup wizard:`bash hermes setup When prompted for a provider, select Custom Endpoint and enter: - Base URL: `http://localhost:11434/v1` - API Key: Leave empty or type `no-key` (Ollama doesn't need one) - Model: `gemma4:31b` (or whichever model you pulled) Alternatively, edit `~/.hermes/config.yaml` directly:yaml model: default: “gemma4:31b” provider: “custom” base_url: “http://localhost:11434/v1” `## Step 4: Start Using Hermes`bash hermes `That's it. You're now running a fully local agent. Try it out:` You: List all Python files in this directory and count the lines of code in each You: Read the README.md and summarize what this project does You: Create a Python script that fetches the weather for Ho Chi Minh City Hermes will use the terminal tool, file operations, and your local model — no cloud calls. ## Step 5: Pick the Right Model for Your Task Not every task needs the biggest model. Here's a practical guide: | Task | Recommended Model | Why | |------|-------------------|-----| | File edits, code, terminal commands | `gemma4:31b` | Only model with reliable tool calling | | Quick Q&A (no tool use needed) | `gemma2:9b` | Fast responses for conversational tasks | | Lightweight chat | `llama3.2:3b` | Fastest, but very limited capabilities | :::note For full agentic work (editing files, running commands, browsing), `gemma4:31b` is currently the best local option with tool-call support. Check [Ollama's model library](https://ollama.com/library) for newer models — tool-calling support is expanding rapidly. ::: Switch models on the fly inside a session: /model gemma2:9b `## Step 6: Optimize for Speed ### Increase Ollama's Context Window By default, Ollama uses a 2048-token context. Hermes requires at least 64,000 tokens for agentic work with tools:`bash # Create a Modelfile that extends context cat > /tmp/Modelfile << ‘EOF’ FROM gemma4:31b PARAMETER num_ctx 64000 EOF ollama create gemma4-64k -f /tmp/Modelfile Then update your Hermes config to use `gemma4-64k` as the model name. ### Keep the Model Loaded By default, Ollama unloads models after 5 minutes of inactivity. For a persistent gateway bot, keep it loaded:bash # Set keep-alive to 24 hours curl http://localhost:11434/api/generate \ -d ‘{“model”: “gemma4:31b”, “keep_alive”: “24h”}’ `Or set it globally in Ollama's environment:`bash # /etc/systemd/system/ollama.service.d/override.conf [Service] Environment=“OLLAMA_KEEP_ALIVE=24h” `### Use GPU Offloading (If Available) If you have an NVIDIA GPU, Ollama automatically offloads layers to it. Check with:`bash ollama ps # Shows which model is loaded and how many GPU layers For a 31B model on a 12 GB GPU, you'll get partial offload (~40 layers on GPU, rest on CPU), which still gives a significant speedup. ## Step 7: Run as a Gateway Bot (Optional) Once Hermes works locally in the CLI, you can expose it as a Telegram or Discord bot — still running entirely on your hardware. ### Telegram 1. Create a bot via [@BotFather](https://t.me/BotFather) and get the token 2. Add to your `~/.hermes/config.yaml`:yaml model: default: “gemma4:31b” provider: “custom” base_url: “http://localhost:11434/v1” platforms: telegram: enabled: true token: “YOUR_TELEGRAM_BOT_TOKEN” `3. Start the gateway:`bash hermes gateway `Now message your bot on Telegram — it responds using your local model. ### Discord 1. Create a Discord application at [discord.com/developers](https://discord.com/developers/applications) 2. Add to config:`yaml platforms: discord: enabled: true token: “YOUR_DISCORD_BOT_TOKEN” 3. Start: `hermes gateway` ## Step 8: Set Up Fallbacks (Optional) Local models can struggle with complex tasks. Set up a cloud fallback that only activates when the local model fails:yaml model: default: “gemma4:31b” provider: “custom” base_url: “http://localhost:11434/v1” fallback_providers: - provider: openrouter model: anthropic/claude-sonnet-4 `This way, 90% of your usage is free (local), and only the hard tasks hit the paid API. ## Troubleshooting ### "Connection refused" on startup Ollama isn't running. Start it:`bash sudo systemctl start ollama # or ollama serve ### Slow responses - Check model size vs RAM: If your model needs more RAM than available, it swaps to disk. Use a smaller model or add RAM. - Check `ollama ps`: If no GPU layers are offloaded, responses are CPU-bound. This is normal for CPU-only servers. - Reduce context: Large conversations slow down inference. Use `/compress` regularly, or set a lower compression threshold in config. ### Model doesn't follow tool calls Smaller models (3B, 7B) sometimes ignore tool-call instructions and produce plain text instead of structured function calls. Solutions: - Use a bigger model — `gemma4:31b` or `gemma2:27b` handle tool calls much better than 3B/7B models. - Hermes has auto-repair — it detects malformed tool calls and attempts to fix them automatically. - Set up a fallback — if the local model fails 3 times, Hermes falls back to a cloud provider. ### Context window errors The default Ollama context (2048 tokens) is too small for agentic work. See [Step 6](#step-6-optimize-for-speed) to increase it. ## Cost Comparison Here's what running locally saves compared to cloud APIs, based on a typical coding session (~100K tokens input, ~20K tokens output): | Provider | Cost per Session | Monthly (daily use) | |----------|-----------------|---------------------| | Anthropic Claude Sonnet | ~$0.80 | ~$24 | | OpenRouter (GPT-4o) | ~$0.60 | ~$18 | | Ollama (local) | $0.00 | $0.00 | Your only cost is electricity — roughly $0.01–0.05 per session depending on hardware. ## What Works Well Locally - File editing and code generation — models 9B+ handle this well - Terminal commands — Hermes wraps the command, runs it, reads output regardless of model - Web browsing — the browser tool does the fetching; the model just interprets results - Cron jobs and scheduled tasks — work identically to cloud setups - Multi-platform gateway — Telegram, Discord, Slack all work with local models ## What's Better with Cloud Models - Very complex multi-step reasoning — 70B+ or cloud models like Claude Opus are noticeably better - Long context windows — cloud models offer 100K–1M tokens; local runtimes often default below Hermes' 64K minimum unless you configure them - Speed on large responses — cloud inference is faster than CPU-only local for long generations The sweet spot: use local for everyday tasks, set up a cloud fallback for the hard stuff. ---  # Register a Microsoft Graph Application # Register a Microsoft Graph Application The Teams meeting pipeline reads meeting transcripts, recordings, and related artifacts from Microsoft Graph using app-only (daemon) authentication — no user sign-in, no interactive consent per meeting. That requires an Azure AD application registration with admin-consented application permissions. This guide walks through: 1. Creating the app registration 2. Creating a client secret 3. Granting the Graph API permissions the pipeline needs 4. Admin-consenting those permissions 5. (Optional) Scoping the app to specific users with an Application Access Policy You need tenant admin rights (or an admin to grant consent on your behalf) to finish this. Bookmark the values you collect — they go into `~/.hermes/.env` at the end. ## Prerequisites - A Microsoft 365 tenant with Teams Premium or Teams licenses that produce meeting transcripts and recordings - Admin access to the Azure portal at [entra.microsoft.com](https://entra.microsoft.com) - A publicly reachable HTTPS endpoint for Graph change notifications (set up later, in the webhook listener step) ## Step 1: Create the App Registration 1. Sign in to [entra.microsoft.com](https://entra.microsoft.com) as a tenant admin. 2. Navigate to Identity → Applications → App registrations. 3. Click New registration. 4. Fill in: - Name: `Hermes Teams Meeting Pipeline` (or any name you'll recognize). - Supported account types: Accounts in this organizational directory only (Single tenant). - Redirect URI: leave blank — app-only auth does not need one. 5. Click Register. You'll land on the app's overview page. Copy two values: - Application (client) ID → `MSGRAPH_CLIENT_ID` - Directory (tenant) ID → `MSGRAPH_TENANT_ID` ## Step 2: Create a Client Secret 1. In the left nav, open Certificates & secrets. 2. Click New client secret. 3. Description: `hermes-graph-secret`. Expires: pick a value that matches your rotation policy (6-24 months is typical). 4. Click Add. 5. Copy the Value column immediately — it's only shown once. That value is `MSGRAPH_CLIENT_SECRET`. > The Secret ID column is not the secret. You want the Value column. ## Step 3: Grant Graph API Permissions The pipeline uses a minimum-viable set of application permissions. Add only what you need; each one widens what the app can read tenant-wide. 1. In the left nav, open API permissions. 2. Click Add a permission → Microsoft Graph → Application permissions. 3. Add the permissions from the table below that match what you want the pipeline to do. 4. After adding, click Grant admin consent for `<your tenant>`. The Status column should flip to a green checkmark for every permission. ### Required for transcript-first summaries | Permission | What it lets the app do | |------------|--------------------------| | `OnlineMeetings.Read.All` | Read Teams online meeting metadata (subject, participants, join URL). | | `OnlineMeetingTranscript.Read.All` | Read meeting transcripts generated by Teams. | ### Required for recording fallback (when a transcript is unavailable) | Permission | What it lets the app do | |------------|--------------------------| | `OnlineMeetingRecording.Read.All` | Download Teams meeting recordings for offline STT processing. | | `CallRecords.Read.All` | Resolve meetings from call records when only the join URL is known. | ### Required for outbound summary delivery (Graph mode only) If `platforms.teams.extra.delivery_mode` is `graph`, the pipeline posts summaries into a Teams channel or chat via the Graph API. Skip these if you use `incoming_webhook` delivery mode instead. | Permission | What it lets the app do | |------------|--------------------------| | `ChannelMessage.Send` | Post messages into Teams channels on behalf of the app. | | `Chat.ReadWrite.All` | Post messages into 1:1 and group chats (only if you set `chat_id` as the delivery target). | ### Not recommended - `OnlineMeetings.ReadWrite.All` / `Chat.ReadWrite` without `.All` — broader than the pipeline needs. - Delegated permissions — the pipeline uses app-only (client-credentials) flow; delegated permissions won't work without user sign-in. ## Step 4: (Recommended) Scope the App with an Application Access Policy By default, application permissions like `OnlineMeetings.Read.All` grant the app access to every meeting in the tenant. For partner demos and dev tenants that's fine; for production you almost certainly want to restrict which users' meetings the app can read. Microsoft provides Application Access Policies for Teams exactly for this. The policy is a PowerShell-only surface; there's no portal UI for it. From an admin PowerShell with the MicrosoftTeams module installed and connected (`Connect-MicrosoftTeams`):powershell # Create a policy scoped to the Hermes app New-CsApplicationAccessPolicy `-Identity "Hermes-Meeting-Pipeline-Policy"` -AppIds “<MSGRAPH_CLIENT_ID>” `-Description "Restrict Hermes meeting pipeline to allow-listed users" # Grant the policy to specific users whose meetings the pipeline may read Grant-CsApplicationAccessPolicy` -PolicyName “Hermes-Meeting-Pipeline-Policy” `-Identity "[email protected]" Grant-CsApplicationAccessPolicy` -PolicyName “Hermes-Meeting-Pipeline-Policy” -Identity "[email protected]" ``` Propagation can take up to 30 minutes after granting. Verify with: ```powershell Test-CsApplicationAccessPolicy -Identity "[email protected]" -AppId "<MSGRAPH_CLIENT_ID>" ``` Without the policy, any user's meetings are readable — that's what the permission technically grants. Don't skip this step on a production tenant. ## Step 5: Write the Credentials to Your Env File Put the three values you collected into/.hermes/.env: ```bash MSGRAPH_TENANT_ID=<directory-tenant-id> MSGRAPH_CLIENT_ID=<application-client-id> MSGRAPH_CLIENT_SECRET=<client-secret-value> ``` Set file permissions so only you can read the secret: ```bash chmod 600 ~/.hermes/.env ``` ## Step 6: Verify the Token Flow Hermes ships a Graph auth smoke-test. From your Hermes install: ```python python -c " import asyncio from tools.microsoft_graph_auth import MicrosoftGraphTokenProvider provider = MicrosoftGraphTokenProvider.from_env() token = asyncio.run(provider.get_access_token()) print('Token acquired, length:', len(token)) print(provider.inspect_token_health()) " ``` A successful run prints a long token string and a health dict showing cached: True`and an`expires_in_seconds`value near 3600. Failures produce a`MicrosoftGraphTokenError`with the Azure error code — the most common are: | Azure error | Meaning | Fix | |-------------|---------|-----| |`AADSTS7000215: Invalid client secret`| Secret value mismatched or expired. | Generate a new secret in step 2; update`.env`. | |` AADSTS700016: Application not found`| Wrong`MSGRAPH_CLIENT_ID`or wrong tenant. | Double-check the values from step 1 are from the same app. | |`AADSTS90002: Tenant not found`| Typo in`MSGRAPH_TENANT_ID`. | Copy the Directory (tenant) ID from the app overview again. | |` insufficient_claims`at call time (not token time) | Token acquires but Graph returns 401/403. | You skipped step 3 admin-consent, or added permissions but haven't re-consented. Revisit API permissions and click Grant admin consent again. | ## Rotating the Client Secret Azure client secrets have a hard expiry. Before yours expires: 1. Create a second client secret in step 2 without deleting the first one. 2. Update`MSGRAPH_CLIENT_SECRET`in`/.hermes/.env`with the new value. 3. Restart the gateway so the new secret is picked up:`hermes gateway restart`. 4. Verify with the smoke test above. 5. Delete the old secret from the Azure portal. ## Next Steps Once credentials verify cleanly, continue with: - Webhook listener setup — stand up the` msgraph_webhookgateway platform that receives Graph change notifications. - Pipeline configuration — configure the Teams meeting pipeline runtime and operator CLI. - Outbound delivery — wire summaries back into a Teams channel or chat. Those pages land alongside the PRs that add the corresponding runtime. This credentials setup is a standalone prerequisite and is safe to complete in advance. ---  # Migrate from OpenClaw # Migrate from OpenClawhermes claw migrate`imports your OpenClaw (or legacy Clawdbot/Moldbot) setup into Hermes. This guide covers exactly what gets migrated, the config key mappings, and what to verify after migration. :::tip If your OpenClaw setup was multi-provider,`hermes setup –portalcollapses it to one OAuth — 300+ models plus the Tool Gateway in a single login. See [Nous Portal](/integrations/nous-portal). ::: ## Quick start ```bash # Preview then migrate (always shows a preview first, then asks to confirm) hermes claw migrate # Preview only, no changes hermes claw migrate --dry-run # Full migration including API keys, skip confirmation hermes claw migrate --preset full --migrate-secrets --yes ``` The migration always shows a full preview of what will be imported before making any changes. Review the list, then confirm to proceed. Reads from/.openclaw/`by default. Legacy`/.clawdbot/`or`/.moltbot/ `directories are detected automatically. Same for legacy config filenames (`clawdbot.json`,` moltbot.json`). ## Options | Option | Description | |--------|-------------| |` –dry-run`| Preview only — stop after showing what would be migrated. | |`–preset `|`full`(all compatible settings) or`user-data`(excludes infrastructure config). Neither preset imports secrets by default — pass`–migrate-secrets`explicitly. | |`–overwrite`| Overwrite existing Hermes files on conflicts (default: refuse to apply when the plan has conflicts). | |`–migrate-secrets`| Include API keys. Required even under`–preset full`— no preset imports secrets silently. | |`–no-backup`| Skip the pre-migration zip snapshot of`/.hermes/`(by default a single restore-point archive is written before apply, under`/.hermes/backups/pre-migration-.zip`; restorable with` hermes import`). | |` –source `| Custom OpenClaw directory. | |`–workspace-target `| Where to place`AGENTS.md`. | |` –skill-conflict `|`skip`(default),`overwrite`, or` rename`. | |` –yes`| Skip the confirmation prompt after preview. | ## What gets migrated ### Persona, memory, and instructions | What | OpenClaw source | Hermes destination | Notes | |------|----------------|-------------------|-------| | Persona |`workspace/SOUL.md`|`/.hermes/SOUL.md`| Direct copy | | Workspace instructions |`workspace/AGENTS.md`|`AGENTS.md`in`–workspace-target`| Requires`–workspace-target`flag | | Long-term memory |`workspace/MEMORY.md`|`/.hermes/memories/MEMORY.md`| Parsed into entries, merged with existing, deduped. Uses`§`delimiter. | | User profile |`workspace/USER.md`|`/.hermes/memories/USER.md`| Same entry-merge logic as memory. | | Daily memory files |`workspace/memory/.md`|`/.hermes/memories/MEMORY.md`| All daily files merged into main memory. | Workspace files are also checked at`workspace.default/`and`workspace-main/`as fallback paths (OpenClaw renamed`workspace/`to`workspace-main/`in recent versions, and uses`workspace-{agentId}`for multi-agent setups). ### Skills (4 sources) | Source | OpenClaw location | Hermes destination | |--------|------------------|-------------------| | Workspace skills |`workspace/skills/`|`/.hermes/skills/openclaw-imports/`| | Managed/shared skills |`/.openclaw/skills/`|`/.hermes/skills/openclaw-imports/`| | Personal cross-project |`/.agents/skills/`|`/.hermes/skills/openclaw-imports/`| | Project-level shared |`workspace/.agents/skills/`|`~/.hermes/skills/openclaw-imports/`| Skill conflicts are handled by`–skill-conflict`:` skip`leaves the existing Hermes skill,`overwrite`replaces it,`rename`creates a`-imported`copy. ### Model and provider configuration | What | OpenClaw config path | Hermes destination | Notes | |------|---------------------|-------------------|-------| | Default model |`agents.defaults.model`|`config.yaml`→`model`| Can be a string or`{primary, fallbacks}`object | | Custom providers |`models.providers.`|`config.yaml`→`custom_providers`| Maps`baseUrl`,` apiType`/`api`— handles both short ("openai", "anthropic") and hyphenated ("openai-completions", "anthropic-messages", "google-generative-ai") values | | Provider API keys |`models.providers..apiKey`|`~/.hermes/.env`| Requires`–migrate-secrets`. See [API key resolution](#api-key-resolution) below. | ### Agent behavior | What | OpenClaw config path | Hermes config path | Mapping | |------|---------------------|-------------------|---------| | Max turns |` agents.defaults.timeoutSeconds`|`agent.max_turns`|`timeoutSeconds / 10`, capped at 200 | | Verbose mode |` agents.defaults.verboseDefault`|`agent.verbose`| "off" / "on" / "full" | | Reasoning effort |`agents.defaults.thinkingDefault`|`agent.reasoning_effort`| "always"/"high"/"xhigh" → "high", "auto"/"medium"/"adaptive" → "medium", "off"/"low"/"none"/"minimal" → "low" | | Compression |`agents.defaults.compaction.mode`|`compression.enabled`| "off" → false, anything else → true | | Compression model |`agents.defaults.compaction.model`|`compression.summary_model`| Direct string copy | | Human delay |`agents.defaults.humanDelay.mode`|`human_delay.mode`| "natural" / "custom" / "off" | | Human delay timing |`agents.defaults.humanDelay.minMs`/`.maxMs`|`human_delay.min_ms`/`.max_ms`| Direct copy | | Timezone |`agents.defaults.userTimezone`|`timezone`| Direct string copy | | Exec timeout |`tools.exec.timeoutSec`|`terminal.timeout`| Direct copy (field is`timeoutSec`, not` timeout`) | | Docker sandbox |` agents.defaults.sandbox.backend`|`terminal.backend`| "docker" → "docker" | | Docker image |`agents.defaults.sandbox.docker.image`|`terminal.docker_image`| Direct copy | ### Session reset policies | OpenClaw config path | Hermes config path | Notes | |---------------------|-------------------|-------| |`session.reset.mode`|`session_reset.mode`| "daily", "idle", or both | |`session.reset.atHour`|`session_reset.at_hour`| Hour (0–23) for daily reset | |`session.reset.idleMinutes`|`session_reset.idle_minutes`| Minutes of inactivity | Note: OpenClaw also has`session.resetTriggers`(a simple string array like`[“daily”, “idle”]`). If the structured` session.reset`isn't present, the migration falls back to inferring from`resetTriggers`. ### MCP servers | OpenClaw field | Hermes field | Notes | |----------------|-------------|-------| |` mcp.servers..command`|`mcp_servers..command`| Stdio transport | |`mcp.servers..args`|`mcp_servers..args`| | |`mcp.servers..env`|`mcp_servers..env`| | |`mcp.servers..cwd`|`mcp_servers..cwd`| | |`mcp.servers..url`|`mcp_servers..url`| HTTP/SSE transport | |`mcp.servers..tools.include`|`mcp_servers..tools.include`| Tool filtering | |`mcp.servers..tools.exclude`|`mcp_servers..tools.exclude`| | ### TTS (text-to-speech) TTS settings are read from two OpenClaw config locations with this priority: 1.`messages.tts.providers.{provider}.`(canonical location) 2. Top-level`talk.providers.{provider}.`(fallback) 3. Legacy flat keys`messages.tts.{provider}.`(oldest format) | What | Hermes destination | |------|-------------------| | Provider name |`config.yaml`→`tts.provider`| | ElevenLabs voice ID |`config.yaml`→`tts.elevenlabs.voice_id`| | ElevenLabs model ID |`config.yaml`→`tts.elevenlabs.model_id`| | OpenAI model |`config.yaml`→`tts.openai.model`| | OpenAI voice |`config.yaml`→`tts.openai.voice`| | Edge TTS voice |`config.yaml`→`tts.edge.voice`(OpenClaw renamed "edge" to "microsoft" — both are recognized) | | TTS assets |`/.hermes/tts/`(file copy) | ### Messaging platforms | Platform | OpenClaw config path | Hermes`.env`variable | Notes | |----------|---------------------|----------------------|-------| | Telegram |`channels.telegram.botToken`or`.accounts.default.botToken`|`TELEGRAM_BOT_TOKEN`| Token can be string or [SecretRef](#secretref-handling). Both flat and accounts layout supported. | | Telegram |`credentials/telegram-default-allowFrom.json`|`TELEGRAM_ALLOWED_USERS`| Comma-joined from`allowFrom[]`array | | Discord |`channels.discord.token`or`.accounts.default.token`|`DISCORD_BOT_TOKEN`| | | Discord |`channels.discord.allowFrom`or`.accounts.default.allowFrom`|`DISCORD_ALLOWED_USERS`| | | Slack |`channels.slack.botToken`or`.accounts.default.botToken`|`SLACK_BOT_TOKEN`| | | Slack |`channels.slack.appToken`or`.accounts.default.appToken`|`SLACK_APP_TOKEN`| | | Slack |`channels.slack.allowFrom`or`.accounts.default.allowFrom`|`SLACK_ALLOWED_USERS`| | | WhatsApp |`channels.whatsapp.allowFrom`or`.accounts.default.allowFrom`|`WHATSAPP_ALLOWED_USERS`| Auth via Baileys QR pairing — requires re-pairing after migration | | Signal |`channels.signal.account`or`.accounts.default.account`|`SIGNAL_ACCOUNT`| | | Signal |`channels.signal.httpUrl`or`.accounts.default.httpUrl`|`SIGNAL_HTTP_URL`| | | Signal |`channels.signal.allowFrom`or`.accounts.default.allowFrom`|`SIGNAL_ALLOWED_USERS`| | | Matrix |`channels.matrix.accessToken`or`.accounts.default.accessToken`|`MATRIX_ACCESS_TOKEN`| Uses`accessToken`(not`botToken`) | | Mattermost |` channels.mattermost.botToken`or`.accounts.default.botToken`|`MATTERMOST_BOT_TOKEN`| | ### Other config | What | OpenClaw path | Hermes path | Notes | |------|-------------|-------------|-------| | Approval mode |`approvals.exec.mode`|`config.yaml`→`approvals.mode`| "auto"→"off", "always"→"manual", "smart"→"smart" | | Command allowlist |`exec-approvals.json`|`config.yaml`→`command_allowlist`| Patterns merged and deduped | | Browser CDP URL |`browser.cdpUrl`|`config.yaml`→`browser.cdp_url`| | | Browser headless |`browser.headless`|`config.yaml`→`browser.headless`| | | Brave search key |`tools.web.search.brave.apiKey`|`.env`→`BRAVE_API_KEY`| Requires`–migrate-secrets`| | Gateway auth token |`gateway.auth.token`|`.env`→`HERMES_GATEWAY_TOKEN`| Requires`–migrate-secrets`| | Working directory |`agents.defaults.workspace`|`config.yaml`→`terminal.cwd`| Legacy migrations may still emit`MESSAGING_CWD`as a compatibility fallback | ### Archived (no direct Hermes equivalent) These are saved to`/.hermes/migration/openclaw//archive/`for manual review: | What | Archive file | How to recreate in Hermes | |------|-------------|--------------------------| |`IDENTITY.md`|`archive/workspace/IDENTITY.md`| Merge into`SOUL.md`| |`TOOLS.md`|`archive/workspace/TOOLS.md`| Hermes has built-in tool instructions | |`HEARTBEAT.md`|`archive/workspace/HEARTBEAT.md`| Use cron jobs for periodic tasks | |`BOOTSTRAP.md`|`archive/workspace/BOOTSTRAP.md`| Use context files or skills | | Cron jobs |`archive/cron-config.json`| Recreate with`hermes cron create`| | Plugins |`archive/plugins-config.json`| See [plugins guide](/user-guide/features/hooks) | | Hooks/webhooks |`archive/hooks-config.json`| Use`hermes webhook`or gateway hooks | | Memory backend |`archive/memory-backend-config.json`| Configure via`hermes honcho`| | Skills registry |`archive/skills-registry-config.json`| Use`hermes skills config`| | UI/identity |`archive/ui-identity-config.json`| Use`/skin`command | | Logging |`archive/logging-diagnostics-config.json`| Set in`config.yaml`logging section | | Multi-agent list |`archive/agents-list.json`| Use Hermes profiles | | Channel bindings |`archive/bindings.json`| Manual setup per platform | | Complex channels |`archive/channels-deep-config.json`| Manual platform config | ## API key resolution When`–migrate-secrets`is enabled, API keys are collected from four sources in priority order: 1. Config values —`models.providers..apiKey`and TTS provider keys in`openclaw.json`2. Environment file —`/.openclaw/.env`(keys like`OPENROUTER_API_KEY`,` ANTHROPIC_API_KEY`, etc.) 3. Config env sub-object —` openclaw.json`→`“env”`or`“env”.“vars”`(some setups store keys here instead of a separate`.env`file) 4. Auth profiles —`/.openclaw/agents/main/agent/auth-profiles.json`(per-agent credentials) Config values take priority. Each subsequent source fills any remaining gaps. ### Supported key targets`OPENROUTER_API_KEY`,` OPENAI_API_KEY`,` ANTHROPIC_API_KEY`,` DEEPSEEK_API_KEY`,` GEMINI_API_KEY`,` ZAI_API_KEY`,` MINIMAX_API_KEY`,` ELEVENLABS_API_KEY`,` TELEGRAM_BOT_TOKEN`,` VOICE_TOOLS_OPENAI_KEYKeys not in this allowlist are never copied. ## SecretRef handling OpenClaw config values for tokens and API keys can be in three formats: ```json // Plain string "channels": { "telegram": { "botToken": "123456:ABC-DEF..." } } // Environment template "channels": { "telegram": { "botToken": "${TELEGRAM_BOT_TOKEN}" } } // SecretRef object "channels": { "telegram": { "botToken": { "source": "env", "id": "TELEGRAM_BOT_TOKEN" } } } ``` The migration resolves all three formats. For env templates and SecretRef objects withsource: “env”`, it looks up the value in` /.openclaw/.env`and the`openclaw.json`env sub-object. SecretRef objects with`source: “file”`or`source: “exec”`can't be resolved automatically — the migration warns about these, and those values must be added to Hermes manually via`hermes config set`. ## After migration 1. Check the migration report — printed on completion with counts of migrated, skipped, and conflicting items. 2. Review archived files — anything in` /.hermes/migration/openclaw//archive/`needs manual attention. 3. Start a new session — imported skills and memory entries take effect in new sessions, not the current one. 4. Verify API keys — run`hermes status`to check provider authentication. 5. Test messaging — if you migrated platform tokens, restart the gateway:`systemctl –user restart hermes-gateway`6. Check session policies — run`hermes config show`and verify the`session_reset`value matches your expectations. 7. Re-pair WhatsApp — WhatsApp uses QR code pairing (Baileys), not token migration. Run`hermes whatsapp`to pair. 8. Archive cleanup — after confirming everything works, run`hermes claw cleanup`to rename leftover OpenClaw directories to`.pre-migration/`(prevents state confusion). ## Troubleshooting ### "OpenClaw directory not found" The migration checks`/.openclaw/`, then` /.clawdbot/`, then` ~/.moltbot/`. If your installation is elsewhere, use` –source /path/to/your/openclaw`. ### "No provider API keys found" Keys might be stored in several places depending on your OpenClaw version: inline in` openclaw.json`under`models.providers..apiKey`, in` /.openclaw/.env`, in the` openclaw.json “env”`sub-object, or in`agents/main/agent/auth-profiles.json`. The migration checks all four. If keys use` source: “file”`or`source: “exec”`SecretRefs, they can't be resolved automatically — add them via`hermes config set`. ### Skills not appearing after migration Imported skills land in` /.hermes/skills/openclaw-imports/`. Start a new session for them to take effect, or run` /skills`to verify they're loaded. ### TTS voice not migrated OpenClaw stores TTS settings in two places:`messages.tts.providers.`and the top-level`talk`config. The migration checks both. If your voice ID was set via the OpenClaw UI (stored in a different path), you may need to set it manually:`hermes config set tts.elevenlabs.voice_id YOUR_VOICE_ID`. ---  # MiniMax OAuth # MiniMax OAuth Hermes Agent supports MiniMax through a browser-based OAuth login flow, using the same credentials as the [MiniMax portal](https://www.minimax.io). No API key or credit card is required — log in once and Hermes automatically refreshes your session. The transport reuses the` anthropic_messages`adapter (MiniMax exposes an Anthropic Messages-compatible endpoint at`/anthropic`), so all existing tool-calling, streaming, and context features work without any adapter changes. ## Overview | Item | Value | |------|-------| | Provider ID |` minimax-oauth `| | Display name | MiniMax (OAuth) | | Auth type | Browser OAuth (PKCE redirect flow) | | Transport | Anthropic Messages-compatible (`anthropic_messages`) | | Models |` MiniMax-M2.7`,` MiniMax-M2.7-highspeed`| | Global endpoint |`https://api.minimax.io/anthropic`| | China endpoint |`https://api.minimaxi.com/anthropic `| | Requires env var | No (`MINIMAX_API_KEY`is not used for this provider) | ## Prerequisites - Python 3.9+ - Hermes Agent installed - A MiniMax account at [minimax.io](https://www.minimax.io) (global) or [minimaxi.com](https://www.minimaxi.com) (China) - A browser available on the local machine (or use`–no-browserfor remote sessions) ## Quick Start ```bash # Launch the provider and model picker hermes model # → Select "MiniMax (OAuth)" from the provider list # → Hermes opens your browser to the MiniMax authorization page # → Approve access in the browser # → Select a model (MiniMax-M2.7 or MiniMax-M2.7-highspeed) # → Start chatting hermes ``` After the first login, credentials are stored under/.hermes/auth.json and are refreshed automatically before each session. ## Logging In Manually You can trigger a login without going through the model picker: ```bash hermes auth add minimax-oauth ``` ### China region If your account is on the China platform (minimaxi.com`), use the API-key-based` minimax-cn`provider instead —`minimax-cn`is registered with`auth_type=“api_key”`only (no OAuth flow). Configure`MINIMAX_CN_API_KEY`(and optionally`MINIMAX_CN_BASE_URL) directly: ```bash echo 'MINIMAX_CN_API_KEY=your-key' >> ~/.hermes/.env ``` ### Remote / headless sessions On servers or containers where no browser is available: ```bash hermes auth add minimax-oauth --no-browser ``` Hermes will print the verification URL and user code — open the URL on any device and enter the code when prompted. ## The OAuth Flow Hermes implements a PKCE browser OAuth flow against the MiniMax OAuth endpoints: 1. Hermes generates a PKCE verifier / challenge pair and a random state value. 2. It POSTs to {base_url}/oauth/code`with the challenge and receives a`user_code`and`verification_uri`. 3. Your browser opens` verification_uri`. If prompted, enter the` user_code`. 4. Hermes polls` {base_url}/oauth/token `until the token arrives (or the deadline passes). 5. Tokens (`access_token`,` refresh_token`, expiry) are saved to` /.hermes/auth.json`under the`minimax-oauth`key. Token refresh (standard OAuth`refresh_tokengrant) runs automatically at each session start when the access token is within 60 seconds of expiry. ## Checking Login Status ```bash hermes doctor ``` The◆ Auth Providerssection will show: ``` ✓ MiniMax OAuth (logged in, region=global) ``` or, if not logged in: ``` ⚠ MiniMax OAuth (not logged in) ``` ## Switching Models ```bash hermes model # → Select "MiniMax (OAuth)" # → Pick from the model list ``` Or set the model directly: ```bash hermes config set model.default MiniMax-M2.7 hermes config set model.provider minimax-oauth ``` ## Configuration Reference After login,/.hermes/config.yamlwill contain entries similar to: ```yaml model: default: MiniMax-M2.7 provider: minimax-oauth base_url: https://api.minimax.io/anthropic ``` ### Region endpoints | Provider id | Portal | Inference endpoint | |-------------|--------|-------------------| |minimax-oauth`(global) |`https://api.minimax.io`|`https://api.minimax.io/anthropic`| |`minimax-cn`(China) |`https://api.minimaxi.com`|`https://api.minimaxi.com/anthropic`| ### Provider aliases All of the following resolve to`minimax-oauth: ```bash hermes --provider minimax-oauth # canonical hermes --provider minimax-portal # alias hermes --provider minimax-global # alias hermes --provider minimax_oauth # alias (underscore form) ``` ## Environment Variables The minimax-oauth`provider does not use`MINIMAX_API_KEY`or`MINIMAX_BASE_URL`. Those variables are for the API-key-based` minimax`and`minimax-cn`providers only. | Variable | Effect | |----------|--------| |`MINIMAX_API_KEY`| Used by`minimax`provider only — ignored for`minimax-oauth`| |`MINIMAX_CN_API_KEY`| Used by`minimax-cn`provider only — ignored for`minimax-oauth`| To use`minimax-oauth`as the active provider, set`model.provider: minimax-oauth`in`config.yaml`(use`hermes setup`for the guided flow), or pass`–provider minimax-oauthfor a single invocation: ```bash hermes --provider minimax-oauth ``` ## Models | Model | Best for | |-------|----------| |MiniMax-M2.7`| Long-context reasoning, complex tool-calling | |`MiniMax-M2.7-highspeed`| Lower latency, lighter tasks, auxiliary calls | Both models support up to 200,000 tokens of context.`MiniMax-M2.7-highspeed`is also used automatically as the auxiliary model for vision and delegation tasks when`minimax-oauth`is the primary provider. ## Troubleshooting ### Token expired — not re-logging in automatically Hermes refreshes the token on every session start if it is within 60 seconds of expiry. If the access token is already expired (for example, after a long offline period), the refresh happens automatically on the next request. If refresh fails with`refresh_token_reused`or`invalid_grant`, Hermes marks the session as requiring re-login. When the refresh failure is terminal (HTTP 4xx,` invalid_grant`, revoked grant, etc.), Hermes marks the refresh token as dead and quarantines it locally so it doesn't keep replaying the doomed exchange. The agent surfaces a single "re-authentication required" message and stays out of the way until you log in again. Fix: run` hermes auth add minimax-oauth`again to start a fresh login. The quarantine clears on the next successful exchange. ### Authorization timed out The device-code flow has a finite expiry window. If you don't approve the login in time, Hermes raises a timeout error. Fix: re-run`hermes auth add minimax-oauth`(or`hermes model`). The flow starts fresh. ### State mismatch (possible CSRF) Hermes detected that the` state`value returned by the authorization server does not match what it sent. Fix: re-run the login. If it persists, check for a proxy or redirect that is modifying the OAuth response. ### Logging in from a remote server If`hermes`cannot open a browser window, use`–no-browser: ```bash hermes auth add minimax-oauth --no-browser ``` Hermes prints the URL and code. Open the URL on any device and complete the flow there. ### "Not logged into MiniMax OAuth" error at runtime The auth store has no credentials for minimax-oauth`. You have not logged in yet, or the credential file was deleted. Fix: run` hermes model`and select MiniMax (OAuth), or run`hermes auth add minimax-oauth. ## Logging Out To remove stored MiniMax OAuth credentials: ```bash hermes auth remove minimax-oauth ``` ## See Also - [AI Providers reference](../integrations/providers.md) - [Environment Variables](../reference/environment-variables.md) - [Configuration](../user-guide/configuration.md) - [hermes doctor](../reference/cli-commands.md) ---  # OAuth over SSH / Remote Hosts # OAuth over SSH / Remote Hosts Some Hermes providers — xAI Grok OAuth, Spotify, and remote MCP servers (Linear, Sentry, Atlassian, Asana, Figma, …) — use a loopback redirect OAuth flow. The auth server redirects your browser to http://127.0.0.1:/callback`so a tiny HTTP listener started by Hermes can grab the authorization code. This works perfectly when Hermes and your browser are on the same machine. It breaks the moment they aren't: your laptop's browser tries to reach`127.0.0.1`on your laptop, but the listener is bound to`127.0.0.1`on the remote server. The fix is a one-line SSH local-forward — or, when you don't have a real SSH client (GCP Cloud Shell, GitHub Codespaces, EC2 Instance Connect, Gitpod, browser-based web IDEs), the new`–manual-pasteflag introduced in [#26923](https://github.com/NousResearch/hermes-agent/issues/26923). ## TL;DR ```bash # On your local machine (laptop), in a separate terminal: ssh -N -L 56121:127.0.0.1:56121 user@remote-host # In your existing SSH session on the remote machine: hermes auth add xai-oauth --no-browser # → Hermes prints an authorize URL. Open it in a browser on your laptop. # → Your browser redirects to 127.0.0.1:56121/callback, the tunnel forwards # the request to the remote listener, login completes. ``` Port56121`is what xAI OAuth uses. For Spotify, replace it with`43827`. Hermes prints the exact port it bound to on the` Waiting for callback on …`line — copy it from there. ## Browser-only remote (Cloud Shell / Codespaces / EC2 Instance Connect) If you don't have a regular SSH client — for example because you're running Hermes inside GCP Cloud Shell, GitHub Codespaces, AWS EC2 Instance Connect, Gitpod, or another browser-based console — the SSH tunnel above isn't available. Use`–manual-pasteinstead: ```bash hermes auth add xai-oauth --manual-paste # → Hermes prints an authorize URL. Open it in a browser on your laptop. # → Approve in the browser. The redirect to 127.0.0.1:56121/callback fails # to load — that's expected. # → Copy the FULL URL from the failed page's address bar. # → Paste it back into the terminal at the "Callback URL:" prompt. ``` The same flag works onhermes model –manual-paste`for the integrated model picker. Hermes accepts three callback paste forms interchangeably: the full URL, a bare`?code=…&state=…`query fragment, or — when the upstream consent page renders the authorization code in-page instead of redirecting (xAI's current behavior on browser-based consoles) — just the bare code value on its own. Hermes uses the same PKCE verifier, state and nonce for both paths, so the upstream OAuth flow is byte-identical —`–manual-paste`is purely a transport change for the callback hop and is not a security downgrade. ## Which Providers Need This | Provider | Loopback port | Tunnel needed? | |----------|---------------|----------------| |`xai-oauth`(Grok SuperGrok) |`56121`| Yes, when Hermes is remote | | Spotify |`43827 `| Yes, when Hermes is remote | | MCP servers (`auth: oauth`) | auto-picked per server | Yes, when Hermes is remote | |` anthropic`(Claude Pro/Max) | n/a | No — paste-the-code flow | |`openai-codex`(ChatGPT Plus/Pro) | n/a | No — device code flow | |`minimax`,` nous-portal`| n/a | No — device code flow | If your provider isn't in the table, you don't need a tunnel. ## MCP Servers Remote MCP servers (Linear, Sentry, Atlassian, Asana, Figma, etc.) use the same loopback redirect flow. Hermes auto-picks a free port per server and prints the authorize URL when the OAuth flow kicks off — either at startup (when a new server appears in`mcp_servers:`) or when you run` hermes mcp login `. You have two ways to complete it from a remote host: Option 1 — paste the redirect URL back (no setup, works anywhere). On an interactive terminal, Hermes prompts you to paste the redirect URL alongside running the local listener. After approving in your browser, the redirect to` http://127.0.0.1:/callbackwill show a connection error — that's expected. Copy the full URL from the browser's address bar and paste it at the Hermes prompt: ``` MCP OAuth: authorization required. Open this URL in your browser: https://mcp.linear.app/authorize?response_type=code&... Or paste the redirect URL here (or the ?code=...&state=... portion) and press Enter: > https://mcp.linear.app/callback?code=abc123&state=xyz Got authorization code from paste — completing flow. ``` A bare?code=…&state=…`query string is accepted too. This works for any MCP server with`auth: oauthand requires no SSH config changes. Option 2 — SSH port forward (same as xAI / Spotify). Hermes prints the exact port it bound to in the SSH-session hint. Open a separate terminal on your laptop: ```bash ssh -N -L <port>:127.0.0.1:<port> user@remote-host ``` Then open the authorize URL in your browser as normal; the redirect tunnels through and the listener picks it up. Use this when you need the flow to complete unattended (e.g. scripted re-auth where you can't paste interactively). Pitfall — the 30s config-reload race. If you edit/.hermes/config.yaml`to add an OAuth MCP server from inside a running Hermes session, the CLI auto-reloads MCP connections with a 30s timeout. That's not enough time to complete an interactive OAuth flow, and the reload will give up. Use`hermes mcp login `from a fresh terminal instead — it has no such cap and waits the full 5 min for you to paste back. ## Why the listener can't just bind 0.0.0.0 xAI and Spotify both validate the`redirect_uri `parameter against an allowlist. Both require the loopback form (`http://127.0.0.1:/callback`). Binding the listener to` 0.0.0.0or a different port would cause the auth server to reject the request as a redirect_uri mismatch. The SSH tunnel keeps the loopback URI intact end-to-end. ## Step-by-step: single SSH hop ### 1. Start the tunnel from your local machine ```bash # xAI Grok OAuth (port 56121) ssh -N -L 56121:127.0.0.1:56121 user@remote-host # Or for Spotify (port 43827) ssh -N -L 43827:127.0.0.1:43827 user@remote-host ```-Nmeans "don't open a remote shell, just hold the tunnel open." Keep this terminal running for the duration of the login. ### 2. In a separate SSH session, run the auth command ```bash ssh user@remote-host hermes auth add xai-oauth --no-browser # or for Spotify: # hermes auth add spotify --no-browser ``` Hermes detects the SSH session, skips the browser auto-open, and prints an authorize URL plus aWaiting for callback on http://127.0.0.1:/callback`line. ### 3. Open the URL in your local browser Copy the authorize URL from the remote terminal and paste it into the browser on your laptop. Approve the consent screen. The auth server redirects to`http://127.0.0.1:/callback`. Your browser hits the tunnel, the request is forwarded to the remote listener, and Hermes prints` Login successful!`. You can tear down the tunnel (Ctrl+C in the first terminal) once you see the success line. ## Step-by-step: through a jump box If you reach Hermes through a bastion / jump host, use SSH's built-in` -J(ProxyJump): ```bash ssh -N -L 56121:127.0.0.1:56121 -J jump-user@jump-host user@final-host ``` This chains a SSH connection through the jump host without putting the loopback port on the jump box itself. The local127.0.0.1:56121`on your laptop tunnels straight through to`127.0.0.1:56121`on the final remote host. For older OpenSSH that doesn't support`-J, the long form is: ```bash ssh -N \ -o "ProxyCommand=ssh -W %h:%p jump-user@jump-host" \ -L 56121:127.0.0.1:56121 \ user@final-host ``` ## Mosh, tmux, ssh ControlMaster The tunnel is a property of the underlying SSH connection. If you're running Hermes inside tmux`over a mosh session, the mosh roaming doesn't carry the`-L`forwarding. Open a separate plain SSH session only for the`-L`tunnel — that's the connection that has to stay alive during the auth flow. Your interactive mosh/tmux session can keep running Hermes normally. If you use`ssh -o ControlMaster=auto, port forwards on a multiplexed connection share the master's lifetime. Restart the master if the tunnel doesn't come up: ```bash ssh -O exit user@remote-host ssh -N -L 56121:127.0.0.1:56121 user@remote-host ``` ## Troubleshooting ### bind [127.0.0.1]:56121: Address already in useSomething on your laptop is already using that port. Either the previous tunnel didn't shut down cleanly, or a local Hermes is also listening on it. Find and kill the offender: ```bash # macOS / Linux lsof -iTCP:56121 -sTCP:LISTEN kill <PID> ``` Then retry thessh -L`command. ### "Could not establish connection. We couldn't reach your app." (xAI) xAI's authorize page shows this when its redirect to`127.0.0.1:/callback`doesn't reach a listener. Either the tunnel isn't running, the port is wrong, or you're using the port Hermes printed in a previous run (the port can be auto-bumped if the preferred one is busy — always read the latest`Waiting for callback on …`line). ###`xAI authorization timed out waiting for the local callback `Same root cause as above — the redirect never made it back. Check the tunnel is still alive (`ssh -N`doesn't show output, so look at the terminal you started it from), restart it if needed, and re-run`hermes auth add xai-oauth –no-browser`. ### Tokens land in the wrong` /.hermes`The tokens are written under the Linux user that ran`hermes auth add …`. If your gateway / systemd service runs as a different user (e.g.` root`or a dedicated`hermes`user), authenticate as that user so the tokens land in their`/.hermes/auth.json`.` sudo -u hermes -i `or equivalent. ## See Also - [xAI Grok OAuth](./xai-grok-oauth.md) - [Spotify (`Running over SSH`)](../user-guide/features/spotify.md#running-over-ssh--in-a-headless-environment) - [Native MCP client (OAuth section)](../user-guide/features/mcp.md#oauth-authenticated-http-servers) - [SSH` -J/ ProxyJump (man page)](https://man.openbsd.org/ssh#J) ---  # Operate the Teams Meeting Pipeline # Operate the Teams Meeting Pipeline Use this guide after you have already enabled the feature from [Teams Meetings](/user-guide/messaging/teams-meetings). This page covers: - operator CLI flows - routine subscription maintenance - failure triage - go-live checks - rollout worksheet ## Core Operator Commands ### Validate the config snapshot ```bash hermes teams-pipeline validate ``` Use this first after any config change. ### Inspect token health ```bash hermes teams-pipeline token-health hermes teams-pipeline token-health --force-refresh ``` Use–force-refreshwhen you suspect stale auth state. ### Inspect subscriptions ```bash hermes teams-pipeline subscriptions ``` ### Renew near-expiry subscriptions ```bash hermes teams-pipeline maintain-subscriptions hermes teams-pipeline maintain-subscriptions --dry-run ``` ### Automating subscription renewal (REQUIRED for production) Microsoft Graph subscriptions expire in at most 72 hours. If nothing renews them, meeting notifications silently stop after 3 days and the pipeline looks "broken." This is the #1 operational failure mode for any Graph-backed integration. You MUST runmaintain-subscriptions`on a schedule. Pick one of these three options: #### Option 1: Hermes cron (recommended if you already run the Hermes gateway) Hermes ships a built-in cron scheduler. The`–no-agent`mode runs a script as the job (rather than using an LLM), and`–script`must point at a file under`~/.hermes/scripts/. First create the script: ```bash mkdir -p ~/.hermes/scripts cat > ~/.hermes/scripts/maintain-teams-subscriptions.sh <<'EOF' #!/usr/bin/env bash exec hermes teams-pipeline maintain-subscriptions EOF chmod +x ~/.hermes/scripts/maintain-teams-subscriptions.sh ``` Then register a script-only cron job that runs every 12 hours (gives 6x headroom against the 72h expiry window): ```bash hermes cron create "0 /12 * " \ --name "teams-pipeline-maintain-subscriptions" \ --no-agent \ --script maintain-teams-subscriptions.sh \ --deliver local ``` Verify it was registered and inspect the next run time: ```bash hermes cron list hermes cron status # scheduler status ``` #### Option 2: systemd timer (recommended for Linux production deployments) Create /etc/systemd/system/hermes-teams-pipeline-maintain.service: ```ini [Unit] Description=Hermes Teams pipeline subscription maintenance After=network-online.target [Service] Type=oneshot User=hermes EnvironmentFile=/etc/hermes/env ExecStart=/usr/local/bin/hermes teams-pipeline maintain-subscriptions ``` And /etc/systemd/system/hermes-teams-pipeline-maintain.timer: ```ini [Unit] Description=Run Hermes Teams pipeline subscription maintenance every 12 hours [Timer] OnBootSec=5min OnUnitActiveSec=12h Persistent=true [Install] WantedBy=timers.target ``` Enable: ```bash sudo systemctl daemon-reload sudo systemctl enable --now hermes-teams-pipeline-maintain.timer systemctl list-timers hermes-teams-pipeline-maintain.timer ``` #### Option 3: Plain crontab ```cron 0 /12 * * * /usr/local/bin/hermes teams-pipeline maintain-subscriptions >> /var/log/hermes/teams-pipeline-maintain.log 2>&1 ``` Make sure the cron environment has the MSGRAPH`credentials. Simplest fix: source`/.hermes/.envat the top of a wrapper script that crontab calls. #### Verifying renewal is working After you've set up the schedule, check renewal activity after the first scheduled run: ```bash hermes teams-pipeline subscriptions # should show expirationDateTime advanced hermes teams-pipeline maintain-subscriptions --dry-run # should show "0 expiring soon" most of the time ``` If you ever see your Graph webhook mysteriously "stop working" after exactly ~72 hours, this is the first thing to check: did the renewal job actually run? ### Inspect recent jobs ```bash hermes teams-pipeline list hermes teams-pipeline list --status failed hermes teams-pipeline show <job-id> ``` ### Replay a stored job ```bash hermes teams-pipeline run <job-id> ``` ### Dry-run meeting artifact fetches ```bash hermes teams-pipeline fetch --meeting-id <meeting-id> hermes teams-pipeline fetch --join-web-url "<join-url>" ``` ## Routine Runbook ### After first setup Run these in order: ```bash hermes teams-pipeline validate hermes teams-pipeline token-health --force-refresh hermes teams-pipeline subscriptions ``` Then trigger or wait for a real meeting event and confirm: ```bash hermes teams-pipeline list hermes teams-pipeline show <job-id> ``` ### Daily or periodic checks - runhermes teams-pipeline maintain-subscriptions –dry-run`- inspect`hermes teams-pipeline list –status failed`- verify the Teams delivery target is still the correct chat or channel ### Before changing webhook URLs or delivery targets - update the public notification URL or Teams target config - run`hermes teams-pipeline validate`- renew or recreate affected subscriptions - confirm new events land in the expected sink ## Failure Triage ### No jobs are being created Check: -`msgraph_webhook`is enabled - the public notification URL points to`/msgraph/webhook`- the client state in the subscription matches`MSGRAPH_WEBHOOK_CLIENT_STATE`- subscriptions still exist remotely and are not expired ### Jobs stay in retry or fail before summarization Check: - transcript permissions and availability - recording permissions and artifact availability -`ffmpeg`availability if recording fallback is enabled - Graph token health ### Summaries are produced but not delivered to Teams Check: -`platforms.teams.enabled: true`-`delivery_mode`-`incoming_webhook_url`for webhook mode -`chat_id`or`team_id`plus`channel_id`for Graph mode - Teams auth config if Graph posting is used ### Duplicate or unexpected replays Check: - whether you manually replayed a job with`hermes teams-pipeline run`- whether the sink record already exists for that meeting - whether you intentionally enabled a resend path in your local config ## Go-Live Checklist - [ ] Graph credentials are present and correct - [ ]`msgraph_webhook`is enabled and reachable from the public internet - [ ]`MSGRAPH_WEBHOOK_CLIENT_STATE`is set and matches subscriptions - [ ] transcript subscription is created - [ ] recording subscription is created if STT fallback is required - [ ]`ffmpeg`is installed if recording fallback is enabled - [ ] Teams outbound delivery target is configured and verified - [ ] Notion and Linear sinks are configured only if actually needed - [ ]`hermes teams-pipeline validate`returns an OK snapshot - [ ]`hermes teams-pipeline token-health –force-refresh `succeeds - [ ] `maintain-subscriptions`is scheduled (Hermes cron, systemd timer, or crontab — see [Automating subscription renewal](#automating-subscription-renewal-required-for-production)). Without this, Graph subscriptions silently expire within 72 hours. - [ ] a real end-to-end meeting event has produced a stored job - [ ] at least one summary has reached the intended delivery sink ## Delivery-Mode Decision Guide | Mode | Use when | Tradeoff | |------|----------|----------| |`incoming_webhook`| you only need simple posting into Teams | simplest setup, less control | |`graph| you need channel or chat posting through Graph | more control, more auth and target config | ## Operator Worksheet Fill this out before rollout: | Item | Value | |------|-------| | Public notification URL | | | Graph tenant ID | | | Graph client ID | | | Webhook client state | | | Transcript resource subscription | | | Recording resource subscription | | | Teams delivery mode | | | Teams chat ID or team/channel | | | Notion database ID | | | Linear team ID | | | Store path override, if any | | | Owner for daily checks | | ## Change Review Worksheet Use this before changing the deployment: | Question | Answer | |----------|--------| | Are we changing the public webhook URL? | | | Are we rotating Graph credentials? | | | Are we changing Teams delivery mode? | | | Are we moving to a new Teams chat or channel? | | | Do subscriptions need to be recreated or renewed? | | | Do we need a fresh end-to-end verification run? | | ## Related Docs - [Teams Meetings setup](/user-guide/messaging/teams-meetings) - [Microsoft Teams bot setup](/user-guide/messaging/teams) ---  # Pipe Script Output to Messaging Platforms # Pipe Script Output to Messaging Platformshermes send`is a small, scriptable CLI that pushes a message to any messaging platform Hermes is already configured for. Think of it as a cross-platform`curl `for notifications — you don't need a running gateway, you don't need an LLM, and you don't need to re-paste bot tokens into each of your scripts. Use it for: - System monitoring (memory, disk, GPU temp, long-running job finished) - CI/CD notifications (deploy done, test failure) - Cron scripts that need to ping you with results - Quick one-shot messages from a terminal - Piping any tool's output anywhere (`make | hermes send –to slack:#builds`) The command reuses the same credentials and platform adapters that` hermes gatewayalready uses, so there's no second configuration surface to maintain. --- ## Quick Start ```bash # Plain text to the home channel for a platform hermes send --to telegram "deploy finished" # Pipe in stdout from anything echo "RAM 92%" | hermes send --to telegram:-1001234567890 # Send a file hermes send --to discord:#ops --file /tmp/report.md # Attach a subject/header line hermes send --to slack:#eng --subject "[CI] build.log" --file build.log # Thread target (Telegram topic, Discord thread) hermes send --to telegram:-1001234567890:17585 "threaded reply" # List every configured target hermes send --list # Filter by platform hermes send --list telegram ``` --- ## Argument Reference | Flag | Description | |------|-------------| |-t, –to TARGET`| Destination. See [target formats](#target-formats). | |`message`(positional) | Message text. Omit to read from`–file`or stdin. | |`-f, –file PATH`| Read the body from a file.`–file -`forces stdin. | |`-s, –subject LINE`| Prepend a header/subject line before the body. | |`-l, –list`| List available targets. Optional positional platform filter. | |`-q, –quiet`| No stdout on success (exit code only — ideal for scripts). | |`–json`| Emit the raw JSON result of the send. | |`-h, –help`| Show the built-in help text. | ### Target Formats | Format | Example | Meaning | |--------|---------|---------| |`platform`|`telegram`| Send to the platform's configured home channel | |`platform:chat_id`|`telegram:-1001234567890`| Specific numeric chat / group / user | |`platform:chat_id:thread_id`|`telegram:-1001234567890:17585`| Specific thread or Telegram forum topic | |`platform:#channel`|`discord:#ops`| Human-friendly channel name (resolved against the channel directory) | |`platform:+E164`|`signal:+15551234567`| Phone-addressed platforms: Signal, SMS, WhatsApp | Any platform Hermes ships adapters for works as a target:`telegram`,` discord`,` slack`,` signal`,` sms`,` whatsapp`,` matrix`,` mattermost`,` feishu`,` dingtalk`,` wecom`,` weixin`,` email`, and others. ### Exit Codes | Code | Meaning | |------|---------| |` 0`| Send (or list) succeeded | |`1`| Delivery failed at the platform level (auth, permissions, network) | |`2`| Usage / argument / config error | Exit codes follow the standard Unix convention so your scripts can branch on them the same way they would on`curl`or`grep`. --- ## Message Body Resolution` hermes send`resolves the message body in this order: 1. Positional argument —`hermes send –to telegram “hi” `2. `–file PATH` —` hermes send –to telegram –file msg.txt`3. Piped stdin —`echo hi | hermes send –to telegram`When stdin is a TTY (no pipe), Hermes does not wait for input — you'll get a clear usage error instead. This keeps scripts from hanging if they accidentally omit the body. --- ## Real-World Examples ### Monitoring: Memory / Disk Alerts Replace ad-hoc`curl https://api.telegram.org/…calls in your watchdogs with a single portable line: ```bash #!/usr/bin/env bash ram_pct=$(free | awk '/^Mem:/ {printf "%d", $3 100 / $2}') if [ "$ram_pct" -ge 85 ]; then hermes send --to telegram --subject "⚠ MEMORY WARNING" \ "RAM ${ram_pct}% on $(hostname)" fi ``` Becausehermes send`reuses your Hermes config, the same script works on any host where Hermes is installed — no need to export bot tokens into each machine's environment manually. :::tip Don't alert the gateway about itself For watchdogs that might fire when the gateway itself is struggling (OOM alerts, disk-full alerts), keep using a minimal`curl`call instead of`hermes send. If the Python interpreter can't load because the box is thrashing, you still want that alert to go out. ::: ### CI / CD: Build and Test Results ```bash # In .github/workflows/deploy.yml or any CI script if ./scripts/deploy.sh; then hermes send --to slack:#deploys "✅ ${CI_COMMIT_SHA:0:7} deployed" else tail -n 100 deploy.log | hermes send \ --to slack:#deploys --subject "❌ deploy failed" exit 1 fi ``` ### Cron: Daily Report ```bash # Crontab entry 0 9 * * * /usr/local/bin/generate-metrics.sh \ | /home/me/.hermes/bin/hermes send \ --to telegram --subject "Daily metrics $(date +%Y-%m-%d)" ``` ### Long-Running Tasks: Ping When Done ```bash ./train.py --epochs 200 && \ hermes send --to telegram "training done" || \ hermes send --to telegram "training failed (exit $?)" ``` ### Scripting with –json`and`–quiet```bash # Hard-fail a script if delivery fails; don't clutter logs on success hermes send --to telegram --quiet "keepalive" || { echo "Telegram delivery failed" >&2 exit 1 } # Capture the message ID for later editing / threading msg_id=$(hermes send --to discord:#ops --json "build started" \ | jq -r .message_id) ``` --- ## Doeshermes send`Need the Gateway Running? Usually no. For any bot-token platform — Telegram, Discord, Slack, Signal, SMS, WhatsApp Cloud API, and most others —`hermes send`calls the platform's REST endpoint directly using credentials from`/.hermes/.env`and`/.hermes/config.yaml`. It's a standalone subprocess that exits as soon as the message is delivered. A live gateway is only required for plugin platforms that rely on a persistent adapter connection (for example, a custom plugin that keeps a long-lived WebSocket open). In that case you'll get a clear error pointing at the gateway; start it with` hermes gateway startand retry. --- ## Listing and Discovering Targets Before sending to a specific channel, you can inspect what's available: ```bash # Every target across every configured platform hermes send --list # Just Telegram targets hermes send --list telegram # Machine-readable hermes send --list --json ``` The listing is built from/.hermes/channel_directory.json`, which the gateway refreshes every few minutes while it's running. If you see "no channels discovered yet", start the gateway once (`hermes gateway start`) so it can populate the cache. Human-friendly names (`discord:#ops`,` slack:#engineering`) are resolved against this cache at send time, so you don't need to memorize numeric IDs. --- ## Comparison with Other Approaches | Approach | Multi-platform | Reuses Hermes creds | Needs gateway | Best for | |----------|----------------|---------------------|---------------|----------| |` hermes send`| ✅ | ✅ | No (bot-token) | Everything below | | Raw`curl`to each platform | Each scripted separately | Manual | No | Critical watchdogs | |`cron`job with`–deliver`| ✅ | ✅ | No | Scheduled agent tasks | |`send_message`agent tool | ✅ | ✅ | No | Inside an agent loop |`hermes send`is intentionally the simplest possible surface. If you need an agent to decide what to say, use the`send_message`tool from within a chat or cron job. If you need a scheduled run with LLM-generated content, use`cronjob(action=‘create’, prompt=…)`with`deliver=‘telegram:…’`. If you just need to pipe a raw string, reach for` hermes send`. --- ## Related - [Automate Anything with Cron](/guides/automate-with-cron) — scheduled jobs whose output auto-delivers to any platform. - [Gateway Internals](/developer-guide/gateway-internals) — the delivery router that` hermes sendshares with cron delivery. - [Messaging Platform Setup](/user-guide/messaging/) — one-time configuration for each platform. ---  # Run Hermes Agent with Nous Portal # Run Hermes Agent with Nous Portal This guide walks you through running Hermes Agent on a [Nous Portal](https://portal.nousresearch.com) subscription end to end — from signing up to verifying that every tool routes correctly. If you just want the overview of what the Portal is and what's in the subscription, see the [Nous Portal integration page](/integrations/nous-portal). This page is the task script. ## Prerequisites - Hermes Agent installed ([Quickstart](/getting-started/quickstart)) - A web browser on the machine you're setting up (or SSH port forwarding — see [OAuth over SSH](/guides/oauth-over-ssh)) - About 5 minutes You do not need: an OpenAI key, an Anthropic key, a Firecrawl account, a FAL account, a Browser Use account, or any other per-vendor credential. That's the whole point. ## 1. Get a subscription Open [portal.nousresearch.com/manage-subscription](https://portal.nousresearch.com/manage-subscription), sign up, and pick a plan. Already subscribed? Skip to step 2. ## 2. Run the one-shot setup ```bash hermes setup --portal ``` This single command does five things: 1. Opens your browser to portal.nousresearch.com for OAuth login 2. Stores the refresh token at/.hermes/auth.json`3. Sets`model.provider: nous`in`/.hermes/config.yaml `4. Picks a default agentic model (`anthropic/claude-sonnet-4.6or similar) 5. Turns on the Tool Gateway for web search, image generation, TTS, and browser automation When it finishes, you're back at your terminal ready to chat. ### What if I'm SSH'd into a server? OAuth needs a browser, but the loopback callback runs on the machine where Hermes is running. Two options: ```bash # Option A: SSH port forwarding (preferred) ssh -N -L 8642:127.0.0.1:8642 user@remote-host # in a local terminal hermes setup --portal # on the remote, open the printed URL in your local browser # Option B: manual paste (for Cloud Shell, Codespaces, EC2 Instance Connect) hermes auth add nous --type oauth --manual-paste # Then re-runhermes setup –portalto wire the provider + gateway ``` See [OAuth over SSH / Remote Hosts](/guides/oauth-over-ssh) for the full walkthrough including ProxyJump chains, mosh/tmux, and ControlMaster gotchas. ## 3. Verify it worked ```bash hermes portal info ``` You should see: ``` Nous Portal ─────────── Auth: ✓ logged in Portal: https://portal.nousresearch.com Model: ✓ using Nous as inference provider Tool Gateway ──────────── Web search & extract via Nous Portal Image generation via Nous Portal Text-to-speech via Nous Portal Browser automation via Nous Portal ``` If any line shows something other than "via Nous Portal" or the auth line says "not logged in", jump to [Troubleshooting](#troubleshooting) below. ## 4. Run your first conversation ```bash hermes chat ``` Try something that exercises both the model and the Tool Gateway: ``` Hey, search the web for "Hermes Agent release notes" and summarize the top 3 hits. ``` You should see Hermes callweb_search`(Firecrawl-backed, through the gateway) and respond with a summary. If the search runs and the response makes sense, you're done — the Portal is wired up end to end. ## 5. Pick the model you actually want`hermes setup –portal`lets you pick a model during setup, but the whole point of the subscription is access to the full catalog — switch any time with`/modelmid-session: ```bash /model anthropic/claude-sonnet-4.6 # best general-purpose agentic /model openai/gpt-5.4 # strong reasoning + tool calling /model google/gemini-2.5-pro # huge context window /model deepseek/deepseek-v3.2 # cost-effective coder /model anthropic/claude-opus-4.6 # heavyweight for hard problems ``` Or pop the picker to browse: ```bash /model ``` Pick a different default permanently: ```bash # in your terminal, outside any session hermes config set model.default anthropic/claude-sonnet-4.6 ``` ### Don't pick Hermes-4 for agent work Hermes-4-70B and Hermes-4-405B are available on the Portal at deep discounts, but they're chat/reasoning models, not tool-call-tuned. They will struggle with multi-step agent loops. Use them via [Nous Chat](https://chat.nousresearch.com) for conversation/research work, or through the [subscription proxy](/user-guide/features/subscription-proxy) from non-agent tools. For Hermes Agent itself, stick to the frontier agentic models above. The Portal's own [info page](https://portal.nousresearch.com/info) carries this warning too — it's the official Nous guidance, not just a Hermes-side opinion. ## 6. (Optional) Customize Tool Gateway routing The gateway is opt-in per tool, not all-or-nothing. If you already have a Browserbase account and want to keep using it while routing web search and image generation through Nous, that's supported: ```bash hermes tools # → Web search → "Nous Subscription" (recommended) # → Image generation → "Nous Subscription" (recommended) # → Browser → "Browserbase" (your existing key) # → TTS → "Nous Subscription" (recommended) ``` These rows appear inhermes toolseven before you've logged into Nous Portal — if you pick "Nous Subscription" without an active session, Hermes runs the Portal login inline (without changing your inference provider or your other tools). Verify your mix with: ```bash hermes portal tools ``` You'll see per-tool routing —via Nous Portal `for the ones routed through the subscription, and the partner name (`browserbase`,` firecrawl, etc.) for the ones using your own keys. ## 7. (Optional) Enable voice mode Because the Tool Gateway includes OpenAI TTS, [voice mode](/user-guide/features/voice-mode) works without a separate OpenAI key: ```bash hermes setup voice # → pick "Nous Subscription" for TTS # → pick a speech-to-text backend (local faster-whisper is free, no setup) ``` Then in any messaging-platform session (Telegram, Discord, Signal, etc.), send a voice message and Hermes will transcribe it, respond, and reply with synthesized voice — all on your Portal subscription. ## 8. (Optional) Cron + always-on workflows The Portal subscription works for [cron jobs](/user-guide/features/cron) and [batch processing](/user-guide/features/batch-processing) the same way it works for interactive chat — the OAuth refresh token is reused automatically. No additional setup; just schedule cron jobs and they'll bill against your subscription. ```bash hermes cron create "every day at 9am" \ "Search the web for top AI news and summarize the 5 most important stories" \ --name "Daily AI news" ``` The cron job runs unattended, calls the model + web search + summarization all through your Portal subscription. ## Profiles and multi-user setups If you use [Hermes profiles](/user-guide/profiles) (e.g. a separate config per project), the Portal refresh token is automatically shared across all profiles via a shared token store. Sign in once on any profile, and the rest pick it up automatically. For team setups where multiple humans share a machine, each human has their own Portal account → each home directory holds its own /.hermes/auth.json`→ no token sharing across users. This is the right boundary. ## Troubleshooting ###`hermes portal info`shows "not logged in" after`hermes setup –portalThe OAuth flow didn't complete. Re-run it: ```bash hermes portal ``` If your browser doesn't open or the callback fails, you're likely on a remote/headless host — see [OAuth over SSH](/guides/oauth-over-ssh) for the port-forwarding and manual-paste workarounds. ### "Model: currently openrouter" (or some other provider) instead of "using Nous as inference provider" Your local config drifted. The OAuth worked butmodel.provideris still pointing at a different provider. Fix: ```bash hermes config set model.provider nous ``` Or interactively: ```bash hermes model # pick Nous Portal ``` Re-verify withhermes portal info. ### Tool Gateway tools showing partner names instead of "via Nous Portal" Per-tool config is overriding the gateway. Run: ```bash hermes tools # pick "Nous Subscription" for any tool you want gateway-routed ``` Some users intentionally mix — e.g. routing web through Nous but using their own Browserbase key for browser. If that's intentional, leave it alone. If not, this command fixes it. ### "Re-authentication required" mid-session Your Portal refresh token was invalidated (password change, manual revoke, session expiry). The token is now quarantined locally so Hermes doesn't replay it endlessly. Just log in again: ```bash hermes auth add nous ``` The quarantine clears automatically on successful re-login. ### Model I want isn't in the /modelpicker The Portal catalog mirrors OpenRouter's model list (300+). If a model is missing, try typing the OpenRouter-style slug directly: ```bash /model anthropic/claude-opus-4.6 /model openai/o1-2025-12-17 ``` If a model is genuinely unavailable, [open an issue](https://github.com/NousResearch/hermes-agent/issues) — most gaps are routing config we can update. ### Billing not appearing on my Portal accounthermes portal info`will tell you whether you're actually routing through the Portal or some other provider. Common causes: -`model.provider`set to`openrouter`/`anthropic`/etc. instead of` nous`- An OAuth refresh failure that fell back to a different configured provider - Multiple Hermes profiles where you're using the wrong one (check`hermes profile current) ### Want to revoke and start clean ```bash hermes auth remove nous # wipes the local refresh token # Then re-run setup or remove the subscription from the Portal web UI ``` ## What this gets you, in plain numbers | Without Portal | With Portal | |----------------|-------------| | 1× OpenRouter / Anthropic / OpenAI key in .env`| 1× OAuth refresh token, no`.envkeys | | 1× Firecrawl key for web | Web routed through gateway | | 1× FAL key for image gen | Image gen routed through gateway | | 1× Browser Use / Browserbase key for browser | Browser routed through gateway | | 1× OpenAI key for TTS / voice mode | TTS routed through gateway | | 5 separate dashboards, top-ups, invoices | 1 subscription, 1 invoice | | Cross-machine: replicate all 5 keys | Cross-machine: re-OAuth once | That's the deal. If you're using more than two of those backends anyway, the subscription pays for itself. ## See also - [Nous Portal integration page](/integrations/nous-portal) — Overview of what's in the subscription - [Tool Gateway](/user-guide/features/tool-gateway) — Full details on every gateway-routed tool - [Subscription proxy](/user-guide/features/subscription-proxy) — Use your Portal subscription from non-Hermes tools - [Voice mode](/user-guide/features/voice-mode) — Set up voice conversations on the Portal subscription - [OAuth over SSH](/guides/oauth-over-ssh) — Remote / headless login patterns - [Profiles](/user-guide/profiles) — Share one Portal login across multiple Hermes configurations ---  # Run Nemotron 3 Ultra free in Hermes Agent # Run Nemotron 3 Ultra free in Hermes Agent Nous Research has been inducted into the Nemotron Coalition of leading AI labs working with NVIDIA to advance open frontier foundation models. In honor of this, we've partnered with Nebius to provide Nemotron 3 Ultra free on [Nous Portal](https://portal.nousresearch.com) for two weeks (June 4th – June 18th). Follow the instructions below to try the model in your Hermes Agent today. :::info Limited-time offer Thenvidia/nemotron-3-ultra:free`tier is available from June 4th to June 18th. The`:freetag is what keeps it on the no-cost plan — pick that exact variant. ::: Pick whichever install fits you. The desktop app is the easiest — no terminal required. If you live in a terminal, the command-line install is right below it. ## Option A — Desktop app (recommended) The simplest path: a one-click installer with a guided, point-and-click setup. No terminal needed. ### 1. Download and install [Download the Hermes Desktop installer](https://hermes-agent.nousresearch.com/desktop) for macOS or Windows, then open it. On first launch it finishes setting itself up (usually under a minute). ### 2. Connect Nous Portal When the app opens, you'll see a "Let's get you set up" screen. Click Nous Portal (marked Recommended). Your browser opens — create a [Nous Portal](https://portal.nousresearch.com) account (or sign in), choose the Free plan, and authorize Hermes. The app connects automatically. ### 3. Pick the free Nemotron 3 Ultra model After connecting, the app shows a Default model card. Click Change, search for nemotron 3 ultra, and select the variant tagged Free tier: ``` nvidia/nemotron-3-ultra:free ``` The:free tag is what keeps it on the no-cost tier — pick that variant. ### 4. Start chatting Click Start chatting. That's it — you're talking to Nemotron 3 Ultra, free. ## Option B — Command line Prefer the terminal? ### 1. Install Hermes Agent On macOS/Linux/WSL2/Android, run ```bash curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash ``` On Windows, run ```powershell iex (irm https://hermes-agent.nousresearch.com/install.ps1) ``` Prefer to review first? Download [install.sh](https://hermes-agent.nousresearch.com/install.sh), inspect it, then run it. After it finishes, reload your shell: ```bash source ~/.bashrc # or source ~/.zshrc ``` ### 2. Run Quick Setup ```bash hermes setup ``` Select Quick Setup. Hermes opens a browser tab and waits for you to finish the next steps. ### 3. Create a Nous Portal account In the browser, create a [Nous Portal](https://portal.nousresearch.com) account (or sign in) and choose the Free plan. ### 4. Connect your account When prompted to connect your account to Hermes Agent, click Connect. You'll see a confirmation once it's linked. ### 5. Select the free Nemotron 3 Ultra model Return to your terminal. From the model list, select: ``` nvidia/nemotron-3-ultra:free ``` The :freetag is what keeps it on the no-cost tier, so make sure you pick that variant. ### 6. Start chatting Complete the remaining Quick Setup prompts, then run: ```bash hermes ``` That's it — you're talking to Nemotron 3 Ultra, free. ## Switching to it later Already set up with another model? - Desktop app: open the model picker, search for nemotron 3 ultra, and select the Free tier variant. - CLI / TUI: switch any time from inside a session with/model nvidia/nemotron-3-ultra:free`, or run` /model`to open the picker and choose it from the list. ## Troubleshooting - Don't see the model in the list? Make sure you finished the Nous Portal connection and that you're on the Free plan. In the CLI,`hermes portal info`confirms you're logged in and routing through Nous. - Picked the wrong variant? Re-select`nvidia/nemotron-3-ultra:free`— the`:freesuffix is required to stay on the no-cost tier. - Browser didn't open / you're on a remote host (CLI)? See [OAuth over SSH / Remote Hosts](/guides/oauth-over-ssh) for port-forwarding and manual-paste workarounds. ## See also - [Desktop App](/user-guide/desktop) — The native one-click app (macOS, Windows, Linux) - [Run Hermes Agent with Nous Portal](/guides/run-hermes-with-nous-portal) — Full Portal walkthrough: models, Tool Gateway, and verification - [Nous Portal integration](/integrations/nous-portal) — What's in the subscription - [Quickstart](/getting-started/quickstart) — Install-to-chat in under 5 minutes ---  # Automated GitHub PR Comments with Webhooks # Automated GitHub PR Comments with Webhooks This guide walks you through connecting Hermes Agent to GitHub so it automatically fetches a pull request's diff, analyzes the code changes, and posts a comment — triggered by a webhook event with no manual prompting. When a PR is opened or updated, GitHub sends a webhook POST to your Hermes instance. Hermes runs the agent with a prompt that instructs it to retrieve the diff via thegh CLI, and the response is posted back to the PR thread. :::tip Want a simpler setup without a public endpoint? If you don't have a public URL or just want to get started quickly, check out [Build a GitHub PR Review Agent](./github-pr-review-agent.md) — uses cron jobs to poll for PRs on a schedule, works behind NAT and firewalls. ::: :::info Reference docs For the full webhook platform reference (all config options, delivery types, dynamic subscriptions, security model) see [Webhooks](/user-guide/messaging/webhooks). ::: :::warning Prompt injection risk Webhook payloads contain attacker-controlled data — PR titles, commit messages, and descriptions can contain malicious instructions. When your webhook endpoint is exposed to the internet, run the gateway in a sandboxed environment (Docker, SSH backend). See the [security section](#security-notes) below. ::: --- ## Prerequisites - Hermes Agent installed and running (hermes gateway`) - [`gh `CLI](https://cli.github.com/) installed and authenticated on the gateway host (`gh auth login`) - A publicly reachable URL for your Hermes instance (see [Local testing with ngrok](#local-testing-with-ngrok) if running locally) - Admin access to the GitHub repository (required to manage webhooks) --- ## Step 1 — Enable the webhook platform Add the following to your` /.hermes/config.yaml: ```yaml platforms: webhook: enabled: true extra: port: 8644 # default; change if another service occupies this port rate_limit: 30 # max requests per minute per route (not a global cap) routes: github-pr-review: secret: "your-webhook-secret-here" # must match the GitHub webhook secret exactly events: - pull_request # The agent is instructed to fetch the actual diff before reviewing. # {number} and {repository.full_name} are resolved from the GitHub payload. prompt: | A pull request event was received (action: {action}). PR #{number}: {pull_request.title} Author: {pull_request.user.login} Branch: {pull_request.head.ref} → {pull_request.base.ref} Description: {pull_request.body} URL: {pull_request.html_url} If the action is "closed" or "labeled", stop here and do not post a comment. Otherwise: 1. Run: gh pr diff {number} --repo {repository.full_name} 2. Review the code changes for correctness, security issues, and clarity. 3. Write a concise, actionable review comment and post it. deliver: github_comment deliver_extra: repo: "{repository.full_name}" pr_number: "{number}" ``` Key fields: | Field | Description | |---|---| | secret`(route-level) | HMAC secret for this route. Falls back to`extra.secret`global if omitted. | |`events`| List of`X-GitHub-Event`header values to accept. Empty list = accept all. | |`prompt`| Template;`{field}`and`{nested.field}`resolve from the GitHub payload. | |`deliver`|`github_comment`posts via`gh pr comment`.` log`just writes to the gateway log. | |`deliver_extra.repo`| Resolves to e.g.`org/repo`from the payload. | |`deliver_extra.pr_number`| Resolves to the PR number from the payload. | :::note The payload does not contain code The GitHub webhook payload includes PR metadata (title, description, branch names, URLs) but not the diff. The prompt above instructs the agent to run`gh pr diff`to fetch the actual changes. The`terminal`tool is included in the default`hermes-webhooktoolset, so no extra configuration is needed. ::: --- ## Step 2 — Start the gateway ```bash hermes gateway ``` You should see: ``` [webhook] Listening on 0.0.0.0:8644 — routes: github-pr-review ``` Verify it's running: ```bash curl http://localhost:8644/health # {"status": "ok", "platform": "webhook"} ``` --- ## Step 3 — Register the webhook on GitHub 1. Go to your repository → Settings → Webhooks → Add webhook 2. Fill in: - Payload URL:https://your-public-url.example.com/webhooks/github-pr-review`- Content type:`application/json`- Secret: the same value you set for`secret`in the route config - Which events? → Select individual events → check Pull requests 3. Click Add webhook GitHub will immediately send a`ping`event to confirm the connection. It is safely ignored —`ping`is not in your`events`list — and returns`{“status”: “ignored”, “event”: “ping”}. It is only logged at DEBUG level, so it won't appear in the console at the default log level. --- ## Step 4 — Open a test PR Create a branch, push a change, and open a PR. Within 30–90 seconds (depending on PR size and model), Hermes should post a review comment. To follow the agent's progress in real time: ```bash tail -f "${HERMES_HOME:-$HOME/.hermes}/logs/gateway.log" ``` --- ## Local testing with ngrok If Hermes is running on your laptop, use [ngrok](https://ngrok.com/) to expose it: ```bash ngrok http 8644 ``` Copy the https://…ngrok-free.app`URL and use it as your GitHub Payload URL. On the free ngrok tier the URL changes each time ngrok restarts — update your GitHub webhook each session. Paid ngrok accounts get a static domain. You can smoke-test a static route directly with`curl`— no GitHub account or real PR needed. :::tip Use`deliver: log`when testing locally Change`deliver: github_comment`to`deliver: log`in your config while testing. Otherwise the agent will attempt to post a comment to the fake`org/repo#99`repo in the test payload, which will fail. Switch back to`deliver: github_commentonce you're satisfied with the prompt output. ::: ```bash SECRET="your-webhook-secret-here" BODY='{"action":"opened","number":99,"pull_request":{"title":"Test PR","body":"Adds a feature.","user":{"login":"testuser"},"head":{"ref":"feat/x"},"base":{"ref":"main"},"html_url":"https://github.com/org/repo/pull/99"},"repository":{"full_name":"org/repo"}}' SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print "sha256="$2}') curl -s -X POST http://localhost:8644/webhooks/github-pr-review \ -H "Content-Type: application/json" \ -H "X-GitHub-Event: pull_request" \ -H "X-Hub-Signature-256: $SIG" \ -d "$BODY" # Expected: {"status":"accepted","route":"github-pr-review","event":"pull_request","delivery_id":"..."} ``` Then watch the agent run: ```bash tail -f "${HERMES_HOME:-$HOME/.hermes}/logs/gateway.log" ``` :::notehermes webhook test `only works for dynamic subscriptions created with`hermes webhook subscribe`. It does not read routes from` config.yaml`. ::: --- ## Filtering to specific actions GitHub sends` pull_request`events for many actions:`opened`,` synchronize`,` reopened`,` closed`,` labeled`, etc. The` events`list filters only by the`X-GitHub-Event`header value — it cannot filter by action sub-type at the routing level. The prompt in Step 1 already handles this by instructing the agent to stop early for`closed`and`labeled`events. :::warning The agent still runs and consumes tokens The "stop here" instruction prevents a meaningful review, but the agent still runs to completion for every`pull_request `event regardless of action. GitHub webhooks can only filter by event type (`pull_request`,` push`,` issues`, etc.) — not by action sub-type (`opened`,` closed`,` labeled`). There is no routing-level filter for sub-actions. For high-volume repos, accept this cost or filter upstream with a GitHub Actions workflow that calls your webhook URL conditionally. ::: > There is no Jinja2 or conditional template syntax.` {field}`and`{nested.field}`are the only substitutions supported. Anything else is passed verbatim to the agent. --- ## Using a skill for consistent review style Load a [Hermes skill](/user-guide/features/skills) to give the agent a consistent review persona. Add`skills`to your route inside`platforms.webhook.extra.routes`in`config.yaml: ```yaml platforms: webhook: enabled: true extra: routes: github-pr-review: secret: "your-webhook-secret-here" events: [pull_request] prompt: | A pull request event was received (action: {action}). PR #{number}: {pull_request.title} by {pull_request.user.login} URL: {pull_request.html_url} If the action is "closed" or "labeled", stop here and do not post a comment. Otherwise: 1. Run: gh pr diff {number} --repo {repository.full_name} 2. Review the diff using your review guidelines. 3. Write a concise, actionable review comment and post it. skills: - review deliver: github_comment deliver_extra: repo: "{repository.full_name}" pr_number: "{number}" ``` > Note: Only the first skill in the list that is found is loaded. Hermes does not stack multiple skills — subsequent entries are ignored. --- ## Sending responses to Slack or Discord instead Replace the deliver`and`deliver_extrafields inside your route with your target platform: ```yaml # Inside platforms.webhook.extra.routes.<route-name>: # Slack deliver: slack deliver_extra: chat_id: "C0123456789" # Slack channel ID (omit to use the configured home channel) # Discord deliver: discord deliver_extra: chat_id: "987654321012345678" # Discord channel ID (omit to use home channel) ``` The target platform must also be enabled and connected in the gateway. Ifchat_id`is omitted, the response is sent to that platform's configured home channel. Valid`deliver`values:`log`·`github_comment`·`telegram`·`discord`·`slack`·`signal`·`sms`--- ## GitLab support The same adapter works with GitLab. GitLab uses`X-Gitlab-Token`for authentication (plain string match, not HMAC) — Hermes handles both automatically. For event filtering, GitLab sets`X-GitLab-Event`to values like`Merge Request Hook`,` Push Hook`,` Pipeline Hook`. Use the exact header value in` events: ```yaml events: - Merge Request Hook ``` GitLab payload fields differ from GitHub's — e.g. {object_attributes.title}`for the MR title and`{object_attributes.iid}`for the MR number. The easiest way to discover the full payload structure is GitLab's Test button in your webhook settings, combined with the Recent Deliveries log. Alternatively, omit`prompt`from your route config — Hermes will then pass the full payload as formatted JSON directly to the agent, and the agent's response (visible in the gateway log with`deliver: log`) will describe its structure. --- ## Security notes - Never use` INSECURE_NO_AUTH` in production — it disables signature validation entirely. It is only for local development. - Rotate your webhook secret periodically and update it in both GitHub (webhook settings) and your` config.yaml`. - Rate limiting is 30 req/min per route by default (configurable via` extra.rate_limit`). Exceeding it returns` 429`. - Duplicate deliveries (webhook retries) are deduplicated via a 1-hour idempotency cache. The cache key is` X-GitHub-Delivery`if present, then`X-Request-ID`, then a millisecond timestamp. When neither delivery ID header is set, retries are not deduplicated. - Prompt injection: PR titles, descriptions, and commit messages are attacker-controlled. Malicious PRs could attempt to manipulate the agent's actions. Run the gateway in a sandboxed environment (Docker, VM) when exposed to the public internet. --- ## Troubleshooting | Symptom | Check | |---|---| |` 401 Invalid signature`| Secret in config.yaml doesn't match GitHub webhook secret | |`404 Unknown route`| Route name in the URL doesn't match the key in`routes:`| |`429 Rate limit exceeded`| 30 req/min per route exceeded — common when re-delivering test events from GitHub's UI; wait a minute or raise`extra.rate_limit`| | No comment posted |`gh `not installed, not on PATH, or not authenticated (`gh auth login`) | | Agent runs but no comment | Check the gateway log — if the agent output was empty or just "SKIP", delivery is still attempted | | Port already in use | Change` extra.port`in config.yaml | | Agent runs but reviews only the PR description | The prompt isn't including the`gh pr diff`instruction — the diff is not in the webhook payload | | Can't see the ping event | Ignored events return`{“status”:“ignored”,“event”:“ping”}at DEBUG log level only — check GitHub's delivery log (repo → Settings → Webhooks → your webhook → Recent Deliveries) | GitHub's Recent Deliveries tab (repo → Settings → Webhooks → your webhook) shows the exact request headers, payload, HTTP status, and response body for every delivery. It is the fastest way to diagnose failures without touching your server logs. --- ## Full config reference ```yaml platforms: webhook: enabled: true extra: host: "0.0.0.0" # bind address (default: 0.0.0.0) port: 8644 # listen port (default: 8644) secret: "" # optional global fallback secret rate_limit: 30 # requests per minute per route max_body_bytes: 1048576 # payload size limit in bytes (default: 1 MB) routes: <route-name>: secret: "required-per-route" events: [] # [] = accept all; otherwise list X-GitHub-Event values prompt: "" # {field} / {nested.field} resolved from payload skills: [] # first matching skill is loaded (only one) deliver: "log" # log | github_comment | telegram | discord | slack | signal | sms deliver_extra: {} # repo + pr_number for github_comment; chat_id for others ``` --- ## What's Next? - [Cron-Based PR Reviews](./github-pr-review-agent.md) — poll for PRs on a schedule, no public endpoint needed - [Webhook Reference](/user-guide/messaging/webhooks) — full config reference for the webhook platform - [Build a Plugin](/guides/build-a-hermes-plugin) — package review logic into a shareable plugin - [Profiles](/user-guide/profiles) — run a dedicated reviewer profile with its own memory and config ---  # xAI Grok OAuth (SuperGrok / X Premium+) # xAI Grok OAuth (SuperGrok / X Premium+) Hermes Agent supports xAI Grok through a browser-based OAuth login flow against [accounts.x.ai](https://accounts.x.ai), using either a SuperGrok subscription ([grok.com](https://x.ai/grok)) or an X Premium+ subscription (linked X account). NoXAI_API_KEY`is required — log in once and Hermes automatically refreshes your session in the background. When you sign in with an X account that has Premium+, xAI automatically links the subscription status to your xAI session, so the OAuth flow works the same as it does for direct SuperGrok subscribers. The transport reuses the`codex_responses`adapter (xAI exposes a Responses-style endpoint), so reasoning, tool-calling, streaming, and prompt caching work without any adapter changes. The same OAuth bearer token is also reused by every direct-to-xAI surface in Hermes — TTS, image generation, video generation, and transcription — so a single login covers all four. ## Overview | Item | Value | |------|-------| | Provider ID |`xai-oauth `| | Display name | xAI Grok OAuth (SuperGrok / X Premium+) | | Auth type | Browser OAuth 2.0 PKCE (loopback callback) | | Transport | xAI Responses API (`codex_responses`) | | Default model |` grok-4.3`| | Endpoint |`https://api.x.ai/v1`| | Auth server |`https://accounts.x.ai `| | Requires env var | No (`XAI_API_KEY`is not used for this provider) | | Subscription | [SuperGrok](https://x.ai/grok) or [X Premium+](https://x.com/i/premium_sign_up) — see note below | ## Prerequisites - Python 3.9+ - Hermes Agent installed - An active SuperGrok subscription on your xAI account, or an X Premium+ subscription on the X account you sign in with (xAI links the subscription automatically) - A browser available on the local machine (or use`–no-browser`for remote sessions) :::warning xAI may restrict OAuth API access by tier xAI's backend enforces its own allowlist on the OAuth API surface and has been seen to reject standard SuperGrok subscribers with`HTTP 403`(see issue [#26847](https://github.com/NousResearch/hermes-agent/issues/26847)) even though the in-app subscription is active. If OAuth login succeeds in the browser but inference returns 403, set`XAI_API_KEY `and switch to the API-key path (`provider: xai) — that surface is not subject to the same gating today. ::: ## Quick Start ```bash # Launch the provider and model picker hermes model # → Select "xAI Grok OAuth (SuperGrok / X Premium+)" from the provider list # → Hermes opens your browser to accounts.x.ai # → Approve access in the browser # → Pick a model (grok-4.3 is at the top) # → Start chatting hermes ``` After the first login, credentials are stored under /.hermes/auth.jsonand refreshed automatically before they expire. ## Logging In Manually You can trigger a login without going through the model picker: ```bash hermes auth add xai-oauth ``` ### Remote / headless sessions On servers, containers, or SSH sessions where no browser is available, Hermes detects the remote environment and prints the authorization URL instead of opening a browser. Important: the loopback listener still runs on the remote machine at127.0.0.1:56121`. The xAI redirect needs to reach that listener, so opening the URL on your laptop will fail (`Could not establish connection. We couldn’t reach your app.) unless you forward the port: ```bash # In a separate terminal on your local machine: ssh -N -L 56121:127.0.0.1:56121 user@remote-host # Then in your SSH session on the remote machine: hermes auth add xai-oauth --no-browser # Open the printed authorize URL in your local browser. ``` Through a jump box / bastion: add -J jump-user@jump-host`. See [OAuth over SSH / Remote Hosts](./oauth-over-ssh.md) for the full step-by-step, including ProxyJump chains, mosh/tmux, and ControlMaster gotchas. ### Browser-only remotes (Cloud Shell, Codespaces, EC2 Instance Connect) If you don't have a regular SSH client (e.g. you're running Hermes inside GCP Cloud Shell, GitHub Codespaces, AWS EC2 Instance Connect, Gitpod, or another browser-based console), the` ssh -L`recipe above isn't available. Use`–manual-pasteinstead — Hermes skips the loopback listener and lets you paste the failed callback URL straight from your browser: ```bash hermes auth add xai-oauth --manual-paste # Or via the model picker: hermes model --manual-paste ``` See [OAuth over SSH / Remote Hosts](./oauth-over-ssh.md#browser-only-remote-cloud-shell--codespaces--ec2-instance-connect) for the full walkthrough. Regression fix for [#26923](https://github.com/NousResearch/hermes-agent/issues/26923). If the consent page renders the authorization code directly on the page (xAI's current behavior on browser-based consoles) instead of redirecting to your127.0.0.1:56121/callback`, paste just the bare code value at the` Callback URL:`prompt — Hermes accepts the full URL, a bare`?code=…&state=…`query fragment, or a bare code interchangeably. ## How the Login Works 1. Hermes opens your browser to`accounts.x.ai`. 2. You sign in (or confirm your existing session) and approve access. 3. xAI redirects back to Hermes and the tokens are saved to` /.hermes/auth.json`. 4. From then on, Hermes refreshes the access token in the background — you stay signed in until you` hermes auth remove xai-oauthor revoke access from your xAI account settings. ## Checking Login Status ```bash hermes doctor ``` The◆ Auth Providers`section will show the current state of every provider, including`xai-oauth. ## Switching Models ```bash hermes model # → Select "xAI Grok OAuth (SuperGrok / X Premium+)" # → Pick from the model list (grok-4.3 is pinned to the top) ``` Or set the model directly: ```bash hermes config set model.default grok-4.3 hermes config set model.provider xai-oauth ``` ## Configuration Reference After login, /.hermes/config.yamlwill contain: ```yaml model: default: grok-4.3 provider: xai-oauth base_url: https://api.x.ai/v1 ``` ### Provider aliases All of the following resolve toxai-oauth: ```bash hermes --provider xai-oauth # canonical hermes --provider grok-oauth # alias hermes --provider x-ai-oauth # alias hermes --provider xai-grok-oauth # alias ``` ## Direct-to-xAI Tools (TTS / Image / Video / Transcription / X Search) Once you're logged in via OAuth, every direct-to-xAI tool reuses the same bearer token automatically — there is no separate setup unless you'd rather use an API key. To pick a backend for each tool: ```bash hermes tools # → Text-to-Speech → "xAI TTS" # → Image Generation → "xAI Grok Imagine (image)" # → Video Generation → "xAI Grok Imagine" # → X (Twitter) Search → "xAI Grok OAuth (SuperGrok / X Premium+)" ``` If OAuth tokens are already stored, the picker confirms it and skips the credential prompt. If neither OAuth nor XAI_API_KEY`is set, the picker offers a 3-choice menu: OAuth login, paste API key, or skip. :::note Video generation is off by default The`video_gen`toolset is disabled by default. Enable it in`hermes tools`→`🎬 Video Generation`(press space) before the agent can call`video_generate`. Otherwise the agent may fall back to the bundled ComfyUI skill, which is also tagged for video generation. ::: :::note X search auto-enables when xAI credentials are present The` x_search`toolset auto-enables whenever xAI credentials (a SuperGrok / X Premium+ OAuth token or`XAI_API_KEY`) are configured. Disable explicitly via` hermes tools`→`🐦 X (Twitter) Search`(press space) if you don't want this. The tool routes through xAI's built-in`x_search`Responses API — it works with either your SuperGrok / X Premium+ OAuth login or a paid`XAI_API_KEY`, and prefers OAuth when both are configured (uses your subscription quota instead of API spend). The tool schema is hidden from the model when no xAI credentials are configured, regardless of whether the toolset is enabled. ::: ### Models | Tool | Model | Notes | |------|-------|-------| | Chat |` grok-4.3`| Default; auto-selected when you log in via OAuth | | Chat |`grok-4.20-0309-reasoning`| Reasoning variant | | Chat |`grok-4.20-0309-non-reasoning`| Non-reasoning variant | | Chat |`grok-4.20-multi-agent-0309`| Multi-agent variant | | Image |`grok-imagine-image`| Default; ~5–10 s | | Image |`grok-imagine-image-quality`| Higher fidelity; ~10–20 s | | Video |`grok-imagine-video`| Text-to-video | | Video |`grok-imagine-video-1.5-preview`| Image-to-video; dated alias`grok-imagine-video-1.5-2026-05-30`| | TTS | (default voice) | xAI`/v1/tts`endpoint | The chat catalog is derived live from the on-disk`models.dev`cache; new xAI releases appear automatically once that cache refreshes.`grok-4.3`is always pinned to the top of the list. ## Environment Variables | Variable | Effect | |----------|--------| |`XAI_BASE_URL`| Override the default`https://api.x.ai/v1`endpoint (rarely needed). | To select xAI as the active provider, set`model.provider: xai-oauth`in`config.yaml`(use`hermes setup`for the guided flow) or pass`–provider xai-oauth`for a single invocation. ## Troubleshooting ### Token expired — not re-logging in automatically Hermes refreshes the token before each session and again reactively on a 401. If refresh fails with`invalid_grant`(the refresh token was revoked, or the account was rotated), Hermes surfaces a typed re-auth message instead of crashing. When the refresh failure is terminal (HTTP 4xx,`invalid_grant`, revoked grant, etc.), Hermes marks the refresh token as dead and quarantines it locally — subsequent calls skip the doomed refresh attempt instead of replaying the same 401 over and over. The agent surfaces a single "re-authentication required" message and stays out of the way until you log in again. Fix: run` hermes auth add xai-oauth`again to start a fresh login. The quarantine clears on the next successful exchange. ### Authorization timed out The loopback listener has a finite expiry window (default 180 s). If you don't approve the login in time, Hermes raises a timeout error. Fix: re-run`hermes auth add xai-oauth`(or`hermes model`). The flow starts fresh. ### State mismatch (possible CSRF) Hermes detected that the` state`value returned by the authorization server doesn't match what it sent. Fix: re-run the login. If it persists, check for a proxy or redirect that is modifying the OAuth response. ### Logging in from a remote server On SSH or container sessions Hermes prints the authorization URL instead of opening a browser. The loopback callback listener still binds`127.0.0.1:56121on the remote host — your laptop's browser can't reach it without an SSH local-forward: ```bash # Local machine, separate terminal: ssh -N -L 56121:127.0.0.1:56121 user@remote-host # Remote machine: hermes auth add xai-oauth --no-browser ``` Full walkthrough (jump boxes, mosh/tmux, port conflicts): [OAuth over SSH / Remote Hosts](./oauth-over-ssh.md). ### HTTP 403 after a successful login (tier / entitlement) OAuth completed in the browser, tokens are saved, but inference or token refresh returnsHTTP 403`with a message similar to "The caller does not have permission to execute the specified operation". This is not a stale-token problem — re-running`hermes model`won't change it. xAI's backend has been seen to restrict OAuth API access to specific SuperGrok tiers despite the in-app subscription being active (issue [#26847](https://github.com/NousResearch/hermes-agent/issues/26847)). Fix: set`XAI_API_KEYand switch to the API-key path: ```bash export XAI_API_KEY=xai-... hermes config set model.provider xai ``` Or upgrade your subscription at [x.ai/grok](https://x.ai/grok) if the OAuth route is required. ### "No xAI credentials found" error at runtime The auth store has noxai-oauth`entry and no`XAI_API_KEY`is set. You haven't logged in yet, or the credential file was deleted. Fix: run`hermes model`and pick the xAI Grok OAuth provider, or run`hermes auth add xai-oauth. ## Logging Out To remove all stored xAI Grok OAuth credentials: ```bash hermes auth logout xai-oauth ``` This clears both the singleton OAuth entry in auth.json`and any credential-pool rows for`xai-oauth`. Use` hermes auth remove xai-oauth <index|id|label>`if you only want to drop a single pool entry (run`hermes auth list xai-oauthto see them). ## See Also - [OAuth over SSH / Remote Hosts](./oauth-over-ssh.md) — required reading if Hermes is on a different machine than your browser - [AI Providers reference](../integrations/providers.md) - [Environment Variables](../reference/environment-variables.md) - [Configuration](../user-guide/configuration.md) - [Voice & TTS](../user-guide/features/tts.md) ---  # Nous Portal # Nous Portal [Nous Portal](https://portal.nousresearch.com) is Nous Research's unified subscription gateway and the recommended way to run Hermes Agent. One OAuth login replaces the juggling act of separate accounts, API keys, and billing relationships across every model lab, search API, image generator, and browser provider you'd otherwise need to wire up by hand. If you only have time to set up one thing, set up this. The fastest path: ```bash hermes setup --portal ``` That single command runs the Portal OAuth, lets you pick a Nous model, sets Nous as your inference provider inconfig.yaml`, and turns on the Tool Gateway. You're ready to` hermes chatimmediately after. Don't have a subscription yet? [portal.nousresearch.com/manage-subscription](https://portal.nousresearch.com/manage-subscription) — sign up, then come back and run the command above. ## What's in the subscription ### 300+ frontier models, one bill The Portal proxies a curated catalog of agentic models from across the ecosystem — billed against your Nous subscription instead of one credit balance per lab. | Family | Models | |--------|--------| | Anthropic Claude | Opus 4.7, Opus 4.6, Sonnet 4.6, Haiku 4.5 | | OpenAI | GPT-5.5, GPT-5.5 Pro, GPT-5.4 Mini, GPT-5.4 Nano, GPT-5.3 Codex | | Google Gemini | Gemini 3 Pro Preview, Gemini 3 Flash Preview, Gemini 3.1 Pro Preview, Gemini 3.1 Flash Lite Preview | | DeepSeek | DeepSeek V4 Pro | | Qwen | Qwen3.7-Max, Qwen3.6-35B-A3B | | Kimi / Moonshot | Kimi K2.6 | | GLM / Zhipu | GLM-5.1 | | MiniMax | MiniMax M2.7 | | xAI | Grok 4.3 | | NVIDIA | Nemotron-3 Super 120B-A12B | | Tencent | Hunyuan 3 Preview | | Xiaomi | MiMo V2.5 Pro | | StepFun | Step 3.5 Flash | | Hermes | Hermes-4-70B, Hermes-4-405B (chat, see [note below](#a-note-on-hermes-4)) | | + everything else | 280+ additional models — the full agentic frontier | Routing happens through OpenRouter under the hood, so model availability and failover behavior matches what you'd get with an OpenRouter key — just billed against your Nous subscription instead. Switch between Claude Sonnet 4.6 for code and Gemini 3 Pro for long context with/modelmid-session — no new credentials, no top-ups, no surprise zero-balance errors. ### The Nous Tool Gateway The same subscription unlocks the [Tool Gateway](/user-guide/features/tool-gateway), which routes Hermes Agent's tool calls through Nous-managed infrastructure. Five backends, one login: | Tool | Partner | What it does | |------|---------|--------------| | Web search & extract | Firecrawl | Agent-grade search and full-page extraction. No Firecrawl API key, no rate limit babysitting. | | Image generation | FAL | Nine models under one endpoint: FLUX 2 Klein 9B, FLUX 2 Pro, Z-Image Turbo, Nano Banana Pro (Gemini 3 Pro Image), GPT Image 1.5, GPT Image 2, Ideogram V3, Recraft V4 Pro, Qwen Image. | | Text-to-speech | OpenAI TTS | High-quality TTS without a separate OpenAI key. Enables [voice mode](/user-guide/features/voice-mode) across messaging platforms. | | Cloud browser automation | Browser Use | Headless Chromium sessions forbrowser_navigate`,` browser_click`,` browser_type`,` browser_vision. No Browserbase account needed. | | Cloud terminal sandbox | Modal | Serverless terminal sandboxes for code execution (optional add-on). | Without the gateway, hooking each of those up means a Firecrawl account, a FAL account, a Browser Use account, an OpenAI key, and a Modal account — five separate signups, five separate dashboards, five separate top-up flows. With the gateway, all of it routes through one subscription. You can also enable just specific gateway tools (e.g. web search but not image generation) — see [Mixing the gateway with your own backends](#mixing-the-gateway-with-your-own-backends) below. ### Nous Chat Your Portal account also covers [chat.nousresearch.com](https://chat.nousresearch.com) — Nous Research's web chat interface with the same model catalog. Useful when you're away from your terminal, or for non-agent conversation work. ### No credentials in your dotfiles Because everything routes through one OAuth-authenticated Portal session, you don't accumulate a .env`file with a dozen long-lived API keys. The refresh token at`/.hermes/auth.jsonis the only credential on disk, and Hermes mints short-lived JWTs from it per request — see [Token handling](#token-handling) below. ### Cross-platform parity [Native Windows](/user-guide/windows-native) makes per-tool API key setup its rough edge — installing a Firecrawl account, a FAL account, a Browser Use account, an OpenAI key from Windows is the highest-friction part of getting a useful agent. A Portal subscription smooths that out: one OAuth covers the model and every gateway tool, so Windows users get the same experience as macOS/Linux without manually configuring four backends. ## A note on Hermes 4 Nous Research's own Hermes 4 family (Hermes-4-70B, Hermes-4-405B) is available through the Portal at heavily discounted rates. These are frontier hybrid-reasoning chat models — strong at math, science, instruction following, schema adherence, roleplay, and long-form writing. They are not recommended for use inside Hermes Agent, however. Hermes 4 is tuned for chat and reasoning, not the rapid-fire tool-calling loop the agent relies on. Use them for [Nous Chat](https://chat.nousresearch.com), for research workflows, or via the [subscription proxy](/user-guide/features/subscription-proxy) from other tooling — but for agent work, pick a frontier agentic model from the catalog instead: ```bash /model anthropic/claude-sonnet-4.6 # best general-purpose agentic model /model openai/gpt-5.5-pro # strong reasoning + tool calling /model google/gemini-3-pro-preview # huge context window /model deepseek/deepseek-v4-pro # cost-effective coder ``` The Portal's own [model info page](https://portal.nousresearch.com/info) carries the same warning, so this isn't a Hermes-side opinion — it's the official guidance from Nous Research. ## Setup ### Fresh install — one command ```bash hermes setup --portal ``` This runs the full setup in one shot: 1. Opens your browser to portal.nousresearch.com for OAuth login 2. Stores the refresh token at/.hermes/auth.json`3. Lets you pick a Nous model from the curated list (or skip to keep your current one) 4. Sets Nous as your inference provider in`/.hermes/config.yaml`(when you pick a model) 5. Turns on the Tool Gateway (web, image, TTS, browser routing) 6. Returns you to your terminal ready to`hermes chatIf you don't have a subscription yet, sign up at [portal.nousresearch.com/manage-subscription](https://portal.nousresearch.com/manage-subscription) first. ### Existing install — add Portal alongside other providers If you already have Hermes configured with OpenRouter, Anthropic, or any other provider and you want to add the Portal alongside them: ```bash hermes model # pick "Nous Portal" from the provider list # browser opens, sign in, done ``` Your existing providers stay configured. You can switch between them with/model`mid-session or`hermes model `between sessions — the Portal becomes one of your available providers, not your only one. ### Headless / SSH / remote setup OAuth needs a browser, but the loopback callback runs on the machine where Hermes is running. For remote hosts, see [OAuth over SSH / Remote Hosts](/guides/oauth-over-ssh) — the same patterns work for the Portal as for any other OAuth-based provider (`ssh -L`port forwarding,`–manual-pastefor browser-only environments like Cloud Shell / Codespaces). ### Profile setup If you use [Hermes profiles](/user-guide/profiles), the Portal refresh token is automatically shared across all profiles via a shared token store. Sign in once on any profile, and the rest pick it up automatically — no need to repeat the OAuth flow per profile. ## Using the Portal day-to-day ### Inspecting what's wired up ```bash hermes portal # log in to Nous Portal + set it up (one-shot onboarding) hermes portal info # login status, subscription info, model + gateway routing hermes portal status # alias forportal infohermes portal tools # detailed Tool Gateway catalog with per-tool routing hermes portal open # open the subscription management page in your browser ```hermes portal`(with no subcommand) is the human-readable alias for`hermes auth add nous –type oauth`— it logs you in, lets you pick a Nous model, sets Nous as your inference provider, and offers the Tool Gateway opt-in (identical to`hermes setup –portal`, and the same Nous flow as the first-time quick setup).` hermes portal infogives you the high-level overview: ``` Nous Portal ─────────── Auth: ✓ logged in Portal: https://portal.nousresearch.com Model: ✓ using Nous as inference provider Tool Gateway ──────────── Web search & extract via Nous Portal Image generation via Nous Portal Text-to-speech via Nous Portal Browser automation via Nous Portal Cloud terminal not configured ``` ### Switching models Inside a session: ```bash /model anthropic/claude-sonnet-4.6 /model openai/gpt-5.5-pro /model google/gemini-3-pro-preview ``` Or open the picker: ```bash /model # arrow keys, enter to select ``` Outside a session (the full setup wizard, useful when adding a new provider): ```bash hermes model ``` ### Mixing the gateway with your own backends If you already have, say, a Browserbase account and want to keep using it while routing web search and image generation through Nous, that's supported. Usehermes toolsto pick backends per tool: ```bash hermes tools # → Web search → "Nous Subscription" # → Image generation → "Nous Subscription" # → Browser → "Browserbase" (your existing key) # → TTS → "Nous Subscription" ``` The Tool Gateway is opt-in per tool, not all-or-nothing. The managed backends show up inhermes toolswhether or not you're logged into Nous Portal — if you pick "Nous Subscription" before authenticating, Hermes runs the Portal login inline (it won't change your inference provider or touch your other tools). See the [Tool Gateway docs](/user-guide/features/tool-gateway) for the full per-tool configuration matrix. ### Subscription management Manage your plan, view usage, or upgrade/cancel at any time: - Web: [portal.nousresearch.com/manage-subscription](https://portal.nousresearch.com/manage-subscription) - CLI shortcut:hermes portal open`(opens the same page in your default browser) ## Configuration reference After`hermes setup –portal`,` /.hermes/config.yamlwill look like: ```yaml model: provider: nous default: anthropic/claude-sonnet-4.6 # or whatever model you picked base_url: https://inference-api.nousresearch.com/v1 ``` The Tool Gateway settings live under their respective tool sections: ```yaml web: backend: nous # web search/extract routes through Tool Gateway image_gen: provider: nous tts: provider: nous browser: backend: nous ``` The OAuth refresh token is stored separately at/.hermes/auth.json`(not in`config.yaml— credentials and configuration are kept separate by design). ## Token handling Hermes mints a short-lived JWT from your stored Portal refresh token on each inference call rather than reusing a long-lived API key. The token lifecycle is fully automatic — refresh, mint, retry on transient 401 — and you never see it. If the Portal invalidates the refresh token (password change, manual revoke, session expiry), the invalid refresh token is quarantined locally so Hermes stops replaying it and you don't see a stream of identical 401s. The next call surfaces a clear "re-authentication required" message. Runhermes auth add nous`to log in again; the quarantine clears on the next successful login. ## Troubleshooting ###`hermes portal infoshows "not logged in" You haven't completed the OAuth flow, or your refresh token was wiped. Run: ```bash hermes portal ``` or usehermes model`and re-select Nous Portal. ### Got a "re-authentication required" message mid-session Your Portal refresh token was invalidated (password change, manual revoke, or session expiry). Run`hermes auth add nous`and your next request will use the new credentials. Any quarantine on the old token clears automatically on successful re-login. ### Want to use a specific provider model that the Portal doesn't expose The Portal proxies through OpenRouter, so any model that OpenRouter supports is generally available. If a specific model isn't appearing in`/model, try the OpenRouter-style slug directly: ```bash /model anthropic/claude-opus-4.6 ``` If a model is genuinely missing, [open an issue](https://github.com/NousResearch/hermes-agent/issues) — we surface the Portal's catalog to Hermes and gaps usually mean a routing config we can update. ### Bills not appearing on my Portal account Check hermes portal info `first — if it shows you're using a different provider (`Model: currently openrouter`instead of`using Nous as inference provider`), your local config has drifted. Run` hermes model, pick Nous Portal, and the next request will route through your subscription. ## See also - [Tool Gateway](/user-guide/features/tool-gateway) — Full details on every gateway tool, per-tool config, and pricing - [Subscription proxy](/user-guide/features/subscription-proxy) — Use your Portal subscription from non-Hermes tools (other agents, scripts, third-party clients) - [Voice mode](/user-guide/features/voice-mode) — Voice conversations using the Portal's OpenAI TTS - [AI Providers](/integrations/providers) — Full provider catalog if you want to compare alternatives - [OAuth over SSH](/guides/oauth-over-ssh) — Login from remote hosts or browser-only environments - [Profiles](/user-guide/profiles) — Multiple Hermes configurations sharing one Portal login ---  # Desktop App # Desktop App The Hermes desktop app is a native app built around the same agent you get from the CLI and the gateway — same config, same API keys, same sessions, same skills, same memory. It is not a separate product or a lightweight clone; it uses the same Hermes Agent core and settings, and drives it through a modern & thoughtfully designed UI. If you have used hermes `in a terminal, everything you set up there is already here, and anything you do here shows up there. It runs on macOS, Windows, and Linux. :::tip Which interface is which? Hermes has several front ends that all talk to the same agent: - Desktop App (this page) — a native application with a purpose-built UI for chat, configuration, and management. - CLI (`hermes`) and [TUI](./tui.md) (`hermes –tui`) — terminal interfaces. - [Web Dashboard](./features/web-dashboard.md) (`hermes dashboard) — a browser admin panel; its optional Chat tab embeds the TUI through a pseudo-terminal. Pick whichever fits the moment. They share state, so you can start a session in one and resume it in another. ::: ## Install Follow the [installation instructions for Hermes Desktop](../getting-started/installation.md). If you already have Hermes installed, simply run ```bash hermes desktop ``` That uses your current config, keys, sessions, and skills. ## What's in the app The desktop app is organized as a chat-first window with a left sidebar for navigation. It's built to allow managing multiple simultaneous agent conversations, configuring messaging providers, creating artifacts, browsing projects' folder structures, and working on multiple projects at once. ### Chat The center of the app. You get: - Streaming responses with live tool activity and structured tool-call summaries as the agent works. - The same conversation history as every other Hermes surface — sessions started here resume in the CLI/TUI and vice versa. - Drag-and-drop files anywhere in the chat area to attach them to your next message. - A right-hand preview rail — render web pages, files, and tool outputs side by side while you keep chatting. - Composer history and queue editing — press the up/down arrow keys in an empty composer to recall and reuse previous prompts, and edit messages you've queued up before they're sent. #### Status bar The bar along the bottom of the chat shows live session state and exposes quick controls without opening Settings: - Inline model picker — switch the model for the active session straight from the status bar. - Per-session YOLO toggle — flip YOLO on or off for just this session (matching the TUI). YOLO bypasses the dangerous-command approval prompts, so know what you're turning off — see [Security → YOLO Mode](./security.md#yolo-mode). Chatting against a Hermes instance on another machine instead of the bundled local backend? See [Connecting to a remote backend](#connecting-to-a-remote-backend) below — and for the full picture of how the remote-hosted dashboard connection works (the auth gate, the /api/ws`chat socket, and WebSocket close-code triage), see [Web Dashboard → Connecting Hermes Desktop to a remote backend](./features/web-dashboard.md#connecting-hermes-desktop-to-a-remote-backend). ### File browser Explore and preview the working directory without leaving the app — useful for following along as the agent reads, writes, and edits files. Set the initial project directory with`hermes desktop –cwd `(or the`HERMES_DESKTOP_CWDenvironment variable). ### Voice Talk to Hermes and hear it back, the same [voice mode](./features/voice-mode.md) available elsewhere. On macOS the OS will prompt once for microphone access. ### Settings & onboarding Manage providers, models, tools, and credentials from a real UI instead of editing YAML. First-run onboarding gets you to your first message in seconds. The settings panes cover providers/keys, model selection, toolset configuration, MCP servers, the gateway, and session management. - Providers settings pane — a dedicated place to manage inference providers, with an Accounts / API-keys UX for signing in and storing credentials per provider. - Every provider and model in the menus — the GUI surfaces the full provider list and every model thathermes modelknows about, so you pick from the same catalog the CLI sees rather than a curated subset. - xAI Grok OAuth — Grok is a first-class OAuth provider in the launcher; sign in through the browser flow like the other OAuth providers. - Tool-backend installs from the GUI — run a tool backend's post-setup install steps directly from the app instead of dropping to a terminal. - Auxiliary-model warning — if you switch the main model to a new provider while auxiliary tasks (titling, summarization, and similar helpers) are still pinned to another provider, the app warns you so you don't unknowingly split work across two providers. First-run onboarding has been redesigned on a unified overlay design system, and you can pick Choose provider later to skip provider setup and get into the app first. ### Management panes The app also surfaces the broader Hermes management surface so you don't have to drop to a terminal: - Skills — browse, install, and manage [skills](./features/skills.md). - Cron — view and manage [scheduled jobs](../reference/cli-commands.md#hermes-cron). - Profiles — switch between [Hermes profiles](./profiles.md) (isolated config/skills/sessions). - Messaging — set up gateway channels. - Agents and Command Center — orchestration surfaces for multi-agent work. ### Keyboard & navigation - Command palette — press Cmd+K (Ctrl+K on Windows/Linux) to jump to actions and navigate the app from the keyboard. - Rebindable shortcuts — a shortcuts panel in Settings lets you remap the app's keyboard shortcuts to your own keys. - Custom zoom shortcuts — zoom the interface in half-step increments for finer control over text size. - UI language switcher — change the app's interface language in-app, including Simplified Chinese (zh-Hans). ### Sessions & profiles - Session-list overhaul — a reworked session list with archiving and general session hygiene to keep the list manageable as it grows. - Search sessions by id — find a specific session directly by its id. - Concurrent multi-profile sessions — run sessions across multiple [profiles](./profiles.md) at the same time, and reference a session in another profile with cross-profile@session`links. ## Updating The app checks for updates in the background and offers a one-click update when one is ready. The [manual update process](https://hermes-agent.nousresearch.com/docs/getting-started/updating) also works with the GUI. ## Uninstalling Open Settings → About → Danger zone and pick how much to remove: - Uninstall Chat GUI only — removes the desktop app and its data; the Hermes agent, your config, and your chats stay. (Same as`hermes uninstall –gui`.) - Uninstall GUI + agent, keep my data — removes the app and the agent but keeps config, chats, and secrets for a future reinstall. (Same as` hermes uninstall`.) - Uninstall everything — removes the app, the agent, and all user data. (Same as` hermes uninstall –full`.) The app closes to finish the job (the cleanup runs after it exits so it can remove the running app bundle and its own venv). The agent-removing options are hidden automatically when no local agent is installed (for example, a GUI-only "lite" client connected to a remote backend). You can do the same from the terminal —` hermes uninstall –gui`for the GUI alone, or`hermes uninstall`/`hermes uninstall –full`for the agent too. :::note Running`hermes uninstall –gui`from a source checkout (a`hermes desktop`dev build) also removes the workspace`node_modules`and`apps/desktop/{dist,release}`build output, since those are GUI build artifacts. They're recoverable with`hermes desktop`(or`npm install`+ a rebuild) — but if you're actively hacking on the desktop app, expect to reinstall dependencies afterward. ::: ## CLI reference:`hermes desktop`To launch via the CLI, simply run`hermes desktop`. By default it installs workspace Node dependencies, builds the current OS's unpacked Electron app, then launches that packaged artifact. | Flag | Description | | -------------------- | ----------------------------------------------------------------------------------------- | |` –skip-build`| Skip npm install/package and launch the existing unpacked app from`apps/desktop/release`| |`–force-build`| Force a full rebuild even if the content stamp matches | |`–build-only`| Build the desktop app but do not launch it (used by`hermes update`) | |` –source`| Launch via`electron .`against`apps/desktop/dist`instead of the packaged app | |`–cwd PATH`| Initial project directory for desktop chat sessions (sets`HERMES_DESKTOP_CWD`) | |` –hermes-root PATH`| Override the Hermes source root the app uses (sets`HERMES_DESKTOP_HERMES_ROOT`) | |` –ignore-existing`| Force the app to ignore any`hermes`CLI already on`PATH`during backend resolution | |`–fake-boot`| Enable deterministic boot delays for validating the startup UI | ## How it works The packaged app ships only the Electron shell. On first launch it installs the Hermes Agent runtime into`HERMES_HOME `(`/.hermes`, or` %LOCALAPPDATA%\hermes`on Windows) — the same layout a CLI install uses, which is why the two are interchangeable. The React renderer talks to a`hermes dashboard`backend over the standard gateway APIs and reuses the agent rather than reimplementing it. Install, backend-resolution, and self-update logic live in the Electron main process. ## Connecting to a remote backend By default the app starts and manages its own local backend. You can instead point it at a Hermes backend running on another machine — a VPS, a home server, or a Mini behind Tailscale. :::info The remote backend is a running`hermes dashboard `process "Remote backend" means a `hermes dashboard` server running on the remote machine — that is the process the desktop app connects to. Nothing in this section works unless that dashboard is actually up and reachable. The desktop app does not start it for you; you (or a` systemd`service) keep`hermes dashboardrunning on the remote host, and the app attaches to it. If you also use messaging channels (Telegram, Discord, etc.), the gateway is a separate long-running process you start independently — see the note after the setup steps. ::: The connection has two halves: on the backend you protect the dashboard with an auth provider, and in the app you enter the backend's URL and sign in. Binding the dashboard to a non-loopback address automatically engages its auth gate, and the provider you configure is what lets the desktop app through. Pick a provider based on where the backend lives: - OAuth (Nous Portal) — preferred for anything reachable beyond your own machine. Logins are verified against your Nous account, so this is the option suitable for a VPS, a public host, or any remote backend. Register the dashboard withhermes dashboard register `(or the Portal [`/local-dashboards](https://portal.nousresearch.com/local-dashboards) page) to provision its OAuth client, then sign in from the app with Sign in with Nous Research. A self-hosted OIDC provider works the same way if you run your own identity provider. - Username/password — local / trusted-network use only. The simplest option when the backend is on the same trusted LAN or reachable only over a VPN (e.g. Tailscale). It protects a single shared credential with no external identity provider, so do not use it for a dashboard exposed to the public internet — reach for OAuth there instead. The rest of this section shows the username/password path because it's the quickest to stand up on a trusted network; for the OAuth path see [Web Dashboard → Default provider: Nous Research](./features/web-dashboard.md#default-provider-nous-research). ### On the backend (the remote machine) Set a username and password, then start the dashboard bound to a reachable address. The credentials live in /.hermes/.env(the secrets file, mode 0600): ```bash # 1. Set the dashboard login credentials. cat >> ~/.hermes/.env <<'EOF' HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password # Recommended: a stable signing secret so sessions survive restarts. # Without it a random key is generated per boot and you'll be logged out # on every restart. HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32) EOF chmod 600 ~/.hermes/.env # 2. Run the dashboard bound to a reachable address. The non-loopback bind # engages the auth gate; the username/password provider handles login. hermes dashboard --no-open --host 0.0.0.0 --port 9119 ``` Keep thathermes dashboard`process running for as long as you want the desktop app to be able to connect — if it stops, the app can no longer reach the backend. Run it under`systemd`,` tmux`, or your process manager of choice so it survives logout and reboots. Separately, make sure the gateway is running on the remote host if you rely on messaging channels — the dashboard backend is what the desktop app talks to, but your Telegram/Discord/Slack gateway sessions are a different process that you start and keep running on their own. See [Messaging](./messaging/index.md) for gateway setup. Prefer not to keep a plaintext password at rest? Set` HERMES_DASHBOARD_BASIC_AUTH_PASSWORD_HASH`to a scrypt hash instead — compute it with`python -c “from plugins.dashboard_auth.basic import hash_password; print(hash_password(‘PW’))”`. Full configuration surface (config.yaml keys, every env var, the rate limiter): [Web Dashboard → Username/password provider](./features/web-dashboard.md#usernamepassword-provider-no-oauth-idp). Running the dashboard as a systemd service? Give the unit` EnvironmentFile=%h/.hermes/.env`so the credentials are in the environment at boot. :::warning The dashboard reads and writes your`.env `(API keys, secrets) and can run agent commands. The username/password setup shown above is for a trusted network — never expose a password-protected dashboard directly to the open internet; put it behind a VPN. [Tailscale](https://tailscale.com/) is the clean option: bind to the machine's tailscale IP (`–host `) and use` http://:9119`as the Remote URL so only your tailnet can reach it. To reach a backend over the public internet, use the OAuth (Nous Portal) provider instead. ::: ### In the app Settings → Gateway → Remote gateway: 1. Remote URL —`http://:9119`(path prefixes like`/hermes`work if you front it with a reverse proxy) 2. Sign in — the app detects which provider the backend advertises and adapts the button. For a username/password backend it shows a Sign in button that opens a credential form (enter the credentials from step 1). For an OAuth backend it shows Sign in with (e.g. Sign in with Nous Research), which runs the provider's browser sign-in. Either way the app ends up with an authenticated session against the backend. 3. Save and reconnect — switches the desktop shell onto the remote backend. The session refreshes automatically; you stay signed in across restarts when` HERMES_DASHBOARD_BASIC_AUTH_SECRET`is set. You can also set the backend URL without the UI via the`HERMES_DESKTOP_REMOTE_URLenvironment variable before launching the app (it overrides the in-app setting); you still sign in from the Gateway settings panel. :::note Per-profile remote hosts The remote gateway host is configured per [profile](./profiles.md), so each profile can point at its own remote backend (or stay on its local one). Switching profiles switches which remote host the app connects to. ::: ### Troubleshooting - Sign-in fails with 401 / "Invalid credentials" — the username or password doesn't match the backend'sHERMES_DASHBOARD_BASIC_AUTH_USERNAME`/`HERMES_DASHBOARD_BASIC_AUTH_PASSWORD`. The backend returns the same generic error for an unknown user and a wrong password (no enumeration oracle), so double-check both. Confirm the gate is on with` curl -s http://:9119/api/status | jq ‘.auth_required, .auth_providers’`— it should report`true`and include`“basic”`. - No "Sign in" button — it asks for a session token instead — the backend's username/password provider isn't active.` /api/status`won't list`“basic”`in`auth_providers`. Make sure both the username and a password (or password hash) are set in` ~/.hermes/.env`and that the dashboard process actually loaded them. - Signed out on every restart — set`HERMES_DASHBOARD_BASIC_AUTH_SECRET`to a stable value. Without it the token-signing key is regenerated per boot, invalidating all sessions. - Connection refused / times out — the backend bound to`127.0.0.1`(the default) or a firewall/VPN is blocking the port. Bind to`0.0.0.0`or the tailscale IP and open the port to your trusted network. For the same setup from the web-dashboard angle, see [Web Dashboard → Connecting Hermes Desktop to a remote backend](./features/web-dashboard.md#connecting-hermes-desktop-to-a-remote-backend); the env vars are catalogued under [Environment Variables → Web Dashboard & Hermes Desktop](../reference/environment-variables.md#web-dashboard--hermes-desktop). ## Troubleshooting Boot logs land in`HERMES_HOME/logs/desktop.log(it includes backend output and recent Python tracebacks) — check it first if the app reports a boot failure. You can also tail it from the CLI: ```bash hermes logs gui -f ``` Common resets: ```bash # Force a clean first-launch setup (macOS/Linux) rm "$HOME/.hermes/hermes-agent/.hermes-bootstrap-complete" # Rebuild a broken Python venv (macOS/Linux) rm -rf "$HOME/.hermes/hermes-agent/venv" # Reset a stuck macOS microphone prompt tccutil reset Microphone com.nousresearch.hermes ``` ### "Build desktop app" stuck on Electron download The build downloads the Electron runtime (~114 MB) fromgithub.com/electron/electron/releases`. If the installer hangs on the Build desktop app step with the live output repeating` retrying attempt=…`, GitHub is being blocked or throttled on your network (firewall, proxy, or region). The installer self-heals this automatically: on a failed build it (1) clears a corrupt cached Electron zip and retries, then (2) if it still fails and you haven't set` ELECTRON_MIRROR`, retries once more through` npmmirror.com`, the de-facto Electron community mirror.` @electron/get`SHASUM-checks the download, but the checksums come from the same mirror — that catches a corrupt or partial download, not a compromised mirror. If you'd rather not trust a third-party host, pin your own`ELECTRON_MIRROR`(below); the build never overrides one you've set. To choose your own mirror (e.g. a corporate/trusted one), set`ELECTRON_MIRRORbefore installing or rebuild manually — the build honors it and won't override it: ```bash ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ \ bash -c 'cd "$HOME/.hermes/hermes-agent/apps/desktop" && CSC_IDENTITY_AUTO_DISCOVERY=false npm run pack' ``` To clear a corrupt cached zip by hand: ```bash rm -f "$HOME/Library/Caches/electron"/electron-.zip # macOS rm -f "$HOME/.cache/electron"/electron-.zip # Linux ``` ## Building from source If you want to hack on the app itself, install workspace deps from the repo root once, then run the dev server fromapps/desktop: ```bash npm install # from repo root — links apps/desktop, web, apps/shared cd apps/desktop npm run dev # Vite renderer + Electron, which boots the Python backend ``` Point the app at a specific checkout, or sandbox it from your real config: ```bash HERMES_DESKTOP_HERMES_ROOT=/path/to/clone npm run dev HERMES_HOME=/tmp/throwaway npm run dev npm run dev:fake-boot # exercise the startup overlay with deterministic delays ``` Build installers: ```bash npm run dist:mac # DMG + zip npm run dist:win # NSIS + MSI npm run dist:linux # AppImage + deb + rpm npm run pack # unpacked app under release/ (no installer) ``` macOS/Windows signing and notarization run automatically when the relevant credentials are present in the environment (CSC_LINK`/`CSC_KEY_PASSWORD`/`APPLE`for macOS,`WIN_CSCfor Windows). ## See also - [CLI Guide](./cli.md) — the terminal interface - [TUI](./tui.md) — the modern terminal UI the desktop backend reuses - [Web Dashboard](./features/web-dashboard.md) — browser admin panel with an embedded chat tab - [Configuration](./configuration.md) — config that the desktop app reads and writes - [Windows (Native)](./windows-native.md) — native Windows install path ---  # user-guide/features/codex-app-server-runtime.md # Codex App-Server Runtime Hermes can optionally handopenai/`and`openai-codex/`turns to the [Codex CLI app-server](https://github.com/openai/codex) instead of running its own tool loop. When enabled, terminal commands, file edits, sandboxing, and MCP tool calls all execute inside Codex's runtime — Hermes becomes the shell around it (sessions DB, slash commands, gateway, memory and skill review). This is opt-in only. Default Hermes behavior is unchanged unless you flip the flag. Hermes never auto-routes you onto this runtime. :::tip Not using OpenAI Codex?`hermes setup –portal`configures a non-Codex backend with Claude/Gemini/etc. in one step. See [Nous Portal](/integrations/nous-portal). ::: ## Why - Run OpenAI agent turns against your ChatGPT subscription (no API key required) using the same auth flow Codex CLI uses. - Use Codex's own toolset and sandbox —`shell`for terminal/read/write/search,`apply_patch`for structured edits,`update_plan`for planning, all running inside seatbelt/landlock sandboxing. - Native Codex plugins — Linear, GitHub, Gmail, Calendar, Canva, etc. — installed via`codex pluginare auto-migrated and active in your Hermes session. - Hermes' richer tools come along — web_search, web_extract, browser automation, vision, image generation, skills, and TTS work via an MCP callback. Codex calls back into Hermes for tools it doesn't have built in. - Memory and skill nudges keep working — Codex's events are projected into Hermes' message shape so the self-improvement loop sees a normal-looking transcript. ## What tools the model actually has This is the part most users want to know up front. When this runtime is on, the model running your turn has three independent sources of tools: ### 1. Codex's built-in toolset (always on) These ship withcodex app-server `itself — no Hermes involvement, no MCP, no plugins. All five are available the moment the runtime starts: - `shell` — runs arbitrary shell commands inside the sandbox. This is how the model reads files (`cat`,` head`,` tail`), writes them (`echo > foo`, heredocs), searches them (`find`,` rg`,` grep`), navigates directories (`ls`,` cd`), runs builds, manages processes, and anything else you'd do in bash. - `apply_patch` — applies a structured multi-file diff in Codex's patch format. The model uses this for non-trivial code edits (adding a function, refactoring across files); shell heredocs are still available for one-off writes. - `update_plan` — codex's internal todo / plan tracker. Equivalent of Hermes'` todo `tool, but managed entirely inside codex's runtime. - `view_image` — load a local image file into the conversation so the model can see it. - `web_search` — codex has its own built-in web search when configured. Hermes also exposes` web_search `(Firecrawl-backed) via the callback below; the model picks whichever it prefers. So anything you'd do via terminal — read/write/search/find/run — codex does natively. The sandbox profile (`:workspace`by default when you enable the runtime) controls what's writable. ### 2. Native Codex plugins (auto-migrated from your`codex plugin`install) When you enable the runtime, Hermes queries codex's`plugin/list`RPC and writes a`[plugins.“@openai-curated”]entry for every plugin you have installed. The plugins themselves are managed by codex and authorized once via codex's own UI. Examples (the ones the OpenClaw thread highlighted as "YouTube-video-worthy"): - Linear — find/update issues - GitHub — search code, view PRs, comment - Gmail — read/send mail - Google Calendar — create/find events - Outlook calendar/email — same shape via the Microsoft connector - Canva — design generation - ...whatever else you've installed viacodex plugin marketplace add openai-curated`+`codex plugin install … `What's NOT migrated: - Plugins you haven't installed yet — install them in Codex first. - ChatGPT app marketplace entries (`app/list`) — these are already enabled inside codex by virtue of your account auth. ### 3. Hermes tool callback (MCP server, registered in` /.codex/config.toml`) Hermes registers itself as an MCP server so codex can call back for tools codex doesn't ship with. Available via the callback: - `web_search` / `web_extract` — Firecrawl-backed; tends to be cleaner than scraping for structured content. - `browser_navigate`/`browser_click`/`browser_type`/`browser_press`/`browser_snapshot`/`browser_scroll`/`browser_back`/`browser_get_images`/`browser_console`/`browser_vision` — full browser automation via Camofox or Browserbase. - `vision_analyze` — call a separate vision model to inspect an image (different from codex's` view_image `which loads it into the conversation). - `image_generate` — image generation through Hermes' image_gen plugin chain. - `skill_view`/`skills_list` — read from Hermes' skill library. - `text_to_speech` — TTS through Hermes' configured provider. When the model wants one of these, codex spawns the` hermes_tools_mcp_server`subprocess via stdio MCP, the call is dispatched through`model_tools.handle_function_call() `(same code path as Hermes' default runtime), and the result is returned to codex like any other MCP response. ### What's NOT available on this runtime These four Hermes tools require the running AIAgent context (mid-loop state) to dispatch, and a stateless MCP callback can't drive them. Switch back to the default runtime (`/codex-runtime auto`) when you need any of them: - `delegate_task` — spawn subagents - `memory` — Hermes' persistent memory store - `session_search` — cross-session search - `todo` — Hermes' todo store (codex's` update_plan `is the in-runtime equivalent) ## Workflow features (`/goal`, kanban, cron) ###` /goal`(the Ralph loop) Works on this runtime. Goals persist in`state_meta`keyed by session id, the continuation prompt feeds back as a normal user message through`run_conversation()`, and codex executes the next turn natively. The goal judge runs via the auxiliary client (configured via` auxiliary.goal_judge`in config.yaml), independent of which runtime is active. The judge's "blocked, needs user input" verdict is a clean escape if codex stalls on approvals. One thing to be aware of: each continuation prompt is a fresh codex turn, which means codex re-evaluates command approval policy from scratch. If you're doing a long-running goal with lots of writes, expect more approval prompts than you'd see on a single in-session task. Set`default_permissions = “:workspace”`(which Hermes does automatically when you enable the runtime) so simple workspace writes don't require prompting. ### Kanban (multi-agent worktree dispatch) Works on this runtime, with one subtle dependency. The kanban dispatcher spawns each worker as a separate`hermes chat -q`subprocess that reads the user's config — which means if`model.openai_runtime: codex_app_server `is set globally, workers also come up on the codex runtime. What works inside a codex-runtime worker: - Codex's full toolset (shell, apply_patch, update_plan, view_image, web_search) — the worker does its actual task work natively - The migrated codex plugins — Linear, GitHub, etc. - The Hermes tool callback for browser_, vision, image_gen, skills, TTS What also works because the MCP callback exposes them: - `kanban_complete`/`kanban_block`/`kanban_comment`/`kanban_heartbeat` — the worker handoff tools. These read` HERMES_KANBAN_TASK`from env (set by the dispatcher), gate access correctly, and write to the per-board SQLite DB pinned by`HERMES_KANBAN_DB`. Without these in the callback, a worker on this runtime could do its task but couldn't report back, hanging until the dispatcher's timeout. - `kanban_show`/`kanban_list` — read-only board queries for the worker to check its own context. - `kanban_create`/`kanban_unblock`/`kanban_link` — orchestrator-only operations. Available for orchestrator agents running on the codex runtime that need to dispatch new tasks. The kanban tools are gated by` HERMES_KANBAN_TASK`env var the dispatcher sets — that var is propagated to the codex subprocess (codex inherits env) and from there to the spawned`hermes-tools`MCP server subprocess. So the tools see the right task id and gate correctly. For Codex app-server workers, Hermes also passes narrow app-server sandbox overrides when`HERMES_KANBAN_TASK`is present: keep`workspace-write `sandboxing, add the board DB directory plus every Kanban path the dispatcher pinned as extra writable roots (`HERMES_KANBAN_WORKSPACES_ROOT`,` HERMES_KANBAN_WORKSPACE`, legacy` HERMES_KANBAN_ROOT`— deduplicated, DB-dir first), and keep network disabled by default. This avoids the brittle`:danger-no-sandbox`workaround while letting`kanban_complete`/`kanban_block`update the board DB and letting workers write reports/artifacts under workspace mounts that live outside the DB directory (e.g.`/media/…/kanban-workspaces/…`on a separate drive — [issue #27941](https://github.com/NousResearch/hermes-agent/issues/27941)). ### Cron jobs Not specifically tested. Cron jobs run via`cronjob`→`AIAgent.run_conversation`, the same code path as the CLI. If the cron job's config has` openai_runtime: codex_app_server`it'll run on codex. The same tool-availability rules apply — codex built-ins + plugins + MCP callback work, agent-loop tools (delegate_task, memory, session_search, todo) don't. If your cron job relies on those, scope the cron to a profile that uses the default runtime. ## Trade-offs | | Hermes default runtime | Codex app-server (opt-in) | |---|---|---| |`delegate_task`subagents | yes | not available — needs agent loop context | |`memory`,` session_search`,` todo`| yes | not available — needs agent loop context | |`web_search`,` web_extract`| yes | yes (via MCP callback) | | Browser automation (Camofox/Browserbase) | yes | yes (via MCP callback) | |`vision_analyze`,` image_generate`| yes | yes (via MCP callback) | |`skill_view`,` skills_list`| yes | yes (via MCP callback) | |`text_to_speech`| yes | yes (via MCP callback) | | Codex`shell`(terminal/read/write/search/find/run) | — | yes (Codex built-in) | | Codex`apply_patch`(structured multi-file edits) | — | yes (Codex built-in) | | Codex`update_plan`(in-runtime todo) | — | yes (Codex built-in) | | Codex`view_image`(load image into conversation) | — | yes (Codex built-in) | | Codex sandbox (seatbelt/landlock, profiles) | — | yes (Codex built-in) | | ChatGPT subscription auth | — | yes (via`openai-codex`provider) | | Native Codex plugins (Linear, GitHub, etc.) | — | yes (auto-migrated) | | User MCP servers | yes | yes (auto-migrated to codex) | | Memory + skill review (background) | yes | yes (via item projection) | | Multi-turn conversations | yes | yes | |`/goal(Ralph loop) | yes | yes | | Kanban worker dispatch | yes | yes (via callback) | | Kanban orchestrator tools | yes | yes (via callback) | | All gateway platforms | yes | yes | | Non-OpenAI providers | yes | n/a — OpenAI/Codex-scoped | ## Prerequisites 1. Codex CLI installed: ```bash npm i -g @openai/codex codex --version # 0.130.0 or newer ``` 2. Codex OAuth login. The codex subprocess reads/.codex/auth.json. Two ways to populate it: ```bash codex login # writes tokens to ~/.codex/auth.json ``` Hermes' own hermes auth login codex`writes to`/.hermes/auth.json`— that's a separate session. Run`codex loginseparately if you haven't. 3. (Optional) Install the Codex plugins you want. When you enable the runtime, Hermes auto-migrates whichever curated plugins you've already installed via Codex CLI: ```bash codex plugin marketplace add openai-curated # then via codex's TUI, install Linear / GitHub / Gmail / etc. ``` Hermes will discover them and write[plugins.“@openai-curated”]`entries to`/.codex/config.tomlautomatically. ## Enabling In a Hermes session: ``` /codex-runtime codex_app_server ``` That command: - Verifies thecodex`CLI is installed (blocks with an install hint if not). - Persists`model.openai_runtime: codex_app_server`to your config.yaml. - Migrates user MCP servers from`/.hermes/config.yaml`to`/.codex/config.toml`. - Discovers and migrates installed native Codex plugins (Linear, GitHub, Gmail, Calendar, Canva, etc.) by querying Codex's` plugin/list`RPC. - Registers Hermes' own tools as an MCP server so the codex subprocess can call back for tools codex doesn't ship with. - Writes`default_permissions = “:workspace”` so the sandbox allows writes within the workspace without prompting for every operation. - Tells you what was migrated. Takes effect on the next session — the current cached agent keeps the prior runtime so prompt caches stay valid. Synonyms:` /codex-runtime on`,` /codex-runtime off`,` /codex-runtime auto. To check current state without changing anything: ``` /codex-runtime ``` You can also set it manually in /.hermes/config.yaml: ```yaml model: openai_runtime: codex_app_server # default is "auto" (= Hermes runtime) ``` ## Self-improvement loop (memory + skill nudges) Hermes' background self-improvement fires on counter thresholds: - Every 10 user prompts → a forked review agent looks at the conversation and decides whether anything should be saved to memory. - Every 10 tool iterations within a single turn → same idea but for skills (skill_manage`writes). Both keep working on the codex runtime. The codex path projects each completed`commandExecution`/`fileChange`/`mcpToolCall`/`dynamicToolCall`item into a synthetic`assistant tool_call`+`tool`result message, so by the time the review runs it sees the same shape it sees on the default Hermes runtime. How the wiring stays equivalent: | | Default runtime | Codex runtime | |---|---|---| |`_turns_since_memory`increments | per user prompt, in run_conversation pre-loop | same code path, before the early-return | |`_iters_since_skill`increments | per tool iteration in the chat-completions loop | by`turn.tool_iterations `after the codex turn returns | | Memory trigger (`_turns_since_memory >= _memory_nudge_interval`) | computed in pre-loop, fires after response | computed in pre-loop, passed through to codex helper | | Skill trigger (`_iters_since_skill >= _skill_nudge_interval`) | computed after the loop | computed after the codex turn | |` _spawn_background_review(messages_snapshot=…, review_memory=…, review_skills=…) `| called when either trigger fires | called identically when either trigger fires | One detail: the review fork itself needs to call Hermes' agent-loop tools (`memory`,` skill_manage`), which require Hermes' own dispatch. So when the parent agent is on` codex_app_server`, the review fork is downgraded to` codex_responses` — same OAuth credentials, same` openai-codexprovider, but talks to OpenAI's Responses API directly so Hermes owns the loop and the agent-loop tools work. This is invisible to the user. Net effect: enable the codex runtime and your memory + skill nudges keep firing exactly as they would otherwise. ## How approvals work Codex requests approval before executing commands or applying patches. These get translated into Hermes' standard "Dangerous Command" prompt: ``` ╭───────────────────────────────────────╮ │ Dangerous Command │ │ │ │ /bin/bash -lc 'echo hello > foo.txt' │ │ │ │ ❯ 1. Allow once │ │ 2. Allow for this session │ │ 3. Deny │ │ │ │ Codex requests exec in /your/cwd │ ╰───────────────────────────────────────╯ ``` - Allow once → approve this single command. - Allow for this session → Codex won't re-prompt for similar commands. - Deny → command is rejected; Codex continues in read-only mode. Forapply_patch `(file edit) approvals, Hermes shows a summary of what changed (`1 add, 1 update: /tmp/new.py, /tmp/old.py`) when codex provides the data via the corresponding` fileChange`item. ## Permission profiles Codex has three built-in permission profiles: -`:read-only`— no writes; every shell command requires approval -`:workspace`— writes within the current workspace allowed without prompts (Hermes' default when you enable the runtime) -`:danger-no-sandbox`— no sandbox at all (don't use this unless you understand it) You can override the default in`/.codex/config.tomloutside Hermes' managed block: ```toml default_permissions = ":read-only" ``` (Hermes will preserve your override on re-migration as long as it lives outside the# managed by hermes-agent`markers.) ## Auxiliary tasks and ChatGPT subscription token cost When this runtime is on with the`openai-codex`provider, auxiliary tasks (title generation, context compression, vision auto-detect, the background self-improvement review fork) also flow through your ChatGPT subscription by default, because Hermes' auxiliary client uses the main provider/model when no per-task override is set. This isn't specific to`codex_app_server`— it's true for the existing`codex_responses`path too — but it's more visible here because you're explicitly opting in for the subscription billing. To route specific aux tasks to a cheaper / different model, set explicit overrides in`/.hermes/config.yaml: ```yaml auxiliary: title_generation: provider: openrouter model: google/gemini-3-flash-preview compression: provider: openrouter model: google/gemini-3-flash-preview vision: provider: openrouter model: google/gemini-3-flash-preview goal_judge: provider: openrouter model: google/gemini-3-flash-preview ``` The self-improvement review fork inherits the main runtime via _current_main_runtime()`and Hermes downgrades it from`codex_app_server`to`codex_responses`automatically (so the fork can actually call`memory`and`skill_manage`— Hermes' own agent-loop tools). That fork still uses your subscription auth unless you've routed aux tasks elsewhere. ## Editing`/.codex/config.tomlsafely Hermes wraps everything it manages between two marker comments: ```toml # managed by hermes-agent —hermes codex-runtime migrateregenerates this section default_permissions = ":workspace" [mcp_servers.filesystem] ... [plugins."github@openai-curated"] ... # end hermes-agent managed section ``` Anything outside that block is yours. Re-running migration (via/codex-runtime codex_app_server`or whenever you toggle the runtime on) replaces the managed block in place but preserves user content above and below it verbatim. This means you can: - Add your own MCP servers Hermes doesn't know about - Override`default_permissions`to`:read-only`if you prefer to be prompted - Configure codex-only options (model, providers, otel, etc.) - Add user-defined permission profiles in`[permissions.]`tables Anything you add inside the managed block will get clobbered on the next migration. If you need a tweak that requires editing the managed block, file an issue and we'll add the knob. ## Multi-profile / multi-tenant setups By default, Hermes points the codex subprocess at`/.codex/`regardless of which Hermes profile is active. This means`hermes -p work`and`hermes -p personal`share the same Codex auth, plugins, and config. For most users this is the right behavior — it matches what running`codex`CLI directly would do. If you want per-profile Codex isolation (separate auth, separate installed plugins, separate config), set`CODEX_HOME`explicitly per profile. The cleanest way is to point at a directory under your`HERMES_HOME: ```bash # Inside the work profile, you might wrap hermes: CODEX_HOME=~/.hermes/profiles/work/codex hermes chat ``` You'll need to re-run codex login`once with that`CODEX_HOME`set so the OAuth tokens land in the profile-scoped location. After that,`hermes -p work`will operate on isolated Codex state. We don't auto-scope this because moving an existing user's`/.codex/`would silently invalidate their Codex CLI auth — anyone who already ran`codex login`would have to re-authenticate. Opt-in feels safer than surprising users. ## HOME environment variable passthrough Hermes does NOT rewrite`HOME`when spawning the codex app-server subprocess (we use`os.environ.copy()`and only overlay`CODEX_HOME`and`RUST_LOG`). This means: - Commands codex runs via its` shell`tool see the real user`HOME`and find`/.gitconfig`,` /.gh/`,` /.aws/`,` /.npmrc`, etc. correctly. - Codex's internal state stays isolated through` CODEX_HOME`(which points at`/.codex/`by default). This matches the boundary OpenClaw arrived at after some early experimentation: isolate Codex's state, leave the user's home alone. (Cf. openclaw/openclaw#81562.) ## MCP server migration Hermes'`mcp_servers `config is auto-translated to the TOML format Codex expects. The migration runs every time you enable the runtime and is idempotent — re-runs replace the managed section but preserve any user-edited Codex config. What translates: | Hermes (`config.yaml`) | Codex (`config.toml`) | |---|---| |` command`+`args`+`env`| stdio transport | |`url`+`headers`| streamable_http transport | |`timeout`|`tool_timeout_sec`| |`connect_timeout`|`startup_timeout_sec`| |`enabled: false`|`enabled = false`| What's not migrated: - Hermes-specific keys like`sampling`(Codex's MCP client has no equivalent — these are dropped with a per-server warning). ## Native Codex plugin migration Plugins installed via`codex plugin`(Linear, GitHub, Gmail, Calendar, Canva, etc.) are discovered through Codex's`plugin/list`RPC. For each plugin where`installed: true`, Hermes writes a` [plugins.“@openai-curated”]`block enabling it in your Hermes session. This means: when your friend says "I have Calendar and GitHub set up in my Codex CLI" and they enable Hermes' codex runtime, Hermes activates those automatically. No re-configuration needed. What's NOT migrated: - Plugins you haven't installed yet — install them in Codex first. - Plugins where codex reports`availability != AVAILABLE`(broken install, expired OAuth, removed from marketplace, etc.). These are skipped to avoid writing config that would fail at activation time. - ChatGPT app marketplace entries (the per-account`app/list`results — these are already enabled inside codex by virtue of your account auth). - Plugin OAuth — you authorize each plugin once in Codex itself; Hermes doesn't touch credentials. ## Hermes tool callback (the new MCP server) Codex's built-in toolset covers shell/file ops/patches but doesn't have web search, browser automation, vision, image generation, etc. To keep those usable in a codex turn, Hermes registers itself as an MCP server in`/.codex/config.toml: ```toml [mcp_servers.hermes-tools] command = "/path/to/python" args = ["-m", "agent.transports.hermes_tools_mcp_server"] env = { HERMES_HOME = "/your/.hermes", PYTHONPATH = "...", HERMES_QUIET = "1" } startup_timeout_sec = 30.0 tool_timeout_sec = 600.0 ``` When the model calls web_search`(or another exposed Hermes tool), codex spawns the`hermes_tools_mcp_server`subprocess via stdio, the request is dispatched through`model_tools.handle_function_call()`, and the result is projected back to codex like any other MCP response. Tools available via the callback:` web_search`,` web_extract`,` browser_navigate`,` browser_click`,` browser_type`,` browser_press`,` browser_snapshot`,` browser_scroll`,` browser_back`,` browser_get_images`,` browser_console`,` browser_vision`,` vision_analyze`,` image_generate`,` skill_view`,` skills_list`,` text_to_speech`. Tools NOT available:` delegate_task`,` memory`,` session_search`,` todo`. These need the running AIAgent context to dispatch (mid-loop state) and a stateless MCP callback can't drive them. Use the default Hermes runtime (`/codex-runtime auto) when you need these. ## Disabling Switch back at any time: ``` /codex-runtime auto ``` Effective on the next session. The Codex managed block stays in /.codex/config.toml`so you can re-enable later without losing config — or remove it manually if you prefer. ## Limitations This runtime is opt-in beta. Working as of Hermes Agent 2026.5 + Codex CLI 0.130.0: - Multi-turn conversations -`commandExecution`and`fileChange`(apply_patch) approvals via Hermes UI - MCP tool calls (verified against`@modelcontextprotocol/server-filesystem`and the new`hermes-tools`callback) - Native Codex plugin migration (verified against Linear / GitHub / Calendar inventory) - Deny/cancel paths - Toggle on/off cycle - Memory and skill nudge counters (verified live via integration tests) - Hermes web_search through codex (verified live: "OpenAI Codex CLI – Getting Started" returned end-to-end) Known limitations: - Hermes auth and codex auth are separate sessions. You need both`codex login`AND`hermes auth login codex`for the cleanest UX (the runtime uses codex's session for the LLM call). This is a deliberate design choice in Hermes'`_import_codex_cli_tokens `— Hermes won't share OAuth state with codex CLI to avoid clobbering each other on token refresh. - `delegate_task`,` memory`,` session_search`,` todo`are unavailable on this runtime. They need the running AIAgent context which a stateless MCP callback can't provide. Use`/codex-runtime auto`when you need these. - No inline patch preview in approval prompts when codex doesn't track the changeset. Codex's`fileChange`approval params don't always carry the changeset. Hermes caches the data from the corresponding`item/started`notification when possible, but if approval arrives before the item has streamed, the prompt falls back to whatever`reason`codex provides. - Sub-second cancellation isn't guaranteed. Mid-stream interrupts (Ctrl+C while codex is responding) are sent via`turn/interrupt`, but if codex has already flushed the final message, you get the response anyway. If you find a bug, [open an issue](https://github.com/NousResearch/hermes-agent/issues) with the output of` hermes logs –since 5m`. Mention` codex-runtimein the title so it's easy to triage. ## Architecture ``` ┌─── Hermes shell (CLI / TUI / gateway) ───┐ │ sessions DB · slash commands · memory │ │ & skill review · cron · session pickers │ └──┬──────────────────────────────────────┬┘ │ user_message final │ ▼ text + │ ┌──────────────────────────────────┐ projected │ │ AIAgent.run_conversation() │ messages │ │ if api_mode == codex_app_server │ │ │ → CodexAppServerSession │ │ │ else: chat_completions / codex_responses (default) └────┬─────────────────────────────┘ │ │ JSON-RPC over stdio │ ▼ │ ┌──────────────────────────────────┐ │ │ codex app-server (subprocess) │──────────────┘ │ thread/start, turn/start │ │ item/* notifications │ │ shell + apply_patch + update_plan│ │ view_image + sandbox │ │ ┌─────────────────────────┐ │ │ │ MCP client │ │ │ │ ├─ user MCP servers │ │ │ │ ├─ native plugins │ │ │ │ │ (linear, github, │ │ │ │ │ gmail, calendar, │ │ │ │ │ canva, ...) │ │ │ │ └─ hermes-tools ───────┼─────────────────┐ │ │ (callback to │ │ │ │ │ Hermes' richer │ │ │ │ │ tools) │ │ │ │ └─────────────────────────┘ │ │ └──────────────────────────────────┘ │ │ ▼ ┌──────────────────────────────────────────────────────────┐ │ hermes_tools_mcp_server.py (subprocess on demand) │ │ web_search, web_extract, browser_, vision_analyze, │ │ image_generate, skill_view, skills_list, text_to_speech│ └──────────────────────────────────────────────────────────┘ ``` For implementation details, see [PR #24182](https://github.com/NousResearch/hermes-agent/pull/24182) and the [Codex app-server protocol README](https://github.com/openai/codex/blob/main/codex-rs/app-server/README.md). ---  # user-guide/features/computer-use.md # Computer Use (macOS) Hermes Agent can drive your Mac's desktop — clicking, typing, scrolling, dragging — in the background. Your cursor doesn't move, keyboard focus doesn't change, and macOS doesn't switch Spaces on you. You and the agent co-work on the same machine. Unlike most computer-use integrations, this works with any tool-capable model — Claude, GPT, Gemini, or an open model on a local vLLM endpoint. There's no Anthropic-native schema to worry about. ## How it works Thecomputer_use `toolset speaks MCP over stdio to [`cua-driver`](https://github.com/trycua/cua), a macOS driver that uses SkyLight private SPIs (`SLEventPostToPid`,` SLPSPostEventRecordTo`) and the` _AXObserverAddNotificationAndCheckRemoteaccessibility SPI to: - Post synthesized events directly to target processes — no HID event tap, no cursor warp. - Flip AppKit active-state without raising windows — no Space switching. - Keep Chromium/Electron accessibility trees alive when windows are occluded. That combination is what OpenAI's Codex "background computer-use" ships. cua-driver is the open-source equivalent. ## Enabling Pick whichever path is most convenient — both run the same upstream installer: Option 1: dedicated CLI command (most direct). ``` hermes computer-use install ``` This fetches and runs the upstream cua-driver installer:curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh`. Use` hermes computer-use status`to verify the install. Option 2: enable the toolset interactively. 1. Run`hermes tools`, pick` 🖱️ Computer Use (macOS)`→`cua-driver (background). 2. The setup runs the upstream installer (same as Option 1). After installing, regardless of which path you took: 3. Grant macOS permissions when prompted: - System Settings → Privacy & Security → Accessibility → allow the terminal (or Hermes app). - System Settings → Privacy & Security → Screen Recording → allow the same. 4. Start a session with the toolset enabled: ``` hermes -t computer_use chat ``` or add computer_use`to your enabled toolsets in`/.hermes/config.yaml`. ## Keeping cua-driver up to date The cua-driver project ships fixes regularly (e.g. v0.1.6 fixed a Safari window-focus bug for UTM workflows). Hermes refreshes the binary in two places so you don't get stuck on a stale release: - `hermes update` — when you update Hermes itself, if` cua-driver `is on PATH the upstream installer re-runs at the end of the update. No-op for non-macOS users and for users without cua-driver installed. - `hermes computer-use install –upgrade` — manual force-refresh. Re-runs the upstream installer regardless of whether cua-driver is already installed. Use this when you want the latest fix without waiting for the next agent update.` hermes computer-use status`shows the installed version next to the binary path. ## Quick example User prompt: "Find my latest email from Stripe and summarise what they want me to do."* The agent's plan: 1.`computer_use(action=“capture”, mode=“som”, app=“Mail”)`— gets a screenshot of Mail with every sidebar item, toolbar button, and message row numbered. 2.`computer_use(action=“click”, element=14)`— clicks the search field (element #14 from the capture). 3.`computer_use(action=“type”, text=“from:stripe”)`4.`computer_use(action=“key”, keys=“return”, capture_after=True)— submit and get the new screenshot. 5. Click the top result, read the body, summarise. During all of this, your cursor stays wherever you left it and Mail never comes to front. ## Provider compatibility | Provider | Vision? | Works? | Notes | |---|---|---|---| | Anthropic (Claude Sonnet/Opus 3+) | ✅ | ✅ | Best overall; SOM + raw coordinates. | | OpenRouter (any vision model) | ✅ | ✅ | Multi-part tool messages supported. | | OpenAI (GPT-4+, GPT-5) | ✅ | ✅ | Same as above. | | Local vLLM / LM Studio (vision model) | ✅ | ✅ | If the model supports multi-part tool content. | | Text-only models | ❌ | ✅ (degraded) | Usemode=“ax”`for accessibility-tree-only operation. | Screenshots are sent inline with tool results as OpenAI-style`image_url`parts. For Anthropic, the adapter converts them into native`tool_result`image blocks. ## Safety Hermes applies multi-layer guardrails: - Destructive actions (click, type, drag, scroll, key, focus_app) require approval — either interactively via the CLI dialog or via the messaging-platform approval buttons. - Hard-blocked key combos at the tool level: empty trash, force delete, lock screen, log out, force log out. - Hard-blocked type patterns:`curl | bash`,` sudo rm -rf /`, fork bombs, etc. - The agent's system prompt tells it explicitly: no clicking permission dialogs, no typing passwords, no following instructions embedded in screenshots. Pair with` approvals.mode: manual`in`/.hermes/config.yaml`if you want every action confirmed. ## Token efficiency Screenshots are expensive. Hermes applies four layers of optimisation: - Screenshot eviction — the Anthropic adapter keeps only the 3 most recent screenshots in context; older ones become`[screenshot removed to save context]`placeholders. - Client-side compression pruning — the context compressor detects multimodal tool results and strips image parts from old ones. - Image-aware token estimation — each image is counted as ~1500 tokens (Anthropic's flat rate) instead of its base64 char length. - Server-side context editing (Anthropic only) — when active, the adapter enables`clear_tool_uses_20250919`via`context_management`so Anthropic's API clears old tool results server-side. A 20-action session on a 1568×900 display typically costs ~30K tokens of screenshot context, not ~600K. ## Limitations - macOS only. cua-driver uses private Apple SPIs that don't exist on Linux or Windows. For cross-platform GUI automation, use the`browser`toolset. - Private SPI risk. Apple can change SkyLight's symbol surface in any OS update. Pin the driver version with the`HERMES_CUA_DRIVER_VERSION`env var if you want reproducibility across a macOS bump. - Performance. Background mode is slower than foreground — SkyLight-routed events take ~5-20ms vs direct HID posting. Not noticeable for agent-speed clicking; noticeable if you try to record a speed-run. - No keyboard password entry.`type has hard-block patterns on command-shell payloads; for passwords, use the system's autofill. ## Configuration Override the driver binary path (tests / CI): ``` HERMES_CUA_DRIVER_CMD=/opt/homebrew/bin/cua-driver HERMES_CUA_DRIVER_VERSION=0.5.0 # optional pin ``` Swap the backend entirely (for testing): ``` HERMES_COMPUTER_USE_BACKEND=noop # records calls, no side effects ``` ## Troubleshooting computer_use backend unavailable: cua-driver is not installed` — Run` hermes computer-use install`to fetch the cua-driver binary, or run`hermes tools`and enable the Computer Use toolset. Clicks seem to have no effect — Capture and verify. A modal you didn't see may be blocking input. Dismiss it with`escape`or the close button. Element indices are stale — SOM indices are only valid until the next`capture`. Re-capture after any state-changing action. "blocked pattern in type text" — The text you tried to` type`matches the dangerous-shell-pattern list. Break the command up or reconsider. ## See also - [Universal skill:`macos-computer-use](https://github.com/NousResearch/hermes-agent/blob/main/skills/apple/macos-computer-use/SKILL.md) - [cua-driver source (trycua/cua)](https://github.com/trycua/cua) - [Browser automation](./browser.md) for cross-platform web tasks. ---  # user-guide/features/deliverable-mode.md # Deliverable Mode When Hermes Agent runs inside a messaging gateway (Slack, Discord, Telegram, WhatsApp, Signal, etc.), it can deliver generated files directly into the chat — not as paths the user has to copy, but as native attachments. A chart shows up as an inline image. A PDF report shows up as a file download. A spreadsheet uploads as .xlsx`. The agent does not need to write a` MEDIA:`tag or do anything special — it just generates the file and mentions its absolute path in the response. The gateway picks the path out of the text, removes it from the visible message, and uploads the file natively. ## How it works Three pieces fit together: 1. The agent has tools that produce files.`execute_code`for charts via matplotlib, the`latex-pdf-report`skill for PDFs, the`powerpoint`skill for decks,`image_generate`for images,`text_to_speech `for audio, and so on. 2. The gateway scans agent responses for file paths. Any absolute path (`/tmp/…`) or home-relative path (`/…`) ending in a supported extension gets extracted. Paths inside code blocks and inline code are ignored so code samples are never mutilated. 3. The gateway dispatches by file type. Images embed inline where the platform supports it; videos embed inline; audio routes to voice/audio attachments; everything else uploads as a file attachment. ## Supported file extensions | Category | Extensions | Delivery | |---|---|---| | Images |` .png .jpg .jpeg .gif .webp .bmp .tiff .svg`| Inline embed | | Video |`.mp4 .mov .avi .mkv .webm`| Inline embed (where supported) | | Audio |`.mp3 .wav .ogg .m4a .flac`| Voice / audio attachment | | Documents |`.pdf .docx .doc .odt .rtf .txt .md`| File upload | | Data |`.xlsx .xls .csv .tsv .json .xml .yaml .yml`| File upload | | Presentations |`.pptx .ppt .odp`| File upload | | Archives |`.zip .tar .gz .tgz .bz2 .7z`| File upload | | Web |`.html .htm`| File upload |`.py`,` .log, and other source-file extensions are intentionally excluded so the agent doesn't auto-ship arbitrary source files; if you want to send code to the user, use a code block. ## Encouraging the agent to produce artifacts The agent doesn't reach for artifacts by default — it has to know to. Two ways to nudge it: Per-session: ask explicitly ("send me the comparison as a chart", "return the data as a CSV") or write your own custom-instructions / personality entry that biases toward artifact-style replies on messaging platforms. Project-level: add the bias to AGENTS.md`/`CLAUDE.md`/`.cursorrules`in a project the agent works from, to your global persona in`/.hermes/SOUL.md`, or as a named preset under` agent.personalities`in`/.hermes/config.yaml`(switchable per session via`/personality`). The mechanic the agent has to use is simple: render the file to an absolute path (e.g.` /tmp/q3-revenue.png`) and mention that path as plain text in the reply. The gateway does the rest. Paths inside fenced code blocks or backticks are ignored so code samples are never mutilated. ## Kanban: artifacts ride completion notifications If you use Hermes' kanban multi-agent workflow, workers can attach deliverable files to their` kanban_completecall: ```python kanban_complete( summary="rendered Q3 revenue chart and report", artifacts=[ "/tmp/q3-revenue.png", "/tmp/q3-report.pdf", ], ) ``` When the gateway notifier delivers the "task completed" message to whoever subscribed to the task in Slack/Telegram/etc., it also uploads each artifact as a native attachment to that chat. The human gets the deliverable and the summary in one place. Files that don't exist on disk when the notifier runs are silently skipped. ## Connecting more services with MCP Beyond the artifact-delivery pipeline, the agent can reach into other services via MCP (Model Context Protocol). The MCP ecosystem ships community servers for most popular tools — install whichever you need: | Service | What it unlocks | |---|---| | Notion | Read/write Notion pages, databases, query workspace | | GitHub | Issues, PRs, comments, repo search beyond the gh CLI | | Linear | Tickets, projects, cycles | | Slack | Workspace-wide search, read other channels | | Gmail | Inbox triage, send mail, label management | | Salesforce | Leads, opportunities, account data | | Snowflake / BigQuery | SQL against data warehouses | | Google Drive | File search, contents, share management | Install MCP servers via/.hermes/config.yaml`under the`mcp_servers`section. See [MCP integration](./mcp.md) for the full setup guide. ## Comparison to Perplexity Computer in Slack Perplexity Computer's Slack integration is built around the same idea: the agent generates a deliverable (chart, PDF, slide deck) and posts it back into the thread as a native attachment. Hermes Agent's deliverable mode provides the same user-facing pattern locally: - Generation happens in the user's own venv / sandbox (no remote tenant). - Files land in the chat via the same Slack`files.uploadV2`API. - Connector breadth comes via MCP rather than a curated catalog of 400 hosted integrations — install the ones you actually use. OAuth tokens stay on the user's machine in`auth.json`/`.env`. No hosted token storage. No multi-tenant microVM. Same end result. ---  # Extending the Dashboard # Extending the Dashboard The Hermes web dashboard (`hermes dashboard`) is built to be reskinned and extended without forking the codebase. Three layers are exposed: 1. Themes — YAML files that repaint the dashboard's palette, typography, layout, and per-component chrome. Drop a file in` /.hermes/dashboard-themes/`; it appears in the theme switcher. 2. UI plugins — a directory with` manifest.json`+ a JavaScript bundle that registers a tab, replaces a built-in page, augments one via page-scoped slots, or injects components into named shell slots. 3. Backend plugins — a Python file inside that plugin directory that exposes a FastAPI`router`; routes are mounted under` /api/plugins//`and called from the plugin's UI. All three are drop-in at runtime: no repo clone, no`npm run build, no patching the dashboard source. This page is the canonical reference for all three. If you just want to use the dashboard, see [Web Dashboard](./web-dashboard). If you want to reskin the terminal CLI (not the web dashboard), see [Skins & Themes](./skins) — the CLI skin system is unrelated to dashboard themes. :::note How the pieces compose Themes and plugins are independent but synergistic. A theme can stand alone (just a YAML file). A plugin can stand alone (just a tab). Together they let you build a complete visual reskin with custom HUDs — the example strike-freedom-cockpit`demo (lives in the`hermes-example-pluginscompanion repo — see [Combined theme + plugin demo](#combined-theme--plugin-demo) for install steps) does exactly that. ::: --- ## Table of contents - [Themes](#themes) - [Quick start — your first theme](#quick-start--your-first-theme) - [Palette, typography, layout](#palette-typography-layout) - [Layout variants](#layout-variants) - [Theme assets (images as CSS vars)](#theme-assets-images-as-css-vars) - [Component chrome overrides](#component-chrome-overrides) - [Color overrides](#color-overrides) - [RawcustomCSS`](#raw-customcss) - [Built-in themes](#built-in-themes) - [Full theme YAML reference](#full-theme-yaml-reference) - [Plugins](#plugins) - [Quick start — your first plugin](#quick-start--your-first-plugin) - [Directory layout](#directory-layout) - [Manifest reference](#manifest-reference) - [The Plugin SDK](#the-plugin-sdk) - [Shell slots](#shell-slots) - [Replacing built-in pages (`tab.override`)](#replacing-built-in-pages-taboverride) - [Augmenting built-in pages (page-scoped slots)](#augmenting-built-in-pages-page-scoped-slots) - [Slot-only plugins (`tab.hidden`)](#slot-only-plugins-tabhidden) - [Backend API routes](#backend-api-routes) - [Custom CSS per plugin](#custom-css-per-plugin) - [Plugin discovery & reload](#plugin-discovery--reload) - [Combined theme + plugin demo](#combined-theme--plugin-demo) - [API reference](#api-reference) - [Troubleshooting](#troubleshooting) --- ## Themes Themes are YAML files stored in` /.hermes/dashboard-themes/`. The file name doesn't matter (the theme's` name:`field is what the system uses), but convention is`.yaml`. Every field is optional — missing keys fall back to the built-in` defaulttheme, so a theme can be as small as one color. ### Quick start — your first theme ```bash mkdir -p ~/.hermes/dashboard-themes ``` ```yaml # ~/.hermes/dashboard-themes/neon.yaml name: neon label: Neon description: Pure magenta on black palette: background: "#000000" midground: "#ff00ff" ``` Refresh the dashboard. Click the palette icon in the header and pick Neon. The background goes black, text and accents go magenta, and every derived color (card, border, muted, ring, etc.) is recomputed from that 2-color triplet viacolor-mix()in CSS. That's the whole onboarding: one file, two colors. Everything below is optional refinement. ### Palette, typography, layout These three blocks are the heart of a theme. Each is independent — override one, leave the others. #### Palette (3-layer) The palette is a triplet of color layers plus a warm-glow vignette color and a noise-grain multiplier. The dashboard's design-system cascade derives every shadcn-compatible token (card, popover, muted, border, primary, destructive, ring, etc.) from this triplet via CSScolor-mix()`. Overriding three colors cascades into the whole UI. | Key | Description | |-----|-------------| |` palette.background`| Deepest canvas color — typically near-black. Drives the page background and card fill. | |`palette.midground`| Primary text and accent. Most UI chrome reads this (foreground text, button outlines, focus rings). | |`palette.foreground`| Top-layer highlight. The default theme sets this to white at alpha 0 (invisible); themes that want a bright accent on top can raise its alpha. | |`palette.warmGlow`|`rgba(…)`string used as the vignette color by. | |` palette.noiseOpacity`| 0–1.2 multiplier on the grain overlay. Lower = softer, higher = grittier. | Each layer accepts either`{hex: “#RRGGBB”, alpha: 0.0–1.0}or a bare hex string (alpha defaults to 1.0). ```yaml palette: background: hex: "#05091a" alpha: 1.0 midground: "#d8f0ff" # bare hex, alpha = 1.0 foreground: hex: "#ffffff" alpha: 0 # invisible top layer warmGlow: "rgba(255, 199, 55, 0.24)" noiseOpacity: 0.7 ``` #### Typography | Key | Type | Description | |-----|------|-------------| |fontSans`| string | CSS font-family stack for body copy (applied to`html`,` body`). | |` fontMono`| string | CSS font-family stack for code blocks,`, .font-monoutilities. | |fontDisplay| string | Optional heading/display stack. Falls back tofontSans. | | fontUrl| string | Optional external stylesheet URL. Injected asinon theme switch. Same URL is never injected twice. Works with Google Fonts, Bunny Fonts, self-hosted@font-facesheets — anything linkable. | |baseSize| string | Root font size — controls the rem scale. E.g.“14px”, “16px”. | | lineHeight| string | Default line-height. E.g.“1.5”, “1.65”. | | letterSpacing| string | Default letter-spacing. E.g.“0”, “0.01em”, “-0.01em”. | ```yaml typography: fontSans: '"Orbitron", "Eurostile", "Impact", sans-serif' fontMono: '"Share Tech Mono", ui-monospace, monospace' fontDisplay: '"Orbitron", "Eurostile", sans-serif' fontUrl: "https://fonts.googleapis.com/css2?family=Orbitron:wght@400;500;600;700&family=Share+Tech+Mono&display=swap" baseSize: "14px" lineHeight: "1.5" letterSpacing: "0.04em" ``` ##### Changing the font from the UI (no YAML) The theme picker in the dashboard header has a Font section below the theme list. Pick any font there and it overrides the body font of whatever theme is active — the choice is independent of the theme and persists across theme switches (stored in config.yamlunderdashboard.font). Choose Theme default to clear the override and fall back to the active theme's own fontSans. The picker offers a curated catalog (system stacks plus a set of Google-Fonts families across sans / serif / mono). It deliberately does not accept a free-text font URL — the font's stylesheet is injected as a , so the catalog keeps the injected origins fixed. For a fully custom face, set fontSans+fontUrlin a theme YAML as shown above. The theme'sfontMono(code blocks, terminal) is always left untouched by the UI override. #### Layout | Key | Values | Description | |-----|--------|-------------| |radius | any CSS length (“0”, “0.25rem”, “0.5rem”, “1rem”, ...) | Corner-radius token. Maps to –radiusand cascades into–radius-sm/md/lg/xl— every rounded element shifts together. | |density|compact\|comfortable\|spacious| Spacing multiplier applied as the–spacing-mulCSS var.compact = 0.85×, comfortable = 1.0×(default),spacious = 1.2×. Scales Tailwind's base spacing, so padding, gap, and space-between utilities all shift proportionally. | ```yaml layout: radius: "0" density: compact ``` ### Layout variants layoutVariantpicks the overall shell layout. Defaults to“standard”when absent. | Variant | Behaviour | |---------|-----------| |standard| Single column, 1600px max-width (default). | |cockpit| Left sidebar rail (260px) + main content. Populated by plugins via thesidebarslot — see [Shell slots](#shell-slots). Without a plugin the rail shows a placeholder. | |tiled| Drops the max-width clamp so pages can use the full viewport width. | ```yaml layoutVariant: cockpit ``` The current variant is exposed asdocument.documentElement.dataset.layoutVariant, so raw CSS in customCSScan target it via:root[data-layout-variant=“cockpit”] …. ### Theme assets (images as CSS vars) Ship artwork URLs with a theme. Each named slot becomes a CSS var (–theme-asset-) that the built-in shell and any plugin can read. The bgslot is automatically wired into the backdrop; other slots are plugin-facing. ```yaml assets: bg: "https://example.com/hero-bg.jpg" # auto-wired into <Backdrop /> hero: "/my-images/strike-freedom.png" # for plugin sidebars crest: "/my-images/crest.svg" # for header-left plugins logo: "/my-images/logo.png" sidebar: "/my-images/rail.png" header: "/my-images/header-art.png" custom: scanLines: "/my-images/scanlines.png" # → --theme-asset-custom-scanLines ``` Values accept: - Bare URLs — wrapped inurl(…)automatically. - Pre-wrappedurl(…), linear-gradient(…), radial-gradient(…)expressions — used as-is. -“none”— explicit opt-out. Every asset is also emitted as–theme-asset--raw(the unwrapped URL), in case a plugin needs to pass it toinstead ofbackground-image. Plugins read these with plain CSS or JS: ```javascript // In a plugin slot const hero = getComputedStyle(document.documentElement) .getPropertyValue("--theme-asset-hero").trim(); ``` ### Component chrome overrides componentStyles restyles individual shell components without writing CSS selectors. Each bucket's entries become CSS vars (–component--) that the shell's shared components read. So card:overrides apply to every, header:to the app bar, etc. ```yaml componentStyles: card: clipPath: "polygon(12px 0, 100% 0, 100% calc(100% - 12px), calc(100% - 12px) 100%, 0 100%, 0 12px)" background: "linear-gradient(180deg, rgba(10, 22, 52, 0.85), rgba(5, 9, 26, 0.92))" boxShadow: "inset 0 0 0 1px rgba(64, 200, 255, 0.28)" header: background: "linear-gradient(180deg, rgba(16, 32, 72, 0.95), rgba(5, 9, 26, 0.9))" tab: clipPath: "polygon(6px 0, 100% 0, calc(100% - 6px) 100%, 0 100%)" sidebar: {} backdrop: {} footer: {} progress: {} badge: {} page: {} ``` Supported buckets:card, header, footer, sidebar, tab, progress, badge, backdrop, page. Property names use camelCase (clipPath) and are emitted as kebab (clip-path). Values are plain CSS strings — anything CSS accepts (clip-path, border-image, background, box-shadow, animation, ...). ### Color overrides Most themes won't need this — the 3-layer palette derives every shadcn token. Use colorOverrideswhen you want a specific accent the derivation won't produce (a softer destructive red for a pastel theme, a specific success green for a brand). ```yaml colorOverrides: primary: "#ffce3a" primaryForeground: "#05091a" accent: "#3fd3ff" ring: "#3fd3ff" destructive: "#ff3a5e" border: "rgba(64, 200, 255, 0.28)" ``` Supported keys:card, cardForeground, popover, popoverForeground, primary, primaryForeground, secondary, secondaryForeground, muted, mutedForeground, accent, accentForeground, destructive, destructiveForeground, success, warning, border, input, ring. Each key maps 1:1 to the –color-CSS var (e.g.primaryForeground→–color-primary-foreground). Any key set here wins over the palette cascade for the active theme only — switching to another theme clears the overrides. ### Raw customCSSFor selector-level chrome thatcomponentStylescan't express — pseudo-elements, animations, media queries, theme-scoped overrides — drop raw CSS intocustomCSS: ```yaml customCSS: | /* Scanline overlay — only visible when cockpit variant is active. */ :root[data-layout-variant="cockpit"] body::before { content: ""; position: fixed; inset: 0; pointer-events: none; z-index: 100; background: repeating-linear-gradient(to bottom, transparent 0px, transparent 2px, rgba(64, 200, 255, 0.035) 3px, rgba(64, 200, 255, 0.035) 4px); mix-blend-mode: screen; } ``` The CSS is injected as a single scoped