HermesAgent.ca
Tutorial

How to Install Hermes Agent on macOS, Linux, and WSL

Install Hermes Agent on your machine and get it running in under 10 minutes. This guide covers macOS, Linux, and Windows (WSL) with terminal commands and expected output for each step.

In short

Hermes Agent installs in one terminal command. After install, run hermes setup to pick a model and provider, then start building skills that improve with every use. You'll have a working AI agent with persistent memory and tool access in under 10 minutes on macOS, Linux, or WSL.

Jump to the install command →

Prerequisites

Before installing Hermes Agent, make sure your system has these basics. Most developer machines already have them; if you're starting fresh, each takes about 2 minutes to install.

RequirementWhyCheck with
Python 3.10+ Hermes runs on Python python3 --version
pip Package installer pip3 --version
git For cloning reference docs and worktrees git --version
Bash or Zsh terminal All commands in this guide assume a Unix-style shell You're reading this, so you have one
Windows users: This guide assumes WSL 2 (Windows Subsystem for Linux). Open PowerShell as Administrator and run wsl --install, then restart and launch the Ubuntu terminal. All commands below work inside that Ubuntu environment. Native Windows (PowerShell/cmd) is also supported by Hermes but has different keybindings and path conventions — see the official docs for details.

Step 1: Install Hermes Agent

Open your terminal and run the single install command. This script detects your OS, creates a virtual environment, installs dependencies, and links the hermes command to your PATH.

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

Expected output: The installer prints progress for each step and finishes with a success message showing your Hermes home directory (typically ~/.hermes/). You'll see something like:

Hermes Agent installed successfully
Home: /Users/you/.hermes
Run 'hermes' to start

If the install completes without errors, restart your terminal or run source ~/.bashrc (or source ~/.zshrc on macOS) so the hermes command is available. Then verify:

hermes --version

You should see a version number. If you get command not found, the shell hasn't picked up the new PATH entry — restart your terminal and try again.

Step 2: First-run setup

Run the interactive setup wizard to choose your AI model, provider, and basic preferences.

hermes setup

The wizard walks you through:

  • Model selection — Choose a model. OpenRouter is the easiest starting point: it gives you access to 200+ models through a single API key. Sign up at openrouter.ai for a free key.
  • Provider configuration — Hermes supports 20+ providers (Anthropic, OpenAI, DeepSeek, Gemini, local models, and more). You can add more later with hermes config.
  • Terminal backend — Keep the default (local) unless you want docker/SSH isolation.
  • Tools — The default tools are file access, terminal, web search, and memory. You can add browser, image generation, and messaging platforms later.
Privacy note — local vs cloud: Hermes Agent runs on your machine, not a remote server. Your files, terminal commands, and conversations stay on your computer by default. When you connect a cloud provider (like OpenRouter or Anthropic), your prompts and tool outputs are sent to that provider's API for processing — the same as using any AI chat tool. For privacy-sensitive work, you can connect a local model (via Ollama or llama.cpp) and keep everything on-device. See the self-hosted AI agent guide for Canadian data residency tradeoffs. (This page is not legal advice.)

After setup, check everything is healthy:

hermes doctor

hermes doctor verifies your Python environment, config file, and API key setup. If anything is missing, it tells you what to fix.

Quick config: skip the wizard

If you already have an API key and know which model you want, you can configure Hermes directly:

# Set your API key (OpenRouter example)
hermes config set model.api_key sk-or-v1-...

# Set the model
hermes config set model.default openai/gpt-4o

# Verify
hermes config

API keys are stored in ~/.hermes/.env (not committed to git). Hermes never stores keys in config.yaml.

Step 3: First run

Start Hermes in interactive chat mode:

hermes

You'll enter a chat session. Try a simple request to confirm everything works:

You: What files are in my home directory?

Hermes should respond by listing files. This confirms the agent can use its terminal and file tools. If it works, you're ready.

For a one-shot query without entering interactive mode:

hermes chat -q "Summarize the last 3 files I modified"

Step 4: Configure your first skill

Now that Hermes is running, the next step is to teach it a reusable workflow. Skills are how Hermes Agent improves over time — each skill is a documented procedure the agent loads into future sessions so it never has to re-learn how to do a task.

Hermes comes with dozens of ready-made skills for common workflows:

hermes skills list        # See installed skills
hermes skills browse       # Browse the skill catalog
hermes skills install ID   # Install a skill from the hub

Some useful starting skills:

  • obsidian — Read, search, and create notes in your Obsidian vault
  • google-workspace — Gmail, Calendar, Drive, Docs, and Sheets automation
  • apple-notes — Manage Apple Notes from the terminal
  • himalaya — Send and read email via IMAP/SMTP from the terminal
  • github-pr-workflow — Full GitHub PR lifecycle from the terminal

When Hermes solves a problem you've never asked before, it can save that approach as a new skill — so next time, it already knows what to do. This is the self-improving part of Hermes Agent. Learn more about Hermes Agent skills →

Frequently asked questions

Can I use Hermes Agent for free?

Yes. The agent itself is open source (MIT license). You pay only for the AI model you connect it to. If you use a local model with Ollama or llama.cpp, the entire stack is free. OpenRouter offers free-trial credits for new accounts, and many providers have free tiers.

Does Hermes Agent work on Windows without WSL?

Yes — Hermes runs natively on Windows (PowerShell, cmd, Windows Terminal, and git-bash). However, WSL 2 is the smoothest experience because install scripts and most skills assume a Unix-style environment. Native Windows works but has some keybinding and path differences. See the official docs for Windows-specific notes.

Where does Hermes store my data?

Everything lives in ~/.hermes/ on your machine: conversations in sessions/, skills in skills/, API keys in .env, and configuration in config.yaml. Nothing is sent to Nous Research or any Hermes-hosted server. Your model provider sees prompts and tool outputs when you make API calls — that's the only data that leaves your machine.

How is persistent memory different from session history?

Session history is the transcript of one conversation. Persistent memory is Hermes's long-term knowledge about you, your preferences, your environment, and lessons learned — it survives across sessions and is injected into every new conversation. For example, if you tell Hermes you prefer GitLab over GitHub, it remembers that preference permanently. How Hermes Agent persistent memory works →

What if I already have an AI coding tool like Claude Code or Codex?

Hermes Agent complements those tools rather than replacing them. Claude Code and Codex are specialized for coding in an editor. Hermes is a general-purpose agent that works across terminal, messaging platforms, and the web — it can check your calendar, send Telegram messages, manage files, and run scheduled tasks. Many users run both: Hermes for broad automation and Claude Code/Codex for in-editor coding. What is Hermes Agent? Full overview →

Next: configure your first skill

Hermes Agent gets better the more you use it. Pick a skill from the catalog, install it, and let Hermes learn your workflow. Each solved problem becomes a reusable skill that makes the agent smarter.

Browse skills →

Related Hermes Agent guides