Hermes Agent API Keys: Provider Setup, Secret Safety, and Smoke Tests

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.

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.

What this guide is for#

People searching for Hermes Agent API keys usually have an operational question, not a curiosity question. They want to know which key is needed, where it belongs, what can safely be skipped, and how to prove the provider works before wiring a gateway or background agent.

This page is intentionally narrow. It is not a tour of every Hermes feature. If you are evaluating Hermes for the first time, start with install Hermes Agent. If you already run Hermes locally and want a browser/control surface, use the Hermes dashboard guide. If the question is total operating cost, compare Hermes pricing and provider costs before overbuilding your own stack.

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 by hermes doctor and 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, GitHub Copilot, or another direct 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.

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:

1. Run hermes config path and hermes config env-path so you know the exact files being used.
2. Add only the provider key needed for the first test.
3. Do not paste API keys into prompts, public Git commits, screenshots, support threads, or blog comments.
4. If you use profiles, run hermes -p <profile> config env-path before assuming the gateway has the same secrets as your CLI.
5. Restart the CLI or gateway after environment changes; a running process may not reload new keys.
6. 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.

A sudden 401: repair the endpoint that rejected the request#

An October 1 support case traced a generic gateway authentication message to a DeepSeek 401. The user reported recovery after replacing the key; the thread also mentioned a provider incident. This supports checking the exact error and provider status, not rotating every credential whenever a bot stops replying.

Before replacing a secret, record the failing provider, endpoint, profile and timestamp. Test under the same operating-system account and Hermes profile as the gateway. A working key on your laptop does not prove a VPS service loaded it. If the endpoint still explicitly rejects the credential, update only that credential through the supported setup flow, safely reload its owning service and verify one short request plus the original channel reply.

Never paste the replacement into chat or a public diagnostic bundle. Do not remove local-server authentication to make a 401 disappear. For a balance, per-key cap or in-flight spending error, use the provider error and billing checklist instead: those are not key-rotation problems.

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 login flow 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:

1. CLI provider smoke test.
2. Tool-calling test if the workflow needs tools.
3. Dashboard or Web UI check if you need local operations visibility.
4. Gateway test for Telegram, Discord, Slack, email, or another channel.
5. Cron or background-job test with a harmless scheduled command.
6. 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.

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.json contents.
• Browser cookies, session tokens, or copied request headers.
• Full .env files 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.

Give every credential a billing owner#

For each key or OAuth route, record the owner, provider account, billing project, intended Hermes profile, allowed workload, and spending ceiling. A valid secret only proves authentication; it does not prove that the route is the one you meant to fund. Fresh August support evidence shows why unattended gateways need provider-side caps and profile isolation. If usage spikes, follow the unexpected provider spend checklist before rotating keys and destroying the evidence trail.

Match every credential to its wallet#

Before debugging a provider failure, write down the provider, authentication method, model ID, active profile, and wallet or subscription expected to pay. OAuth subscription access, a direct API key, OpenRouter credit, and a local endpoint are separate routes. A working consumer subscription does not prove the API wallet is funded. The provider cost and rate-limit guide maps 401, 402, 403, 429, and output-limit errors to the right fix.

A valid key does not prove the intended billing route#

When a provider bill names an unexpected model, preserve the request window before replacing credentials. The provider spend proof runbook shows how to reconcile the active profile, model, auxiliary routes, Hermes logs, and provider usage without exposing secrets.