Hermes Agent on one prepaid key

• 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 (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.

Nothing is installed on the RelaySwitch side. The base URL and the key are the whole configuration.

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:

• 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:

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:

Field names follow Hermes Agent's providers page, configuration guide and CLI reference (read 2026-10-30).

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, 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:

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:

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 and in the OpenAPI document under the keys tag.

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.

Switch inside a session with /model; the change lasts for that session unless --global writes it back to config.yaml:

How the prepaid balance and the cached rate work is on Pricing.

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.

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.

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:

Then send one request the way Hermes does. -i prints the headers, including the request id:

Then run hermes and send a message. The request shows on the console Usage page within seconds, with its tokens and its charge.

Register your MCP servers once on the 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 page):

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 and observability.

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, no key needed, so before a long Hermes Agent run you can see whether the id you set answered as it did yesterday.

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:

• 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 <id>.
• 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.