Hermes Agent

Hermes Agent: Install and first job

This is page 2 of 8 in the Hermes Agent guide. It installs Hermes on Windows 11 or a Mac, turns on the safety switches before anything else, connects a free model, and gives Hermes one small job in an empty folder.

Facts here were checked on 14 November 2026. Use your everyday account for every step, and do not run Hermes as an administrator, because Hermes runs commands as whatever account starts it.

Install on Windows 11

The desktop app comes first, and it needs Windows 11 version 22H2 or later.

1. Check your Windows version

Open Settings, then System, then About. Look under Windows specifications for Version.

What you should see 22H2 or a newer version. If you see something older, update Windows first, or use the main guide.

2. Download the app

Open the official site: https://hermes-agent.nousresearch.com/

Download the desktop app for Windows. The site also has a Microsoft Store button, and either one is fine.

The site also shows "Download .exe instead." That is Hermes-Setup.exe, a different installer that builds Hermes from source, so use the regular download or the Store.

What you should see a download that ends in .appinstaller, or the Hermes page in the Microsoft Store.

3. Install it

Open the .appinstaller file, and Windows App Installer opens and installs Hermes. If you used the Store, click its install button instead.

What you should see Hermes in your Start menu. When you open it, the Hermes window appears. The app already contains what it needs, so the first launch does not build anything.

If you would rather paste a command

Use this only if the desktop app will not install. Open PowerShell as your everyday account, not as an administrator, and paste:

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

This downloads Python, Node.js, and other tools Hermes needs, and it also adds a web browser and a tool that can drive your real screen. During the install it may ask you to set up a model and a messaging app, but skip the messaging part for now.

If hermes is not found afterward, close PowerShell and open a new window. Hermes's Windows guide says the installer adds hermes to your account's list of program folders, and that windows already open when it finishes do not pick up the change.

Windows Defender may quarantine a file called uv.exe, which means Defender locks the file away. Hermes calls this a false alarm about a tool from a company named Astral.

Only if Defender actually quarantines uv.exe, and only if you downloaded Hermes from the official site: open PowerShell as an administrator once and paste the line below, with your own Windows user name in place of YOURNAME. Close the administrator window right after.

Add-MpPreference -ExclusionPath "C:\Users\YOURNAME\AppData\Local\hermes\bin"

This tells Defender to stop scanning that one folder, which the agent can also write to, so remove the exclusion later with Remove-MpPreference -ExclusionPath and the same path if you stop using Hermes.

What you should see the install finishes with no error. Typing hermes in a new PowerShell window starts a chat.

Install on a Mac

The desktop app is for Macs with an Apple chip.

1. Check your chip

Click the Apple menu, then About This Mac.

What you should see Chip followed by Apple M1, M2, or newer. If it says Processor and Intel, stop here and use the main guide.

Hermes's own pages disagree on the oldest macOS that works. The homepage says macOS 12, while the release notes for version 0.23.0 say macOS 13, and this guide could not confirm which is right. macOS 13 or newer meets both.

2. Download and install

Open the official site: https://hermes-agent.nousresearch.com/

Download the desktop app for macOS. Open the DMG file, which is a Mac installer disk, and drag Hermes.app into Applications.

What you should see Hermes in your Applications folder. When you open it, the Hermes window appears.

If you would rather paste a command

Open Terminal and paste:

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

Like the Windows command, this also adds a web browser and a screen-driving tool, and it may ask about a model and a messaging app, so skip messaging for now. When it finishes, paste:

source ~/.zshrc
hermes

What you should see the install finishes, then a Hermes chat starts in Terminal.

Turn on the safety switches first

Do this before you connect a model, email, or a chat app.

Here is what Hermes does out of the box:

The switches below make it ask you more, but they do not build a wall.

1. Make one folder

Make a new folder called agent-tryout inside Documents, and put nothing personal in it. Add one harmless text file called hello.txt with one sentence in it.

What you should see an agent-tryout folder holding only hello.txt.

2. Open the settings file

Hermes keeps its settings in a plain text file called config.yaml.

