--- title: "Hermes Agent setup with one prepaid API key" canonical: https://relayswitch.io/guides/hermes-agent generated: 2026-11-02T10:11:08.989Z source: https://api.relayswitch.io/v1/catalog base_url: https://api.relayswitch.io/v1 --- Checked 2026-10-30 # Hermes Agent on one prepaid key Add RelaySwitch to Hermes Agent as a named provider: one entry in config.yaml, a key for Hermes alone with its own budget in .env, any model id on the catalog. Pay as you go, by card or crypto. Hermes Agent takes any OpenAI-compatible endpoint as a named entry under `providers` in `~/.hermes/config.yaml`. Point one at `https://api.relayswitch.io/v1` and every chat model on the [Models page](https://relayswitch.io/models) becomes a `custom:relayswitch:` ref, Claude included, billed per token from a prepaid balance. No subscription, no monthly fee: the balance only moves when a request runs. The block below is the current `providers` form. Older guides show a `custom_providers` list; Hermes still reads it and `hermes update` migrates it, but new setups use the mapping. ## 01What you need - Hermes Agent installed. The one-line installer below is for Linux, macOS and WSL2; native Windows has a PowerShell installer in Hermes Agent's docs. - A RelaySwitch key from the [console](https://app.relayswitch.io/console) (email-code sign-in). Keys start with `sk-relay-`. Create one for Hermes alone, so its requests sit apart from any other tool on the Usage page. - A prepaid balance, from $10 by card or crypto, no KYC. The console chat runs 12 free turns a day before the first top-up; Hermes requests bill the balance. bash 1`curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash` Nothing is installed on the RelaySwitch side. The base URL and the key are the whole configuration. ## 02Where the settings are Settings live in `~/.hermes/config.yaml`; secrets live in `~/.hermes/.env`. Hermes reads CLI flags first, then `config.yaml`, then `.env`, then its defaults. A value in `config.yaml` can reference a variable as `${VAR_NAME}`, and a `providers` entry can name one with `key_env`, which is the form used here. Put the key in the env file, one line: bash 1`RELAYSWITCH_API_KEY=sk-relay-...` ## 03The Hermes Agent providers entry yaml 1`model:` 2 `default: claude-sonnet-5-5` 3 `provider: custom:relayswitch` 4 5`providers:` 6 `relayswitch:` 7 `api: https://api.relayswitch.io/v1` 8 `key_env: RELAYSWITCH_API_KEY` 9 `transport: chat_completions` 10 `default_model: claude-sonnet-5-5` 11 `models:` 12 `claude-sonnet-5-5: {}` 13 `claude-opus-5-5: {}` 14 `gpt-6.1-sol: {}` 15 `gemini-3.1-pro-preview: {}` 16 `deepseek-v4-pro-0813: {}` 17 `kimi-k3.1-pro: {}` 18 `glm-5.3: {}` 19 `hermes-4-405b: {}` - `api`: the endpoint, with the `/v1`. Hermes also accepts `base_url` as an alias for the same field. - `key_env` names the variable in `.env` that holds the key. The key never sits in `config.yaml`. - `transport: chat_completions`: every id on the Models page answers that format here, Claude included, so one entry covers the whole catalog. - `models` is a mapping keyed by model id. An empty value takes the defaults; `context_length` under an id overrides what Hermes detects when that comes out wrong. The ids above are a starting list, read from the catalog at render; any other id on the Models page goes in the same mapping. - `model.provider` selects the entry as `custom:relayswitch`; `model.default` is the id Hermes starts with. The same block from the shell. Dotted paths go to `config.yaml`; the UPPER\_SNAKE key goes to `.env`: bash 1`hermes config set RELAYSWITCH_API_KEY sk-relay-...` 2`hermes config set providers.relayswitch.api https://api.relayswitch.io/v1` 3`hermes config set providers.relayswitch.key_env RELAYSWITCH_API_KEY` 4`hermes config set providers.relayswitch.transport chat_completions` 5`hermes config set model.provider custom:relayswitch` 6`hermes config set model.default claude-sonnet-5-5` `hermes model` does the same through a wizard: choose the custom endpoint option and enter the base URL, the key and a model id. For a single run with nothing written to disk, the launch-only flags hold the key in memory: bash 1`hermes chat --provider custom --base-url https://api.relayswitch.io/v1 --api-key sk-relay-... --model claude-sonnet-5-5` Field names follow Hermes Agent's [providers page](https://hermes-agent.nousresearch.com/docs/integrations/providers), [configuration guide](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) and [CLI reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) (read 2026-10-30). ## 04A key for Hermes Agent alone, with a budget Give Hermes Agent its own key instead of the one you use elsewhere. A key carries a prepaid budget in USD, an allowed-model list, a Requests / min and tokens / min limit, a monthly cap and an expiry. The budget is a hard stop for that key: the balance is what is debited, and when the key reaches its budget it answers `402` while every other key on the account keeps running. In the [console](https://app.relayswitch.io/console), open Keys, create a key named `hermes-main`, set its budget and tick the models it may call. Or do the whole thing by API with an admin key: bash 1`# $ADMIN_KEY is an admin key, created once in the console (Keys, "Admin key").` 2`curl https://api.relayswitch.io/v1/keys \` 3 `-H "Authorization: Bearer $ADMIN_KEY" \` 4 `-H "Content-Type: application/json" \` 5 `-d '{"name": "hermes-main", "budget_usd": 20, "rpm": 60, "monthly_cap_usd": 100,` 6 `"allowed_models": ["claude-sonnet-5-5", "claude-opus-5-5", "gpt-6.1-sol"]}'` 7 8`# 201: the full key, once, with its record.` 9`# {"key": "sk-relay-...", "data": {"id": "k7m2...", "budget_micro": 20000000,` 10`# "budget_spent_micro": 0, "budget_remaining_micro": 20000000, ...}}` An admin key manages keys through `GET`, `POST`, `PATCH` and `DELETE https://api.relayswitch.io/v1/keys` and cannot call a model, so a leaked admin key spends nothing. Put the key the call returns where Hermes Agent reads it, and watch the agent's spend on its own line: bash 1`# Requests and spend today, this month and in all, and what is left of the budget.` 2`curl https://api.relayswitch.io/v1/keys/KEY_ID/usage -H "Authorization: Bearer $ADMIN_KEY"` 3 4`# Raise the budget (never under what is spent), narrow the models, pause or resume.` 5`curl -X PATCH https://api.relayswitch.io/v1/keys/KEY_ID \` 6 `-H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \` 7 `-d '{"budget_usd": 40, "status": "active"}'` `POST https://api.relayswitch.io/v1/keys` takes `name` and, optionally, `allowed_models`, `rpm`, `tpm`, `monthly_cap_usd`, `budget_usd` and `expires_at` (Unix milliseconds). `PATCH` takes the same fields plus `status`; a budget may go up or down but never under what the key has spent, and `null` removes it. The shapes are in the [docs](https://relayswitch.io/docs#key-api) and in the OpenAPI document under the `keys` tag. ## 05Which model to pick Hermes needs tool calling for every file read, shell command and subagent, so pick a model that returns tool calls; the ids in the mapping above all do. Before a long task with another id, send one short task and check that Hermes runs a tool. Input price decides the session cost, because Hermes sends the conversation and every tool result back on each turn; pick by the input column. | Model | Input | Cached | Output | Developer list in / out | Context | | --- | --- | --- | --- | --- | --- | | [Claude Sonnet 5.5](https://relayswitch.io/models/claude-sonnet-5-5) | $1.20 (40% under) | $0.075 | $3.00 (70% under) | $2.00 / $10.00 | 1M tokens | | [Claude Opus 5.5](https://relayswitch.io/models/claude-opus-5-5) | $2.80 (30% under) | $0.15 | $10.00 (50% under) | $4.00 / $20.00 | 1M tokens | | [GPT-6.1 Sol](https://relayswitch.io/models/gpt-6.1-sol) | $0.60 (70% under) | $0.06 | $3.00 (70% under) | $2.00 / $10.00 | 1.1M tokens | | [Gemini 3.1 Pro Preview](https://relayswitch.io/models/gemini-3.1-pro-preview) | $1.20 (40% under) | $0.12 | $7.20 (40% under) | $2.00 / $12.00 | 1M tokens | | [DeepSeek V4 Pro 0813](https://relayswitch.io/models/deepseek-v4-pro-0813) | $0.792 (40% under) | $0.0625 | $1.188 (70% under) | $1.32 / $3.96 | 1M tokens | | [Kimi K3.1 Pro](https://relayswitch.io/models/kimi-k3.1-pro) | $1.00 (50% under) | $0.10 | $5.00 (50% under) | $2.00 / $10.00 | 1M tokens | | [GLM 5.3](https://relayswitch.io/models/glm-5.3) | $0.3276 (70% under) | $0.068 | $1.0296 (70% under) | $1.092 / $3.432 | 1M tokens | | [Hermes 4 405B](https://relayswitch.io/models/hermes-4-405b) | $1.20 | input rate | $4.80 | — | 128K tokens | USD per million tokens, read from the RelaySwitch catalog when this page was built. Developer list: the catalog's record of the developer's own price. Switch inside a session with `/model`; the change lasts for that session unless `--global` writes it back to `config.yaml`: text 1`/model custom:relayswitch:claude-opus-5-5` 2`/model custom:relayswitch:gpt-6.1-sol --global` How the prepaid balance and the cached rate work is on [Pricing](https://relayswitch.io/pricing). ## 06What a turn costs One agent turn at 30,000 input tokens and 1,000 output tokens: a session that has read a few files and run a command or two. Input dominates because the conversation and tool results travel up again on every turn. Nothing is counted at the cached rate; the sizes are an assumption, and the console's Usage page shows your real ones. | Model | One turn | 30 turns | | --- | --- | --- | | [GLM 5.3](https://relayswitch.io/models/glm-5.3) | $0.0109 | $0.3257 | | [GPT-6.1 Sol](https://relayswitch.io/models/gpt-6.1-sol) | $0.021 | $0.63 | | [DeepSeek V4 Pro 0813](https://relayswitch.io/models/deepseek-v4-pro-0813) | $0.0249 | $0.7484 | | [Kimi K3.1 Pro](https://relayswitch.io/models/kimi-k3.1-pro) | $0.035 | $1.05 | | [Claude Sonnet 5.5](https://relayswitch.io/models/claude-sonnet-5-5) | $0.039 | $1.17 | | [Hermes 4 405B](https://relayswitch.io/models/hermes-4-405b) | $0.0408 | $1.22 | | [Gemini 3.1 Pro Preview](https://relayswitch.io/models/gemini-3.1-pro-preview) | $0.0432 | $1.30 | | [Claude Opus 5.5](https://relayswitch.io/models/claude-opus-5-5) | $0.094 | $2.82 | The turn above at the live per-token prices, read from the catalog at render. Claude Sonnet 5.5 is $0.039 for that turn, so a 30\-turn session is $1.17. GLM 5.3 has the lowest turn cost in the table, so the same session is $0.3257 there. When a response reports cached input tokens, they bill at the model's cached rate where it has one, shown in the table above. ## 07Check it `hermes status` shows the model, the active provider and which providers have a credential, without printing key values. From the same shell, the key should list the models: bash 1`hermes status` 2`curl https://api.relayswitch.io/v1/models -H "Authorization: Bearer $RELAYSWITCH_API_KEY"` Then send one request the way Hermes does. `-i` prints the headers, including the request id: bash 1`curl -i https://api.relayswitch.io/v1/chat/completions \` 2 `-H "Authorization: Bearer $RELAYSWITCH_API_KEY" \` 3 `-H "Content-Type: application/json" \` 4 `-d '{"model": "claude-sonnet-5-5", "max_tokens": 16, "messages": [{"role": "user", "content": "Say ok."}]}'` Then run `hermes` and send a message. The request shows on the [console](https://app.relayswitch.io/console) Usage page within seconds, with its tokens and its charge. ## 08Sessions, caps and tools for long runs Register your MCP servers once on the [MCP gateway](https://relayswitch.io/features/mcp-gateway) and Hermes Agent reaches all their tools through one endpoint on its own key. Hermes Agent reads remote servers from `mcp_servers` in config.yaml, with a `url` and `headers` (the Hermes [MCP](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) page): yaml 1`# ~/.hermes/config.yaml` 2`mcp_servers:` 3 `relayswitch:` 4 `url: "https://api.relayswitch.io/mcp/org"` 5 `headers:` 6 `Authorization: "Bearer sk-relay-..."` Any request that declares web search ($0.01 a search), web fetch, a code sandbox ($0.05 a container-hour, 1-minute minimum) or a remote MCP server in the OpenAI or Anthropic tool shape has the tool run by the API inside the same call, with citations and a receipt per round. Details on [agent tools](https://relayswitch.io/features/agent-tools) and [observability](https://relayswitch.io/features/observability). ## 09Check the model is the one on the label Every model in the catalog gets the same canary prompt each day and its answer is compared with the last one. The result is public at [https://api.relayswitch.io/v1/proof](https://api.relayswitch.io/v1/proof), no key needed, so before a long Hermes Agent run you can see whether the id you set answered as it did yesterday. 305 / 339Models unchanged on today’s check21 changed, 13 not reached; read 2026-11-02T09:20 UTC Every request Hermes Agent sends has a signed receipt with the model, the billed tokens and the charge in USD, streamed or not. Fetch it by the request id from the response headers, and check the signature on the [Verify page](https://relayswitch.io/statements/verify): bash 1`curl https://api.relayswitch.io/v1/requests/REQUEST_ID/receipt \` 2 `-H "Authorization: Bearer $RELAYSWITCH_API_KEY"` ## 10Errors and fixes - `401`: the key is wrong, revoked or not reaching the request. Check `~/.hermes/.env` for the line, confirm `key_env` names the same variable, and copy the key again from the console. - `402`: the balance is too low, or the key reached its own budget or monthly cap. Top up in the console, or raise the budget on the key; it works again at once. - `404`: the id in `model.default` is not on the Models page. A dot, a dash or a date suffix out of place is enough. Copy the id from the page and set it with `hermes config set model.default `. - `429`: the key hit its rate limit. Wait and resend, or create a key with a higher Requests / min in the console. - A `400` on the first run: Hermes' own FAQ puts this down to a model name mismatch. Run `hermes config show` and compare `model.default` against the Models page. - Every custom endpoint is ignored: an old `custom_providers` key in `config.yaml` is no longer a YAML list. Make it a list again or move the entry to the `providers` mapping on this page, then run `hermes doctor`. The full error table is in the [docs](https://relayswitch.io/docs). ## Questions Can Hermes Agent use a custom OpenAI-compatible API? Yes. Hermes Agent takes any OpenAI-compatible endpoint as a named entry under providers in ~/.hermes/config.yaml, with api, key\_env and transport chat\_completions. The block on this page points it at https://api.relayswitch.io/v1, and every chat model on the Models page then runs through it, Claude included. How do I change the model Hermes Agent uses? Set model.default to the model id and model.provider to custom:relayswitch, or run /model custom:relayswitch: inside a session. Add --global to the /model command to write the choice back to config.yaml. Copy the id from the Models page rather than typing it. Where does the API key go for Hermes Agent? In ~/.hermes/.env, as RELAYSWITCH\_API\_KEY=... on one line. hermes config set with an UPPER\_SNAKE name writes there too. The providers entry reads it through key\_env, so the key never sits in config.yaml. Does Hermes Agent run Claude through the same entry? Yes. The Claude ids here answer the OpenAI chat completions format, so they go in the same providers entry as the GPT, Gemini, DeepSeek and Kimi ids, with transport chat\_completions and one key. No second provider and no separate Anthropic key. How does Hermes Agent get billed on this key? Each request bills per token to the prepaid balance behind the key, at the live rates in the table above, with no subscription and no monthly fee. The console Usage page shows every request within seconds with its tokens and its charge. How do I top up the balance Hermes Agent spends from? In the console, by card or in USDT, USDC, BTC, ETH or SOL, from $10. No KYC. The key works again the moment the top-up lands. How do I cap what Hermes Agent can spend? Give Hermes its own key with budget\_usd set, in the console under Keys or with POST https://api.relayswitch.io/v1/keys and an admin key. At its budget the key answers 402 and other keys on the account keep running; GET https://api.relayswitch.io/v1/keys/:id/usage shows the spend today, this month and in all. Related - [All guides](https://relayswitch.io/guides) - [OpenClaw](https://relayswitch.io/guides/openclaw) - [OpenCode](https://relayswitch.io/guides/opencode) - [Claude Code](https://relayswitch.io/guides/claude-code) - [Key API](https://relayswitch.io/docs#key-api) - [Models and prices](https://relayswitch.io/models) - [How pricing works](https://relayswitch.io/pricing) - [Pay by card or crypto](https://relayswitch.io/pay-with-crypto) - [Docs](https://relayswitch.io/docs) ## Run Hermes Agent on a prepaid balance One key, from $10 by card or crypto. No KYC, no subscription. [Models](https://relayswitch.io/models)[Get a key](https://app.relayswitch.io/console)