How to Install Hermes Agent with Ollama Local Models (2026)

What Hermes Agent Does and Why Local Models Make Sense

Hermes Agent (GitHub: NousResearch/hermes-agent, MIT license) is an autonomous AI agent that runs as a persistent process on your machine. Instead of answering one question at a time, it executes multi-step tasks: browsing the web, running terminal commands, reading and writing files, sending messages through connected platforms, and scheduling recurring automations in natural language.

The core architectural components:

• SOUL.md: A Markdown file at `~/.hermes/SOUL.md` that stores your identity and preferences. Loaded at every session startup as the primary agent context.
• memories/ directory: Fact-based memories at `~/.hermes/memories/` extracted automatically from sessions and retrieved by relevance.
• skills/ directory: Step-by-step procedures the agent writes for itself and reuses across sessions.
• Gateway: Connections to Telegram, Discord, Slack, WhatsApp, Signal, and Email for remote task submission.

Why replace the cloud API with Ollama:

For tasks involving sensitive data or sustained personal automation, local Ollama inference costs nothing beyond electricity and keeps every token on your own hardware. A well-configured 27B model like Qwen3.5 handles most agent workloads that previously required GPT-4o.

Compared to OpenClaw: OpenClaw has a web dashboard UI and a larger third-party skill marketplace (molthub). Hermes supports Docker, SSH, and cloud sandbox terminal backends, which makes it more predictable for technical developer workflows where the execution environment matters.

Install Ollama and Configure the 64K Context Window

Most Hermes + Ollama setups fail at the context window. Ollama defaults to 4,096 tokens. Hermes requires 64,000. The gap makes the agent behave erratically after the first few tool calls, and the symptom looks like a model quality problem rather than a configuration one. Fix this before anything else.

Install Ollama

# Linux and macOS — one-command installer
curl -fsSL https://ollama.com/install.sh | sh

Verify the installation:

ollama --version
# Expected: ollama version 0.6.x

On Linux, Ollama installs as a systemd service and starts automatically. Confirm it is running:

systemctl status ollama
# Expected: active (running)

Choose a Model for Hermes Agent

Hermes Agent's tool-calling and multi-step reasoning require a model with reliable function-calling support and a minimum 64K context window. These models work well:

Pull your chosen model. Qwen3 8B is the recommended starting point for most machines:

ollama pull qwen3:8b

# Expected output:
# pulling manifest
# pulling e...  100% ████████ 5.2 GB / 5.2 GB
# success

Also check the best local LLM models guide for a full hardware-to-model matching table.

Set the Context Window to 64K (Required)

Hermes Agent requires at least 64,000 tokens of context. Ollama defaults to 4,096. You must change this before running Hermes, or it will behave erratically after the first 3-4 tool calls.

Choose one of these three approaches:

**Option 1: Environment variable (simplest, current terminal session)**

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

**Option 2: Systemd service override (persists across reboots on Linux)**

# Open the systemd override editor
sudo systemctl edit ollama.service

In the editor that opens, add:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

Save and reload:

sudo systemctl daemon-reload && sudo systemctl restart ollama

**Option 3: Per-model Modelfile (most explicit, controls a single named model)**

# Create a Modelfile setting 64K context for qwen3:8b
cat > Modelfile << 'EOF'
FROM qwen3:8b
PARAMETER num_ctx 64000
EOF

# Build the modified model under a new name
ollama create qwen3-8b-64k -f Modelfile

# Expected output:
# transferring model data
# using existing layer sha256...
# creating new layer sha256...
# writing manifest
# success

Verify the context length is active:

ollama run qwen3:8b --num_ctx 64000 "reply with just: OK"
ollama ps
# Check the CONTEXT column — should show 64000

Install Hermes Agent

Hermes Agent installs via a one-command script that handles all dependencies: Python 3.11 (via uv), Node.js v22, ripgrep, ffmpeg, and Playwright for browser automation. Git is the only prerequisite you need to install manually.

Linux, macOS, and Windows WSL2

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

The script takes 2-5 minutes on a 100 Mbps connection. After it finishes, reload your shell:

# Linux (bash)
source ~/.bashrc

