Getting Started with Hermes Agent: A Comprehensive Beginner’s Guide (Part 1)

Artificial intelligence is rapidly transforming how developers, researchers, and teams automate complex tasks, orchestrate multi-step workflows, and build intelligent systems that adapt to real-world demands. Among the emerging tools in this rapidly evolving space, Hermes Agent stands out as a powerful, multi-role AI agent platform developed by Nous Research. Designed from the ground up for flexibility and extensibility, Hermes Agent enables users to deploy AI-driven automation with a rich skills system, scheduled cron jobs, and seamless Model Context Protocol (MCP) integration.

In this first installment of our comprehensive Hermes Agent tutorial series, we will walk you through everything you need to get started — from the very first installation command to running a complete workflow. By the end of this guide, you will have Hermes Agent installed on your system, configured correctly for your environment, and running your very first automated task. Whether you are a software developer looking to eliminate repetitive chores, a data scientist seeking to orchestrate pipelines, or a researcher exploring the frontiers of AI agent architectures, this guide provides the solid foundation you need.

Table of Contents

  1. What is Hermes Agent?
  2. Prerequisites
  3. Installation
  4. Configuration
  5. Understanding the Architecture
  6. Your First Workflow
  7. Running Cron Jobs
  8. MCP Integration Basics
  9. Troubleshooting Common Issues
  10. Next Steps

What is Hermes Agent?

Hermes Agent is an open-source, multi-role AI agent framework created by the team at Nous Research. Unlike simple chatbot interfaces or single-purpose automation scripts, Hermes Agent is architected to serve as a general-purpose intelligence layer that can assume different personas, load domain-specific capabilities on demand, and interact with external systems through standardized protocols.

At its core, Hermes Agent treats automation as a conversation between specialized actors. Each actor — called a role — carries its own context, system instructions, and permitted skills. This design makes it possible to build a single agent instance that behaves like a code reviewer in one moment and a data analyst in the next, simply by switching roles.

Key features that distinguish Hermes Agent from other automation frameworks include:

The project is actively maintained on GitHub at https://github.com/NousResearch/hermes-agent, where you can find the latest releases, contribute code, and report issues.

Prerequisites

Before installing Hermes Agent, ensure your environment meets the following baseline requirements. These prerequisites are minimal by design, reflecting the project’s philosophy of accessibility:

You can quickly verify your shell and curl availability by running the following commands in your terminal:

echo $SHELL
curl --version

If you plan to use local LLM inference instead of a cloud provider, you will also need a compatible inference engine such as llama.cpp or vLLM running on your machine.

Installation

Installing Hermes Agent is intentionally straightforward. The Nous Research team provides an official setup script that handles platform detection, binary installation, and initial directory creation automatically.

Running the Setup Script

Open your terminal and execute the following one-liner:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/setup-hermes.sh | bash

This script performs several important actions behind the scenes:

  1. Platform detection: Identifies your operating system and CPU architecture (x86_64, arm64, etc.).
  2. Binary download: Fetches the latest stable release of the hermes binary from GitHub Releases.
  3. Installation: Places the binary in a directory within your PATH, typically ~/.local/bin for user-local installs or /usr/local/bin for system-wide installs.
  4. Directory scaffolding: Creates the default configuration directory at ~/.hermes/ with subdirectories for roles, skills, logs, and data.
  5. Verification: Runs a quick smoke test and prints the installed version to confirm success.

Verifying the Installation

After the script completes, confirm that Hermes Agent is available by checking its version:

hermes --version

You should see output similar to the following:

hermes-agent v0.9.2

If the command returns command not found, the installation directory is likely missing from your PATH. You can resolve this by adding the following line to your shell profile file (~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish):

export PATH="$HOME/.local/bin:$PATH"

After editing the profile, reload your shell configuration so the change takes effect immediately:

source ~/.bashrc  # or source ~/.zshrc

Alternative: Manual Installation

