What Gets Bundled and Why Each Matters

+15 Mana ✨
Hermes Architecture Overview(DOCUMENTATION)

Introduction

Hermes ships with a small but carefully chosen runtime. Each component is included for a specific reason, not because Hermes uses every feature of every binary, but because removing any one of them would break a class of agent behavior. Understanding what is in the box helps you reason about what Hermes can do and what it cannot.

Key Concepts

  • uv: Ultra-fast Python package manager that provisions Python and resolves dependencies.
  • Python 3.11: The runtime Hermes' own code is written in.
  • Node.js v22: Used for browser automation and platform integrations (notably WhatsApp).
  • ripgrep: Fast recursive code search, the search tool Hermes hands to the model.
  • ffmpeg: Audio conversion, used by voice mode for STT and TTS.

Real World Context

The bundle is a contract. When the model decides to grep a codebase, it calls ripgrep, not your system grep, not GNU grep, not BSD grep. That makes the agent's behavior reproducible: a session that worked yesterday will work today and tomorrow. Voice mode is the cleanest example: TTS providers expect specific audio formats, and ffmpeg is the universal converter that bridges them. Without ffmpeg, voice mode would silently fail on half its providers.

Deep Dive

What each component enables

text
Component       Enables
─────────────   ──────────────────────────────────────────────
uv              Fast install of Python; isolated venv
Python 3.11     The Hermes runtime itself
Node.js v22     Browser automation; WhatsApp gateway
ripgrep         The search tool used inside agent sessions
ffmpeg          Audio format conversion for voice mode

Why specific versions

Python 3.11 is the lowest common denominator for the libraries Hermes depends on, while still being widely supported. Node.js v22 is required for the Playwright-based browser tools and modern WhatsApp client libraries. Pinning these versions means you do not get surprised by language-level breaking changes.

Why bundled instead of system-installed

Three reasons:

  1. Reproducibility, A session works the same on every install of the same Hermes version.
  2. Isolation, Updating your system Python does not break Hermes. Updating Hermes does not touch your system Python.
  3. Fewer bug reports, A class of "does not work on my machine" issues simply cannot happen if everyone runs the same bundled stack.

Common Pitfalls

  1. Confusing bundled with isolated, Hermes' bundled tools are isolated from your system, but not from each other. Voice mode still depends on ffmpeg being in the bundle.
  2. Replacing bundled binaries, Do not symlink your system ripgrep over the bundled one. You will lose reproducibility for very little gain.

Best Practices

  1. Trust the bundle, If a tool is not in the bundle, assume Hermes was not meant to need it.
  2. Update Hermes, not the bundle, Get newer ripgrep / ffmpeg via a Hermes upgrade, not by hand.

Summary

  • The bundled runtime is uv, Python 3.11, Node.js v22, ripgrep, and ffmpeg.
  • Each component enables a class of agent behavior, search, browser, voice.
  • Bundling is a deliberate trade: more disk for stronger reproducibility and isolation.

Code Examples

bash
# Inspect what Hermes bundled, none of these touch your system PATH
ls ~/.hermes/hermes-agent/runtime/
# python-3.11/   node-22/   ripgrep   ffmpeg   uv

# Hermes uses the bundled binaries, your system versions are irrelevant
hermes doctor --verbose | grep -E 'python|node|ripgrep|ffmpeg'
✓ Completed