# macOS (zsh)
source ~/.zshrc

Verify the installation:

hermes --version
# Expected: hermes-agent X.X.X

Alternative: pip install

pip install hermes-agent

# Install optional system dependencies (Node.js, ripgrep, ffmpeg, Playwright)
hermes postinstall

Windows Native PowerShell (Early Beta)

iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)

The Windows installer downloads a portable Git distribution and installs Hermes to `%LOCALAPPDATA%\hermes\hermes-agent`. No admin rights required. This path is in early beta as of v0.14.0. WSL2 provides a more stable experience on Windows.

Run the Diagnostic Check

After installation, confirm all components are present:

hermes doctor

# Expected output:
# ✓ Python 3.11.x
# ✓ Node.js v22.x.x
# ✓ ripgrep x.x.x
# ✓ ffmpeg x.x.x
# ✓ playwright chromium
# ✓ hermes-agent x.x.x

Any failed checks appear with an X and a suggested fix command. Run `hermes postinstall` if any optional dependencies are missing.

Configure Hermes Agent to Use Ollama

With Ollama running at 64K context and Hermes installed, point Hermes at the local endpoint.

Interactive Setup (Recommended)

hermes model

The interactive menu asks for your provider. Select:

1. "Custom endpoint (self-hosted / VLLM / etc.)" 2. Enter URL: `http://localhost:11434/v1` 3. API key: press Enter to skip (Ollama requires no key) 4. Model name: type the exact name shown in `ollama list`, for example `qwen3:8b` or `qwen3-8b-64k` if you used the Modelfile method

Hermes writes these values to `~/.hermes/config.yaml` automatically.

Manual Configuration via config.yaml

Open the config file directly:

hermes config edit

Set these values under the `model` key:

model:
  default: qwen3:8b
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 64000

Windows WSL2: Fix the Localhost Issue

If Ollama runs on your Windows host and Hermes runs inside WSL2, `localhost:11434` inside WSL2 refers to the WSL2 container, not your Windows machine. Two steps to fix this:

**Step 1: Tell Ollama on Windows to listen on all interfaces**

# Run in Windows PowerShell before starting Ollama
$env:OLLAMA_HOST = "0.0.0.0"
ollama serve

**Step 2: Find your Windows host IP from inside WSL2**

# Inside your WSL2 terminal
cat /etc/resolv.conf | grep nameserver
# The IP shown (e.g., 172.29.192.1) is your Windows host IP

**Step 3: Use that IP as the base URL in config.yaml**

model:
  base_url: http://172.29.192.1:11434/v1

This is the same networking issue that affects OpenClaw and AnythingLLM Docker setups. Any tool running in an isolated environment needs the actual host IP rather than `localhost`.

First Run and Verification

Start Hermes Agent:

# Standard CLI interface
hermes

# Modern TUI interface (recommended — shows tool activity in real time)
hermes --tui

