Hermes Agent Docs: The Complete Reference Guide

While standard session-based AI chatbots are confined to a single browser tab, the official Nous Research Hermes Agent supports over 60 built-in tools across 6 different terminal backends and 20+ messaging platforms [Nous Research 2026]. This architectural shift from a simple chat interface to a persistent, self-improving platform is where the developers of next-generation autonomous workflows are building.

Nous Research Hermes Agent is a self-improving, open-source autonomous agent platform developed by Nous Research, featuring a built-in learning loop and multi-platform messaging gateways. Unlike standard agents that run inside a browser session and lose state when you close the tab, the Hermes Agent runs as a persistent daemon. It is designed to run continuously on local hardware or remote servers, maintaining context and learning from every interaction. The platform is released under the MIT license, positioning it as an open, self-contained system that developers can deploy on their own infrastructure.

The architecture splits into three main layers: the model client interface, the terminal backend executor, and the communication gateway. The model client supports multiple providers, letting you connect to OpenAI, Anthropic, OpenRouter, or local models using Ollama and vLLM. The terminal backend executor is where the agent actually runs code and interacts with files. The messaging gateway connects the agent to communication networks like Telegram, Discord, WhatsApp, Signal, and email. This means you do not have to write custom wrappers for each messaging platform, as the gateway routes incoming files and text directly to the agent's core loop.

A core capability of the Hermes Agent is its self-evolution mechanism. When the agent encounters a complex task, it does not just execute a one-off script. Instead, it attempts to solve the problem, verifies the output, and documents the successful solution as a reusable skill. These skills are written to a local directory and conform to the open agentskills.io standard. During future runs, the agent can load these skills on demand, using a process called progressive disclosure. This technique keeps the prompt size small and avoids wasting tokens on instructions that are not relevant to the current task.

The evolutionary learning loop is powered by frameworks like DSPy and GEPA (Generative Epistemic Productive Agents). Rather than relying on static system instructions, the agent optimizes its prompts and python code based on execution feedback. If a task fails, the agent records the error, alters its code parameters, and attempts execution again. Once it passes validation, the optimized workflow is compiled into a skill. This self-improving capability ensures the agent becomes more effective at specialized tasks the longer it runs in your environment.

When you install the Hermes Agent, it creates a hidden directory in your home folder at ~/.hermes/. This directory serves as the persistent root for the agent, storing all configurations, memory state, skills, and logs. Understanding the layout of this directory is key for configuring custom environments and debugging tool behaviors.

• config.yaml Contains general runtime configurations. This is where you configure model preferences, default terminal backends, speech-to-text settings, memory compression limits, and active Model Context Protocol (MCP) servers.

• .env Stores sensitive variables, API keys, and gateway credentials. It takes precedence over config.yaml to ensure secrets are kept out of shared configuration files.

• SOUL.md Defines the system prompt and core persona of the agent. By editing this file, you can customize how the agent speaks, its behavioral boundaries, and its default operational guidelines.

• auth.json Contains OAuth credentials and tokens used when connecting the agent to third-party services via the Nous Portal gateway. If you bypass the portal, you must configure API keys manually in .env.

• memories/ Holds persistent state files, including MEMORY.md and USER.md. The agent updates these files at the end of each session to remember user preferences, completed tasks, and recurring errors.

• skills/ A folder containing Python modules and configuration files for agent-generated skills. The agent registers these skills to expand its functionality dynamically.

• cron/ Contains scheduled automation configurations. The agent checks this folder to run background tasks on a recurring schedule.

• sessions/ Stores gateway session state files to track conversation state and message histories across Telegram or Discord.

• logs/ Contains runtime logs, including agent.log, gateway.log, and errors.log. The agent automatically redacts sensitive API keys and tokens before writing to these files.

The configuration engine follows a strict hierarchy of precedence: CLI arguments pass first, followed by settings defined in config.yaml, values set in the .env file, and finally the built-in system defaults. This layout ensures you can override configuration options on the fly using CLI flags without modifying persistent configurations.

To manage configurations, you should use the built-in CLI commands rather than editing the files manually. For instance, running hermes config displays your active settings, while hermes config edit opens config.yaml in your system editor. You can set values directly using hermes config set KEY VAL, which automatically routes keys to either config.yaml or .env based on whether the setting is sensitive. When you update the Hermes Agent, run hermes config migrate to update your local files to the latest schema.

