Module 02: Installation & First Run — AI Agents: Master Hermes Agent

**Course:** Hermes Agent — From Zero to Autonomous Agent

**Module:** 2 of 8

**Reading time:** ~20 minutes

**Difficulty:** Beginner — no prior Hermes experience needed, basic terminal familiarity helpful

TL;DR

One-liner install	`curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh \	bash`
Prerequisites	Git + a Linux/macOS/WSL2 system. The installer handles Python, Node.js, ripgrep, and ffmpeg automatically.
After install	`source ~/.bashrc && hermes`
First run	Setup wizard walks you through choosing a provider and getting API keys
Time to first chat	Under 2 minutes
Docker alternative	`docker run -it ghcr.io/nousresearch/hermes-agent`
Got stuck?	`hermes doctor` diagnoses everything

Before You Start

Supported Platforms

Platform	Status	Notes
Linux (x86_64, arm64)	✅ Production-ready	Ubuntu, Debian, Fedora, Arch, openSUSE all tested
macOS (Intel, Apple Silicon)	✅ Production-ready	Intel and M-series both supported
WSL2 (Windows)	✅ Production-ready	Use Ubuntu from Microsoft Store, then install as Linux
Windows Native (PowerShell)	⚠️ Early Beta	Works but fewer battle-tested paths
Termux (Android)	✅ Supported	Auto-detected by installer
NixOS	✅ Supported	Dedicated flake and NixOS module

Prerequisites

**Absolute minimum:**

- **Git** — run `git --version` to check. If missing:

- **Ubuntu/Debian:** `sudo apt install git`

- **macOS:** `xcode-select --install` or `brew install git`

- **Fedora:** `sudo dnf install git`

- **Windows WSL:** `sudo apt install git` (inside WSL)

**The installer handles everything else automatically** — you don't need to pre-install Python, Node.js, ripgrep, or ffmpeg. It detects what's missing and provisions it.

**Optional but nice to have:**

- A terminal emulator that supports true color (kitty, iTerm2, Windows Terminal, GNOME Terminal)

- `curl` (most systems have it; install with `sudo apt install curl` if missing)

Getting an API Key (Do This Now)

You'll need an API key from an LLM provider. For beginners, **OpenRouter** is the best starting point — one API key gives access to 200+ models including GPT-4o, Claude, Gemini, and open-source models.

