How to Run Hermes Agent with an OpenAI-Compatible Endpoint

August 13, 2026

Terminal agents are most useful when they can keep memory, switch models, and run against the same endpoint you use in the rest of your stack. This guide shows how to connect a self-installed Hermes Agent instance to Ace Data Cloud through Hermes's OpenAI-compatible Custom Endpoint flow.

What you can do

With this setup, Hermes can call Ace Data Cloud through https://api.acedata.cloud/v1 using the Chat Completions transport. That means your terminal agent can use a model such as claude-opus-5, gpt-5, gemini-2.5-pro, deepseek-v3.2-exp, kimi-k3, or glm-4.6, while keeping the configuration inside Hermes.

The practical outcome is simple: you install Hermes once, point it at the Ace Data Cloud base URL, store the token in an environment file, and then run hermes chat. You can also verify the same endpoint directly with curl before debugging anything inside the agent.

How it works

Hermes separates secrets from non-secrets. The API token goes in ~/.hermes/.env, while the provider definition and model selection live in ~/.hermes/config.yaml. Ace Data Cloud is configured as a custom provider with transport: chat_completions.

Under the hood, Hermes calls the OpenAI-compatible endpoint. The main request path for chat is:

POST https://api.acedata.cloud/v1/chat/completions

Hermes can also read model metadata from /v1/models. If context length detection is not available during startup, the documentation recommends setting an explicit context_length. Hermes requires at least a 64K context window for each session; the recommended models in the source guide meet that requirement.

Install Hermes Agent

On Linux, macOS, or WSL2, use the official installer:

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

The installer prepares the dependencies Hermes needs, including Python, Node.js, ripgrep, and ffmpeg. After installation, check that the command is available:

hermes --version

If a version string is printed, the CLI is installed and ready for provider configuration.

Configure the custom endpoint interactively

The easiest path is the interactive model selector:

hermes model

When Hermes lists providers, choose:

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

Then enter the values from the Ace Data Cloud guide:

API base URL: https://api.acedata.cloud/v1
API key: your Ace Data Cloud API token
Model: for example, claude-opus-5
Context length: leave blank so Hermes can read from /v1/models, or use 200000 as a fallback

Once saved, start a session:

hermes chat

Configure it manually for repeatable environments

For a machine image, CI setup, or batch deployment, editing the files directly is often cleaner. First put the token in ~/.hermes/.env:

ACEDATA_API_KEY={token}

Then define the provider in ~/.hermes/config.yaml:

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

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

This makes ACEDATA_API_KEY the only secret-bearing value. The YAML file can stay focused on provider name, base URL, transport, context length, and the default model.

Verify the integration before using it for real work

Start with a one-turn Hermes check. Silent mode plus --max-turns 1 keeps the test deterministic:

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

If the output is HERMES_OK, Hermes is reaching /v1/chat/completions successfully.

You can also bypass Hermes and test the endpoint directly:

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-opus-5","messages":[{"role":"user","content":"reply HERMES_OK"}],"max_tokens":20}'

The expected response is an OpenAI-compatible chat.completion object. The model reply is available at choices[0].message.content.

Switch models and route auxiliary work

Inside a running Hermes chat, you can switch models with commands such as:

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

To persist a choice globally, add --global:

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

Hermes also lets you route auxiliary tasks, such as title generation, vision, compression, and web extraction, to separate models. The documented example uses Flash models for those supporting jobs:

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

Troubleshooting checklist

No API key or provider not found: check ~/.hermes/.env for ACEDATA_API_KEY, or rerun hermes model.
HTTP 401 or HTTP 403: the API token may be wrong or disabled.
HTTP 402: the token is valid, but the balance is insufficient.
HTTP 429: an upstream rate limit was triggered; wait and retry later.
Context limit: 2048 tokens: explicitly add context_length: 1000000 under the provider.
No valid account found: check the model ID. The guide calls out claude-opus-5 as the expected style, not claude-sonnet-4-5.

Once the single-turn check passes, you have a clean baseline: Hermes is installed, the custom provider is configured, and the same token works through a direct Chat Completions call. From there, the agent-specific work—memory, skills, channels, and scheduled tasks—can be configured inside Hermes rather than mixed into the model plumbing.

For the source configuration details and the maintained model list, read the Ace Data Cloud Hermes Agent integration guide.

Search This Blog

AceDataCloud