Hermes Agent Guide

What Hermes Agent is

Hermes Agent is an open-source autonomous agent from Nous Research. It runs in your terminal, connects to 20+ messaging platforms, and works with any major LLM provider. Unlike a chat wrapper, Hermes executes tasks with tools, remembers context across sessions, and can run on a VPS while you talk to it from Telegram or Discord.

Use this guide when you want a personal agent that survives beyond a single browser tab.

Prerequisites

Before installing, confirm:

• OS: Linux, macOS, WSL2, or native Windows
• Git installed
• One provider: Nous Portal OAuth (fastest), OpenRouter, Anthropic, OpenAI, or a local Ollama endpoint
• Optional: A $5–10/month VPS if you want always-on access

Install (5 minutes)

Linux / macOS / WSL2:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Windows (PowerShell):

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Then run the setup wizard:

hermes setup --portal

The portal path handles OAuth, model selection, and Tool Gateway (web search, browser, image gen) in one pass. Prefer full control? Use hermes setup and pick Blank Slate, then enable tools one at a time.

Core configuration checklist

Step	Command	What it does
Pick model	hermes model	Choose provider + default model (128K+ context recommended)
Enable tools	hermes tools	Toggle file ops, terminal, web, browser, cron, skills
Verify health	hermes doctor	Catch missing keys, broken paths, version drift
First chat	hermes	Run a real task — not "hello", ask it to list a folder or summarize a file

Connect messaging (optional)

Once CLI chat works:

hermes gateway setup

Supported channels include Telegram, Discord, Slack, WhatsApp, and Signal. Start with one channel. Pair DMs using the security prompts — do not expose an unauthenticated gateway to the public internet.

Production VPS pattern

1. Spin up Ubuntu 22.04 on any cheap VPS
2. Install Hermes with the curl script
3. Run hermes setup --portal and hermes gateway setup
4. Create a systemd service so Hermes restarts on reboot
5. Lock SSH to keys only; keep the gateway behind pairing

Talk to the agent from your phone while it runs shell commands on the server.

Skills, memory, and cron

• Memory persists facts across sessions (~/.hermes/ by default)
• Skills are reusable procedures the agent writes and reuses
• Cron schedules recurring tasks (daily briefings, repo checks, inbox triage)

Enable these only after your base chat loop is stable. Each layer adds capability and surface area.

Troubleshooting

Symptom	Fix
Model errors	hermes model → re-select provider; check API key or OAuth
Tools fail silently	hermes tools → confirm file/terminal toolsets are on
Gateway won't connect	hermes doctor --fix; verify bot token and firewall
Wrong config file	hermes config path → edit config.yaml directly

First-week playbook

Day 1: Install, verify chat, run one file task
Day 2: Connect Telegram or Discord
Day 3: Enable web search; ask it to research a topic and save notes
Day 4: Create your first skill (e.g., "weekly repo summary")
Day 5: Deploy to VPS if you want always-on access

Quick reference

hermes              # Interactive session
hermes model        # Switch provider/model
hermes tools        # Tool configuration
hermes gateway      # Start messaging bridge
hermes doctor       # Diagnostics
hermes update       # Pull latest release

Hermes is MIT-licensed. Docs: hermes-agent.nousresearch.com