How to Install and Use Hermes Agent for Free: A Practical Guide

About 8 min

How to Install and Use Hermes Agent for Free: A Practical Guide

Hermes Agent popped up on my radar a few weeks ago, and after digging through the GitHub repo (37.5k stars, MIT license, built by Nous Research), I realized it does something most AI agents don't: it gets better the more you use it. Not in some vague "the model improves" sense — it literally builds skills from your interactions, remembers what worked, and refines those skills over time. That alone makes it worth a look.

The part that sold me: it runs on a $5 VPS. No GPU required unless you want one. And you can connect it to Telegram, Discord, Slack, WhatsApp, and about a dozen other platforms. We recommend using LightNode as your VPS provider — their hourly billing starts at $0.013/hour, which is hard to beat for experimenting with self-hosted AI.

What Hermes Agent Actually Does
System Requirements
Installation
Setting Up a Free Model Provider
Configuration
Running Your First Session
Connecting to Messaging Platforms
Key Features Worth Knowing About
Troubleshooting
Wrapping Up

What Hermes Agent Actually Does

Most AI agents follow the same pattern: you send a prompt, they run some tools, return a result, and forget everything. Hermes Agent takes a different approach. It has a built-in learning loop:

You give it a task
It figures out what skills are needed
If a skill doesn't exist, it creates one
It uses the skill, evaluates the result, and stores what worked
Next time you ask for something similar, it pulls up that refined skill

This means the agent actually improves with use, not just because the underlying model got an update. Your specific workflows, your specific codebase, your specific habits — it learns those patterns.

Beyond the learning loop, Hermes Agent ships with 47 built-in tools, supports MCP (Model Context Protocol) integration for extending capabilities, and can delegate tasks to subagents. It also has a cron scheduler for recurring tasks and a voice mode if you want to go hands-free.

System Requirements

Before installing, make sure your system meets the basics:

OS: Linux (Ubuntu 20.04+ recommended), macOS (12+), or Windows via WSL2
Python: 3.10 or higher
RAM: 2GB minimum, 4GB recommended
Disk: ~500MB for the agent itself
Network: Internet access for model API calls

For Android users, Termux works too. Windows natively isn't supported — you need WSL2.

If you're deploying to a VPS, a $5/month box with 1 vCPU and 1GB RAM handles it fine for light use. Heavier workloads (multiple messaging platforms, frequent cron jobs) benefit from 2GB+.

Installation

There are two ways to install Hermes Agent. The quick way handles everything for you. The manual way gives you more control.

Method 1: One-Line Install (Recommended)

Open your terminal and run:

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

This script does the heavy lifting: checks dependencies, sets up a virtual environment, clones the repo, installs packages, and runs the initial setup wizard. On a fresh Ubuntu box, the whole thing takes about 2-3 minutes.

After it finishes, verify the installation:

hermes --version

You should see the version number printed. If you get a "command not found" error, restart your shell or run source ~/.bashrc (or ~/.zshrc if you use zsh).

Method 2: Manual Install

If you prefer knowing exactly what goes on your machine, or if the one-liner fails for some reason:

# Clone the repo
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the setup wizard
python setup.py

The setup wizard walks you through model provider selection, API key entry, and basic configuration. You can always re-run it later with hermes setup.

Setting Up a Free Model Provider

Hermes Agent doesn't ship its own model. It connects to external providers. Here's the good news: several providers offer free tiers that work with Hermes Agent.

Option 1: OpenRouter (Easiest Free Option)

OpenRouter gives you access to 200+ models, and several of them are free to use. This is the path I'd recommend for getting started.

Create an account at openrouter.ai
Generate an API key from your dashboard
Find free models — look for models tagged "free" in the model catalog

Common free models on OpenRouter include variants of Llama, Mistral, and Qwen. The available free models rotate, so check the current catalog.

During the Hermes Agent setup wizard, select "OpenRouter" as your provider and paste your API key when prompted.

Option 2: Nous Portal

Nous Research runs their own inference portal. It occasionally offers free credits for new users, and the models available there are tuned specifically for agent workloads.

Visit nousresearch.com and sign up
Check your dashboard for any free credit allocations
Use the provided API key in Hermes Agent setup

Option 3: Other Providers

Hermes Agent also supports:

z.ai / GLM: Chinese AI platform with a free tier
Kimi / Moonshot: Another option with limited free usage
MiniMax: Free tier available for light use
Any OpenAI-compatible endpoint: If you have access to other providers, you can plug them in

To configure a custom endpoint, you'll need the base URL and an API key. The setup wizard handles this, or you can edit the config file directly (covered in the next section).

Configuration

Hermes Agent stores its configuration in ~/.hermes/config.toml. After running the setup wizard, you'll find something like this:

[model]
provider = "openrouter"
api_key = "sk-or-v1-..."
model = "meta-llama/llama-3.3-70b-instruct:free"

[agent]
name = "Hermes"
memory = true
skills_dir = "~/.hermes/skills"

[messaging]
# Configure messaging platforms here
# telegram_token = ""
# discord_token = ""

Key Configuration Options

Model settings: Switch models or providers anytime. If you want to try a different free model on OpenRouter, just update the model field. You can also change providers entirely — swap provider to "openai" or "nous" and update the API key accordingly.

Memory: Keep memory = true. This is what enables the learning loop. The agent stores conversation history and skill refinements in ~/.hermes/memory/.

Skills directory: This is where learned skills get saved. You can browse ~/.hermes/skills/ to see what the agent has picked up. Skills are stored as JSON files and can be edited manually if you want to fine-tune them.

Switching Models from CLI

