Chapter 5

Quick Start: Run Your First Hermes Agent in 10 Minutes

Chapter 5: Quick Start — Running Your First Hermes Agent in 10 Minutes

Chapter Overview

Enough theory — it is time to act. This chapter is a precise operational manual: from environment verification, installation, and initial configuration, to running your first real task. The full process is designed to take under 10 minutes. We provide complete command sequences for macOS, Linux, and WSL2 (Windows), plus a detailed troubleshooting guide. The chapter concludes with an "installation verification checklist" to confirm everything is ready.

5.1 Environment Requirements

Before starting the installation, confirm your environment meets these requirements:

Hardware Requirements

Component	Minimum	Recommended
CPU	Dual-core 2GHz	Quad-core 3GHz+
Memory	4GB RAM	8GB+ RAM
Disk	2GB available	10GB+ (for local models)
Network	Stable internet connection	Low-latency connection (for cloud API use)

Local model users note: If you plan to use local Hermes models rather than cloud APIs, hardware requirements increase significantly:

Hermes 3 8B: Requires 8GB+ VRAM (GPU) or 16GB+ RAM (CPU inference)

Hermes 4 70B: Requires 40GB+ VRAM or 80GB+ RAM

Software Dependencies

# Check Python version (requires 3.9+)
python3 --version
# Expected output: Python 3.9.x or higher

# Check pip
pip3 --version

# Check Git
git --version

5.2 macOS Installation (Recommended)

Step 1: Install Homebrew (if not already installed)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Step 2: Install Python 3.11

brew install [email protected]

# Verify
python3.11 --version
# Expected output: Python 3.11.x

Step 3: Create a Virtual Environment (strongly recommended)

# Create project directory
mkdir ~/hermes-workspace && cd ~/hermes-workspace

# Create virtual environment
python3.11 -m venv hermes-env

# Activate virtual environment
source hermes-env/bin/activate

# Prompt should change to (hermes-env) $

Step 4: Install Hermes Agent

# Install latest version
pip install hermes-agent

# Install specific version (if needed)
pip install hermes-agent==0.8.2

# Verify installation
hermes --version
# Expected output: hermes-agent 0.8.x

Step 5: Initialize Configuration

# Run configuration wizard
hermes init

# The wizard will prompt for:
# 1. Default LLM provider (OpenAI/Anthropic/NousResearch/Ollama)
# 2. API Key
# 3. Default tool set
# 4. Data storage path (Skill library, etc.)

Configuration wizard sample output:

Hermes Agent Initialization Wizard
====================================

Select your default LLM provider:
1. NousResearch (Hermes 4) [Recommended]
2. OpenAI (GPT-4)
3. Anthropic (Claude)
4. Ollama (Local model)

Your choice [1]: 1

