core-app,web,infra: a hosted-only deployment runs no local runtime — the chart refuses it, the core 500s in it

[baakhoff]

What

A deployment that runs no local runtime at all — hosted chat and hosted embeddings, no Ollama — is something the repo already claims to support (LLM_BOOTSTRAP_MODELS="" is documented as "hosted-only or air-gapped", docs/reference/config.md:88; the bootstrap explicitly tolerates "a hosted-only deployment running no Ollama", docs/services/core-app.md:753). It is not actually supported anywhere else. Three states — in-chart Ollama, external Ollama, no Ollama — are collapsed into two, and the third is treated as a configuration error.

The Helm chart refuses to render it: infra/k8s/epicurus/templates/_helpers.tpl:113-119 requireds ollama.external.url the moment ollama.enabled is false, so helm install fails before the cluster sees anything. The proof this is a gap and not a policy is in our own CI: k8s-smoke disables the chart's Ollama and then applies a fake StatefulSet (infra/ci/ollama-stub.yaml) purely so the container-runtime seam finds a workload to match. We wrote a stub instead of a mode.

Compose cannot express it either: infra/ollama/compose.yaml is an unconditional include: (compose.yaml:13) and core-app hard-depends on the service (services/core-app/compose.yaml:83-84).

And when an operator forces it anyway (a placeholder external URL), the core degrades loudly in three places that should be quiet, and quietly in one that should be loud:

• GET /platform/v1/llm/models 500s. gateway.models() lets the /api/tags failure propagate (services/core-app/src/epicurus_core_app/llm/gateway.py:1115), the route has no guard (services/core-app/src/epicurus_core_app/llm/routes.py:198-203), and no httpx exception handler exists on the app (app.py:1297-1320 covers only GatewayPausedError, PathEscapeError, OSError). The Models page polls it every 10 s (services/web/src/screens/ModelsScreen.tsx:431-438), so the operator gets a 500 every 10 s. POST /llm/pull (routes.py:283) and DELETE /llm/models (routes.py:238) 500 the same way.
• GET /platform/v1/readiness reports the model component "warming" forever (gateway.py:372-396 returns warm=False on failure; readiness.py:67,103). Advisory — it never blocks a turn — but the chat warm-up indicator never completes, on every turn, for the life of the deployment.
• The startup bootstrap spends 180 s polling a runtime that does not exist before giving up (llm/bootstrap.py:138-152), once per process start, unless the operator knows to set LLM_BOOTSTRAP_MODELS="".
• The quiet one: show() failures are caught and return an empty ModelDetails (gateway.py:1254-1258), so model_role degrades to "unknown" and _ensure_can_serve lets the call through (gateway.py:443) to fail at the provider instead of refusing with a reason.

Meanwhile nothing validates that the defaults make sense without a runtime. LLM_DEFAULT_MODEL is llama3.2 and MEMORY_EMBED_MODEL is nomic-embed-text (services/core-app/src/epicurus_core_app/settings.py:27,146; mirrored at infra/k8s/epicurus/values.yaml:133,144), both bare names, and providers.resolve routes a bare name — and any unknown prefix — to the local runtime (llm/providers.py:50-61). So the out-of-the-box hosted-only install is precisely the half-working stack we refuse to ship elsewhere: chat works through the hosted provider the operator configured, and memory recall plus every module index fails at call time against a runtime that isn't there.

Owner directive (2026-09-19): if Ollama is turned off, embeddings must not go through it. They already need not — _embed_config classifies an embedding model through the same provider registry as chat and sends a hosted one straight to the provider with the tenant's key from OpenBao (gateway.py:932-977, #865). The gateway is ready; the deployment surface is not.

As of main @ 43625e5.

Why it happens

epicurus.ollamaUrl was written by copying epicurus.qdrantUrl / epicurus.openbaoUrl (_helpers.tpl:97-111) — components the core genuinely cannot run without, where required is right. Ollama is not one of them, and the helper three lines further down already shows the other shape: epicurus.minioUrl uses default, not required (_helpers.tpl:129-135).

Underneath that, the core has no representation of "there is no local runtime". ollama_url is a plain string with a localhost default (settings.py:20), so absent and unreachable and misconfigured are the same thing to every call site, and each one guesses: some catch and degrade (show, unload, /api/ps), some propagate to a 500 (models, pull, delete), one polls for three minutes (bootstrap). The web mirrors the same ambiguity with two inline warning strings ("The local runtime is unreachable — is the ollama service up?", ModelsScreen.tsx:493-497; ChatScreen.tsx:712-714) while every other local-runtime control — the pull card, the catalog, the KV-cache card, the context-window card, the Local (Ollama) optgroup in the embedding picker (ModelsScreen.tsx:1619-1625) — renders as though a runtime existed.

