Install & first run

Requirements

• Python 3.11+ (the installer checks this; upgrade first if it complains).
• macOS, Linux, WSL2, or native Windows. There is also a tested Termux path for Android.

Install Hermes

macOS / Linux / WSL2

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Don't use sudo

The installer writes to ~/.local/bin. If hermes: command not found afterward, reload your shell (source ~/.zshrc) or add export PATH="$HOME/.local/bin:$PATH" to your shell config.

Windows (PowerShell)

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Or download the Hermes Desktop installer from hermes-agent.nousresearch.com for a GUI + CLI bundle.

Install Ollama (for local models)

If you plan to run offline (recommended for this handbook):

# macOS
brew install ollama

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

# Start the server
ollama serve

Pull a model with tool-calling support:

ollama pull qwen3.5:27b

First-time setup

Run the interactive setup:

hermes setup

For cloud providers, hermes setup --portal covers model + tools in one OAuth login. For offline setup, skip this and go straight to Complete offline setup.

Verify it works

hermes

You should see the Hermes CLI prompt. Type a simple message:

Hello! What can you do?

If Hermes responds, installation succeeded. If it asks for a provider, you still need to configure a model (see offline setup next).

Key directories

Everything Hermes stores lives locally:

Path	What it holds
~/.hermes/config.yaml	Main configuration
~/.hermes/memory/	Persistent memory
~/.hermes/skills/	Agent-created skills
~/.hermes/sessions/	Conversation history

TIP

Hermes does not collect telemetry. Your conversations, memory, and skills stay on your machine. See Privacy & offline data.

Next: Your first conversation, then Complete offline setup.