If you prefer not to run a remote script, you can download the appropriate binary directly from the GitHub Releases page, extract it, and place it in a directory of your choice. This approach is favored in high-security environments where piping scripts to bash is restricted.

Configuration

Hermes Agent uses a central YAML configuration file located at ~/.hermes/config.yaml. This file is the heart of your agent’s behavior, controlling everything from the active role to LLM parameters and external integrations.

Creating the Configuration File

If the setup script did not create the file automatically, you can initialize it manually:

mkdir -p ~/.hermes
touch ~/.hermes/config.yaml

Starter Configuration

Open ~/.hermes/config.yaml in your preferred text editor and paste the following starter template. This configuration is designed to work out of the box while remaining easy to customize:

# Hermes Agent Configuration
agent:
  name: "default-agent"
  role: "general-assistant"
  log_level: "info"
  workspace: "~/.hermes/workspace"

llm:
  provider: "openai"
  model: "gpt-4o"
  api_key: "${OPENAI_API_KEY}"
  temperature: 0.7
  max_tokens: 2048
  timeout_seconds: 60

skills:
  directory: "~/.hermes/skills"
  auto_load: true
  allowed:
    - "*"

scheduler:
  enabled: true
  timezone: "UTC"
  jobs_file: "~/.hermes/jobs.yaml"

mcp:
  enabled: true
  servers:
    - name: "filesystem"
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "~/.hermes/data"]

logging:
  directory: "~/.hermes/logs"
  max_files: 30
  format: "json"

Configuration Section Reference

SectionPurpose
agentDefines the agent’s identity, active role, logging verbosity, and workspace path.
llmConfigures the large language model provider, model name, generation parameters, and request timeouts.
skillsPoints to the skills directory, toggles auto-loading, and optionally restricts which skills may be loaded.
schedulerEnables or disables the built-in cron-like job scheduler and sets the timezone for job execution.
mcpConfigures MCP server connections, allowing the agent to invoke external tools through a standardized protocol.
loggingControls log output location, retention policy, and formatting.

Managing Secrets with Environment Variables

For security and portability, it is strongly recommended to inject sensitive values — especially API keys — through environment variables rather than hardcoding them in YAML. Hermes Agent supports POSIX-style variable interpolation using ${VAR_NAME} syntax.

Before starting the agent, export your key in the terminal:

export OPENAI_API_KEY="sk-your-key-here"

To make this persistent across terminal sessions, add the export line to your shell profile and reload it.

Validating Your Configuration

Hermes Agent ships with a built-in configuration validator that catches syntax errors, missing required fields, and type mismatches before the agent starts. Run the validator whenever you make changes:

hermes config validate

A valid configuration produces:

✓ Configuration is valid

If errors exist, the validator prints detailed messages with line numbers and suggestions, making debugging straightforward.

Understanding the Architecture

To use Hermes Agent effectively, it helps to understand three foundational concepts: roles, skills, and the scheduler.

Roles

A role defines the persona, behavioral context, and available capabilities of the agent at runtime. You can maintain multiple roles and switch between them by changing the agent.role field in config.yaml or by passing the --role flag on the command line.

Roles are stored as individual YAML files in ~/.hermes/roles/. Here is an example of a role specialized for code review:

# ~/.hermes/roles/code-reviewer.yaml
name: "code-reviewer"
system_prompt: |
  You are an expert software engineer specializing in code review.
  Focus on security vulnerabilities, performance bottlenecks, and maintainability.
  Be concise and actionable in your feedback. Always suggest improvements
  rather than merely pointing out problems.
skills:
  - "git"
  - "static-analysis"
  - "linter"

When this role is active, the agent will load only the skills listed under skills, constraining its tool access appropriately.

Skills

Skills are modular extensions that give the agent new capabilities. A skill can be as simple as a Python script that wraps a shell command, or as complex as a multi-file package integrating with a third-party API.

The standard directory structure for a skill looks like this:

~/.hermes/skills/
└── hello/
    ├── skill.yaml
    └── main.py

The skill.yaml manifest declares metadata and the entry point:

