Hermes: Claude and Codex configuration

Add a named CloudService provider to Hermes and expose only the model family allowed by the key.

Automatic configuration

bash

npm install -g cloudservice@latest
cloudservice

Select Hermes. The CLI detects the catalog, preserves unrelated profiles in ~/.hermes/config.yaml, stores the key outside YAML, adds the required user agent, and verifies one compatible model. Use cloudservice doctor to check it again.

Shared secure key setup

Hermes loads provider secrets from ~/.hermes/.env. On a new setup, store the key without echoing it or placing it in shell history. If the variable already exists, edit that line privately instead of appending a duplicate:

bash

umask 077
mkdir -p "$HOME/.hermes"
printf "CloudService API key: "
IFS= read -r -s CLOUDSERVICE_HERMES_API_KEY
printf "\n"
printf "CLOUDSERVICE_HERMES_API_KEY=%s\n" "$CLOUDSERVICE_HERMES_API_KEY" >> "$HOME/.hermes/.env"
unset CLOUDSERVICE_HERMES_API_KEY
chmod 600 "$HOME/.hermes/.env"

Do not put the key in config.yaml. If you replace the key with a different billing mode, update the provider URL at the same time.

Manual configuration for Codex models in Hermes

Merge this named provider into ~/.hermes/config.yaml. For an OpenAI token-pack key, change only base_url to https://api.yourdomain.example/token/v1.

yaml

custom_providers:
  - name: cloudservice-codex
    base_url: https://api.yourdomain.example/v1
    key_env: CLOUDSERVICE_HERMES_API_KEY
    api_mode: codex_responses
    extra_headers:
      User-Agent: CloudService-Hermes/1.0
    models:
      gpt-5.6-terra: {}

model:
  provider: custom:cloudservice-codex
  default: gpt-5.6-terra

codex_responses selects Hermes's native Responses transport for Codex models. The IDs above are examples only: add or remove IDs using the authenticated /models catalog for this exact key. Do not put Claude or DeepSeek V4 Flash in this provider.

bash

hermes --provider custom:cloudservice-codex \
  --model gpt-5.4-mini \
  --ignore-rules --toolsets clarify --oneshot "K"

Manual configuration for Claude models in Hermes

Use this separate provider for a key that exposes Claude. For a Claude token-pack key, change only base_url to https://api.yourdomain.example/token.

yaml

custom_providers:
  - name: cloudservice-claude
    base_url: https://api.yourdomain.example
    key_env: CLOUDSERVICE_HERMES_API_KEY
    api_mode: anthropic_messages
    extra_headers:
      User-Agent: CloudService-Hermes/1.0
    max_output_tokens: 4096
    models:
      fable-5: {}
      claude-opus-5: {}

model:
  provider: custom:cloudservice-claude
  default: claude-opus-5
  max_tokens: 4096

anthropic_messages selects Hermes's native Messages transport. Add only Claude IDs returned by this key's native model discovery. The shared 4096 value is an intentional response-budget cap for this mixed-model provider, not Claude Opus 5's native capability; raise it deliberately only when the selected model and your budget support a larger response. Keep User-Agent: CloudService-Hermes/1.0 exactly as shown.

bash

hermes --provider custom:cloudservice-claude \
  --model claude-haiku-4-5-20251001 \
  --ignore-rules --toolsets clarify --oneshot "K"

Manual configuration for DeepSeek V4 Flash in Hermes

DeepSeek V4 Flash is not a Codex Responses model or a Claude Messages model. It uses the OpenAI-compatible Chat Completions route. Configure it only when this exact key's catalog declares tools: true; Hermes agent mode fails closed on a text-only route.

yaml

custom_providers:
  - name: cloudservice-deepseek
    base_url: https://api.yourdomain.example/v1
    key_env: CLOUDSERVICE_HERMES_API_KEY
    api_mode: chat_completions
    extra_headers:
      User-Agent: CloudService-Hermes/1.0
    max_output_tokens: 4096
    models:
      deepseek-v4-flash: {}

model:
  provider: custom:cloudservice-deepseek
  default: deepseek-v4-flash
  max_tokens: 4096

For a DeepSeek token-pack key, change only base_url to https://api.yourdomain.example/token/v1. If the catalog does not declare tool support, use Continue Chat/Edit instead of forcing this provider into Hermes.

Runtime behavior and security

New Hermes sessions use the configured default; an existing chat keeps its active model until you switch it or start a new session. Hermes streams normally and owns its retry policy, so do not wrap it in another generation retry loop. The authenticated catalog is the source of truth whenever documentation examples and a key's available models differ.

Keep ~/.hermes/.env user-only. Never put the key in YAML, a repository, a prompt, or a support transcript. Inside a chat, switch with /model custom:cloudservice-codex:MODEL_ID or /model custom:cloudservice-claude:MODEL_ID.

See Hermes Agent's named custom-provider reference.