# Hermes Agent Integration Guide

Hermes Agent is an open-source autonomous AI Agent developed by Nous Research. It can run persistently on a server, supports persistent memory, scheduled tasks, parallel sub-agents, and can connect to multiple messaging channels such as Telegram, Discord, and Slack. This guide explains how to use it with the UModelverse platform to call models.

## **System Requirements**

| Platform | Requirements |
| --- | --- |
| Windows | Windows 10 or Windows 11 (must be used via WSL2) |
| macOS | macOS 10.15 (Catalina) or later |
| Linux | Ubuntu 18.04+, CentOS 7+, Debian 9+ |

A network connection is required on all platforms. The installation script will automatically prepare dependencies such as Python and Git.

## **1. Install Hermes Agent**

### macOS / Linux

1.  Run the installation script in your terminal (it will automatically install required dependencies):
    
    ```
    curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
    ```
    
2.  Reload the terminal environment to activate the commands:
    
    ```
    source ~/.bashrc    # If using zsh, change this to: source ~/.zshrc
    ```
    
3.  Check the version number — if it prints normally, the installation was successful:
    
    ```
    hermes --version
    ```
    

### Windows

Native installation on Windows is not currently supported. You must first install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install), then follow the macOS / Linux steps above inside the WSL2 terminal.

## **2. Configure the UModelverse API**

### 2.1 Obtain an API Key

Visit the [UModelverse Console](https://console.ucloud.cn/modelverse/api) to get your API key. For available models, see the [supported models](https://api-us-ca.umodelverse.ai/v1/models) on the UModelverse platform.

### 2.2 Write the Configuration

Hermes uses OpenRouter as its inference source by default. To connect to UModelverse, you need to set `model.provider` to `custom`. You can write each setting using the following commands (replace `YOUR_API_KEY` with your actual key):

```
hermes config set model.provider custom
hermes config set model.base_url https://api-us-ca.umodelverse.ai
hermes config set model.api_mode anthropic_messages
hermes config set model.api_key YOUR_API_KEY
hermes config set model.default qwen3.7-max
```

These commands write the configuration to `~/.hermes/config.yaml`. You can also edit that file directly for the same result:

```
model:
  default: qwen3.7-max
  provider: custom
  base_url: https://api-us-ca.umodelverse.ai
  api_mode: anthropic_messages
  api_key: YOUR_API_KEY
```

> `model.default` is set to `qwen3.7-max` here as an example. You can replace it with any model listed in the [supported models](https://api-us-ca.umodelverse.ai/v1/models) on the UModelverse platform.

## **3. Verify the Configuration**

Send a test message:

```
hermes chat -q "Hello"
```

If you receive a normal reply, the configuration is successful. To temporarily switch models, use the `-m` flag:

```
hermes chat -m claude-opus-4-8
```

## **Frequently Asked Questions**

### Still connecting to OpenRouter after configuration — what should I do?

Hermes routes through OpenRouter by default. To connect to UModelverse, you must change `model.provider` to `custom`. Run the following command to confirm:

```
hermes config set model.provider custom
```

### Getting an authentication failure or connection error — what should I do?

Check the following in order:

1.  The `api_key` field in `~/.hermes/config.yaml` contains a valid UModelverse API Key, copied in full with no extra spaces.
    
2.  `base_url` is set to `https://api-us-ca.umodelverse.ai`, `api_mode` is set to `anthropic_messages`, and `provider` is set to `custom`.
    
3.  `model.default` is one of the models listed in the [supported models](https://api-us-ca.umodelverse.ai/v1/models) on the UModelverse platform — make sure there are no typos and that you are not using a model the platform does not provide.