Fix

Make "no local runtime" a first-class deployment mode, spelled OLLAMA_URL="".

The contract (pre-decided, so the three parts below can be built in parallel):

• CoreAppSettings grows local_runtime_enabled: bool — bool(ollama_url.strip()). Blank means absent, deliberately, not misconfigured.
• New GET /platform/v1/llm/local-runtime → {"state": "absent" | "unreachable" | "ok", "url_configured": bool}. A separate endpoint rather than an envelope around GET /llm/models, which stays a bare list[ModelInfo] (five web consumers and seven internal callers read it; wrapping it is a breaking change bought for nothing).
• GET /llm/models never 500s again: absent → [], unreachable → []. The state is the new endpoint's job.
• POST /llm/pull, DELETE /llm/models, POST /llm/unload, the KV-cache apply: 409 with a detail naming the mode when absent; 502 with a clear detail when unreachable. Never a bare 500.
• _ensure_can_serve refuses a local model id when the runtime is absent, raising the existing ModelCapabilityError shape (ADR-0140, llm/errors.py) → 400 with the hint "no local runtime is configured — choose a hosted model".
• Readiness: the model component reports a n/a state when the runtime is absent, instead of warming forever.
• Bootstrap: absent → one log line and return, no 180 s poll.
• The container-runtime seam (ADR-0134): with no runtime, the Ollama restart arm and the KV-cache apply return their existing "unavailable" result rather than instructing the operator to restart a container that does not exist.

Part 1 — core (core-app MINOR). The contract above, plus: no validator that rejects a bare-name default (a local default with no runtime is now a legible refusal at call time, not a boot failure — a deployment may legitimately point a tenant pref at a hosted model while the env default is stale).

Part 2 — web (web MINOR). The Models page reads the new endpoint and, when the state is absent, collapses the local half into one honest line ("Local AI is not configured on this deployment") — the pull card, the catalog, the KV-cache card and the context-window card go with it; the embedding picker drops its Local (Ollama) optgroup (ModelsScreen.tsx:1619-1625) so the operator cannot choose a model that cannot run; the chat picker's Local heading likewise (ChatScreen.tsx:712-714). unreachable keeps today's warning — that state is an error and should still look like one. This is the rendering half only; the runtime-level Local AI / Hosted AI switch stays #945 (2.0.0) and is not in scope here.

Part 3 — infra (chart MINOR). epicurus.ollamaUrl renders empty when ollama.enabled: false and ollama.external.url is blank (follow minioUrl), and the chart then sets LLM_BOOTSTRAP_MODELS="" unless the operator overrode it. In exchange, add the guard that is actually worth having: fail at render time when there is no local runtime and core.memoryEmbedModel or core.llm.defaultModel is still a bare (local) name — naming the hosted alias to set. That catches the half-working stack; today's guard catches a legitimate one. Compose gets the same capability: profiles: [local-ai] on ollama + ollama-init (the pattern infra/observability/compose.yaml:38 already uses), depends_on: ollama: {condition: service_started, required: false}, and OLLAMA_URL: ${OLLAMA_URL-http://ollama:11434} so blanking the var is how an operator says "no local runtime" on Compose too. infra/ci/ollama-stub.yaml is retired and k8s-smoke gains a hosted-only assertion in its place.

Kubernetes parity: both arms. The chart is half the deliverable (Part 3), the Compose profile is the other half, and the ADR-0134 seam must behave identically on CONTAINER_RUNTIME=docker and =kubernetes when there is no workload to restart.

Tests

