Skip to main content
Hermes Agent is Nous Research’s multi-provider AI agent framework. It supports OAuth, API key, and custom endpoint authentication, and can deliver to Telegram, Discord, Slack, WhatsApp, Signal, and more. For how RuAPI compares with Nous Portal from Russia and how to pay for models without a foreign card, see www.ruapi.ai/hermes-agent-v-rossii; the setup steps are below. There are two ways to connect Hermes to RuAPI: install the RuAPI plugin (recommended; it is listed in the official Hermes plugin catalog), or use Hermes’ built-in “Custom endpoint” flow (OpenAI-compatible).

Prerequisites

1

RuAPI account + API key

Console → API Keys → create a sk-... key.
2

OS

Linux, WSL2, Windows 10/11 and Apple Silicon macOS are all in Hermes’ top support tier (Tier 1). On Windows and Apple Silicon macOS you can also use the Hermes Desktop installer, which adds the desktop app.

Install Hermes

One-liner:
Then open a new terminal window, or reload your shell config: source ~/.zshrc in zsh (the macOS default) or source ~/.bashrc in bash.
Confirm:
If something doesn’t start, hermes doctor shows which components are missing and how to fix them. The RuAPI plugin is listed in the official Hermes plugin catalog and needs Hermes 0.21.5 or newer. It adds two providers that share one key:
  • ruapi: Claude models over the native Anthropic API, so Hermes’ prompt caching and thinking settings apply;
  • ruapi-openai: GPT, Gemini, DeepSeek, Qwen, GLM, Kimi and other models over the OpenAI-compatible API.
1

Install the plugin

2

Set the API key

hermes setup also asks for RUAPI_API_KEY.
3

Pick a model

Run hermes model, choose RuAPI (Claude) or RuAPI (OpenAI-compatible) (other models), then pick a model. Or set it at launch:
The model list is built from the models your account can use; image and video models are left out. Plugin source: RuAPI-ai/hermes-provider-ruapi.

Option 2: no plugin, Custom endpoint

Launch the provider wizard:
Follow these steps:
1

Pick 'Custom endpoint'

The wizard lists every built-in provider (Nous Portal / OpenRouter / Anthropic / OpenAI / …). Scroll to the bottom and select Custom endpoint (self-hosted / VLLM / etc.).
2

Base URL

OpenAI-compatible protocol — the URL must end in /v1.
3

API key

Paste your RuAPI key sk-.... Hermes writes it to ~/.hermes/.env.
4

Name the connection

For example, RuAPI. Hermes creates a matching credential pool.
5

Choose a model

Popular families:
  • GPT (OpenAI)
  • Claude Sonnet (callable via the OpenAI-compatible protocol on RuAPI)
  • DeepSeek, Kimi, GLM, etc.
Exact names and the full list are on the pricing page.
The wizard writes ~/.hermes/config.yaml:

First call

Start the CLI:
Inside the prompt:
A normal reply plus a matching RuAPI Console → Usage Logs entry = success.

Switch models

Inside a session:
Or exit and rerun hermes model to change the default. For everyday chats and routine agent tasks deepseek-flash is enough and costs many times less than Claude Sonnet, which matters because Hermes often sends a long history with every request. With the RuAPI plugin, start it like this: hermes --provider ruapi-openai --model deepseek-flash (via Custom endpoint — /model custom:deepseek-flash). For hard work, switch to Claude: /model claude-sonnet-5-5 (via Custom endpoint — /model custom:claude-sonnet-5-5). To have Claude go through the native RuAPI provider with the plugin (caching and thinking), pick it in hermes model.

Wire up Telegram / Discord / etc.

Once the model is configured, set up the gateway:
Follow the prompts (Telegram bot token, etc.). Once the gateway is up, messages will route through RuAPI. See the Hermes Messaging Gateway docs for details.

Troubleshooting

  • Confirm the API key line in ~/.hermes/.env is your RuAPI key, copied correctly.
  • Check the key status in RuAPI Console → API Keys.
  • That model ID isn’t on RuAPI — check the pricing page.
  • base_url must end in /v1.
Hermes’s built-in Anthropic flow is built around Claude Max OAuth — overriding the base URL for third-party gateways isn’t reliable. Custom endpoint (OpenAI-compatible) is the cleanest path on RuAPI, and Claude models work over it too.
Hermes supports multiple providers. Run hermes model again to add another, and use /model mid-session to switch.
Function calling passes through the OpenAI-compatible protocol unchanged. If a tool call fails, first verify the model supports tool use (GPT and Claude models handle it reliably — see function calling).

Advanced

  • Auxiliary models: Hermes uses an auxiliary model for vision / web summarization / MoA, defaulting to your main model. To save money, override it to a cheaper one — see Auxiliary Models.
  • Credential pools: round-robin keys and auto-failover — see Credential Pools.