You can also customize the identity file SOUL.md to define strict guidelines for your agent. For example, if you want your agent to write clean code and document steps in markdown, your SOUL.md should declare these parameters explicitly. This file is parsed at boot, and its contents are injected directly into the core system instructions of the LLM. You can create separate profiles using hermes profile create NAME, which isolates memory and configurations into dedicated sub-directories under ~/.hermes/.

To run shell commands and execute code, the Hermes Agent supports 6 terminal backends. The choice of backend depends on your security requirements and host architecture:

• Local Runs commands directly on the host machine. While this is fast and simple, it lacks isolation, meaning the agent can write to or delete any file in your local user directory.

• Docker Executes tasks inside containerized environments. This isolates the agent from your host file system, protecting your host machine from unintended commands.

• SSH Connects to a remote server to execute shell scripts. This is useful when the agent needs access to specific cloud environments or remote compute nodes.

• Singularity Provides containerized execution designed for high-performance computing (HPC) environments where Docker is not permitted due to security limitations.

• Modal A serverless execution provider. The agent's environment runs on-demand in the cloud and hibernates when idle, keeping compute costs low while maintaining access.

• Daytona A serverless environment manager that provides automated environment setup and wake-on-demand capabilities for persistent workflows.

You can switch backends using the CLI. For example, to set Docker as your active executor, run hermes config set terminal.backend docker. The agent will then run all terminal operations inside an isolated container.

If you deploy on Modal or Daytona, the system leverages serverless containers that spin up dynamically when a task is scheduled. When the tasks are completed, the container enters hibernation to prevent billing charges. Modal specializes in remote GPU and CPU compute scaling, spinning up containers in milliseconds, while Daytona focuses on managing development environments and local developer containers. While this is highly efficient for running background cron jobs or processing queued webhooks, it creates an issue with file loss.

If you want to add custom Python code to the agent, you can create a plugin. Plugins are stored in ~/.hermes/plugins/. Each plugin folder must contain a plugin.yaml config file and the Python source files. Unlike core tools, plugins allow you to add custom SaaS connectors or complex logic without modifying the main Hermes Agent codebase.

name: "custom_analyzer"
version: "1"
description: "Analyzes file formats and structures"
tools:
  - name: "analyze_structure"
    handler: "handler.py:analyze"
    description: "Extracts file format structures"

def analyze(file_path: str) -> dict:
    return {"status": "success", "file": file_path}

While containerized and serverless backends like Docker, Modal, and Daytona protect your host system, they introduce a storage challenge. Because these environments are ephemeral, any files, reports, or memory state files generated during execution are lost when the container stops or goes to sleep. To keep your work, you must configure a persistent storage layer.

Developers often use local directory mounts, but these only work when running locally. Cloud options like AWS S3 allow you to save files, but configuring access scripts and managing file versions across a team is complex. Google Drive provides storage but lacks metadata indexing and version history for agentic tools.

This is where Fast.io shared workspaces serve as a persistent workspace. Fast.io provides shared org-owned workspaces that act as a central repository for your agent. Every file saved to Fast.io has a per-file version history, allowing you to track changes and roll back edits made by the agent. Additionally, once you enable Fast.io Intelligence Mode, the workspace automatically indexes all uploaded files, making them searchable by meaning and queryable via RAG without setting up a database. Agents and humans can also use Collaborative Notes to co-edit files in real-time, bridging the gap between automated scripts and human team members.

Persist Hermes Agent files across sessions

Deploy your agent with a persistent shared workspace featuring automatic file indexing, per-file version history, and Metadata Views. Every organization begins with a 14-day free trial that requires a credit card.

Start 14-Day Trial

The Hermes Messaging Gateway runs as a continuous background daemon, allowing you to interact with your agent from messaging services. Instead of typing commands into a terminal, you can send tasks, ask questions, and receive files directly from your mobile device or chat client.

