Installation & Provider Setup

The installer is a single curl command that handles everything: Python, Node, system dependencies, and the Hermes binary itself. After that, the fastest path to a working agent is hermes setup --portal, which gives you a model and all four Tool Gateway tools through one OAuth sign-in. This lesson covers both paths and verifies everything works.

What you'll learn

• One command installs everything: curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
• hermes setup --portal is the fastest path to a working agent, one OAuth covers a model plus web search, image generation, TTS, and browser tools
• hermes doctor is the verification checkpoint, if it passes, Hermes is ready

The problem

Installing an AI agent platform usually means wrangling Python environments, compiling dependencies, and debugging GPU drivers before you even get to a chat prompt. Hermes's installer handles the entire stack, Python 3.11, Node.js v22, ripgrep, ffmpeg, and the Hermes binary itself, in one shot. The goal is to go from zero to a working agent in under two minutes.

Options & when to use each

Setup path	Good for	Costs you	When to pick it
Shell installer (curl | bash)	Linux, macOS, WSL2, Android (Termux)	None, handles everything	Most users, most of the time
PowerShell installer	Windows native	Requires PowerShell, some Windows-specific path quirks	Windows users who don't use WSL
Desktop installer download	macOS and Windows users who want the GUI bundled	Includes the Electron app (~200MB download)	Users who know they want the Desktop app
PyPI (pip install hermes-agent)	Programmatic installs, CI/CD, Docker images	You manage Python, Node, ripgrep, and ffmpeg yourself	Container builds, automated deployments

For this course, we use the shell installer. It's the fastest path and works on every platform we'll cover.

Build it

Step 1: Install

To fetch and execute the automated setup script for Linux, macOS, or WSL2, run the installation curl script from your terminal:

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

The installer detects your OS and handles dependencies automatically. On Linux it installs Python 3.11, Node.js v22, ripgrep, and ffmpeg via your system package manager. On macOS it uses Homebrew. On WSL2 it uses apt.

After the installer finishes, source your shell config to pick up the new hermes command:

source ~/.bashrc

Or on macOS with zsh: source ~/.zshrc.

Step 2: Verify the install

Run the built-in diagnostic tool to audit the local installation state, system packages, and system variables:

hermes doctor

Expected output confirms: Python and Node versions are compatible, the ~/.hermes/ directory structure exists, the state database is reachable, and no broken dependencies are detected. If hermes doctor passes, the install is clean.

If it reports issues, run hermes doctor --fix to attempt automatic repair. Common issues: missing system packages (the installer handles most of these, but --fix catches edge cases), incorrect shell PATH, or stale state from a previous install.

Step 3: Connect a provider

The recommended configuration path uses the Nous Portal for unified model access and automatic tool provisioning:

hermes setup --portal

This opens a browser for Nous Portal OAuth. One sign-in covers a model (with access to 300+ models through the portal) plus four Tool Gateway tools: web search, image generation, TTS, and browser automation. No separate API keys needed.

If you prefer to bring your own API key:

hermes setup

This walks through an interactive wizard. You'll pick a provider (OpenRouter, Anthropic, OpenAI, Google, DeepSeek, or any of the 20+ supported providers), enter your API key, and select a default model. The key is stored in ~/.hermes/.env, never committed to git.

To change the model later:

hermes model

This opens an interactive picker showing all available models from your configured provider. You can also set it directly:

hermes config set model.default "anthropic/claude-sonnet-4"

Step 4: Verify the provider works

To verify that your selected model can execute prompt requests successfully, run a quick query test using the CLI command line parameter:

hermes chat -q "What is the current date in ISO 8601 format?"

If the response is a valid date string, the provider connection is working. If you get an authentication error, check your API key in ~/.hermes/.env or re-run hermes auth for OAuth providers.

Image needed (screenshot): A terminal showing the output of hermes doctor with all checks passing, followed by hermes chat -q returning a valid response. Suggested filename: 01-install-verify.png

What goes wrong

Mistake	How you notice it	The fix
hermes: command not found after install	The shell can't find the binary	source ~/.bashrc (or ~/.zshrc). The installer adds ~/.local/bin to PATH, but the current shell session doesn't know about it until you re-source
hermes doctor fails with missing Python/Node	The installer couldn't install dependencies (usually a permissions issue)	Run hermes doctor --fix. If that fails, install Python 3.11 and Node.js v22 manually, then re-run the installer
OAuth flow hangs or fails to open browser	hermes setup --portal opens a browser, but you're on a headless server	Run hermes setup --portal from a machine with a browser, or use manual API key setup: hermes setup and select your provider
API key stored in the wrong place	hermes chat fails with authentication errors	API keys go in ~/.hermes/.env, not config.yaml. Check with hermes config env-path to confirm the file location. Never commit .env to git
Windows PowerShell: iex blocked by execution policy	iex (irm https://...) fails with a security error	Run Set-ExecutionPolicy RemoteSigned -Scope CurrentUser first, or use the Desktop installer instead

Confirm it worked

To perform a final sanity check verifying the system diagnosis, active model, and filesystem command integration, run these diagnostic validations:

# 1. Verify the install
hermes doctor

# 2. Check your provider and model
hermes config | grep -A2 "model:"

# 3. Run a real query, not a hello-world
hermes chat -q "List the 5 largest files in my home directory, sorted by size"

If step 3 returns actual file names and sizes (not a refusal or an error), Hermes is installed, connected to a model, and has working file system access. That's the baseline for everything that follows.

Next: The CLI, Your First Real Task , interactive chat, one-shot mode, and the slash commands you'll use every day.