How to Install Hermes Agent on Linux, macOS, or WSL2

Hermes Agent, developed by Nous Research, is an autonomous AI agent framework featuring persistent procedural memory, dynamic skill synthesis, and deep tool execution. Whether deploying on a local developer workstation (macOS/WSL2) or an enterprise Linux GPU server, this guide walks through the complete end-to-end installation, local model configuration (via vLLM or Ollama), Model Context Protocol (MCP) setup, and 24/7 production systemd daemon management.

Step-by-step Hermes Agent installation flow from Git to setup to first chat.
Hermes Agent Production Installation: From system dependencies and model configuration to MCP tools and daemon deployment.

Prerequisites & System Requirements

Before beginning installation, ensure your environment meets the minimum technical specifications:

  • Operating System: Ubuntu 22.04/24.04 LTS, Debian 12, macOS Sonoma/Sequoia (Apple Silicon M1–M4 recommended), or Windows 11 with WSL2 (Ubuntu).
  • Core Dependencies: Git, Python 3.10–3.12, Node.js 18+ (required for running external MCP server adapters), ripgrep, and ffmpeg.
  • Hardware (Local Inference):
    • Hermes 3 8B: 16GB system RAM (macOS) or 8GB–12GB VRAM (NVIDIA RTX 3060/4060).
    • Hermes 3 70B: 48GB VRAM (2× RTX 3090/4090 or cloud A100/H100) using vLLM FP8/AWQ quantization.
  • Hardware (API Mode): Standard VPS with 2 vCPUs and 4GB RAM if routing reasoning through OpenAI-compatible cloud endpoints (OpenRouter, Together AI, or Nous Portal).

Step 1: Install System Dependencies

Install the essential build tools, version control, and runtime utilities for your host OS:

On Ubuntu / Debian / WSL2:

sudo apt-get update && sudo apt-get install -y \
  git curl wget build-essential python3-dev python3-pip python3-venv \
  ripgrep ffmpeg jq nodejs npm

On macOS (via Homebrew):

brew install git curl ripgrep ffmpeg jq node python@3.11 uv

Step 2: Install Hermes Agent

Nous Research provides both an automated one-line installer and a manual Git installation method. For production and developer environments, both methods are fully supported.

Method A: Automated One-Line Installer (Recommended)

The official installation script automatically configures isolated virtual environments using uv, installs system bindings, and registers the global hermes executable:

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

Once complete, reload your shell profile to update your system PATH:

# For Bash users:
source ~/.bashrc

# For Zsh users:
source ~/.zshrc

Method B: Manual Git Clone & Virtualenv Setup

If you are customizing Hermes core modules or running inside restricted enterprise networks, clone the repository directly:

git clone https://github.com/NousResearch/hermes-agent.git ~/hermes-agent
cd ~/hermes-agent

# Create and activate virtual environment with uv or python venv
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.cargo/env
uv venv .venv
source .venv/bin/activate

# Install Hermes Agent and development dependencies
uv pip install -e .

Step 3: Configure Inference Model Backends

Hermes Agent is model-agnostic and connects to any OpenAI-compatible API endpoint. Choose the inference architecture that matches your performance and privacy requirements:

Option 1: 100% Local Inference via Ollama (Zero API Costs)

For privacy-conscious local development without API billing, install Ollama and pull the official Nous Hermes 3 model weights:

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

# Pull Hermes 3 8B (fits in 8GB–16GB RAM)
ollama pull hermes3

# Or pull Hermes 3 70B (requires ~40GB+ RAM/VRAM)
ollama pull hermes3:70b

Option 2: High-Performance Production Inference via vLLM

For multi-user teams and high-throughput server deployments with dedicated NVIDIA GPUs, deploy vLLM with Hermes 3 70B FP8:

# Run vLLM with Hermes 3 70B using FP8 quantization on 2x RTX 4090 or A100
python3 -m vllm.entrypoints.openai.api_server \
  --model NousResearch/Hermes-3-Llama-3.1-70B-FP8 \
  --host 0.0.0.0 \
  --port 8000 \
  --tensor-parallel-size 2 \
  --max-model-len 16384 \
  --enable-auto-tool-choice \
  --tool-call-parser hermes

