How to install Hermes Agent

Which install method should you use?

Use the one-line install script for a command-line install, or the Hermes Desktop package if you want the desktop app on macOS or Windows. Both set up the same agent, and the desktop app uses the same data layout as a command-line install.

The macOS desktop installer is for Apple Silicon only. The docs list macOS on Intel processors as an unsupported platform.

How do you install Hermes Agent on Linux, macOS or WSL2?

Run the install script in your terminal, then reload your shell. You need Git, curl, tar and SHA-256 utilities on the machine first.

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

The script clones the source, downloads a verified copy of uv, and lets Hermes' own package manager (PM) provide pinned versions of Python 3.14, Node.js, npm, ripgrep and FFmpeg. You do not need to install Python yourself. By default it also installs the browser tools and the computer-use driver. The script accepts --skip-browser and --skip-computer-use to leave those out, and --non-interactive to skip the setup stages that need input.

On minimal Debian, Ubuntu or RHEL-family images, the managed Node.js needs libatomic. The installer installs the distro package for you and asks for your sudo password once if it needs it.

How do you install Hermes Agent on native Windows?

Open PowerShell and run the Windows installer. Native Windows runs the CLI, the gateway, the TUI and the tools without WSL.

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

The installer provides Python 3.14, Node.js, npm, ripgrep and FFmpeg. If Git is missing, it stages a verified Git for Windows archive in Hermes' tool store without replacing any system Git. Everything goes under %LOCALAPPDATA%\hermes\, and the hermes command lives in %LOCALAPPDATA%\hermes\bin\. The Windows equivalents of the script options are -SkipBrowser, -SkipComputerUse and -NonInteractive.

If you prefer WSL2, run the Linux command inside WSL2 instead. That install lives under ~/.hermes as it would on Linux.

To add the desktop app later, run hermes desktop after a command-line install.

What should you do if Windows Defender flags uv.exe?

Treat it as a false positive. The flagged file, %LOCALAPPDATA%\hermes\bin\uv.exe, is Astral's uv, the Rust-based Python package manager Hermes bundles to manage its Python environment. Machine-learning antivirus engines often flag unsigned Rust binaries that download and install packages.

The Hermes README includes a PowerShell script that downloads the matching uv release, checks its GitHub attestation with gh attestation verify, and compares the file hash with your copy. Once you are satisfied, exclude the folder from scanning. In PowerShell running as Administrator:

Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\hermes\bin"

Exclude the folder, not the file hash, because Hermes updates uv and the hash changes with every version. In Bitdefender, add the exception under Protection > Antivirus > Settings > Manage Exceptions.

How do you install Hermes Agent on Android?

Use the Termux APT package on an aarch64 Android device, not the desktop or server script. You add Hermes' signed repository, then run pkg install hermes-agent. The package includes Python, Node.js and the TUI, and it offers a stable channel and a prerelease canary channel. At the time of writing, the Termux guide carries a notice that the package is not working and a fix is in progress, so read that page before you start.

What should you do right after installing?

Pick a model provider, run one real chat, and check the install. These are the commands you will use most in the first session:

hermes setup      # full setup wizard
hermes model      # choose a provider and model
hermes            # classic CLI
hermes --tui      # newer terminal UI
hermes doctor     # diagnose problems
hermes update     # update a source install

On a fresh install, hermes setup offers three modes:

• Quick Setup (Nous Portal): OAuth login with no API keys to manage.
• Full Setup: you walk through every provider, tool and option with your own keys.
• Blank Slate: only the provider, model, file tools and terminal tools are on. You enable everything else yourself.

Hermes needs a model with at least 64,000 tokens of context. If you run a local model, set its context to 64K or more, for example --ctx-size 65536 for llama.cpp or -c 65536 for Ollama.

Secrets go in ~/.hermes/.env and other settings in ~/.hermes/config.yaml. hermes config set writes each value to the right file:

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

A good rule from the quickstart: get one clean conversation working before you add the messaging gateway, cron jobs, skills or routing.

How do you use Nous Portal instead of separate API keys?

Run hermes setup --portal on a fresh install. It logs you in through OAuth, sets Nous as your provider and turns on the Tool Gateway, which covers web search, image generation, text-to-speech and a cloud browser under one subscription. Check what is connected at any time with hermes portal info. You can still bring your own key for any individual tool.

Where does Hermes Agent store its files?

Hermes keeps its code and your data in separate places, and the HERMES_HOME variable selects the data directory.

Inside the data directory you will find config.yaml, .env, SOUL.md, memories/, skills/ and, once you create them, extra agents under profiles/. The docs warn against deleting the data directory to repair an application install.

How do you fix common install problems?

Most first-day problems have a one-line fix, and hermes doctor tells you what is missing for anything else.

How do you update Hermes Agent?

Run hermes update for a source install made with the script. Other install types update through their own channel: the desktop app's Update control for desktop bundles, pulling a new image and recreating the container for Docker, and pkg update followed by pkg upgrade hermes-agent for Termux. hermes doctor reports which kind of install you have.

FAQ

Sources

• Hermes Agent README (GitHub)
• Installation
• Quickstart
• Hermes on Android with Termux
• Updating & Uninstalling
• Hermes Desktop