Install Hermes and Run It for the First Time

This is the hands-on lesson. You will install Hermes Agent with a single command, connect it to a language model so it can think, and start it for the first time. The steps are beginner-friendly. You will paste one command for your system and answer a few prompts. Take it slowly and read each step before you run it.

What You'll Learn

• What you need before you install (and what you do not)
• The single command that installs Hermes
• How to connect a language model backend so Hermes can think
• How to start Hermes and say hello for the first time
• Where your data is stored on your machine

Before You Start: What You Need

Hermes runs on macOS, Linux, and Windows. You do not need to install programming languages or databases yourself. The installer sets up what it needs automatically.

You will need three things:

1. A supported machine. A Mac, a Linux computer, or a Windows 10 or 11 PC.
2. A terminal. This is the text window where you type commands. On macOS it is the Terminal app. On Linux it is your shell. On Windows it is PowerShell (or Windows Terminal), or the Ubuntu window if you use WSL2.
3. Access to a language model. Hermes orchestrates, but the actual thinking comes from a large language model. You will connect one during setup. We cover the options below.

That is it. No coding background required.

Step 1: Install Hermes

Pick the section for your computer. You only need one of them.

macOS or Linux

Open your terminal and paste the official install command from Nous Research:

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

Press Enter. This downloads the installer and runs it. It can take a few minutes the first time, and it is normal to see a lot of text scroll past. When it finishes, reload your shell so the new hermes command is found:

source ~/.bashrc

If your Mac uses zsh (the default on newer Macs), run source ~/.zshrc instead, or simply close the terminal and open a new one.

Windows: The Simple Way (Native, Recommended for Beginners)

Hermes runs directly on Windows 10 and 11. You do not need WSL, Docker, or admin rights. This is the easiest path if you are new to the command line.

1. Open PowerShell from the Start menu. A normal window is fine. You do not need "Run as administrator".
2. Paste this command and press Enter:

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

3. When it finishes, close PowerShell and open a new window. This step matters. The new window picks up the hermes command. If you skip it, Windows will say it cannot find hermes.
4. Check that it worked:

hermes --version

If you see a version number, Hermes is installed.

Windows: The WSL2 Way (Optional)

WSL2 gives you a Linux system inside Windows. You only need it if you want Linux-only extras, or you already use WSL2 for other work. If you are unsure, use the native path above. Most WSL problems come from old or half-finished WSL setups, so the native path avoids them.

If you do want WSL2, follow these steps in order:

1. Right-click PowerShell and choose Run as administrator, then run:

wsl --install

2. Restart your PC when asked. After the restart, an Ubuntu window opens and asks you to create a Linux username and password. These are new and separate from your Windows login. Write them down.
3. Back in PowerShell, check that Ubuntu runs on WSL 2, not WSL 1:

wsl --list --verbose

Look at the VERSION column. If Ubuntu shows 1, upgrade it. Use the name from the NAME column. It may be Ubuntu, or something like Ubuntu-22.04:

wsl --set-version Ubuntu 2
wsl --set-default-version 2

4. Open the Ubuntu app from the Start menu. Run every Hermes command from here, not from PowerShell:

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

If hermes is still not found, close the Ubuntu window and open a new one.

A Quick Word on Safety

All of these commands download a script from the internet and run it. This is the install method the project documents, and it is common for developer tools, but it is worth understanding. If you want to be cautious, open the URL in a browser first and read the script before you run it. That is a good habit for any command like this, not just this one.

Step 2: Connect a Language Model Backend

After installing, Hermes needs a brain. It supports several backends, so you can pick what fits your budget and privacy needs:

• Nous Portal. The first-party option from Nous Research. You sign in with an OAuth login (the same kind of "log in with..." flow you have used on other sites). This is often the simplest starting point.
• OpenRouter. A single service that gives you access to 200+ models from many providers through one API key. Handy if you want to try different models without separate accounts.
• A custom OpenAI-compatible endpoint. If you already use a provider that follows the common API format, you can point Hermes at it.
• Local vLLM. This runs a model on your own hardware. It keeps the thinking on your machine too, which is the most private option, but it needs a capable computer (a strong GPU helps).

For most beginners, Nous Portal or OpenRouter is the easiest way to start. Whichever you choose, follow Hermes's setup prompts and paste in the key or complete the login when asked.

A note on cost and privacy. If you use a cloud backend (Nous Portal, OpenRouter, or a custom hosted endpoint), your prompts are sent to that provider, and you pay it for usage, usually a small amount per action. If keeping everything on your machine matters to you, the local vLLM option does that, at the cost of needing stronger hardware. There is no single right answer. Pick based on your budget and how sensitive your data is.

