---
title: "How to Add a Custom Provider to Hermes Agent (2026)"
description: "Connect Hermes Agent to any OpenAI-compatible provider — MiniMax, DeepSeek, Gemini, Grok, OpenAI, or haimaker.ai. Base URLs, API keys, and timeout fixes."
date: 2026-05-11
updatedDate: 2026-06-26
location: San Francisco, CA – May 11th, 2026
image: /images/hermes-custom-provider-setup-hero.jpg
keywords: "hermes agent custom provider, hermes agent provider setup, hermes agent api key, hermes agent minimax provider setup, hermes agent gemini api, hermes agent deepseek setup, hermes agent grok api, hermes custom endpoint, hermes agent openai compatible api"
faq:
  - question: "How do I add a custom provider to Hermes Agent?"
    answer: "Run `hermes model` in your terminal, choose 'Custom endpoint', and enter three things: the provider's base URL (ending in /v1), your API key, and the model identifier. Hermes stores the selection and uses it for every run. Any provider that exposes an OpenAI-compatible /v1/chat/completions endpoint works — MiniMax, DeepSeek, Google, xAI, OpenAI, OpenRouter, a local Ollama instance, or haimaker.ai. For haimaker.ai specifically, 'npx -y @haimaker/connect --hermes' configures Hermes in one command."
  - question: "What base URL does Hermes Agent need?"
    answer: "Hermes needs the OpenAI-compatible root, not the full chat-completions path. Use https://api.haimaker.ai/v1 for haimaker, https://api.minimax.io/v1 for MiniMax, https://api.deepseek.com/v1 for DeepSeek, https://generativelanguage.googleapis.com/v1beta/openai for Gemini's OpenAI-compatible layer, https://api.x.ai/v1 for xAI Grok, https://api.openai.com/v1 for OpenAI, or http://localhost:11434/v1 for Ollama. Hermes appends /chat/completions itself."
  - question: "Why is my Hermes custom provider timing out?"
    answer: "Long agentic steps on a slower provider can exceed Hermes' default read timeout. Set the HERMES_STREAM_READ_TIMEOUT environment variable (in seconds) to a higher value before launching Hermes, and check that your base URL ends in /v1 with no trailing slash. A 401 instead of a timeout means the API key didn't take — re-run `hermes model` and re-enter it."
---

