How to Set Up Hermes Agent: Complete Tutorial (2026)

Setting up Hermes Agent took me from zero to a fully automated publishing pipeline in one evening. This guide walks through every command and config file I used — no skipped steps, no “left as an exercise for the reader”.

By the end, you’ll have Hermes running on your machine, connected to local and cloud AI models, and ready to automate real tasks.

What You’ll Need

• Computer — Linux (WSL2 on Windows works), macOS, or any modern Linux distro
• GPU — Optional, but recommended for local models (NVIDIA with 8GB+ VRAM)
• Internet — Required for cloud models and tool connections
• Time — About 30 minutes for core setup

Step 1: Install Docker and Docker Compose

Hermes Agent runs in Docker containers for isolation. If you don’t have Docker yet:

# Linux (Ubuntu/Debian)
sudo apt update
sudo apt install docker.io docker-compose-plugin
sudo usermod -aG docker $USER
newgrp docker

# Verify
docker --version
docker compose version

On Windows, install Docker Desktop with WSL2 backend — this gives you both Docker and a Linux terminal.

Step 2: Clone and Configure Hermes

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

# Copy the example config
cp config.example.yaml config.yaml

Open config.yaml in your editor. Here’s a minimal working config:

# config.yaml — minimal setup
provider: openrouter          # Default AI provider

models:
  main: google/gemma-4-31b-it:free    # Free tier model
  # Add paid models later for better quality

tools:
  - terminal          # Run shell commands
  - web               # Web search and browsing
  - file              # Read and write files
  - search             # Search the web
  - code_exec          # Execute Python code

memory:
  enabled: true       # Persistent memory between sessions
  max_size: 3000       # Characters (auto-prunes oldest entries)

skills:
  auto_save: true      # Automatically create skills from tasks

Step 3: Set Up AI Models

You have two options for AI models — local (free) or cloud (better quality).

Option A: Local Models with Ollama (Free)

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a small fast model
ollama pull gemma3:4b

# Pull a larger model when you need quality
ollama pull qwen3:14b

# Start Ollama
ollama serve

Then in your Hermes config, set the provider to ollama-local.

Option B: Cloud Models with OpenRouter (Free Tier Available)

OpenRouter gives you access to dozens of models, including a generous free tier:

1. Go to openrouter.ai and create an account
2. Go to Keys → Create a new key
3. Copy the key
4. Add it to your Hermes config:

# In config.yaml
providers:
  openrouter:
    api_key: "sk-or-v1-your-key-here"
    models:
      - google/gemma-4-31b-it:free    # Free, fast
      - qwen/qwen3-coder:free          # Free, good for code
      - deepseek/deepseek-r1:free     # Free, strong reasoning

Pro tip: Start with free models. Upgrade to paid ones (Claude, GPT-4) only when you need them. Hermes routes tasks to the right model automatically.

Step 4: Start Hermes

# Start the agent
hermes start

# Or if running from source
python -m hermes

You’ll see a greeting message and a prompt. That’s it — Hermes is running.

Step 5: Your First Task

Try something simple to verify everything works:

You: What tools do you have available?

Hermes: I have the following tools available:
- terminal: Run shell commands
- web: Search and browse the internet
- file: Read, write, and edit files
- search: Web search via SearXNG
- code_exec: Execute Python code
...

Now try a real task:

You: Search the web for the latest news about AI agents and summarize the top 3 stories.

Hermes: [searches web, reads articles, summarizes]

Congratulations — you have a working AI agent that can search, read, and synthesize information.

Step 6: Teach Hermes Your Preferences

This is where Hermes becomes different from every other AI tool. Tell it your preferences and it reminds itself next session:

You: Remember that I prefer concise responses without markdown formatting.

Hermes: Saved to memory: "User prefers concise responses without markdown formatting"

You: I'm in Serbia. My timezone is UTC+2.

Hermes: Saved to memory: "User is in Serbia, timezone UTC+2"

Next time you start Hermes, it loads these preferences automatically. No re-explaining.

Step 7: Build Your First Skill

When Hermes completes a complex task, it can save the entire procedure as a skill. Next time, it follows the proven steps instead of figuring it out from scratch.

You: Research "AI agent automation" keywords, find the top 10 by search volume, and save them to a database.

Hermes: [completes task using search, API calls, and database]

Hermes: This task involved keyword research, API calls, and database storage. 
Would you like me to save this as a skill for future use?

You: Yes, save it as "keyword-research"

Hermes: Skill saved: seo-keyword-research
Next time you say "research keywords for X", I'll follow this proven workflow.

Skills are stored in ~/.hermes/skills/ as markdown files. You can edit them manually, share them, or let Hermes improve them over time.