• Settings: blank / whitespace / set OLLAMA_URL → local_runtime_enabled false / false / true.
• GET /llm/local-runtime returns each of the three states (absent; a URL whose host refuses; a stubbed runtime that answers /api/tags).
• GET /llm/models returns [] and 200 in both the absent and unreachable states — the regression test for the 10-second 500.
• pull / delete / unload / KV-cache apply → 409 when absent, 502 when unreachable, in place of 500.
• embed() with a hosted embedding model succeeds while the runtime is absent (the owner's directive, pinned); embed() with a bare/local id while absent raises ModelCapabilityError, not a connection error.
• Chat with a hosted model succeeds while absent; a local id refuses with the hint.
• Readiness reports n/a for the model component when absent, and does not report ready=False on that account.
• Bootstrap with an absent runtime returns without polling (assert on elapsed time / no HTTP call), and logs once.
• Container seam: restart-Ollama with no matching workload returns the unavailable result on both the docker and kubernetes arms.
• Web: Models page renders the collapsed local section for absent, the warning for unreachable, and the full local UI for ok; the embedding picker has no local optgroup when absent.
• Chart: helm template with ollama.enabled: false and a blank external.url renders (it does not today) and emits an empty OLLAMA_URL plus LLM_BOOTSTRAP_MODELS=""; the same values with core.memoryEmbedModel: nomic-embed-text fails with the new message; ollama.enabled: false with an external URL still renders that URL.
• Compose: tests/test_compose_ports.py-style static assertion that ollama carries the local-ai profile and core-app's dependency on it is required: false.
• k8s-smoke: a hosted-only boot asserts GET /platform/v1/llm/models returns 200 and /llm/local-runtime reports absent.

Docs

docs/infrastructure/kubernetes.md (a hosted-only section + the ollama.enabled row in the values table, :395), docs/infrastructure/index.md (the Compose local-ai profile), docs/services/core-app.md (the new endpoint, the 409/502 refusals, the readiness n/a state, and the hosted-only paragraph at :753 which currently over-promises), docs/reference/config.md (blank OLLAMA_URL semantics, :88 area), docs/reference/platform-api.md (GET /platform/v1/llm/local-runtime), docs/user/configuration.md (what the Models page shows on a hosted-only deployment), plus an ADR — "a hosted-only deployment runs no local runtime" — amending ADR-0010 / ADR-0011 / ADR-0118 / ADR-0134.

Note for a separate issue

llm/providers.py:42, docs/infrastructure/secrets.md:138 and docs/services/core-app.md:565 all state that one OpenRouter key reaches that provider's chat and embedding models (#865). OpenRouter exposes no embeddings endpoint as far as we can tell, which would make openrouter/… an embedding dead end and the hosted-only path above much narrower than it looks (gpt/… or the custom OpenAI-compatible slot). Verify with one real call before 1.0.0 and correct the three claims if it does not hold; not in scope here.

[baakhoff]

In progress on two branches, built in parallel against the contract pinned in the issue body:

• feat/core-no-local-runtime — Part 1 (core: local_runtime_enabled, GET /platform/v1/llm/local-runtime, the 200-instead-of-500 on /llm/models, the 409/502 refusals, _ensure_can_serve, readiness n/a, the bootstrap short-circuit, the ADR-0134 seam on both arms) and Part 3 (chart ollamaUrl three states + the defaults guard, the Compose local-ai profile, retiring infra/ci/ollama-stub.yaml for a real hosted-only assertion in k8s-smoke). core-app 0.128.0→0.129.0, chart 0.1.2→0.2.0.
• feat/web-hosted-only-models — Part 2 (the Models page and the chat picker render absent as a settled state rather than a warning; unreachable keeps today's warning). web 0.150.0→0.151.0.

The runtime-level Local AI / Hosted AI switch stays #945 (2.0.0) and is out of scope here. ADR-0144 comes with the first branch.

[baakhoff]

Part 2 (web) — PR #963, branch feat/web-hosted-only-models, web 0.150.0→0.151.0 (MINOR).
All 12 checks green (frontend, quality, runtime-smoke, k8s-smoke, images,
compose-validate, chart-validate, migrations, docs-linkcheck, observability-lint,
shell-lint, secret-scan).

Shipped

• useLocalRuntime() (services/web/src/lib/useLocalRuntime.ts) over
  GET /platform/v1/llm/local-runtime, with LocalRuntimeState / LocalRuntimeStatus in
  contracts.ts and api.localRuntime() in api.ts. One query, read by the Models page, the
  local-model card, the embedding picker, the chat picker, the welcome state and the module
  model slots.
• absent: the Models page's local half becomes one line — the catalog, the download tray, the
  local model list, the context-window card and the KV-cache card are removed from the render,
  not disabled. The embedding picker drops its Local (Ollama) optgroup (and says every option
  is now hosted, so the corpus leaves the machine whichever is picked); the chat picker drops the
  Local heading but keeps the core-default row ungrouped, since the core's default may
  itself be hosted; the first-run welcome stops offering a pull; a module model slot with nothing
  left to offer says why.
• unreachable: today's warning, unchanged — now driven by the runtime's own state, with
  models.isError kept beside it for an older core. The "None yet. Pull one above" line is
  suppressed there (an empty 200 used to be impossible in that state, and would otherwise
  contradict the warning right under it).
• ok, and an older core that 404s: unchanged. An unknown answer reads as ok deliberately —
  hiding the local half from a deployment that has a runtime is the worse failure.

One defect found while building, fixed here

settled must latch (isFetched, not !isPending). The components it gates subscribe to the
same query; an errored query is permanently stale, so each newly-mounted subscriber triggered a
refetch, which put the query back into pending, which unmounted them again — a Models page that
oscillates forever against a core without the endpoint. There is a test that fails on the old
expression.

Covered only by mocks (lane A ships the endpoint)

Everything above is driven by a mocked api.localRuntime(); this branch cannot exercise the real
route. For the merge-set review, once both branches are combined:

1. the real payload parses against LocalRuntimeStatus and the three state strings match the
   core's exactly (absent / unreachable / ok, plus url_configured);
2. GET /llm/models really answers 200 + [] when absent and when unreachable — the
   unreachable warning and the suppressed "None yet" line both depend on that;
3. a hosted-only boot shows the collapsed card and no warning anywhere on Models or Chat.

Deliberately left out

• The runtime-level Local AI / Hosted AI switch stays A system-level switch to turn off local AI or hosted AI as a whole #945 (2.0.0), per the issue.
• No change to PROVIDER_LABELS.local (format.ts:49). That label only renders for
  hosted-filtered lists; the one local-labelled surface was the embedding optgroup, which is now
  gated.
• AutomationsScreen and SuggestionReviewModal are untouched. Both render local models
  ungrouped under a "Core default" option with a separate Hosted optgroup, so an empty local
  list reads correctly with no blank section and no lie. Checked, not changed.
• A module's embedding slot still offers no hosted ids. The select's comment ("hosted ids
  are chat-only — the gateway embeds locally") has been wrong since llm: OpenRouter provider alias + hosted embedding models through the gateway #865, but correcting it is a
  capability change I did not want to make blind against a contract lane A owns. The slot now
  explains why it is empty instead. Follow-up below.
• ModelsScreen still fetches ["models"] for the catalog's installed set even when
  absent. It is a 200 + [] and costs nothing; skipping it would be a second code path for no
  gain.

Verification skipped, and why

No task smoke, no compose boot, no image build locally (docker-light rule). Local gates were
npx tsc -b, npm run lint, npm test (105 files / 1177 tests), plus
tests/test_check_docs_links.py and tests/test_no_nul_bytes.py for the docs edit. No test
exclusions were needed — the web suite is jsdom-only. No visual check on the testing box (it
tracks testing, and this is not deployed).

Follow-ups worth filing

1. A module's embedding slot should offer saved hosted embedding models. Since llm: OpenRouter provider alias + hosted embedding models through the gateway #865 the
   gateway embeds through a hosted provider, so the Select's chat-only restriction and its
   comment in ModulesScreen.tsx are stale — and on a hosted-only deployment they leave an
   embedding slot with literally nothing to choose. Wants the same role-aware filter the
   Models page's Embedding card already applies.
2. The Models page fetches the model catalog even where nothing can be pulled. Harmless
   today (the card is not rendered when absent) but worth a enabled: guard if the catalog
   query ever grows a cost.
3. The web version still lives in two files (package.json, package-lock.json) with no
   test comparing them — the JS-side twin of chore(modules): manifests report the declared version — six stale pins fixed, tests compare instead of pin #854/chore: six module manifests pin stale versions, and their tests pin the same literals #845. A one-line assertion in the frontend
   gate would close it.

ADR

None from this lane — lane A writes ADR-0144 for the whole decision. One UI choice the
coordinator may want recorded inside it: an unknown answer from /llm/local-runtime reads as
ok, so an older core, a transient failure, or a future core that drops the endpoint keeps
exactly today's behaviour rather than hiding the local half of the product.

[baakhoff]

Lane A closing notes — Part 1 (core) + Part 3 (infra), PR #964

All 13 checks green, k8s-smoke included: the gate now upgrades a live release into the hosted-only mode and asserts the core answers (state: absent, GET /llm/models → 200 + [], pull → 409). Part 2 (web) is the other lane.

Shipped

Core (core-app 0.128.0 → 0.129.0) — the pre-decided contract, as written: local_runtime_enabled, GET /platform/v1/llm/local-runtime, a model list that never 500s, 409/502 in place of the bare 500s, a ModelCapabilityError refusal for a local id, readiness n/a, a bootstrap that returns in one line, and a KV-cache apply that asks neither ADR-0134 arm to find a workload.

Infra (chart 0.1.2 → 0.2.0) — epicurus.ollamaUrl renders empty, LLM_BOOTSTRAP_MODELS blanks itself when left at auto, a render-time guard refuses a runtime-less release with bare model defaults, and Compose gets the local-ai profile + required: false + ${OLLAMA_URL-…}.

Where the pre-decided contract turned out to be wrong

One place. The brief put the KV-cache apply in the same bucket as pull/delete/unload: "409 when absent, 502 when unreachable". The 502 half is wrong and I did not implement it. That path never talks to Ollama — it writes the start-up env file and asks the container runtime to bounce the workload — so "unreachable" is not a state it can observe without inventing a probe, and refusing there would break two real cases: setting the KV-cache type while the server happens to be down (legitimate; the env file is read at next start), and k8s-smoke's own shared assertion, which applies a KV-cache change against a runtime that answers nothing. It refuses 409 when absent (before persisting the preference) and is otherwise unchanged — applied/staged already report exactly how far it got (#709). Documented in the route docstring, in docs/reference/platform-api.md and in the ADR below.

Deliberately left out / deviations

• infra/ci/ollama-stub.yaml is not retired, though the issue and the lane brief both proposed it. It is the only Ollama workload a kind run ever has, so it is what exercises KubernetesController.restart_service and the chart Role's statefulsets verb — the ci: k8s-smoke and runtime-smoke parity holes — Ollama restart arm, files PVC, web on Compose, minio-init, helm upgrade #919 parity hole. Retiring it would re-open that hole and force the shared KV-cache assertion to become runtime-conditional, weakening the Compose gate too. Instead the gate asserts the hosted-only mode in its upgrade phase, where the stub is irrelevant, and the stub's header now says all of this.
• A second k8s-smoke boot — the gate runs ~10 of its 20-minute budget already. Folding the mode into the existing helm upgrade costs nothing and makes that step a real config change instead of the timestamp it used to use to force a roll.
• docs/user/configuration.md — lane B's file, untouched, as instructed.
• No validator rejecting a bare-name default in the core, per the issue: a local default with no runtime is a legible refusal at call time, not a boot failure.

Owner attention

1. The local-ai profile is opt-in by construction, so every start path selects it explicitly (.env.example, all four task *-up, infra/cd/reconcile.sh unless EPICURUS_LOCAL_AI=0), and tests/test_no_local_runtime.py::test_every_start_path_still_turns_local_ai_on keeps it that way. The one residual change: a bare docker compose up -d in a checkout with no .env (or an .env predating this) no longer starts Ollama. The testing box is safe either way because task reconcile passes the flag itself — but adding COMPOSE_PROFILES=local-ai to its .env costs nothing and makes a hand-typed docker compose up behave too.
2. docker compose ps ollama on the box after the next reconcile is the one-line confirmation that the profile wiring did what it should.

Follow-ups worth filing

• portability/embedding.py::_local_note still says "not among the 0 model(s) the local runtime holds" on a hosted-only deployment whose embed pref is (wrongly) a bare name. Accurate, but it could name the mode. It needs local_runtime_enabled on the EmbeddingProbe protocol, which touches that feature's test stubs — out of scope here.
• structlog logger freezing. configure_logging sets cache_logger_on_first_use=True, so the first use of a module-level logger after the app configures logging pins the processor list that was live at that instant — and a later capture_logs() then intercepts nothing. test_llm_gateway.py already documented this on _RecordingLog; this PR hit it again (a new gateway warning changed which test froze the logger, and test_the_learn_warning_names_the_cause_and_no_account_id started failing only in a full run). I moved the two affected tests onto the recorder — one of them, the api-key redaction assertion, was vacuously passing in full runs. A repo-wide fix (e.g. configure_logging mutating the configured processor list in place, the way capture_logs does, so already-bound loggers keep honouring configuration) belongs in epicurus-core and needs its own version bump.
• GET /platform/v1/llm/local-runtime costs one /api/tags round trip per call when a runtime is configured. Fine for a page poll; if the web ends up calling it at chat-turn frequency it deserves the same short TTL cache the module registry uses.
• unreachable is not cached or debounced — a genuinely down runtime logs one warning per probe. Bounded by the caller's poll interval, but a "warn once per streak" treatment (like the catalog's) would be quieter.

ADR — paste-ready

ADR-0144 — A hosted-only deployment runs no local runtime — 2026-09-19 — Accepted

Issue #962. Related: ADR-0010, ADR-0011, ADR-0118, ADR-0134.

Context. The platform is local-first, and until now that was indistinguishable from local-only. OLLAMA_URL was a plain string with a localhost default, so absent, unreachable and misconfigured were one fact to every call site, and each one guessed differently: models() and pull() and delete_model() let the failure propagate to a bare 500 — on an endpoint the Models page polls every ten seconds — show() and unload() caught it and degraded silently, the readiness probe read it as "cold" and so reported the turn's model warming forever, and the first-boot bootstrap polled a dead address for 180 seconds on every process start. The quiet degradation was the worst of them: an unreachable /api/show returns empty details, the model's role reads unknown, and unknown is waved through by design (ADR-0140), so a local model sailed past the capability gate to die at the provider with a connection error instead of being refused with a reason. The deployment surfaces were no better. The Helm chart requiredd ollama.external.url the moment Ollama was disabled — a helper copied from qdrantUrl/openbaoUrl, components the core genuinely cannot run without — so helm install failed before the cluster saw anything; Compose included the Ollama fragment unconditionally and core-app hard-depended on the service. The proof this was a gap rather than a policy was in our own CI: k8s-smoke disabled the chart's Ollama and applied a fake StatefulSet so the container-runtime seam would find a workload. We had written a stub instead of a mode. Meanwhile the docs promised the mode in two places, and nothing validated that the defaults made sense without a runtime: LLM_DEFAULT_MODEL=llama3.2 and MEMORY_EMBED_MODEL=nomic-embed-text are bare names, and a bare name routes to the local runtime — so the out-of-the-box hosted-only install was precisely the half-working stack we refuse to ship elsewhere, with chat working through the operator's hosted provider while memory recall and every module index failed at call time.

Decision. "No local runtime" is a first-class deployment mode, spelled OLLAMA_URL="", and the three states are carried in the data rather than inferred from a caught exception. CoreAppSettings.local_runtime_enabled is the fact; GET /platform/v1/llm/local-runtime reports absent | unreachable | ok with url_configured, as a separate endpoint — GET /llm/models stays a bare list[ModelInfo], because twelve consumers read that array and wrapping it would be a breaking change bought for nothing. That list now answers 200 with an empty body in both non-serving states: "what does the local runtime hold" has an honest answer when it holds nothing and when it cannot be asked, and which is a different question with its own endpoint. Everything that genuinely needs a runtime refuses with a reason: pull, the SSE pull (before the response starts, since an SSE cannot take back its status), delete and unload answer 409 when absent — nothing is broken, the request is simply meaningless here and retrying will never help — and 502 when a configured runtime is unreachable, never a bare 500. The KV-cache apply is the one exception to the pair and refuses 409 when absent only: it never talks to Ollama, so "unreachable" is not a state it can observe, and setting the value while the server is down is legitimate — applied/staged already say how far it got (#709). Inference is refused one layer earlier, in _ensure_can_serve, with the ModelCapabilityError the role gate already speaks (ADR-0140) rather than a new error type, and before the pause rule, because "resume to run inference" is an instruction an operator with no runtime cannot follow; the chat fallback chain likewise skips local candidates. Readiness reports the model n/a and ready, and the bootstrap returns in one log line. On the deployment surfaces, epicurus.ollamaUrl follows epicurus.minioUrl and renders empty, the chart blanks LLM_BOOTSTRAP_MODELS when it is left at auto, and in exchange for the guard we removed we added the one worth having: a release with no local runtime whose chat or embedding default is still a bare (local) name fails to render, naming the key and a hosted alias. Compose gets the same capability through a local-ai profile on ollama and ollama-init, required: false on the core's dependency, and OLLAMA_URL: ${OLLAMA_URL-http://ollama:11434} — single-dash, because :- would substitute the default back in for the deliberately empty value that is the setting. A profile is opt-in by construction, so local AI is kept on by making every path that starts the stack select it explicitly rather than by hoping nobody notices.

Consequences. A hosted-only install is now a supported deployment on both runtimes, with the same words on each, and the operator is told which of the three states applies rather than shown a broken local UI or a 500 every ten seconds. The old chart guard refused a legitimate deployment and the new one refuses a broken one, which is a strictly better trade but not a free one: a naive --set ollama.enabled=false now fails at render time, deliberately, and the message is what carries the fix. The mode costs a discipline on Compose — a profile is opt-in, so .env.example, all four task *-up tasks and infra/cd/reconcile.sh select local-ai themselves (EPICURUS_LOCAL_AI=0 is the deploy-side opt-out), and a test pins that; a bare docker compose up -d with no .env at all no longer starts Ollama. The KV-cache exception means the 409/502 pair is not quite uniform across the four local-only endpoints, which is a smaller cost than a refusal that cannot be justified. infra/ci/ollama-stub.yaml survives despite this ADR removing its original justification: it is the only Ollama workload a kind run has, and so the only thing exercising the Kubernetes arm's restart path and the chart Role's statefulsets verb (#919) — the gate instead asserts the new mode in its upgrade phase, which also turns that step from a timestamp-forced roll into a real configuration change. GET /llm/local-runtime costs one /api/tags round trip per call when a runtime is configured, which is fine at page-poll frequency and would want a short TTL cache if anything called it per turn.

Implemented for #962 (branch feat/core-no-local-runtime, PR #964).

[baakhoff]

Lane A follow-up — the Compose half is an overlay, not a profile (PR #964, green)

The first cut of the Compose half regressed the repo's documented install. README.md:50 and docs/user/installation.md:10-27 both publish git clone → cd epicurus → docker compose up -d, and neither mentions an .env before that step — so putting profiles: [local-ai] on the ollama services took the local runtime out of every fresh clone while the shipped llama3.2 / nomic-embed-text defaults still pointed at it. That is the half-working stack the new chart guard exists to refuse, delivered by default to the person least able to diagnose it; an existing operator who pulled and re-upped without an .env lost Ollama too. .env.example carrying the profile did not cover it: nothing copies that file into place and no doc says to. My original note called this owner-attention; it was a defect.

Fixed on the same branch (commit 1615979d), with the overlay idiom the repo already uses:

• infra/ollama/compose.hosted-only.yaml — layered over the stack, never included by it. It does both halves in one step: removes ollama + ollama-init (by assigning a profile nothing enables, since an override file can add to the compose model but not delete from it) and blanks OLLAMA_URL. Either alone is wrong — removing only the container leaves the core probing a host that is gone, which is unreachable, not absent.
• task hosted-only-up / task hosted-only-down drive it; EPICURUS_HOSTED_ONLY=1 applies it from infra/cd/reconcile.sh, whose default path passes no -f at all, exactly as before.
• Every profile-selection I had added is gone: infra/ci/smoke.sh is byte-identical to main again, infra/ollama/compose.yaml differs from main by a comment block only, and task up / obs-up / docker-socket-up / external-mounts-up are back to their original commands. .env.example gained comments only — no new active setting.
• compose.yaml's header now states the rule and names the three opt-in overlays.

Pinned in both directions. tests/test_no_local_runtime.py::test_the_default_install_still_brings_up_the_local_runtime asserts no profile gates those services and no start task needs a flag; …::test_the_local_runtime_can_be_left_out_through_the_overlay asserts the overlay removes them and blanks the URL. compose-validate proves the same against a real docker compose config on both shapes — the default stack must contain ollama + ollama-init and point the core at http://ollama:11434, and the overlay must contain neither and render OLLAMA_URL: "".

Also folded in, per the coordinator: GET /platform/v1/llm/local-runtime answering 404 (an older core), a non-2xx, or an unparseable body reads as ok — the client keeps its pre-#962 behaviour rather than collapsing every local control against a core that is serving one. Recorded in docs/reference/platform-api.md and the core-app page for the web lane.

All 13 checks green, k8s-smoke and runtime-smoke included.

ADR-0144 — replaces the version in my earlier comment

The Decision and Consequences paragraphs changed (the Compose mechanism, the two rules above); Context is unchanged. Take this one.

ADR-0144 — A hosted-only deployment runs no local runtime — 2026-09-19 — Accepted

Issue #962. Related: ADR-0010, ADR-0011, ADR-0118, ADR-0134.

Context. The platform is local-first, and until now that was indistinguishable from local-only. OLLAMA_URL was a plain string with a localhost default, so absent, unreachable and misconfigured were one fact to every call site, and each one guessed differently: models() and pull() and delete_model() let the failure propagate to a bare 500 — on an endpoint the Models page polls every ten seconds — show() and unload() caught it and degraded silently, the readiness probe read it as "cold" and so reported the turn's model warming forever, and the first-boot bootstrap polled a dead address for 180 seconds on every process start. The quiet degradation was the worst of them: an unreachable /api/show returns empty details, the model's role reads unknown, and unknown is waved through by design (ADR-0140), so a local model sailed past the capability gate to die at the provider with a connection error instead of being refused with a reason. The deployment surfaces were no better. The Helm chart requiredd ollama.external.url the moment Ollama was disabled — a helper copied from qdrantUrl/openbaoUrl, components the core genuinely cannot run without — so helm install failed before the cluster saw anything; Compose included the Ollama fragment unconditionally and core-app hard-depended on the service. The proof this was a gap rather than a policy was in our own CI: k8s-smoke disabled the chart's Ollama and applied a fake StatefulSet so the container-runtime seam would find a workload. We had written a stub instead of a mode. Meanwhile the docs promised the mode in two places, and nothing validated that the defaults made sense without a runtime: LLM_DEFAULT_MODEL=llama3.2 and MEMORY_EMBED_MODEL=nomic-embed-text are bare names, and a bare name routes to the local runtime — so the out-of-the-box hosted-only install was precisely the half-working stack we refuse to ship elsewhere, with chat working through the operator's hosted provider while memory recall and every module index failed at call time.

Decision. "No local runtime" is a first-class deployment mode, spelled OLLAMA_URL="", and the three states are carried in the data rather than inferred from a caught exception. CoreAppSettings.local_runtime_enabled is the fact; GET /platform/v1/llm/local-runtime reports absent | unreachable | ok with url_configured, as a separate endpoint — GET /llm/models stays a bare list[ModelInfo], because twelve consumers read that array and wrapping it would be a breaking change bought for nothing. That list now answers 200 with an empty body in both non-serving states: "what does the local runtime hold" has an honest answer when it holds nothing and when it cannot be asked, and which is a different question with its own endpoint. A client that cannot get an answer from that endpoint — a 404 from an older core, any non-2xx, an unparseable body — reads it as ok and keeps its previous behaviour: the state steers what a surface draws, never what the core will do, and collapsing every local control against a core that is serving one is a worse failure than showing a control that then refuses. Everything that genuinely needs a runtime refuses with a reason: pull, the SSE pull (before the response starts, since an SSE cannot take back its status), delete and unload answer 409 when absent — nothing is broken, the request is simply meaningless here and retrying will never help — and 502 when a configured runtime is unreachable, never a bare 500. The KV-cache apply is the one deliberate exception to that pair and refuses 409 when absent only: it never talks to Ollama — it writes the start-up env file and asks the container runtime to bounce the workload — so unreachable is not a state it can observe without inventing a probe, and setting the value while the server is down is legitimate, since the file is read at the next start and applied/staged already report exactly how far the call got (#709). Inference is refused one layer earlier, in _ensure_can_serve, with the ModelCapabilityError the role gate already speaks (ADR-0140) rather than a new error type, and before the pause rule, because "resume to run inference" is an instruction an operator with no runtime cannot follow; the chat fallback chain likewise skips local candidates. Readiness reports the model n/a and ready, and the bootstrap returns in one log line. On Kubernetes, epicurus.ollamaUrl follows epicurus.minioUrl and renders empty, the chart blanks LLM_BOOTSTRAP_MODELS when it is left at auto, and in exchange for the guard we removed we added the one worth having: a release with no local runtime whose chat or embedding default is still a bare (local) name fails to render, naming the key and a hosted alias. On Compose the mode is an opt-out overlay — infra/ollama/compose.hosted-only.yaml, task hosted-only-up — which removes the two Ollama services and blanks OLLAMA_URL together, since removing the container alone produces unreachable rather than absent. Deliberately not a compose profile on those services: a profile is opt-in by construction, and these sit on the one install path the repo publishes (git clone → docker compose up -d, with no .env mentioned), so a profile would have removed the local runtime from every fresh clone while the shipped bare defaults still pointed at it — the very stack the chart guard above refuses, shipped as the default.

Consequences. A hosted-only install is now a supported deployment on both runtimes, with the same words on each, and the operator is told which of the three states applies rather than shown a broken local UI or a 500 every ten seconds. The default Compose install is untouched — infra/ollama/compose.yaml differs only by a comment, infra/ci/smoke.sh not at all — and the opt-out is a visible command rather than an invisible variable, at the cost of an overlay file the operator must remember to pass on every up (the two task targets and EPICURUS_HOSTED_ONLY=1 on the deploy box are the answer to that). The old chart guard refused a legitimate deployment and the new one refuses a broken one, which is a strictly better trade but not a free one: a naive --set ollama.enabled=false now fails at render time, deliberately, and the message is what carries the fix. The KV-cache exception means the 409/502 pair is not quite uniform across the four local-only endpoints, which is a smaller cost than a refusal that cannot be justified. infra/ci/ollama-stub.yaml survives despite this ADR removing its original justification: it is the only Ollama workload a kind run has, and so the only thing exercising the Kubernetes arm's restart path and the chart Role's statefulsets verb (#919) — the gate instead asserts the new mode in its upgrade phase, which also turns that step from a timestamp-forced roll into a real configuration change. GET /llm/local-runtime costs one /api/tags round trip per call when a runtime is configured, which is fine at page-poll frequency and would want a short TTL cache if anything called it per turn.

Implemented for #962 (branch feat/core-no-local-runtime, PR #964).