Use Hermes Agent with Models Hub: Custom Endpoint Setup

Point Hermes Agent's Custom Endpoint at Models Hub through the hermes model menu, so terminal tool calls and skills run on your Models Hub balance, with recommended models and error fixes.

Hermes Agent is an open-source terminal AI agent from Nous Research, bringing tool calling, file read/write, and code execution to your terminal. It has a built-in Custom Endpoint provider type that connects to any OpenAI-compatible API, configured entirely through an interactive menu — no config file editing or code required. This page covers only the connection step — see the official quickstart for the message gateway, skill store, and other features.

Three things you need

A Models Hub API key, the endpoint https://modelsok.com/v1 (must end with /v1), and a model name. Hermes requires a model with at least 64K tokens of context — confirm this before picking one.

Prerequisites

Hermes Agent installed (see the installation steps below). Project page: GitHub.
A Models Hub API key from the Tokens page, in a group that can access the models you want.

Recommended models

All three models below meet the 64K+ context requirement.

Use case	Model	Pricing	Live status
First choice for everyday terminal tasks	`claude-sonnet-4-6`	Price	Availability and latency
Complex reasoning and long-context tasks	`gpt-5.5`	Price	Availability and latency
Cheap and fast, good for simple tasks	`gpt-5.4-mini`	Price	Availability and latency

Model names are authoritative on the pricing page.

Setup

Install Hermes Agent.

Linux / macOS / WSL2:
```
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```
Windows (native):
```
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
```
Note: native Windows support depends on the current install script — if you hit issues, use WSL2 and run the Linux command instead. Run hermes --version afterward to confirm it installed.
Run the interactive configuration menu:
```
hermes model
```
Scroll to Custom Endpoint with the arrow keys and press Enter.
Fill in:

Setting What to enter
Base URL https://modelsok.com/v1, must end with /v1
API Key Your Models Hub API key
Model One of the model names above, must exactly match the model ID in the Models Hub console

Confirm as prompted to save.

Setting	What to enter
Base URL	`https://modelsok.com/v1`, must end with `/v1`
API Key	Your Models Hub API key
Model	One of the model names above, must exactly match the model ID in the Models Hub console

Verify

Launch Hermes and start chatting:

hermes

Or use TUI mode: hermes --tui. Send a test message, such as "Hi, tell me what day of the week it is today." A normal reply means you're connected. Then check Usage logs in the Models Hub console; a request under that model name appears within seconds, confirming traffic went through Models Hub. During a conversation, type /model at any time to view or switch the current model.

Common errors

Symptom	Cause	Fix
Empty reply or error	Base URL doesn't end with `/v1`	Run `hermes model` again and use `https://modelsok.com/v1`
"Model not found"	Model name doesn't exactly match the model ID in the Models Hub console	Check the spelling on the pricing page
"Invalid API Key"	Incomplete key, or a disabled token	Generate a new key on the Tokens page, then run `hermes model` again
"Insufficient context"	The model in use has less than 64K context	Switch to a model from the table above
Installation fails on Windows	The native script isn't compatible with some environments	Use WSL2 and run the Linux install command in a WSL2 terminal

FAQ

How is it billed? Per input and output token actually consumed per request, at the price on each model's pricing page.

How is this different from using the official API directly? The URL, key, and model name in Custom Endpoint work exactly like connecting to a vendor's API directly — only the domain changes to Models Hub.

How do I switch models? Type /model during a conversation, or run hermes model again to override the previous configuration.