@open-gonka/hermes-setup

Point hermes-agent at the Gonka Router OpenAI-compatible endpoint in one npx command.

npx @open-gonka/hermes-setup

Need an account / API key? Register and issue a gnk-sk-… key at https://opengonka.com. The installer also prints this link as a clickable terminal link right before it asks for your key.

Connect (recommended)

npx @open-gonka/hermes-setup --connect

--connect links this machine to your OpenGonka account in the browser and provisions the API key automatically — no copy-paste. It uses the OAuth 2.0 Device Authorization Grant (like claude / gh auth login), so it also works over SSH on a headless server:

1. the installer opens (or prints) https://opengonka.com/connect?code=…
2. you sign in and approve the connection (showing the displayed code)
3. the hub mints a gnk-sk-… key, the installer writes it into Hermes

If the Connect endpoints are not available, the installer falls back to the hidden manual key prompt automatically.

Headless / unattended installs

The interactive picker and confirmation need a TTY. For a fully unattended install on a server (e.g. provisioning scripts), pass the model and skip the confirmation:

npx @open-gonka/hermes-setup --connect \
  --model moonshotai/Kimi-K2.6 \
  --yes

• --model <id> — preselect a qualified model (skips the interactive picker). Matched case-insensitively; an unknown id fails with the list of qualified models. Current qualified ids:
  • moonshotai/Kimi-K2.6 (recommended)
  • MiniMaxAI/MiniMax-M2.7
  • Qwen/Qwen3-235B-A22B-Instruct-2507-FP8
• --yes — apply the planned changes without the confirmation prompt.
• Browser auto-open opt-out: NO_BROWSER=1 or OPENGONKA_SETUP_NO_BROWSER=1 (also auto-skipped when CI is set). The active link is always printed.

With --connect the approval still happens in a browser you control (open the printed link on any device); the CLI itself needs no local browser or stdin.

Overview

@open-gonka/hermes-setup is a small onboarding helper for people who use hermes-agent and want it configured to use Gonka Router without manually editing ~/.hermes/config.yaml or ~/.hermes/.env.

It configures Hermes to use:

• provider: custom
• base_url: https://api.opengonka.com/v1

Is This For You?

This helper is for you if you want Hermes to use Gonka Router as its primary OpenAI-compatible endpoint through provider: custom and https://api.opengonka.com/v1.

You should also have:

• hermes-agent available on your machine
• Hermes Agent v2026.5.16 / v0.14.0 or newer
• a Gonka Router API key (gnk-sk-…) — get one at https://opengonka.com
• an interactive terminal
• Linux, macOS, or WSL2

What Happens During Setup

In plain language, the helper:

• finds the active Hermes config, including --profile <name> if you use one
• prints an active (clickable) registration link so unregistered users can sign up and create a key
• asks for your Gonka Router key through a hidden prompt
• calls GET https://api.opengonka.com/v1/models, compares the live catalog with the checked-in launch qualification artifacts, and offers only currently qualified models
• writes the minimum Hermes settings needed for Gonka Router
• rolls back if a later write fails

A successful GET /v1/models check confirms auth and model visibility only. It does not prove billing, quota, or first-request readiness.

What It Changes

The helper manages these Hermes files:

• ~/.hermes/config.yaml
• ~/.hermes/.env

When setup succeeds, the helper writes only the Gonka-Router-managed surface:

• model.provider = custom
• model.base_url = https://api.opengonka.com/v1
• model.default = <selected model>
• model.api_key = ${GONKA_ROUTER_API_KEY}
• GONKA_ROUTER_API_KEY (your raw key, stored only in ~/.hermes/.env)

Your raw key is stored only in ~/.hermes/.env. It is never written to config.yaml; the config only stores the ${GONKA_ROUTER_API_KEY} reference.

Important Limits

The helper intentionally stays narrow:

• it does not replace hermes setup
• it does not support legacy endpoint paths such as OPENAI_BASE_URL, LLM_MODEL, root-level provider / base_url, or legacy custom_providers
• it does not accept arbitrary custom base URLs
• it does not mutate shell profiles or auth.json credential pools
• it does not support native Windows
• it does not claim full first-request verification beyond GET /v1/models

The current checked-in launch qualification artifacts include:

• moonshotai/Kimi-K2.6 (recommended default)
• MiniMaxAI/MiniMax-M2.7
• Qwen/Qwen3-235B-A22B-Instruct-2507-FP8

Configuration source of truth

Everything that identifies the deployment lives in src/constants/contract.ts:

| Constant | Value | | ------------------ | ------------------------------ | | canonicalBaseUrl | https://api.opengonka.com/v1 | | registrationUrl | https://opengonka.com | | apiKeyEnvVar | GONKA_ROUTER_API_KEY | | apiKeyPrefix | gnk-sk- |

Change those values to retarget the installer at a different router/hub.

Learn More

• How It Works
• Security
• Connect Backend Contract (for the OpenOpen Gonka team)