How to Install and Set Up Hermes Agent: Step-by-Step Guide

Hermes Agent installs in under two minutes with a single terminal command on Linux, macOS, or WSL2. As of April 2026, the open-source agent from Nous Research has accumulated over 33,000 GitHub stars and ships with persistent memory, a self-improving skills system, and support for 200+ LLM models through providers like OpenRouter, Anthropic, and OpenAI. This guide covers both the one-line installer and Docker deployment, walks through API key configuration, and gets you to your first conversation.

Prerequisites and System Requirements

Hermes Agent requires only Git as a manual prerequisite — the installer handles everything else. The install script detects your operating system, downloads uv (a fast Python package manager), provisions Python 3.11 without touching your system Python, clones the repository with submodules, installs all dependencies into an isolated virtual environment, and adds the hermes CLI to your PATH.

Supported platforms as of the v0.7.0 release (April 2026):

For VPS deployments, 4GB RAM is the minimum. The official documentation recommends 8GB for comfortable headroom when running gateway services, background memory writes, and browser automation simultaneously.

For a broader comparison of where Hermes Agent fits among AI agent frameworks, see our AI agent frameworks comparison.

Method 1: One-Line Installer

The one-line installer is the fastest path from zero to a working Hermes Agent instance. It completes in under two minutes on most machines with a reasonable internet connection.

Open your terminal and run:

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

The script performs these steps automatically:

1. Downloads and installs uv (Python package manager)
2. Provisions Python 3.11 in an isolated environment
3. Clones the Hermes Agent repository with all submodules
4. Installs dependencies into a virtual environment
5. Creates the hermes CLI command and adds it to your PATH

After installation completes, run the setup wizard:

hermes setup

The wizard walks through model provider selection, API key entry, tool configuration, and gateway setup. Each step can also be run independently later using hermes model, hermes tools, or hermes gateway.

If you want to learn more about what Hermes Agent is before installing, read our explainer on Hermes Agent.

Method 2: Docker Installation

Docker deployment provides a sandboxed environment that isolates Hermes Agent from your host system. This is the recommended approach for VPS deployments and production gateway setups.

Prerequisites for Docker

You need Docker Desktop (macOS/Windows) or Docker Engine (Linux) installed and running. On Linux:

sudo apt install docker.io
sudo usermod -aG docker $USER

Interactive Setup

Create a persistent data directory and run the setup wizard inside the container:

mkdir -p ~/.hermes
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  --shm-size=1g \
  nousresearch/hermes-agent:latest setup

The --shm-size=1g flag is required because Playwright (used for browser automation) needs shared memory.

Docker Compose for Persistent Gateway

For a persistent deployment that restarts automatically, create a docker-compose.yaml:

version: "3.8"
services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    volumes:
      - ~/.hermes:/opt/data
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"

Start with docker compose up -d and view logs with docker compose logs -f hermes.

Verify the volume mount is correct. Without the ~/.hermes:/opt/data mount, data inside the container is ephemeral and lost on restart — including your memory files and configuration.

API Key and Model Configuration

Hermes Agent requires exactly one LLM provider configured to function. As of April 2026, the agent supports over a dozen providers natively, with OpenRouter being the most flexible option since it provides access to 200+ models through a single API key.

Supported Providers

API keys are stored securely in ~/.hermes/.env. You can switch providers at any time using hermes model to open the interactive model selector, or set keys directly with the config commands above.

Choosing a Model

For general-purpose agent tasks, Claude Sonnet or GPT-4.1 through OpenRouter provide strong results. For budget-conscious setups, DeepSeek or local models via Ollama keep costs near zero. The model choice affects both capability and per-message cost — see our best AI agents for small business guide for cost-focused recommendations.

First Run and Verification

After installation and API key setup, launch Hermes Agent with a simple command to verify everything works.

hermes

You should see a welcome banner displaying your active model, available tools, and installed skills. Type a message and press Enter to start your first conversation.

Verifying the Installation

Run these commands to confirm each component is working:

# Check version
hermes --version

# Verify model connection
hermes chat -q "What model are you running on?"

# List available tools
hermes tools

# Check installed skills
hermes chat --toolsets skills -q "What skills do you have?"

If the model responds and tools are listed, your installation is complete. The agent will automatically create its initial memory files (MEMORY.md and USER.md) after your first few conversations as it begins learning about you.

Limitations and Tradeoffs

Hermes Agent has several constraints worth understanding before committing to a deployment.

• No native Windows support. You must use WSL2 or Docker on Windows machines. This adds a layer of complexity for Windows-only teams.
• API cost responsibility. Hermes Agent is free and open source (MIT license), but you pay for LLM API calls directly. Costs depend entirely on your chosen provider and model. There is no built-in cost cap or spending limit.
• Memory size limits. Built-in local memory is bounded — approximately 2,200 characters for agent notes and 1,375 characters for user profile. For deeper memory, you need the Honcho integration or another external memory provider.
• Single external memory provider. Only one external memory provider can be active at a time alongside built-in memory. You cannot stack multiple providers.
• Learning curve for skills. While basic chat works immediately, the skills system, gateway configuration, and memory tuning require reading the documentation to use effectively.

If you are comparing Hermes Agent against other options, our OpenClaw vs Hermes Agent comparison covers the architectural differences in detail.

Related Guides

• What Is Hermes Agent?
• OpenClaw vs Hermes Agent
• AI Agent Frameworks Compared (2026)
• How to Build an AI Agent from Scratch

Frequently Asked Questions

What are the system requirements for Hermes Agent?

Hermes Agent requires Git as the only prerequisite. The installer handles Python 3.11, dependencies, and PATH configuration automatically. It runs on Linux, macOS, and WSL2. Native Windows is not supported — use WSL2 instead. For Docker installs, you need Docker Desktop or Docker Engine running. A VPS with 4GB RAM works, though 8GB is recommended for comfortable headroom with gateway services and browser automation.

Can I run Hermes Agent with a free LLM?

Yes. Hermes Agent supports free model providers including Ollama for local models, Copilot (if you have a GitHub Copilot subscription), and some providers offer free tiers. OpenRouter also provides access to several free models. However, for reliable agent performance, a paid API key from Anthropic, OpenAI, or OpenRouter with a funded account is recommended.

How do I update Hermes Agent to the latest version?

Run hermes update from the terminal. This pulls the latest release, updates dependencies, and preserves your configuration and memory files. For Docker installs, pull the latest image with docker pull nousresearch/hermes-agent:latest and restart the container.

Does Hermes Agent work on Windows?

Hermes Agent does not run natively on Windows. Install WSL2 (Windows Subsystem for Linux) first, then run the standard Linux installer inside WSL2. The Docker installation method also works on Windows through Docker Desktop with WSL2 backend enabled.

What is the difference between hermes setup and hermes model?

hermes setup runs the full setup wizard that walks through all configuration including model provider, API keys, tools, and gateway setup. hermes model is a focused command that only lets you switch your LLM provider and model selection without touching other settings. Use hermes setup for first-time configuration and hermes model when you just want to change models later.