> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes

> How to install and configure Hermes Agent, and connect to Mixroute API via Custom Endpoint

Hermes Agent is an open-source terminal AI Agent by Nous Research, providing powerful tool calling, file read/write, and code execution capabilities in your terminal. With built-in Custom Endpoint support, Hermes can seamlessly connect to any OpenAI-compatible API — including Mixroute — without writing any code or plugins.

* Official site: [hermes-agent.nousresearch.com](https://hermes-agent.nousresearch.com)
* Quick start: [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)
* GitHub: [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)

## Core Features

<CardGroup cols={3}>
  <Card title="Intelligent Agent" icon="robot">
    Native support for tool calling, file read/write, and code execution with persistent memory
  </Card>

  <Card title="Multi-channel Integration" icon="message">
    Unified messaging gateway for Telegram, Discord, Slack, WhatsApp and more
  </Card>

  <Card title="Open Model Ecosystem" icon="plug">
    Built-in Custom Endpoint support for any OpenAI-compatible API
  </Card>
</CardGroup>

## Prerequisites

<Steps>
  <Step title="Prepare Mixroute Address">
    Get an available Mixroute address, for example: `https://api.mixroute.ai/v1`

    <Note>
      If you need to use native ports, you need to configure according to the endpoints in the API documentation. It is recommended to keep the settings in this guide to avoid errors and issues caused by different endpoints.
    </Note>
  </Step>

  <Step title="Get API Key">
    Generate an API Key in the Mixroute console
  </Step>

  <Step title="Choose a Model">
    Determine the model name you want to use, which must exactly match the model ID in the Mixroute console (e.g., `gpt-5.5`)
  </Step>
</Steps>

<Info>
  Hermes Agent requires the model to support at least 64K tokens context window. Please verify this requirement when selecting a model, otherwise you may encounter context insufficient errors.
</Info>

## Install Hermes Agent

<Tabs>
  <Tab title="Linux / macOS / WSL2">
    * Run the official one-click installation script in your terminal: Choose `Quick setup` mode to deploy and configure core settings. For Provider and Model details, see **Configure mixroute integration**.

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
    ```

    * After installation, reload your terminal environment variables:

    ```bash theme={null}
    source ~/.bashrc	# If using zsh, use source ~/.zshrc
    ```
  </Tab>

  <Tab title="Windows">
    <Warning>
      Hermes Agent does not natively support Windows. You need to install WSL2 (Windows Subsystem for Linux 2) first, then run the Linux/macOS installation command above in the WSL2 terminal.
    </Warning>

    WSL2 installation reference: [Microsoft WSL Installation Guide](https://learn.microsoft.com/windows/wsl/install)
  </Tab>
</Tabs>

<Check>
  Run `hermes --version`. If a version number is displayed, the installation was successful.
</Check>

## Configure Mixroute Integration

This is the most critical step in the integration process. Hermes Agent provides an interactive menu, so you don't need to write any code or manually edit configuration files — just follow the prompts to enter the Mixroute URL, Key, and model name.

<Note>
  After configuration, if you want to change settings or failed to complete the provider setup during the interactive guide, you can run `hermes model` at any time after Hermes Agent deployment to overwrite the previous configuration and enter a new URL, Key, or model name.
</Note>

<Steps>
  <Step title="Select Provider">
    Use arrow keys to scroll to **Custom Endpoint** (or similar "custom endpoint" option) and press Enter to confirm.

    <Tip>
      For multi-provider scenarios, it is recommended to configure multiple SKs on the platform for separate management.
    </Tip>
  </Step>

  <Step title="Enter Base URL">
    Enter your Mixroute address, for example:

    ```text theme={null}
    https://api.mixroute.ai/v1
    ```

    <Warning>
      This is the most common source of configuration errors. You need to use native model capabilities. Please refer to the API documentation and model marketplace information to revise the Base URL.

      Mismatched endpoints may cause Hermes to malfunction or incur additional costs.
    </Warning>
  </Step>

  <Step title="Enter API Key">
    Enter the API Key generated in your Mixroute console, for example:

    ```text theme={null}
    sk-xxxxxxxxxxxxxxxx
    ```
  </Step>

  <Step title="Enter Model Name">
    Enter the model you want to use, for example:

    ```text theme={null}
    gpt-5.5
    ```

    <Warning>
      The model name must **exactly match** the ID in the Mixroute model catalog, otherwise you will get a "model not found" error.
    </Warning>
  </Step>

  <Step title="Select API Mode">
    Hermes has four compatible modes. Select based on your model. Hermes defaults to Auto-detect.

    1. `Auto-detect [current]`<br />Use Hermes URL heuristics; best for standard OpenAI-compatible endpoints.
    2. `Chat Completions`<br />Use `/chat/completions` for standard OpenAI-compatible servers.
    3. `Responses / Codex`<br />Use `/responses` for Codex-compatible tool-calling backends.
    4. `Anthropic Messages`<br />Use `/v1/messages` for Anthropic-compatible endpoints.
  </Step>
</Steps>

### Smart Routing Integration (Optional)

<Tip>
  [Smart Routing](https://console.mixroute.ai/smart-route) is an intelligent model routing capability that automatically distributes requests to the most suitable model based on task complexity, reducing API costs while enhancing efficiency.

  Add the following configuration to complete the integration. See [here](/en/smart-routing) for constraints and usage guide.

  ```text theme={null}
  # Smart Routing
  API Key : <you smart routing key>
  API Host : https://api.mixroute.ai/v1
  Models: auto
  ```
</Tip>

### Key Configuration Reference

<Tabs>
  <Tab title="Traditional API Node">
    | Config Item | Description                                             | Example                      |
    | ----------- | ------------------------------------------------------- | ---------------------------- |
    | Base URL    | Mixroute address, must end with `/v1`                   | `https://api.mixroute.ai/v1` |
    | API Key     | Token generated in Mixroute console                     | `sk-xxxxxxxxxxxxxxxx`        |
    | Model       | Model name, must match the model ID exposed by Mixroute | `gpt-5.5`                    |
  </Tab>

  <Tab title="Smart Routing Node">
    | Config Item | Description                                         | Example                      |
    | :---------- | :-------------------------------------------------- | :--------------------------- |
    | Base URL    | Mixroute Smart Routing address, must end with `/v1` | `https://api.mixroute.ai/v1` |
    | API Key     | Token generated in Mixroute Smart Routing console   | `sk-xxxxxxxxxxxxxxxx`        |
    | Model       | Model name, auto-routed based on task complexity    | `auto`                       |
  </Tab>
</Tabs>

## Verify Integration

After configuration, start Hermes to begin a conversation:

```bash theme={null}
hermes
```

Or use the more modern TUI mode (terminal graphical interface):

```bash theme={null}
hermes --tui
```

Enter a test message, for example:

```text theme={null}
Hello, what day is it today?
```

<Check>
  If the model responds normally, the integration is successful.
</Check>

### View and Switch Models

Enter the following command directly in the conversation to view the current model and switch quickly:

```text theme={null}
/model
```

## FAQ

<Accordion title="Empty response or error">
  Check if the Base URL ends with `/v1`
</Accordion>

<Accordion title="Model not found error">
  Confirm the model name exactly matches the model ID in the Mixroute console
</Accordion>

<Accordion title="Invalid API Key error">
  Generate a new Key in the Mixroute console, then run `hermes model` again
</Accordion>

<Accordion title="Don't know how to access the configuration menu">
  Enter `hermes model` in the terminal and press Enter
</Accordion>

<Accordion title="Want to switch models">
  Run `hermes model` again, or enter `/model` in the conversation
</Accordion>

<Accordion title="Want to modify previous configuration">
  Run `hermes model` again, which will overwrite the previous settings
</Accordion>

<Accordion title="Cannot install on Windows">
  Hermes does not natively support Windows. Please install WSL2 first and execute the installation command in the WSL2 terminal
</Accordion>

<Info>
  After integrating with Mixroute, all subsequent Hermes Agent capabilities (messaging gateway, skill calling, background service, etc.) will call your selected model through Mixroute, without needing to configure model providers separately for each feature.
</Info>