Setup

Install Hermes Agent with a practical setup guide.

Use this Hermes Agent setup guide across the supported environments, then verify the CLI before you spend time on providers, tools, or channel integrations.

Built around Hermes v0.9Updated: 2026-04-18Community guide

Before you start

Clear the basics first.

Hermes setup is easier when you insist on a verified install first. Do not skip the version check; it catches most environment mistakes before they spread.

Official install command

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

Use the upstream installer first. Once it lands, reload the shell and run `hermes --version`. Only after that should you open `hermes setup`.

macOS

The cleanest path if you want the reference install experience with the fewest environment surprises.

1

Run the official installer

The installer handles the core runtime pieces for Hermes so you do not need to wire them together manually.

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

Reload your shell

Refresh the PATH changes so the `hermes` command resolves immediately.

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

Verify the CLI

Make sure Hermes responds before you continue into provider setup.

hermes --version
4

Open the guided setup

Add your provider configuration and produce the first local config file.

hermes setup

Before you run it

  • Use Terminal or iTerm with a normal user account.
  • Install Xcode command line tools first if your shell cannot build small utilities.
  • Keep GitHub reachable because the installer pulls official assets.

What success looks like

  • `hermes --version` returns a version string instead of a shell error.
  • `hermes` opens an interactive session and accepts input.
  • Your config file exists under `~/.hermes/` after setup completes.

If it breaks

  • If the shell still says `command not found`, reload the shell again and check whether `~/.local/bin` is in PATH.
  • If the installer stops early, rerun it after installing Xcode command line tools with `xcode-select --install`.

Linux

Good for server-oriented workflows and for users who want Hermes on the same box as their development environment.

1

Confirm Git is present

The installer assumes Git already exists.

git --version
2

Run the installer

Use the same upstream install command as macOS unless the official Hermes docs say otherwise.

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

Reload the shell and verify Hermes

Confirm the binary is visible from the current session.

source ~/.bashrc
hermes --version
4

Run interactive setup

Store the initial provider settings and create the first working config.

hermes setup

Before you run it

  • Use a distro shell where you can install Git and basic packages.
  • Expect the install script to work best on mainstream Debian, Ubuntu, or Fedora-like environments.
  • Keep a normal user shell open instead of running the entire process as root.

What success looks like

  • The install command completes without a dependency failure.
  • The `hermes` command is available in a new shell session too.
  • You can start a chat after provider configuration.

If it breaks

  • If Git is missing, install it first with your package manager and rerun the installer.
  • If PATH is wrong, export `PATH="$HOME/.local/bin:$PATH"` and persist that in your shell rc file.

Windows with WSL2

Use this when your main machine is Windows. The Hermes path is smoother inside a Linux shell than in native Windows.

1

Install or confirm WSL2

Run the command from an elevated PowerShell window, then reboot if Windows asks for it.

wsl --install
2

Open Ubuntu and finish account setup

Create the Linux username and password before installing Hermes.

3

Run the Hermes installer in Ubuntu

From here the flow matches a normal Linux install.

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

Verify Hermes and run setup

Stay in the Linux shell for both verification and provider configuration.

source ~/.bashrc
hermes --version
hermes setup

Before you run it

  • Enable virtualization in BIOS if WSL2 has not been used on this machine before.
  • Install Ubuntu from the Microsoft Store or with `wsl --install`.
  • Plan to do the Hermes work inside the Ubuntu shell, not in PowerShell.

What success looks like

  • Ubuntu launches cleanly and has outbound network access.
  • Hermes installs inside WSL2 and does not depend on the Windows shell PATH.
  • The first chat runs inside Ubuntu without provider errors.

If it breaks

  • If `wsl --install` fails, confirm virtualization is enabled and rerun PowerShell as administrator.
  • If provider traffic fails from WSL2, check firewall, proxy, and DNS settings inside the Linux shell.

Termux / Android

Best treated as an advanced or opportunistic setup. It can work, but it is less predictable than a desktop shell.

1

Update package indexes

Start by refreshing the package state for the mobile shell.

pkg update
2

Install Git

This is the one dependency to land before you run the Hermes installer.

pkg install git -y
3

Try the official installer

The Termux route is less canonical, but the official command is still the first thing to try.

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

Reload and test

If Hermes starts correctly, continue into provider setup as normal.

source ~/.bashrc
hermes --version
hermes setup

Before you run it

  • Use the modern Termux build from F-Droid or GitHub rather than an outdated store package.
  • Install Git first because the Hermes install script expects it.
  • Disable aggressive battery restrictions if you want to keep Hermes or gateway processes alive.

What success looks like

  • The install script completes without a package or architecture mismatch.
  • `hermes --version` returns in the same Termux session after reload.
  • A short chat succeeds once the provider is configured.

If it breaks

  • If the official script fails, switch to the manual Hermes installation path from the upstream docs.
  • If background jobs die, set Termux to unrestricted battery mode and use `termux-wake-lock` when needed.

Next step

Once Hermes answers back, move into the seven-day route.

The install page gets you to a working CLI. The next page turns that baseline into a week of deliberate practice so the tool does not stay a fresh install forever.

Open the 7-day route