Hermes Agent BYOK Setup: Bring Your Own Key Guide

What BYOK Actually Means for Hermes Agent

Hermes Agent is BYOK by design. You point it at any provider you already have credentials for, and every inference call is billed to your provider account, not to a middle layer that marks the tokens up. This is not a paywall workaround, it is the default posture of the agent: model-agnostic, provider-agnostic, and biased toward whichever backend you trust with your data.

Two things confuse people at first. First, BYOK for Hermes covers real LLM API keys (OpenAI, Anthropic, OpenRouter, Kimi, MiniMax, and dozens of others). It also covers OpenAI-compatible endpoints, which means self-hosted vLLM or Ollama servers count. Second, BYOK is per backend, not all-or-nothing. You can run Anthropic for reasoning and Ollama for cheap background summarization on the same agent, if you configure both.

The rest of this guide walks through picking a provider, storing the key without leaking it, and switching later without rebuilding your setup.

Why BYOK Matters More Than "Free API Credits"

Every AI SaaS eventually asks you to trust its opaque pooled key. BYOK breaks that model. Your credential, your bill, your data retention policy, your audit log. If the platform disappears tomorrow, your provider account keeps working.

The practical benefits, ranked by how often they matter in real Hermes deployments:

Data control. Provider-side logs, retention rules, and Zero Data Retention terms are governed by your agreement with the model provider, not by the agent vendor's negotiated defaults.
Cost transparency. No hidden markup between you and the model. If you use OpenRouter, you see the same per-token cost you would see in a raw curl request.
Vendor lock-in avoidance. Swapping providers is a two-line config change instead of a migration project. The hermes model command switches you between Claude, GPT, Gemini, or Llama without touching skills or memory.
Kill switch on your side. If a key leaks or a bill spikes, you rotate the key at the provider dashboard. The agent stops working within seconds, and no one else has to sign off on the rotation.

For Hermify's Starter plan, BYOK is the whole point. The tier is designed around "you bring the key, we run the container." That is why the setup below is worth learning even if you plan to use managed hosting later.

Step-by-Step: Set Up Your First BYOK Provider

Hermes needs at least one provider configured to run. The most frictionless path is OpenRouter (one key, hundreds of models), but the mechanics are the same for OpenAI, Anthropic, and every other supported backend.

1. Get a Key From the Provider

Pick one and generate a key from the provider's dashboard:

OpenRouter at openrouter.ai. The key starts with sk-or-. Best default for BYOK.
OpenAI at platform.openai.com. Key starts with sk-.
Anthropic at console.anthropic.com. Key starts with sk-ant-.
Kimi, MiniMax, GLM, Nous Portal, and others follow the same pattern: sign up, generate a key, copy it once.
Ollama or vLLM running on your machine. No key needed, just the URL of the OpenAI-compatible endpoint.

Add credits (or a payment method) at the provider. If the account has zero balance, Hermes will fail on the first inference call with a clear error.

2. Run the Interactive Setup

From the terminal, on the machine where Hermes lives:

hermes setup

Pick your provider from the list, paste the key, and select a model. Hermes writes the configuration for you.

If you prefer scripting, the same thing without prompts:

hermes config set OPENROUTER_API_KEY sk-or-your-key-here
hermes config set MODEL "anthropic/claude-sonnet-latest"

The ~ prefix in a model ID (~anthropic/claude-sonnet-latest) means "latest version in this family," so you do not need to keep chasing new snapshots by hand.

3. Know Where the Key Lives

Hermes stores secrets and configuration in separate files, by design:

Secrets land in ~/.hermes/.env (permissioned 600 so only the user can read it).
Provider name, model, feature flags land in ~/.hermes/config.yaml and are safe to version-control.

This split matters. You can commit config.yaml to a private repo or a dotfiles setup and reproduce a Hermes install on a new machine, then add the key on that machine from an env var or secrets manager without ever writing it to disk in cleartext.

