Hermes Agent Using Ace Data Cloud 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.), and can run on various backends such as local, Docker, SSH, Daytona, Modal, Vercel Sandbox, etc.

Hermes natively supports any OpenAI-compatible endpoint and can directly connect to Ace Data Cloud 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.

Application Process

To use this service, first go to the Ace Data Cloud Console to obtain your API Token for backup.

If you are not logged in or registered, you will be automatically redirected to the login page to invite you to register and log in. After registering and logging in, you will be automatically returned to the current page. The first application will grant a free quota, allowing you to experience the capabilities of Hermes Agent in conjunction with Ace Data Cloud for free.

Install Hermes Agent

Hermes is a Python package that requires Python 3.10 or higher. It is recommended to install it globally using pipx:

pipx install hermes-agent

You can also use pip:

pip install --user hermes-agent

After installation, check if the command is available:

hermes --version

If you see command not found, please check if the bin directory of pipx or pip --user is in your PATH.

Configure Ace Data Cloud

Hermes saves "secrets" (API Token) and "non-secrets" (provider and model selection) separately in ~/.hermes/.env and ~/.hermes/config.yaml. Ace Data Cloud is accessed 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.acedata.cloud/v1
API key The Token you copied from the Ace Data Cloud console
Model For example claude-sonnet-4-6 (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 and the API Token to ~/.hermes/.env, then you can start:

hermes chat

Method 2: Manually Edit Configuration File

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

ACEDATA_API_KEY={token}

Replace {token} with your API Token.

Then edit ~/.hermes/config.yaml:

custom_providers:
  - name: acedatacloud
    base_url: https://api.acedata.cloud/v1
    key_env: ACEDATA_API_KEY
    api_mode: chat_completions

model:
  provider: custom:acedatacloud
  default: claude-sonnet-4-6
  context_length: 200000

After saving, you can start:

hermes chat

Hermes requires each session to have at least a 64K context window. 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 Ace Data Cloud.

1. Check Hermes Version

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

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

2. Single Turn Conversation (Default Model claude-sonnet-4-6)

Use -Q silent mode + --max-turns 1 to run a minimal conversation, allowing the model to 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-sonnet-4-6 with gpt-5, gemini-2.5-pro, deepseek-v3.2-exp, or any other ID from the "recommended models" below to confirm that multiple model families are available.

4. Direct curl Check (Bypassing Hermes)

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

$ curl -sS -H "Authorization: Bearer $ACEDATA_API_KEY" \
       -H "Content-Type: application/json" \
       -X POST https://api.acedata.cloud/v1/chat/completions \
       -d '{"model":"claude-sonnet-4-6","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, refer to the "Troubleshooting" section below to locate the cause; especially HTTP 402 / HTTP 403 used_up indicates that the Token is valid but the balance is insufficient, recharge at platform.acedata.cloud/console/balance.

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

Family Recommended Model ID Remarks
Claude claude-sonnet-4-6 The strongest daily use model
Claude claude-opus-4-8 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-k2.5 / kimi-k2-thinking-turbo Moonshot reasoning model
GLM glm-4.6 / glm-5 / glm-5.1 Zhizhu flagship

The complete model directory can be queried at https://api.acedata.cloud/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-4-8 --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 is a high-priced model 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 Ace Data Cloud 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.

Hermes itself does not have any additional charges.

Advanced: Coexistence with other providers + Failover

Hermes supports the custom_providers: list, allowing you to configure Ace Data Cloud, local Ollama, Together AI, etc., simultaneously and switch freely at runtime. You can also configure a fallback chain to automatically downgrade to another provider if the main provider fails:

custom_providers:
  - name: acedatacloud
    base_url: https://api.acedata.cloud/v1
    key_env: ACEDATA_API_KEY
  - name: local
    base_url: http://localhost:11434/v1   # Local Ollama

model:
  provider: custom:acedatacloud
  default: claude-sonnet-4-6

fallback_providers:
  - provider: custom:acedatacloud
    model: gpt-5
  - provider: custom:local
    model: qwen2.5-coder:32b

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 should be claude-sonnet-4-6 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: 200000 in the model block of config.yaml
Model is in /v1/models list but call returns 500 The model may not yet be enabled on your account; first verify the token is valid with gpt-5 or other general models

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