Hermes Agent Configuration Guide

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

📌 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
• Official Docs: hermes-agent.nousresearch.com/docs

1. Install Hermes Agent

Method 1: pip install (recommended)

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

Method 2: script install (follow main branch)

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

After installation, reload Shell:

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

2. Core Configuration Process

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

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:

model:
  provider: custom
  base_url: "https://llmoxy.com/v1"
  model: "gpt-5.5"

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

hermes config set model.provider custom
hermes config set model.base_url https://llmoxy.com/v1
hermes config set model.model gpt-5.5

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):

hermes config set OPENAI_API_KEY <LLMOXY_API_KEY>xxxxxxxxxxxxxxx

Replace <LLMOXY_API_KEY>xxxxxxxxxxxxxxx with the real token obtained from the LLMoxy Console.

💡 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:

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 gpt-5.5 (or other model ID supported by LLMoxy, e.g., gpt-5.4)

4. Launch Hermes

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

# ~/.hermes/config.yaml
model:
  provider: custom
  base_url: "https://llmoxy.com/v1"
  model: "gpt-5.5"

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

💡 Model naming rule tip gpt-5.5 is the standard model ID on LLMoxy, viewable in the console "Model List". Other common ones:

• GPT series: gpt-5.5, gpt-5.4, gpt-4o
• Claude series: claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5
• Gemini series: gemini-2.5-pro

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.