Install Hermes and Run It for the First Time

This is the hands-on lesson. You will install Hermes Agent, connect it to a language model so it can think, and start it for the first time. There are two ways to install it: a desktop app you download and open like any other app, or a single command in a terminal. Both are beginner-friendly. Take it slowly and read each step before you do it.

What You'll Learn

• The two ways to install Hermes, and which one fits your computer
• How the desktop app sets itself up with a free trial model
• How to connect a language model, including free local models that run on your own computer
• How to start Hermes and say hello for the first time
• Where your data is stored and how Hermes stays up to date

Before You Start: Pick Your Install

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

	Desktop app	Command line
Best for	Beginners who prefer clicking to typing	Linux, older computers, or anyone happy in a terminal
Windows	Windows 11 (version 22H2 or newer)	Windows 10 or 11
Mac	Macs with Apple silicon (M1 or newer)	Any recent Mac
Linux	No standard download; use the command line	Yes
First model	Free trial model built in, no API key needed	You connect a model during setup

If your computer fits the desktop column, start with the desktop app. If it does not (Windows 10, an Intel Mac, or Linux), use the command line. You end up with the same Hermes either way.

You will also need access to a language model. Hermes orchestrates, but the actual thinking comes from a large language model. The desktop app gives you a free trial model to start, and Step 2 covers the longer-term options, including free models that run on your own machine.

No coding background required.

Step 1, Option A: Install the Desktop App (Easiest)

1. Go to the official Hermes Agent website, hermes-agent.nousresearch.com, and download the desktop app for your system.
2. Install it:
   • Windows: Open the downloaded .appinstaller file. Windows App Installer installs Hermes for you. Hermes is also listed in the Microsoft Store.
   • Mac: Open the downloaded DMG file and drag Hermes into your Applications folder.
3. Open Hermes like any other app.

The desktop app is a signed package that already includes everything Hermes needs, so the first launch does not build anything, and it updates itself. Then jump to Step 2.

Step 1, Option B: Install From the Command Line

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

macOS or Linux

Open your terminal (the Terminal app on a Mac) 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 (Native, Recommended)

Hermes runs directly on Windows 10 and 11. You do not need WSL, Docker, or admin rights.

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://hermes-agent.nousresearch.com/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 desktop app or the native path above. Most WSL problems come from old or half-finished WSL setups, so the other paths avoid 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

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: First Launch and Connecting a Model

If You Installed the Desktop App

The first time you open the app, Hermes starts a short setup chat instead of a settings screen. One card at a time, it asks your name, a color and a layout, which apps to connect, and which plugins to install. Then it gives you a quick tour and suggests a few first tasks.

This setup chat runs on a free trial model, so you do not need an account or an API key to get started. The trial is a one-time welcome, once per user account on your computer. To keep using Hermes after that, connect a model from the list below. If you want to skip the setup chat, click Skip setup. You can bring it back later from Settings → Run onboarding again.

If You Installed From the Command Line

The command line has no free trial model, so you connect one right away. Interactive installs walk you through setup at the end. If you skipped it, run:

hermes model

This opens a menu where you pick a provider. The fastest path, according to the official docs, is hermes setup --portal, which signs you in to Nous Portal and sets everything up in one go.

Your Model Options

Hermes supports several kinds of model, so you can pick what fits your budget and privacy needs:

• Nous Portal. The first-party option from Nous Research. You sign in with a "log in with..." style flow, and one subscription gives you access to many models.
• 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.
• Local models, in one click. Hermes can run open models entirely on your own computer, with no account and no API key. It installs the engine for you, checks your graphics card and memory, and picks the best model that fits. Open Settings → Providers → Local Models in the desktop app, or run hermes model and choose Local models in a terminal. Models are big downloads (often several gigabytes), and they run best on a computer with a good graphics card or plenty of memory.
• A custom endpoint or your own local server. If you already use a provider that follows the common OpenAI-style API, or you run Ollama or LM Studio, you can point Hermes at it. This is for later, once you are comfortable.

For most beginners: try Hermes with the desktop trial, then pick Nous Portal or OpenRouter for the strongest models, or local models if privacy matters most and your computer can handle it.

A note on cost and privacy. With a cloud option (Nous Portal, OpenRouter, or a hosted endpoint), your prompts are sent to that provider, and you pay it for usage, usually a small amount per action. Local models keep everything on your machine and cost nothing per action, but they are slower and less capable than the top cloud models unless you have strong hardware. There is no single right answer. Pick based on your budget, your computer, and how sensitive your data is.

Step 3: Start Hermes and Say Hello

If you use the desktop app, you are already in a chat window. If the app feels busy, turn on Simple mode to make it a plain chat.

If you installed from the command line, start the built-in terminal interface 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.

There is also a gateway, which lets you talk to Hermes from a messaging app. Once you set it up and connect a platform, you can message Hermes from Telegram, Discord, Slack, WhatsApp, or Signal, just like messaging a contact. Start with the desktop app or terminal to confirm your install works, and 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\.

Step 5: Keep Hermes Up to Date

Hermes now ships tested, stable releases, and installs follow those by default.

• Desktop app: it updates itself.
• Command line: run hermes update now and then.

Updates bring security fixes, so do not skip them. The safety lesson later in this course comes back to this.

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.
• "API key not set", or Hermes starts but cannot think. No model is connected yet. Run hermes model and pick a provider or a local model. In the desktop app, open Settings → Providers.
• Your desktop trial has ended. That is expected. The free trial model is a one-time welcome. Connect Nous Portal, OpenRouter, or a local model to keep going.
• Something else looks broken. Run hermes doctor. It checks your install and tells you what is missing.

The Desktop App

• Windows will not install the app. The desktop app needs Windows 11 version 22H2 or newer. On Windows 10, use the native command-line install instead.
• Your Mac will not open the app. The desktop app is built for Macs with Apple silicon (M1 or newer). On an older Intel Mac, use the command-line install instead.

On Windows (Native Command Line)

• 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 Option B.
• 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 desktop app or 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 cover the desktop app, the Windows (Native) and Windows (WSL2) installs, and every setup command, and details can change between versions.

Key Takeaways

• There are two ways to install Hermes: the desktop app (Windows 11 22H2+ or an Apple silicon Mac) or one command in a terminal (macOS, Linux, Windows 10 and 11). No coding background needed.
• The desktop app opens with a guided setup chat on a free trial model, so you can try Hermes before you have an API key.
• To keep using Hermes, connect a model: Nous Portal, OpenRouter, a custom endpoint, or free local models that Hermes installs in one click.
• Cloud models cost a small amount per action and send prompts to the provider; local models keep everything on your machine but need a capable computer.
• All of Hermes's data lives locally (~/.hermes/, or %LOCALAPPDATA%\hermes\ on native Windows). The desktop app updates itself; on the command line, run hermes update.
• Most install problems are fixed by opening a new terminal, running hermes model to connect a model, or running hermes doctor.