Hermes Agent

Hermes Agent is Nous Research's agent runtime, tuned for the Hermes / Qwen tool format. It injects a large system prompt with ~60+ tools, so a long context window is a hard prerequisite.

Quick start

Needs: Hermes Agent v0.21.6 from its GitHub release and Python 3.14. The PyPI package is older than v0.21.6.

$ rapid-mlx serve qwen3.5-4b-4bit --port 8000
# In another terminal, after installing Hermes below:
$ export PATH="$HOME/hermes-agent/.venv/bin:$PATH"
$ rapid-mlx agents hermes --setup --yes
$ hermes chat -q "Run cat README.md using the terminal tool and report its title" -Q -t terminal

A reply means Hermes is using your local model. rapid-mlx agents hermes --test runs the full integration check.

Install

$ git clone --depth 1 --branch v0.21.6 https://github.com/NousResearch/hermes-agent.git "$HOME/hermes-agent"
$ uv venv --python 3.14 "$HOME/hermes-agent/.venv"
$ uv pip install --python "$HOME/hermes-agent/.venv/bin/python" -e "$HOME/hermes-agent"
$ export PATH="$HOME/hermes-agent/.venv/bin:$PATH"

Config

One-shot: rapid-mlx agents hermes --setup writes ~/.hermes/config.yaml (or $HERMES_HOME/config.yaml), auto-detecting your served model and its real context window. An existing file is merged: your other keys are kept, no backup is made, and --dry-run previews without writing. The cli toolset list is trimmed to the toolsets your installed Hermes supports. The 0.21.6 release ignores the old model.max_tokens setting, so a fresh setup omits it. An existing value is preserved but unused. A representative template (context_length shown for a 256K-window model):

# ~/.hermes/config.yaml
model:
  provider: "custom"
  default: "qwen3.6-35b-4bit"
  base_url: "http://localhost:8000/v1"
  context_length: 262144
platform_toolsets:
  cli: [terminal, file, code_execution, web, browser, skills, image_gen]

Run

$ rapid-mlx serve qwen3.5-4b-4bit
$ hermes chat                                  # interactive
$ hermes chat -q "summarize this repo"             # one-shot

Recommended aliases (per rapid-mlx agents hermes): qwen3.5-4b-4bit, qwen3.5-9b-4bit, gemma-4-26b-4bit, qwen3.5-35b-4bit, qwen3.6-35b-4bit.

Integration harness (test_hermes.py)

The deep flow at tests/integrations/test_hermes.py writes ~/.hermes/config.yaml to point at the running server, then drives hermes chat -q <query> -Q in non-interactive mode. Because Hermes injects 60+ tools into every turn, small models can run out of context — the harness treats "context too small for the tool block" as SKIP, not FAIL.

Gotchas

• Keep model.context_length at the server's real context window. Setup detects this automatically. Hermes' tool prompt can be large; use -t file,terminal to limit toolsets for a small model.
• todo tool conflict on Gemma 4. Hermes injects a todo tool that races Gemma 4's own reasoning format. Fix: exclude todo from platform_toolsets, or use Hermes' -t flag.

Empirical

Hermes Agent 0.21.6 called terminal to read a file and returned its marker through the local Qwen 3.5-4B server on 2026-10-11. The hermes-agent row of the integration matrix is ✅ on Qwen 3.6, Gemma 4, and gpt-oss; DeepSeek R1-Distill XFAIL(arch). Deep flow assertions in test_hermes.py cover plain, streaming, single tool, multi-tool, and structured output.

See also