1. Go to [openrouter.ai/keys](https://openrouter.ai/keys)

2. Sign up (free tier available with initial credits)

3. Create an API key

4. Copy it somewhere safe — you'll paste it into the setup wizard

**Pro tip:** OpenRouter's free tier gives you enough credits to explore for weeks. If you run out, top up with as little as $5 to access everything.

Method 1: One-Line Installer (Recommended)

This is the fastest and most battle-tested path. Works on **Linux, macOS, WSL2, and Termux**.

Open your terminal and run:


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

**What you'll see:**


⚕ Hermes Agent Setup

→ Checking for uv...
✓ uv found (0.6.x)
→ Creating virtual environment...
→ Installing hermes-agent and dependencies...
→ Installing Node.js 22...
→ Installing system tools (ripgrep, ffmpeg)...
→ Installing Playwright browsers for web automation...
→ Symlinking hermes command to ~/.local/bin/hermes...

✓ Installation complete!

Run 'source ~/.bashrc' then 'hermes' to start chatting!

**Time estimate:** 30-90 seconds on a decent internet connection.

What the Installer Actually Does

Let's demystify that one-liner. The install script:

1. **Detects your platform** — Linux, macOS, Termux, or other POSIX

2. **Installs `uv`** — a lightning-fast Python package manager (replaces pip)

3. **Clones the repo** to `~/.hermes/hermes-agent/`

4. **Creates a Python virtual environment** inside the repo (Python 3.11)

5. **Installs all dependencies** — Hermes core, browser automation, voice tools

6. **Installs Node.js v22** — needed for browser automation and the WhatsApp bridge

7. **Installs system tools** — `ripgrep` (fast file search) and `ffmpeg` (audio format conversion)

8. **Installs Playwright browsers** — headless Chromium for web automation

9. **Symlinks the `hermes` command** to `~/.local/bin/hermes`

10. **Updates your shell config** — adds `~/.local/bin` to PATH in `.bashrc` or `.zshrc`

**Install layout after completion:**

What	Where
Hermes code	`~/.hermes/hermes-agent/`
Virtual environment	`~/.hermes/hermes-agent/venv/`
`hermes` command	`~/.local/bin/hermes` (symlink to venv)
Your config & data	`~/.hermes/`
Skills	`~/.hermes/skills/`
Session history	`~/.hermes/sessions/`
Logs	`~/.hermes/logs/`

After Installation

Reload your shell so the `hermes` command is found:


source ~/.bashrc    # if you use bash
# OR
source ~/.zshrc     # if you use zsh

Verify the installation:


hermes --version
# Expected output (version number will differ):
# Hermes Agent 0.x.x

Method 2: Docker Install

Prefer containers? Hermes has an official Docker image. Good for isolated environments, CI/CD pipelines, or if you don't want the installer touching your system.


# Pull and run
docker run -it --rm \
  -v ~/.hermes:/root/.hermes \
  -e OPENROUTER_API_KEY=your_key_here \
  ghcr.io/nousresearch/hermes-agent

**Breaking this down:**

- `-it` — interactive terminal mode

- `--rm` — remove container when done

- `-v ~/.hermes:/root/.hermes` — persist your config and sessions on the host

- `-e OPENROUTER_API_KEY=...` — pass your API key as an environment variable

For a persistent setup (recommended), create a data directory first:


mkdir -p ~/.hermes-docker
docker run -it --rm \
  -v ~/.hermes-docker:/root/.hermes \
  -e OPENROUTER_API_KEY=your_key_here \
  ghcr.io/nousresearch/hermes-agent

**Note:** The Docker image is built from the `main` branch. For a pinned version, use a specific tag like `ghcr.io/nousresearch/hermes-agent:v0.x.x`.

Method 3: Manual Git Clone Install

For developers, contributors, or anyone who wants full control:


# 1. Clone the repo
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# 2. Run the setup script
./setup-hermes.sh

The `setup-hermes.sh` script does the same work as the one-liner installer — installs `uv`, creates a venv, installs dependencies, and symlinks the `hermes` command. The difference is you have the repo on disk, so you can:

- Switch branches (`git checkout develop`)

- Make local changes

- Run the test suite (`scripts/run_tests.sh`)

- Stay on a specific version

Windows-Specific Setup

Option A: WSL2 (Easiest, Most Stable)

1. **Install WSL2** — Open PowerShell as Administrator and run:

```powershell

wsl --install

```

This installs Ubuntu by default. Restart when prompted.

2. **Launch Ubuntu** from the Start Menu. On first boot, set up a Linux username and password.

3. **Update packages:**

```bash

sudo apt update && sudo apt upgrade -y

```

4. **Install Git:**

```bash

sudo apt install git curl -y

```

5. **Run the one-liner installer:**

```bash

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

```

6. **Reload and launch:**

```bash

source ~/.bashrc

hermes

```

Option B: Native Windows (Early Beta)

Open **PowerShell** (not CMD) and run:


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

**What the PowerShell installer does:**

1. Installs `uv` for Python package management

2. Clones the repo to `%LOCALAPPDATA%\hermes\hermes-agent`

3. Creates a virtual environment

4. Installs a **portable Git Bash** (PortableGit) — no admin rights needed, completely isolated from any system Git install

5. Installs Node.js 22, ripgrep, ffmpeg

6. Adds `hermes` to your User PATH

**After install:** Open a **new PowerShell window** (PATH updates need a fresh session) and run `hermes`.

**Heads up:** The browser-based dashboard chat pane requires WSL2 on Windows. Everything else — CLI, gateway, cron, browser tool, MCP servers — runs natively.

First Launch: The Setup Wizard

This is where the magic happens. Run:


hermes

The first time you launch, you'll be greeted by an interactive **setup wizard**. It looks something like this:


╭──────────────────────────────────────────────╮
│          ⚕ Hermes Agent Setup Wizard          │
│              Let's get you started!           │
╰──────────────────────────────────────────────╯

I'll help you configure:
• Your LLM provider and model
• Your API credentials
• Tool preferences
• Platform integrations (optional)

Let's begin!

→ Which provider would you like to use?
  1) OpenRouter (recommended — 200+ models, one API key)
  2) OpenAI (GPT-4o, o1, o3-mini)
  3) Anthropic (Claude Opus 4, Sonnet 4)
  4) Nous Portal (Nous Research endpoint)
  5) Local / Other (Ollama, vLLM, custom endpoint)
  > 1

