.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
You installed Hermes Agent and now your shell says hermes: command not found. This is the number one post-install problem in the community. In most cases the install worked fine. The shell just doesn't know about the new binary yet.
I'll walk through the fixes from fastest to slowest. If you're in a hurry, the first one solves it 90% of the time.
Why "hermes: command not found" happens
The Hermes installer puts the hermes binary in one of two locations:
~/.local/bin/hermesfor the per-user install (default on most Linux distros)~/.hermes/hermes-agent/venv/bin/hermeswhen the install uses a virtual environment
Both of these need to be on your shell's PATH. On Ubuntu and Debian, ~/.local/bin is added to PATH only when a login shell reads your profile. If you ran the install in a terminal that was already open, your shell never re-read the profile. The binary is there, the shell just won't find it by name. Easy mistake. The Nous installation docs mentions this but it's burried near the bottom.
Reload your shell PATH (the 90% fix)
Just source your shell config in the current terminal:
source ~/.bashrcIf you're on zsh:
source ~/.zshrcThen check:
hermes --versionIf you see a version string, you are done. Open a new terminal tab to make sure the PATH is set for future sessions too.
Fish shell users
Fish doesn't use bashrc. Your file is ~/.config/fish/config.fish and you also need to check the fish_user_paths universal variable:
fish_add_path ~/.local/binWhat to do when source doesn't fix it
If sourcing your config still doesn't bring hermes into scope, the binary may be somewhere unexpected or your profile may not export the right directory.
Find where the binary is installed
ls -la ~/.local/bin/hermes 2>/dev/null
ls -la ~/.hermes/hermes-agent/venv/bin/hermes 2>/dev/null
echo $PATH | tr ':' '\n'First two commands tell you where the binary lives. Third command shows the directories your shell is searching. Compare. If the binary's directory is not in PATH, that is the problem.
Add the binary's directory to PATH
Append this to your shell config:
export PATH="$HOME/.local/bin:$PATH"For zsh it goes in ~/.zshrc. For bash on Debian/Ubuntu it should go in ~/.profile so that login shells (used by systemd, cron, ssh non-interactive) pick it up too. If you only put it in ~/.bashrc the gateway will work when you start it manually but break under systemd. Common gotcha.
If you installed into a venv
Some installs land the binary inside a virtualenv at ~/.hermes/hermes-agent/venv/bin/hermes. You can add that venv bin to PATH the same way as above, or create a thin wrapper script in ~/.local/bin:
cat > ~/.local/bin/hermes << 'EOF'
#!/usr/bin/env bash
exec "$HOME/.hermes/hermes-agent/venv/bin/hermes" "$@"
EOF
chmod +x ~/.local/bin/hermesThe wrapper survives Hermes upgrades that rebuild the venv. I prefer this on my own boxes becuase I don't want to update PATH every time the venv path changes.
macOS specific notes
On macOS the default shell since Catalina is zsh. Your file is ~/.zshrc. If you upgraded from older macOS you may still be on bash, in which case use ~/.bash_profile.
Multiple Python installs problem
macOS users sometimes have Python from Homebrew, pyenv and the system all installed. The Hermes installer can pick one Python while your PATH points to another. To check, run:
which python3
head -1 ~/.local/bin/hermesIf the shebang at the top of the hermes file points to a Python that no longer exists (e.g. you removed Homebrew Python after install), the launcher fails before showing any usefull error. Reinstall Hermes and pin a single Python.
WSL2 specific notes
On WSL2 the same PATH logic applies but Windows can complicate things via interop. If you run hermes from PowerShell, Windows routes the call to WSL. Make sure to test from a real WSL terminal first (Windows Terminal, Ubuntu profile) before debugging anything on the Windows side.
If hermes gateway start works in your terminal but fails when started by systemd inside WSL, the systemd unit needs an explicit Environment="PATH=..." entry. Our Hermes systemd setup tutorial shows the right unit format.
About native Windows installs
Hermes Agent does not run natively on Windows. If you ran the install script in PowerShell or CMD and got hermes not found, the install never placed a working binary on your system. You have two options: install Hermes inside WSL2, or use the Hermes Desktop GUI app. Our Hermes on Windows comparison explains both paths in detail.
Verify the install with hermes doctor
After PATH is fixed, run:
hermes doctorDoctor checks Python version, network reachability, provider config, write permissions on the data dir and several other things. It will tell you what else needs to be fixed before chat works. Skipping this step usually means finding those issues one at a time over the next hour. Five seconds of doctor saves a lot of time.
If doctor complains about no provider configured, see our separate guide on no inference provider configured.
Clean reinstall if nothing else works
Occasionally an install ends in a half-broken state. The binary exists but launching it does nothing or hangs. Back up your session history first if you have any, then wipe and reinstall:
# back up state.db before deleting anything
cp ~/.hermes/state.db ~/state.db.backup
# remove install
rm -rf ~/.hermes
rm -f ~/.local/bin/hermes
# re-run the official installer (get the command from Nous docs)For proper backups of state.db (not just cp) see our Hermes Agent backups tutorial. A live SQLite file shouldn't be copied with cp, you can corrupt it.
Skip all the install steps with a LumaDock VPS
If you want to skip the install process entirely, the LumaDock Hermes Agent VPS template comes preinstalled with hermes on the PATH, the data directory ready and the dashboard set up. Plans include unmetered bandwidth and no setup fees, which helps if you're spinning up and tearing down test instances often. The end-to-end setup is covered in our Hermes Agent complete guide.
