Picking a Model Provider for Hermes Agent: A First-Run Decision Guide

What “picking a provider” means for Hermes

The provider decision comes IMMEDIATELY after install and right before the first hermes chat. Get this wrong and every layer above (tools, memory, gateway, plugins) starts looking broken when only the model layer is misconfigured.

The three decisions you actually make

1. Which provider? (the seven providers section)
2. Which auth path? (Portal-OAuth, raw API key, custom endpoint)
3. Which default model?

Decision rubric

Provider	Auth	Cost shape	Speed floor	Multi-model via one key	Notes
Nous Portal	OAuth	Included free tier	fast	no	Easiest for Nous users
OpenRouter	API key	per-token	varies by model	YES	One key, many models
Anthropic	API key	per-token	fast	no	Claude family native
OpenAI / Codex	API key OR OAuth (Codex tier)	per-token	fast	no	OpenAI native
Gemini	API key	free + paid tiers	varies	no	Google AI Studio
MiniMax	API key	per-token	varies	no	Active provider on this build
local OpenAI-compatible (vLLM, Ollama, LM Studio)	none	free (your box)	slow	n/a	First-class on a Mac mini

The /guides/hermes-agent-setup-v2.md guide walked you through “hermes chat -q ‘Reply with OK.’” as the smoke test. This guide is the layer IN BETWEEN — what to do between picking Hermes and writing that smoke test.

A short reading guide for the table: the “auth” column is the part most new users get stuck on. Portal-OAuth means a browser round-trip; a raw API key means pasting a token into the credential store; and a custom endpoint means pointing Hermes at a server you already control (Ollama, vLLM, LM Studio, or any drop-in OpenAI-compatible API). The “multi-model via one key” column is what makes OpenRouter special: a single OpenRouter key can route to Claude, GPT, Gemini, Llama, and dozens of others without re-auth. The other providers tie you to one vendor’s model family.

The “speed floor” column is the median you should expect on a healthy network for a short prompt; per-token latency on paid providers is usually faster than local inference, and free tiers are usually the slowest because they sit behind shared quotas. Treat the local OpenAI-compatible row as a special case: cost is “free (your box)” only because the hardware is already paid for. A 70B-class model on a Mac mini will feel slow next to a hosted API, and that tradeoff is the point.

How to pick

Default path: Nous Portal if you have a Nous account; OpenRouter if you want one key that can swap models. The Portal route is fastest because OAuth removes the API-key paste step entirely, and the resulting config is stored as a credential you can refresh later without re-typing a token. OpenRouter is the right call when you have not yet committed to a model family and want to A/B different providers against the same Hermes install without juggling seven keys.

Migration / multi-provider path: start with OpenRouter to learn which model fits, then drop the cost floor by routing to a free model on Google or to a local Ollama endpoint for solo work. Once you have a “favorite” model, switch the Hermes default to that provider directly; OpenRouter’s per-token surcharge is small but not zero, and a direct key removes one hop from every request.

Power user path: Hermes supports running multiple provider profiles via the ~/.hermes/profile settings; keep Nous Portal as the default and use --provider openrouter per-call when you want a different model tier. The --provider flag is the escape hatch that lets one Hermes install talk to many model catalogs without rewriting config.yaml between runs.

What goes wrong (and how to recover)

• hermes setup --portal opens a browser window on Windows but doesn’t seem to do anything: usually a corporate network blocks the OAuth callback. Run hermes setup --portal --no-browser instead and paste the URL into a local laptop browser.
• hermes model returns “no model found”: you are not in an interactive terminal. Use hermes config set default <provider/model> directly.
• Provider auth fails the smoke test but the model loads: provider credential is loaded but the model name doesn’t match what the provider offers. Check hermes model --refresh to re-fetch the model list from the live provider catalog.

Commands, briefly

hermes setup --portal              # OAuth Portal path (easiest first run)
hermes model --refresh             # Re-fetch provider model lists
hermes model                       # Interactive picker
hermes config set default <provider/model>   # Non-interactive set
hermes chat -q "Reply with OK."    # Smoke test the chosen layer

Verification checklist

Step	Command	What it proves
1	hermes setup --portal (or hermes model)	A provider/model is configured
2	hermes doctor	The local config is healthy enough to chat
3	hermes chat -q "Reply with OK."	The chosen model actually responds
4	hermes model --refresh	The provider catalog is fresh

What not to do

• Don’t pick a custom OpenAI-compatible endpoint without first verifying the endpoint outside Hermes (curl the /v1/models and confirm the model name appears).
• Don’t chain --non-interactive with setup --portal (Portal needs the OAuth browser round-trip).
• Don’t assume one provider’s free tier covers another’s rate limits — they don’t, and switching mid-session will cost you the in-flight context.

Sources

• Hermes CLI commands reference
• Hermes providers docs
• Hermes configuration docs
• NousResearch/hermes-agent GitHub repo

Last verified: 2026-07-14 against Hermes v0.18.2 (2026.7.7.2) and the live provider catalog on this install. Re-run hermes --version before following a flag whose number may have shifted.