Hermes Agent

Connect Hermes Agent to Eden AI and run the self-hosted, persistent agent on 500+ models with automatic fallbacks and a single 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 evolving skills, and reaches you across the CLI and 20+ messaging platforms. Because Hermes talks to any OpenAI-compatible endpoint, you can point it at Eden AI and get:

500+ models: Access OpenAI, Anthropic, Google, and more through a single API key
One key, many providers: Switch models by changing a single config value — no per-provider keys
Automatic fallbacks: Configure a backup model that Hermes tries when the primary one fails

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 Choosing a model.

Prerequisites

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

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Eden AI API key from app.edenai.run → API Keys

Setup

1. Point Hermes at Eden AI

Configure the custom provider with the Eden AI base URL and a function-calling model. Use the built-in config set commands — no manual file editing required:

hermes config set model.provider custom
hermes config set model.base_url https://api.edenai.run/v3
hermes config set model.default anthropic/claude-sonnet-latest

This writes to Hermes’ config file (hermes config path prints its location — ~/.hermes/config.yaml on macOS/Linux, %LOCALAPPDATA%\hermes\config.yaml on Windows). The result looks like:

model:
  provider: custom
  base_url: https://api.edenai.run/v3
  default: anthropic/claude-sonnet-latest

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):

EDENAI_API_KEY=YOUR_EDEN_AI_API_KEY

base_url must be https://api.edenai.run/v3 (no 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.
Billing is handled on the Eden AI side through your API key. Check per-request cost in the Eden AI dashboard.

3. Start Hermes

hermes chat

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

hermes chat -Q -q "Reply with exactly one word: pong"

Every LLM call now flows through Eden AI, with unified billing and per-request cost visibility.

Choosing a model

Hermes requires function calling, so pick a model that supports it. Any provider/model string from the Eden AI catalog works — set it with hermes config set model.default <model> or per-session with hermes chat -m <model>.

Model	Best for
`anthropic/claude-sonnet-latest`	Recommended default — balanced reasoning, reliable tool calling
`anthropic/claude-opus-4-8`	Maximum capability
`anthropic/claude-haiku-4-5`	Fast and cheap
`openai/gpt-5`	OpenAI’s frontier model
`google/gemini-2.5-pro`	Long context, multimodal

Browse the full catalog at app.edenai.run/models.

Set up a fallback

Hermes can fall back to a backup model when the primary one fails. Add a second Eden AI model to the fallback chain:

hermes fallback add

First-class provider plugin (optional)

The setup above uses Hermes’ generic custom provider, which is the fastest way to get running. For a native --provider eden-ai experience — so Eden AI shows up in hermes model, hermes doctor, and the setup wizard — install Eden AI as a standalone model-provider plugin. Drop a directory under $HERMES_HOME/plugins/model-providers/eden-ai/, with no changes to the Hermes repo:

from providers import register_provider
from providers.base import ProviderProfile

eden_ai = ProviderProfile(
    name="eden-ai",
    aliases=("edenai",),
    display_name="Eden AI",
    description="Eden AI — 500+ models via one OpenAI-compatible API (EU/GDPR)",
    signup_url="https://app.edenai.run",
    env_vars=("EDENAI_API_KEY",),
    base_url="https://api.edenai.run/v3",
    auth_type="api_key",
    default_aux_model="mistral/mistral-small-2603",
    fallback_models=(
        "anthropic/claude-sonnet-5",
        "openai/gpt-5.5",
        "mistral/mistral-small-2603",
    ),
)

register_provider(eden_ai)

name: eden-ai
kind: model-provider
version: 1.0.0
description: Eden AI — 500+ models via one OpenAI-compatible API (EU/GDPR)
author: Eden AI

Hermes then auto-wires credential resolution, the --provider eden-ai flag, the hermes model picker (models fetched from {base_url}/models), and the hermes doctor health check. Select it with:

hermes chat --provider eden-ai

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):

mcp_servers:
  edenai:
    url: https://mcp.edenai.run/mcp
    headers:
      Authorization: Bearer ${EDENAI_API_KEY}

Hermes interpolates ${VAR} in server entries, 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, which means 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` / `Custom token not found`

Verify your Eden AI key — grab 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/trailing spaces.

`Request included tools parameter, but providers ... do not support function calling`

The selected model can’t do function calling, which Hermes requires. Switch to a function-calling model:

hermes config set model.default anthropic/claude-sonnet-latest

`model not found`

Ensure model.default uses the provider/model format (e.g. anthropic/claude-sonnet-latest). No bare model names.

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 terminal-based AI agent
OpenCode - Terminal-based AI coding assistant
Claude Code - Official Claude CLI

V3 Documentation

Quick Start

Overview

LLMs

Expert Models

General

Organization

Data Governance

Integrations

Overview

Prerequisites

Setup

1. Point Hermes at Eden AI

2. Add your API key

3. Start Hermes

Choosing a model

Set up a fallback

First-class provider plugin (optional)

Expert Models as Tools (MCP)

Troubleshooting

`401` / `Custom token not found`

`Request included tools parameter, but providers ... do not support function calling`

`model not found`

Connection issues

Next Steps

​Overview

​Prerequisites

​Setup

​1. Point Hermes at Eden AI

​2. Add your API key

​3. Start Hermes

​Choosing a model

​Set up a fallback

​First-class provider plugin (optional)

​Expert Models as Tools (MCP)

​Troubleshooting

​401 / Custom token not found

​Request included tools parameter, but providers ... do not support function calling

​model not found

​Connection issues

​Next Steps

Overview

Prerequisites

Setup

1. Point Hermes at Eden AI

2. Add your API key

3. Start Hermes

Choosing a model

Set up a fallback

First-class provider plugin (optional)

Expert Models as Tools (MCP)

Troubleshooting

`401` / `Custom token not found`

`Request included tools parameter, but providers ... do not support function calling`

`model not found`

Connection issues

Next Steps