# Hermes Agent Configuration Guide

> Point Hermes Agent's custom Provider to LLMoxy via ~/.hermes/config.yaml and .env to access GPT / Claude / Gemini full series models.

Website: [https://hermes-agent.nousresearch.com (click to jump!)](https://hermes-agent.nousresearch.com)

> **📌 About Hermes Agent**
> Hermes Agent is an open-source terminal AI agent launched by Nous Research, supporting CLI / TUI / API Server three entry points, and can connect to any OpenAI compatible endpoint.

## Source Code Address

- GitHub: [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)
- Official Docs: [hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs)

## 1. Install Hermes Agent

### Method 1: pip install (recommended)

```bash
pip install hermes-agent
hermes postinstall    # Optional: auto-install Node.js / browser / ripgrep / ffmpeg
```

### Method 2: script install (follow main branch)

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

After installation, reload Shell:

```bash
source ~/.zshrc    # or source ~/.bashrc
```

## 2. Core Configuration Process

Hermes Agent settings are concentrated in the `~/.hermes/` directory:

| File | Purpose |
| --- | --- |
| `~/.hermes/config.yaml` | All non-sensitive config: model, provider, terminal, compression, etc. |
| `~/.hermes/.env` | API Key and other sensitive credentials |

### 1. Configure config.yaml (custom provider)

Open or create `~/.hermes/config.yaml`, write the `model` block as `custom` Provider, and point `base_url` to LLMoxy:

```yaml
model:
  provider: custom
  base_url: "https://llmoxy.com/v1"
  model: "grok-4.7"
```

You can also use CLI one-click write (automatically lands in `config.yaml`):

```bash
hermes config set model.provider custom
hermes config set model.base_url https://llmoxy.com/v1
hermes config set model.model grok-4.7
```

### 2. Configure .env (write API Key)

Write the LLMoxy token to `~/.hermes/.env`:

```
OPENAI_API_KEY=<LLMOXY_API_KEY>xxxxxxxxxxxxxxx
```

Or use CLI (recommended, automatically routes to `.env` without leaking to YAML):

```bash
hermes config set OPENAI_API_KEY <LLMOXY_API_KEY>xxxxxxxxxxxxxxx
```

Replace `<LLMOXY_API_KEY>xxxxxxxxxxxxxxx` with the real token obtained from the [LLMoxy Console](https://llmoxy.com/).

> **💡 Tip**
> Please use a token from the **auto** group. Hermes Agent calls LLMoxy via OpenAI Chat Completions protocol; `base_url` must include `/v1`.

## 3. Interactive Quick Configuration (optional)

If you don't want to manually edit YAML, run `hermes model` to enter the interactive wizard:

```bash
hermes model
```

Select in order:

1. In Provider options, pick **Custom Endpoint**
2. Base URL enter `https://llmoxy.com/v1`
3. API Key paste LLMoxy token
4. Model enter `grok-4.7`

## 4. Launch Hermes

```bash
hermes          # Classic CLI
hermes --tui    # Modern TUI interface (recommended)
```

After launch, the welcome banner will display the currently active model and provider; you can enter a test prompt to verify connectivity.

## Complete Configuration Example

```yaml
# ~/.hermes/config.yaml
model:
  provider: custom
  base_url: "https://llmoxy.com/v1"
  model: "grok-4.7"
```

```
# ~/.hermes/.env
OPENAI_API_KEY=<LLMOXY_API_KEY>xxxxxxxxxxxxxxx
```

> **💡 Model naming rule tip**
> `grok-4.7` is the standard model ID on LLMoxy, viewable in the console "Model List". Other common ones:
> - **GPT series**: `gpt-6.1-sol`
> - **Claude series**: `claude-opus-5-5`, `claude-fable-5-2`

## Configuration Priority

Hermes Agent reads configuration following this priority (from high to low):

1. Command line parameters
2. `~/.hermes/config.yaml`
3. `~/.hermes/.env`
4. Built-in defaults

After modifying configuration, no need to restart Hermes; the next new session will automatically load the latest `config.yaml`.

This is the markdown version of https://en.llmoxy.com/docs/code-tutorials/hermes-agent.
