In Chapter 3, you saw the mental model: profiles, skills, memory, toolsets, gateway, and cron. But what actually runs those components? Where do the files live? How does the agent reach the model that powers it?
This chapter goes one layer deeper — into the technology that makes the mental model real. Think of it like driving a car. You use the steering wheel, pedals, and dashboard. The engine, transmission, and fuel system are underneath — knowing they exist helps you reason about maintenance, but you do not need to rebuild them.
If you like knowing what is under the hood, this chapter is for you. If not, skim it and come back when you need to debug something or configure a provider.
Hermes is a Python application — specifically, it requires Python 3.11 or newer. The installer handles Python for you: it sets up the runtime, a package manager called , and all the libraries Hermes depends on. You do not need to install Python yourself or manage a virtual environment.
Python matters if you want to write custom tools later — Hermes tools are Python, and the tool registry discovers them automatically. But you can use the 70+ built-in tools without writing any Python.
When you install Hermes, it creates ~/.hermes on your machine. This is your agent's home — everything that makes it unique lives here. That matters for two reasons: back up this folder and you have backed up your agent; copy it to another machine and your agent moves with you. The files are all readable text, not a database you cannot inspect.
~/.hermes/
├── config.yaml # Main settings — model, provider, toolsets, memory
├── .env # API keys and secrets (separate from config)
├── hermes-agent/ # The program code itself
├── sessions/ # Conversation history per profile
├── skills/ # Procedural knowledge documents
├── memories/ # Persistent facts and preferences per profile
├── cron/ # Scheduled job definitions and state
├── logs/ # Session and gateway logs
├── pairing/ # Messaging platform pairing data
├── hooks/ # Custom shell-script hooks
└── image_cache/ # Cached image filesProfiles each get their own subfolder inside sessions/, skills/, and memories/ — so two profiles on the same machine never share or overwrite each other's data.
The config.yaml file defines how your agent behaves: model selection, inference provider, enabled tools, memory limits, session policies, and more. You do not have to edit it by hand — hermes setup walks you through key choices on first install, and hermes config lets you change any setting later. The file uses , a plain-text format built for readability. The installer creates it from a template with sensible defaults.
The key sections: model (which AI model and provider), terminal (command execution mode), memory (limits and auto-save behavior), platform_toolsets (which tools per platform), and compression (how long conversations get summarized). Other sections cover gateway streaming, display preferences, and subagent limits — you can explore them as your setup grows or let defaults handle it.
The .env file stores API keys and other secrets — your model provider key, messaging platform tokens, and any sensitive values. It is deliberately separate from config.yaml so you can share your configuration with a colleague without exposing your credentials. The setup wizard creates this file from a template and prompts you to fill in your keys. Hermes also reads environment variables from your system shell, so if you already have an OPENAI_API_KEY set in your terminal, Hermes picks it up automatically.
Hermes does not include its own AI model. It calls external providers — services like OpenAI, Anthropic, and Google — through their APIs. You bring your own API key, and Hermes routes your prompts to the model you choose. The default is "auto," which detects your provider from your credentials. You can also pick explicitly with hermes model — no code changes required.
There are also providers for NVIDIA NIM, Xiaomi, MiniMax, and others. Hermes is not locked to any single model or provider — switch with one command and the rest of your setup stays the same. Hermes also supports : if your primary provider goes down, Hermes tries the next one automatically.
In Chapter 3, you saw toolsets as a concept. Technically, Hermes includes over 70 built-in tools organized into toolsets — groups of tools that share a purpose and often share dependencies (e.g., the web toolset includes search and page extraction; the terminal toolset includes command execution and process management). Tools are auto-discovered at startup — each tool file registers itself with the tool registry, no manual configuration needed. Custom tools appear as soon as Hermes finds them.
You control which toolsets are available per profile and per platform. CLI sessions might have full access, while a Telegram bot might be restricted to web search and file operations. This gives each agent exactly the capabilities it needs — and nothing more. Composite presets like hermes-cli and hermes-telegram bundle toolsets for convenience.
MCP (Model Context Protocol) is an open standard that lets AI tools talk to each other. Hermes plays two roles: as an MCP server, it exposes its messaging conversations so other tools (like Claude Code) can list conversations, read history, and respond to approval requests from within their own interface. As an MCP client, it connects to external MCP servers — adding tools from the ecosystem like filesystem access, GitHub integration, or database queries to your Hermes agent.
MCP is optional — Hermes works fully without it. If you already use tools that support MCP, add a few lines to your config.yaml pointing to the server and Hermes discovers its tools automatically.
The base install includes only the packages every session needs. Provider-specific and feature-specific packages install automatically when you enable them — for example, choosing Anthropic as your provider installs the Anthropic SDK on the spot. This keeps the initial install small and reduces potential supply-chain surface area.
Security is built in layers — approvals, redaction, isolation — covered in depth in Chapter 13.
You now know the tech stack: Python runtime, ~/.hermes data directory, config.yaml for settings, .env for secrets, model providers for AI, tool registry for capabilities, and MCP for external integrations. If your agent suddenly cannot connect to a model, which two files would you check first — and why?