hermes-skills/skills/devops/hermes-backup/references/hermes-config-discipline.md

Hermes Configuration Discipline

Do not modify Hermes config.yaml by adding keys you guessed or assumed existed. Always verify before applying.

The Rule

You must verify every config key exists in official Hermes documentation before adding it to config.yaml.

Hermes config keys are not arbitrary YAML — they are read by specific code paths in the Hermes runtime. A made-up key is silently ignored, not validated, and leaves you thinking a feature was configured when it wasn't.

Verification Sources (in priority order)

1. The hermes config CLI — hermes config set KEY VAL validates the key path before applying. If hermes config set accepts it, it's a real key.
2. The official docs — https://hermes-agent.nousresearch.com/docs/user-guide/configuration
3. The hermes-agent skill — loaded with skill_view(name='hermes-agent'), it documents known config sections.
4. The source code — hermes_cli/config.py contains DEFAULT_CONFIG which enumerates every recognized top-level key.
5. The internal help — hermes config --help, hermes config check, hermes config show

What NOT to do

• Do not assume patterns from other tools carry over. Just because some other tool uses fallback_providers doesn't mean Hermes reads them.
• Do not write a key + value into config.yaml that you haven't seen in the docs, the skill, or the source. Writing and testing is not the right order — verify first, then write.
• Do not patch config.yaml by hand with arbitrary YAML when hermes config set exists. The CLI is the safe path. Use it.

What config changes look like for Hermes

If the user wants automatic fallback to a local model, verify the installed Hermes schema first. Current Hermes uses model.fallbacks for the main agent and delegation.fallback for child agents. Do not substitute guessed names such as fallback_providers, fallback_chain, or fallback_order.

Example shape (verify against the installed version before applying):

model:
  fallbacks: '[{"model":"llama3.2:3b","provider":"ollama-local"}]'

delegation:
  fallback: '[{"model":"llama3.2:3b","provider":"ollama-local"}]'

providers:
  ollama-local:
    base_url: http://localhost:11434/v1

Verify a custom OpenAI-compatible provider

A provider is active only if it is represented in current config.yaml under providers or the active model block. A stale auth.json record containing only a label, URL, status, or secret fingerprint is metadata -- it does not prove the credential still exists or that Hermes can use it.

1. Parse config.yaml; inspect model, providers, delegation, and auxiliary without printing secrets.
2. Check .env for the expected named variable; report only presence and length.
3. Treat auth.json fingerprints as clues, not usable credentials.
4. Call <base_url>/models with the actual credential and verify the requested model ID appears.
5. Send a minimal chat completion using that exact model.
6. Only after both calls succeed report the provider and model as functional.

Verify Ollama as a fallback

1. Confirm the binary, service, and listener. Keep it local-only unless remote access was explicitly requested.
2. Pull the exact configured model.
3. Verify both /api/tags and OpenAI-compatible /v1/models list it.
4. Send a deterministic /v1/chat/completions probe and verify returned content.
5. Confirm model.fallbacks and, when required, delegation.fallback reference the same provider/model.

Installing a model is not complete until inference succeeds. A configured provider with an empty model list is not operational.

Config change workflow

User request → check docs/skill/source for real key →
  if EXISTS → use `hermes config set` or edit via `hermes config edit`
  if NOT FOUND → tell user it doesn't exist, suggest alternatives

When the user corrects you

If the user calls out a made-up config key:

• Acknowledge immediately — don't deflect
• Remove the invalid key from config.yaml via the proper CLI or a direct edit
• Document the lesson

Known missing features (as of 2026-07-05)

User wants	Hermes has	Workaround
Automatic provider failover	fallback_providers does NOT exist	Manual provider switch via CLI, or local ollama for maintenance tasks
Multiple fallback providers	Not supported	N/A
Provider priority list	Not supported	N/A

Web tools use_gateway pitfall

Hermes has two config knobs for web tools:

web:
  backend: firecrawl        # Which web backend to use
  use_gateway: false         # true = route through Nous Portal gateway

The trap: When web.use_gateway: true (the default or a previously-set value), Hermes routes Firecrawl requests through Nous Portal's gateway — it ignores your FIRECRAWL_API_KEY from .env entirely. If you're not logged into Nous Portal (no OAuth session), web_search and web_extract fail with:

"Web tools are not configured. Set FIRECRAWL_API_KEY for cloud Firecrawl..."

Even though the key IS set and valid. The fix is:

hermes config set web.use_gateway false

Then a new session (/reset) picks up the change. Note: /reset itself does NOT fix this — the problem is the config value, not the session state. Multiple resets without changing the config value will all fail the same way.

Verification: Test the key directly against Firecrawl's API before and after:

source ~/.hermes/.env 2>/dev/null
curl -s -X POST "https://api.firecrawl.dev/v1/search" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"test","limit":1}'
# Expected: HTTP 200, {"success": true, "data": [...]}

Key learning: web.use_gateway: true is NOT a fallback or override layer — it replaces the local key. If you're self-hosting the Firecrawl key in .env, this must be false. Setting it back to true after switching to Nous Portal OAuth would be correct for that auth mode.

Debugging flow for "web tools not configured"

1. Check .env:  grep FIRECRAWL_API_KEY ~/.hermes/.env
   → If missing, add key. If present, proceed.
2. Check config: grep -A2 '^web:' ~/.hermes/config.yaml
   → If use_gateway: true, flip to false via:
       hermes config set web.use_gateway false
   → Then /reset or start new session.
3. Test key: direct curl to api.firecrawl.dev (see above)
   → 200 = key valid. Non-200 = key expired/wrong.
4. Verify tools: try web_search or web_extract