Skip to main content

Hermes Agent Integration Guide

Hermes Agent is an open-source autonomous terminal AI agent by Nous Research. It can independently handle coding, file operations, task orchestration, and other complex work directly in your terminal. It works with any OpenAI-compatible API endpoint, and the official provider documentation lists Custom Endpoint as a first-class option, so it can be connected to OPE.AI seamlessly.

Install Hermes Agent​

macOS / Linux / WSL2 / Termux​

Use the official install script:

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

Reload your shell configuration after installation:

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

Windows​

Hermes Agent now has native Windows support. Run the following in PowerShell:

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

The installer handles uv, Python 3.11, Node.js, and other dependencies automatically, and bundles a portable Git Bash (no admin required). If you prefer to use WSL2, you can also run the Linux/macOS install command above in a WSL2 terminal.

Native Windows installs live under %LOCALAPPDATA%\hermes; WSL2 installs live under ~/.hermes.

Verify Installation​

hermes --version

If the version number is printed correctly, the installation was successful.

Get an API Key​

Log in to the OPE.AI Console and create your own API Key (starting with sk-).

Configure OPE.AI​

OPE.AI provides an OpenAI-compatible protocol with the API endpoint at https://api.ope.ai/v1. Connecting Hermes Agent requires configuring just three fields: API base URL, API key, and Model name.

Run the model configuration command:

hermes model

In the menu, select Custom endpoint (self-hosted / VLLM / etc.), then enter:

FieldValue
API base URLhttps://api.ope.ai/v1
API KeyYour OPE.AI API Key
Model namee.g. claude-sonnet-5

Leave the context window blank when prompted — Hermes will auto-detect it from the endpoint. The configuration is saved to ~/.hermes/config.yaml automatically.

Method 2: Manual Configuration (~/.hermes/config.yaml)​

~/.hermes/config.yaml
model:
  default: claude-sonnet-5
  provider: custom
  base_url: https://api.ope.ai/v1
  api_key: sk-xxxx
warning

The legacy LLM_MODEL environment variable has been removed from Hermes, and OPENAI_BASE_URL only applies to the openai-api provider. For custom endpoints, ~/.hermes/config.yaml is the single source of truth for model and endpoint configuration. Use the hermes model command or set model.base_url in config.yaml directly.

Verify Configuration​

Start an interactive conversation:

hermes "Hello, please introduce yourself"

If Hermes replies using the configured model, the integration is successful.

info

Hermes Agent requires a model with at least 64K context at startup (the system prompt, tool schemas, and working conversation state need enough room). Models with less than 64K context are rejected at startup. All of the models below meet this requirement.

Use CaseRecommended ModelContext WindowNotes
Everyday coding & writingclaude-sonnet-51MBalanced performance, excellent for coding, writing, and tool calling
Complex reasoningclaude-opus-51MStrong reasoning and agent capabilities, ideal for complex engineering and professional tasks
All-around flagshipgpt-5.6-sol1MComprehensive strength, ideal for programming, research, and complex knowledge work
Cost optimizationdeepseek-v4-flash-07311MExtremely low cost, top choice for high-frequency calls
Multimodal tasksglm-5.3-flash1MNative multimodal, long context, balanced speed and agent capabilities

For the full list of models and pricing, see Model Pricing.

Getting Started​

Interactive Chat​

hermes

Launch the terminal UI and start chatting directly.

Ask via CLI​

hermes chat --provider custom --model claude-sonnet-5 "Write a quicksort in Python"

Switch Models Mid-Session​

hermes model vs /model

hermes model (run from your terminal, outside any chat session) is the full provider setup wizard. Use it to add new providers, enter API keys, and configure custom endpoints.

/model (typed inside an active session) can only switch between providers and models you've already set up. It cannot add new providers or prompt for API keys. To add a new provider, exit the session (Ctrl+C or /quit), run hermes model, then start a new session.

Hermes supports switching models without restarting:

/model custom:gpt-5.4              # Switch to gpt-5.4 on the custom provider
/model custom:DeepSeek-V3.2        # Switch to DeepSeek
/model custom                     # Auto-detect the model from the endpoint
tip

/model custom (bare, no model name) queries the endpoint's /models API and auto-selects the model — handy when you're not sure of the exact model name.

Troubleshooting​

"No API key" / provider not found​

  • Check that provider: custom and api_key in ~/.hermes/config.yaml are correct
  • Make sure base_url and the model are written into config.yaml
  • Re-run hermes model to go through the interactive setup again

401 / 403 Authentication Errors​

  • Confirm the API Key format is correct (starts with sk-)
  • Log in to the OPE.AI Console to verify the key is valid
  • Confirm the API endpoint is correct: https://api.ope.ai/v1

Model Not Found / No Response​

  • Check the model ID spelling (e.g. claude-sonnet-5)
  • Confirm base_url in ~/.hermes/config.yaml matches the model name
  • Use a correct model ID from the recommended models table above

Context Error at Startup​

  • Switch to a model with a context window of at least 64K (see the recommended models table above)
  • Re-run hermes model and set the correct context window (or leave it blank for auto-detection)

Auxiliary Tasks (vision, session titles, etc.)​

Auxiliary tasks such as vision (image analysis), session-title generation, and context compression use your main chat model by default (auxiliary.*.provider: "auto") — no extra configuration is needed, and they don't add extra cost. If you want auxiliary tasks to run on a cheaper/faster model, use Configure auxiliary models in the hermes model menu, or configure them manually as described in the Auxiliary Models docs.