Step 8: Connect External Tools (Optional)

Hermes gets powerful when connected to your existing tools. Here are the most useful integrations:

n8n (Workflow Automation)

# Add to config.yaml
tools:
  - n8n:
      base_url: "http://localhost:5678"
      api_key: "your-n8n-api-key"

This lets Hermes trigger n8n workflows, create new automations, and chain actions across services.

ComfyUI (Image Generation)

# ComfyUI connects via API
tools:
  - comfyui:
      base_url: "http://localhost:8188"
      default_model: "Juggernaut-XL_v9"

Hermes can generate images for blog posts, social media, or digital products — directly from your prompts.

PostgreSQL (Database)

# For keyword research, content tracking, analytics
tools:
  - postgres:
      host: "localhost"
      port: 5432
      database: "seo_research"
      user: "hermes"
      password: "your-password"

Store and query data without leaving the conversation.

Step 9: Set Up Cron Jobs for Automation

Hermes can run tasks on a schedule — daily keyword research, weekly content audits, hourly server monitoring:

You: Set up a cron job that checks my Docker containers every 30 minutes and alerts me if any are down.

Hermes: Created cron job:
- Schedule: every 30 minutes
- Task: Check Docker container health, alert via Telegram if any container is not running
- ID: docker-monitor

Cron jobs run in the background, even when you’re not chatting with Hermes. Results are delivered to your preferred channel (Telegram, Discord, email).

Step 10: The $0 Budget Stack (What I Actually Use)

Here’s the exact stack I use to run this entire website with zero monthly costs:

Component	Tool	Cost
AI Agent	Hermes Agent	Free (open source)
Content AI	OpenRouter free tier	$0/mo
Image Generation	ComfyUI + SDXL (local RTX 3090)	$0/mo
Workflow Automation	n8n (self-hosted Docker)	$0/mo
Website	WordPress on Spaceship	€3.49/mo hosting
Database	PostgreSQL (Docker)	$0/mo
Keyword Research	RapidAPI free tier	$0/mo
Image Optimization	Pillow + WebP conversion	$0/mo
Total		€3.49/mo

The only real cost is domain hosting. Everything else is free and self-hosted.

Common Issues and Fixes

“Docker permission denied”

sudo usermod -aG docker $USER
# Log out and back in

“Ollama model not found”

ollama pull gemma3:4b
# Make sure ollama serve is running

“OpenRouter 429 rate limit”

You hit the free tier limit. Wait 60 seconds, or upgrade to a paid model ($0.01-0.03 per request).

“Hermes doesn’t remember my preferences”

Check that memory: enabled: true is in your config.yaml. Memory is stored in ~/.hermes/memory/.

“Skills not saving”

Skills are auto-saved for tasks with 5+ tool calls. For simpler tasks, explicitly ask: “Save this as a skill named X”.

What’s Next?

Once Hermes is running, here’s what to try:

1. Content pipeline — Have Hermes research keywords, generate images, and publish to WordPress
2. Server monitoring — Set up cron jobs to watch Docker containers and alert you
3. Digital products — Generate ComfyUI workflows, package them, and list on Gumroad
4. Client websites — Use saved skills to build websites faster each time

Read our comparison of the best AI agents in 2026 to see how Hermes stacks up against alternatives.

Frequently Asked Questions

Can I run Hermes without a GPU?

Yes. Use cloud models only (OpenRouter, Anthropic, OpenAI). The agent itself needs minimal RAM. You only need a GPU for local models via Ollama.

Is Hermes Agent really free?

The agent is 100% free and open-source (MIT license). Cloud AI models have free tiers with rate limits. Local models via Ollama are completely free with no limits.

How is Hermes different from ChatGPT?

ChatGPT is a chatbot — it forgets everything after each conversation. Hermes is an agent that takes actions (terminal, web, files, APIs), remembers your preferences, and builds skills from experience. It’s an employee that improves over time, not a calculator that resets.

Can I use Hermes for my business?

Yes. The MIT license allows commercial use. Many businesses use Hermes for content creation, web development, SEO, and DevOps monitoring.

What if something goes wrong?

Hermes has a built-in diagnostic system. Run hermes doctor to check your setup. The community is active on GitHub for support.

Does Hermes work offline?

With local models (Ollama), yes — fully offline. With cloud models (OpenRouter), you need internet. You can mix both: local for simple tasks, cloud for complex reasoning.

Disclosure: This tutorial is written and published using Hermes Agent’s own pipeline — AI content (OpenRouter), AI images (ComfyUI SDXL), and automated publishing (n8n to WordPress). We use the exact stack described in Step 10.