Bug Report: .env File Silently Stripped During hermes update / Config Migration

Summary

Running hermes update or hermes config migrate silently strips user-added environment variables from ~/.hermes/.env, removing all custom sections (Telegram, DeepSeek, browser settings, terminal overrides, debug flags) and replacing them with a fresh template. Only "standard" sections recognized by the internal template survive. This causes silent loss of critical API keys and platform credentials.

Severity: HIGH — Causes complete loss of messaging platform connectivity (Telegram, Discord, etc.) and API access (search, web extraction, custom providers) until the user manually restores keys from a pre-update snapshot.

Environment

• Hermes commit: 9fb40e6a3 (May 15, 2026)
• OS: Linux 6.8.0-31-generic (Ubuntu)
• Python: 3.11
• Install method: Git clone
• Profiles: Single (default)

Steps to Reproduce

1. Start with a working .env containing custom sections (e.g., Telegram bot token, DeepSeek API key, browser settings, terminal overrides, debug flags)
2. Run hermes update (which triggers config migration)
3. OR run hermes config migrate directly
4. Compare .env before and after

Expected Behavior

.env should be preserved in full — existing keys should never be removed. Migration should only add new missing keys (commented out by default), never delete user-set values.

Actual Behavior

.env is silently rewritten from an internal template, dropping all unrecognized sections. Output:

=== .env Before (May 14 snapshot) ===
473 lines — contains Telegram, DeepSeek, browser, terminal, debug config

=== .env After (May 15 post-update) ===
212 lines — 261 lines GONE (55% of file)

=== What Was Lost ===
BROWSERBASE_ADVANCED_STEALTH
BROWSERBASE_PROXIES
BROWSER_INACTIVITY_TIMEOUT
BROWSER_SESSION_TIMEOUT
DEEPSEEK_API_KEY
IMAGE_TOOLS_DEBUG
MOA_TOOLS_DEBUG
TELEGRAM_ALLOWED_USERS
TELEGRAM_BOT_TOKEN
TELEGRAM_HOME_CHANNEL
TERMINAL_LIFETIME_SECONDS
TERMINAL_MODAL_IMAGE
TERMINAL_TIMEOUT
VISION_TOOLS_DEBUG
WEB_TOOLS_DEBUG

Impact

• All messaging platforms go offline — missing TELEGRAM_BOT_TOKEN causes gateway to start with "No messaging platforms enabled"
• Primary API key lost — DEEPSEEK_API_KEY dropped, LLM calls fail
• Web search breaks — TAVILY_API_KEY, FIRECRAWL_API_KEY stripped
• All cron deliveries silently fail — jobs run but can't deliver to Telegram
• User must manually restore keys from pre-update snapshot (~/.hermes/state-snapshots/)

Workaround

The pre-update snapshot mechanism (~/.hermes/state-snapshots/<timestamp>-pre-update/.env) preserves the original .env, allowing manual recovery. Users should verify .env integrity after every update:

diff ~/.hermes/.env ~/.hermes/state-snapshots/$(ls -t ~/.hermes/state-snapshots/ | head -1)/.env

Suspected Root Cause

The config migration/sanitization flow (hermes_cli/config.py — sanitize_env_file(), _write_env_vars(), and related functions) regenerates .env from a template of known keys. Keys not in the OPTIONAL_ENV_VARS + _EXTRA_ENV_KEYS known-keys set are silently dropped.

Additionally, _sanitize_env_lines() (line 4400) uses known_keys = set(OPTIONAL_ENV_VARS.keys()) | _EXTRA_ENV_KEYS — any key NOT in this set may be treated as a concatenation artifact and split/dropped.

Related

• This appears related to the known issue where "hermes update temporarily blanks API keys during restart" (documented in community discussions)
• Similar reports may exist for config loss during hermes setup wizard runs