Enter NousResearch API Key:
(Register at https://api.nousresearch.com)
API Key: nous-xxxxxxxxxxxxxxxx

✓ API Key validated successfully

Data storage path (default: ~/.hermes):
[Press Enter to use default]

✓ Initialization complete! Configuration saved to ~/.hermes/config.yaml

Run 'hermes chat' to start, or 'hermes run "your task"' to execute a task.

5.3 Linux Installation

Ubuntu / Debian

# Update package manager
sudo apt-get update

# Install Python 3.11 and tools
sudo apt-get install -y python3.11 python3.11-venv python3.11-dev pip3

# Create and activate virtual environment
mkdir ~/hermes-workspace && cd ~/hermes-workspace
python3.11 -m venv hermes-env
source hermes-env/bin/activate

# Install Hermes
pip install hermes-agent

# Initialize
hermes init

CentOS / RHEL / Fedora

# Fedora
sudo dnf install python3.11 python3.11-devel

# CentOS/RHEL requires EPEL
sudo yum install epel-release
sudo yum install python3.11

# Remaining steps are the same as Ubuntu
python3.11 -m venv ~/hermes-workspace/hermes-env
source ~/hermes-workspace/hermes-env/bin/activate
pip install hermes-agent
hermes init

Using pipx (isolated installation, recommended for system-wide use)

# Install pipx
pip install pipx
pipx ensurepath

# Install Hermes via pipx (isolated environment, no manual venv management)
pipx install hermes-agent

# Use directly without environment activation
hermes --version

5.4 WSL2 (Windows Subsystem for Linux) Installation

Prerequisite: Install WSL2

# Run in Windows PowerShell (as Administrator)
wsl --install

# After restart, Ubuntu is installed by default
# Open the Ubuntu terminal

Installing Inside WSL2

# Update Ubuntu
sudo apt-get update && sudo apt-get upgrade -y

# Install Python 3.11
sudo apt-get install -y python3.11 python3.11-venv python3.11-dev

# Create workspace directory (in Linux filesystem, not /mnt/c/)
mkdir ~/hermes-workspace && cd ~/hermes-workspace

# Create virtual environment
python3.11 -m venv hermes-env
source hermes-env/bin/activate

# Install
pip install hermes-agent

# Initialize
hermes init

WSL2 performance note: Place project files in WSL2's Linux filesystem (~/) rather than Windows mount directories (/mnt/c/) for significantly better file I/O performance.

5.5 Configuration In Depth

Configuration File Structure

Hermes configuration is stored in ~/.hermes/config.yaml:

# ~/.hermes/config.yaml
version: "1.0"

# LLM model configuration
model:
  provider: "nousresearch"
  name: "hermes-4"
  api_key: "nous-xxxxxxxxxxxx"    # Use environment variable in practice
  temperature: 0.1                # Low temperature for more stable results
  max_tokens: 4096

# Tool configuration
tools:
  enabled: "all"
  sandbox_code_execution: true
  allowed_file_paths:
    - "~/Documents"
    - "~/Downloads"
    - "/tmp"

# Learning system configuration
learning:
  skill_library_path: "~/.hermes/skills"
  auto_extract_skills: true
  skill_confidence_threshold: 0.8

# Context management
context:
  compression_enabled: true
  max_context_tokens: 32768
  compression_trigger: 0.8       # Trigger compression at 80% capacity

# Security settings
security:
  require_confirmation_for:
    - "email"
    - "webhook"
    - "file_delete"
  forbidden_operations:
    - "system_format"
    - "sudo"

Managing Sensitive Information with Environment Variables (Recommended)

# Add to ~/.bashrc or ~/.zshrc
export HERMES_API_KEY="nous-xxxxxxxxxxxx"
export OPENAI_API_KEY="sk-xxxxxxxxxxxx"
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxx"

# Reference in config.yaml:
# model:
#   api_key: "${HERMES_API_KEY}"

5.6 Running Your First Conversation

Interactive Chat Mode

# Start interactive chat
hermes chat

# Output:
# Hermes Agent v0.8.x
# Model: hermes-4 (NousResearch)
# Tools loaded: 42
# Skill library: 0 skills (fresh install)
#
# Enter your task, 'help' for commands, '/quit' to exit
#
# >

# Try your first simple task:
> Search for "large language model latest advances 2025" and give me a 150-word English summary

# Hermes will:
# 1. Invoke the web_search tool
# 2. Process search results
# 3. Generate a summary
# 4. Distill and save a Skill from this session

Single-Task Mode (Non-interactive)

# Execute a single task
hermes run "Explain the differences between Python asyncio and threading,
           compare them in a table, and give a real-world scenario
           recommendation for when to use each"

# With file input
hermes run --input /path/to/document.pdf \
  "Analyze this document, extract key data points, and generate a summary"

# Specify output file
hermes run "Generate a brief introduction to quantum computing" \
  --output /tmp/quantum_intro.md

# Debug mode (shows every tool invocation step)
hermes run --debug \
  "Search for Hermes 4 technical specifications and organize them into a table"

Your First Complete Multi-Step Task

# A complete example demonstrating Hermes's multi-step capability
hermes run """
Task: Quick Competitor Research

Please complete the following steps:
1. Search for information about 'AI Agent frameworks 2025'
2. Identify mainstream frameworks (at least 5)
3. Compare their core features (programming language, main capabilities, license)
4. Generate a comparison table in Markdown format
5. Save the result to ~/Desktop/agent_comparison.md
"""

Expected output (after approximately 2–3 minutes):

[Hermes Agent Execution Log]
─────────────────────────────────────
Step 1/5: Search for information
  → Calling web_search("AI Agent frameworks 2025")
  → Retrieved 12 results
  ✓ Complete (3.2s)

Step 2/5: Identify mainstream frameworks
  → Analyzing search results
  → Identified: LangChain, AutoGen, CrewAI, Hermes, OpenHands, Dify
  ✓ Complete (1.1s)

Step 3/5: Collect detailed information
  → Calling web_search × 6 (one per framework)
  → Calling web_scraper (fetching GitHub page data)
  ✓ Complete (18.4s)

Step 4/5: Generate comparison table
  → Organizing data, formatting Markdown
  ✓ Complete (2.3s)

Step 5/5: Save file
  → Calling file_writer
  → File saved: ~/Desktop/agent_comparison.md
  ✓ Complete (0.1s)

─────────────────────────────────────
Task complete! Total time: 25.1s
Skill distillation: 2 new skills extracted from this task
  - "Multi-framework comparative research workflow"
  - "Open-source project data extraction from GitHub"

5.7 Troubleshooting Common Installation Issues

Issue 1: `hermes` command not found

# Cause: PATH not correctly configured
# Solution:
which hermes   # Check installation location

# If using venv, confirm it is activated:
source ~/hermes-workspace/hermes-env/bin/activate

# If using pipx, refresh PATH:
pipx ensurepath
source ~/.bashrc   # or ~/.zshrc

Issue 2: API Key validation failure

# Check if API Key is correctly set
hermes config show | grep api_key

# Test API connection
hermes test connection

# If using environment variable, verify it takes effect
echo $HERMES_API_KEY

# Reconfigure
hermes config set --api-key "your-key-here"

Issue 3: Python version conflict

# Check current Python version
python3 --version

# If below 3.9, explicitly use python3.11
python3.11 -m pip install hermes-agent
python3.11 -m hermes init

# Or use pyenv to manage multiple Python versions
brew install pyenv
pyenv install 3.11.9
pyenv global 3.11.9

Issue 4: Network connection timeout

# Test connectivity
curl -s https://api.nousresearch.com/v1/models

# If proxy is required
export HTTPS_PROXY="http://your-proxy:port"
hermes test connection

# Configure Hermes to use proxy
hermes config set --proxy "http://your-proxy:port"

Issue 5: Insufficient tool execution permissions

# Check current tool permission configuration
hermes tools permissions

# Add file access permissions
hermes config set --allowed-paths "/home/user/data,/tmp"

# Enable bash execution (disabled by default, requires explicit authorization)
hermes config set --enable-bash-execution true

5.8 Installation Verification Checklist

Run the following verification to confirm a fully successful installation:

#!/bin/bash
# Hermes installation verification script
echo "=== Hermes Agent Installation Verification ==="

# 1. Version check
echo -n "1. Version check... "
hermes --version > /dev/null 2>&1 && echo "✓ Pass" || echo "✗ Fail"

# 2. Configuration check
echo -n "2. Configuration check... "
hermes config validate > /dev/null 2>&1 && echo "✓ Pass" || echo "✗ Fail"

# 3. API connection test
echo -n "3. API connection test... "
hermes test connection > /dev/null 2>&1 && echo "✓ Pass" || echo "✗ Fail"

# 4. Tool loading test
echo -n "4. Tool loading test... "
TOOL_COUNT=$(hermes tools list 2>/dev/null | wc -l)
[ "$TOOL_COUNT" -gt 20 ] && echo "✓ Pass (${TOOL_COUNT} tools)" || echo "✗ Fail"

# 5. Basic task test
echo -n "5. Basic task test... "
RESULT=$(hermes run "Reply in one sentence: this is just a test" 2>/dev/null)
[ -n "$RESULT" ] && echo "✓ Pass" || echo "✗ Fail"

# 6. Skill library initialization
echo -n "6. Skill library check... "
[ -d ~/.hermes/skills ] && echo "✓ Pass" || echo "✗ Fail"

echo ""
echo "Verification complete. If all items show ✓, Hermes is installed successfully."

# Run the verification script
bash hermes_verify.sh

Expected all-pass output:

=== Hermes Agent Installation Verification ===
1. Version check... ✓ Pass
2. Configuration check... ✓ Pass
3. API connection test... ✓ Pass
4. Tool loading test... ✓ Pass (42 tools)
5. Basic task test... ✓ Pass
6. Skill library check... ✓ Pass

Verification complete. If all items show ✓, Hermes is installed successfully.

Chapter Summary

After completing this chapter, you have:

Verified environment requirements and understood minimum hardware/software dependencies
Completed installation on three platforms (macOS/Linux/WSL2), choosing the method that fits your environment
Understood the configuration file structure and know how to adjust key parameters
Executed your first task, directly witnessing Hermes's multi-step autonomous execution
Mastered troubleshooting, knowing where to look for common problems
Passed the installation verification, confirming the system is ready

You now stand at the starting line with Hermes. The chapters ahead will take you deeper into understanding how it works, optimizing your usage strategies, and building more sophisticated agent applications.

Review Questions

During the installation process, which step was most confusing or time-consuming for you? Was this a problem with environment configuration, documentation, or something this chapter could have explained better?
What results did your first task produce? What aspects of Hermes's performance exceeded expectations? What fell short?
Examine the Skill library Hermes created (~/.hermes/skills/). What has been saved there already? What new understanding of Hermes's learning mechanism does this give you?
If you were going to deploy Hermes for other members of your team, which parts of the installation and configuration process most need to be documented?

Next chapter: Learning Paths and Book Guide — find the optimal learning route based on your role (user / developer / deployer).

Rate this chapter

4.9 / 5 (92 ratings)