Hermes | Vtrix API Docs

Overview

Hermes supports custom OpenAI-compatible providers. Add Vtrix as a named custom provider, store the Vtrix API key in Hermes’ .env file, and select a Vtrix model in config.yaml.

Prerequisites

Hermes Agent
A Vtrix API key, created in Settings

Optional: use Vtrix Doctor

You can also use Vtrix Doctor to check the local Base URL, API key, and model settings before editing files. Supported tools, including OpenClaw and Hermes, can be configured after confirmation.

Configuration Steps

Install Hermes

• Using the official install script

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

After installation, run:

hermes --version

Store your Vtrix API key

Hermes keeps secrets in ~/.hermes/.env. Create or edit the file:

mkdir -p ~/.hermes
vim ~/.hermes/.env

Add:

VTRIX_API_KEY=YOUR_VTRIX_API_KEY

Add Vtrix as a custom provider

Create or edit ~/.hermes/config.yaml:

vim ~/.hermes/config.yaml

Add the Vtrix provider and set it as the active model provider:

custom_providers:
  - name: vtrix
    base_url: https://cloud.vtrix.ai/llm
    key_env: VTRIX_API_KEY

model:
  provider: custom:vtrix
  default: gpt-5.5

Base URL

Use https://cloud.vtrix.ai/llm as the Vtrix OpenAI-compatible Base URL. Hermes reads the API key from the VTRIX_API_KEY entry in ~/.hermes/.env.

Switch models

To switch models, change only model.default.

Type	Example model	Notes
High performance	`gpt-5.5`	Strong general coding and reasoning
Standard	`gpt-5.4`	Balanced daily development
Qwen	`qwen3.7-max`	Qwen route through the same Vtrix base URL

Tip

You can also run hermes model, choose a custom endpoint, and enter the same Vtrix Base URL and model ID interactively.

Start Hermes

Go to your project directory and start Hermes:

cd /path/to/your/project
hermes

For a quick config check, run:

hermes doctor

If Hermes responds normally, requests are routed to Vtrix through the configured custom provider. You can also check usage or billing in Vtrix Settings.

Troubleshooting

Error: 401 Unauthorized

Cause: VTRIX_API_KEY is missing, incorrect, or not loaded from ~/.hermes/.env.

Fix:

grep VTRIX_API_KEY ~/.hermes/.env

Confirm the key exists, then restart Hermes.

Unknown provider or custom provider not found

Cause: model.provider does not match the custom provider name.

Fix: Confirm that the provider name is vtrix and the selected provider is custom:vtrix:

custom_providers:
  - name: vtrix

model:
  provider: custom:vtrix

Error: model not found

Cause: model.default does not match a Vtrix model ID.

Fix: Open the Models page, copy the correct model ID, and update model.default.

Hermes does not pick up the new configuration

Cause: Hermes was already running, or another config value overrides the active model.

Fix: Exit Hermes completely, restart it, and run:

hermes config
hermes doctor

Confirm the active provider is custom:vtrix and the base URL is https://cloud.vtrix.ai/llm.