Hermes Quick Start — Install, Pick a Model, First Chat

Before you start

• An operating system Hermes supports: Linux, macOS, WSL2 or native Windows. The macOS desktop package is Apple Silicon only; Intel Macs aren't supported. Android works through the Termux package.
• Git, curl and tar for the command-line installer on Linux and macOS. You don't need to install Python or Node yourself: the installer brings its own pinned Python 3.14, Node.js, ripgrep and FFmpeg.
• A model with at least 64,000 tokens of context. Hermes rejects smaller models at startup. Every current hosted model clears this. For a local model, set its context to 64K or more (for Ollama, -c 65536).
• An account with a model provider, or a subscription Hermes can sign in to: Nous Portal, ChatGPT/Codex, Claude Max, SuperGrok, GitHub Copilot and others.

Step 1 — Install Hermes

Desktop app (macOS or Windows): download the package from the Hermes website. On macOS, open the DMG and copy Hermes.app to Applications. On Windows, open the .appinstaller file. The package already contains the agent and its runtime, so first launch doesn't build anything.

Command line only, on Linux, macOS or WSL2:

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

Command line only, on native Windows (PowerShell):

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

The script clones Hermes into ~/.hermes/hermes-agent/, installs a hermes launcher in ~/.local/bin/, and keeps your data in ~/.hermes/. On Windows these live under %LOCALAPPDATA%\hermes\. It also installs a browser for web tools; add --skip-browser to leave it out. An interactive run finishes by launching setup. If the install fails, the last lines and the log path (~/.hermes/logs/install.log) are printed.

Then reload your shell:

source ~/.bashrc    # or: source ~/.zshrc
hermes --version

Installed from the command line and want the desktop app too? Run hermes desktop.

Step 2 — Choose a provider and model

This is the step that matters most. Run the full wizard, or just the model picker:

hermes setup          # full wizard: provider, tools, messaging
hermes model          # just the provider and model
hermes setup --portal # Nous Portal: sign in, pick a model, turn on its hosted tools

On a fresh install, hermes setup offers three modes: Quick Setup (Nous Portal, no API keys), Full Setup (bring your own keys and walk through every option), and Blank Slate. Blank Slate turns on only the model, file tools and terminal. Web, memory, cron, skills, plugins and MCP stay off until you enable them with hermes tools, and hermes update won't turn them back on.

Settings are split across two files. Secrets and tokens go in ~/.hermes/.env, everything else in ~/.hermes/config.yaml. hermes config set writes each value to the right one:

hermes config set OPENROUTER_API_KEY sk-or-...   # goes to .env
hermes config set terminal.backend docker        # goes to config.yaml
hermes config get terminal.backend

Which model?

Any model with 64K+ context works. For an agent that runs tools all day, output price matters more than input price. Prices below are per million tokens, input / output, checked 2026-09-24.

You can switch at any time with hermes model, or mid-session with /model. Rates for 40+ models are in the cost calculator.

Step 3 — Your first chat

hermes          # classic CLI
hermes --tui    # the newer full-screen TUI; same sessions and commands

The banner shows your model, tools and skills. Ask for something you can check, such as "Check my current directory and tell me what looks like the main project file." It's working if Hermes replies, uses a tool when it needs one, and keeps going for more than one turn.

Then make sure sessions resume:

hermes --continue   # or: hermes -c

Useful straight away: type / for the command list, !ls runs a shell command without spending a model turn, and typing a new message while Hermes works redirects it (Ctrl+C also stops it).

Step 4 — Check the install

hermes doctor   # config and dependency problems
hermes status   # agent, auth and platform status

If something is off, work down this list in order: hermes doctor, hermes model, hermes setup, hermes sessions list, hermes --continue, hermes gateway status. Empty or broken replies almost always mean the provider or model is wrong, so re-run hermes model.

Step 5 — Optional: keep it running

You don't need a background process to chat. You need one when Hermes should answer on Telegram or Discord, or run scheduled jobs while you're away. That process is the gateway:

hermes gateway setup     # connect Telegram, Discord, Slack, email…
hermes gateway install   # install as a systemd (Linux) or launchd (macOS) service
hermes gateway start
hermes gateway status

On WSL, use hermes gateway run inside tmux instead of install/start, because WSL's systemd support is unreliable. On a Linux server, the linger fix in our Discord guide keeps the service alive after you log out.

Next: Telegram or Discord, how memory works, skills, and hardening.

Keeping Hermes up to date

hermes update            # pull the latest release and reinstall dependencies
hermes update --check    # preview what would change
hermes update --backup   # snapshot ~/.hermes first

Desktop installs update from the app's Update control, and Docker installs by pulling a new image. The current release is v0.21.5 (tag v2026.9.24). If you're on 0.21.0 or 0.21.1, update now: those builds could report a healthy state.db as corrupt (details).

CLI quick reference

Full list: the official CLI reference.