Installing and Configuring Hermes Agent

Installing the CLI

Hermes ships a single install script per platform. No package manager dance, no manual dependency resolution.

Linux, macOS, WSL2, or Android via Termux:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc   # or source ~/.zshrc, depending on your shell

Windows (native PowerShell):

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

Both installers put a hermes binary on your PATH and, unless you pass a CLI-only flag, install Hermes Desktop alongside it. Verify the install before doing anything else:

hermes --version
hermes doctor

hermes doctor is the single most useful command in this entire course. It validates your configuration end to end, provider credentials, terminal backend availability, MCP server reachability, and tells you exactly what’s broken instead of leaving you to guess from a stack trace. Run it any time something feels wrong.

Running Setup

A fresh install has no model configured yet. hermes setup walks you through three modes:

hermes setup

If you already have a Nous Portal subscription, skip the wizard’s provider question entirely:

hermes setup --portal     # OAuth + provider + gateway, in one command

For this course, Quick Setup is the fastest path to a working agent. You will revisit hermes model in Module 2 to add and switch between providers deliberately.

Where Configuration Actually Lives

~/.hermes/.env          # secrets: API keys, OAuth tokens
~/.hermes/config.yaml   # everything else: model, provider, terminal backend, MCP servers
~/.hermes/skills/       # skills the agent has written or you have added

A minimal config.yaml after Quick Setup looks like this:

model:
  provider: "nous-portal"
  default: "claude-sonnet-5"

terminal:
  backend: "local"

agent:
  disabled_toolsets: []

You can edit this file directly, or change values from the CLI without opening an editor:

hermes config set model anthropic/claude-opus-4.6
hermes config set terminal.backend docker

Common pitfall: committing ~/.hermes/.env to a dotfiles repository. It contains raw API keys and OAuth tokens. Only config.yaml is safe to version-control or share when asking for help.

First Chat

Launch the interface with either the classic CLI or the newer terminal UI:

hermes            # classic CLI
hermes --tui       # terminal UI, recommended for longer sessions

A few commands you will use in nearly every session from here on:

hermes --continue        # or hermes -c, resumes your most recent session
hermes sessions list      # see all past sessions
hermes tools               # inspect which tools are currently loaded
hermes gateway status      # check the messaging gateway (Module 6)

Hermes Agent requires a model with at least 64,000 tokens of context. If you point it at a smaller local model in Module 2, keep this floor in mind, undersized context windows are the most common source of confusing tool-call failures for newcomers self-hosting a small model.

Exercise: run hermes setup with Quick Setup, then hermes --tui and ask the agent to “list the files in the current directory and summarize what kind of project this looks like.” Confirm it actually executes a shell command rather than guessing from the file names alone, that’s your first look at the tool-calling loop you’ll build on in Module 3.