Hermes Agent ships with a short list of built-in providers, but its real flexibility is the **Custom endpoint** option: any service that speaks the OpenAI chat-completions format plugs in with a base URL, a key, and a model name. That covers MiniMax, DeepSeek, Google Gemini, xAI Grok, OpenAI, OpenRouter, a private vLLM box, a local Ollama instance, and [haimaker.ai](https://haimaker.ai) for all of them at once.

Here's the general setup, then the exact values for the providers people ask about most.

## The general method

Every custom provider in Hermes goes through the same three-question flow:

```bash
hermes model
```

1. Pick **Custom endpoint** from the menu.
2. Enter the **base URL** — the OpenAI-compatible root, ending in `/v1` (Hermes appends `/chat/completions` itself).
3. Enter your **API key** for that provider.
4. Enter the **model identifier** the provider expects.

Hermes saves the selection and uses it for every subsequent run. To change providers later, run `hermes model` again. That's the whole mechanism — the rest of this post is just filling in the right values.

A model only works well in Hermes if it follows tool schemas and carries enough context for the agent's loops — aim for at least ~64K usable context. See [Best Models for Hermes Agent](/blog/best-models-for-hermes/) for which model to actually pick.

## haimaker.ai — one key for every model

Instead of juggling a separate account, key, and base URL per provider, point Hermes at haimaker.ai once and switch models by editing one string. The fastest way to set it up is a single command:

```bash
export HAIMAKER_API_KEY=your-haimaker-key
npx -y @haimaker/connect --hermes
```

[`@haimaker/connect`](/connect) writes Hermes' custom-endpoint config and verifies the key, then exits. Add `--model` to pin a model or `--pick-model` to choose one interactively, and run `npx @haimaker/connect --uninstall --hermes` to undo it. Get a key first at [app.haimaker.ai](https://app.haimaker.ai/sign-up); new accounts come with free credits.

Prefer the built-in `hermes model` flow? Enter these values when it asks:

- **Base URL:** `https://api.haimaker.ai/v1`
- **API key:** your haimaker.ai key
- **Model:** any supported model, e.g. `anthropic/claude-sonnet-4-6`, `openai/gpt-5-4-codex`, `google/gemini-3-1-pro`, `minimax/minimax-m2-5`, `deepseek/deepseek-v3-2`, `xai/grok-4-1-fast`, `zai/glm-4-7`, `moonshot/kimi-k2-5`

Models run about 5% below market rate, and you only manage one billing account.

## MiniMax in Hermes

MiniMax M2.5 is the popular budget choice for Hermes — cheap enough to leave running, capable enough to handle tool loops.

- **Base URL:** `https://api.minimax.io/v1`
- **API key:** from your MiniMax platform console
- **Model:** `MiniMax-M2.5` (use the exact ID shown in the MiniMax console — casing matters)

Or get MiniMax through haimaker.ai with model `minimax/minimax-m2-5` and skip the separate account.

## Google Gemini in Hermes

Gemini exposes an OpenAI-compatible layer, so it works as a Hermes custom endpoint.

- **Base URL:** `https://generativelanguage.googleapis.com/v1beta/openai`
- **API key:** your Google AI Studio key
- **Model:** `gemini-3-flash` for cheap, fast work; `gemini-3.1-pro` for long-context research

Yes, Hermes Agent supports Google Gemini this way — there's no separate Gemini integration to enable, it's just a custom endpoint. Or use `google/gemini-3-1-pro` through haimaker.ai.

## DeepSeek in Hermes

- **Base URL:** `https://api.deepseek.com/v1`
- **API key:** from the DeepSeek platform
- **Model:** `deepseek-chat` (points at the current V3.2 line) or `deepseek-reasoner`

Through haimaker.ai: `deepseek/deepseek-v3-2`.

## xAI Grok in Hermes

- **Base URL:** `https://api.x.ai/v1`
- **API key:** from the xAI console
- **Model:** `grok-4.1-fast` for cheap large-context work, `grok-code-fast` for code-specific tasks

Through haimaker.ai: `xai/grok-4-1-fast`.

## OpenAI / Codex models in Hermes

If you want OpenAI's own models (including the Codex line) behind Hermes:

- **Base URL:** `https://api.openai.com/v1`
- **API key:** an OpenAI **API** key (a ChatGPT Plus subscription does not include API access — you need a separate API key with billing enabled)
- **Model:** `gpt-5.4-codex` for coding, `gpt-5.4` for general work

Through haimaker.ai: `openai/gpt-5-4-codex`.

## Local models via Ollama

- **Base URL:** `http://localhost:11434/v1`
- **API key:** any non-empty string (Ollama ignores it, but Hermes wants a value)
- **Model:** `gemma4:latest`, `qwen3.5:latest`, or whatever you've pulled

```bash
ollama pull gemma4
hermes model   # Custom endpoint → base URL above → model gemma4:latest
```

## Common problems

- **Timeouts on long steps.** Slower providers can exceed Hermes' default stream read timeout during big agentic turns. Set `HERMES_STREAM_READ_TIMEOUT` (seconds) to a larger value before launching Hermes.
- **401 / auth errors.** The key didn't register, or you pasted a console/session token instead of an API key. Re-run `hermes model` and re-enter it.
- **404 on requests.** Your base URL probably includes `/chat/completions` already, or has a trailing slash. Hermes appends the path itself — end the URL at `/v1`.
- **Tool calls failing repeatedly.** That's usually the model, not the config. Small models drift on tool schemas; move up a tier.

## Get your haimaker.ai key

New accounts get free credits to test with. Browse every supported model with live pricing and benchmarks at [haimaker.ai](https://haimaker.ai), then run `npx -y @haimaker/connect --hermes` to point Hermes at it.

<a href="https://app.haimaker.ai/sign-up?utm_source=hermes_blog&utm_medium=cta&utm_campaign=hermes_custom_provider" class="cta-button">GET $10 FREE CREDITS ON HAIMAKER</a>

---

*Related: [Best Models for Hermes Agent](/blog/best-models-for-hermes/) · [Hermes Agent Pricing](/blog/hermes-api-costs-pricing/) · [Hermes Agent vs Codex CLI](/blog/hermes-vs-codex/)*