↓ Skip to main content
Linux blog

Hermes Agent: Complete How-To Guide

·821 words·4 mins· ·
Linux Hermes-Agent Ai Guide Linux Opensource How-To

What is Hermes Agent?
#

Hermes Agent is an open-source, self-hosted AI agent created by Nous Research. It runs in your terminal or as a gateway service, connects to multiple LLM providers, and has powerful tools for browsing the web, writing code, managing files, and automating tasks.

Unlike cloud-only AI assistants, Hermes Agent lives on your own server — your data stays private, you control everything, and it’s fully customizable.

Prerequisites
#

Before starting, make sure you have:

  • A Linux server (Ubuntu 22.04+ / 24.04 recommended)
  • Python 3.10+ and pip
  • Node.js 18+ (for some features)
  • Git
  • An API key for an LLM provider (OpenAI, Anthropic, OpenRouter, etc.)

Step 1: Install Hermes Agent
#

The recommended way to install Hermes Agent is via pip:

# Install from PyPI
pip install hermes-agent

Or use the latest development version from GitHub:

git clone https://github.com/nousresearch/hermes-agent.git
cd hermes-agent
pip install -e .

Step 2: Configure Your Provider
#

Hermes Agent supports multiple LLM providers. Set up your API key:

# Using OpenRouter (recommended for flexibility)
export OPENROUTER_API_KEY="sk-or-v1-your-key-here"

# Or using OpenAI
export OPENAI_API_KEY="sk-your-key-here"

# Or using Anthropic
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

For persistent configuration, create a .env file in your project directory:

echo 'OPENROUTER_API_KEY="sk-or-v1-your-key-here"' >> .env
echo 'HERMES_MODEL="openrouter/anthropic/claude-sonnet-4"' >> .env

Step 3: Start the Gateway (Optional)
#

Hermes Agent can run as a gateway service that connects to messaging platforms:

# Start the gateway
hermes gateway start

This allows you to interact with Hermes Agent from:

  • Telegram — chat with your agent via Telegram bot
  • Feishu/Lark — integrate with Feishu group chats
  • Discord — connect to Discord servers
  • Terminal — direct CLI access

Step 4: Configure Channels
#

Edit your ~/.hermes/config.yaml to add your messaging channels:

telegram:
  bot_token: "your-bot-token"
  allowed_users: ["your-user-id"]

feishu:
  app_id: "your-app-id"
  app_secret: "your-app-secret"

channel:
  default: "telegram:your-user-id"

Step 5: Install Skills
#

Hermes Agent is extensible via “skills” — plugins that add capabilities:

# List available skills
hermes skills list

# Install a skill
hermes skills install web-search
hermes skills install github-code-review
hermes skills install youtube-content

# View skill documentation
hermes skill view jupyter-live-kernel

Popular skills include:

  • web-research-cli — search the web and fetch pages
  • github-pr-workflow — manage GitHub pull requests
  • jupyter-live-kernel — run Python code in Jupyter
  • computer-use — control the desktop browser
  • youtube-content — summarize YouTube transcripts

Step 6: Run Your First Task
#

Start an interactive session:

hermes

Try asking it something:

“Search for the latest news about AI and summarize the top 3 stories.”

Hermes Agent will:

  1. Search the web using its browser tool
  2. Read the pages
  3. Summarize the results
  4. Return a clean answer

Step 7: Schedule Cron Jobs
#

Hermes Agent can run tasks on a schedule:

# Schedule a daily briefing
hermes cron create \
  --schedule "0 9 * * *" \
  --prompt "Give me a daily briefing: check my email, calendar, and top news" \
  --channel "telegram:your-chat-id"

This is great for:

  • Daily news briefings
  • GitHub PR status checks
  • Server monitoring alerts
  • Weekly report generation

Step 8: Use the Browser Tool
#

Hermes Agent has a built-in browser that can navigate websites, click buttons, fill forms, and extract content:

# In an interactive session, ask:
"Go to https://example.com and take a screenshot of the homepage"
"Search for affordable flights to Tokyo"
"Fill out this contact form with my details"

The browser tool is powered by Playwright and supports:

  • Page navigation
  • Clicking elements
  • Form filling
  • Screenshots
  • JavaScript execution
  • Console log monitoring

Step 9: Memory and Persistence
#

Hermes Agent remembers information across sessions:

# Save important facts
"Remember that my server IP is 192.168.1.100"

# The agent will persist this information
# and recall it in future sessions

You can also manually save durable facts:

hermes memory add "My preferred model is claude-sonnet-4"
hermes memory list

Step 10: Troubleshooting
#

Gateway won’t start
#

Check if the port is already in use:

lsof -i :8000

API key issues
#

Verify your environment variables:

echo $OPENROUTER_API_KEY
hermes config show

Skills not found
#

Make sure your config file has the correct paths:

hermes config set skills.directory ~/.hermes/skills

Advanced Configuration
#

Custom Models
#

# config.yaml
model:
  provider: openrouter
  name: openrouter/anthropic/claude-sonnet-4
  temperature: 0.7
  max_tokens: 4096

Multiple Profiles
#

# Create a work profile
hermes config set --profile work
# Switch profiles
hermes --profile work

Custom Tools
#

Hermes Agent supports custom tool definitions. Create a Python file with your tool function and register it:

# my_tools.py
from hermes_tools import tool

@tool
def my_custom_function(query: str) -> str:
    """My custom tool description"""
    return f"Result for: {query}"

Conclusion
#

Hermes Agent is a powerful, self-hosted AI assistant that gives you full control over your AI interactions. Whether you’re automating tasks, monitoring servers, or just want a private AI assistant, Hermes Agent delivers:

  • Privacy — your data stays on your server
  • Flexibility — multiple LLM providers, extensible skills
  • Automation — cron jobs, scheduled tasks, workflows
  • Integration — Telegram, Feishu, Discord, CLI

For more information, visit the official documentation or check out the GitHub repository.

Happy automating! 🚀