name: "hello"
description: "A simple greeting skill that returns a friendly message"
version: "1.0.0"
author: "your-name"
entrypoint: "main.py"

Skills are loaded automatically at startup when skills.auto_load is enabled, or they can be loaded on demand using the CLI.

Scheduler

The scheduler provides cron-style recurring task execution without requiring a separate system cron daemon. Jobs are declared in ~/.hermes/jobs.yaml and are managed through the hermes scheduler subcommand. This tight integration means scheduled jobs have full access to the agent’s roles, skills, and LLM context.

Your First Workflow

Let us now build a practical workflow that demonstrates how roles, skills, and the agent runtime work together. Our workflow will create a role, build a custom skill that fetches the current date and time, and then invoke the agent to perform a task using both.

Step 1: Create a Tutorial Role

First, define a new role optimized for teaching and guided assistance:

mkdir -p ~/.hermes/roles
cat > ~/.hermes/roles/tutorial.yaml << 'EOF'
name: "tutorial"
system_prompt: |
  You are a helpful tutorial assistant.
  You guide users through learning new tools step by step.
  Always be encouraging, provide clear examples, and explain
  the reasoning behind each step.
  When invoking skills, briefly describe what the skill does
  so the user learns by observation.
skills:
  - "datetime"
  - "filesystem"
EOF

Step 2: Build a DateTime Skill

Create the skill directory and its manifest:

mkdir -p ~/.hermes/skills/datetime
cat > ~/.hermes/skills/datetime/skill.yaml << 'EOF'
name: "datetime"
description: "Provides current date and time information in ISO format"
version: "1.0.0"
entrypoint: "main.py"
EOF

Now implement the skill logic:

cat > ~/.hermes/skills/datetime/main.py << 'EOF'
#!/usr/bin/env python3
from datetime import datetime
import sys

def get_current_time():
    return datetime.now().isoformat()

def get_current_date():
    return datetime.now().strftime("%Y-%m-%d")

if __name__ == "__main__":
    if len(sys.argv) > 1 and sys.argv[1] == "--date":
        print(get_current_date())
    else:
        print(get_current_time())
EOF

chmod +x ~/.hermes/skills/datetime/main.py

This skill supports two modes: returning the full ISO timestamp by default, or returning only the date when passed the --date flag.

Step 3: Activate the Tutorial Role

Update your ~/.hermes/config.yaml to use the new role:

agent:
  name: "tutorial-agent"
  role: "tutorial"
  log_level: "debug"

Run the validator to ensure everything is consistent:

hermes config validate

Step 4: Run Interactive Mode

Start the agent in interactive mode to converse with it directly:

hermes run --interactive

At the prompt, try asking:

> What is the current date and time?

The agent will recognize that it needs temporal information, invoke the datetime skill, and synthesize a response such as:

The current date and time is 2026-06-09T14:32:10.

Because the tutorial role is active, the agent will also explain that it used the datetime skill, reinforcing the learning experience.

Step 5: Execute a One-off Task

Interactive mode is excellent for exploration, but automation often requires executing a single task and exiting. Hermes Agent supports this via the --task flag:

hermes run --task "Say hello and tell me today's date" --role tutorial

This pattern is ideal for CI/CD pipelines, pre-commit hooks, and shell scripts where you need deterministic, scriptable behavior.

Running Cron Jobs

One of Hermes Agent’s most powerful features is its built-in scheduler, which enables cron-style automation without relying on the host system’s cron daemon. This means your scheduled jobs inherit the agent’s full context — roles, skills, LLM access, and MCP tools.

Defining a Scheduled Job

Create or edit ~/.hermes/jobs.yaml:

jobs:
  - name: "hourly-health-check"
    schedule: "0 * * * *"
    role: "tutorial"
    task: "Perform a system health check: report disk usage, memory usage, and running process count."
    enabled: true

  - name: "daily-summary"
    schedule: "0 9 * * *"
    role: "tutorial"
    task: "Generate a brief summary of today's agenda based on ~/.hermes/data/notes.txt"
    enabled: true

