Hermes Agent

Hermes Agent connects to Actualyze as a custom endpoint over the OpenAI Chat Completions API. You can add it with the hermes model setup wizard or as a named provider in ~/.hermes/config.yaml. Hermes reads Actualyze's /models endpoint: its pickers list the models your key can call, and it takes each model's context window from the listing, so you don't declare models or windows yourself. Two Hermes defaults matter here: it refuses to start with a model whose context window is under 64,000 tokens, and it sends reasoning_effort: medium on every request unless you set an effort yourself.

#Before you start

• An Actualyze API key with the inference scope and read-write permission. Workspace Admins, Members and FinOps Managers who belong to a team can create one: in the Actualyze app, select API Keys under ADMIN in the sidebar (every role that can hold keys sees this page, not only admins), then select Create API Key. Keep the default Read & Write permission. The key's budget is the one your Hermes usage draws down.
• A model your key can call that supports tool calling and has a context window of at least 64,000 tokens. Choose a model shows how to check both.

#Install

If Hermes isn't installed yet, the install script works on macOS, Linux and WSL2:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Reload your shell (source ~/.bashrc or source ~/.zshrc) before running hermes. On native Windows, run iex (irm https://hermes-agent.nousresearch.com/install.ps1) in PowerShell; Hermes then keeps its files in %LOCALAPPDATA%\hermes\, so read that folder wherever this guide says ~/.hermes/. Nous Research's installation guide covers the desktop packages and the other install methods.

#Connect to Actualyze

#With the setup wizard

Run hermes model in your terminal, outside any Hermes session, and choose Custom endpoint (enter URL manually). Answer the prompts in this order:

After the API key, Hermes calls the endpoint's /models and reports how many models it can see. That count is a quick check that the URL and key work. After the display name, Hermes prints the context length it detected for the model you picked. The wizard saves the endpoint to ~/.hermes/config.yaml and the API key to ~/.hermes/.env as HERMES_CUSTOM_APP_ACTUALYZE_AI_API_KEY.

#In config.yaml

A named provider keeps the endpoint in config.yaml and the API key in ~/.hermes/.env, where Hermes keeps secrets:

providers:
  actualyze:
    api: https://app.actualyze.ai/openai/v1
    key_env: ACTUALYZE_API_KEY
    transport: chat_completions
 
model:
  default: <model-id>
  provider: custom:actualyze

ACTUALYZE_API_KEY=<your-actualyze-api-key>

• api is the OpenAI-compatible endpoint. Keep the trailing /openai/v1.
• key_env names the variable in ~/.hermes/.env that holds your API key.
• transport: chat_completions makes Hermes use Chat Completions. Without it, Hermes guesses the API from the URL.
• model.default is the model a new session starts on. Hermes lists the rest from the endpoint, so the file doesn't name them.

#Choose a model

Model names are catalog model IDs or Virtual Model slugs, written exactly as Actualyze lists them, without adding a provider/ prefix of your own. Hermes lists them for you from Actualyze's /models endpoint, in the hermes model wizard and in the /model picker inside a session. To check a model's details yourself, ask the endpoint:

curl https://app.actualyze.ai/openai/v1/models \
  -H "Authorization: Bearer <your-actualyze-api-key>"

Each entry carries context_window, max_output_tokens and a capabilities object that includes tool_use. The Model Catalog in the Actualyze app shows the same details.

• Hermes reads context_window from the listing and uses it to decide when to compress the conversation. Set a window yourself only when the listing shows context_window: null for your model, or to compress earlier than the model's limit: add context_length under providers.actualyze.models.<model-id> in config.yaml, or set model.context_length, which applies to the model you're running and is dropped when you switch models. Without a window from Actualyze, Hermes uses a built-in value matched on the model name, or 256,000 tokens when nothing matches, and either may be wrong for your model.
• 64,000 tokens is the floor. Hermes rejects a smaller window at startup and when you switch to the model. Pick a model with a larger one.
• Switch models in a session with /model, which opens a picker, or directly with /model custom:actualyze:<model-id>. The switch lasts for the session unless you add --global, and /model --refresh fetches the model list again. /model only switches between providers you've already set up; add a new one with hermes model outside a session.
• Side tasks use the same model. By default Hermes runs vision, compression and title generation on your main model, so those calls also go through Actualyze and draw down the same key's budget.

#Reasoning effort

When you haven't set an effort, Hermes adds reasoning_effort: medium to each Chat Completions request. Actualyze passes the field through to the model provider, so a reasoning model that honors it runs at medium effort rather than its own default. To change it, use /reasoning <level> in a session (add --global to save it) or set agent.reasoning_effort in config.yaml. If a model rejects the field with a 400 that names it, Hermes retries the request without it and leaves it off for the rest of the session.

#Troubleshooting

• Hermes refuses to start, citing the context window: the model's window, or the context_length you set, is under 64,000 tokens.
• A notice that the model rejects reasoning effort: the model doesn't accept the field. Hermes retries without it on its own and leaves it off for the rest of the session.
• The wizard can't verify the endpoint, or lists no models: check the base URL (it must end in /openai/v1) and the API key.
• 402: a spend limit stopped the request before any model ran, so nothing was charged. The message says which limit: usually the key's budget, or the key's own monthly limit.
• 401: the key was rejected. Check the key's variable in ~/.hermes/.env: ACTUALYZE_API_KEY for the named provider, HERMES_CUSTOM_APP_ACTUALYZE_AI_API_KEY after the wizard. The key may also be mistyped, revoked or expired, lack the inference scope, or belong to someone who is no longer on the key's team.
• 403: the request was refused. If the message says read-write permission is required, the key is read-only; create a read-write key. Otherwise your team can't use the model you asked for; check its access in the Model Catalog or pick another.
• 402 saying Budget required: the key's budget was deleted, archived or retired, or you no longer have access to it. Create a new key bound to a budget you can use.
• Model not found: the model name doesn't match a catalog model or Virtual Model your workspace serves.
• Actualyze is missing from /model: the provider isn't set up yet. Quit the session and run hermes model.

#Reference

Requests you cancel mid-stream still draw down the usage they consumed.

For Hermes Agent's own settings, see Nous Research's AI providers documentation, in particular the sections on custom endpoints, named custom providers and context length detection.