ModelStream LogoModelStream Logo
Models
Video API
Image API
Chat API
Audio API
Studio
Pricing
Docs
Menu
IntroductionQuickstartAPI KeysUse with Hermes AgentUse with OpenClaw
Model ListBilling Guide
ModelStream
Getting Started
Use with Hermes Agent

Use ModelStream with Hermes Agent

Point Hermes Agent (Nous Research) at ModelStream and get 300+ models behind one OpenAI-compatible endpoint — with smart routing, built-in failover, and one-string model switching.

~10 minutes
Hermes Agent · Nous Research
No card required

You'll need a ModelStream account (modelstream.ai — no card required). This guide uses the public base URL https://api.modelstream.ai/v1 and model slugs gpt-4o-mini, claude-sonnet, modelstream-auto.

How it works

Hermes Agent works with any OpenAI-compatible endpoint — if a server implements /v1/chat/completions, Hermes can use it. ModelStream is exactly that: one endpoint in front of every major model. You configure it once as a custom provider (or a named custom provider) and switch models with /model mid-session.

Windows

What you need before starting

  • A Windows computer.
  • An internet connection.
  • A ModelStream account with an API key (we'll get that in Step 2).

Step 1 — Open PowerShell

  1. 1Press the Windows key on your keyboard.
  2. 2Type PowerShell.
  3. 3Click on Windows PowerShell to open it.
A blue or black text window will appear. This is your terminal — you'll type commands here.

Step 2 — Get your API key and endpoint from ModelStream

Before installing, grab your credentials:

  1. 1Open your web browser and go to modelstream.ai.
  2. 2Log in to your account (or create one if you don't have one yet).
  3. 3Go to the API Keys section of your dashboard.
  4. 4You will see two things you need — your ENDPOINT (looks like https://api.modelstream.ai/v1) and your API KEY (a long string of letters and numbers).
  5. 5Copy both of these somewhere handy (like Notepad) — you'll need them in a minute.

Step 3 — Install Hermes

Go back to your PowerShell window. Copy and paste this entire line, then press Enter:

powershell
iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)

Hermes will download and install automatically. You'll see text scrolling by — that's normal. Wait a few minutes until it finishes.

When the installation is done, the Hermes Agent Setup Wizard will appear on your screen automatically. Move on to Step 4.

Step 4 — Configure Hermes (Setup Wizard)

The wizard will ask you a series of questions. Here's exactly what to choose at each step:

  1. 1
    Setup typeSelect Full Setup (option 2). Press Enter.
  2. 2
    Provider / endpointSelect Custom Endpoint (option 30 on a fresh install). Press Enter.
  3. 3
    Endpoint URLThe wizard will ask you to paste your endpoint URL. Paste the endpoint you copied from the ModelStream API Keys page. Press Enter.
  4. 4
    API keyThe wizard will ask you to paste your API key. Paste the API key you copied from the ModelStream API Keys page. Press Enter.
  5. 5
    API compatibility modeSelect auto-detect. Press Enter.
  6. 6
    Base modelSelect the model you want to use (for example qwen3.6, or whatever model you prefer from the list). Press Enter.
  7. 7
    Remaining optionsThe wizard will ask about browser settings, model types, and other preferences. If you're not sure what to pick, the default option is usually fine — just press Enter to accept each one.
When the wizard finishes, Hermes is installed and configured!

Step 5 — Verify everything works

Type this command and press Enter:

powershell
hermes doctor

This checks that everything is installed and configured correctly. If there's a problem, it will tell you what to fix.

Step 6 — Start using Hermes

Type:

powershell
hermes

You'll see a welcome message and a prompt where you can type. Write your message and press Enter. Hermes will respond and can use tools (run commands, search the web, read files, etc.) to help you.

  • To ask a quick question without entering chat mode: hermes chat -q "What is the capital of France?"
  • To exit, type: /quit

How to open Hermes any time (after installation)

Hermes is now installed on your computer, but it doesn't have a desktop icon or a Start menu shortcut like normal apps. To use it, you need to open it manually each time. Here's how:

  1. 1Press the Windows key on your keyboard.
  2. 2Type PowerShell.
  3. 3Click on Windows PowerShell to open it.
  4. 4In the window that appears, type: hermes
  5. 5Press Enter.

That's it! Hermes will start and you can begin chatting. Every time you want to use Hermes — whether it's tomorrow, next week, or next month — just repeat these same steps.

To close Hermes when you're done, type /quit and press Enter. You can then close the PowerShell window normally (click the X button).

TIP: You can also right-click on PowerShell in the Start menu and select "Pin to taskbar" so it's always one click away at the bottom of your screen.

Linux and macOS

Step 1 — Install Hermes Agent

Skip this if Hermes is already installed.

bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

The installer handles Node.js 18+ and Python 3.10+. Then run the setup wizard once:

bash
hermes setup

Step 2 — Get your ModelStream API key

  1. 1Sign up at modelstream.ai.
  2. 2Dashboard → API Keys → Create Key, name it (e.g. hermes), copy it.
  3. 3Export it (or add to ~/.hermes/.env):
bash
export MODELSTREAM_API_KEY="ms-..."

Step 3 — Add ModelStream as a provider

Option A — Interactive wizard (recommended)

bash
hermes model

# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# API base URL:   https://api.modelstream.ai/v1
# API key:        your ModelStream key
# Model name:     gpt-4o-mini
# API mode:       chat_completions
# Context length: leave blank for auto-detection

The wizard persists everything to ~/.hermes/config.yaml — the single source of truth for model and endpoint config (don't use legacy .env model vars).

Option B — Edit ~/.hermes/config.yaml directly

Minimal setup:

config.yaml
model:
  default: gpt-4o-mini
  provider: custom
  base_url: https://api.modelstream.ai/v1
  api_key: ms-...

Recommended: named custom provider. This keeps ModelStream alongside any other endpoints you use, reads the key from the environment instead of the config file, and lets you pin context lengths per model:

config.yaml
custom_providers:
  - name: modelstream
    base_url: https://api.modelstream.ai/v1
    key_env: MODELSTREAM_API_KEY
    api_mode: chat_completions
    models:
      gpt-4o-mini:
        context_length: 128000
      claude-sonnet:
        context_length: 200000
      modelstream-auto:
        context_length: 128000

Step 4 — Verify and switch models

Start a session with hermes, then switch models mid-session:

hermes session
/model custom:modelstream:gpt-4o-mini       # named-provider triple syntax
/model custom:modelstream:claude-sonnet     # one string to change provider+model
/model custom:modelstream:modelstream-auto  # let ModelStream smart-route for you

(With the simple Option A/B setup, the syntax is /model custom:<model>.)

Hermes persists your choice to config, so it survives restarts. Remember the split: hermes model (in your terminal) adds/configures providers; /model (inside a chat) only switches between ones already set up.

Tips

Vision models

If you point Hermes at a vision-capable ModelStream model, set model.supports_vision: true in config.yaml so attached images are sent natively rather than pre-processed.

Context length

Hermes auto-detects context windows (including via your endpoint's /models API). Set context_length explicitly only if detection gets it wrong.

Auxiliary models

Some Hermes tools (vision, web summarization, MoA) use an "auxiliary" model that defaults to your main chat model. Route these to a cheaper ModelStream model in the auxiliary config section to cut costs further.

Output cap vs context window

model.max_tokens limits a single response; context_length is the total window. Don't confuse them.

Troubleshooting

Symptom
Fix
401 / auth errors
Check MODELSTREAM_API_KEY is exported (or set in ~/.hermes/.env) and key_env matches the variable name.
404 on requests
Base URL must include /v1: https://api.modelstream.ai/v1.
/model won't show ModelStream
Providers are added with hermes model outside a session — exit (/quit), run hermes model, restart.
Wrong context window
Set context_length per model under custom_providers[].models, or model.context_length for the simple setup.
Provider-specific request fields needed
Add an extra_body: map under the ModelStream entry in custom_providers.

Next steps

  • Browse the full catalog in your ModelStream dashboard and add slugs under custom_providers[].models as needed.
  • Estimate your monthly bill with the ModelStream cost calculator.
  • Migrating an existing OpenAI or Anthropic codebase too? Same one-line base-URL swap — see the ModelStream migration guides.
Also using OpenClaw? Use ModelStream with OpenClaw
ModelStream

Video API

  • Seedance 2.0
  • Happyhorse 1.0
  • Vidu Q3
  • Kling V3.0
  • Veo 3.1
  • Wan 2.7
  • More Video Models →

Image API

  • GPT Image 2
  • Nano Banana 2
  • Seedream 5.0
  • Imagen 4
  • Qwen Image 2.0
  • Z-Image Turbo
  • More Image Models →

Audio API

  • Suno Music
  • Qwen3 TTS Flash
  • More Audio Models →

Chat API

  • GLM-5.2
  • Claude Opus 4.8
  • Gemini 3.5 Flash
  • Qwen 3.7 Max
  • GPT 5.5
  • More Chat Models →

About Us

  • Privacy Policy
  • Terms of Service
  • Support
  • Enterprise

© 2026 ModelStream Inc. All rights reserved.