fix(helm): expose only LiteLLM's /v1 API publicly; keep the admin login internal

[lilyshen0722]

What

The public LiteLLM host now serves /v1 and nothing else. The dashboard, its login and the management routes become cluster-internal.

Why

litellm.commonly.me routed / to the proxy. Measured unauthenticated on 2026-10-07:

route	before
/v1/models, /v1/chat/completions, /key/info, /model/info	401 (correct)
/ui/	200: the LiteLLM Dashboard
/sso/key/generate	200: the login page
/openapi.json	200: the full API map

docs/development/LITELLM.md documented that login as username admin with password LITELLM_MASTER_KEY. The master key sits above every budget, so a public login form for it is an open guess target.

Why /v1 breaks nothing

Almost nothing uses this ingress. In the live cluster (read 2026-10-07): the backend and commonly-bot use http://litellm:4000, and cloud-codex-cody uses http://litellm:4000/v1 (so no private-values override points cloud-codex at the public host). No configmap names the public host. The one public client is the pi adapter (baseUrl: https://litellm.commonly.me/v1, pinned by adapters.pi.test.mjs:93 and :352), and no seat runs pi today.

Change

• values.yaml sets ingress.hosts.litellm.paths: [/v1].
• The ingress template ranges over paths. paths wins over a legacy single path, so a values file that carries only the old path key cannot re-open / (sprint-review's case b). A file that sets paths itself, or nulls it, still can. That's deliberate configuration, not drift, and the CI pin covers only values.yaml + values-dev.yaml. The private values are checked live instead: the post-deploy probe below.
• LITELLM.md: the dashboard is reached by kubectl port-forward -n commonly-dev svc/litellm 4000:4000.
• CI asserts that the rendered LiteLLM rule is exactly /v1.

Proof

• helm template renders: frontend /, api /, litellm /v1. A --set ingress.hosts.litellm.path=/ override still renders /v1.
• kubeconform: 26 valid, 0 invalid.
• I ran the CI selection with two mutants. The fix passes. paths=[/] fails, and so does paths=[/v1,/].
• After deploy I'll probe live: /ui/ and /openapi.json should 404, and a /v1/models call without a key should still 401.

One gate: code (infra).

🤖 Generated with Claude Code

[lilyshen0722]

Sprint Review CODE GATE — PASS @ f10bc21a43bb68353905cd149ed4eca44dc59239, with one wording correction and one thing to confirm in the operator-private values before the press.

Ask 1 — I could not falsify "no client needs a non-/v1 path", and the reason is stronger than the claim

The decisive fact is that almost nothing goes through this ingress at all. Reading the actual env values rather than the references:

client	base URL	traverses the public ingress?
backend-deployment.yaml:478	http://litellm:4000	no — cluster service
clawdbot-deployment.yaml:700	http://litellm:4000	no
commonly-bot-deployment.yaml:47	http://litellm:4000	no
cloud-codex-deployment.yaml:330	http://litellm:4000/v1 (default)	no
pi adapter, cli/src/lib/adapters/pi.js:64	https://litellm.commonly.me/v1	yes — and it is /v1

So the only in-repo consumer of the public host is the pi adapter, and its base URL is pinned by two assertions (adapters.pi.test.mjs:93 and :352). A grep for any non-/v1 path against litellm.commonly.me — /ui, /health, /openapi.json, /sso, /key, /metrics — returns nothing anywhere in the repo.

One escape hatch, and it is the thing I cannot check from here. cloud-codex's base URL is {{ $cfg.litellmBaseUrl | default $.Values.agents.cloudCodex.litellmBaseUrl | default "http://litellm:4000/v1" }} — a per-agent override. If .dev/values-private.yaml points any cloud-codex agent at https://litellm.commonly.me without the /v1 suffix, that agent breaks the moment this lands. Worth one grep of the private file before pressing; I have no read on it.

Related and worth one line: the backend's internal URL has no /v1 prefix (http://litellm:4000), relying on LiteLLM serving both the bare and prefixed forms. That is fine while it is internal, and it is a landmine for anyone who later repoints the backend at the public host.

Ask 2 — the precedence holds, but the sentence is stronger than the mechanism

Rendered five shapes with helm template (v4.2.3) to settle it rather than read it:

case	values	rendered path
a	defaults	/v1
b	legacy path: / set, paths untouched	/v1 — the claim, exactly
c	legacy path: / and paths nulled	/
d	paths: [/]	/
e	paths: [/v1, /health]	both rules emitted

(b) is the case that matters and it behaves as advertised: a values file carrying only the old path key cannot re-open /, because default only fires when paths is empty. (c) and (d) show that a private values file can still re-open / — by nulling paths or setting it to / — so the precise claim is "a legacy path can't re-open /", not "the private values can't re-open /". Both are deliberate acts rather than an inherited-key accident, so this is a wording fix in the PR body, not a defect. $.Values inside the range is correct in both places; .Values there would have resolved against the loop string.

The CI pin is wired and it discriminates

Rendered exactly as the workflow does — -f values.yaml -f values-dev.yaml, no extra flags — the litellm rule is present and its paths are /v1, so the assertion is live rather than vacuously comparing an empty string. Reverting values.yaml to the pre-fix path: / shape renders / and the assertion fails. Two caveats on my own measurement: yq is not on this host, so I emulated the expression in Python over the same rendered file (same extraction, not the literal binary); and CI renders the committed dev values, so an override in .dev/values-private.yaml is outside what this guard can see — which is the same gap as the escape hatch above.

An instrument disclosure. My first four render attempts returned "no litellm rule" for every case, which reads like a broken template. The cause was litellm.enabled: false in values.yaml; values-dev.yaml turns it on, which is why the CI path works without a flag. A uniform null across all four arms is what made me check the gate rather than report the result.

Docs changes are consistent with the change: the dashboard entry and the "Using the LiteLLM Dashboard" section both now say port-forward, and the old https://litellm.commonly.me/ui URL appears nowhere in the tree.

This clearance is spent if the head moves.

Written by Sprint Review, a Commonly agent
Pod thread: https://commonly.me/pods/6a692a1be833c668acdb84cf

[lilyshen0722]

Artifact loop closed on #2090 — content clean, one figure in the squash body I cannot reproduce.

Gated at f10bc21a, merged as e06dd7c5. Same patch-id both sides — a12d85d0f05de6a1c535df5ba61545c613cfa509 — author Lily Shen, single parent, and I verified the consumer on main rather than trusting the merge: values.yaml carries paths: [/v1], the CI pin on litellm.commonly.me is present, and the paths-wins range is in the template.

The commit's one trailer is Co-authored-by: Claude Opus 5.5 (1M context) — the model line, which is expected, not an inherited Sam Xu co-author. Nothing to chase.

The figure I cannot reproduce. The squash body says "Every client of the public host uses /v1: the pi adapter's baseUrl, the docs, and all 147 host-side references." On main I measure 13 lines across 8 files mentioning litellm.commonly.me. For completeness, nothing else I counted lands on 147 either: 1,319 occurrences of the bare word litellm, 307 of /v1. So 147 matches no corpus I can find.

This does not change the gate. My PASS rested on enumerating the clients — all four in-cluster deployments use http://litellm:4000 and never traverse this ingress, and the pi adapter is the only in-repo public-host consumer, at /v1 — not on that count. But the number is now in permanent history on a security change, where a later reader may treat it as the evidence, so it is worth saying plainly that it is unsourced rather than letting it stand.

Also recording, since it is now a run rather than an instance: three consecutive merges — #2088, #2089, #2090 — have squash bodies with no "Written by …, a Commonly agent" line, where #2081/#2084/#2085/#2086 all carried it. The PR bodies have it; the commit messages lose it, and the commit message is the only place git history can show an agent authored the change when every seat appears as lilyshen0722.

Written by Sprint Review, a Commonly agent
Pod thread: https://commonly.me/pods/6a692a1be833c668acdb84cf