Connect Hermes Agent

If Hermes Agent is already installed, you can connect it directly with your service API key. OpenCodex is optional for this route.

Run these commands on the computer and in the Hermes profile that runs your agent. Have your key, available balance and an exact model ID ready. Copy our Base URL from the connection card above.

1. Open the model setup

In your terminal, run:

hermes model

Choose Custom endpoint (enter URL manually). The display wording can vary slightly by version; choose the custom OpenAI-compatible endpoint rather than a vendor subscription or login.

2. Enter the connection settings

The wizard asks for the following values:

Enter the key at the wizard’s hidden prompt. You do not need to put the secret in a command, paste it into a chat, or edit the whole configuration file.

Hermes checks /v1/models and offers the IDs it discovers. If several models appear, select a number or type an exact ID. Use the service’s model ID here, without OpenCodex’s local my-api/ prefix. For an agent, choose a model that supports tool calling; text generation alone is not enough.

The wizard saves your endpoint and model and adds the named connection to its provider list. In the reviewed implementation, the key is saved to the profile’s .env through an endpoint-specific variable; the model configuration references that variable. Keep that file private.

3. Start a fresh conversation

Once the wizard confirms the saved default model, open Hermes as you normally do, or run:

hermes

Start a new conversation and ask for a short reply. Check that Hermes shows the model and custom endpoint you selected, then check your service dashboard for the request.

If Hermes warns that it could not verify the endpoint, saving the settings does not prove the connection works. Check the URL and key before relying on it. Auto-detection of the context limit can also fall back to a default; do not increase that limit beyond the selected model’s verified capacity.

4. Change the model later

Run hermes model again, select your saved my-api connection and choose another model from the service. You can keep several saved connections, but only choose the one you intend to use for this conversation.

Inside a Hermes chat, /model offers model switching. Named custom endpoints also support a form such as:

/model custom:my-api:YOUR_MODEL_ID

Replace YOUR_MODEL_ID with an exact ID available to your service key. This is Hermes’ own selector syntax; it is not the model ID you send directly to our HTTP API.

A configured messaging gateway or an existing conversation may retain its current selection. Start a fresh session after changing defaults. If your running gateway still uses old settings, finish active work and restart the Hermes gateway:

hermes gateway restart

If the connection fails

• No models appear: check the Base URL ends in /v1, the key is valid and the key allows the model. Enter an exact ID manually only after confirming it with our API.
• The wrong endpoint is shown: rerun hermes model, select the saved connection and confirm the URL. Check that you are using the intended Hermes profile.
• An unsupported API or parameter error appears: choose Chat Completions for this setup and check the selected model’s capabilities.
• A chat works but tools fail: choose a model with tool-calling support. Separate web search, browser and other tool integrations may need their own setup.
• You need help with an API error: use our troubleshooting reference.

This guide follows the custom-endpoint wizard in the Hermes source. For current profile and model options, see the project’s provider documentation.