Provider Setup 2026: Connecting 100+ LLMs to Hermes Agent
Connect Hermes Agent to providers: Nous Portal OAuth, API-key providers, credential pools, fallback chains, local models and OpenRouter routing.
Hermes Agent reaches models through one configuration layer: a provider ID, a credential, and a model name. Everything below comes from the official Hermes documentation pages listed at the end, fetched 2026-11-11. Where the documentation is silent, this guide says so instead of filling the gap.
Provider Overview
This guide groups providers into five practical families. The distinctions matter because each family has a different credential path, a different billing surface, and a different failure mode.
| Group | How you authenticate | What you get | Sourced notes |
|---|---|---|---|
| Nous Portal | OAuth login (hermes setup --portal, hermes auth add nous) |
300+ frontier agentic models plus the Tool Gateway | “The recommended way to run Hermes Agent”; paid subscribers: “No extra API keys needed” |
| First-class API-key providers | An API key in ~/.hermes/.env, then --provider <id> |
Dedicated provider IDs with documented example models | Ten providers accept base-URL override env vars; Fireworks endpoint changes go through model.base_url in config.yaml |
| OAuth / subscription providers | Browser or device-code login (hermes model) |
Anthropic OAuth, ChatGPT/Codex OAuth, xAI Grok OAuth, Qwen Portal OAuth | Claude Pro cannot use the OAuth path; Vertex AI uses GCP billing |
| Local / self-hosted endpoints | hermes model → “Custom endpoint (self-hosted / VLLM / etc.)” or a model: block in config.yaml |
Any OpenAI-compatible server you run yourself | api_key may be left empty for local servers |
| Gateways | API key or cloud credentials | ai-gateway, openrouter |
OpenRouter alone supports provider_routing |
Nous Portal is described as “Nous Research’s unified subscription gateway and the recommended way to run Hermes Agent.” The Providers page’s quick-pick table names OpenRouter (default) or Nous Portal under “Just want it to work”.
Fastest Path: Nous Portal OAuth
One Portal login covers 300+ frontier agentic models (Claude, GPT, Gemini, DeepSeek, Qwen, Kimi, GLM, MiniMax, Grok, …) plus the Tool Gateway — web search, image generation, TTS, browser automation — billed against your Nous subscription instead of separate per-provider accounts. Subscriptions are managed at portal.nousresearch.com/manage-subscription.
hermes setup --portal # fresh install — OAuth + provider + gateway in one command
hermes model # existing install — pick "Nous Portal" from the list
hermes portal info # inspect login + routing at any time
hermes auth add nous # OAuth login for the portal credential
hermes tools # inspect or enable Tool Gateway toolsThe Tool Gateway is available to paid Nous Portal subscribers with “No extra API keys needed.” Every Portal request carries a client tag of the form client=hermes-client-v<version>; the documentation’s illustration of that format is client=hermes-client-v0.13.0, which is an example of the format, not a statement of any installed or documented release. The tag is auto-aligned to the installed release and refreshes on hermes update.
Authentication needs no configuration: Hermes prefers scoped inference:invoke JWTs for Portal requests, with the legacy opaque session-key path as a fallback. Credentials rotate transparently, and revoked refresh tokens are quarantined to avoid replay loops.
One warning applies to every setup, Portal included: some features (vision, compression, MoA) use a separate “auxiliary” model. The default auxiliary.*.provider: "auto" routes those tasks to your main chat model, and each task can be overridden individually — for example, pointing compression at a different model.
Choosing the Right Setup
Pick the narrowest path that fits:
- You have a Nous subscription → Portal OAuth. One login, no per-provider keys, and the Tool Gateway included.
- You want a specific vendor model with your own billing → a first-class API-key provider or an OAuth/subscription provider.
- You run your own weights → a custom endpoint in
config.yaml. - You want routing control or a single key across vendors → a gateway (
openrouter,ai-gateway).
For plan-dependent logins, the documentation is explicit about what is and is not documented:
| Path | Works? | What gets consumed | What does NOT get consumed | Common surprise |
|---|---|---|---|---|
Claude Max + OAuth (hermes model → Anthropic OAuth) |
Yes — requires Max and purchased extra usage credits | The extra/overage credits added on top of the Max plan | The base Max plan allowance | — |
| Claude Pro | No — Pro subscribers cannot use the OAuth path; use ANTHROPIC_API_KEY |
Pay-per-token billing against that key’s organization | Any Claude subscription allowance | — |
| ChatGPT / Codex plan OAuth | Yes — hermes model → ChatGPT or Codex Subscription |
Not currently documented | Not currently documented | Eligible plan tiers are not currently documented |
| xAI SuperGrok / X Premium+ OAuth | Yes — browser OAuth, no API key needed | Subscription quota (documented for X Search); inference quota semantics not currently documented | API spend, when OAuth credentials are configured and preferred | HTTP 403 after a successful login — xAI restricts OAuth API access to specific tiers; workaround is an XAI_API_KEY |
| Google consumer Gemini | No documented path — gemini is API-key only (GOOGLE_API_KEY / GEMINI_API_KEY); Vertex AI uses GCP billing |
— | — | Free-tier keys “can be exhausted after a handful of agent turns” |
The documentation marks unknown cells “not currently documented” and instructs: “Don’t assume — check your provider’s billing dashboard.”
Manual Provider Setup
API-key providers
These providers have built-in support with dedicated provider IDs. Set the API key and use --provider to select. The full documented block, verbatim:
# Fireworks AI
hermes chat --provider fireworks --model accounts/fireworks/models/kimi-k2p6
# Requires: FIREWORKS_API_KEY in ~/.hermes/.env
# NovitaAI Model API
hermes chat --provider novita --model moonshotai/kimi-k2.5
# Requires: NOVITA_API_KEY in ~/.hermes/.env
# Ramp Router (model IDs come from your account's live catalog)
hermes chat --provider router --model gpt-5.4-mini
# Requires: RAMP_ROUTER_API_KEY in ~/.hermes/.env
# z.ai / ZhipuAI GLM
hermes chat --provider zai --model glm-5
# Requires: GLM_API_KEY in ~/.hermes/.env
# Kimi / Moonshot AI (international: api.moonshot.ai)
hermes chat --provider kimi-coding --model kimi-for-coding
# Requires: KIMI_API_KEY in ~/.hermes/.env
# Kimi / Moonshot AI (China: api.moonshot.cn)
hermes chat --provider kimi-coding-cn --model kimi-k2.5
# Requires: KIMI_CN_API_KEY in ~/.hermes/.env
# MiniMax (global endpoint)
hermes chat --provider minimax --model MiniMax-M2.7
# Requires: MINIMAX_API_KEY in ~/.hermes/.env
# MiniMax (China endpoint)
hermes chat --provider minimax-cn --model MiniMax-M2.7
# Requires: MINIMAX_CN_API_KEY in ~/.hermes/.env
# Qwen Cloud / DashScope (Qwen models)
hermes chat --provider alibaba --model qwen3.5-plus
# Requires: DASHSCOPE_API_KEY in ~/.hermes/.env
# Xiaomi MiMo
hermes chat --provider xiaomi --model mimo-v2-pro
# Requires: XIAOMI_API_KEY in ~/.hermes/.env
# Tencent TokenHub (Hy4 preview)
hermes chat --provider tencent-tokenhub --model hy4-preview
# Requires: TOKENHUB_API_KEY in ~/.hermes/.env
# Tencent TokenPlan (Hy4 preview via Anthropic Messages endpoint)
hermes chat --provider tencent-tokenplan --model hy4-preview
# Requires: TOKENPLAN_API_KEY in ~/.hermes/.env
# Arcee AI (Trinity models)
hermes chat --provider arcee --model trinity-large-thinking
# Requires: ARCEEAI_API_KEY in ~/.hermes/.env
# Meta Model API (Muse Spark family)
hermes chat --provider meta-ai --model muse-spark-1.2
# Requires: MODEL_API_KEY in ~/.hermes/.env
# GMI Cloud
# Use the exact model ID returned by GMI's /v1/models endpoint.
hermes chat --provider gmi --model zai-org/GLM-5.1-FP8
# Requires: GMI_API_KEY in ~/.hermes/.env
# Nebius Token Factory
hermes chat --provider nebius --model deepseek-ai/DeepSeek-V4-Pro
# Requires: NEBIUS_API_KEY in ~/.hermes/.envNotes carried over from the source: Fireworks’ default endpoint is https://api.fireworks.ai/inference/v1, and a different endpoint is configured through model.base_url in config.yaml, not .env. Meta contributor tiers (muse-spark-1.2-contributor, muse-spark-1.3-contributor) trigger a confirmation prompt because Meta may train on prompts and completions; the non-contributor IDs are the ones to use for confidential work.
OAuth and enterprise providers
Anthropic supports ANTHROPIC_API_KEY, the OAuth path in hermes model, and ANTHROPIC_TOKEN, plus auto-detection of Claude Code credentials. --provider claude and --provider claude-code are shorthand for --provider anthropic. Hermes prefers Claude Code’s own credential store over copying OAuth tokens into ~/.hermes/.env, so refreshable credentials stay refreshable.
OpenAI Codex authenticates via device code by default (open a URL, enter a code). Organizations that disable that grant can opt into browser authorization-code + PKCE with hermes auth add openai-codex --browser for one login, or auth.codex_login_flow: browser in config.yaml for every Codex login. The browser flow listens on http://localhost:1455/auth/callback — the registered redirect URI, so the port is fixed — and falls back to device code if the port is taken. Over SSH, tunnel it: ssh -N -L 1455:127.0.0.1:1455 user@host. Credentials live in ~/.hermes/auth.json; existing Codex CLI credentials can be imported from ~/.codex/auth.json when present, and no Codex CLI installation is required. Terminal refresh errors (invalid_grant, revoked grants) mark the refresh token dead and stop replay; the quarantine clears on the next successful exchange. A TLS failure mode on Python/OpenSSL 3.5+ ([SSL: UNEXPECTED_EOF_WHILE_READING]) is worked around by pointing OPENSSL_CONF at a config restricting Groups to classic curves — Hermes does not change default TLS policy:
openssl_conf = openssl_init
[openssl_init]
ssl_conf = ssl_sect
[ssl_sect]
system_default = system_default_sect
[system_default_sect]
Groups = x25519:secp256r1:secp384r1:x448GitHub Copilot is no longer built in. The copilot and copilot-acp providers ship as the github-copilot labs plugin — built by Nous Research, but not supported. Install it with hermes plugins install github-copilot; profiles already using those IDs get it installed automatically by hermes update or at their next agent/gateway start. Sign in with hermes auth add copilot (device-code login), or set COPILOT_GITHUB_TOKEN, GH_TOKEN, or GITHUB_TOKEN. Logins made with the gh CLI or the Copilot CLI are no longer read. Plugin documentation lives at the github-copilot plugin page.
Provider Configuration Table
From the “Supported Providers” table in the fallback providers documentation:
| Provider | Slug | Requirement |
|---|---|---|
| AI Gateway | ai-gateway |
AI_GATEWAY_API_KEY |
| OpenRouter | openrouter |
OPENROUTER_API_KEY |
| Nous Portal | nous |
hermes setup --portal (fresh) or hermes auth add nous (OAuth) |
| OpenAI Codex | openai-codex |
hermes model → ChatGPT or Codex Subscription (ChatGPT OAuth) |
| Anthropic | anthropic |
ANTHROPIC_API_KEY or Claude Code credentials |
| z.ai / GLM | zai |
GLM_API_KEY |
| Kimi / Moonshot | kimi-coding |
KIMI_API_KEY |
| MiniMax | minimax |
MINIMAX_API_KEY |
| MiniMax (China) | minimax-cn |
MINIMAX_CN_API_KEY |
| DeepSeek | deepseek |
DEEPSEEK_API_KEY |
| NVIDIA NIM | nvidia |
NVIDIA_API_KEY (optional: NVIDIA_BASE_URL) |
| GMI Cloud | gmi |
GMI_API_KEY (optional: GMI_BASE_URL) |
| Upstage Solar | upstage (alias solar) |
UPSTAGE_API_KEY (optional: UPSTAGE_BASE_URL) |
| StepFun | stepfun |
STEPFUN_API_KEY (optional: STEPFUN_BASE_URL) |
| Ollama Cloud | ollama-cloud |
OLLAMA_API_KEY |
| Google AI Studio | gemini |
GOOGLE_API_KEY (alias GEMINI_API_KEY) |
| xAI (Grok) | xai (alias grok) |
XAI_API_KEY (optional: XAI_BASE_URL) |
| xAI Grok OAuth (SuperGrok) | xai-oauth (alias grok-oauth) |
hermes model → xAI Grok OAuth (browser login; SuperGrok subscription) |
| AWS Bedrock | bedrock |
Standard boto3 auth (AWS_REGION + AWS_PROFILE or AWS_ACCESS_KEY_ID) |
| Qwen Portal (OAuth) | qwen-oauth |
hermes model (Qwen Portal OAuth) |
Slug corrections carried into this refresh: Qwen Cloud / DashScope is alibaba, NVIDIA NIM is nvidia, Tencent TokenHub is tencent-tokenhub, Tencent TokenPlan is tencent-tokenplan, Fireworks is fireworks, NovitaAI is novita, and Google AI Studio is gemini.
Custom endpoints and named providers
The manual model: block:
model:
default: your-model-name
provider: custom
base_url: http://localhost:8000/v1
api_key: your-key-or-leave-empty-for-local
# key_env: MY_PROVIDER_API_KEY # env var holding the key (alternative to api_key)Named providers live under a providers: dict keyed by name:
providers:
local:
api: http://localhost:8080/v1
work:
api: https://gpu-server.internal.corp/v1
key_env: CORP_API_KEY
transport: chat_completions
anthropic-proxy:
api: https://proxy.example.com/anthropic
key_env: ANTHROPIC_PROXY_KEY
transport: anthropic_messagesAccepted per-entry fields: api (aliases base_url / url), name, key_env or inline api_key or key_cmd, transport (chat_completions / anthropic_messages / codex_responses), default_model, models, context_length, discover_models, extra_body, extra_headers, session_affinity_header, ssl_ca_cert / ssl_verify, catalog_provider, enabled: false, and request_timeout_seconds.
An entry keyed like a built-in provider that sets its own api takes over that name: --provider openrouter, /model, hermes model and the dashboard save it as custom:openrouter; declared keys are used and the built-in’s env key is never sent. hermes doctor warns when model.provider names a built-in that such an entry takes over. A same-named block without an endpoint only tunes the built-in — for example providers.openrouter: {request_timeout_seconds: 300}.
Legacy variables: LLM_MODEL in .env is removed; config.yaml is the single source of truth for model and endpoint configuration. OPENAI_BASE_URL is still honored, but only for the openai-api provider. Stale .env entries are cleared automatically on the next hermes setup or config migration.
Switching Models
hermes model runs in your terminal, outside any session: a full setup wizard that adds providers, runs OAuth, enters API keys and configures endpoints. /model runs inside a Hermes chat session and only switches between already-configured providers and models — it cannot add providers, run OAuth, or prompt for API keys. If only one provider is configured, /model shows only that provider’s models.
To add a provider: exit your session (Ctrl+C or /quit), run hermes model, set up the new provider, then start a new session.
Documented /model forms:
/model custom:qwen-2.5 # Switch to a model on your custom endpoint
/model custom # Auto-detect the model from the endpoint
/model openrouter:claude-sonnet-4 # Switch back to a cloud provider
/model custom:local:qwen-2.5 # Use the "local" custom provider with model qwen-2.5
/model custom:work:llama3 # Use the "work" custom provider with llama3Bare /model custom queries your endpoint’s /models API and auto-selects the model if exactly one is loaded. Switching persists base URL and provider to config.yaml; switching away from a custom endpoint to a built-in provider clears the stale base URL.
Credential Pools
Credential pools let you register multiple API keys or OAuth tokens for the same provider; when one key hits a rate limit or billing quota, Hermes rotates to the next healthy key. A single Nous Portal OAuth covers 300+ models, so most users don’t need a pool when on Portal. If an API key is already in .env, Hermes auto-discovers it as a 1-key pool.
hermes auth # Interactive pool management wizard
hermes auth list # Show all pools and credentials
hermes auth list <provider> # Show a specific provider's pool
hermes auth add <provider> # Add a credential (prompts for type and key)
hermes auth add <provider> --type api-key --api-key <key> # Add an API key non-interactively
hermes auth add <provider> --type oauth # Add an OAuth credential via browser login
hermes auth remove <provider> <target>Bare hermes auth opens an interactive wizard for adding, removing, and resetting credentials and setting the rotation strategy. Credentials live in ~/.hermes/auth.json; env-borrowed keys appear as env: rows such as env:OPENROUTER_API_KEY.
Rotation strategies: round_robin, least_used, fill_first, random. The documented decision flow:
- 429, plan/usage limit reached → rotate immediately (the cap won’t clear on retry).
- 429, generic/transient → retry the same key once; a second 429 rotates.
- 402 billing error → rotate immediately, with a 1-hour cooldown on that key.
- 401 auth expired → try refreshing the token (OAuth); if refresh fails, rotate.
- 400 “model is not supported when using Codex with a ChatGPT account” → bench that key for that model only; other models stay usable. If every key rejects the model, the model is skipped for the session.
- HTTP 200 with
response.status: failed(how ChatGPT/Codex reports usage limits) → the same rules, keyed on the embedded error code. Content-policy failures do not rotate.
Two costs to know: pools are tried first — only when every pool key is exhausted does the fallback provider activate — and key rotation resets the prompt cache, because provider-side caches are scoped to the account or API key, so each rotation re-reads full history at undiscounted input price. Also note the Codex rule: only different OpenAI accounts rotate independently; two logins of the same account share one token family, and Hermes warns warning: this login is the same OpenAI account as openai-codex credential #N. See Credential Pools.
Fallback Chains
Fallbacks are the cross-provider layer: when the primary fails with rate limits, server overload, auth failures or connection drops, Hermes switches to a backup provider:model pair for that turn without losing your conversation. Fallback is turn-scoped: each new message restores the primary, and within one turn fallback activates at most once. hermes fallback reuses the provider picker from hermes model and offers add, list (alias ls), remove (alias rm), clear, and check.
Changes persist under the top-level fallback_providers: list; each entry requires both provider and model, and entries missing either field are ignored.
fallback_providers:
- provider: openrouter
model: anthropic/claude-sonnet-4fallback_providers (plural, list) is the current shape and supports multiple fallbacks tried in order. fallback_model (singular) is the legacy single-fallback key — still honored for back-compat, but hermes fallback writes fallback_providers and migrates legacy config on write. When both are set, fallback_providers takes priority.
Benching: a rate-limit response that names a reset time benches the primary until exactly then; otherwise the backoff is exponential, 60 s up to 4 h. fallback.min_switch_reset_seconds (default 0) holds the switch when the declared reset is sooner than the threshold.
Local Models
Local runtimes connect through a custom endpoint: run hermes model, pick “Custom endpoint (self-hosted / VLLM / etc.)”, and enter the base URL, or set a model: block with provider: custom. The documented endpoints and context settings:
| Runtime | Base URL | Context and tool settings from the docs |
|---|---|---|
| Ollama | http://localhost:11434/v1 (no key) |
OLLAMA_CONTEXT_LENGTH=64000 ollama serve, or context_length: 64000 in config.yaml |
| vLLM | http://localhost:8000/v1 |
--max-model-len (e.g. 65536); --enable-auto-tool-choice and --tool-call-parser for tool calls |
| SGLang | launch example uses port 30000 |
--context-length; --tool-call-parser for your model family |
llama.cpp (llama-server) |
http://localhost:8080/v1 |
-c 64000; --jinja is required for tool calling |
| LM Studio | http://localhost:1234/v1 |
lms load <model> --context-length 64000 |
Hermes Agent requires at least 64,000 tokens of context for agent use with tools; smaller windows are rejected at startup. To confirm tool support on llama.cpp, check http://localhost:8080/props: the chat_template field should be present.
OpenRouter Routing
Provider routing applies only when using OpenRouter as your LLM provider; it has no effect on Nous Portal or direct provider connections. Portal decides routing centrally per model and does not accept caller-supplied preferences, so Hermes never sends the provider object there and provider_routing is simply ignored.
provider_routing:
sort: "price" # How to rank providers
only: [] # Whitelist: only use these providers
ignore: [] # Blacklist: never use these providers
order: [] # Explicit provider priority order
require_parameters: false # Only use providers that support all parameters
data_collection: null # Control data collection ("allow" or "deny")sort accepts "price" (cheapest provider first), "throughput" (fastest tokens-per-second first), and "latency" (lowest time-to-first-token first). only is a whitelist of provider slugs — when set, only those providers are used, all others excluded; use the lowercase slug OpenRouter shows, e.g. "anthropic" or "google". ignore is the blacklist of provider names. Full page: Provider routing.
Verifying Provider Health
hermes fallback check # static: resolve each entry and its credentials, no inference
hermes fallback check --live # also send one minimal request per entry, in parallel
hermes fallback check --live --json
hermes -p <profile> fallback check--live sends one short completion per statically ready entry, over that provider’s own API and never answered by another provider. Empty or malformed answers and failed/cancelled status count as failures. The command exits with status 1 when any entry is not ready, so cron jobs and CI can gate on it. JSON output reports per-entry readiness; credentials are never printed. A static pass for Bedrock or an external-process provider only proves the route resolves; use --live to prove it. A model_mismatch check is skipped for local or private-network servers, which often report a placeholder model name.
Recommended Workflow
- Run
hermes setup --portal(orhermes model→ Nous Portal) and confirm withhermes portal info. - For any additional vendor, add its key with
hermes auth add <provider>and verify withhermes auth list. - Set your primary permanently in
config.yamlundermodel:—providerplusdefault. - Add at least one
fallback_providersentry, with bothproviderandmodel. - Gate on
hermes fallback check --live --jsonin any scheduled job. - Re-check after every
hermes update, since config migration clears stale.enventries.
FAQ
What is the difference between hermes model and /model?
hermes model is the terminal setup wizard: add providers, run OAuth, enter API keys, configure endpoints. /model only switches between already-configured providers and models inside a session, and cannot add anything.
Does Nous Portal replace individual API keys?
For the models it covers, yes: “No extra API keys needed” for paid subscribers, covering 300+ frontier agentic models plus the Tool Gateway. You would still add separate keys for providers you connect directly.
How do I sign in to GitHub Copilot now?
Install the labs plugin with hermes plugins install github-copilot, then run hermes auth add copilot, or set COPILOT_GITHUB_TOKEN, GH_TOKEN, or GITHUB_TOKEN. Logins made with the gh CLI or the Copilot CLI are no longer read.
How do credential pools interact with fallbacks?
Pools are tried first, rotating within one provider. Only when all pool keys are exhausted does the fallback provider activate. Pools and fallbacks are optional and work independently.
Can I use Claude Pro or a Google consumer Gemini plan?
Claude Pro cannot use the OAuth path — the documented alternative is ANTHROPIC_API_KEY, billed independently of the subscription. For Gemini, the gemini provider is API-key only; Vertex AI uses GCP billing, and a billing-enabled Google Cloud project is recommended for agent use.
How do I keep the setup healthy after upgrades?
Run hermes fallback check --live, check hermes auth list, and note that hermes setup or config migration clears stale .env entries automatically.
The Bottom Line
Nous Portal OAuth is the documented recommended path: one login, 300+ frontier agentic models, the Tool Gateway, and no extra API keys for paid subscribers. First-class API-key providers cover everything else with a dedicated --provider ID and one env var each. config.yaml is the single source of truth for model and endpoint configuration. Pools handle same-provider key rotation and are tried first; fallback_providers handles cross-provider failover and is verified with hermes fallback check --live, which exits 1 when any entry is not ready.
How This Guide Was Built
This guide was built from official Hermes Agent documentation pages fetched 2026-11-11: Providers, Fallback providers, Credential pools, Provider routing, Nous Portal, Configuration, and Quickstart.
No hands-on tests were run by this pipeline. Nothing here is a measured result. Quoted passages come from the Providers, Fallback providers, Credential pools and Provider routing pages; the Nous Portal and Quickstart pages were fetched and are listed for reference only.
Companion Guides & External Documentation
- Nous Portal — portal login, Tool Gateway, client tag
- Configuration —
config.yamlreference - Quickstart — first install
- Credential pools — multi-key rotation
- Fallback providers — cross-provider failover and health checks
- Provider routing — OpenRouter routing keys
- github-copilot plugin — Copilot labs plugin
- Manage your Nous subscription
📖 Related Reads
- ToolBrain — tool reviews, LLM comparisons, and AI workflow guides
- NoCode Insider — AI workflow automation with no-code tools, agents, and APIs
Cross-links automatically generated from Hermes Tutorials.