Hermes Agent
Hermes Agent with Gemini: API key, models and fixes
Updated 20 November 2026
Hermes Agent has a native Google Gemini provider that talks to the Google AI Studio (Gemini) API with an API key. This page covers the setup, the models the documentation names, how the free tier and billing are described, whether a Google AI Pro or Ultra subscription can be used, a short note on Vertex AI, and the errors the documentation lists.
Facts come from the official Google Gemini guide, the Google Vertex AI guide and the AI Providers page, all in the Hermes Agent 0.23.3 documentation, read on 20 November 2026. Model names and availability change, so treat the lists below as a snapshot of that date.
Gemini access options
The documentation describes API-key access through Google AI Studio and OAuth2 access through Vertex AI. It documents no consumer-subscription sign-in path.
| Route | What you need | Who bills you |
|---|---|---|
Native Gemini provider (gemini) | A Google AI Studio API key in GOOGLE_API_KEY or GEMINI_API_KEY | Your key’s quota: the free tier, or the Google Cloud project with billing that the key belongs to |
| Sign in with a Google AI Pro or Ultra subscription | The documentation describes no path for this | Not applicable |
Vertex AI (vertex) | A Google Cloud project with billing active and the Vertex AI API enabled, plus a service-account JSON file or Application Default Credentials with the roles/aiplatform.user role on the project | Your Google Cloud project |
The native provider does not use Google’s OpenAI-compatible endpoint. The guide says Hermes keeps its own OpenAI-shaped message and tool loop and translates each request into Gemini’s native APIs, which it says preserves tool calling, streaming, multimodal inputs and Gemini-specific response metadata. No extra Python package is required for it.
Set up the API key
Create a key at aistudio.google.com/apikey. The guide says Hermes checks both GOOGLE_API_KEY and GEMINI_API_KEY for the gemini provider. Add one to ~/.hermes/.env, then run the model picker in your terminal:
echo "GOOGLE_API_KEY=..." >> ~/.hermes/.env
hermes model
hermes chatIn hermes model, choose “More providers...” and then “Google AI Studio”. The guide says Hermes checks your key tier, shows the Gemini models and lets you pick one. Hermes also needs to be installed first; if it is not, see how to install Hermes Agent.
If you would rather edit the file, the guide gives this shape for ~/.hermes/config.yaml:
model:
default: gemini-3.7-flash
provider: gemini
base_url: https://generativelanguage.googleapis.com/v1betaUse Gemini’s own model IDs here. The guide says to use gemini-3.7-flash, not an OpenRouter-style ID such as google/gemini-3.7-flash, when the provider is gemini. To switch model inside a running chat, use /model gemini-3.7-flash or another ID. The guide notes that /model only switches among providers you have already configured and does not collect new keys, so run hermes model first.
Which Gemini models the guide names
The hermes model picker shows the Gemini models in Hermes’s provider registry. The guide’s table of common choices, with its own notes shortened:
| Model | ID | The guide’s note |
|---|---|---|
| Gemini 4 Hydrogen | gemini-4-hydrogen | Fast model for everyday coding and agentic work; free and paid tiers |
| Gemini 4 Carbon | gemini-4-carbon | Strongest reasoning model; paid tier only |
| Gemini 4 Argon | gemini-4-argon | Flagship reasoning model |
| Gemini 3.8 Flash | gemini-3.8-flash | Most capable Flash model for long-horizon agentic and coding work |
| Gemini 3.7 Flash | gemini-3.7-flash | Recommended default balance of speed, capability and multimodal understanding |
| Gemini 3.1 Pro Preview | gemini-3.1-pro-preview | Most capable reasoning, math and coding model |
| Gemini 3.5 Flash Lite | gemini-3.5-flash-lite | Fastest and lowest-cost option for lightweight tasks |
| Gemini 2.5 Flash | gemini-2.5-flash | Previous generation fast model with thinking |
| Gemini 2.5 Pro | gemini-2.5-pro | Previous generation complex reasoning model |
The guide says model availability changes over time. If a model disappears or is not enabled for your key, run hermes model again and pick from the current list.
Two other things the guide mentions:
- Moving aliases.
gemini-pro-latestandgemini-flash-latestlet Google advance the model without a config change. The guide warns that your usage charges may be affected if newer models carry different rates, and suggests explicit IDs such asgemini-3.7-flashif you need strict reproducibility. - Gemma models. Google also serves Gemma models through the Gemini API, for example
gemma-4-31b-it. Hermes hides very low-throughput Gemma entries from the picker, and the guide treats them as evaluation options: it says Google’s Gemma API pricing is free-tier-only with low caps, so sustained agent use should normally move to a paid Gemini model, a self-hosted deployment or another provider. To use a hidden one, set its ID undermodel.defaultinconfig.yaml.
Free tier or billing
The guide recommends a billing-enabled Google Cloud project for agent use. Its reason: Gemini’s free tier is too small for long-running agent sessions, because Hermes may make several model calls per user turn. In its troubleshooting section it adds that tool use, retries, compression and auxiliary tasks can each need extra calls, so free-tier quotas can be used up after a handful of agent turns.
Hermes probes the key during setup. If it finds the free tier, you see the message “This Google API key is on the free tier”. The documented fix is to enable billing on the Google Cloud project attached to the key, regenerate the key if needed, and run hermes model again. The guide gives no prices or quota numbers; read the current limits on Google’s own pages. For the wider cost picture, see is Hermes Agent free.
One more detail from the guide: Gemini 4 Carbon is marked paid tier only, and Gemini 4 Hydrogen is marked as available on free and paid tiers.
Can you use a Google AI Pro or Ultra subscription?
According to the AI Providers page, no documented path exists. It lists “Google, Gemini consumer plan (Google AI Pro / Ultra)” as not usable: the gemini provider is API-key only, and Vertex AI bills to your Google Cloud project. It says there is currently no way to sign in to Hermes with a consumer Gemini subscription.
We also looked for a separate Gemini CLI sign-in provider in the documentation we were given for this page, and did not find one, so we do not describe one here, and we have no risk warning to relay about it. Check the Hermes documentation for updates to supported sign-in methods. For comparison, the same page does document subscription sign-in for some other providers; see Hermes Agent with Claude and Hermes Agent with ChatGPT.
What the page does say is that your API key’s quota is what gets used, and that how a consumer plan would be consumed is not currently documented. No consumer-subscription sign-in path is documented. The native Gemini provider requires an AI Studio API key; the separate Vertex AI provider uses Google Cloud credentials and project billing.
Vertex AI, briefly
The separate Vertex AI provider (vertex) serves Gemini models from Google Cloud. The Vertex guide says it has no static API key for the standard endpoint: every request needs a short-lived OAuth2 access token, which Hermes mints and refreshes for you from a service-account JSON file or Application Default Credentials. It describes Vertex as the choice when you want Gemini usage to draw on your Google Cloud account rather than an AI Studio key.
Choose one credential method. For a service-account JSON file, run:
echo "VERTEX_CREDENTIALS_PATH=/path/to/service-account.json" >> ~/.hermes/.envAlternatively, for Application Default Credentials, leave VERTEX_CREDENTIALS_PATH and GOOGLE_APPLICATION_CREDENTIALS unset and run:
gcloud auth application-default loginYou then run hermes model and choose “Google Vertex AI”. The service account needs the roles/aiplatform.user role, and the guide says Vertex model IDs need a google/ prefix, such as google/gemini-3.7-flash. For the Gemini 3.x preview models it says to leave the region at global.
The AI Studio guide also mentions Vertex AI express-mode keys, which need GEMINI_BASE_URL=https://aiplatform.googleapis.com. Its warning is that the base URL, not the key’s prefix, decides which surface Hermes uses. A 403 PERMISSION_DENIED usually means the key and host are paired incorrectly.
Gemini settings and the errors the guide lists
Use hermes doctor to check setup. The guide says it reports whether GOOGLE_API_KEY or GEMINI_API_KEY is available and whether the configured provider credentials can be resolved. A few Gemini-specific settings are worth knowing:
- Base URL. Use
https://generativelanguage.googleapis.com/v1beta. If a base URL ongenerativelanguage.googleapis.comhas no API version segment, Hermes appends/v1beta. A proxy on another host is treated as an OpenAI-compatible endpoint, not a native Gemini one. - Which Google API is used. On AI Studio, Hermes sends Gemini 3 and later models through Google’s Interactions API and older Gemini 2.x and Gemma models through
generateContent. You can override this underproviders:withgemini_api, which takesinteractions,generate_contentorauto(the default), for every model or one model at a time. - Reasoning effort. For Gemini 4 models the guide maps Hermes’s reasoning effort (
/reasoningoragent.reasoning_effort) onto Google’s thinking level, and describes a long-decode mode for the highest efforts that can produce much longer replies. - Messaging apps. The guide says Gemini works with all gateway platforms. Configure the provider, then run
hermes gateway setupandhermes gateway start. See Hermes Agent on Telegram for a typical chat setup.
The troubleshooting entries, with the documented fix for each:
- “Gemini native client requires an API key”. Hermes found no key. Add
GOOGLE_API_KEYorGEMINI_API_KEYto~/.hermes/.env, then runhermes modelagain. - “This Google API key is on the free tier”. Enable billing on the Google Cloud project behind the key, regenerate the key if needed, and run
hermes model. - “404 model not found”. The model is not available for your account, region or key. Run
hermes modeland pick another one from the current list. - A Gemma model is missing from the picker. Hermes may hide low-throughput Gemma models. Set the ID directly in
~/.hermes/config.yamlif you want to evaluate one. - “429 quota exceeded” on Gemma. The Gemma free-tier caps are low. Use Gemma for compatibility testing, then switch to a paid Gemini model or another provider.
- The OpenAI-compatible endpoint is configured. If
~/.hermes/.envhasGEMINI_BASE_URLset to the URL ending in/v1beta/openai/, change it tohttps://generativelanguage.googleapis.com/v1betaor remove it. - Tool calling fails with schema errors. Upgrade Hermes and run
hermes modelagain; the guide says the native adapter cleans tool schemas for Gemini’s stricter format and older builds may not.
Gemini on ReadyHermes
ReadyHermes runs your own Hermes Agent on our servers, always on, connected to the chat apps you choose. In the workspace, the Model key tab lists Google Gemini as a provider. Choose it, paste an API key from Google AI Studio, press Load models, pick a model and press Check and switch. We send one tiny test message first, then the agent restarts on your key, which takes about a minute. Use included AI switches back.
Google bills the key directly, and ReadyHermes adds no AI limit on your own key. Only an API key works there. There is no screen for a Google AI Pro or Ultra subscription, a Gemini CLI sign-in or Vertex AI, and we have not tested those on ReadyHermes. The AI included with a plan is not Gemini.
Plans start from US$3.99 a month (Lite) or US$6.99 (Pro), with US$1 of AI included every month and a one-hour free trial. See managed Hermes Agent hosting or self-hosting vs managed hosting to decide which fits.
Questions
How do I use Gemini with Hermes Agent?
Create an API key at aistudio.google.com/apikey and add GOOGLE_API_KEY (or GEMINI_API_KEY) to ~/.hermes/.env. Then run hermes model, choose More providers, then Google AI Studio, and pick a model. The resulting config.yaml uses provider gemini with the base URL https://generativelanguage.googleapis.com/v1beta.
Is Gemini free to use with Hermes Agent?
A free-tier key can be used, but the Hermes documentation says the free tier is too small for long-running agent sessions, because Hermes may make several model calls per user turn. It recommends a billing-enabled Google Cloud project. It gives no prices or quota numbers, so check Google's own pages.
Can I use my Google AI Pro or Ultra subscription with Hermes Agent?
The Hermes documentation lists no path for it. It says there is currently no way to sign in to Hermes with a consumer Gemini subscription: the gemini provider is API-key only, and Vertex AI bills to your Google Cloud project. We found no separate Gemini CLI sign-in provider in the documentation we read.
Which Gemini models does Hermes Agent support?
The guide's common choices include gemini-4-hydrogen, gemini-4-carbon, gemini-4-argon, gemini-3.8-flash, gemini-3.7-flash, gemini-3.1-pro-preview, gemini-3.5-flash-lite, gemini-2.5-flash and gemini-2.5-pro, plus the moving aliases gemini-pro-latest and gemini-flash-latest. Availability changes, so run hermes model for the current list.
Can I use my own Gemini API key on ReadyHermes?
Yes. The workspace's Model key tab lists Google Gemini: paste an AI Studio API key, press Load models, pick a model and press Check and switch. Google bills the key directly. Only an API key works there; a Google AI Pro or Ultra subscription, Gemini CLI sign-in and Vertex AI are not offered or tested.