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
- Linux / macOS / WSL2
- Windows (PowerShell)
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.hermes doctor shows which components are missing and how to fix them.
Option 1: install the RuAPI plugin (recommended)
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:Option 2: no plugin, Custom endpoint
Launch the provider wizard: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
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.
~/.hermes/config.yaml:
First call
Start the CLI:Switch models
Inside a session: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:Troubleshooting
Model not found (503) or 404
Model not found (503) or 404
- That model ID isn’t on RuAPI — check the pricing page.
base_urlmust end in/v1.
Why not use Hermes's built-in 'Anthropic' provider?
Why not use Hermes's built-in 'Anthropic' provider?
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.
Run Nous Portal + RuAPI side by side
Run Nous Portal + RuAPI side by side
Hermes supports multiple providers. Run
hermes model again to add another, and use /model mid-session to switch.Tool / function calling not working
Tool / function calling not working
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.