The startup banner confirms the model and context configuration:

  _    _
 | |  | |  ___ _ __ _ __ ___   ___  ___
 | |__| |/ _ \ '__| '_ ` _ \ / _ \/ __|
 |  __  |  __/ |  | | | | | |  __/\__ \
 |_|  |_|\___|_|  |_| |_| |_|\___||___/

Model: qwen3:8b (custom endpoint)
Context: 64000 tokens
Tools: terminal, browser, file, web_search

Test with a task that uses the terminal tool:

List the 5 largest files in my home directory by size

Hermes calls the terminal tool to run `find ~ -maxdepth 1 -type f -printf '%s %f\n' | sort -rn | head -5`, shows the command for approval (in manual mode), and returns the results. If you see a tool call followed by real output, the Ollama connection is working.

Test a multi-step task to verify the 64K context holds:

Search the web for the latest Qwen3 benchmark results, summarise the findings in 3 bullet points, and save them to a file called qwen3-notes.txt in my home directory

This task requires web browsing, reasoning, and file writing across multiple turns. If Hermes completes it without a context overflow error, the 64,000-token configuration is correct.

Manage Long Sessions with /compress

Hermes auto-compresses the context when it reaches 50% of the 64K limit (around 32,000 tokens). Trigger it manually in long sessions:

/compress

This summarises the session history into a compact representation while keeping the last 20 messages intact. On a 64K context window with Qwen3 8B, a multi-hour coding or research session stays within limits with one or two manual compress calls.

Configure SOUL.md: The Agent Identity File

SOUL.md is stored at `~/.hermes/SOUL.md`. Hermes reads it at every startup as its primary identity context, the first slot in the system prompt. It tells the agent who you are, your working preferences, timezone, active projects, and any standing instructions.

Open it for editing:

# Open via Hermes command
hermes config edit soul

# Or edit directly
nano ~/.hermes/SOUL.md

Add your context in plain Markdown:

# Identity

My name is [Your name]. I work as a [role] in [timezone].

## Working Preferences

- Prefer concise output unless asked for detail
- When writing code, use Python 3.11+ syntax and type hints
- Default file format: Markdown
- Primary OS: Ubuntu 22.04

## Active Projects

- [List current projects so Hermes maintains context across sessions]

## Recurring Tasks

- Daily morning brief: weekdays at 9 AM
- Weekly report: Fridays before 4 PM

## Directories and Paths

- Projects: ~/projects/
- Notes: ~/notes/
- Downloads: ~/Downloads/

Hermes also writes to SOUL.md and the separate `~/.hermes/memories/` folder automatically as it learns your patterns across sessions. The memory system maintains two separate stores:

You do not need to update SOUL.md manually beyond the initial setup. But providing your name, timezone, and key preferences at the start saves several sessions of inference time compared to waiting for the agent to infer your context automatically.

Connect Hermes to Telegram or Discord (Optional)

The Hermes gateway connects the running agent to Telegram, Discord, Slack, WhatsApp, Signal, or Email. You send tasks from your phone without opening a terminal, and the agent can message you with updates or task completions while it works.

Run the gateway setup wizard:

hermes gateway setup

The wizard walks through your chosen platform. For Telegram, you need a bot token from @BotFather.

Set Up a Telegram Gateway

1. Open Telegram and search for @BotFather 2. Send `/newbot`, follow the prompts, and copy the token 3. Run `hermes gateway setup` and select Telegram 4. Paste your token when prompted

Test the gateway in the foreground:

hermes gateway run

Send a message to your bot. Hermes responds using the same local Ollama model. To run the gateway persistently:

# Using tmux (recommended over systemd on WSL2)
tmux new-session -d -s hermes-gateway 'hermes gateway run'

# Check gateway status
tmux attach -t hermes-gateway

On a Linux server with working systemd:

sudo systemctl enable --now hermes-gateway
sudo journalctl -fu hermes-gateway  # view live logs

Check gateway status at any time:

hermes gateway status

Configuration Reference

All Hermes settings live in `~/.hermes/config.yaml`. Secrets and API keys go in `~/.hermes/.env`. The most relevant settings for an Ollama-backed setup:

Set values via CLI without opening config.yaml:

# Switch terminal commands to run inside Docker containers
hermes config set terminal.backend docker

# Show model reasoning traces (useful when debugging Qwen3 thinking mode)
hermes config set display.show_reasoning true

# Extend streaming timeout for slower models or CPU-only inference
hermes config set HERMES_STREAM_READ_TIMEOUT 1800

# Enable smart approval mode for less interruption
hermes config set approvals.mode smart

Install and Manage Skills

Hermes ships with 70+ built-in skills (capabilities for file management, web search, Python scripting, image generation, and more). Search and install additional community skills:

# Search available skills
hermes skills search web

# List installed skills
hermes skills list

# Install a skill
hermes skills install web-scraper

Skills are stored in `~/.hermes/skills/` and persist across updates.

Update Hermes Agent

# pip install method
pip install --upgrade hermes-agent

# curl install method — re-run the installer
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Your `~/.hermes/` directory (config.yaml, SOUL.md, memories, and skills) is never modified by an update.

Troubleshooting

Frequently Asked Questions

pip install --upgrade hermes-agent

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

tmux new-session -d -s hermes 'hermes gateway run'

sudo systemctl enable --now hermes-gateway