BETA

Docs
Instructions

How to connect Hermes to Apily

Hermes works with any OpenAI-compatible endpoint. The address and the key are entered in the hermes model wizard or written into config.yaml — both paths end up in the same file.

Tool
Hermes OpenAI-compatible
Base URL
https://apily.pro/v1
Key
apily_your-api-key
Config file
~/.hermes/config.yaml

Requirements

  • Windows 10/11, macOS 12+ or a modern 64-bit Linux.
  • A terminal: on macOS, Linux, WSL2 and Termux the installer runs through curl, on Windows through PowerShell.
  • Settings live in ~/.hermes/, or %LOCALAPPDATA%\hermes on Windows.
  • An Apily API key from your account at apily.pro.

Install Hermes

macOS, Linux, WSL2, Termux
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
Windows PowerShell
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Reload your shell after installing and check the command: hermes starts the agent and hermes model opens the provider setup wizard.

Configuration

  1. Leave the active session first: inside a chat, /model only switches between things already set up and cannot add a provider.
  2. Start the wizard: hermes model.
  3. Choose Custom endpoint (self-hosted / VLLM / etc.).
  4. API base URL: https://apily.pro/v1
  5. API key: apily_your-api-key
  6. Model name: gpt-5.6-sol. The context-length field can stay empty — it is then detected automatically.

Both paths write into the same config.yaml; the wizard merely fills it in for you.

~/.hermes/config.yaml
model:
  default: gpt-5.6-sol
  provider: custom
  base_url: https://apily.pro/v1
  api_key: apily_your-api-key

Prefer a named provider (handy when there is more than one endpoint)? Then the key comes from the environment variable named in key_env:

~/.hermes/config.yaml
providers:
  apily:
    api: https://apily.pro/v1
    key_env: APILY_API_KEY
    transport: chat_completions
    discover_models: false
    models:
      - gpt-5.6-sol
~/.hermes/.env
APILY_API_KEY=apily_your-api-key

The files live in ~/.hermes/, or in %LOCALAPPDATA%\hermes on Windows (config.yaml and .env).

Your first request

terminal
curl https://apily.pro/v1/chat/completions \
  -H "Authorization: Bearer apily_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-sol","messages":[{"role":"user","content":"ping"}]}'

Then start the agent with hermes. Inside a session the model is switched with /model custom:gpt-5.6-sol, or /model custom:apily:gpt-5.6-sol for the named provider.

Switching models

The model list comes from the hermes model wizard, or from /model inside a session. With discover_models: false you see exactly what is listed under models; with the default value Hermes queries the endpoint's own /models. Examples from the Apily catalog:

  • gpt-5.6-sol · claude-opus-5 · deepseek-v4-flash-0731 · gemini-3.5-flash

Configuring reasoning

If the tool can send a reasoning_effort field, Apily forwards it upstream unchanged. Thinking is billed as output tokens.

Common errors and how to fix them

SymptomCauseFix
"No authenticated providers" in the pickerHermes lists a provider only when it has a working credential.Run hermes model again and enter the key.
The new provider is missing from /modelInside a session /model only switches between things already set up and never adds a provider.Leave the session, run hermes model, then start a new session.
The model list is slow or noisyBy default Hermes queries the endpoint's /models listing.Set discover_models: false and list the models you want under models.
401 Invalid API keyKey copied with stray spaces, truncated, or revoked.Copy the key whole from the API page in your Apily account, the apily_ prefix included.
402 Insufficient balanceYour token balance can't cover the request's estimated cost.Top up your balance on the Billing page in your Apily account.

FAQ

All guidesPreviousDeepSeek HarnessNextPi