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:
- Eden AI API key from app.edenai.run → API Keys
Setup
1. Point Hermes at Eden AI
Configure thecustom provider with the Eden AI base URL and a function-calling model, using the built-in config set commands:
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, soapi.edenai.run maps to EDENAI_API_KEY. Add it to Hermes’ secrets file (hermes config env-path prints its location):
base_urlmust behttps://api.edenai.run/v3, without a trailing/chat/completions: the OpenAI-compatible client appends that for you.- Keep the key in the
.envfile, not inconfig.yaml. Any environment variable namedEDENAI_API_KEYworks too. - Eden AI bills the calls to the key you used. See monitoring to track consumption and cost.
3. Start Hermes
Model naming
Eden AI model ids areprovider/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 defaultanthropic/claude-haiku-latest: fast and cheapopenai/gpt-latest: OpenAI’s current flagship
*-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 withhermes 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 itsfallback_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:
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:
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 undermcp_servers in Hermes’ config file (hermes config path prints the location):
${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
Confirmbase_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>