Step-by-Step Wizard Walkthrough

**Step 1: Choose a provider.** Pick **OpenRouter** (option 1) for the easiest start. It gives you access to every major model through a single API key.

**Step 2: Enter your API key.** Paste the key you created earlier. It gets saved to `~/.hermes/.env`, not your shell history.

**Step 3: Choose a model.** OpenRouter offers 200+ models. Good defaults:

Model	Best for	Cost
`openrouter:openai/gpt-4o`	General purpose, writing, reasoning	Low
`openrouter:anthropic/claude-sonnet-4`	Coding, complex tasks	Medium
`openrouter:google/gemini-2.5-pro`	Long context, research	Low
`openrouter:meta-llama/llama-4-maverick`	Open model, fast	Very low
`openrouter:qwen/qwen-2.5-72b-instruct`	Strong open model	Very low

For beginners, **`openrouter:openai/gpt-4o`** is a solid default — fast, capable, and affordable.

**Step 4: Configure tools.** The wizard asks which tools you want enabled:

- **Terminal** (run shell commands) — **Recommended: Yes**

- **File system** (read/write files) — **Recommended: Yes**

- **Web search** — **Recommended: Yes**

- **Browser automation** — Optional, can enable later

- **Vision** — Optional, for image analysis

**Step 5: Messaging platforms (optional).** You can set up Telegram, Discord, or Slack now, or skip and configure later with `hermes gateway setup`.

When the wizard finishes, you'll see:


✓ Setup complete! Your configuration has been saved.

You can change any of these settings later with:
  hermes model     — Change provider or model
  hermes tools     — Enable/disable tools
  hermes config    — View/edit all settings
  hermes gateway   — Set up messaging platforms

Ready to chat! Type your message below or /help for commands.

Your First Chat

After the wizard, you're dropped into the Hermes CLI. You'll see a `>` prompt. Try these:


> Hello! What can you do?

Hermes will respond with a friendly introduction and a list of capabilities. You'll see the **KawaiiSpinner** — an animated face (`◕‿◕`, `⧗◕‿◕⧗`, etc.) that shows the agent is thinking.

Asking Questions


> What time is it right now?

This will trigger Hermes to use its **date/time tool** — you'll see the tool call in the output:


 ◕‿◕  Thinking...
 ┊ Calling tool: get_current_date

 The current date and time is Saturday, May 23, 2026, 10:15:42 AM UTC.

Seeing Tool Calls in Action

This is where Hermes separates from vanilla chatbots. Try:


> Check my disk usage

You'll see Hermes:

1. **Decide** what tool to use

2. **Call** the terminal tool with `df -h`

3. **Read** the output

4. **Format** a readable response

Example output:


 ⧗◕‿◕⧗  Working...
 ┊ Running: df -h

 📊 Disk Usage Summary:

 Filesystem      Size  Used  Avail  Use%
 /dev/sda1       50G   23G    27G    46%
 tmpfs           2.0G  1.2M   2.0G    1%

 Your root partition is 46% full — plenty of room.

Try more:


