Skip to main content
Hermes Agent’s custom provider accepts any OpenAI-compatible endpoint, so connecting it to Eden AI takes three config values and one API key.

Overview

Hermes Agent is an open-source, self-hosted AI agent from Nous Research. It runs as a persistent background process with its own memory and skills, and reaches you from the CLI and through messaging platforms. Pointed at Eden AI, it can use the function-calling chat models in the Eden AI catalog with a single Eden AI key.
Hermes is an agent, so every request it sends includes a tools (function-calling) parameter. Point it at a model that supports function calling. See Model naming.

Prerequisites

  • Hermes Agent already installed. If not, run the one-line installer:

Setup

1. Point Hermes at Eden AI

Configure the custom provider with the Eden AI base URL and a function-calling model, using the built-in config set commands:
This writes to Hermes’ config file (hermes config path prints its location: ~/.hermes/config.yaml on macOS and Linux, %LOCALAPPDATA%\hermes\config.yaml on Windows, or $HERMES_HOME/config.yaml when you set HERMES_HOME). The result looks like:

2. Add your API key

Hermes derives the key’s environment-variable name from the base URL host, so api.edenai.run maps to EDENAI_API_KEY. Add it to Hermes’ secrets file (hermes config env-path prints its location):
  • base_url must be https://api.edenai.run/v3, without a trailing /chat/completions: the OpenAI-compatible client appends that for you.
  • Keep the key in the .env file, not in config.yaml. Any environment variable named EDENAI_API_KEY works too.
  • Eden AI bills the calls to the key you used. See monitoring to track consumption and cost.

3. Start Hermes

For a one-shot, non-interactive run (handy for scripts or a quick smoke test):

Model naming

Eden AI model ids are provider/model, and Eden AI rejects a bare name such as claude-sonnet-latest with a 400. Hermes needs function calling, so pick a chat model that supports it. These ids work today:
  • anthropic/claude-sonnet-latest: balanced reasoning and reliable tool calling, a good default
  • anthropic/claude-haiku-latest: fast and cheap
  • openai/gpt-latest: OpenAI’s current flagship
Each *-latest alias follows the provider’s current model, so the config does not go stale. The full list, with each model’s capabilities, is in List LLM Models.

Switching models

Set the default with hermes config set model.default <model>, or override it for one session:

Fallbacks

A backup model can come from either side, and the two are separate mechanisms. Hermes switches models. Hermes tries the entries of its fallback_providers list in order when the primary fails with a rate limit, an overload or a connection error. hermes fallback add opens the same picker as hermes model and needs a terminal. You can also edit config.yaml and point an entry at Eden AI as a custom endpoint:
Eden AI switches models. A routing policy is a saved model chain that Eden AI runs for you. Create one whose targets all support function calling, then make its name Hermes’ model:
Hermes sends the id unchanged to a custom provider (hermes@v0.22.5:hermes_cli/model_normalize.py:126-144 strips only a literal custom/ or custom: prefix), and Eden AI runs the policy’s chain for policy/<name>; a request that names an ordinary model runs that model.

Add Eden AI as a provider plugin (optional)

Hermes lets you register a provider by dropping a directory under $HERMES_HOME/plugins/model-providers/. Eden AI is not bundled with Hermes and no Eden AI plugin is published, so the two files below are ones you write yourself. They follow the layout in Hermes’ own model provider plugin guide. Create $HERMES_HOME/plugins/model-providers/eden-ai/ with these two files:
Hermes’ guide says the profile’s name is then accepted by --provider, so you can select it with:

Expert Models as Tools (MCP)

Eden AI also hosts an MCP server that exposes the expert model catalog (OCR, web search, speech, translation and more) as tools. Add it under mcp_servers in Hermes’ config file (hermes config path prints the location):
Hermes expands ${VAR} in server entries, and loads the .env file that hermes config env-path prints into its environment at startup, so this reuses the EDENAI_API_KEY you already added in step 2. The server’s tools register into Hermes’ normal tool registry at startup, so they chain with built-in tools in a single workflow. Run /reload-mcp in an active chat to pick up config changes without a restart. See the MCP server page for the full tool catalog and the conventions its tools share.

Troubleshooting

401 / Invalid API key or Invalid token

Eden AI does not recognize the key: it answers Invalid API key for a wrong or revoked sk-eden-... key and Invalid token for a token of any other shape. Create a fresh one at app.edenai.run → API Keys. Confirm EDENAI_API_KEY is set in Hermes’ .env (hermes config env-path) and has no leading or trailing spaces.

Model(s) not found or inactive

Eden AI returns this 400 when the model id is not in the catalog. Use an id the catalog lists: provider/model, for example anthropic/claude-sonnet-latest, or a routable name.

Connection issues

Confirm base_url is exactly https://api.edenai.run/v3 and check Eden AI status at app-edenai.instatus.com.

Next Steps

  • OpenClaw - Self-hosted personal AI assistant
  • nanobot - Self-hosted personal AI agent framework
  • Routing policies - Save a model chain and call it as policy/<name>