Step 3: Start Hermes and Say Hello

Hermes gives you two ways to interact with it.

The quickest is the built-in terminal interface. Start it by typing:

hermes

This opens a chat right in your terminal. Try a simple first message, such as asking it to introduce itself or to summarize a short piece of text you paste in. This confirms everything is connected.

The second way is the gateway, which lets you talk to Hermes from a messaging app. Once you start the gateway and connect a platform, you can message Hermes from Telegram, Discord, Slack, WhatsApp, or Signal, just like messaging a contact. The terminal interface is the fastest way to confirm your install works, so start there. Connect a messaging platform later once you are comfortable.

Step 4: Know Where Your Data Lives

Everything Hermes stores, its memory, the skills it writes, and its configuration, lives in a single folder on your machine:

• macOS, Linux, and WSL2: ~/.hermes/ in your home directory. The ~ is shorthand for your home directory, and the leading dot means the folder is hidden by default.
• Windows (native): %LOCALAPPDATA%\hermes\. Paste that into the File Explorer address bar to open it.

Because it is all local and readable, you have full visibility into what your assistant is keeping. This is also the folder to back up if you want to keep everything Hermes has learned, and the folder to check if you ever want to review or clean up its memory. In the rest of this course we write ~/.hermes/ for short. On native Windows, read that as %LOCALAPPDATA%\hermes\.

If Something Goes Wrong

Most install problems have a short fix. Find your symptom below.

On Any System

• "command not found" when you type hermes. Your terminal has not picked up the new command yet. Close the terminal and open a new one. On macOS, Linux, or WSL2 you can also run source ~/.bashrc.
• Hermes starts but cannot think. The language model backend is not connected. Re-check the key or login you set up in Step 2.
• Something else looks broken. Run hermes doctor. It checks your install and tells you what is missing.

On Windows (Native)

• hermes is not recognized right after install. Open a new PowerShell window. If it still fails, run it by its full path: & "$env:LOCALAPPDATA\hermes\bin\hermes.exe".
• You pasted the Linux curl ... | bash command into PowerShell and it failed. That command is for macOS, Linux, and WSL2 only. In PowerShell, use the iex (irm ...) command from Step 1.
• Strange characters or a UnicodeEncodeError message. Use Windows Terminal (free in the Microsoft Store) instead of the old blue PowerShell window.

On Windows With WSL2

• wsl --install fails or says you need to enable a feature. Make sure you opened PowerShell with Run as administrator, then restart your PC and try again. Your PC also needs virtualization turned on. Most modern PCs have it on already. If yours does not, the error message will say so, and you turn it on in your PC's BIOS settings.
• Hermes is slow or unreliable. Your Ubuntu may be running on WSL 1. Run wsl --list --verbose in PowerShell. If it shows 1, run wsl --set-version Ubuntu 2, swapping Ubuntu for the name in the NAME column (for example Ubuntu-22.04).
• An old Ubuntu from years ago is acting up. If you set up WSL long ago, it may be outdated or half-configured. The quickest fix is often to skip WSL and use the native Windows install instead.
• bad interpreter: /bin/bash^M. A file was saved with Windows line endings. Inside Ubuntu, run sudo apt install dos2unix, then dos2unix followed by the file name.
• Login or certificate errors after your PC wakes from sleep. WSL's clock has drifted. Run wsl --shutdown in PowerShell, then open Ubuntu again. This restarts WSL and resets its clock.
• Everything feels slow inside a project folder. Your files are probably under /mnt/c/, which is your Windows drive. Keep Hermes work inside your Linux home folder (~) instead.

When in doubt, the official Hermes Agent docs are the best source. They have a full Windows (Native) guide and a Windows (WSL2) guide, and installer details can change between versions.

Key Takeaways

• Hermes installs with one command on macOS, Linux, and Windows. On Windows, the native PowerShell install is the simplest path. WSL2 is optional. No coding background needed.
• After installing, you connect a language-model backend: Nous Portal, OpenRouter, a custom endpoint, or local vLLM.
• Cloud backends cost a small amount per action and send prompts to the provider; local vLLM keeps thinking on your machine but needs stronger hardware.
• Start with the terminal interface by typing hermes, then connect a messaging platform later.
• All of Hermes's data lives locally (~/.hermes/, or %LOCALAPPDATA%\hermes\ on native Windows), which you can inspect and back up.
• Most install problems are fixed by opening a new terminal, using the right command for your system, or running hermes doctor.