> Create a new directory called test-project and a file called notes.txt
> Search the web for "latest AI agent frameworks 2026"
> What's in my current directory?
> Write a Python script that prints the Fibonacci sequence

Each command will show tool calls in real-time — you can watch Hermes think, act, and iterate.

Understanding the Interface


 ◕‿◕  Thinking...               ← The spinner shows the agent is processing
 ┊ Calling tool: run_terminal    ← Every tool call is shown
 ┊ Running: python3 script.py    ← The actual command being executed
 ✓ Command completed (exit: 0)   ← Status of the tool call

 Here's the result...            ← The agent's natural language response

Key interface elements:

- **`>` prompt** — Type your message here

- **Slash commands** — Type `/` to see available commands (`/help`, `/new`, `/model`, `/skills`, etc.)

- **Tool call output** — Every tool the agent uses is shown with `┊` prefix

- **Tab completion** — Press Tab to autocomplete slash commands

- **`Ctrl+C`** — Interrupt the current action

- **`Ctrl+L`** — Clear the screen

- **Up/Down arrows** — Navigate conversation history

- **`/new` or `/reset`** — Start a fresh conversation

Troubleshooting: `hermes doctor`

If something goes wrong, run:


hermes doctor

This runs a comprehensive diagnostic check:


⚕ Hermes Doctor

System:
  ✓ OS: Linux 6.8.0-110-generic (x86_64)
  ✓ Shell: bash 5.2.21

Installation:
  ✓ Hermes path: /root/.local/bin/hermes
  ✓ Hermes home: /root/.hermes
  ✓ Git: available
  ✓ Install method: git installer

Python:
  ✓ Python 3.11.9 (via uv)
  ✓ Virtual environment: active

Dependencies:
  ✓ uv: 0.6.x
  ✓ Node.js: v22.x
  ✓ ripgrep: 14.x
  ✓ ffmpeg: 7.x
  ✓ Playwright browsers: installed

Configuration:
  ✓ Config file: /root/.hermes/config.yaml
  ✓ API keys: OPENROUTER_API_KEY configured
  ✓ Provider: openrouter
  ✓ Model: openai/gpt-4o

  ✗ Telegram: not configured
  ✗ Discord: not configured

  ✓ 2 checks passed, 2 optional checks skipped.

`hermes doctor` checks for:

- Missing dependencies

- Invalid configuration

- Unset API keys

- Broken symlinks

- Permission issues

- Python version compatibility

Each issue comes with a suggested fix command.

Common Issues & Fixes

**`hermes: command not found`**

- **Fix:** Run `source ~/.bashrc` (or `source ~/.zshrc`), then try again.

- **If it persists:** Your `~/.local/bin` may not be in PATH. Add this to your shell config:

```bash

export PATH="$HOME/.local/bin:$PATH"

```

**Setup wizard doesn't start — blank screen or hangs**

- **Fix:** Your terminal might not be fully interactive. Try:

```bash

hermes setup

```

This launches the wizard directly.

- **If that also hangs:** Try the non-interactive config path:

```bash

hermes config set provider openrouter

hermes config set OPENROUTER_API_KEY your_key_here

hermes config set model openrouter:openai/gpt-4o

hermes chat

```

**`ModuleNotFoundError: No module named 'dotenv'`**

- **Fix:** You're invoking the repo source file directly with system Python instead of the venv launcher. Make sure you're running `~/.local/bin/hermes` (or just `hermes` after `source ~/.bashrc`), not `~/hermes-agent/hermes`.

**`API key not set`**

- **Fix:** Run `hermes model` to configure your provider, or:

```bash

hermes config set OPENROUTER_API_KEY your_key_here

```

**`Permission denied` when running `hermes`**

- **Fix:** The installer needs write access to `~/.local/bin/`. If you installed as root, the binary might be in `/usr/local/bin/`. Try:

```bash

sudo ln -s ~/.hermes/hermes-agent/venv/bin/hermes /usr/local/bin/hermes

```

**Slow first launch after install**

- **Normal:** The first launch triggers Playwright browser download (~100MB) if the installer skipped it. Subsequent launches are instant.

