# Hermes: Claude and Codex configuration

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

## Automatic configuration

**macOS / Linux**

```bash
npm install -g scalemax@latest
scalemax
```

**Windows PowerShell**

```powershell
npm.cmd install -g scalemax@latest
scalemax.cmd
```

Windows PowerShell blocks npm’s .ps1 launchers by default (“running scripts is disabled on this system”), so these commands use the .cmd launcher: npx.cmd, npm.cmd, scalemax.cmd. In Command Prompt you can leave out .cmd.

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 `scalemax doctor` to check it again.

## Shared secure key setup

Hermes loads provider secrets from `~/.hermes/.env` (Windows: `%USERPROFILE%\.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:

**macOS / Linux**

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

**Windows PowerShell**

```powershell
New-Item -ItemType Directory -Force -Path "$HOME\.hermes" | Out-Null
$secret = Read-Host "ScaleMax API key" -AsSecureString
Add-Content -Path "$HOME\.hermes\.env" -Value ("SCALEMAX_HERMES_API_KEY=" + [System.Net.NetworkCredential]::new("", $secret).Password)
Remove-Variable secret
```

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.scalemax.pro/token/v1`.

```yaml
custom_providers:
  - name: scalemax-codex
    base_url: https://api.scalemax.pro/v1
    key_env: SCALEMAX_HERMES_API_KEY
    api_mode: codex_responses
    extra_headers:
      User-Agent: ScaleMax-Hermes/1.0
    models:
      gpt-5.6-terra: {}

model:
  provider: custom:scalemax-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.

**macOS / Linux**

```bash
hermes --provider custom:scalemax-codex \
  --model gpt-5.6-luna \
  --ignore-rules --toolsets clarify --oneshot "K"
```

**Windows PowerShell**

```powershell
hermes --provider custom:scalemax-codex `
  --model gpt-5.6-luna `
  --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.scalemax.pro/token`.

```yaml
custom_providers:
  - name: scalemax-claude
    base_url: https://api.scalemax.pro
    key_env: SCALEMAX_HERMES_API_KEY
    api_mode: anthropic_messages
    extra_headers:
      User-Agent: ScaleMax-Hermes/1.0
    max_output_tokens: 4096
    models:
      fable-5: {}
      claude-opus-5: {}
      claude-opus-5-5: {}

model:
  provider: custom:scalemax-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: ScaleMax-Hermes/1.0` exactly as shown.

**macOS / Linux**

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

**Windows PowerShell**

```powershell
hermes --provider custom:scalemax-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: scalemax-deepseek
    base_url: https://api.scalemax.pro/v1
    key_env: SCALEMAX_HERMES_API_KEY
    api_mode: chat_completions
    extra_headers:
      User-Agent: ScaleMax-Hermes/1.0
    max_output_tokens: 4096
    models:
      deepseek-v4-flash: {}

model:
  provider: custom:scalemax-deepseek
  default: deepseek-v4-flash
  max_tokens: 4096
```

For a DeepSeek token-pack key, change only `base_url` to `https://api.scalemax.pro/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:scalemax-codex:MODEL_ID` or `/model custom:scalemax-claude:MODEL_ID`.

See [Hermes Agent's named custom-provider reference](https://hermes-agent.nousresearch.com/docs/integrations/providers/#named-custom-providers).