Hermes Setup

    Prerequisites

    • Create an API key in the Gate.AI Console.
    • If you use auto routing, enable it under Settings → Routing in the console.

    Option 1: Terminal setup

    1. Choose model and custom endpoint

    Run in your terminal:

    bash
    1hermes model

    In the menu, choose Custom endpoint and fill in the fields:

    ItemValue
    API base URLhttps://api.gate.ai/openai/v1
    API keyYour Gate.AI API key
    Modelauto (recommended for auto routing), or the full model ID from the console (e.g. deepseek/deepseek-v3.2)

    If you are asked for context length, press Enter to leave it blank (Hermes will detect it).

    2. (Optional) Local web dashboard

    To edit configuration in the browser, run:

    bash
    1hermes dashboard

    3. Verify

    bash
    1hermes chat "Hello"

    Success means the request reached Gate.AI and smart routing or your chosen model returned a result.

    You can also run hermes doctor to verify the connection.

    Option 2: Edit configuration files

    1. File locations

    macOS / Linux

    • ~/.hermes/config.yaml , main config (model, provider, base_url, api_key, etc.)
    • ~/.hermes/.env , secrets and env vars (recommended)

    Windows

    • C:\Users.hermes\config.yaml
    • C:\Users.hermes.env

    2. Save the API key in .env (pick one)

    Option A (same name as Gate.AI)

    bash
    1# Gate.AI API 密钥2GATEAI_API_KEY=sk-v1-xxxxxxxxxxxxxxxxxxxxx

    Option B (common Hermes custom-endpoint convention)

    If model.api_key is not set for a custom endpoint, Hermes falls back to OPENAI_API_KEY. Put your Gate.AI key there:

    toml
    1OPENAI_API_KEY=sk-v1-xxxxxxxxxxxxxxxxxxxxx

    3. Configure model in config.yaml

    Auto routing (auto)

    yaml
    1model:2  default: auto3  provider: custom4  base_url: https://api.gate.ai/openai/v15  api_key: ${GATEAI_API_KEY}

    If you use Option B, leave api_key blank or remove it so Hermes uses OPENAI_API_KEY.

    Hermes expands ${VAR} when loading config (variables must exist in the environment, usually from ~/.hermes/.env).

    Fixed model example

    The model ID must match the Gate.AI model list.

    yaml
    1model:2  default: deepseek/deepseek-v3.23  provider: custom4  base_url: https://api.gate.ai/openai/v15  api_key: ${GATEAI_API_KEY}

    4. Verify after saving

    After saving, run hermes chat "Hello" to verify the Gate.AI connection.

    Multiple routes / models

    If you need multiple logical routes under one Gate.AI key (e.g. one with auto and one fixed to deepseek/deepseek-v3.2), add custom_providers in config.yaml (names: letters, digits, hyphens; e.g. gateai-auto):

    yaml
    1model:2  default: auto3  provider: custom4  base_url: https://api.gate.ai/openai/v15  api_key: ${GATEAI_API_KEY}67custom_providers:8  - name: gateai-auto9    base_url: https://api.gate.ai/openai/v110    api_key: ${GATEAI_API_KEY}11    model: auto1213  - name: gateai-deepseek14    base_url: https://api.gate.ai/openai/v115    api_key: ${GATEAI_API_KEY}16    model: deepseek/deepseek-v3.2

    How to switch

    1. Terminal: run hermes model again and pick the named route or Custom endpoint.
    2. In chat (TUI): use the /model syntax from the Hermes docs, for example:
    bash
    1/model custom:gateai-auto:auto2/model custom:gateai-deepseek:deepseek/deepseek-v3.2

    (Names follow custom_providers[].name; format is custom:<profile name>:<model id>.)

    FAQ

    Only some models work

    Confirm model.provider is custom, and Base URL is https://api.gate.ai/openai/v1. If OpenAI-compatible models work but others do not, check model IDs and routing settings.

    401 / invalid API key

    Check the key is copied correctly and not expired; after editing .env, restart running hermes and hermes gateway before retrying.

    Model not found or empty reply

    • Model ID matches the console (e.g. deepseek/deepseek-v3.2 ).
    • Auto routing is enabled in the Gate.AI console.
    • Run hermes doctor to inspect config and connectivity.