How to Set Up Hermes Agent: The Self-Improving AI That Runs 24/7

What is Hermes Agent and why it went viral

Hermes Agent is an open-source autonomous AI agent built by Nous Research, the lab behind the Hermes, Nomos, and Psyche model families. It launched in early 2025, exploded in early 2026 with over 66,000 GitHub stars in under two months, and is now one of the fastest-growing open-source AI projects on GitHub.

Unlike a chatbot or coding copilot, Hermes Agent lives on your own infrastructure. It runs on Linux, macOS, a $5 VPS, or serverless compute like Daytona or Modal. It talks to you through Telegram, Discord, Slack, or WhatsApp. And every session it gets a little smarter: building a persistent memory of your preferences and writing its own skill files from the procedures it learns during complex tasks.

This guide walks you through the full setup from install to first task in about 20 minutes. You will also learn how to connect a Telegram gateway, run a local model with Ollama, and understand how the skills system compounds over time.

How Hermes Agent is different from other AI tools

Most AI tools are stateless. Every conversation starts from zero. You re-explain your project, your preferences, and your stack each time. Hermes Agent is built to solve this.

Compared to other open-source autonomous agents like OpenClaw, Hermes Agent's defining feature is the closed learning loop: the agent does not just use skills you provide, it creates and rewrites its own from experience. Three features make this possible:

• Persistent memory: stored in a SQLite database with full-text search across sessions. Hermes remembers your projects and preferences permanently and you can query memories from weeks ago.
• Self-created skills: after completing a complex task (typically five or more tool calls), Hermes autonomously creates a skill file capturing the procedure, known failure modes, and verification steps. It stores these in ~/.hermes/skills/ and loads them automatically when a similar task appears next time.
• Multi-platform presence: connect to Telegram, Discord, Slack, WhatsApp, Signal, and 15 other platforms from a single gateway process. Swap devices, swap platforms, and the session context stays intact.

Before you start

Confirm your environment meets these requirements before installing. The pip path is fastest for most users. The git installer tracks the main branch and is better if you want the latest commits before they hit a tagged release.

• Python 3.10 or later for the pip install path, or curl and Git for the git installer
• A model provider: Nous Portal (zero-config, free to try), OpenRouter, OpenAI, Anthropic, or any OpenAI-compatible endpoint with at least 64,000 tokens of context
• Linux, macOS, or WSL2 on Windows (native Windows is not supported — install WSL2 first)
• Optional: a Telegram account for the messaging gateway

Install Hermes Agent

Two install paths are available. Use pip for stable tagged releases. Use the git installer if you want the latest commits from the main branch.

Option A: pip install (recommended for most users)

Optionally run postinstall to set up extras like Node.js, a browser driver, ripgrep, and ffmpeg:

Option B: git installer for Linux, macOS, and WSL2. Tracks the main branch for the latest commits:

After either install completes, reload your shell. Use ~/.zshrc on macOS if you run zsh:

Choose your model provider

Hermes Agent works with Nous Portal, OpenRouter, OpenAI, Anthropic Claude, Google Gemini, DeepSeek, and any OpenAI-compatible endpoint. The minimum requirement is a model with at least 64,000 tokens of context, which most modern hosted models easily meet.

Run the interactive model picker to walk through provider selection:

The easiest path is Nous Portal, which gives access to 300+ models and the built-in Tool Gateway (web search, image generation, TTS) in one subscription. Set it up in a single command:

For Anthropic Claude, export your API key then run hermes model to select a Claude model:

For OpenAI:

For OpenRouter, which gives access to 200+ models from a single key:

Connect Telegram for messaging anywhere

The CLI works fine for local use, but the real power of Hermes Agent is reaching it from your phone or any device through a messaging platform. The Hermes Agent Telegram integration is the fastest gateway to configure and takes about five minutes.

Hermes supports Telegram, Discord, Slack, WhatsApp, Signal, and 15 other platforms from a single gateway process. Once configured, your agent holds the same session context across all platforms.

Step 1: Open Telegram and search for @BotFather. Send /newbot, follow the prompts to name your bot, and copy the bot token.

Step 2: Run the gateway setup command and paste your bot token when prompted:

Step 3: Start the gateway:

Open your Telegram bot and send it any message. The agent responds within seconds, using the same session context as the CLI.

