hermes-skills/skills/devops/infrastructure-automation/references/config-verification.md

Verification Rules for Infrastructure Changes

Never invent config keys

If you're about to set a configuration value, confirm the key actually exists in the software first.

Bad pattern:

fallback_providers:
  - provider: ollama-local
    model: qwen2.5:7b

Hermes has no fallback_providers key. This silently did nothing. The user rightfully called this out.

Right pattern:

1. Check the software's docs or --help for the config option
2. If docs are offline, check the source code
3. If you can't confirm it exists, ask the user or use a different approach
4. A config key that does nothing is worse than no config change at all — it gives false confidence

Verify before reporting success

Every "should work" assertion that turned out wrong erodes trust. Apply the same bar to config changes that you do to terminal commands:

• Before: "I set fallback_providers, now Hermes will auto-fail over to the local model"
• After writing the config, check: does the software even have a fallback_providers key?
• After: "do not invent config keys without verifying" — direct user correction

Key verification for copy-paste operations

When copying an API key from one config file to another:

1. Read both files as raw bytes/hex
2. Confirm the destination key is byte-identical to the source key
3. The display layer may redact keys with ... — the raw file contains the real key. Don't copy the displayed version.
4. Use repr() or hex dump to compare, not visual inspection of the truncated display

Gateway restart in single-process environments

When Hermes runs as a single systemd service (gateway mode), you cannot restart it from within itself. Use these workarounds:

# Via busctl (works without spawning a second process)
XDG_RUNTIME_DIR=/run/user/0 busctl call --user org.freedesktop.systemd1 \
  /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager \
  RestartUnit 'ss' '<service>.service' 'replace'

# For profile-specific gateways (e.g., Anita profile):
KY_PROFILE=anita
service_name="hermes-gateway-$KY_PROFILE"
XDG_RUNTIME_DIR=/run/user/0 busctl call --user org.freedesktop.systemd1 \
  /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager \
  StartUnit 'ss' "$service_name.service" 'replace'