Hermes Agent App

Hermes Agent Install and Configuration

Guide Clean setup guide for Windows and macOS. Built from the official Hermes Agent documentation and repository on 17 May 2026. What this guide covers

• Install Hermes on macOS using the official one-line installer.

• Install Hermes on Windows using either WSL2, the safer route, or native PowerShell, which the official docs

currently mark as early beta.

• Run first-time setup, select AI providers and models, configure terminal backends, enable safer Docker execution,

and add skills, memory, and MCP integrations.

• Keep the setup clean: secrets in ~/.hermes/.env, non-secret settings in ~/.hermes/config.yaml, and no random

global Python installs. Recommended setup System Best path Why

macOS

Official one-line installer Directly supported by the official POSIX installer.

Windows

WSL2 one-line installer

Most battle-tested Windows route according to the official

install page. Windows native

PowerShell installer

Works for common paths, but is still early beta.

1. Install on macOS

Open Terminal and run the official installer. It clones the repo, creates the Python environment, installs dependencies, and makes the hermes command available.

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

bash Restart Terminal after install, then verify the command is available.

hermes doctor
hermes --help

If hermes is not found, reload your shell profile or open a new terminal window.

source ~/.zshrc
# or
source ~/.bashrc

Optional developer install

Use this only if you plan to modify Hermes source code.

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

./setup-hermes.sh ./hermes

1. Install on Windows

Path A: WSL2 recommended

Install Ubuntu in WSL2, open the Ubuntu terminal, then run the same official Linux/macOS installer. wsl –install

# restart Windows if prompted
# open Ubuntu, then run:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh |

bash

hermes doctor

Path B: native Windows PowerShell beta

Open PowerShell as your normal user. The official native installer handles uv, Python 3.11, Node.js 22, ripgrep, ffmpeg, and portable Git Bash. After install, open a new PowerShell window so PATH refreshes.

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

Native Windows feature note

The official docs say native Windows supports the CLI, gateway, cron scheduler, browser tool, and MCP servers. The dashboard chat terminal pane is WSL2-only because native Windows lacks the POSIX PTY behavior it needs.

1. First-time Hermes setup

Run the setup wizard first. It walks through model provider credentials, defaults, tools, and other core settings.

hermes setup

Then choose or change your main model any time with the model picker.

hermes model

Start a chat session.

hermes
# or
hermes chat

Useful maintenance commands

hermes doctor # diagnose missing dependencies or config
hermes config # view current config
hermes config edit # open ~/.hermes/config.yaml
hermes config check # check for missing options after updates
hermes config migrate # add missing config options interactively
hermes tools # enable or disable available tools

1. Where Hermes stores configuration

Hermes keeps user settings in ~/.hermes. Keep secrets separate from normal settings.
~/.hermes/

config.yaml # model, terminal backend, tools, compression, memory, skill settings .env # API keys, bot tokens, passwords, provider secrets

auth.json # OAuth provider credentials

SOUL.md # primary agent identity

memories/ # persistent memory skills/ # installed or agent-created skills cron/ # scheduled jobs sessions/ # gateway sessions logs/ # diagnostic logs Rule: use hermes config set when possible. It automatically routes API keys to .env and regular settings to config.yaml.

hermes config set OPENROUTER_API_KEY sk-or-...
hermes config set terminal.backend docker

1. Configure AI providers and models

Hermes has a main model and auxiliary models. The main model handles normal agent reasoning and tool loops.

Auxiliary models handle side jobs like vision, web extraction, compression, title generation, approval scoring, session search, skill search, and MCP tool routing. Fast path

hermes model

Pick a provider, authenticate, then select a model. The choice is written to ~/.hermes/config.yaml and new sessions use it. Example config structure

model

provider: openrouter default: anthropic/claude-opus-4.7 base_url: '' api_mode: chat_completions Configure auxiliary models Use cheaper, faster models for side tasks. This is useful when your main model is expensive or reasoning-heavy.

hermes model
# choose: Configure auxiliary models

Common production pattern

auxiliary

vision

provider: openrouter model: google/gemini-2.5-flash

web_extract

provider: openrouter model: google/gemini-2.5-flash

compression

