Skip to content
Skip to Content
Batchwell Docs

Hermes Agent setup

Use Batchwell in Hermes Agent by adding a custom provider to ~/.hermes/config.yaml with base_url set to the Batchwell base URL.

To use Batchwell in Hermes Agent, set the model block of ~/.hermes/config.yaml to provider: custom, with base_url set to https://api.batchwell.ai/v1, a Batchwell model id as default, and key_env naming the environment variable that holds your Batchwell API key. This is Hermes Agent's documented setup for a custom OpenAI-compatible endpoint.

Not tested end to end

This setup is not tested end to end. It follows Hermes Agent's documented custom endpoint configuration, and Batchwell has not run Hermes Agent against the API to confirm every feature works.

Create a key as described in the Quickstart and Authentication, then run:

Shell
curl -fsSL https://batchwell.ai/connect.sh | sh -s -- hermes --model batchwell/kimi-k3.1-pro-uncensored

It writes ~/.hermes/config.yaml and ~/.hermes/.env: the model settings through hermes config set, and the key line in ~/.hermes/.env (readable only by you). It reads your key from BATCHWELL_API_KEY, or asks for it on the terminal with the input hidden, and checks it with GET /v1/models before it writes anything. Then start the agent with hermes. Every file it changes is first copied to <file>.batchwell-backup-<time>; to undo it, copy that backup back over the file, or delete a file the command created. The command runs on macOS, Linux and WSL; see Connect an agent for every option.

Paste this prompt into the agent, or into any coding agent, and it sets itself up the same way. It names the variable that holds the key, never the key itself, and tells the agent to back up each file before it changes it.

Prompt
Set up Hermes Agent to use Batchwell. Change ~/.hermes/config.yaml and ~/.hermes/.env.

Base URL: https://api.batchwell.ai/v1
Model id: batchwell/kimi-k3.1-pro-uncensored
API format: OpenAI Chat Completions
API key: in the environment variable BATCHWELL_API_KEY

Rules:
- Read the key from BATCHWELL_API_KEY. If it is unset, stop and ask me to export it. Never ask me to paste a key into this chat, never print it, and never write it into a file inside a git repository.
- Back up every file before you change it, as <file>.batchwell-backup-<UTC time>.
- Change only the Batchwell entries. Keep every other setting.

Steps:
- Run hermes config set for model.provider custom, model.base_url https://api.batchwell.ai/v1, model.default batchwell/kimi-k3.1-pro-uncensored and model.key_env BATCHWELL_API_KEY.
- Put the line BATCHWELL_API_KEY=<key> in ~/.hermes/.env (mode 0600; replace an existing BATCHWELL_API_KEY= line), written from $BATCHWELL_API_KEY, never as a command argument.
- Check: GET https://api.batchwell.ai/v1/models with the header Authorization: Bearer $BATCHWELL_API_KEY. A 200 that lists the model id means it works.
- Tell me to restart with: hermes. The first answer comes back.

curl -fsSL https://batchwell.ai/connect.sh | sh -s -- hermes --model batchwell/kimi-k3.1-pro-uncensored does the same in one step. Guide: https://batchwell.ai/docs/clients/hermes
config.yaml
model:
  default: batchwell/kimi-k3.1-pro-uncensored
  provider: custom
  base_url: https://api.batchwell.ai/v1
  key_env: BATCHWELL_API_KEY

The snippet is made for batchwell/kimi-k3.1-pro-uncensored, a model Batchwell serves today. Put your key in ~/.hermes/.env as BATCHWELL_API_KEY= followed by the key, so no key is written into config.yaml. Create a key as described in the Quickstart and Authentication.

You can also run hermes model and choose "Custom endpoint (self-hosted / VLLM / etc.)". It asks for the same three values: the API base URL, the API key and the model name.

  • default is the model Hermes Agent uses. Set it to the model id from GET /v1/models; see models.
  • provider: custom selects Hermes Agent's custom endpoint provider, for any OpenAI-compatible API.
  • base_url is the address Hermes Agent sends its requests to. Set it to the Batchwell base URL, which ends in /v1.
  • key_env names the environment variable that holds the key. Hermes Agent reads BATCHWELL_API_KEY from your shell or from ~/.hermes/.env. The key starts with bw_live_ or bw_test_.

Hermes Agent treats config.yaml as the single source of truth for the model and endpoint. It needs a model with a context window of at least 64,000 tokens for agent use with tools, and refuses to start with a smaller one. Check the context length of the model you choose on models.

That model lists these supported parameters: temperature, top_p, max_tokens, max_completion_tokens, stop, stream_options, tools, tool_choice, reasoning_effort. These are the model's tunable parameters, not the whole request: Batchwell accepts only the fields listed under accepted fields, including stream and stream_options. Any other field fails with 400 unsupported_parameter, and the error message names the field.

Batchwell rejects n greater than 1, logprobs and top_logprobs with 400 unsupported_parameter, and accepts text content only (parts of type image_url, input_audio or file get 400 unsupported_content). The full list is on chat completions.