The gateway supports Telegram, Discord, WhatsApp, Signal, and email. You configure these connections by running hermes gateway setup and inputting the credentials for your chosen platform. Telegram bot setup requires chatting with the BotFather account on Telegram to obtain an API token, which you then enter during the gateway prompt. Discord setup requires visiting the Discord Developer Portal, creating an application, and activating the Message Content Intent under the Bot settings tab before copying the client token. To run the gateway in production, you should install it as a persistent system service. Below is a sample systemd service file configured to manage the gateway process:

[Unit]
Description=Hermes Agent Messaging Gateway Service
After=network.target

[Service]
Type=simple
User=hermes
WorkingDirectory=/home/hermes
ExecStart=/usr/local/bin/hermes gateway run
Restart=on-failure
Environment=PATH=/usr/local/bin:/usr/bin:/bin

[Install]
WantedBy=multi-user.target

Because the Hermes Agent runs shell commands on your terminal backends, securing the messaging gateway is critical. If your gateway is public, unauthorized users can send malicious commands to your server. To prevent this, you must specify allowed users in your .env file. For Telegram, you configure TELEGRAM_ALLOWED_USERS with your specific account ID. The gateway will ignore any message sent by an account not matching this list.

When you send files to the agent through Telegram or Discord, the gateway saves them locally and alerts the agent using the MEDIA:/path/to/file syntax. However, sending large documents, videos, or zip files back through chat interfaces is often blocked by attachment limits or network timeouts. To handle this, the agent can upload outputs to Fast.io and generate a branded share link. Fast.io shares can be durable or expiring, and you can restrict access per recipient. The agent sends the link back to the chat gateway, allowing the user to view or download the file securely from a web browser. This workflow bypasses file size limits and maintains a clear audit log of who accessed the data.

Follow these steps to deploy Hermes Agent with a persistent Fast.io workspace, connect the Model Context Protocol (MCP) server, and automate document data extraction.

Step 1: Install and Initialize the Agent

Install the agent using the official installation script. For Linux and macOS, run the following command in your terminal:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

After the installation finishes, run the setup portal to configure your model client and default tool gateways:

hermes setup --portal

Step 2: Configure Fast.io MCP Server

Fast.io exposes Streamable HTTP at /mcp and legacy SSE at /sse (refer to the Fast.io developer documentation for specific tool actions). You can connect Hermes Agent directly to these endpoints by declaring them in your config. To add the Fast.io MCP server, run hermes config edit and add the server to your config.yaml file:

mcp_servers:
  fastio:
    command: "npx"
    args:
      - "-y"
      - "@fastio/mcp-server"
    env:
      FASTIO_API_KEY: "your_api_key_here"

Once this MCP server is declared, the agent can read and write to your workspaces during runtime. You can test the MCP tools by asking the agent to list the available files in your workspace, verifying that it has read access.

Step 3: Automate Document Data Extraction with Metadata Views

Once the agent is connected, it can read and write to your workspaces. When the agent uploads business files (such as invoices, legal contracts, or design files) to a shared workspace, you can use Metadata Views to extract structured fields. Metadata Views turn documents into a queryable database. By writing natural language descriptions, you define a schema with columns of type Text, Integer, Decimal, Boolean, URL, JSON, or Date & Time. Fast.io automatically processes the files and populates a spreadsheet, which is detailed at the Fast.io Metadata Views product page.

The agent can use its MCP server to read these structured views, allowing it to automate business tasks like generating accounting reports or tracking renewal dates without manual coding. When combining this with Fast.io's Intelligence Mode, developers can run hybrid search queries. Hybrid search combines full-text and semantic search, allowing the agent to locate a document by its meaning or query specific metadata values, such as searching for contract files with renewal values above a specific number.

Step 4: Transfer Ownership to a Human Team

In a typical developer workflow, you might deploy an agent to set up a workspace, compile a document archive, and build metadata schemas. Once the project is complete, you can use the ownership transfer feature to hand the workspace over to your client or manager. The agent initiates the transfer via the API, and the human accepts it. While the client takes over the subscription and files, you can retain developer access to maintain the codebase. Fast.io has no permanent free plans or free agent tiers. Creating a user account is free, but performing work requires an organization. Every organization starts with a 14-day free trial that requires a credit card, allowing teams to test the setup before committing to a paid plan. You can choose from the Starter plan ($29/mo), the Business plan ($99/mo), or the Growth plan ($299/mo) depending on your team's size (find full details at the Fast.io pricing page).