Credential Pools

Credential Pools 문서는 Hermes Agent 공식 문서(user-guide/features/credential-pools)를 한국어로 정리한 가이드입니다. Pool multiple API keys or OAuth tokens per provider for automatic rotation and rate limit recovery. 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치 버전과 공식 원문을 확인하세요.

핵심 요약

Pool multiple API keys or OAuth tokens per provider for automatic rotation and rate limit recovery.

한국어 가이드 범위: user-guide/features/credential-pools 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Credential Pools
동작 방식
빠른 시작
Add a second OpenRouter key
Add a second Anthropic key
Add an Anthropic OAuth credential (requires Claude Max plan + extra usage credits)
Opens browser for OAuth login
Interactive Management
CLI Commands
Rotation Strategies
Error Recovery
Custom Endpoint Pools
After setting up a custom endpoint via hermes model:
Shows:
Together.ai (1 credential):
#1 config key api_key config:Together.ai ←
Add a second key for the same endpoint:
Auto-Discovery
Delegation & Subagent Sharing
Thread Safety
아키텍처
Storage

상세 내용

Credential Pools

Credential pools let you register multiple API keys or OAuth tokens for the same provider. When one key hits a rate limit or billing quota, Hermes automatically rotates to the next healthy key — keeping your session alive without switching providers.

동작 방식

