Hermes

Connect Hermes Agent to AI/ML API through the native provider fork or a manual OpenAI-compatible setup.

About

Hermes Agent is an agent framework for CLI and messaging workflows. It supports OpenAI-compatible providers and can use AI/ML API either through the native provider fork or through manual OpenAI-compatible configuration.

This guide covers both setup paths.

Quick start

Use the AI/ML API fork if you want the fastest path:

1. Clone the fork.

2. Export AIMLAPI_API_KEY.

3. Run hermes model.

4. Choose AI/ML API.

5. Start chatting with hermes chat.

Use the upstream repository if you want to stay on the official codebase and do not mind manual configuration.

When to use AI/ML API with Hermes

AI/ML API works well with Hermes when you want:

• one key for many model providers

• an OpenAI-compatible endpoint

• fast switching between coding, reasoning, and multimodal models

Prerequisites

Before you start, make sure you have:

• a working Hermes installation

• an AI/ML API key from aimlapi.com/app/keys

• a model ID from aimlapi.com/models

Use this base URL:

https://api.aimlapi.com/v1

Need a key first? Use API Key Management.

Choose a setup path

Option 1: AI/ML API fork

Use the AI/ML API fork if you want the smoothest setup.

Repository:

• aimlapi/hermes-agent-aimlapi

Benefits:

• AI/ML API appears in hermes model

• the endpoint is preconfigured

• model discovery is tuned for chat models

Option 2: Official Hermes repository

Use the official Hermes repository if you want to stay on upstream Hermes.

Repository:

• NousResearch/hermes-agent

This path uses Hermes' generic OpenAI-compatible provider flow.

Option 1: Set up the AI/ML API fork

Clone the fork and start provider setup:

git clone https://github.com/aimlapi/hermes-agent-aimlapi.git
cd hermes-agent-aimlapi
git checkout feature/add-aimlapi-provider
export AIMLAPI_API_KEY=your_key_here
hermes model

Then:

1. Choose AI/ML API.

2. Pick a model.

3. Start Hermes with hermes or hermes chat.

Hermes already knows the default endpoint. You do not need to enter it manually.

Saved configuration

Hermes stores provider settings in ~/.hermes/config.yaml and reads secrets from ~/.hermes/.env.

Example config.yaml:

model:
  provider: aimlapi
  base_url: https://api.aimlapi.com/v1
  default: openai/gpt-5-chat-latest

Example .env:

AIMLAPI_API_KEY=your_key_here
AIMLAPI_BASE_URL=https://api.aimlapi.com/v1

AIMLAPI_BASE_URL is optional.

One-off run

Use this when you want to test AI/ML API without changing your default provider:

hermes chat --provider aimlapi --model openai/gpt-5-chat-latest

Verify the fork setup

Run a quick health check:

hermes doctor

Then open a chat directly:

hermes chat --provider aimlapi --model openai/gpt-5-chat-latest

Option 2: Set up official Hermes

Clone the upstream repository:

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

Add your credentials to ~/.hermes/.env:

OPENAI_API_KEY=your_key_here
OPENAI_BASE_URL=https://api.aimlapi.com/v1

Then set a model in ~/.hermes/config.yaml:

model:
  provider: custom
  base_url: https://api.aimlapi.com/v1
  default: openai/gpt-5-chat-latest

Start Hermes:

hermes

Verify the upstream setup

Check that Hermes sees your configuration:

hermes doctor

Then start a chat and confirm the selected model answers normally.

What changes in the upstream flow

Compared with the fork:

• AI/ML API does not appear as a native provider

• Hermes treats the endpoint as a custom backend

• you may need to enter model IDs manually

Model selection

Use exact AI/ML API model IDs in Hermes.

Common examples:

• openai/gpt-5-chat-latest

• anthropic/claude-sonnet-4.6

• google/gemini-2.5-flash

The Hermes picker focuses on chat-completion models. Non-chat models are excluded from the interactive list.

Good starting models

Start with one of these:

• openai/gpt-5-chat-latest for strong general use

• anthropic/claude-sonnet-4.6 for coding and long-form work

• google/gemini-2.5-flash for lower latency and lower cost

For the full catalog, use All Model IDs.

Switch models later

To change the saved model, run:

hermes model

To switch inside a session in the fork, use /model:

/model aimlapi:openai/gpt-5-chat-latest
/model aimlapi:anthropic/claude-sonnet-4.6
/model aimlapi:google/gemini-2.5-flash

CLI and gateway usage

Once configured, the normal Hermes commands work as usual:

hermes
hermes chat

If you use the Hermes gateway, it reuses the same default provider:

hermes gateway setup
hermes gateway start

Config checklist

Make sure these values line up:

• base URL: https://api.aimlapi.com/v1

• provider: aimlapi in the fork, custom in upstream

• model ID: exact AI/ML API model ID

• API key variable: AIMLAPI_API_KEY in the fork or OPENAI_API_KEY in upstream

Diagnostics

Check your setup with:

hermes doctor

This helps confirm:

• your API key is present

• Hermes can reach the models endpoint

• the saved provider config is valid

Troubleshooting

Hermes does not ask for the endpoint

This is expected in the AI/ML API fork. The default endpoint is built in:

https://api.aimlapi.com/v1

My model is missing from the picker

Usually one of these is true:

• the model is not exposed as a chat-completion model

• the live model list failed to load

• the model is not in the starter list yet

Set the model manually in config.yaml if needed.

Hermes selects another provider

Force AI/ML API with one of these:

• run hermes model and choose AI/ML API

• set model.provider: aimlapi

• use hermes chat --provider aimlapi --model ...

I want to use a proxy

Set a custom base URL:

AIMLAPI_BASE_URL=https://your-proxy.example/v1

I get an auth error

Usually one of these is wrong:

• the key is missing from ~/.hermes/.env

• the variable name does not match your setup path

• the saved provider points to another backend

Run hermes doctor first. Then reopen ~/.hermes/.env and verify the key name.

Links

• All Model IDs

• AI/ML API keys

• AI/ML API model catalog

• AI/ML API models endpoint

• Hermes repository