Hermes Agent Using qiyaov Tutorial

Hermes Agent is an open-source terminal agent launched by Nous Research, supporting persistent memory, skill creation, and 21+ communication platform gateways (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, etc.). It can run on various backends such as local, Docker, SSH, Daytona, Modal, Vercel Sandbox, etc.

Hermes natively supports any OpenAI-compatible endpoint and can connect to qiyaov directly without additional plugins, with one API Token accessing 60+ large models such as Claude, GPT, Gemini, Grok, DeepSeek, Kimi, GLM, etc. This article describes the configuration process.

Private Beta Hosted Deployment

qiyaov can deploy an independent, persistent Hermes instance for each application. The platform automatically creates model credentials and counts them against the global quota of the account, without needing to paste the API Token in the wizard.

  1. Select the default model and resource specifications in the deployment wizard.
  2. After deployment, open the Hermes Dashboard on the management page.
  3. Log in using the username admin and the random password displayed on the management page.

Telegram, Discord, Slack, WhatsApp, Signal, Email, MCP, Skills, and Cron are all configured within the Hermes Dashboard. Configuration, sessions, memory, skills, and scheduled tasks are saved in the instance's persistent volume, which will not be cleared by ordinary Pod restarts or version updates. Completely deleting the deployment will also reclaim persistent data.

The hosted deployment is currently in private Beta. Please first verify automated behavior using a test account and test channel; stopping or deleting the instance will interrupt message reception and scheduled tasks.

Application Process

The hosted deployment is currently in private Beta and is enabled for approved accounts by the platform. When installing Hermes yourself, you can obtain the API Token from the qiyaov Console.

Install Hermes Agent

Linux, macOS, and WSL2 use the official installer:

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

The installer will prepare the necessary Python, Node.js, ripgrep, and ffmpeg for Hermes. After installation, check if the command is available:

hermes --version

You can also use the official Docker image directly; the hosted deployment uses the same image and persists variable data to /opt/data.

Configure qiyaov

Hermes saves "secrets" (API Token) and "non-secrets" (provider and model selection) separately in ~/.hermes/.env and ~/.hermes/config.yaml. qiyaov connects through Hermes's Custom Endpoint mechanism, with two configuration methods.

Method 1: Interactive hermes model (Recommended)

Run:

hermes model

Hermes will list all available providers, select:

Custom endpoint (self-hosted / VLLM / etc.)

Then follow the prompts to enter:

Field Input
API base URL https://api.qiyaov.com/v1
API key The Token you copied from the qiyaov console
Model For example, claude-opus-5 (see the recommended list below)
Context length Leave blank to let Hermes automatically read from /v1/models, or fill in 200000 as a fallback

Hermes will write the selection to ~/.hermes/config.yaml, write the API Token to ~/.hermes/.env, and then you can start:

hermes chat

Method 2: Manually Edit Configuration Files

If you prefer to edit the configuration directly (for example, in batch deployments, CI/CD scenarios), edit ~/.hermes/.env:

ACEDATA_API_KEY={token}

Replace {token} with your API Token.

Then edit ~/.hermes/config.yaml:

providers:
  acedatacloud:
    name: Ace Data Cloud
    api: https://api.qiyaov.com/v1
    key_env: ACEDATA_API_KEY
    transport: chat_completions
    context_length: 1000000

model:
  provider: custom:acedatacloud
  default: claude-opus-5

After saving, you can start:

hermes chat

Hermes requires at least a 64K context window for each session. The recommended models below all meet this requirement. If you enable a model with a smaller context (such as below 32K), Hermes will refuse to start.

Verify Integration

After completing the configuration as described above, run the following minimal commands to confirm that Hermes has successfully connected to qiyaov.

1. Check Hermes Version

$ hermes --version
Hermes Agent v0.20.0 (...)
Python: 3.12.x

As long as the version number is output, it indicates that the command line is available.

2. Single Turn Dialogue (Default Model claude-opus-5)

Run a minimal dialogue using -Q silent mode + --max-turns 1 to have the model echo a string exactly:

$ hermes chat -Q --max-turns 1 -q "Reply with EXACTLY this string and nothing else: HERMES_OK"

HERMES_OK

If you see HERMES_OK in the output, it indicates that /v1/chat/completions is working.

3. Switch to Another Model

$ hermes chat -Q --max-turns 1 -q "Reply ONLY with the word PONG"

PONG

You can replace claude-opus-5 with any ID from the "recommended models" below, such as gpt-5, gemini-2.5-pro, deepseek-v3.2-exp, etc., to confirm that multiple model families are available.

4. Direct Curl Verification (Bypassing Hermes)

