How to Install Hermes Agent Locally

Step-by-step setup

1. Pick the right install path

Use WSL2 on Windows if you want the smoothest Windows experience. Hermes can run natively on Windows, but the official docs still label that path as early beta, and the Linux-style installer inside WSL2 is the safer first choice for most readers.

Use the macOS/Linux path if you are already on a Unix-style terminal. macOS does not need WSL; open Terminal and use the same one-line installer shown below.

Use native Windows only when you intentionally want Hermes outside WSL2 and you are comfortable with beta behavior.

2. Install WSL2 on Windows if needed

On Windows, open PowerShell as administrator and run:

wsl --install

Microsoft documents this as the current one-command WSL installation path in its official WSL install guide. It enables the required Windows features and installs Ubuntu by default. If your Windows build is older or the one-command installer does not work, use Microsoft's manual WSL installation steps.

After restart, open Ubuntu from the Start menu and create the Linux user account when prompted. Then update the package list and install basic tools:

sudo apt update
sudo apt install -y curl git ca-certificates

Success looks like this: you have an Ubuntu terminal open, commands run without Windows PowerShell syntax errors, and curl --version plus git --version both return version information.

3. Install Hermes Agent on Linux, macOS, or WSL2

In your Linux, macOS, or WSL2 terminal, run the official GitHub-hosted installer from the Hermes installation docs:

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

Wait for the installer to finish. It prepares the Hermes command, runtime dependencies, and local environment for your user account. If the installer prints a message about opening a new shell or reloading your profile, do that before testing the command.

Reload Bash:

source ~/.bashrc

If you use Zsh instead:

source ~/.zshrc

Then run:

hermes setup

Success looks like this: your terminal recognizes the hermes command and the setup wizard starts instead of returning command not found.

4. Choose a model provider

Hermes needs a model provider before it can answer or act. The easiest route is the built-in portal setup:

hermes setup --portal

Use this if you want a guided hosted-provider setup and do not want to wire separate provider keys one by one.

If you prefer local AI, run a local model server such as Ollama and point Hermes to its OpenAI-compatible endpoint during model setup. When Hermes and Ollama run in the same environment, the usual local base URL is:

http://127.0.0.1:11434/v1

If Hermes runs inside WSL2 while Ollama runs on the Windows host, test the endpoint from inside WSL2 before saving it:

curl http://127.0.0.1:11434/v1/models
curl http://host.docker.internal:11434/v1/models

Use the base URL that returns a model list from the same terminal where Hermes runs. Do not guess here; model networking problems are much easier to fix before you add gateways or automations.

You can change the model configuration later with:

hermes model

5. Start Hermes

After setup, start the interactive CLI:

hermes

Run a simple, low-risk prompt first. Do not connect messaging platforms, browser tools, or broad filesystem access until the base chat path works and you know which model endpoint Hermes is using.

6. Native Windows beta option

If you want to install Hermes directly in Windows PowerShell, use the official native Windows beta installer:

iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)

Open a new PowerShell window after installation so your PATH updates. The official docs say the native installer provisions the Windows-side dependencies and stores native Windows data under %LOCALAPPDATA%\hermes.

Use this path when you specifically need native Windows. For a first install, WSL2 is still the cleaner recommendation because the official docs describe it as the more proven Windows route.

Verify it works

Run the health check:

hermes doctor

Then confirm the command is available:

hermes --help

Start the CLI:

hermes

If you use Ollama or another local OpenAI-compatible endpoint, verify the endpoint from the same environment where Hermes runs:

curl http://127.0.0.1:11434/v1/models

For WSL2-to-Windows-host testing, also try:

curl http://host.docker.internal:11434/v1/models

A good first finish line is simple: hermes doctor does not show a blocking install problem, hermes opens the CLI, and your configured model responds to one short prompt.

Common problems

hermes: command not found

Open a new terminal, or reload your shell profile:

source ~/.bashrc

If that does not work, check whether your user PATH includes the directory where the installer placed the Hermes launcher. The official docs also recommend hermes doctor for diagnostics once the command is reachable.

WSL installs but Ubuntu does not open correctly

Run:

wsl.exe --list --verbose

If no distribution appears, return to Microsoft's WSL install instructions and install Ubuntu explicitly. On older Windows builds, use the manual install path.

Native Windows feels unstable

Move the install to WSL2 unless you have a strong reason to stay native. Native Windows support is useful, but it is still marked as early beta in the Hermes docs. WSL2 also keeps the Linux-style data path and shell behavior closer to the main install flow.

Hermes cannot see local Ollama models

Test from the Hermes environment, not from a different terminal. If Hermes runs in WSL2, run the curl test inside WSL2. If Hermes runs natively in Windows, test from PowerShell. If Hermes runs in Docker, remember that localhost means the container itself, not your host machine.

Use the URL that returns JSON model data:

curl http://127.0.0.1:11434/v1/models
curl http://host.docker.internal:11434/v1/models

Setup asks for an API key

Choose a hosted provider path, run:

