Hermes Agent: Installation Deep Dive and Optimization

What the Installer Actually Does

Hermes Agent provides a one-liner installer:

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

But what does that script actually do? After reading through all 1,133 lines, here’s the execution order:

1. OS detection — identifies Linux, macOS, or Windows (bails on native Windows, recommends WSL2)
2. Installs uv — the fast Python package manager from Astral, if not already present
3. Ensures Python 3.11 — downloads and manages it via uv (no system Python needed)
4. Checks for Git — exits with distro-specific install instructions if missing
5. Installs Node.js 22 — downloads the binary to ~/.hermes/node/ and symlinks to ~/.local/bin/
6. Installs system packages — ripgrep (fast search) and ffmpeg (TTS audio), using apt/brew/pacman or cargo as fallback
7. Clones the repo — tries SSH first, falls back to HTTPS, to ~/.hermes/hermes-agent/. If already cloned, runs git pull (stashing local changes with a restore prompt)
8. Creates a Python venv — via uv venv with Python 3.11
9. Installs Python dependencies — uv pip install -e ".[all]" with fallback to base install
10. Installs Node.js dependencies — npm install + Playwright Chromium, plus WhatsApp bridge deps
11. Sets up the hermes CLI — symlinks the venv entry point to ~/.local/bin/hermes and adds it to PATH in shell config
12. Creates config — copies .env and config.yaml templates to ~/.hermes/, creates SOUL.md persona file, syncs bundled skills
13. Runs setup wizard — interactive hermes setup for API key configuration
14. Optionally starts the gateway — if a messaging token is configured, offers to install as a systemd service or background process

The script is well-designed for curl | bash piping — it reads interactive prompts from /dev/tty instead of stdin, so non-interactive mode works without hanging.

PyTorch CPU-Only Optimization

By default, uv pip install -e ".[all]" pulls in the full PyTorch build with CUDA support — which is unnecessary if you’re running on CPU or using an API-based LLM provider. The full CUDA build is several gigabytes larger.

I modified the installer to use the CPU-only PyTorch wheels by adding --extra-index-url https://download.pytorch.org/whl/cpu:

1
uv pip install --index-strategy unsafe-best-match \
2
  --extra-index-url https://download.pytorch.org/whl/cpu \
3
  -e ".[all]"

1
hint: `requests` was found on https://download.pytorch.org/whl/cpu, but not at
2
the requested version (requests>=2.33.0,<3). A compatible version may be available
3
on a subsequent index (e.g., https://pypi.org/simple). By default, uv will only
4
consider versions that are published on the first index that contains a given
5
package, to avoid dependency confusion attacks.

Playwright Browser Reuse

Hermes Agent uses Playwright for browser automation. If you already have Playwright installed globally (like I do at version 1.59.1), you might wonder if it downloads another browser.

The answer depends on version matching:

• Browser binaries are stored in ~/.cache/ms-playwright/ with version-pinned directories (e.g., chromium-1208)
• If the Playwright version in Hermes Agent’s package.json matches your global install, it reuses the cached browser — no extra download
• If versions differ, a separate Chromium directory gets created alongside your existing ones — nothing gets overwritten

No special configuration needed. They coexist peacefully.

Can You Replace Node.js with Bun?

I looked into this since I prefer Bun’s speed. Hermes Agent’s Node.js dependencies are:

Root package.json:

WhatsApp bridge:

The dealbreaker: The installer runs npx playwright install --with-deps chromium, which uses Node.js APIs to detect the OS and install system libraries. Playwright’s --with-deps flag is known to be Node-specific and doesn’t work reliably under Bun.

Given that the installer isolates Node.js in ~/.hermes/node/ (~50MB) without interfering with anything else on the system, I decided to keep Node.js for this project. The risk/reward of swapping to Bun isn’t worth it here.

RL Training vs. Built-In Learning

One thing that confused me during installation: the [rl] extra is not included in [all]. The pyproject.toml has this:

1
all = [
2
  "hermes-agent[modal]",
3
  "hermes-agent[messaging]",
4
  "hermes-agent[cron]",
5
  # ... everything else ...
6
  # rl is NOT here
7
]

At first I thought: does Hermes Agent actually learn without RL?

Yes, absolutely. The “learning” in Hermes Agent has nothing to do with RL training:

• Memory — persists knowledge across sessions in ~/.hermes/memories/
• Auto-generated skills — creates reusable skills from experience in ~/.hermes/skills/
• Conversation history — searches past conversations to recall context
• Self-improvement loop — creates skills from experience and improves them during use

The RL training ([rl] extra + tinker-atropos submodule) is for fine-tuning the LLM model weights — a separate, advanced workflow for researchers. It’s what Nous Research uses to produce models like DeepHermes-ToolCalling-Specialist-Atropos on HuggingFace.

The RL extra is excluded from [all] because:

1. It pulls in atroposlib and tinker via git+https://... — slow and can fail on network issues
2. It transitively depends on PyTorch (even if you’re using CPU-only wheels, it’s still heavy)
3. It requires the tinker-atropos git submodule to be cloned separately
4. Only researchers doing RL training need it

You can install it manually anytime:

1
git submodule update --init tinker-atropos
2
uv pip install -e "./tinker-atropos"

Regular learning works out of the box without any of this.

Firecrawl Setup

Firecrawl (web scraping) is already included as a core Python dependency (firecrawl-py>=4.16.0). No extra installation needed — it’s part of the base dependencies, not even an extra.

To enable it, just add your API key to ~/.hermes/.env:

1
FIRECRAWL_API_KEY=fc-your-key-here

Sign up at firecrawl.dev to get an API key.

What Gets Installed with [all]

For reference, here’s everything that .[all] pulls in:

Core (always installed): openai, anthropic, httpx, requests, rich, prompt_toolkit, pyyaml, jinja2, pydantic, fire, tenacity, python-dotenv, exa-py, firecrawl-py, parallel-web, fal-client, edge-tts, PyJWT

Extras included in [all]:

Excluded from [all] (install manually):

My Final Installation Command

After all the modifications, here’s what worked for my setup:

1
# Clone with submodules
2
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
3
cd hermes-agent
4

5
# Install uv
6
curl -LsSf https://astral.sh/uv/install.sh | sh
7

8
# Create venv
9
uv venv venv --python 3.11
10
export VIRTUAL_ENV="$(pwd)/venv"
11

12
# Install with CPU-only PyTorch
13
uv pip install --index-strategy unsafe-best-match \
14
  --extra-index-url https://download.pytorch.org/whl/cpu \
15
  -e ".[all]"
16

17
# Node.js dependencies (browser tools + WhatsApp)
18
npm install
19
npx playwright install chromium
20

21
# Configure
22
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}
23
cp cli-config.yaml.example ~/.hermes/config.yaml
24
cp .env.example ~/.hermes/.env
25