If there is no config.yaml, open Hermes once and close it, then look again. This guide could not confirm when Hermes first creates that file.

What you should see a text file with lines like name: value, some of them indented.

3. Change three settings

Make the file contain these lines, using two spaces for each indent. If the file already has a terminal:, approvals:, or skills: line, change the lines under it rather than adding a second copy.

On Windows, replace YOURNAME with your Windows user name:

terminal:
  backend: local
  cwd: C:\Users\YOURNAME\Documents\agent-tryout

approvals:
  mode: manual

skills:
  write_approval: true

On a Mac, use cwd: /Users/YOURNAME/Documents/agent-tryout instead.

What each one does:

Leave backend at local. It sounds odd, but the safer-sounding options, like Docker, turn the approval questions off.

Never use approvals.mode: off, /yolo, or hermes --yolo, because those turn the questions off.

Save the file, then close and reopen Hermes.

What you should see the file saved with those lines, and Hermes opening again with no error.

4. The extra file limit

Hermes has one more limit, called HERMES_WRITE_SAFE_ROOT. When it is set to your folder, it stops Hermes's file-writing tools from saving anywhere else.

It only covers two of Hermes's tools, so a command can still change files outside the folder. This guide could not confirm where the desktop app reads this setting from, so it is not a step here.

5. Keep these off

What you should see no email, bank, or chat bot connected, and no paid key without a cap.

Connect a free model

Hermes reads keys from a file called .env, in the same folder as config.yaml. Open it with Notepad or TextEdit, and add this line with your Gemini key after the =:

GEMINI_API_KEY=paste-your-key-here

If there is no .env file, make a new plain text file with exactly that name. In Notepad, choose Save as type: All files so it does not become .env.txt. Do not paste the key into the chat.

Then pick Gemini as the model. If you used the command install, type hermes model and choose Gemini. In the desktop app, choose Gemini when Hermes asks for a provider, although this guide could not confirm the desktop app's menu names for that.

One warning from Hermes's own docs: a free Gemini key can run out after a handful of jobs, because Hermes may call the model several times for each message you send. If it stops answering, wait for the free limit to reset, or see the model page.

Nous Research also sells its own model plan, Nous Portal. Its free tier is $0 and only has free models, while Plus is $20 a month. Page 1 lists the other plans.

What you should see you type "hello" and Hermes answers.

Or use a local model

First install Ollama and download a model with Run a local model with Ollama. Hermes refuses to start with less than 64,000 tokens of context, so raise Ollama's context length to at least that, as the Ollama page shows.

Type hermes model and choose Custom endpoint (self-hosted / VLLM / etc.). Enter http://localhost:11434/v1 as the URL, skip the API key, and type the model name exactly as ollama list shows it. This guide could not confirm the desktop app's menu names for this setting.

What you should see Hermes starting with no error about the context window, then an answer when you type "hello".

Your first safe job

If you used the command install, start the chat from your new folder. On Windows, paste cd "$env:USERPROFILE\Documents\agent-tryout" into PowerShell, and on a Mac, paste cd ~/Documents/agent-tryout into Terminal. Then type hermes.

Type this:

Read hello.txt in C:\Users\YOURNAME\Documents\agent-tryout (on a Mac, /Users/YOURNAME/Documents/agent-tryout). Write a new file called note.txt next to it, with a one-sentence summary. Do not touch any other folder.

Watch every step. When Hermes asks to run a command, read it first, and approve one command at a time.

Deny anything that:

If you do not answer within 300 seconds, Hermes treats that as no.

There is one gap. If Hermes writes a small Python program to do the job, the docs say that program's file changes in the desktop app or a terminal chat do not ask first. Python is a programming language, and if you see Hermes writing a program for this job, stop it. Page 6 explains how to stop Hermes.

When it is done, open agent-tryout in File Explorer or Finder yourself.

What you should see hello.txt and a new note.txt, and nothing else in that folder.

Sources

Research in this repo:

Official Hermes pages (checked 14 November 2026):

Next

Continue to Files, the browser, and memory.

Checked 14 November 2026 · prices, limits, and versions change