The schedule field follows standard five-field cron syntax:

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6, Sunday = 0)
│ │ │ │ │
* * * * *

Managing the Scheduler

Start the scheduler in the foreground for testing:

hermes scheduler start

For production or long-running use, start it as a background daemon:

hermes scheduler start --daemon

Monitor the scheduler’s status:

hermes scheduler status

Stop the scheduler gracefully:

hermes scheduler stop

All job outputs and any errors are written to ~/.hermes/logs/scheduler.log by default, making it easy to audit automated actions.

MCP Integration Basics

The Model Context Protocol (MCP) is an open standard developed to solve a common problem in AI agent design: how to connect agents to external tools, databases, and APIs in a consistent, secure, and discoverable way. Hermes Agent has first-class MCP support, allowing you to extend your agent’s reach far beyond its built-in skills.

Configuring an MCP Server

MCP servers are declared in the mcp.servers list within ~/.hermes/config.yaml. Each server is defined by a name, the command to launch it, and any arguments it requires.

Here is an example configuration that connects to both a filesystem server and a web fetch server:

mcp:
  enabled: true
  servers:
    - name: "filesystem"
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "~/.hermes/data"]
    - name: "fetch"
      command: "uvx"
      args: ["mcp-server-fetch"]

When the agent starts, it launches each configured MCP server as a subprocess and communicates with it over stdio using the MCP protocol. Tools exposed by the server become available to the agent dynamically.

Using MCP Tools in Workflows

Once an MCP server is connected, its tools are automatically discoverable by the agent. You can reference them naturally in task descriptions:

hermes run --task "Read the file ~/.hermes/data/notes.txt and summarize its contents" --role tutorial

Behind the scenes, the agent routes the file reading operation through the MCP filesystem server, receives the raw content, and then processes it using its configured LLM to generate the summary. This separation of concerns — tool execution versus reasoning — is one of the key strengths of the MCP architecture.

Troubleshooting Common Issues

Even with a well-designed tool, you may encounter hiccups during setup. Here are solutions to the most common issues reported by new Hermes Agent users.

Command Not Found After Installation

If your terminal reports hermes: command not found, the binary directory is not in your PATH. Diagnose with:

which hermes || echo "Hermes not in PATH"
echo $PATH

Ensure ~/.local/bin is included. If not, add the export line to your shell profile and reload it.

Invalid Configuration Errors

YAML is sensitive to indentation. A single misplaced space can prevent the agent from starting. Always run the validator after editing:

hermes config validate

Common mistakes include using tabs instead of spaces, forgetting quotes around strings containing special characters, and omitting required fields like agent.name.

Skill Fails to Load

If a skill does not appear in interactive mode or produces errors:

  1. Verify the skill directory exists under ~/.hermes/skills/.
  2. Confirm that skill.yaml is correctly formatted and that entrypoint points to an existing file.
  3. Ensure the entrypoint script has executable permissions (chmod +x).
  4. Check that skills.auto_load is set to true in config.yaml.
  5. Review ~/.hermes/logs/agent.log for detailed loading traces.

Scheduler Jobs Not Executing

If scheduled jobs appear to be ignored:

  1. Confirm that scheduler.enabled is true in config.yaml.
  2. Verify that hermes scheduler status reports an active state.
  3. Double-check your cron syntax. Online cron parsers or the hermes scheduler validate command can help.
  4. Ensure the timezone setting matches your expectation; the scheduler uses UTC by default.

Next Steps

Congratulations! You have successfully installed Hermes Agent, configured your environment, and executed your first workflow. In this guide, you learned how to:

This foundation positions you to tackle far more sophisticated automation challenges. In Part 2 of this series, we will explore advanced topics including:

Stay tuned, and happy automating!

Resources

Published on June 9, 2026. This tutorial was written for Hermes Agent v0.9.x. Commands and configuration options may evolve in future releases; always consult the official documentation for the latest details.