How to Install and Set Up Hermes Agent: Complete Beginner's Guide

on

The era of simple text-based chatbots is over. We're now living in the age of agents—systems that directly modify files on your PC, open browsers to search for information, and code solutions they need. Hermes Agent sits at the center of this revolution, excelling at understanding user intent and generating executable code. Whether you're a complete beginner or looking to build your first agent, I'll walk you through everything from installation to real-world deployment in meticulous detail.




Terminal Setup and Local Environment Strategy


To get started, you need a Terminal environment where you can enter commands. Mac users can search for Terminal using Spotlight (Cmd+Space), while Windows users should open PowerShell as an administrator and install WSL2 first with the command wsl --install. Linux users can simply press Ctrl+Alt+T to launch the terminal immediately.


The first tool you need to check is Git. Type git --version in Terminal—if version information doesn't appear, you'll need to install Git for your specific OS. Once Git is ready, you can use the one-line script below to automatically install all dependencies like Python and Node.js.


# 1. Verify Git installation (install from https://git-scm.com/ if needed)
git --version

# 2. Run the one-line installation script
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 3. Apply environment variables (run this if commands aren't found)
source ~/.bashrc


If you're an advanced user who wants faster and more efficient package management, consider using uv. It's an extremely fast Python package manager that lets you install Hermes cleanly in an isolated environment with these commands:


# Install uv and Hermes
curl -LsSf https://astral.sh/uv/install.sh | sh
uv pip install -e ".[all]"


Key checklist:

  • Launch Terminal and verify WSL2/environment variables by OS
  • Confirm Git installation for version control foundation
  • Resolve all Python and Node.js dependencies through automatic installation script
  • Optional: use the uv package manager for high-performance installation
  • Verify normal operation by running the hermes command
  • If errors occur, try the source command or restart your terminal

Connecting to Models: OpenRouter and API Key Setup


For your agent to think intelligently, you need to connect an LLM (Large Language Model) as its brain. As of 2026, the most recommended approach is using OpenRouter (https://openrouter.ai/). Sign up by clicking the Sign Up button in the top right, then navigate to Keys and click Create Key to generate your personal API key.


OpenRouter is perfect for beginners because a single key lets you freely test hundreds of models—Claude 3.5 Sonnet, GPT-4o, Llama 3, and more—and switch between them instantly. In your first week or two, experiment with different models to find the brain that works best for you. Once you've settled on a specific model, you can later sign up directly with that service (like Anthropic) and connect the API there, saving roughly 10% in fees while also getting faster response times.


Cost comparison (per 1M tokens):
- Claude via OpenRouter: ~$3.00 (includes convenience markup)
- Direct Anthropic API: ~$2.70 (requires direct management)


If you want messenger integration, you'll also need to generate a Bot Token through Telegram's @BotFather. Create a bot using the /newbot command and save the token you receive. With just this token, you can assign tasks to your agent directly from the Telegram app on your phone.


Key checklist:

  • OpenRouter signup and unified API key generation process
  • Explore optimal LLM options (Claude, GPT, etc.) based on your use case
  • Establish a testing period, then optimize costs through direct API connections
  • Create external control bots using Telegram @BotFather
  • Monitor API usage and balance across each platform
  • Securely store and manage Secret Keys separately for security

The Complete config.yaml Guide and Security Setup


All agent settings are configured in the config.yaml file. YAML syntax is particular about indentation—always use 2 spaces instead of tabs. For beginners, using VS Code (command: code ~/.hermes/config.yaml) is much safer than Terminal's nano editor. Below is a complete configuration example that balances security and scalability:


# ~/.hermes/config.yaml – Full configuration example
model:
  provider: openrouter
  api_key: ${OPENROUTER_API_KEY}  # Environment variables recommended
  model: anthropic/claude-sonnet-4

terminal: local              # Change to docker for VPS security

gateway:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
  discord:
    token: ${DISCORD_BOT_TOKEN}
  slack:
    token: ${SLACK_BOT_TOKEN}

toolsets:                    # Restrict or enable tool sets
  - web
  - terminal
  - file
  - skills


For security, avoid typing API keys directly into configuration files. Instead, use Terminal's environment variable feature. Register commands like export OPENROUTER_API_KEY="sk-or-xxxxx" in your .bashrc or .zshrc—this way, even if your config file is exposed, your precious API credits remain protected. When running on external servers (VPS), setting the terminal option to docker is essential to keep the agent isolated and prevent it from accessing your entire system.


Key checklist:

  • Use GUI editors like VS Code for safe YAML editing
  • Strengthen API key security through environment variables
  • Set up Docker isolation when running on VPS for system protection
  • Enable multi-gateway integration (Telegram, Discord, Slack)
  • Control agent permissions through toolsets configuration
  • Verify changes take effect in real-time after agent restart

Understanding the Skill System and Intelligent Maintenance


The most powerful feature of Hermes Agent is its Skill system. A Skill is a Markdown file that stores a task procedure the agent has learned. For example, when you ask it to convert Markdown to HTML, the agent automatically saves that entire complex process as a file like ~/.hermes/skills/markdown-to-html.md. The next time you make the same request, it reads this file and processes it much faster and more accurately.


After using the agent for a while, the size of its SQLite-based state.db file can grow. Occasionally check its size with du -h ~/.hermes/state.db in Terminal. If you feel your agent's memory has become corrupted, you can directly open the MEMORY.mdfile in the memories folder and correct or delete incorrect information.


# Memory maintenance examples
nano ~/.hermes/memories/MEMORY.md  # Edit what the agent remembers about you
rm ~/.hermes/skills/unwanted.md    # Delete a skill it learned incorrectly


The most common error, YAML parsing error, usually happens because of incorrect indentation or tab characters mixed into your file. If the hermes command won't run, try opening a new terminal window or updating the package with pip install --upgrade hermes-agent. As time goes on, you'll experience the joy of building your own personalized agent that understands you better and creates the tools it needs—truly making the leap in productivity.


Key checklist:

  • How the Markdown-based Skill system works and how to use it
  • Check state.db file size and manage your database regularly
  • Curate agent memory by directly editing MEMORY.md
  • Troubleshoot YAML parsing errors and path recognition issues
  • Upgrade packages periodically to access the latest features
  • Delete custom skills and retrain them for optimization

Now open Terminal and start having conversations with your own agent. You're about to experience a whole new dimension of productivity.