provider: openrouter model: google/gemini-3-flash-preview

title_generation

provider: openrouter model: google/gemini-3-flash-preview Inside a running chat, switch the current session with a slash command. Add –global if you also want to persist it for future sessions.

/model gpt-5.4 --provider openrouter
/model gpt-5.4 --provider openrouter --global

1. Configure terminal execution

The terminal backend decides where shell commands run. Local is easiest, Docker is safer, SSH is useful for remote machines, and cloud sandboxes are useful for isolated compute.

terminal

backend: local # local | docker | ssh | modal | daytona | vercel_sandbox | singularity cwd: '.' timeout: 180

Safer Docker backend

Use Docker when you want the agent to work in an isolated environment instead of directly on your files. Install

Docker Desktop first on macOS or Windows, then set the backend.
hermes config set terminal.backend docker

Recommended Docker config for projects

terminal

backend: docker docker_image: nikolaik/python-nodejs:python3.11-nodejs20 docker_mount_cwd_to_workspace: true docker_run_as_host_user: true

docker_forward_env

• GITHUB_TOKEN

container_cpu: 2 container_memory: 8192 container_persistent: true Only forward credentials the agent truly needs. Any variable in docker_forward_env becomes visible inside the container session.

1. Configure tools

Use the tool settings to reduce risk. Disable tools you do not need, especially when using the local backend.

hermes tools

Practical baseline

• For normal personal use, keep file, shell, browser, and web tools enabled only when you need them.

• For client work, prefer Docker backend before giving the agent terminal or file-write access.

• For risky experiments, create a separate project directory and run Hermes from that folder.

1. Configure memory

Hermes can use persistent memory so the agent remembers useful context across sessions. Configure it with the

memory setup command.

hermes memory setup

Hindsight memory provider example

hermes memory setup # select hindsight
# cloud mode manual example:
hermes config set memory.provider hindsight

echo 'HINDSIGHT_API_KEY=your-key' >> ~/.hermes/.env

1. Configure skills

Skills are reusable instructions and workflows. Hermes can browse official optional skills and install skills from supported registries, GitHub repos, and direct SKILL.md URLs.

hermes skills browse --source official
hermes skills install official/security/1password
hermes skills search react --source skills-sh
hermes skills inspect skills-sh/vercel-labs/json-render/json-render-react
hermes skills install openai/skills/k8s
hermes skills tap add myorg/skills-repo

Security note

Hub-installed skills are security-scanned. Use –force only after reviewing a non-dangerous warning. Dangerous scan verdicts should not be overridden.

1. Configure MCP servers

MCP lets Hermes connect to external tools and servers. Exact setup depends on the MCP server. Keep MCP credentials in ~/.hermes/.env and keep server configuration in config.yaml or the relevant Hermes integration settings. General pattern

# 1. Install or run the MCP server
# 2. Add required API keys to ~/.hermes/.env
# 3. Register the MCP server in Hermes settings
# 4. Restart the session or gateway
# 5. Test with a low-risk command before using it on real projects

1. Configure project context

Add an AGENTS.md file in a project folder to tell Hermes how to work inside that repo. This is useful for code style, testing rules, deployment notes, and commands the agent should or should not run.

# AGENTS.md

Project rules

• Use pnpm, not npm.
• Run pnpm test before final changes.
• Do not modify production secrets.
• Ask before running migrations.
• Keep generated assets inside ./outputs.

1. Clean final checklist

• Run hermes doctor and fix every reported issue.

• Run hermes model and confirm your main model is selected.

• Set auxiliary models if your main model is expensive.

• Use Docker backend for safer coding or automation tasks.

• Run hermes tools and disable anything you do not need.

• Keep keys in ~/.hermes/.env, not inside project files.

• Create AGENTS.md in important repos so the agent follows your workflow.

Official sources checked

Hermes Agent official installation docs: hermes-agent.nousresearch.com/docs/getting-started/installation
Hermes Agent official configuration docs: hermes-agent.nousresearch.com/docs/user-guide/configuration
Hermes Agent official model configuration docs: hermes-agent.nousresearch.com/docs/user-guide/configuring-models

NousResearch/hermes-agent GitHub repository README and documentation files