Configure one Hermes Agent model-provider route, keep its credentials out of prompts and logs, and verify the account that serves the first request before connecting unattended work.
Quick answer#
For Hermes Agent API keys, pick one provider route first: Nous Portal for the fastest Nous-native setup, OpenRouter for broad model routing and fallback choices, Ollama/local models when privacy matters more than cloud quality, or FlyHermes when you do not want to maintain provider keys, VPS uptime, gateways, and cron delivery yourself. Put static keys in the active profile's .env file, never in config.yaml, prompts or screenshots, then run hermes doctor and one tiny hermes chat -q "reply ok" smoke test before adding Telegram, Discord, cron jobs, dashboard access, Docker, or team workflows.
Provider auth is a route, not just a brand#
A provider can expose both OAuth/subscription access and API-key billing. Those routes may use the same model name but different balances and entitlements. If a fallback reaches 402 while another machine still works, compare the active profile, provider ID, auth type, and credential on each machine before replacing keys. The AI agent rate-limit guide maps 401, 402, 429, paid-model session state, credential pools, and auxiliary routes to the right repair.
After adding a provider with hermes model, start a new chat before judging the change. Existing conversations can retain their selected model; a newly available free model does not automatically rewrite an older paid-model session.
In the current gateway-backed classic CLI, creation options such as provider, model and base URL are frozen into a session. Do not try to change them by adding different flags to --resume; use the documented /model switching command, or start a genuinely new chat for a clean acceptance check. The CLI session contract, checked November 8, 2026, documents this boundary. A successful new chat does not prove an older resumed conversation changed accounts. Match the test timestamp and actual provider route to the expected usage record before treating credential replacement as complete.
Choose one provider path first#
Most setup failures happen because people try to solve model access, gateway delivery, Docker networking, dashboard exposure, and cron reliability at the same time. Choose one provider path first, verify it from the CLI, then expand.
- Nous Portal: use Nous Portal when you want the official Nous ecosystem route, hosted model access, and Tool Gateway services. The shortest path is
hermes setup --portal, followed byhermes doctorand one CLI chat smoke test. - OpenRouter: use OpenRouter with Hermes when you want many model choices, fallback options, and explicit credit control. This is useful for rate-limit resilience and budget switching.
- Direct provider keys: use Anthropic, OpenAI, DeepSeek, Hugging Face, or another direct API provider when your organization already buys that provider and wants a simpler bill.
- Local models: use Ollama with Hermes when privacy and zero API spend matter more than maximum reasoning quality or uptime.
- Managed FlyHermes: use FlyHermes pricing when provider setup, gateway uptime, dashboard access, phone access, and cron delivery should be handled as a managed service instead of a self-hosted project.
GitHub Copilot: migrate the login, not the secret files#
The current github-copilot labs plugin is built by Nous Research but unsupported. Its copilot API provider no longer reads gh or Copilot CLI token files. If gh auth status succeeds while Hermes reports missing Copilot credentials, use the interactive hermes auth add copilot flow in the owning profile; copying another tool's token files is not the migration procedure. The separate copilot-acp route uses the installed Copilot CLI and copilot login.
For API tokens, the documented precedence is COPILOT_GITHUB_TOKEN, GH_TOKEN, then GITHUB_TOKEN. Classic ghp_ PATs are rejected; the plugin documents OAuth gho_, GitHub App ghu_, and fine-grained github_pat_ tokens with Copilot Requests permission. Prefer the interactive flow rather than exposing a secret in a command argument. A token's format is not proof of account entitlement.
Follow the Copilot plugin setup checklist, then verify one harmless request and its actual account/model. Source: official Copilot plugin documentation, checked November 4, 2026. This is a documented authentication change, not a claim that a paid Copilot test was performed.
Where Hermes secrets belong#
Hermes keeps settings and secrets separate. Use hermes config path for the YAML config and hermes config env-path for the environment file. Profiles have their own config and env files, so a key placed in the default profile will not automatically exist in a separate Telegram bot or project profile.
Copy this checklist before adding any key:
- Run
hermes config pathandhermes config env-pathso you know the exact files being used. - Add only the provider key needed for the first test.
- Do not paste API keys into prompts, public Git commits, screenshots, support threads, or blog comments.
- If you use profiles, run
hermes -p <profile> config env-pathbefore assuming the gateway has the same secrets as your CLI. - Restart the CLI or gateway after environment changes; a running process may not reload new keys.
- Keep bot tokens, provider keys, OAuth tokens, and webhook secrets out of reusable skills unless the skill only names the variable, not the value.
Minimal self-hosted smoke test#
Use this sequence before debugging anything higher-level:
hermes doctor
hermes config path
hermes config env-path
hermes chat -q "Reply with exactly: provider ok"
If that tiny prompt fails, do not debug Telegram, Discord, Slack, cron, or the dashboard yet. Fix the model/provider layer first. If it succeeds, then test the next layer with one visible artifact: a sent message, a created file, a completed scheduled job, a received webhook, or a gateway log line.
Check where the rejected credential came from#
A key in the right file can still be the wrong credential for a running request. Start with the host, operating-system user and profile that own the workload. Record the selected provider, endpoint and model, then inspect the credential pool. Do not print the key to compare it.
For example, replace work and deepseek with the actual profile and provider:
hermes -p work config env-path
hermes -p work config get model
hermes -p work auth list deepseek
The auth list identifies pool entries and their sources. An environment-backed entry, a manually added key and an OAuth login are different things; editing an unrelated .env entry will not repair a rejected OAuth grant. Provider-specific credential priority also matters. The official provider reference documents those differences; do not apply one provider's lookup order to every other provider.
Open the interactive hermes -p work auth add deepseek flow only after identifying the failing route. Keep the old working routes intact while you test the intended replacement. A long-running service may need a safe reload before it uses the new configuration. Follow the authentication recovery checklist for the exact error branches and final channel test.
If the key-entry prompt stays blank, do not paste repeatedly or put the secret into an echo command. Use the API-key paste troubleshooting guide. The goal is to prove one authorized request, not to make a secret visible on screen.
Common provider failure patterns#
- Wrong profile: the CLI works but the gateway fails because the gateway runs under a different Hermes profile with a different
.env. - Wrong model name: the provider key is valid but the configured model slug is not available from that provider.
- Missing OAuth refresh: OAuth-backed providers such as Nous Portal or OpenAI Codex may need a fresh
hermes loginflow instead of another API key. - Exhausted credits: OpenRouter or direct API calls can fail when credits are depleted even though the key format is correct.
- Rate limits: a provider may work for one prompt and fail during multi-tool tasks because agent loops make repeated calls.
- Gateway cache: the gateway may keep old process state after config changes. Restart the gateway before assuming the token is bad.
- Docker/env mismatch: a Docker-backed runtime can have a different environment from your local shell.
For broader provider economics, use the model provider cost and rate-limit guide. For reliability planning, use Hermes provider fallbacks.
Provider keys before gateways, cron, and dashboard#
A Hermes integration can look broken when the provider is actually the failing layer. Use this order:
- CLI provider smoke test.
- Tool-calling test if the workflow needs tools.
- Dashboard or Web UI check if you need local operations visibility.
- Gateway test for Telegram, Discord, Slack, email, or another channel.
- Cron or background-job test with a harmless scheduled command.
- Only then move to VPS, Docker, team, or production workflows.
This sequence matches the support evidence: provider/model confusion often shows up as gateway silence, missed cron jobs, or a dashboard that appears healthy while actual turns fail.
Self-hosted vs managed decision#
Self-hosting Hermes is powerful because you control provider choice, profiles, skills, memory, tools, and where the runtime lives. It is also operational work. You own secret storage, provider credits, OAuth refresh, gateway uptime, Docker/VPS maintenance, log inspection, and delivery checks.
Use self-hosted Hermes when you want that control. Use FlyHermes when the desired outcome is a managed AI agent reachable from browser/mobile channels without maintaining the provider and gateway stack yourself. If you are deciding between the two, read self-hosted vs hosted AI agent before committing to a VPS.
Practical setup checklist#
- Confirm the base agent works — run one local Hermes prompt before adding any integration, backend, or UI layer.
- Choose the narrow workflow — define the smallest outcome that proves the provider key works.
- Add credentials safely — place static API keys, bot tokens, and webhook secrets in the owning profile's .env or supported secret store, never in prompts or committed content.
- Enable only the needed tools — give Hermes the specific browser, terminal, messaging, file, or web tools required for this workflow.
- Run a visible smoke test — send one message, create one file, complete one background job, or receive one webhook event.
- Save the procedure — after the first success, turn the verified steps and pitfalls into a Hermes skill so the workflow improves next time.
This order matters. If the model key is wrong, every gateway looks broken. If the workspace mount is wrong, every Docker run looks like a reasoning failure. If a bot token is copied into the wrong profile, the agent can be healthy while the integration stays silent.
What not to put in a prompt#
Never paste these into a chat prompt, public issue, screenshot, or support thread:
- API keys such as OpenRouter, Anthropic, OpenAI, DeepSeek, Hugging Face, Gemini, or provider-specific tokens.
- Telegram, Discord, Slack, WhatsApp, email, or webhook credentials.
- OAuth refresh tokens or
auth.jsoncontents. - Browser cookies, session tokens, or copied request headers.
- Full
.envfiles or launchd/service files that contain secrets. - Production database, Stripe, PostHog, GitHub, or Vercel credentials.
If you need help debugging, share the command, the redacted provider name, the error class, and whether hermes doctor and the tiny CLI smoke test passed. Redact the secret value itself.
Continue with the setup you need#
- Nous Portal setup for Hermes Agent — official Nous account/provider route.
- OpenRouter for Hermes Agent — model routing, credits, and fallback choices.
- Hermes provider costs and rate limits — choose a provider without surprise bills.
- Hermes provider fallbacks — avoid one-provider outages.
- Hermes dashboard and Web UI — inspect local operations after the provider works.
- Hermes pricing — managed FlyHermes route.
- Install Hermes Agent — base install path.
- Self-hosted vs hosted AI agent — decide whether to maintain the stack yourself.
A dead OAuth login needs a different repair from a cooldown#
Current credential-pool documentation separates temporarily exhausted credentials from permanently rejected OAuth grants. A cooldown can expire; a login rejected with invalid_grant, invalid_token, or refresh_token_reused requires reauthentication. Repeatedly clearing a timer does not repair a revoked grant.
Inspect hermes auth list <provider> under the owning profile, then use hermes auth add <provider> when that specific login needs repair. Do not copy token files into several homes as a substitute for a supported login flow. Two logins to the same OpenAI account do not create extra quota and can invalidate an older token family. The provider fallback setup and verification guide distinguishes auth repair from authorized backup capacity. Never paste auth-store contents into a support thread.
Source: official Hermes fallback and recovery documentation, checked October 1, 2026.
Multiple keys: use the credential pool#
Do not paste a second provider key over the first one when you need controlled rotation. Use hermes auth add to register an authorized credential, hermes auth list to inspect the pool without exposing secret values, and hermes auth reset <provider> after a temporary exhaustion window clears. Credential pools handle same-provider keys; provider fallbacks handle a different provider or local endpoint. Label every key by owner and billing account, and remove stale credentials before handing a profile to a team or gateway service.
Bottom line#
Configure exactly one provider first, keep secrets in the right file, verify one real Hermes response, and only then add gateways, cron jobs, dashboards, Docker, VPS hosting, or team workflows. If the provider layer works but you do not want to own the rest of the operations stack, use FlyHermes as the managed path.
Record the credential owner before unattended use#
Keep a private record of the provider account, billing project, intended Hermes profile, credential label, allowed workload and spending ceiling. Record the source of the credential without copying its value. OAuth subscription access, a direct API key and router credit can have different entitlements under the same provider brand.
After one successful reply, check the provider's request record before restoring unattended traffic. If the bill names an unexpected route, preserve the request window and inspect primary, auxiliary and fallback calls using the provider spend checklist. Rotating keys first can remove useful evidence without fixing the routing mistake.