Connect Hermes Agent to an OpenAI-compatible API
Hermes has a built-in Custom Endpoint flow for OpenAI-compatible APIs. The clean setup is short: test the endpoint outside Hermes, run the provider wizard, inspect what Hermes saved, then start a fresh session. This guide follows the current Hermes documentation rather than older custom_providers snippets.
What does Hermes support?
Hermes documents support for any endpoint that implements /v1/chat/completions. For a new endpoint, the recommended route is hermes model and “Custom endpoint (self-hosted / VLLM / etc.).” The wizard asks for the API base URL, API key, model name and transport, then writes the result to ~/.hermes/config.yaml.
Test the API before changing Hermes
Use the same key and Base URL you plan to give Hermes. On 2026-08-02, the production route below returned structured HTTP 401 JSON without a key. That proves the route is reachable and enforces authentication; it is not a valid-key model test.
curl https://monkeytheme.com/v1/models \ -H "Authorization: Bearer ***"
| Result | Next check |
|---|---|
| Model list | Copy an exact model ID from the response |
| 401 JSON | Check the Bearer header and whether the key is active |
| HTML or 404 | Check that the Base URL ends in /v1 once, not zero or two times |
Use the current Custom Endpoint wizard
hermes model # Choose: Custom endpoint (self-hosted / VLLM / etc.) # Base URL: https://monkeytheme.com/v1 # API key: your own dashboard key # Model: an exact ID returned by /v1/models # Transport: chat_completions
Run this command from the terminal, outside an active chat. Hermes distinguishes it from /model: the terminal wizard can add credentials and endpoints, while the in-chat command only switches among providers already configured.
If you manage named providers in YAML
The current format uses the top-level providers: dictionary. Keep the secret in an environment variable and reference its name with key_env.
# ~/.hermes/config.yaml
providers:
monkeyai:
api: https://monkeytheme.com/v1
key_env: MONKEYAI_API_KEY
transport: chat_completions
default_model: YOUR_EXACT_MODEL_ID# ~/.hermes/.env MONKEYAI_API_KEY=***
Older tutorials may show a top-level custom_providers: list. Hermes still reads it, but the official docs call it legacy and say updates migrate it to providers:. Do not rewrite a working configuration just to match an old snippet.
Verify what Hermes will actually use
hermes config check hermes config get model --json hermes status
After setup, open a fresh Hermes session and run one small request with the selected model. An already open chat keeps the model it started with unless you switch it in-session. If direct /v1/models succeeds but Hermes fails, compare the saved Base URL, provider, transport and exact model ID before changing anything else.
Official sources
FAQ
Can Hermes Agent use an OpenAI-compatible API?
Yes. Hermes documents a Custom Endpoint flow for servers that implement /v1/chat/completions.
What Base URL should I enter for MonkeyAI?
Use https://monkeytheme.com/v1 for the OpenAI-compatible endpoint.
Should I use hermes model or /model?
Use hermes model in the terminal to add an endpoint and credential. Use /model inside a chat only to switch among providers already configured.
Should I still copy an old custom_providers example?
No. The current format is the top-level providers dictionary. Hermes still reads the legacy list and can migrate it.
Does a reachable /v1/models route prove the full setup works?
No. A 401 only proves routing and authentication enforcement. A valid model list and one fresh-session request are still required.