Run your first task

Start a conversation from the command line to verify everything is working. This also begins building the agent's memory of your environment and preferences.

A few good first tasks that exercise the agent's built-in tools and start generating Hermes Agent skills:

• Ask it to search the web for a topic and summarize what it finds
• Ask it to create a file, write content into it, and confirm it was saved
• Ask it to list the files in your current directory and describe what each one is for

After five or more tool calls in a session, Hermes will automatically write a skill file from what it learned. View all saved skills with:

How Hermes Agent skills compound over time

Every time Hermes completes a complex task, it creates a skill: a structured Markdown file capturing the procedure, known failure modes, and verification steps. Skills are stored in ~/.hermes/skills/ and loaded automatically at the start of each session when the agent determines they are relevant to the current task.

Skills can self-improve. If the agent discovers a better approach to a procedure it has already captured, it rewrites the skill file. You can read, edit, or delete any skill at any time since they are plain text Markdown files.

Community-contributed skills are available at agentskills.io. Drop any compatible skill file into ~/.hermes/skills/ and it loads automatically the next session, extending what your agent knows how to do without you writing anything.

List all locally saved skill files:

Add a community skill by downloading the .md file from agentskills.io and dropping it into your skills directory:

Run Hermes Agent locally with Ollama

If you want to keep all data on your own machine and avoid sending anything to an external API, use a local model through Ollama. This requires a machine with enough VRAM for the model you choose. An 8B parameter model typically runs on 8GB of VRAM; a 14B model needs 12 to 16GB.

Install Ollama from ollama.ai, then pull a model with a sufficient context window. Qwen 2.5 14B is a strong default for local autonomous agent use:

Hermes needs a large context window to load its system prompt, tool definitions, and memory. Set the context length before starting Ollama:

Point Hermes at the local Ollama endpoint:

Run hermes model to select Ollama as your provider and choose your model name:

Use Docker for a sandboxed execution backend

Hermes Agent supports six execution backends that control where the agent's code and commands actually run. Docker is the recommended backend for most deployments because it runs commands inside a hardened container with dropped capabilities, no privilege escalation, and PID limits.

To switch to the Docker backend, make sure Docker is installed and running on your machine, then set the backend in your Hermes configuration:

The other available backends are: Local (runs directly on the host with no isolation), SSH (executes on a remote server), Daytona and Modal (serverless with near-zero idle cost), and Singularity/Apptainer (for HPC environments where Docker is unavailable).

• Local: simplest, no isolation, fine for testing
• Docker: recommended for most use cases, sandboxed container execution
• SSH: agent runs commands on a remote server over SSH
• Daytona / Modal: serverless, hibernates when idle, low cost between sessions
• Singularity/Apptainer: HPC and research environments

Common errors and how to fix them

• Context length exceeded: Your model does not have a large enough context window. Set OLLAMA_CONTEXT_LENGTH=32768 for local models, or switch to a hosted model with at least 64K context.
• hermes: command not found after install: Run source ~/.bashrc (or source ~/.zshrc on macOS) to reload your shell path without closing the terminal.
• Telegram gateway not responding: Run hermes gateway status to check the process. Restart it with hermes gateway restart.
• API key not recognized on startup: Confirm the key is exported in your current shell session. Keys set only in a .env file will not load unless you source that file explicitly.
• Skills not loading between sessions: Skills must be stored as .md files in ~/.hermes/skills/. Run ls ~/.hermes/skills/ to confirm they are present and readable.

Where to go from here

Once your base setup is working, there is a lot more to explore. A few directions worth prioritizing once you have a clean first conversation running:

• Schedule automated tasks with the built-in cron system: run hermes cron to set up recurring jobs delivered to Telegram or any connected platform
• Connect MCP servers to extend Hermes with external tool capabilities — any MCP-compatible server works out of the box with no custom code
• Deploy on a VPS for 24/7 operation. A 2-core, 4GB RAM server is the recommended minimum and costs $5 to $10 per month from most cloud providers
• Try serverless deployment via Daytona or Modal — the agent hibernates when idle and wakes on demand, keeping costs near zero between sessions
• Browse community skills at agentskills.io and drop useful .md files into ~/.hermes/skills/ to extend what your agent already knows how to do