MegaBrain University · guide

How to Use Hermes Agent with Claude, GPT-6 and 100+ Models on One API Key

Updated November 11, 2026 · 10 min setup

What is Hermes Agent

Hermes Agent is an open-source AI agent by Nous Research. It runs on your machine or a server, uses tools (terminal, files, browser, web search), learns reusable skills from finished tasks, keeps memory between sessions, and talks to you through the terminal or through Telegram, Discord, Slack, WhatsApp, Signal and email.

Hermes does not come with a model. It needs an inference provider, and any OpenAI-compatible endpoint works. MegaBrain is one: a single key and balance for Claude, GPT, Gemini, Grok and open models, so you can give Hermes a frontier model for hard work and a cheap one for routine jobs without juggling vendor accounts.

Setup, step by step

1. Step 1. Get a MegaBrain API key

   Sign up with GitHub, Google or email, add funds on the Balance page and create a key on the API key page. The key works for every text, image and video model, and each request is paid from your balance — no subscription.

   Put the key in an environment variable so it never lands in a config file you share:

   # ~/.zshrc or ~/.bashrc
   export MEGABRAIN_API_KEY="your-megabrain-key"

   Copy

   curl https://getmegabrain.com/api/gateway/v1/chat/completions \
     -H "Authorization: Bearer $MEGABRAIN_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"model": "anthropic/claude-sonnet-5.5", "messages": [{"role": "user", "content": "Say OK"}]}'

   Copy

   Check the key before you touch the agent. A JSON reply with choices means the key, the balance and the model all work:

2. Step 2. Install Hermes Agent

   On macOS, Linux or WSL2:

   curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
   source ~/.zshrc   # or ~/.bashrc

   Copy

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

3. Step 3. Point Hermes at MegaBrain

   Run hermes model and pick Custom endpoint (self-hosted / VLLM / etc.). Enter the base URL, paste your key and type the model ID:

   Base URL:  https://getmegabrain.com/api/gateway/v1
   API key:   your-megabrain-key
   Model:     anthropic/claude-sonnet-5.5

   Copy

   The wizard writes ~/.hermes/config.yaml. You can also edit it by hand:

   model:
     provider: custom
     base_url: https://getmegabrain.com/api/gateway/v1
     api_key: your-megabrain-key
     default: anthropic/claude-sonnet-5.5

   Copy

   OPENAI_BASE_URL does not configure a custom endpoint in Hermes — config.yaml is the source of truth. Keep the file private: it holds your key.

4. Step 4. Start a session and check it

   Run hermes and give it a task that needs a tool, for example “List the files in this folder and summarize what each one does”. If Hermes runs a command and answers, tool calling works. Switch models inside a session with /model custom:openai/gpt-6.1-sol.

5. Step 5. Connect a messaging app and run it 24/7

   Run hermes gateway setup to connect Telegram, Discord, Slack, WhatsApp, Signal or email, then hermes gateway start. To keep it running after you close the terminal (cron jobs need this), install it as a service with hermes gateway install.

Which model to choose

Hermes needs a model that supports tool calling and a context window of at least 64K tokens. Every model below qualifies. Start with Claude Sonnet 5.5; move routine cron jobs to Gemini Flash or DeepSeek Flash once they work.

Every model with its price and context window is in the catalog. They all work with the same key.

What you can do

Business use cases

Every weekday at 8:00, read sales.csv in ~/reports, compare yesterday with the same weekday last week, and send me in Telegram: revenue, orders, top 3 products, and anything that changed by more than 20%. Keep it under 10 lines.

Using the MegaBrain media API (docs: https://getmegabrain.com/docs/media, key in $MEGABRAIN_API_KEY), generate a 1:1 product shot of our blue ceramic mug on a light oak table with Nano Banana Pro, save it to ~/marketing, and save the steps as a skill called product-shot.

Troubleshooting

FAQ