Your request
  → Pick key from pool (round_robin / least_used / fill_first / random)
  → Send to provider
  → 429 rate limit?
      → Plan/usage limit reached (e.g. ChatGPT/Codex "usage limit reached")?
          → Rotate to next pool key immediately (no retry — the cap won't clear on retry)
      → Generic / transient 429?
          → Retry same key once (transient blip)
          → Second 429 → rotate to next pool key
      → All keys exhausted → fallback_model (different provider)
  → 402 billing error?
      → Immediately rotate to next pool key (24h cooldown)
  → 401 auth expired?
      → Try refreshing the token (OAuth)
      → Refresh failed → rotate to next pool key
  → Success → continue normally

빠른 시작

If you already have an API key set in .env, Hermes auto-discovers it as a 1-key pool. To benefit from pooling, add more keys:

Add a second OpenRouter key

hermes auth add openrouter --api-key sk-or-v1-your-second-key

Add a second Anthropic key

hermes auth add anthropic --type api-key --api-key sk-ant-api03-your-second-key

Add an Anthropic OAuth credential (requires Claude Max plan + extra usage credits)

hermes auth add anthropic --type oauth

openrouter (2 credentials): #1 OPENROUTER_API_KEY api_key env:OPENROUTER_API_KEY ← #2 backup-key api_key manual

Check your pools:

Output:

Interactive Management

Run hermes auth with no subcommand for an interactive wizard:

hermes auth

What would you like to do?
  1. Add a credential
  2. Remove a credential
  3. Reset cooldowns for a provider
  4. Set rotation strategy for a provider
  5. Exit

anthropic supports both API keys and OAuth login.
  1. API key (paste a key from the provider dashboard)
  2. OAuth login (authenticate via browser)
Type [1/2]:

CLI Commands

Command	Description
`hermes auth`	Interactive pool management wizard
`hermes auth list`	Show all pools and credentials
`hermes auth list <provider>`	Show a specific provider's pool
`hermes auth add <provider>`	Add a credential (prompts for type and key)
`hermes auth add <provider> --type api-key --api-key <key>`	Add an API key non-interactively
`hermes auth add <provider> --type oauth`	Add an OAuth credential via browser login
`hermes auth remove <provider> <index>`	Remove credential by 1-based index
`hermes auth reset <provider>`	Clear all cooldowns/exhaustion status

Rotation Strategies

Configure via hermes auth → "Set rotation strategy" or in config.yaml:

Strategy	Behavior
`fill_first` (default)	Use the first healthy key until it's exhausted, then move to the next
`round_robin`	Cycle through keys evenly, rotating after each selection
`least_used`	Always pick the key with the lowest request count
`random`	Random selection among healthy keys

credential_pool_strategies:
  openrouter: round_robin
  anthropic: least_used

Error Recovery

The pool handles different errors differently:

Error	Behavior	Cooldown
429 Rate Limit	Retry same key once (transient). Second consecutive 429 rotates to next key	1 hour
402 Billing/Quota	Immediately rotate to next key	24 hours
401 Auth Expired	Try refreshing the OAuth token first. Rotate only if refresh fails	—
All keys exhausted	Fall through to `fallback_model` if configured	—

Custom Endpoint Pools

Custom OpenAI-compatible endpoints (Together.ai, RunPod, local servers) get their own pools, keyed by the endpoint name from custom_providers in config.yaml.

After setting up a custom endpoint via hermes model:

hermes auth list

Shows:

이 섹션의 세부 항목은 공식 문서 Shows:를 참고하세요.

Together.ai (1 credential):

이 섹션의 세부 항목은 공식 문서 Together.ai (1 credential):를 참고하세요.

#1 config key api_key config:Together.ai ←

이 섹션의 세부 항목은 공식 문서 #1 config key api_key config:Together.ai ←를 참고하세요.

Add a second key for the same endpoint:

hermes auth add Together.ai --api-key sk-together-second-key json { "credential_pool": { "openrouter": [...], "custom:together.ai": [...] } } ```

Custom endpoint pools are stored in `auth.json` under `credential_pool` with a `custom:` prefix:

Auto-Discovery

Hermes automatically discovers credentials from multiple sources and seeds the pool on startup:

Source	Example	Auto-seeded?
Environment variables	`OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`	Yes
OAuth tokens (auth.json)	Codex device code, Nous device code	Yes
Claude Code credentials	`~/.claude/.credentials.json`	Yes (Anthropic)
Hermes PKCE OAuth	`~/.hermes/auth.json`	Yes (Anthropic)
Custom endpoint config	`model.api_key` in config.yaml	Yes (custom endpoints)
Manual entries	Added via `hermes auth add`	Persisted in auth.json

When the agent spawns subagents via delegate_task, the parent's credential pool is automatically shared with children:

주요 항목:

Same provider — the child receives the parent's full pool, enabling key rotation on rate limits
Different provider — the child loads that provider's own pool (if configured)
No pool configured — the child falls back to the inherited single API key

Thread Safety

The credential pool uses a threading lock for all state mutations (select(), mark_exhausted_and_rotate(), try_refresh_current(), mark_used()). This ensures safe concurrent access when the gateway handles multiple chat sessions simultaneously.

아키텍처

For the full data flow diagram, see docs/credential-pool-flow.excalidraw in the repository.

Storage

Pool state is stored in ~/.hermes/auth.json under the credential_pool key:

{
  "version": 1,
  "credential_pool": {
    "openrouter": [
      {
        "id": "abc123",
        "label": "OPENROUTER_API_KEY",
        "auth_type": "api_key",
        "priority": 0,
        "source": "env:OPENROUTER_API_KEY",
        "secret_source": "bitwarden",
        "secret_fingerprint": "sha256:12ab34cd56ef7890",
        "last_status": "ok",
        "request_count": 142
      }
    ],
    "anthropic": [
      {
        "id": "manual1",
        "label": "personal-api-key",
        "auth_type": "api_key",
        "priority": 0,
        "source": "manual",
        "access_token": "sk-ant-api03-..."
      }
    ]
  }
}

credential_pool_strategies:
  openrouter: round_robin
  anthropic: least_used

실습 체크리스트

공식 문서와 설치된 Hermes 버전을 대조합니다.
관련 CLI는 hermes --help 및 하위 명령 --help로 확인합니다.
Gateway·메시징 변경 후 hermes gateway 재시작을 검토합니다.
시크릿·토큰은 환경 변수/시크릿 매니저에만 둡니다.

자주 쓰는 명령·설정 예시

Your request
  → Pick key from pool (round_robin / least_used / fill_first / random)
  → Send to provider
  → 429 rate limit?
      → Plan/usage limit reached (e.g. ChatGPT/Codex "usage limit reached")?
          → Rotate to next pool key immediately (no retry — the cap won't clear on retry)
      → Generic / transient 429?
          → Retry same key once (transient blip)
          → Second 429 → rotate to next pool key
      → All keys exhausted → fallback_model (different provider)
  → 402 billing error?
      → Immediately rotate to next pool key (24h cooldown)
  → 401 auth expired?
      → Try refreshing the token (OAuth)
      → Refresh failed → rotate to next pool key
  → Success → continue normally

# Add a second OpenRouter key
hermes auth add openrouter --api-key sk-or-v1-your-second-key

# Add a second Anthropic key
hermes auth add anthropic --type api-key --api-key sk-ant-api03-your-second-key

# Add an Anthropic OAuth credential (requires Claude Max plan + extra usage credits)
hermes auth add anthropic --type oauth
# Opens browser for OAuth login

hermes auth list

openrouter (2 credentials):
  #1  OPENROUTER_API_KEY   api_key env:OPENROUTER_API_KEY ←
  #2  backup-key           api_key manual

anthropic (3 credentials):
  #1  hermes_pkce          oauth   hermes_pkce ←
  #2  claude_code          oauth   claude_code
  #3  ANTHROPIC_API_KEY    api_key env:ANTHROPIC_API_KEY

hermes auth

What would you like to do?
  1. Add a credential
  2. Remove a credential
  3. Reset cooldowns for a provider
  4. Set rotation strategy for a provider
  5. Exit

anthropic supports both API keys and OAuth login.
  1. API key (paste a key from the provider dashboard)
  2. OAuth login (authenticate via browser)
Type [1/2]:

credential_pool_strategies:
  openrouter: round_robin
  anthropic: least_used

Credential Pools

핵심 요약

Pool multiple API keys or OAuth tokens per provider for automatic rotation and rate limit recovery.

한국어 가이드 범위: user-guide/features/credential-pools 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Credential Pools
동작 방식
빠른 시작
Add a second OpenRouter key
Add a second Anthropic key
Add an Anthropic OAuth credential (requires Claude Max plan + extra usage credits)
Opens browser for OAuth login
Interactive Management
CLI Commands
Rotation Strategies
Error Recovery
Custom Endpoint Pools
After setting up a custom endpoint via hermes model:
Shows:
Together.ai (1 credential):
#1 config key api_key config:Together.ai ←
Add a second key for the same endpoint:
Auto-Discovery
Delegation & Subagent Sharing
Thread Safety
아키텍처
Storage

상세 내용

Credential Pools

동작 방식

Your request
  → Pick key from pool (round_robin / least_used / fill_first / random)
  → Send to provider
  → 429 rate limit?
      → Plan/usage limit reached (e.g. ChatGPT/Codex "usage limit reached")?
          → Rotate to next pool key immediately (no retry — the cap won't clear on retry)
      → Generic / transient 429?
          → Retry same key once (transient blip)
          → Second 429 → rotate to next pool key
      → All keys exhausted → fallback_model (different provider)
  → 402 billing error?
      → Immediately rotate to next pool key (24h cooldown)
  → 401 auth expired?
      → Try refreshing the token (OAuth)
      → Refresh failed → rotate to next pool key
  → Success → continue normally

빠른 시작

If you already have an API key set in .env, Hermes auto-discovers it as a 1-key pool. To benefit from pooling, add more keys:

Add a second OpenRouter key

hermes auth add openrouter --api-key sk-or-v1-your-second-key

Add a second Anthropic key

hermes auth add anthropic --type api-key --api-key sk-ant-api03-your-second-key

Add an Anthropic OAuth credential (requires Claude Max plan + extra usage credits)

hermes auth add anthropic --type oauth

openrouter (2 credentials): #1 OPENROUTER_API_KEY api_key env:OPENROUTER_API_KEY ← #2 backup-key api_key manual

Check your pools:

Output:

Interactive Management

Run hermes auth with no subcommand for an interactive wizard:

hermes auth

What would you like to do?
  1. Add a credential
  2. Remove a credential
  3. Reset cooldowns for a provider
  4. Set rotation strategy for a provider
  5. Exit

anthropic supports both API keys and OAuth login.
  1. API key (paste a key from the provider dashboard)
  2. OAuth login (authenticate via browser)
Type [1/2]:

CLI Commands

Command	Description
`hermes auth`	Interactive pool management wizard
`hermes auth list`	Show all pools and credentials
`hermes auth list <provider>`	Show a specific provider's pool
`hermes auth add <provider>`	Add a credential (prompts for type and key)
`hermes auth add <provider> --type api-key --api-key <key>`	Add an API key non-interactively
`hermes auth add <provider> --type oauth`	Add an OAuth credential via browser login
`hermes auth remove <provider> <index>`	Remove credential by 1-based index
`hermes auth reset <provider>`	Clear all cooldowns/exhaustion status

Rotation Strategies

Configure via hermes auth → "Set rotation strategy" or in config.yaml:

Strategy	Behavior
`fill_first` (default)	Use the first healthy key until it's exhausted, then move to the next
`round_robin`	Cycle through keys evenly, rotating after each selection
`least_used`	Always pick the key with the lowest request count
`random`	Random selection among healthy keys

credential_pool_strategies:
  openrouter: round_robin
  anthropic: least_used

Error Recovery

The pool handles different errors differently:

Error	Behavior	Cooldown
429 Rate Limit	Retry same key once (transient). Second consecutive 429 rotates to next key	1 hour
402 Billing/Quota	Immediately rotate to next key	24 hours
401 Auth Expired	Try refreshing the OAuth token first. Rotate only if refresh fails	—
All keys exhausted	Fall through to `fallback_model` if configured	—

Custom Endpoint Pools

Custom OpenAI-compatible endpoints (Together.ai, RunPod, local servers) get their own pools, keyed by the endpoint name from custom_providers in config.yaml.

After setting up a custom endpoint via hermes model:

hermes auth list

Shows:

이 섹션의 세부 항목은 공식 문서 Shows:를 참고하세요.

Together.ai (1 credential):

이 섹션의 세부 항목은 공식 문서 Together.ai (1 credential):를 참고하세요.

#1 config key api_key config:Together.ai ←

이 섹션의 세부 항목은 공식 문서 #1 config key api_key config:Together.ai ←를 참고하세요.

Add a second key for the same endpoint:

hermes auth add Together.ai --api-key sk-together-second-key json { "credential_pool": { "openrouter": [...], "custom:together.ai": [...] } } ```

Custom endpoint pools are stored in `auth.json` under `credential_pool` with a `custom:` prefix:

Auto-Discovery

Hermes automatically discovers credentials from multiple sources and seeds the pool on startup:

Source	Example	Auto-seeded?
Environment variables	`OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`	Yes
OAuth tokens (auth.json)	Codex device code, Nous device code	Yes
Claude Code credentials	`~/.claude/.credentials.json`	Yes (Anthropic)
Hermes PKCE OAuth	`~/.hermes/auth.json`	Yes (Anthropic)
Custom endpoint config	`model.api_key` in config.yaml	Yes (custom endpoints)
Manual entries	Added via `hermes auth add`	Persisted in auth.json

When the agent spawns subagents via delegate_task, the parent's credential pool is automatically shared with children:

주요 항목:

Same provider — the child receives the parent's full pool, enabling key rotation on rate limits
Different provider — the child loads that provider's own pool (if configured)
No pool configured — the child falls back to the inherited single API key

Thread Safety

아키텍처

For the full data flow diagram, see docs/credential-pool-flow.excalidraw in the repository.

Storage

Pool state is stored in ~/.hermes/auth.json under the credential_pool key:

{
  "version": 1,
  "credential_pool": {
    "openrouter": [
      {
        "id": "abc123",
        "label": "OPENROUTER_API_KEY",
        "auth_type": "api_key",
        "priority": 0,
        "source": "env:OPENROUTER_API_KEY",
        "secret_source": "bitwarden",
        "secret_fingerprint": "sha256:12ab34cd56ef7890",
        "last_status": "ok",
        "request_count": 142
      }
    ],
    "anthropic": [
      {
        "id": "manual1",
        "label": "personal-api-key",
        "auth_type": "api_key",
        "priority": 0,
        "source": "manual",
        "access_token": "sk-ant-api03-..."
      }
    ]
  }
}

credential_pool_strategies:
  openrouter: round_robin
  anthropic: least_used

실습 체크리스트

공식 문서와 설치된 Hermes 버전을 대조합니다.
관련 CLI는 hermes --help 및 하위 명령 --help로 확인합니다.
Gateway·메시징 변경 후 hermes gateway 재시작을 검토합니다.
시크릿·토큰은 환경 변수/시크릿 매니저에만 둡니다.

자주 쓰는 명령·설정 예시

Your request
  → Pick key from pool (round_robin / least_used / fill_first / random)
  → Send to provider
  → 429 rate limit?
      → Plan/usage limit reached (e.g. ChatGPT/Codex "usage limit reached")?
          → Rotate to next pool key immediately (no retry — the cap won't clear on retry)
      → Generic / transient 429?
          → Retry same key once (transient blip)
          → Second 429 → rotate to next pool key
      → All keys exhausted → fallback_model (different provider)
  → 402 billing error?
      → Immediately rotate to next pool key (24h cooldown)
  → 401 auth expired?
      → Try refreshing the token (OAuth)
      → Refresh failed → rotate to next pool key
  → Success → continue normally

# Add a second OpenRouter key
hermes auth add openrouter --api-key sk-or-v1-your-second-key

# Add a second Anthropic key
hermes auth add anthropic --type api-key --api-key sk-ant-api03-your-second-key

# Add an Anthropic OAuth credential (requires Claude Max plan + extra usage credits)
hermes auth add anthropic --type oauth
# Opens browser for OAuth login

hermes auth list

openrouter (2 credentials):
  #1  OPENROUTER_API_KEY   api_key env:OPENROUTER_API_KEY ←
  #2  backup-key           api_key manual

anthropic (3 credentials):
  #1  hermes_pkce          oauth   hermes_pkce ←
  #2  claude_code          oauth   claude_code
  #3  ANTHROPIC_API_KEY    api_key env:ANTHROPIC_API_KEY

hermes auth

What would you like to do?
  1. Add a credential
  2. Remove a credential
  3. Reset cooldowns for a provider
  4. Set rotation strategy for a provider
  5. Exit

anthropic supports both API keys and OAuth login.
  1. API key (paste a key from the provider dashboard)
  2. OAuth login (authenticate via browser)
Type [1/2]:

credential_pool_strategies:
  openrouter: round_robin
  anthropic: least_used

Credential Pools

핵심 요약

문서 구성

상세 내용

Credential Pools

동작 방식

빠른 시작

Add a second OpenRouter key

Add a second Anthropic key

Add an Anthropic OAuth credential (requires Claude Max plan + extra usage credits)

Opens browser for OAuth login

Interactive Management

CLI Commands

Rotation Strategies

Error Recovery

Custom Endpoint Pools

After setting up a custom endpoint via hermes model:

Shows:

Together.ai (1 credential):

#1 config key api_key config:Together.ai ←

Add a second key for the same endpoint:

Auto-Discovery

Delegation & Subagent Sharing

Thread Safety

아키텍처

Storage

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Credential Pools

핵심 요약

문서 구성

상세 내용

Credential Pools

동작 방식

빠른 시작

Add a second OpenRouter key

Add a second Anthropic key

Add an Anthropic OAuth credential (requires Claude Max plan + extra usage credits)

Opens browser for OAuth login

Interactive Management

CLI Commands

Rotation Strategies

Error Recovery

Custom Endpoint Pools

After setting up a custom endpoint via hermes model:

Shows:

Together.ai (1 credential):

#1 config key api_key config:Together.ai ←

Add a second key for the same endpoint:

Auto-Discovery

Delegation & Subagent Sharing

Thread Safety

아키텍처

Storage

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드