**`curl: command not found` during install**

- **Fix:** Install curl first:

```bash

sudo apt install curl -y # Debian/Ubuntu

sudo dnf install curl -y # Fedora

```

**Git not found during install**

- **Fix:**

```bash

sudo apt install git -y # Debian/Ubuntu

sudo dnf install git -y # Fedora

brew install git # macOS

```

**Docker: `ghcr.io/nousresearch/hermes-agent: not found`**

- **Fix:** First pull the image:

```bash

docker pull ghcr.io/nousresearch/hermes-agent

```

Then run. If pulling fails, you may need to authenticate with GitHub Container Registry:

```bash

echo $GITHUB_TOKEN | docker login ghcr.io -u your-username --password-stdin

```

**WSL: `hermes` command works in Ubuntu but not in PowerShell**

- **Expected.** WSL is a separate Linux environment. `hermes` only works inside the WSL terminal window. Use the native Windows installer if you need PowerShell access.

Next Steps After First Chat

You're up and running. Here's what to try next:

1. **`hermes model`** — Experiment with different models (Claude for coding, Gemini for long context, open models for speed)

2. **`hermes tools`** — Browse available tools and enable/disable them per platform

3. **`/skills`** — See what skills are installed and available

4. **`hermes gateway setup`** — Connect Telegram or Discord so you can chat from your phone

5. **`hermes cron`** — Schedule your first automated task

6. **`/help`** — Full list of slash commands

Key Takeaways

- **One command** is all it takes: `curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash`

- **The installer handles everything** — Git is the only prerequisite; Python, Node.js, ripgrep, and ffmpeg are auto-installed

- **Docker alternative** available for containerized deployments

- **WSL2** is the most stable Windows path; native Windows PowerShell install is in early beta

- **First launch triggers the setup wizard** — choose OpenRouter for the simplest start

- **Watch tool calls happen live** — Hermes shows every command it runs and tool it uses

- **`hermes doctor`** diagnoses any issues with clear, actionable fixes

- **From install to first chat is under 2 minutes** on a decent internet connection

Quiz Questions

1. **What is the only prerequisite for the one-line installer on Linux/macOS?**

- a) Python 3.11

- b) Git

- c) Docker

- d) Node.js

2. **Where does the installer put the `hermes` command?**

- a) `/usr/bin/hermes`

- b) `~/hermes-agent/hermes`

- c) `~/.local/bin/hermes` (symlink to the venv)

- d) `/opt/hermes/hermes`

3. **What provider is recommended for beginners during the setup wizard?**

- a) OpenAI

- b) Anthropic

- c) OpenRouter

- d) Nous Portal

4. **What command do you run if you encounter issues after installation?**

- a) `hermes check`

- b) `hermes diagnose`

- c) `hermes doctor`

- d) `hermes status`

5. **Which of these is NOT a step you should take after installation?**

- a) `source ~/.bashrc`

- b) `hermes` to launch the setup wizard

- c) Installing Python manually before running the installer

- d) Pasting your API key when prompted

**Answers:** 1-b, 2-c, 3-c, 4-c, 5-c

*Next Module: Module 3 — Configuration & Customization (coming soon)*

Installation & First Run

🎬 Full Walkthrough Video

TL;DR

Before You Start

Supported Platforms

Prerequisites

Getting an API Key (Do This Now)

Method 1: One-Line Installer (Recommended)

What the Installer Actually Does

After Installation

Method 2: Docker Install

Method 3: Manual Git Clone Install

Windows-Specific Setup

Option A: WSL2 (Easiest, Most Stable)

Option B: Native Windows (Early Beta)

First Launch: The Setup Wizard

Step-by-Step Wizard Walkthrough

Your First Chat

Asking Questions

Seeing Tool Calls in Action

Understanding the Interface

Troubleshooting: `hermes doctor`

Common Issues & Fixes

Next Steps After First Chat

Key Takeaways

Quiz Questions