If you version-control the config, add ~/.hermes/.env to your .gitignore. If you use a secrets manager (1Password CLI, doppler, sops, Bitwarden), you can generate the .env file at boot instead of storing the key on disk permanently.

4. Verify It Works

Send a smoke test through Hermes:

hermes chat "say hello and tell me which model you are"

If the key is wrong, the account has no credits, or the endpoint is unreachable, the error tells you which. Fix and re-run. Never move on to skills, cron jobs, or memory tuning until the provider round-trips cleanly.

Choosing the Right Provider for Your Setup

You are not locked in to a first pick. But the first pick matters, because it sets the ceiling for the memory, tool calling, and long-context work Hermes will attempt.

You want zero-friction, "just make it work": OpenRouter with ~anthropic/claude-sonnet-latest. One key, one bill, easy model swaps.
You already have an OpenAI or Anthropic account: Use the direct provider. Slightly lower per-token cost than routing through OpenRouter, but no cross-provider fallback.
You want to stay on Nous Research infrastructure: Nous Portal is the officially blessed path and pairs naturally with the Hermes system prompts.
You want to run local: Ollama or vLLM as an OpenAI-compatible endpoint. Costs nothing per token, requires a GPU-capable box, and needs a model with real tool-calling support to be useful for the agent.
You want strict data isolation: Anthropic direct (Zero Data Retention on request) or a self-hosted endpoint. Do not route through aggregators if this is your priority.

Hermes needs a model with at least 64K context tokens, because persistent memory files (MEMORY.md, USER.md, skills) get injected on every call. Smaller-context models silently drop context, which breaks the memory loop that makes Hermes different from a stateless chatbot.

If you want a deeper walkthrough on picking the model itself, see How to Configure Hermes Agent with OpenRouter.

Configuration Mistakes to Avoid

A few patterns burn users on their first BYOK setup:

Committing the .env file. The single most common mistake. Even a "private" GitHub repo is not a safe place for sk- keys. Add .env to .gitignore from day one.
Choosing a model without tool-call support. Some cheaper OpenRouter models cannot call tools. Hermes needs tool calls for file writes, web fetches, scheduled tasks, and MCP. If skills silently stop working, check the model's capability flags.
Under-funding the provider account. Providers pause requests when credits hit a threshold. Set an auto-reload floor at OpenRouter or a low-balance alert at OpenAI so a long-running Hermes cron does not die at 3am.
Storing the key in shell history. hermes config set OPENROUTER_API_KEY sk-or-... writes to .bash_history by default. Prefer hermes setup (interactive, no history), or prefix the command with a space if your shell is configured to skip such lines.
Assuming one key covers everything. MCP tools that need their own credentials (a GitHub token, a Notion API key) are separate BYOK slots. The LLM key does not unlock them.
Not rotating. Set a calendar reminder every 90 days to rotate the provider key. hermes config set overwrites the old value cleanly.

If you get stuck, Hermes Agent Telegram troubleshooting covers the common failure modes end-to-end.

What Changes With Managed Hosting

Everything above is what a self-hosted Hermes install looks like. If you deploy through Hermify, the BYOK model is identical (your key, your bill, your data) but the mechanics move into a dashboard:

Paste the OpenRouter, OpenAI, or Anthropic key once in the onboarding flow.
Hermify encrypts it at rest and injects it into your container at boot. It is never visible in logs, never shown back after save, and rotates cleanly on demand.
Switch models from the dashboard without SSHing anywhere. The change takes effect on the next agent restart, which is one click away.
The Starter plan is BYOK-only by design. Pro and Dedicated include a managed key if you would rather skip the provider signup entirely, but you can still bring your own if you prefer.

The point is that BYOK is not a self-hosted-only feature. It is a posture: your credential, your data, your kill switch. Managed hosting preserves it, it just handles the ops around it.

Get Started

If you are self-hosting, run hermes setup, paste your key, and you are done. If you want the same BYOK model without the container maintenance, get started with Hermify and you are live on Telegram in about a minute.

Either way, keep the key on your side of the fence. That is what BYOK is for.