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.

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:
- Model Provider: Select
ollama,vllm, orcustom_openai. - API Base URL: For local Ollama enter
http://localhost:11434/v1; for vLLM enterhttp://localhost:8000/v1. - Model Identifier: Enter
hermes3(Ollama) orNousResearch/Hermes-3-Llama-3.1-70B-FP8(vLLM). - API Key: Enter
ollamafor 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:
- Message
@BotFatheron Telegram to create a new bot and obtain an API token. - Configure the token in Hermes:
hermes gateway setup telegram --token "YOUR_TELEGRAM_BOT_TOKEN" --whitelist "YOUR_USER_ID" - 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:
- What Is Hermes Agent? Architecture, Nous Research Hermes 3 & Procedural Memory
- 11 Practical Enterprise Use Cases for Hermes Agent
- Hermes Agent vs. OpenClaw Architectural Shootout