Feature: self-hosted provider setup (Ollama / LM Studio) in Settings → Providers after onboarding

[pamnard]

Problem

Hermes Agent supports local Ollama/LM Studio (and other OpenAI-compatible servers), but after first-run onboarding the WebUI has no obvious way to add or reconfigure them.

Today:

• Onboarding wizard supports Ollama, LM Studio, and Custom OpenAI-compatible under Open / self-hosted (api/onboarding.py::_SUPPORTED_PROVIDER_SETUPS, static/onboarding.js).
• Settings → Providers only renders providers with API-key env vars (configurable = pid in _PROVIDER_ENV_VAR in api/providers.py).
• Local Ollama is deliberately omitted from _PROVIDER_ENV_VAR because it is keyless by default (bug(providers): Ollama (local) shows 'API key configured' when only Ollama Cloud key is set — both providers share OLLAMA_API_KEY in _PROVIDER_ENV_VAR #1410 — avoids colliding with Ollama Cloud / OLLAMA_API_KEY).

Result for common installs:

1. User completes onboarding with a cloud provider (or configures via hermes model / CLI and gets onboarding_completed: true).
2. Wizard never shows again (static/boot.js: onboarding_completed ? Promise.resolve(false) : loadOnboardingWizard()).
3. Settings → Providers shows API-key providers only — no Ollama card, no base URL editor, no probe/Test button.
4. User assumes WebUI cannot connect to local Ollama, even though Hermes CLI can.

This is especially confusing for CLI-first users (Yandex/custom providers not in the onboarding catalog) who never saw the self-hosted wizard step.

Expected behavior

Post-onboarding, operators should be able to configure self-hosted inference from the WebUI without editing config.yaml or rerunning the full wizard.

Minimum viable UX (reuse existing backend):

• Add a Self-hosted section in Settings → Providers for:
  • ollama (local)
  • lmstudio
  • custom OpenAI-compatible
• Reuse existing onboarding primitives:
  • Base URL field + optional API key (respect key_optional)
  • POST /api/onboarding/probe (or a providers-scoped alias) to list models from <base_url>/models
  • Persist via the same config/env write path as onboarding (apply_onboarding_setup logic), without requiring onboarding_completed=false
• After save: invalidate model cache + refresh model picker (same as provider key add/remove — see bug(providers): removed provider still appears in model dropdowns until server restart #1539 pattern)

Non-goals (for this request)

• Replacing hermes model CLI
• Changing Ollama Cloud env-var collision rules (bug(providers): Ollama (local) shows 'API key configured' when only Ollama Cloud key is set — both providers share OLLAMA_API_KEY in _PROVIDER_ENV_VAR #1410) — local Ollama should remain keyless-by-default
• Docker host networking docs (already covered in docs/onboarding.md / docs/docker.md)

Acceptance criteria

• With onboarding_completed: true, user can add/configure local Ollama from Settings → Providers
• Base URL probe works and populates model choices (or free-text model for custom)
• Saved config makes models appear in composer model picker without server restart
• Existing release-channel onboarding flow unchanged
• Regression tests for: configure local Ollama post-onboarding; Ollama Cloud card still independent of local Ollama (bug(providers): Ollama (local) shows 'API key configured' when only Ollama Cloud key is set — both providers share OLLAMA_API_KEY in _PROVIDER_ENV_VAR #1410)

References

• Onboarding catalog: api/onboarding.py (ollama, lmstudio, custom)
• Providers panel filter: static/panels.js::loadProvidersPanel() (configurable || is_oauth || is_custom)
• Local Ollama omitted from env-var map: api/providers.py::_PROVIDER_ENV_VAR comment at ~653
• Probe endpoint: POST /api/onboarding/probe (bug(onboarding): wizard never probes <base_url>/v1/models — accepts unreachable endpoints silently and persists empty model list #1499)
• Related broader parity issue: Clarify and harden Provider/Model source-of-truth across WebUI, CLI, and Gateway #1240

Reporter context

Observed on a local bootstrap install where Hermes Agent was configured via CLI (Yandex provider). WebUI worked, but there was no visible Ollama setup path after onboarding except resetting onboarding_completed or using the terminal.

[NeilSCGH]

Hello,

This is a very relevant proposal. I was stuck because I missed the onboarding phase, and there is no way in the UI to add a local Ollama instance once onboarding_completed is set to true.

Just a quick tutorial/walkaround to add ollama using the CLI:

1. Open the cli inside your hermes-agent terminal
2. Type hermes model
3. Select `Custom endpoint (enter URL manally)
4. Write the url of your ollama instance, for example http://ip:11434/v1
5. Select the model and follow the remaining simple questions

[nesquena-hermes]

Confirmed the gap, and thanks for the precise code citations — they make this easy to act on.

The onboarding wizard supports Ollama / LM Studio / Custom OpenAI-compatible under Open / self-hosted (api/onboarding.py::_SUPPORTED_PROVIDER_SETUPS, static/onboarding.js), but Settings → Providers only renders providers with API-key env vars (configurable = pid in _PROVIDER_ENV_VAR in api/providers.py). Local Ollama is deliberately omitted from _PROVIDER_ENV_VAR because it's keyless by default (#1410, to avoid colliding with Ollama Cloud / OLLAMA_API_KEY). So once onboarding completes, a user who configured a cloud provider has no obvious in-app path to add or reconfigure a keyless local server.

Tracking under Power user features. The likely fix shape is a dedicated "Local / self-hosted" section in Settings → Providers that mirrors the onboarding _SUPPORTED_PROVIDER_SETUPS entries (base-URL + optional key) instead of gating purely on env-var presence — so keyless providers are first-class in the post-onboarding settings, not just the wizard.

[theherrovn-sys]

I'd like to work on this. I have Ollama running locally with 15 models for testing. The fix involves: 1) Adding keyless provider support in api/providers.py 2) UI in Settings → Providers for Ollama/LM Studio endpoint configuration. Can deliver within 24 hours.

[nesquena-hermes]

Two open PRs now target this — worth coordinating before either merges

Heads-up for contributors and whoever triages this: there are now two open PRs implementing the same feature, with overlapping but not identical scope. I read both diffs against master.

#3404 (@theherrovn-sys) — narrower. Marks key_optional providers as configurable/keyless in get_providers(), adds an endpoint-URL field, and a POST /api/providers/base-url that writes only model.base_url:

if base_url is not None:
    model_cfg["base_url"] = base_url
else:
    model_cfg.pop("base_url", None)
cfg["model"] = model_cfg

It does not switch the active provider or set model.default, so saving an Ollama endpoint configures the URL but doesn't make Ollama the routed provider.

#3406 (@pamnard, issue author) — fuller. POST /api/providers/self-hosted → apply_self_hosted_provider_setup() writes model.provider, model.default, and model.base_url, reloads hermes_cli config, invalidates the models cache, and ships a regression test (tests/test_issue3260_self_hosted_providers_settings.py) that also guards the local-Ollama vs OLLAMA_API_KEY independence from #1410:

model_cfg["provider"] = provider
model_cfg["default"] = _normalize_model_for_provider(provider, model)
if provider_meta.get("requires_base_url"):
    model_cfg["base_url"] = base_url

That's the "actually switch to this self-hosted provider" operation, closer to what the issue asks for.

The shared constraint both inherit

Both write to a single global cfg["model"]["base_url"]. #3404 self-documents this as a follow-up risk, and it applies equally to #3406: there is exactly one model.base_url slot in config.yaml, so a user can't keep both an Ollama endpoint and an LM Studio endpoint configured at once — saving one overwrites the other. The clean fix is per-provider storage (e.g. custom_providers[].base_url, which resolve_model_provider in api/config.py:1673 already routes through for named custom endpoints), but that's a larger change than either PR makes.

Recommendation

These will conflict in api/providers.py, api/routes.py, and static/panels.js — they touch the same functions and add parallel POST endpoints with different paths (/api/providers/base-url vs /api/providers/self-hosted). Probably worth picking one as the base. #3406 is the more complete implementation and has the regression coverage; #3404's keyless-rendering changes to get_providers() and the endpoint-field UI in _buildProviderCard() are a clean subset that could fold in. Flagging so two contributors don't both land overlapping endpoints.

[pamnard]

Thanks for the triage write-up — agreed.

#3406 as the base: that PR switches model.provider, model.default, and model.base_url (plus cache reload), which matches this issue’s “configure local Ollama after onboarding and actually use it” goal. Happy to coordinate with #3404 so we don’t land overlapping endpoints.

Known limitation (MVP): both approaches share a single global model.base_url in config.yaml, so only one self-hosted endpoint is “active” at a time. Fine for this issue; per-provider base URLs would be a sensible follow-up if we want Ollama + LM Studio configured side by side without overwriting.

Ready for review on #3406 when convenient.

[theherrovn-sys]

Thanks for the thorough review on #3260, and for landing on #3406 as the base — I agree it's the stronger foundation. Its handling of the settings flow is cleaner than what I had in #3404, and I'd rather build on that than relitigate it.

That said, I think there's a gap we can close together. #3406 wires up the keyless providers well, but the provider model and discovery path are still fairly coupled to specific endpoints. I'd like to propose layering a small abstraction on top:

• A provider schema with auth_mode and configurable flags, so Ollama, LM Studio, and custom OpenAI-compatible endpoints share one code path instead of special-casing each.
• A thin adapter interface (test_connection, list_models, chat) so chat execution resolves base_url/default_model from config at request time — no hardcoded URLs.
• Model discovery with TTL caching, manual refresh, and a manual-entry fallback.

The win is mostly in maintainability: adding a future provider becomes config + one adapter, rather than touching the chat path.

Happy to rebase #3404 onto #3406 and bring these in incrementally, smallest diffs first, so it's easy to review.

[pamnard]

Thanks for the thoughtful follow-up — that sounds good to me.

I'm happy for #3406 to land as the MVP so we unblock the "configure local Ollama/LM Studio after onboarding and actually use it" flow.

Your proposed layering (provider schema + small adapter interface + better model discovery) makes sense as a follow-up, and I'd prefer to see that come in as a set of small, focused PRs on top of #3406 rather than reshaping this one.

Once #3406 is merged, I'm glad to coordinate on the adapter work so we keep diffs tight and avoid stepping on each other.