hermes setup --portal

or configure your provider later:

hermes model

For a local endpoint, use the provider option that supports a custom or OpenAI-compatible base URL. If the wizard requires an API key field for a local endpoint, use the value recommended by the current Hermes setup prompt rather than hard-coding a secret you do not need.

Gateway setup fails

Keep the first install simple. Finish CLI setup and one model response first, then run:

hermes gateway setup

Most gateway failures come from missing tokens, wrong provider URLs, port conflicts, or trying to configure too many channels before the base install is stable.

Next useful actions

Once the CLI works, configure only the next feature you actually need.

For a local-first setup, connect Hermes to Ollama, test one small task, and confirm where your Hermes data is stored before enabling long-running workflows.

For a messaging setup, add one gateway, send one test message, and confirm that the gateway uses the expected model provider. Do not connect Telegram, Discord, Slack, and email all at once on the first day.

For a safer agent setup, create a dedicated workspace folder, avoid administrator/root sessions, and keep secrets out of prompts and screenshots. Treat Hermes memory, generated skills, and gateway tokens as sensitive local data.

For maintenance, learn these commands early:

hermes model
hermes tools
hermes gateway setup
hermes update
hermes doctor

Background, planning, and caveats

Is the official Hermes site legitimate?

Yes, for this guide's purposes, the source chain is consistent. The Nous Research homepage links to Hermes Agent, the Hermes Agent homepage links to its docs, and the docs link to the public NousResearch/hermes-agent GitHub repository. For installation commands, use the official Hermes docs or repository rather than copied commands from old posts.

Which operating system path should you choose?

Choose WSL2 on Windows if you want the easiest path with the fewest surprises. It lets you follow the Linux/macOS installer and keeps most troubleshooting in a normal Linux shell.

Choose macOS/Linux direct install if that is your main machine. You do not need WSL on a Mac. Open Terminal, run the installer, reload the shell, and run hermes setup.

Choose native Windows if you want to test the PowerShell installer and can tolerate early beta rough edges. Native Windows data lives under %LOCALAPPDATA%\hermes, while WSL2/Linux-style installs use ~/.hermes, so the two setups can exist separately.

Choose Android/Termux only if you are intentionally experimenting on Android. Hermes documents a Termux-aware path, but that is not the main recommendation for a first desktop install.

What Hermes Agent is

Hermes Agent is an open-source agent runtime from Nous Research. It is not just a chat window. Depending on how you configure it, Hermes can use model providers, local tools, messaging gateways, scheduled tasks, browser tooling, memory, and generated skills.

That is why this guide installs the base CLI first and delays broader integrations until after verification. The goal is not to turn on every feature quickly. The goal is to get a working local agent, prove the model connection, then add capabilities deliberately.

Where Hermes stores data

For normal Linux, macOS, and WSL2 installs, expect Hermes state under:

~/.hermes

For native Windows installs, the official docs describe the native data location as:

%LOCALAPPDATA%\hermes

Keep this data private. It can contain configuration, local state, memory, generated skill material, and references to connected services. Back it up before major updates if the install has become important to your workflow.

Hosted models vs local models

A hosted provider is usually faster to set up because you do not need to manage local model performance, GPU memory, or local networking. The tradeoff is that prompts and tool outputs may leave your machine depending on the provider and configuration.

A local model stack keeps more work on your machine, but it adds hardware and troubleshooting requirements. If you use Ollama, verify the /v1/models endpoint from the same terminal where Hermes runs before saving that endpoint in setup.

Security checklist

Use a low-risk workspace for the first install. Avoid running Hermes as administrator or root unless you have a specific reason. Connect one model provider first, then one gateway, then one tool category. Keep API keys and messaging tokens out of prompts, screenshots, shared terminals, and public issue reports.

Review generated or downloaded skills before trusting them in sensitive folders. If you enable terminal, browser, or file access, assume Hermes can affect the environment you give it.

Official links worth keeping nearby

Use the Hermes installation docs for the current installer commands, the Hermes docs index for feature-specific guides, and Microsoft's WSL install guide for the Windows Linux layer. These pages should be your first stop if commands change.

Red flags

• You installed native Windows only because it looked shorter, but you actually wanted the most stable Windows path.
• You configured gateways before the CLI and model provider were verified.
• You saved a model endpoint that only works from a different terminal than the one running Hermes.
• You ran the agent as administrator/root without a clear reason.
• You pasted provider keys or messaging tokens into prompts, screenshots, logs, or public support posts.
• You enabled broad filesystem or terminal access before testing in a low-risk folder.

Bottom line

For most Windows users, install WSL2 with wsl --install, open Ubuntu, run the official Hermes Linux/macOS/WSL2 installer, then run hermes setup. For macOS and Linux users, run the same installer directly in Terminal. Native Windows is available, but it is still the beta path, not the first recommendation for a smooth setup.

Once Hermes starts, verify with hermes doctor, test one model response, and only then add gateways, tools, browser features, or persistent workflows. A clean first install is worth more than turning on every capability at once.