Summary

The current self-hosted Honcho flow in Hermes appears inconsistent between docs and implementation.

Hermes docs suggest that self-hosted Honcho can be configured via HONCHO_BASE_URL or ~/.honcho/config.json without an API key. In practice, the current CLI and config resolution behave differently enough that the documented path is misleading.

What I observed

1. hermes honcho setup is still API-key-first

hermes honcho setup prompts for a Honcho API key and exits early if no key is provided. It does not offer a self-hosted base_url path in the wizard.

That makes the wizard a poor fit for self-hosted Honcho instances that do not use API keys.

2. Actual config resolution differs from the docs

Current implementation resolves config in this order:

1. $HERMES_HOME/honcho.json
2. ~/.honcho/config.json
3. environment variables

So instance-local $HERMES_HOME/honcho.json currently takes precedence over the shared global file.

3. Current code uses root-level baseUrl

The current code path appears to resolve self-hosted Honcho from root-level baseUrl or HONCHO_BASE_URL.

In my testing, a working self-hosted config was:

{
  "baseUrl": "http://<honcho-host>:8000",
  "hosts": {
    "hermes": {
      "workspace": "hermes",
      "peerName": "user",
      "aiPeer": "hermes",
      "memoryMode": "hybrid",
      "writeFrequency": "async",
      "recallMode": "hybrid",
      "sessionStrategy": "per-directory",
      "enabled": true
    }
  }
}

This differs from the current docs examples, which imply ~/.honcho/config.json and host-scoped base_url.

4. Env-only self-hosted mode is not surfaced cleanly by CLI checks

An env-only HONCHO_BASE_URL path is enough for Hermes runtime client creation, but hermes honcho status and hermes doctor do not fully treat that as configured unless a config file exists.

Expected behavior

For self-hosted Honcho, Hermes should support a clean, documented path where:

• no API key is required when the local/self-hosted instance is configured without auth
• hermes honcho setup offers a self-hosted base_url flow
• docs and implementation agree on:
  • config file path precedence
  • whether baseUrl is root-level or host-level
  • whether env-only config should be considered fully configured by status and doctor

Suggested fixes

• Add a self-hosted branch to hermes honcho setup
• Align docs with current code, or align code with docs
• Make hermes honcho status and hermes doctor recognize env-only self-hosted Honcho as configured when runtime can actually connect