#1502: tracking: sunset LMSTUDIO_API_KEY env-var legacy alias (introduced in #1501, target removal ~Nov 2026)

Summary

Tracking the eventual removal of the LMSTUDIO_API_KEY legacy alias added in PR #1501 (#1499 + #1500).

After #1501 ships:

• Canonical env var for LM Studio is LM_API_KEY (matches hermes_cli/auth.py:lmstudio.api_key_env_vars)
• Legacy alias LMSTUDIO_API_KEY is preserved as a read-only fallback in two places:
  • api/onboarding.py:_SUPPORTED_PROVIDER_SETUPS["lmstudio"]["env_var_aliases"]
  • api/providers.py:_PROVIDER_ENV_VAR_ALIASES["lmstudio"]
• Onboarding only writes the canonical name going forward
• Detection (Settings → Providers + onboarding readiness) reads canonical first, then aliases

The alias mechanism prevents an upgrade cliff for existing users with LMSTUDIO_API_KEY in .env. But it also means we carry a small amount of dead code forever unless we sunset it.

Sunset criteria

Drop the alias when all of the following are true:

1. Time: at least 6 months since #1501 shipped (gives users multiple release cycles to upgrade)
2. No new bug reports referencing LMSTUDIO_API_KEY in either issue tracker or Discord for the prior 90 days
3. Documentation: the upgrade-path note in #1501's release notes has been live for at least 3 releases

When all three hit, file a small PR that:

• Removes the env_var_aliases entry from _SUPPORTED_PROVIDER_SETUPS["lmstudio"]
• Removes the _PROVIDER_ENV_VAR_ALIASES["lmstudio"] entry
• Removes the alias-fallback branches in _provider_api_key_present (api/onboarding.py) and _provider_has_key (api/providers.py) — but keeps the _PROVIDER_ENV_VAR_ALIASES dict shape so future env-var renames can use the same mechanism
• Updates the regression tests in tests/test_issue1500_lmstudio_env_var_alignment.py to remove the legacy-detection assertions (or flip them to "legacy is no longer detected")
• Adds a release-note entry: "Removed legacy LMSTUDIO_API_KEY env-var detection. Users still on the old name should rename it to LM_API_KEY in ~/.hermes/.env."

Why not just leave it forever?

Leaving the alias in place is also defensible — it's ~10 LOC of dead code with a clear comment explaining why. But there are two costs:

1. Cognitive load: every future engineer touching the env-var detection path has to understand why there's a fallback dict. The comment is good, but the next person renaming a different env var has a tempting precedent ("just add it to aliases too") that may not be necessary if they're starting fresh.
2. Misleading detection: a user with LMSTUDIO_API_KEY in .env after rename-cliff sees Settings reporting has_key=True even though the agent runtime won't pick it up. The PR description acknowledges this; an explicit drop date forces us to revisit and either (a) actually rewrite their .env at upgrade time, (b) emit a deprecation log warning before silent drop, or (c) just drop and accept the has_key=True / chat-fails mismatch is fine because they need to rename anyway.

Priority

Low. The alias is safe and useful for the next several months. File this so it doesn't get forgotten — typical follow-up cadence in the WebUI repo is 6-12 months for cleanup-class issues.

Related

• PR #1501 (introduced the alias)
• Issue #1500 (motivated the env-var alignment)
• references/reviewer-flagged-fix-in-release-not-followup.md (skill that captures when to land vs. defer reviewer-flagged items)

When to schedule

Re-evaluate around November 2026 — far enough out that #1501 has had multiple release cycles to roll through user installs, recent enough to still be tracked.