hermes - 💡(How to fix) Fix Bug: interactive CLI can create a fresh ~/.hermes and diverge from managed runtime state when shared HERMES_HOME/container bridge is missing [1 participants]

Summary

In a managed/containerized deployment, running hermes interactively can create a fresh local ~/.hermes/ with template config/env files while the real gateway/tool runtime continues using a different backend/state root. From the user's perspective this looks like Hermes has "two backends":

• integrated runtime: live cron jobs, messaging, MCP/auth state
• interactive CLI: empty/fresh profile with 0 jobs and template .env

This is extremely confusing and can lead users (or the agent) to install a second local CLI/profile that silently diverges.

What happened

Observed symptoms:

• integrated runtime had live cron jobs and working tool integrations
• interactive CLI reported:
  • Jobs: 0
  • no auth.json
  • no state.db
  • no messaging config
• ~/.hermes/.env visible to the interactive CLI was a newly created template file, not the configured env file the user expected
• install script behavior confirmed the template .env was only created because the CLI believed this Hermes home was new

Important diagnostic evidence

• Docs already hint at this exact footgun:
  • website/docs/getting-started/nix-setup.md
  • line explaining that without addToSystemPackages = true, running hermes in your shell creates a separate ~/.hermes/ directory
• In the affected environment, the local CLI and the integrated runtime clearly did not share the same state root
• A cron-based runtime diagnostic observed /root/.hermes with only cache/ and skills/ visible from that execution context, while the cronjob tool still listed live jobs from the integrated runtime

Why this is a problem

This is more than a docs issue:

1. The failure mode is silent
2. The user can end up with a second, apparently valid Hermes install
3. The CLI may show a template .env, which makes it look like secrets/config were lost
4. Agent/tool debugging becomes misleading because the interactive CLI and tool runtime disagree about the world

Expected behavior

When Hermes is installed in a managed/containerized deployment, interactive CLI invocation should do one of the following:

1. transparently route to the managed runtime/backend, or
2. fail loudly with a clear message like:
   • managed runtime detected
   • this shell is not attached to the shared Hermes state
   • do not create a new local ~/.hermes
   • enable the documented bridge (addToSystemPackages, container.hostUsers, shared HERMES_HOME, etc.)

It should not silently bootstrap a fresh local home that diverges from the real runtime.

Proposed fixes

At least one of these should happen:

• container/managed install should write enough metadata for host-side CLI detection even in partial/bridged environments
• hermes should detect when it is about to create a fresh local ~/.hermes while a managed runtime likely exists and warn/refuse
• installer should warn when creating a template .env in a likely split-state environment
• docs should include a stronger troubleshooting section for “CLI sees empty ~/.hermes but gateway has live state”

Platform / environment

• containerized runtime
• interactive shell saw /root/.hermes
• integrated runtime had live cron/tool state not visible to the local CLI

User impact

High confusion / split-brain state. It makes the product feel broken and can trigger unnecessary reinstalls, secret re-entry, and incorrect debugging.