If you want to bypass Hermes to verify the endpoint directly, you can use curl:

$ curl -sS -H "Authorization: Bearer $ACEDATA_API_KEY" \
       -H "Content-Type: application/json" \
       -X POST https://api.qiyaov.com/v1/chat/completions \
       -d '{"model":"claude-opus-5","messages":[{"role":"user","content":"reply HERMES_OK"}],"max_tokens":20}'

This will return an OpenAI-compatible chat.completion object, with the choices[0].message.content field being the model's reply. If it returns HERMES_OK, it confirms that the Token and model ID configuration are correct.

5. If Any Step Fails

Do not continue adjusting parameters; first, locate the cause according to the "Troubleshooting" section below; especially HTTP 402 / HTTP 403 used_up indicates that the Token is valid but the balance is insufficient, and you can recharge at platform.acedata.cloud/console/balance.

The following models have been end-to-end verified with qiyaov POST /v1/chat/completions and can be used directly as model.default:

Family Recommended Model ID Remarks
Claude claude-opus-5 The strongest daily main model
Claude claude-opus-5 Flagship, complex reasoning / long tasks
GPT gpt-5 OpenAI flagship
GPT gpt-5.4 Latest generation
Gemini gemini-2.5-pro Google flagship, multimodal
Gemini gemini-3.0-pro / gemini-3.1-pro Latest Gemini 3 series
Grok grok-4 xAI flagship
DeepSeek deepseek-v3.2-exp / deepseek-v3 High cost-performance ratio
Kimi kimi-k3 Moonshot reasoning and vision flagship model
GLM glm-4.6 / glm-5 / glm-5.1 Zhizhu flagship

The complete model directory can be queried at https://api.qiyaov.com/v1/models (also the endpoint called during Hermes startup self-check).

Switching models can also be executed at any time in the running chat:

/model custom:acedatacloud:gpt-5
/model custom:acedatacloud:gemini-2.5-pro
/model custom:acedatacloud:deepseek-v3.2-exp

To persist to config.yaml, add the --global parameter:

/model custom:acedatacloud:claude-opus-5 --global

Use cheaper models for auxiliary tasks (optional, cost-saving)

Hermes defaults to using the main model for "auxiliary tasks" such as session title generation, visual analysis, context compression, and web summarization. If the main model uses high-priced models like Opus / GPT-5, this part will waste costs. Auxiliary tasks can be routed to cheaper Flash models:

auxiliary:
  title:
    provider: custom:acedatacloud
    model: gemini-2.5-flash
  vision:
    provider: custom:acedatacloud
    model: gemini-2.5-flash
  compression:
    provider: custom:acedatacloud
    model: gemini-2.5-flash
  web_extract:
    provider: custom:acedatacloud
    model: gemini-2.5-flash-lite

You can also configure it using the "Show auxiliary" panel of hermes model.

Billing Explanation

All calls are billed according to the Credits on the qiyaov platform — based on the model and token count. Token balance, consumption records, and usage aggregated by model can be viewed at platform.acedata.cloud/console/usages; when the balance is insufficient, recharge at platform.acedata.cloud/console/balance.

There are no additional software fees for self-installing Hermes; the hosted deployment is currently in private Beta and does not offer a public deployment package. Model calls are still billed according to the above Credits.

Advanced: Coexistence with other providers + Failover

Hermes supports the providers: dictionary, allowing you to configure qiyaov, local Ollama, and other compatible endpoints simultaneously, switching at runtime with /model custom:<name>:<model>:

providers:
  acedatacloud:
    api: https://api.qiyaov.com/v1
    key_env: ACEDATA_API_KEY
    transport: chat_completions
  local:
    api: http://localhost:11434/v1
    transport: chat_completions

model:
  provider: custom:acedatacloud
  default: claude-opus-5

The old version of Hermes's custom_providers: list can still be read, but the current configuration format is based on providers:.

Troubleshooting

Phenomenon Troubleshooting Direction
No API key / provider not found Check if ~/.hermes/.env has ACEDATA_API_KEY; or rerun hermes model to input
HTTP 401 / 403 API Token error or disabled, please regenerate at console
HTTP 402 Insufficient balance, recharge at recharge page
HTTP 429 Triggered upstream rate limiting, please try again later
No valid account found Model ID is not a standard name — note it is claude-opus-5 not claude-sonnet-4-5, refer to /v1/models output
Context limit: 2048 tokens startup error Hermes did not receive context length, explicitly add context_length: 1000000 in providers.<name>
Model is in /v1/models list but call 500 The model may not yet be enabled on your account; first verify Token validity with gpt-5 or other general models

For more details, please refer to the official Hermes documentation: