Hermes - Orq.ai Documentation

Hermes Agent is a self-improving agent from Nous Research with a built-in MCP client. Route its model calls through the AI Gateway, then connect it to the Orq MCP server for agentic access to the workspace.

Prerequisites

Hermes installed (desktop app or CLI)
Active Orq.ai account
An Orq.ai API key

AI Gateway

Hermes is OpenAI-compatible, so it routes through the AI Gateway by pointing the OpenAI provider at the router. Configure it in the desktop app or the CLI. Changes made in the desktop app apply to the CLI as well, since both share the same configuration.

Desktop app
CLI

Open provider settings

Open the Hermes desktop app. On first launch, skip provider selection to set it later. Open Settings in the top right, then go to Providers > API keys.

Set the OpenAI API key and base URL

Scroll to OpenAI API and expand it. Paste the Orq.ai API key into the OpenAI API key field and click Save. Then paste the router URL into the OpenAI API base URL override field and click Save:

https://api.orq.ai/v3/router

Hermes API keys settings with the OpenAI API entry expanded, the Orq.ai key in the OpenAI API key field, and the router URL in the base URL override field

Select a model

Hermes now routes through the AI Gateway. Pick a model from the recommended list, or search by name for any other model from the AI Gateway catalog that is not shown.

Open the config with hermes config edit and set the model block to a custom provider pointed at the router, with the Orq.ai key inline:

model:
  provider: custom
  default: "anthropic/claude-sonnet-4-6"
  base_url: "https://api.orq.ai/v3/router"
  api_key: "<your-orq-api-key>"

Set default to any provider-prefixed model from the AI Gateway catalog. Override the model for a single session with hermes chat --model openai/gpt-5.4.

The default config already contains a model block. Edit its existing keys; the block must end up with a single provider and a single base_url.

Verification

Send a prompt in Hermes. The response appears in Hermes and the request appears in Orq.ai Traces with the selected model identifier.

MCP

The Orq MCP server exposes the Orq.ai platform as MCP tools. Hermes’s built-in MCP client connects to it and uses those tools to manage Agents, run experiments, and query Traces from natural language.

Desktop app
CLI

Open MCP settings

In Settings, go to MCP and click New server in the top right.

Add the Orq MCP server

Set the Name to orq and paste the following into the Server JSON field, then click Save server:

{
  "url": "https://my.orq.ai/v2/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_ORQ_API_KEY"
  }
}

Replace YOUR_ORQ_API_KEY with an Orq.ai API key.

Hermes MCP settings showing a new server named orq with the Orq MCP URL and a bearer Authorization header in the Server JSON field

Reload MCP

Click Reload MCP in the top right. Hermes connects to the Orq MCP server and its tools become available.

Add the Orq MCP server to ~/.hermes/config.yaml under mcp_servers:

mcp_servers:
  orq:
    url: "https://my.orq.ai/v2/mcp"
    headers:
      Authorization: "Bearer <your-orq-api-key>"

Reload MCP servers without restarting by running /reload-mcp inside Hermes, then confirm the connection:

hermes mcp test orq

Available Commands

Once connected, ask Hermes to perform operations across the workspace:

Agents

Create an agent with custom instructions and tools
Get agent configuration for [agent-key]
Invoke agent [agent-key] with input [message]

Experiments

Create an experiment from dataset [dataset-key]
Run experiment and auto-evaluate results
Export experiment run [run-id] as CSV

Datasets

Create a dataset called "customer-queries"
Add datapoints to dataset [dataset-key]
List all datapoints in dataset [dataset-key]

Traces

List traces from the last 24 hours
Show me traces with errors
Get span details for trace [trace-id]

Analytics

Get analytics overview for my workspace
Show me workspace metrics for the last 7 days

Orq MCP Quickstart

The full Orq MCP tool reference.

API Keys

Create and manage Orq.ai API keys.

​Prerequisites

​AI Gateway

​Verification

​MCP

​Available Commands

​See Also

Orq MCP Quickstart

API Keys

Prerequisites

AI Gateway

Verification

MCP

Available Commands

See Also