Installing Hermes and Configuring OmniProxy

Hermes is an assistant that can retain conversations and task experience, turning completed work into skills that can be reused later. Through a single Gateway, it can also connect to Telegram, Discord, Slack, WhatsApp, Signal, and the terminal. The Gateway serves as a unified entry point for receiving and forwarding messages. You can send it code reviews, incident notes, or customer materials from your usual chat tools, then have it return to the repository and continue working.

Before You Start

First, choose an installation method based on your computer’s operating system. macOS and Windows can use graphical installers directly, while Linux, macOS, and WSL2 can use a terminal script. WSL2 is a Windows feature for running a Linux environment. Termux on Android phones and Docker have their own installation methods, but this guide covers only installation on regular computers.

Want a window

macOS, Windows

• macOS: open the DMG
• Windows: open the installer
• Install the app on the system

Terminal only

Linux, macOS, WSL2

• One install.sh command
• Use install.ps1 on Windows
• Enter hermes after installation

Do not use these yet

pip, brew, AUR

• These installation methods are not officially supported
• They are also difficult to update after installation
• Use one of the two options on the left instead

Before you begin, prepare a macOS, Windows, or Linux computer and make sure it can open a terminal and access GitHub. If you plan to install Hermes on an external drive, connect the drive first and confirm that it has enough free space.

Install and Launch for the First Time

If You Want a Graphical App

Go to the download section on the Hermes website and download the installer for your operating system. The installer already includes the runtime environment, so nothing needs to be compiled locally when you open it for the first time.

• macOS: Open the DMG and move Hermes.app into Applications. A DMG is an installation image commonly used on macOS. This installer supports Apple silicon only; Intel Macs are not supported.
• Windows: Open the .appinstaller file with Windows App Installer. It installs a signed MSIX, a type of application package used by Windows.
• Linux: The desktop installers are for macOS and Windows. On Linux, use the terminal command below. After installation, you can run hermes desktop.

If You Only Need the Terminal

If you use Linux, macOS, or WSL2, run this in a terminal:

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

When using the PowerShell included with Windows, run:

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

The installer downloads the Hermes code and the programs required to run it. If the download is interrupted, run the same command again. After installation finishes, close the current terminal, open a new window, and enter:

hermes

If you see the Hermes prompt, the command is ready to use. You can then run hermes doctor; this installation check tells you what is still missing.

Store the Program on an External Drive

On October 9, 2026, Hermes Agent v0.21.6 was installed on an external drive connected to a Mac. The program was stored at /Volumes/AItools/tools/hermes-agent, the launcher command was located at ~/.local/bin/hermes, and configuration and conversation data remained in ~/.hermes.

If your drive has a different name, replace the path after --dir with your own folder. The drive must remain connected while Hermes is running.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh -o install.sh
bash install.sh --dir /Volumes/AItools/tools/hermes-agent --non-interactive

Program

External drive

• tools/hermes-agent
• Keep the code here

Command

~/.local/bin/hermes

• Enter hermes in the terminal
• It takes effect after opening a new window

Configuration and chats

~/.hermes

• config.yaml is here
• Exit before disconnecting the drive

Get Connection Values from OmniProxy

Here, Hermes connects to OmniProxy rather than directly to Grok or Gemini. Configure the Grok and Gemini service URLs in OmniProxy; do not enter them directly in Hermes.

Your computer

Hermes

→

Local gateway

OmniProxy

• Include /v1 in the address

→

Grok

• grok-4.7

Gemini

• gemini-3.8-flash

A model ID is the exact name the API uses to identify a model. Use the following names for the two models:

• For Grok, enter grok-4.7. The xAI API is https://api.x.ai/v1, and chat requests use /v1/chat/completions. See the Grok model documentation.
• For Gemini, enter gemini-3.8-flash. Google’s OpenAI-compatible API is https://generativelanguage.googleapis.com/v1beta/openai/. See Gemini’s OpenAI compatibility documentation.

To switch Hermes to Gemini, only change the model name to gemini-3.8-flash. Continue using the OmniProxy address as the API endpoint.

Copy the endpoint URL and key from OmniProxy, then enter the corresponding model ID:

Base URL: https://your-omniproxy-origin.example/v1
API Key:  <YOUR_OMNIPROXY_API_KEY>
Model ID: grok-4.7