You don't have to edit the config file every time. Hermes Agent has built-in commands for this:

# List available models for your current provider
hermes model list

# Switch to a specific model
hermes model set meta-llama/llama-3.3-70b-instruct:free

# Check what model you're currently using
hermes model show

Health Check

Run this after any configuration change to make sure everything is wired up correctly:

hermes doctor

It checks your API key, model availability, network connectivity, and skill system status. If something's wrong, it tells you exactly what to fix.

Running Your First Session

Once configured, start a session:

hermes chat

This opens an interactive REPL. Try something simple first:

You: What tools do you have available?
Hermes: I have access to 47 built-in tools including:
- file_read / file_write (file operations)
- shell_exec (run shell commands)
- web_search / web_fetch (web access)
- code_search (search codebases)
- calendar / reminders (scheduling)
- ...and more. I can also use MCP tools if configured.

Then give it a real task:

You: Create a Python script that monitors a directory for new files and logs their names to a file called new_files.log

Hermes: I'll create that for you.
[creates watch_dir.py with inotify or polling-based implementation]
[tests the script]
The script is ready at ./watch_dir.py. Run it with python watch_dir.py /path/to/watch

The first time you ask for something, the agent builds the skill from scratch. Ask for a similar task later, and it reuses the refined version. You can see this in action by checking the skills directory after a few sessions.

Connecting to Messaging Platforms

One of Hermes Agent's standout features is platform support. You can talk to it through 15+ messaging platforms, not just the CLI.

Telegram Setup

Message @BotFather on Telegram to create a new bot
Copy the bot token
Add it to your config:

hermes gateway add telegram --token "YOUR_BOT_TOKEN"

Start the gateway:

hermes gateway start telegram

Now you can chat with your agent directly in Telegram. It maintains the same memory and skills as your CLI sessions.

Discord Setup

Create a bot in the Discord Developer Portal
Enable the Message Content Intent
Copy the bot token
Configure:

hermes gateway add discord --token "YOUR_BOT_TOKEN"
hermes gateway start discord

Other Supported Platforms

The same pattern applies to all platforms. Use hermes gateway add <platform> with the required credentials:

Slack: Requires a Slack App with bot scopes
WhatsApp: Uses the WhatsApp Business API or an unofficial bridge
Signal: Requires signal-cli setup
Matrix: Needs a Matrix bot account
Mattermost: Personal access token
Email: IMAP/SMTP credentials
SMS: Twilio or similar provider
DingTalk / Feishu / WeCom: For Chinese messaging platforms

Run hermes gateway list to see all available platforms and their status.

Key Features Worth Knowing About

Skills Hub

Hermes Agent has a community skills repository. Browse and install skills other people have created:

# Browse available community skills
hermes skills browse

# Install a specific skill
hermes skills install web-scraper

# List your installed skills
hermes skills list

This is useful if you don't want to wait for the agent to learn from scratch. Someone has probably already built a skill for common tasks like web scraping, API testing, or document parsing.

Cron Scheduling

Set up recurring tasks without external cron:

hermes cron add "0 9 * * *" "Summarize yesterday's git commits and post to #dev-channel"

The agent handles the scheduling internally and uses its skills to execute the task.

Voice Mode

If you want to go hands-free:

hermes chat --voice

This uses your system microphone and speakers. It works best with models that handle audio input, though it can also use a local speech-to-text layer.

Subagent Delegation

For complex multi-step tasks, Hermes Agent can spin up subagents:

You: Research the top 5 VPS providers, compare their pricing, and create a summary document

Hermes: I'll delegate this to subagents for parallel research.
[spawns subagents for each provider]
[collects results]
[generates comparison document]

Subagents share the parent's memory and skill system, so they benefit from everything the main agent has learned.

Troubleshooting

"command not found: hermes"

The install script adds Hermes to your PATH, but your current shell might not have picked it up. Fix:

source ~/.bashrc  # or ~/.zshrc

If that doesn't work, check if ~/.local/bin/hermes exists and add it to your PATH manually:

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

API Key Errors

Run hermes doctor first. It will tell you if your API key is invalid, expired, or if the model you selected is unavailable. Common fixes:

For OpenRouter: Check your key at openrouter.ai/keys
Free models sometimes have rate limits — try a different free model
Make sure there's no trailing whitespace in your API key

Model Not Responding

Free tier models have usage caps. If you hit one:

hermes model list    # see what's available
hermes model set <different-free-model>  # switch

High Memory Usage

If the agent's memory grows too large (check with du -sh ~/.hermes/memory/), you can prune old entries:

hermes memory prune --older-than 30d

This keeps recent interactions and skills but drops conversation logs older than 30 days.

Gateway Connection Issues

For messaging platforms, make sure the gateway process is running:

hermes gateway status

If a gateway keeps disconnecting, check your network and restart it:

hermes gateway restart telegram

Wrapping Up

Hermes Agent does something I haven't seen other open-source agents pull off well: it actually learns from your usage patterns and gets better over time, without requiring you to manually define workflows or write custom plugins. The skills system is the real differentiator — tasks that take 10 minutes the first time take 30 seconds the fifth time.

The fact that it runs on cheap hardware and connects to free model providers means you can have a personal AI agent running 24/7 for close to zero cost. Hook it up to Telegram or Discord, and you've got an always-available assistant that remembers your preferences, your codebase, and your workflows.

To get started:

Pick a VPS (or use your local machine) — LightNode works well for this
Run the one-line installer
Sign up for OpenRouter and grab a free model
Start chatting

The GitHub repo has detailed documentation, and the community is active if you run into issues. Give it a weekend — by Monday, you'll have an agent that's already started building skills specific to your work.