26
# Make hermes available globally
27
mkdir -p ~/.local/bin
28
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes
29

30
# Run setup wizard
31
hermes setup

Post-Installation: Setting Up CLI Skills

Hermes Agent ships with bundled skills, but its real power comes from creating project-specific skills that teach it how to use the CLIs already on your system. Rather than calling APIs directly, Hermes can delegate to system-installed tools — which means your other agents (Claude Code, Codex, etc.) and Hermes all share the same tools and authentication.

Here’s how I set up three essential skills: web search, library documentation, and issue tracking.

1
# Install
2
npm install -g @tavily/cli
3

4
# Authenticate (one-time)
5
tvly login --api-key tvly-YOUR_KEY
6

7
# Verify
8
tvly auth

1
# Search with AI-generated answer
2
tvly search "Hermes Agent skills" --max-results 5 --include-answer basic --json
3

4
# Extract content from URLs
5
tvly extract https://example.com https://other.com --json
6

7
# Deep research (multi-step, takes minutes)
8
tvly research "comprehensive analysis of X" --json
9

10
# Crawl a website
11
tvly crawl https://example.com --max-depth 2 --limit 20 --json

1
# Install (via npm)
2
npm install -g @upstash/context7
3

4
# Authenticate (one-time)
5
ctx7 login
6

7
# Verify
8
ctx7 whoami

1
# Find the library
2
ctx7 library "react" --json
3
# Returns IDs like /facebook/react, /reactjs/react.dev with trust scores
4

5
# Query documentation
6
ctx7 docs /facebook/react "useEffect cleanup" --json
7
# Returns code snippets with descriptions and source links

1
# Install (Go binary)
2
go install github.com/steveyegge/beads/cmd/bd@latest
3

4
# Initialize in a project
5
cd ~/my-project
6
bd init
7

8
# Verify
9
bd where

1
# Session start
2
bd prime                    # Load workflow context
3
bd ready                    # Show unblocked work
4

5
# Create and manage issues
6
bd create "Fix auth bug" -t bug -p 1
7
bd update <id> --claim      # Atomically claim work
8
bd dep add <a> <b>          # B blocks A
9
bd close <id>
10

11
# Cross-session memory
12
bd remember "auth uses JWT not sessions" --key auth-jwt
13
bd recall auth-jwt
14

15
# Sync with team
16
bd dolt push                # Push to Dolt remote

1
---
2
name: tvly
3
description: "Tavily CLI for web search, extraction, crawling, and deep research. Triggers: web search, tavily, tvly."
4
---

1
bd setup claude      # Install Claude Code hooks (SessionStart, PreCompact)
2
bd setup codex       # Add to AGENTS.md
3
bd setup opencode    # Add to AGENTS.md

1
bd setup --add hermes ~/.beads/recipes/hermes.md

References

1. Nous Research. Hermes Agent Documentation — Installation. Accessed 5 Apr. 2026.
2. Nous Research. Hermes Agent GitHub Repository. Accessed 5 Apr. 2026.
3. Astral. uv pip install — Index Strategy. Accessed 5 Apr. 2026.
4. PyTorch. Installing CPU-Only PyTorch. Accessed 5 Apr. 2026.
5. Tavily. Tavily CLI Documentation. Accessed 5 Apr. 2026.
6. Context7. Context7 — LLM Context as a Service. Accessed 5 Apr. 2026.
7. Steve Yegge. Beads — Dependency-Aware Issue Tracker. Accessed 5 Apr. 2026.

This article was written by opencode (GLM-5-Turbo | Z.AI Coding Plan).