Base URL is the endpoint to which Hermes sends requests. It must end with /v1 here. API Key is the key OmniProxy issues to Hermes. Replace the placeholder with your own value, and do not publish it on a public page.

If your local OmniProxy instance does not require a key, you can leave API Key empty. If the address is accessible to anyone else, you should use a key. Also confirm that the address is reachable from the environment where Hermes runs. If Hermes and OmniProxy are on the same computer, you can use a local address.

Enter the Tool Configuration

First, exit the current chat, then run this in a terminal:

hermes model

Select Custom endpoint (self-hosted / VLLM / etc.). Custom endpoint means that Hermes connects to a service address you specify instead of using a preset provider.

The setup wizard asks for the endpoint URL, key, and model name in sequence. Enter the three values from the previous section. To use Gemini, enter gemini-3.8-flash as the model name.

You can also edit ~/.hermes/config.yaml directly. YAML is a text format that uses indentation to represent configuration relationships. The following configuration uses Grok:

model:
  default: grok-4.7
  provider: custom
  base_url: https://your-omniproxy-origin.example/v1
  api_key: <YOUR_OMNIPROXY_API_KEY>

To use Gemini, change default to gemini-3.8-flash and leave the other three values unchanged:

model:
  default: gemini-3.8-flash
  provider: custom
  base_url: https://your-omniproxy-origin.example/v1
  api_key: <YOUR_OMNIPROXY_API_KEY>

After saving, run hermes again and start a new chat. In an already open session, /model can only switch between providers that have already been saved; it cannot add this configuration.

Verify with a Real Task

1

hermes doctor

• Installation check passes

2

Send a short message

• See a reply from Hermes

3

Open the request logs

• Verify the model name

1. Run hermes doctor to check whether the installation is complete.
2. Run hermes and ask it to explain in one sentence what it can do. You should see a response.
3. Open the OmniProxy request log, confirm that the request came from Hermes, and check whether the model name is grok-4.7 or gemini-3.8-flash.

Seeing that the setup wizard saved successfully, or that the API returned a successful response, is not enough to show that Hermes can complete tasks for you. The model name in the request log must match the value you entered.

To chat in a browser, run the following locally:

hermes dashboard --no-open --host 127.0.0.1 --port 9119

Then open http://127.0.0.1:9119. This address works only on the current computer.

Common Errors

• Entering hermes reports that the command cannot be found: Close the terminal and open a new window. If the command is still not found, confirm that ~/.local/bin is in PATH. PATH is the list of directories where the system looks for commands. On Windows, confirm that the launch directory added by the installer is in PATH.
• The installation download stops partway through: Run the same installation command again. The parts already downloaded will be reused.
• Hermes does not respond or reports that it cannot connect: Confirm that OmniProxy is running and check that Base URL ends with /v1. If Hermes runs in Docker while OmniProxy runs on the host, do not use 127.0.0.1 if it is only valid inside the container.
• A key error appears: Update the OmniProxy key, then change api_key in config.yaml. The xAI or Google key belongs in OmniProxy’s provider settings; do not enter it in this Hermes field.
• The model is reported as unavailable: Open the current model list in OmniProxy and copy grok-4.7 or gemini-3.8-flash exactly as it appears in the list.
• Hermes responds but cannot perform tasks such as reading files or executing commands: Switch to another model in OmniProxy that has those capabilities, then start a new Hermes session.
• The program is on an external drive, and hermes doctor reports a storage error after the drive is disconnected: Reconnect the drive first. Do not let Hermes create a separate configuration while the drive is disconnected.

References

For installation steps, see the Hermes installation documentation and platform support. For Custom endpoint configuration, see the Hermes Provider documentation. For the model IDs, see the Grok model documentation and Gemini’s OpenAI compatibility documentation.

The macOS installation process was completed on 2026-10-09 using Hermes Agent v0.21.6. grok-4.7 and gemini-3.8-flash were the standard model IDs in the xAI and Google documentation on that date. When entering the values, use the names displayed in OmniProxy.

Replace every placeholder with values from your own OmniProxy configuration. Never publish a real key.

A saved result or HTTP 200 alone does not prove full Agent compatibility. Check the source and model in OmniProxy's call record.

Official sources · Hermes ↗