Option 3: Cloud Hosted Endpoints (OpenRouter / Together AI)

If running on lightweight VPS instances without local GPUs, obtain an API key from OpenRouter or Together AI. Hermes 3 70B and 405B endpoints are natively supported.

Step 4: Run Initial Setup & Verification

Execute the interactive setup wizard to establish configuration files at ~/.hermes/config.yaml:

hermes setup

The configuration prompt asks for:

  1. Model Provider: Select ollama, vllm, or custom_openai.
  2. API Base URL: For local Ollama enter http://localhost:11434/v1; for vLLM enter http://localhost:8000/v1.
  3. Model Identifier: Enter hermes3 (Ollama) or NousResearch/Hermes-3-Llama-3.1-70B-FP8 (vLLM).
  4. API Key: Enter ollama for local instances, or paste your cloud API secret key.

Verify that your setup is operational by running the diagnostic check:

hermes doctor

Launch an interactive terminal session to test basic reasoning and tool execution:

hermes
hermes> List all running Docker containers and check disk usage on /var/log.

Hermes should formulate a plan, call system utilities via subshell, and present a structured summary.

Step 5: Connect Model Context Protocol (MCP) Servers

Hermes Agent natively integrates with the open Model Context Protocol (MCP) standard. Configure external tools by editing ~/.hermes/mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/var/www", "/opt/data"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:secret@localhost:5432/production"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_yourProductionTokenHere"
      }
    }
  }
}

Reload tools in your active session:

hermes tools reload

Step 6: Deploy Multi-Channel Messaging Gateways

Hermes Agent functions as a 24/7 collaborative assistant by connecting to team messaging platforms:

Telegram Bot Gateway:

  1. Message @BotFather on Telegram to create a new bot and obtain an API token.
  2. Configure the token in Hermes:
    hermes gateway setup telegram --token "YOUR_TELEGRAM_BOT_TOKEN" --whitelist "YOUR_USER_ID"
  3. Start the gateway daemon:
    hermes gateway start telegram

Discord Gateway:

Create a bot application in the Discord Developer Portal, enable Message Content Intent, and bind it to Hermes:

hermes gateway setup discord --token "YOUR_DISCORD_BOT_TOKEN" --channels "ops-automation,ai-support"
hermes gateway start discord

Step 7: Production Daemon Setup with Systemd

For enterprise deployments on Linux servers, run Hermes Agent as a background systemd service to ensure automated restarts after server reboots or unexpected process termination:

Create the service file at /etc/systemd/system/hermes-agent.service:

[Unit]
Description=Hermes Autonomous Agent Daemon
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu
ExecStart=/home/ubuntu/.local/bin/hermes gateway start --all
Restart=always
RestartSec=10
Environment="PATH=/home/ubuntu/.local/bin:/usr/local/bin:/usr/bin:/bin"
EnvironmentFile=/home/ubuntu/.hermes/.env
StandardOutput=append:/var/log/hermes-agent.log
StandardError=append:/var/log/hermes-agent.error.log

[Install]
WantedBy=multi-user.target

Enable and activate the service:

sudo systemctl daemon-reload
sudo systemctl enable hermes-agent
sudo systemctl start hermes-agent
sudo systemctl status hermes-agent

Troubleshooting Common Installation Issues

Symptom / Error Root Cause Resolution
command not found: hermes Global path not exported in shell profile. Add export PATH="$HOME/.local/bin:$PATH" to ~/.bashrc or ~/.zshrc, then reload with source ~/.bashrc.
CUDA out of memory Model context length or batch size exceeds GPU VRAM. Reduce --max-model-len in vLLM (e.g., from 32768 to 16384) or enable 8-bit / 4-bit KV cache quantization.
Failed to connect to MCP server Node.js version mismatch or missing NPX package permissions. Ensure Node.js 18+ is installed (node -v) and execute the NPX package manually once to accept package downloads.
Connection refused (11434) Ollama service is not running locally. Start Ollama in the background via ollama serve or sudo systemctl start ollama.

Next Steps & Related Guides

Now that your Hermes Agent is installed and operational, explore its architectural advantages and real-world deployment patterns:

Primary Documentation & Upstream Repositories