diff --git a/.github/workflows/test-unit.yml b/.github/workflows/test-unit.yml
index 76af64c8ccd..87f8df347bb 100644
--- a/.github/workflows/test-unit.yml
+++ b/.github/workflows/test-unit.yml
@@ -1116,6 +1116,11 @@ jobs:
with:
category: ui
+ - name: Run UI runtime prefix regression tests
+ if: steps.changes.outputs.decision != 'skip'
+ working-directory: .
+ run: python3 -m unittest discover -s tests/integration/ui -p test_ui_root_path.py
+
- name: Setup Node.js
if: steps.changes.outputs.decision != 'skip'
uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
diff --git a/helm/litellm/README.md b/helm/litellm/README.md
index 53dc300b886..5af634e3dbb 100644
--- a/helm/litellm/README.md
+++ b/helm/litellm/README.md
@@ -23,3 +23,73 @@ ui:
backend:
gatewayUrl: https://gateway.example.com
```
+
+# Custom URL prefix
+
+Set `serverRootPath` to serve the componentized chart under a URL prefix. An empty value or `/` keeps the existing root deployment. A trailing slash is normalized
+
+```yaml
+fullnameOverride: litellm
+serverRootPath: /services/llm
+ingress:
+ enabled: false
+gateway:
+ extraEnv:
+ - name: PROXY_BASE_URL
+ value: https://platform.example.com/services/llm
+backend:
+ extraEnv:
+ - name: PROXY_BASE_URL
+ value: https://platform.example.com/services/llm
+```
+
+Supply the chart's existing database, Redis, master-key and SSO settings as usual. Configure the OAuth callback as `https://platform.example.com/services/llm/sso/callback`
+
+The chart passes `SERVER_ROOT_PATH` to gateway, backend and UI. The UI image prepares its export in a fresh directory under `/tmp` at startup, leaving the packaged files untouched. With a read-only root filesystem, mount a writable `emptyDir` on `/tmp`. The default root deployment does not copy or rewrite the export
+
+When the chart's ingress is enabled, its gateway, backend and UI routes and `ingress.extraPaths` are prefixed. Paths in `extraPaths` remain root-relative, for example `/custom-provider`, and the chart adds the configured prefix. The ingress must preserve the path sent upstream. Prefixes containing dots require Gateway API or the ALB controller; ingress-nginx cannot preserve all of the chart's exact matches with its dotted-path normalization
+
+The prefix applies to gateway, backend and UI. Lens is distributed separately and keeps its independently configured ingestion address
+
+With an external Gateway API controller, route UI requests to port 3000, inference requests to port 4000, and management/configuration/SSO to port 4001. Preserve the prefix for Python services. The UI accepts both a preserved prefix and a prefix stripped by `URLRewrite`
+
+This Istio example covers the UI, configuration/SSO, chat completions and model listing. Add other inference routes from `templates/ingress.yaml` as needed. Do not send all `/v1` paths to the gateway: several management endpoints also use that version prefix
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ name: litellm
+ namespace: litellm
+spec:
+ parentRefs:
+ - name: platform
+ namespace: istio-ingress
+ hostnames:
+ - platform.example.com
+ rules:
+ - matches:
+ - path: {type: Exact, value: /services/llm}
+ - path: {type: Exact, value: /services/llm/}
+ - path: {type: Exact, value: /services/llm/favicon.ico}
+ - path: {type: PathPrefix, value: /services/llm/ui}
+ - path: {type: PathPrefix, value: /services/llm/_next}
+ - path: {type: RegularExpression, value: '^/services/llm/.*\.txt$'}
+ backendRefs:
+ - name: litellm-ui
+ port: 3000
+ - matches:
+ - path: {type: PathPrefix, value: /services/llm/v1/chat}
+ - path: {type: PathPrefix, value: /services/llm/chat}
+ - path: {type: PathPrefix, value: /services/llm/v1/models}
+ backendRefs:
+ - name: litellm-gateway
+ port: 4000
+ - matches:
+ - path: {type: PathPrefix, value: /services/llm}
+ backendRefs:
+ - name: litellm-backend
+ port: 4001
+```
+
+Health probes keep their existing unprefixed paths on the container port. Runtime prefix preparation changes static asset URLs and configuration discovery, and adds HTML metadata so the UI knows its prefix before hydration; login return URLs and dashboard navigation use the prefix reported by the backend
diff --git a/helm/litellm/templates/_helpers.tpl b/helm/litellm/templates/_helpers.tpl
index 8cb2fbf441d..7b5bf5199b0 100644
--- a/helm/litellm/templates/_helpers.tpl
+++ b/helm/litellm/templates/_helpers.tpl
@@ -698,6 +698,14 @@ shutdown drain window.
{{- printf "%s-lens-clickhouse" (include "litellm.fullname" . | trunc 47 | trimSuffix "-") -}}
{{- end -}}
+{{- define "litellm.serverRootPath" -}}
+{{- $root := .Values.serverRootPath | default "" | trimSuffix "/" -}}
+{{- if and $root (or (not (regexMatch "^(/[A-Za-z0-9_.~-]+)+$" $root)) (regexMatch "(^|/)\\.\\.?(/|$)" $root)) -}}
+{{- fail "serverRootPath must contain safe absolute path segments without traversal" -}}
+{{- end -}}
+{{- $root -}}
+{{- end -}}
+
{{- define "litellm.lens.mode" -}}
{{- $mode := .Values.lensWorker.mode | default (ternary "bundled" "disabled" .Values.lensWorker.enabled) -}}
{{- if not (has $mode (list "bundled" "external" "disabled")) -}}
diff --git a/helm/litellm/templates/backend/deployment.yaml b/helm/litellm/templates/backend/deployment.yaml
index 7360261dab1..cb8b31a812e 100644
--- a/helm/litellm/templates/backend/deployment.yaml
+++ b/helm/litellm/templates/backend/deployment.yaml
@@ -59,6 +59,11 @@ spec:
containerPort: 4001
protocol: TCP
env:
+ {{- $root := include "litellm.serverRootPath" . }}
+ {{- if $root }}
+ - name: SERVER_ROOT_PATH
+ value: {{ $root | quote }}
+ {{- end }}
{{- include "litellm.lensConnectionEnv" . | nindent 12 }}
{{- if .Values.ui.publicUrl }}
- name: LITELLM_CORS_ORIGINS
diff --git a/helm/litellm/templates/gateway/deployment.yaml b/helm/litellm/templates/gateway/deployment.yaml
index b0e7f0dcebb..9033c8c7d8d 100644
--- a/helm/litellm/templates/gateway/deployment.yaml
+++ b/helm/litellm/templates/gateway/deployment.yaml
@@ -55,6 +55,11 @@ spec:
containerPort: 4000
protocol: TCP
env:
+ {{- $root := include "litellm.serverRootPath" . }}
+ {{- if $root }}
+ - name: SERVER_ROOT_PATH
+ value: {{ $root | quote }}
+ {{- end }}
{{- include "litellm.lensConnectionEnv" . | nindent 12 }}
{{- if .Values.ui.publicUrl }}
- name: LITELLM_CORS_ORIGINS
diff --git a/helm/litellm/templates/ingress.yaml b/helm/litellm/templates/ingress.yaml
index 22ff8a95566..26e8f9ff40e 100644
--- a/helm/litellm/templates/ingress.yaml
+++ b/helm/litellm/templates/ingress.yaml
@@ -32,6 +32,7 @@
{{- end }}
{{- end }}
{{- if .Values.ingress.enabled -}}
+{{- $root := include "litellm.serverRootPath" . -}}
{{- $gatewayName := include "litellm.gateway.fullname" . -}}
{{- $backendName := include "litellm.backend.fullname" . -}}
{{- $uiName := include "litellm.ui.fullname" . -}}
@@ -39,6 +40,9 @@
{{- $backendPort := .Values.backend.service.port -}}
{{- $uiPort := .Values.ui.service.port -}}
{{- $controller := .Values.ingress.controller | default "alb" -}}
+{{- if and $root (eq $controller "nginx") (contains "." $root) }}
+{{- fail "serverRootPath containing dots is not supported with ingress.controller=nginx; use Gateway API or a prefix without dots" }}
+{{- end }}
{{- if not (has $controller (list "alb" "nginx")) }}
{{- fail (printf "ingress.controller: unknown controller %q, expected one of alb, nginx" $controller) }}
{{- end }}
@@ -77,6 +81,9 @@
(dict "path" "/_next" "pathType" "Prefix")
(dict "path" "/ui" "pathType" "Prefix")
-}}
+{{- if $root }}
+{{- $uiPaths = append $uiPaths (dict "path" "/" "pathType" "Exact" "trailingSlash" true) }}
+{{- end }}
{{- if eq $controller "alb" }}
{{- $uiPaths = append $uiPaths (dict "path" "/*.txt" "pathType" "ImplementationSpecific") }}
{{- end }}
@@ -211,7 +218,7 @@ spec:
{{- range $uiPaths }}
{{- $pathType := include "litellm.ingress.pathType" (dict "controller" $controller "path" .path "pathType" .pathType) }}
{{- $builtinPathKeys = append $builtinPathKeys (printf "%s|%s" .path $pathType) }}
- - path: {{ .path }}
+ - path: {{ if eq .path "/" }}{{ if .trailingSlash }}{{ printf "%s/" $root }}{{ else }}{{ $root | default "/" }}{{ end }}{{ else }}{{ printf "%s%s" $root .path }}{{ end }}
pathType: {{ $pathType }}
backend:
service:
@@ -224,14 +231,14 @@ spec:
# /test/* MCP management endpoints fall to the backend catch-all.
# Exact /debug/memory/summary reads a serving worker's RSS (the e2e memory
# gate); the rest of /debug/* stays on the backend.
- - path: /test
+ - path: {{ printf "%s/test" $root }}
pathType: Exact
backend:
service:
name: {{ $gatewayName }}
port:
number: {{ $gatewayPort }}
- - path: /debug/memory/summary
+ - path: {{ printf "%s/debug/memory/summary" $root }}
pathType: Exact
backend:
service:
@@ -241,7 +248,7 @@ spec:
{{- range $gatewayPrefixes }}
{{- $pathType := include "litellm.ingress.pathType" (dict "controller" $controller "path" . "pathType" "Prefix") }}
{{- $builtinPathKeys = append $builtinPathKeys (printf "%s|%s" . $pathType) }}
- - path: {{ . }}
+ - path: {{ printf "%s%s" $root . }}
pathType: {{ $pathType }}
backend:
service:
@@ -293,7 +300,7 @@ spec:
{{- if has (printf "%s|%s" $extra.path $pathType) $builtinPathKeys }}
{{- fail (printf "ingress.extraPaths[%d]: path %s with pathType %s is already routed by this chart, and a duplicate would take it over rather than add to it" $idx $extra.path $pathType) }}
{{- end }}
- - path: {{ $extra.path | quote }}
+ - path: {{ printf "%s%s" $root $extra.path | quote }}
pathType: {{ $pathType }}
backend:
service:
@@ -302,7 +309,7 @@ spec:
number: {{ $target.port }}
{{- end }}
# --- Catch-all → backend (management API: /key/*, /user/*, /team/*, ...) ---
- - path: /
+ - path: {{ $root | default "/" }}
pathType: Prefix
backend:
service:
diff --git a/helm/litellm/templates/ui/deployment.yaml b/helm/litellm/templates/ui/deployment.yaml
index 394eea17451..dd526f912e2 100644
--- a/helm/litellm/templates/ui/deployment.yaml
+++ b/helm/litellm/templates/ui/deployment.yaml
@@ -54,6 +54,11 @@ spec:
containerPort: 3000
protocol: TCP
env:
+ {{- $root := include "litellm.serverRootPath" . }}
+ {{- if $root }}
+ - name: SERVER_ROOT_PATH
+ value: {{ $root | quote }}
+ {{- end }}
{{- if .Values.ui.logLevel }}
- name: LITELLM_LOG
value: {{ .Values.ui.logLevel | quote }}
diff --git a/helm/litellm/tests/server_root_path_tests.yaml b/helm/litellm/tests/server_root_path_tests.yaml
new file mode 100644
index 00000000000..575554087f8
--- /dev/null
+++ b/helm/litellm/tests/server_root_path_tests.yaml
@@ -0,0 +1,74 @@
+suite: custom server root path
+templates:
+ - gateway/configmap.yaml
+ - gateway/deployment.yaml
+ - backend/deployment.yaml
+ - ui/deployment.yaml
+ - ingress.yaml
+set:
+ database.writer.host: postgres
+ database.writer.dbname: litellm
+ lens.enabled: false
+ lensWorker.enabled: false
+tests:
+ - it: configures all serving components with the same normalized prefix
+ set:
+ serverRootPath: /services/llm/
+ templates:
+ - gateway/deployment.yaml
+ - backend/deployment.yaml
+ - ui/deployment.yaml
+ asserts:
+ - contains:
+ path: spec.template.spec.containers[0].env
+ content:
+ name: SERVER_ROOT_PATH
+ value: /services/llm
+ - it: routes only prefixed paths when ingress is enabled
+ template: ingress.yaml
+ set:
+ ingress.enabled: true
+ serverRootPath: /services/llm
+ ingress.extraPaths:
+ - path: /custom-provider
+ asserts:
+ - equal:
+ path: spec.rules[0].http.paths[0].path
+ value: /services/llm
+ - contains:
+ path: spec.rules[0].http.paths
+ content:
+ path: /services/llm/ui
+ pathType: Prefix
+ backend:
+ service:
+ name: RELEASE-NAME-litellm-ui
+ port:
+ number: 3000
+ - contains:
+ path: spec.rules[0].http.paths
+ content:
+ path: /services/llm/
+ pathType: Exact
+ backend:
+ service:
+ name: RELEASE-NAME-litellm-ui
+ port:
+ number: 3000
+ - contains:
+ path: spec.rules[0].http.paths
+ content:
+ path: /services/llm/custom-provider
+ pathType: Prefix
+ backend:
+ service:
+ name: RELEASE-NAME-litellm-gateway
+ port:
+ number: 4000
+ - it: rejects traversal
+ template: ui/deployment.yaml
+ set:
+ serverRootPath: /services/../llm
+ asserts:
+ - failedTemplate:
+ errorMessage: serverRootPath must contain safe absolute path segments without traversal
diff --git a/helm/litellm/values.yaml b/helm/litellm/values.yaml
index aa6ee7a6056..f3a3deb291a 100644
--- a/helm/litellm/values.yaml
+++ b/helm/litellm/values.yaml
@@ -1,3 +1,5 @@
+serverRootPath: ""
+
# LiteLLM helm chart values
nameOverride: ""
@@ -198,7 +200,7 @@ billingMetrics:
caSecretName: "" # existing Secret holding ca.crt
exportIntervalMs: "" # push cadence; the proxy defaults to 60000
-# External Postgres connection.
+# External Postgres connection.
database:
writer:
host: ""
diff --git a/tests/integration/ui/test_ui_root_path.py b/tests/integration/ui/test_ui_root_path.py
new file mode 100644
index 00000000000..d2032bc8279
--- /dev/null
+++ b/tests/integration/ui/test_ui_root_path.py
@@ -0,0 +1,89 @@
+import hashlib
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+from typing import Final
+
+REPO: Final = Path(__file__).resolve().parents[3]
+
+
+class TestUIRootPath(unittest.TestCase):
+ def prepare(self, directory: Path, prefix: str) -> subprocess.CompletedProcess[str]:
+ return subprocess.run(
+ [
+ "sh",
+ str(REPO / "ui" / "prepare-root-path.sh"),
+ str(directory / "source"),
+ str(directory / "runtime"),
+ str(REPO / "ui" / "nginx.conf"),
+ str(directory / "nginx.conf"),
+ prefix,
+ ],
+ text=True,
+ capture_output=True,
+ )
+
+ def source(self, directory: Path) -> Path:
+ source: Final = directory / "source"
+ source.mkdir()
+ (source / "index.html").write_text(
+ '
'
+ ''
+ '
'
+ )
+ (source / "index.txt").write_text('[{"href":"/favicon.ico?version=1"}]')
+ (source / "app.js").write_text('fetch("/litellm/.well-known/litellm-ui-config")')
+ (source / "font.woff2").write_bytes(bytes(range(256)))
+ return source
+
+ def test_nested_prefix_preserves_original_export_and_binary_assets(self) -> None:
+ with tempfile.TemporaryDirectory() as tmp:
+ directory: Final = Path(tmp)
+ source: Final = self.source(directory)
+ original: Final = (source / "index.html").read_bytes()
+ self.assertEqual(self.prepare(directory, "/services/llm/").returncode, 0)
+ runtime: Final = directory / "runtime"
+ self.assertIn("/services/llm/_next/app.js", (runtime / "index.html").read_text())
+ self.assertIn(
+ 'name="litellm-server-root-path" content="/services/llm"', (runtime / "index.html").read_text()
+ )
+ self.assertIn('href="/services/llm/get_favicon"', (runtime / "index.html").read_text())
+ self.assertIn('href="/services/llm/favicon.ico?version=1"', (runtime / "index.html").read_text())
+ self.assertIn('src="/services/llm/ui/assets/logo.png"', (runtime / "index.html").read_text())
+ self.assertIn("/services/llm/favicon.ico?version=1", (runtime / "index.txt").read_text())
+ self.assertEqual(runtime.stat().st_mode & 0o005, 0o005)
+ self.assertEqual((runtime / "index.html").stat().st_mode & 0o004, 0o004)
+ self.assertEqual((runtime / "app.js").read_bytes(), (source / "app.js").read_bytes())
+ self.assertEqual((source / "index.html").read_bytes(), original)
+ self.assertEqual((runtime / "font.woff2").read_bytes(), (source / "font.woff2").read_bytes())
+ self.assertEqual(self.prepare(directory, "/services/llm/").returncode, 0)
+ self.assertNotIn("/services/llm/services/llm", (runtime / "app.js").read_text())
+ self.assertEqual(self.prepare(directory, "/other/path").returncode, 0)
+ self.assertIn("/other/path/_next/app.js", (runtime / "index.html").read_text())
+ self.assertNotIn("/services/llm", (runtime / "index.html").read_text())
+
+ def test_default_root_leaves_export_unchanged(self) -> None:
+ with tempfile.TemporaryDirectory() as tmp:
+ directory: Final = Path(tmp)
+ source: Final = self.source(directory)
+ self.assertEqual(self.prepare(directory, "/").returncode, 0)
+ self.assertEqual((directory / "runtime" / "app.js").read_bytes(), (source / "app.js").read_bytes())
+
+ def test_rejects_unsafe_roots_before_writing(self) -> None:
+ with tempfile.TemporaryDirectory() as tmp:
+ directory: Final = Path(tmp)
+ self.source(directory)
+ for prefix in ("relative", "/a/../b", "/a/./b", "/a//b", "/a|b", "/a?b", "/a\nb", "//", "/a//"):
+ with self.subTest(prefix=prefix):
+ self.assertNotEqual(self.prepare(directory, prefix).returncode, 0)
+ self.assertFalse((directory / "runtime").exists())
+
+ def test_source_can_be_read_only(self) -> None:
+ with tempfile.TemporaryDirectory() as tmp:
+ directory: Final = Path(tmp)
+ source: Final = self.source(directory)
+ (source / "app.js").chmod(0o444)
+ digest: Final = hashlib.sha256((source / "app.js").read_bytes()).hexdigest()
+ self.assertEqual(self.prepare(directory, "/services/llm").returncode, 0)
+ self.assertEqual(hashlib.sha256((source / "app.js").read_bytes()).hexdigest(), digest)
diff --git a/ui/Dockerfile b/ui/Dockerfile
index d78a155b874..706b17a5365 100644
--- a/ui/Dockerfile
+++ b/ui/Dockerfile
@@ -41,6 +41,11 @@ COPY ui/docker-entrypoint.d/40-litellm-runtime-config.sh /docker-entrypoint.d/
# Routing rules — see ui/nginx.conf for the full description.
COPY ui/nginx.conf /etc/nginx/nginx.conf
+COPY --chmod=755 ui/prepare-root-path.sh /usr/local/bin/prepare-ui-root-path
+COPY --chmod=755 ui/docker-entrypoint.sh /usr/local/bin/litellm-ui-entrypoint
+
+ENTRYPOINT ["/usr/local/bin/litellm-ui-entrypoint"]
+
EXPOSE 3000/tcp
# nginx as PID 1 in foreground; respects SIGTERM out of the box, so
diff --git a/ui/docker-entrypoint.sh b/ui/docker-entrypoint.sh
new file mode 100644
index 00000000000..ef843c137ca
--- /dev/null
+++ b/ui/docker-entrypoint.sh
@@ -0,0 +1,12 @@
+#!/bin/sh
+set -eu
+
+if [ "${1:-}" = nginx ] && [ -n "${SERVER_ROOT_PATH:-}" ] && [ "$SERVER_ROOT_PATH" != / ]; then
+ runtime_dir=$(mktemp -d /tmp/litellm-ui.XXXXXX)
+ /usr/local/bin/prepare-ui-root-path /usr/share/nginx/html "$runtime_dir" \
+ /etc/nginx/nginx.conf "$runtime_dir/nginx.conf" "$SERVER_ROOT_PATH"
+ shift
+ set -- nginx -c "$runtime_dir/nginx.conf" "$@"
+fi
+
+exec /docker-entrypoint.sh "$@"
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/hooks/useAuthorized.serverRootPath.test.ts b/ui/litellm-dashboard/src/app/(dashboard)/hooks/useAuthorized.serverRootPath.test.ts
index 228811ac37c..f294f9d880c 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/hooks/useAuthorized.serverRootPath.test.ts
+++ b/ui/litellm-dashboard/src/app/(dashboard)/hooks/useAuthorized.serverRootPath.test.ts
@@ -1,6 +1,6 @@
/* @vitest-environment jsdom */
import React from "react";
-import { renderHook, waitFor } from "@testing-library/react";
+import { act, renderHook, waitFor } from "@testing-library/react";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import useAuthorized from "./useAuthorized";
@@ -9,8 +9,6 @@ vi.unmock("@/app/(dashboard)/hooks/useAuthorized");
const replaceMock = vi.fn();
-const UI_CONFIG_DELAY_MS = 50;
-
const uiConfigResponse = {
server_root_path: "/llmproxy",
proxy_base_url: null,
@@ -19,13 +17,18 @@ const uiConfigResponse = {
sso_configured: false,
};
+let uiConfigGate = Promise.withResolvers();
+
const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
const url = typeof input === "string" ? input : input.toString();
- if (!url.includes("/litellm/.well-known/litellm-ui-config")) {
+ if (url.endsWith("/ui/litellm-runtime-config.json")) {
+ return { ok: false } as Response;
+ }
+ if (!url.endsWith("/.well-known/litellm-ui-config")) {
throw new Error(`unexpected fetch: ${url}`);
}
- await new Promise((resolve) => setTimeout(resolve, UI_CONFIG_DELAY_MS));
- return { ok: true, json: async () => uiConfigResponse } as unknown as Response;
+ const config = await uiConfigGate.promise;
+ return { ok: true, json: async () => config } as unknown as Response;
});
const wrapper = ({ children }: { children: React.ReactNode }) => {
@@ -37,6 +40,7 @@ describe("useAuthorized under SERVER_ROOT_PATH", () => {
const originalLocation = window.location;
beforeEach(() => {
+ uiConfigGate = Promise.withResolvers();
vi.stubGlobal("fetch", fetchMock);
Object.defineProperty(window, "location", {
value: {
@@ -62,6 +66,7 @@ describe("useAuthorized under SERVER_ROOT_PATH", () => {
it("sends an unauthenticated visitor to a login URL that keeps the server root path", async () => {
renderHook(() => useAuthorized(), { wrapper });
+ await act(async () => uiConfigGate.resolve(uiConfigResponse));
await waitFor(() => {
expect(replaceMock).toHaveBeenCalled();
@@ -77,8 +82,11 @@ describe("useAuthorized under SERVER_ROOT_PATH", () => {
renderHook(() => useAuthorized(), { wrapper });
expect(replaceMock).not.toHaveBeenCalled();
- await new Promise((resolve) => setTimeout(resolve, UI_CONFIG_DELAY_MS / 2));
+ await waitFor(() => {
+ expect(fetchMock).toHaveBeenCalledWith(expect.stringMatching(/\/\.well-known\/litellm-ui-config$/));
+ });
expect(replaceMock).not.toHaveBeenCalled();
+ await act(async () => uiConfigGate.resolve(uiConfigResponse));
await waitFor(() => {
expect(replaceMock).toHaveBeenCalled();
diff --git a/ui/litellm-dashboard/src/app/login/LoginPage.test.tsx b/ui/litellm-dashboard/src/app/login/LoginPage.test.tsx
index 6a61f5ed85f..2a81dda7199 100644
--- a/ui/litellm-dashboard/src/app/login/LoginPage.test.tsx
+++ b/ui/litellm-dashboard/src/app/login/LoginPage.test.tsx
@@ -1,6 +1,7 @@
import { describe, it, expect, vi, beforeEach } from "vitest";
-import { render, screen, waitFor } from "@testing-library/react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { setServerRootPath } from "@/lib/serverRootPath";
import LoginPage from "./LoginPage";
const mockPush = vi.fn();
@@ -69,6 +70,7 @@ const createQueryClient = () =>
describe("LoginPage", () => {
beforeEach(() => {
+ setServerRootPath("/");
vi.clearAllMocks();
mockPush.mockClear();
mockReplace.mockClear();
@@ -98,12 +100,16 @@ describe("LoginPage", () => {
});
});
- it("should call router.replace to dashboard when jwt is valid", async () => {
+ it.each([
+ ["/", "/ui"],
+ ["/services/llm/", "/services/llm/ui"],
+ ])("keeps valid-token navigation under %s", async (root, expectedPath) => {
+ setServerRootPath(root);
const validToken = "valid-token";
(useUIConfig as ReturnType).mockReturnValue({
data: {
auto_redirect_to_sso: false,
- server_root_path: "/",
+ server_root_path: root,
proxy_base_url: null,
sso_configured: false,
},
@@ -120,7 +126,7 @@ describe("LoginPage", () => {
);
await waitFor(() => {
- expect(mockReplace).toHaveBeenCalledWith("/ui");
+ expect(mockReplace).toHaveBeenCalledWith(expectedPath);
});
});
@@ -235,11 +241,15 @@ describe("LoginPage", () => {
expect(mockReplace).not.toHaveBeenCalled();
});
- it("should show Login with SSO button when sso_configured is true", async () => {
+ it.each([
+ ["/", "/ui/login/"],
+ ["/services/llm", "/services/llm/ui/login/"],
+ ])("returns SSO to the control plane UI under %s", async (root, expectedPath) => {
+ setServerRootPath(root);
(useUIConfig as ReturnType).mockReturnValue({
data: {
auto_redirect_to_sso: false,
- server_root_path: "/",
+ server_root_path: root,
proxy_base_url: null,
sso_configured: true,
},
@@ -259,7 +269,10 @@ describe("LoginPage", () => {
expect(screen.getByRole("heading", { name: "Login" })).toBeInTheDocument();
});
- expect(screen.getByRole("button", { name: "Login with SSO" })).toBeInTheDocument();
+ fireEvent.click(screen.getByRole("button", { name: "Login with SSO" }));
+ expect(mockPush).toHaveBeenCalledWith(
+ `http://localhost:4000/sso/key/generate?return_to=${encodeURIComponent(new URL(expectedPath, window.location.origin).href)}`,
+ );
});
it("should show disabled Login with SSO button with popover when sso_configured is false", async () => {
diff --git a/ui/litellm-dashboard/src/app/login/LoginPage.tsx b/ui/litellm-dashboard/src/app/login/LoginPage.tsx
index 10d8051232c..51cf697ce03 100644
--- a/ui/litellm-dashboard/src/app/login/LoginPage.tsx
+++ b/ui/litellm-dashboard/src/app/login/LoginPage.tsx
@@ -24,6 +24,7 @@ import { useZodForm } from "@/lib/forms/useZodForm";
import { clearTokenCookies, getCookieFromDocument } from "@/utils/cookieUtils";
import { isJwtExpired } from "@/utils/jwtUtils";
import { consumeReturnUrl, getLoginUrl, getReturnUrl, isValidReturnUrl } from "@/utils/returnUrlUtils";
+import { uiHref } from "@/utils/uiHref";
import { CircleAlert, Info, TriangleAlert, X } from "lucide-react";
import { useRouter } from "next/navigation";
import { useEffect, useId, useState } from "react";
@@ -108,7 +109,7 @@ function LoginPageContent() {
params.delete("code");
const cleanSearch = params.toString();
window.history.replaceState(null, "", window.location.pathname + (cleanSearch ? `?${cleanSearch}` : ""));
- router.replace("/ui/?login=success");
+ router.replace(`${uiHref("")}?login=success`);
});
return;
}
@@ -128,7 +129,7 @@ function LoginPageContent() {
if (returnUrl) {
router.replace(getUiPageUrl(returnUrl, true));
} else {
- router.replace("/ui");
+ router.replace(uiHref("").replace(/\/$/, ""));
}
return;
}
@@ -162,7 +163,7 @@ function LoginPageContent() {
if (selectedWorker) {
selectWorker(selectedWorker.worker_id);
// Stay on the CP's UI — proxyBaseUrl already points at the worker
- router.push("/ui/?login=success");
+ router.push(`${uiHref("")}?login=success`);
} else {
// Normal (non-control-plane) login — follow the server's redirect
const returnUrl = consumeReturnUrl(getRuntimeBackendBaseUrl());
@@ -344,7 +345,7 @@ function LoginPageContent() {
// SSO on the worker (or this instance if no worker), always
// include return_to so the callback redirects back here
const ssoBase = selectedWorker?.url ?? getProxyBaseUrl();
- const returnTo = encodeURIComponent(getLoginUrl(window.location.origin));
+ const returnTo = encodeURIComponent(new URL(getLoginUrl(), window.location.origin).href);
router.push(`${ssoBase}/sso/key/generate?return_to=${returnTo}`);
}}
className="w-full"
diff --git a/ui/litellm-dashboard/src/components/networking.test.ts b/ui/litellm-dashboard/src/components/networking.test.ts
index 8b0f0389772..364c480b48f 100644
--- a/ui/litellm-dashboard/src/components/networking.test.ts
+++ b/ui/litellm-dashboard/src/components/networking.test.ts
@@ -229,7 +229,7 @@ describe("UI config and public endpoints", () => {
};
const mockFetch = setupMockFetch([
- { url: "/litellm/.well-known/litellm-ui-config", data: uiConfig },
+ { url: "/.well-known/litellm-ui-config", data: uiConfig },
{ url: "/public/providers/fields", data: [] },
]);
@@ -255,7 +255,7 @@ describe("UI config and public endpoints", () => {
};
const mockFetch = setupMockFetch([
- { url: "/litellm/.well-known/litellm-ui-config", data: uiConfig },
+ { url: "/.well-known/litellm-ui-config", data: uiConfig },
{ url: "/public/model_hub/info", data: {} },
]);
@@ -278,7 +278,7 @@ describe("UI config and public endpoints", () => {
};
const mockFetch = setupMockFetch([
- { url: "/litellm/.well-known/litellm-ui-config", data: uiConfig },
+ { url: "/.well-known/litellm-ui-config", data: uiConfig },
{ url: "/public/model_hub", data: [] },
]);
@@ -301,7 +301,7 @@ describe("UI config and public endpoints", () => {
};
const mockFetch = setupMockFetch([
- { url: "/litellm/.well-known/litellm-ui-config", data: uiConfig },
+ { url: "/.well-known/litellm-ui-config", data: uiConfig },
{ url: "/public/agent_hub", data: [] },
]);
@@ -322,7 +322,7 @@ describe("UI config and public endpoints", () => {
};
const mockFetch = setupMockFetch([
- { url: "/litellm/.well-known/litellm-ui-config", data: uiConfig },
+ { url: "/.well-known/litellm-ui-config", data: uiConfig },
{ url: "/public/mcp_hub", data: [] },
]);
@@ -343,7 +343,7 @@ describe("UI config and public endpoints", () => {
};
const mockFetch = setupMockFetch([
- { url: "/litellm/.well-known/litellm-ui-config", data: uiConfig },
+ { url: "/.well-known/litellm-ui-config", data: uiConfig },
{ url: "/public/providers/fields", data: [] },
]);
@@ -365,14 +365,14 @@ describe("UI config and public endpoints", () => {
proxy_base_url: "https://example.com",
};
- const mockFetch = setupMockFetch([{ url: "/litellm/.well-known/litellm-ui-config", data: uiConfig }]);
+ const mockFetch = setupMockFetch([{ url: "/.well-known/litellm-ui-config", data: uiConfig }]);
const result = await Networking.getUiConfig();
expect(mockFetch).toHaveBeenCalledTimes(2);
expect(result).toEqual(uiConfig);
const configCall = mockFetch.mock.calls.find((call) =>
- (call[0] as string).includes("/litellm/.well-known/litellm-ui-config"),
+ (call[0] as string).endsWith("/.well-known/litellm-ui-config"),
);
expect(configCall).toBeDefined();
});
@@ -383,7 +383,7 @@ describe("UI config and public endpoints", () => {
proxy_base_url: "https://example.com",
};
- setupMockFetch([{ url: "/litellm/.well-known/litellm-ui-config", data: uiConfig }]);
+ setupMockFetch([{ url: "/.well-known/litellm-ui-config", data: uiConfig }]);
await Networking.getUiConfig();
@@ -397,7 +397,7 @@ describe("UI config and public endpoints", () => {
proxy_base_url: "https://backend.example.com",
gateway_base_url: "https://gateway.example.com",
};
- const mockFetch = setupMockFetch([{ url: "/litellm/.well-known/litellm-ui-config", data: uiConfig }]);
+ const mockFetch = setupMockFetch([{ url: "/.well-known/litellm-ui-config", data: uiConfig }]);
await Networking.getUiConfig();
expect(await Networking.testModelGroupConnection("token", "chat-model", "chat")).toEqual({ status: "success" });
@@ -415,7 +415,7 @@ describe("UI config and public endpoints", () => {
server_root_path: "",
proxy_base_url: "https://backend.example.com",
};
- const mockFetch = setupMockFetch([{ url: "/litellm/.well-known/litellm-ui-config", data: uiConfig }]);
+ const mockFetch = setupMockFetch([{ url: "/.well-known/litellm-ui-config", data: uiConfig }]);
await Networking.getUiConfig();
expect(await Networking.testModelGroupConnection("token", "embedding-model", "embedding")).toEqual({
@@ -1062,6 +1062,55 @@ describe("getUiConfig runtime backend discovery", () => {
return { networking, mockFetch };
};
+ it.each([
+ ["https://backend.example.com", "/services/llm"],
+ ["https://backend.example.com/api-prefix", "/services/llm"],
+ ["https://backend.example.com", "/services/llm/"],
+ ])("loads static configuration from backend %s under normalized UI prefix %s", async (backendBase, uiPrefix) => {
+ const mockFetch = vi
+ .fn()
+ .mockResolvedValueOnce({
+ ok: true,
+ json: async () => ({ backend_url: backendBase }),
+ } as Response)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: async () => ({ ...discoveryConfig(), server_root_path: "/services/llm" }),
+ } as Response);
+ vi.stubGlobal("fetch", mockFetch);
+ const networking = await loadFreshNetworking();
+ const { setServerRootPath } = await import("@/lib/serverRootPath");
+ setServerRootPath(uiPrefix);
+ networking.switchToWorkerUrl("https://worker.example.com/worker-mount");
+
+ await networking.getUiConfig();
+
+ expect(mockFetch).toHaveBeenNthCalledWith(1, "/services/llm/ui/litellm-runtime-config.json", {
+ cache: "no-store",
+ });
+ expect(mockFetch.mock.calls[1][0]).toBe(`${backendBase}/litellm/.well-known/litellm-ui-config`);
+ });
+
+ it("discovers the control plane under the UI prefix when no static backend is configured", async () => {
+ const mockFetch = vi
+ .fn()
+ .mockResolvedValueOnce({ ok: false } as Response)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: async () => ({ ...discoveryConfig(), server_root_path: "/services/llm" }),
+ } as Response);
+ vi.stubGlobal("fetch", mockFetch);
+ const networking = await loadFreshNetworking();
+ const { setServerRootPath } = await import("@/lib/serverRootPath");
+ setServerRootPath("/services/llm");
+ networking.switchToWorkerUrl("https://worker.example.com/worker-mount");
+
+ await networking.getUiConfig();
+
+ expect(mockFetch).toHaveBeenNthCalledWith(1, "/services/llm/ui/litellm-runtime-config.json", { cache: "no-store" });
+ expect(mockFetch).toHaveBeenNthCalledWith(2, "/services/llm/.well-known/litellm-ui-config");
+ });
+
it("uses a normalized runtime backend URL for discovery and the management fallback", async () => {
const mockFetch = vi
.fn()
diff --git a/ui/litellm-dashboard/src/components/networking.tsx b/ui/litellm-dashboard/src/components/networking.tsx
index 38d150f1d63..06f75725561 100644
--- a/ui/litellm-dashboard/src/components/networking.tsx
+++ b/ui/litellm-dashboard/src/components/networking.tsx
@@ -156,6 +156,7 @@ import {
registerBaseUrlGetter,
registerErrorHandler,
} from "@/lib/http/runtime";
+import { withServerRoot } from "@/lib/assetPaths";
import { serverRootPath, setServerRootPath } from "@/lib/serverRootPath";
export { serverRootPath };
@@ -566,7 +567,9 @@ export const getUiConfig = async () => {
: await (async (): Promise => {
try {
// eslint-disable-next-line no-restricted-syntax -- read the UI static config before the API origin is known
- const response = await fetch("/ui/litellm-runtime-config.json", { cache: "no-store" });
+ const response = await fetch(withServerRoot("/ui/litellm-runtime-config.json", serverRootPath), {
+ cache: "no-store",
+ });
if (!response.ok) return null;
const runtimeConfig: unknown = await response.json();
if (
@@ -584,9 +587,10 @@ export const getUiConfig = async () => {
})();
runtimeBackendBaseUrl = runtimeBackendUrl;
const discoveryBaseUrl = defaultProxyBaseUrl ?? runtimeBackendUrl;
+ const discoveryRoot = resolveApiBase({ serverRootPath }) || "/litellm";
const url = discoveryBaseUrl
? `${discoveryBaseUrl}/litellm/.well-known/litellm-ui-config`
- : `/litellm/.well-known/litellm-ui-config`;
+ : `${discoveryRoot}/.well-known/litellm-ui-config`;
const response = await fetch(url);
const jsonData: LiteLLMWellKnownUiConfig = await response.json();
/**
diff --git a/ui/litellm-dashboard/src/lib/serverRootPath.test.tsx b/ui/litellm-dashboard/src/lib/serverRootPath.test.tsx
new file mode 100644
index 00000000000..2613f8b2876
--- /dev/null
+++ b/ui/litellm-dashboard/src/lib/serverRootPath.test.tsx
@@ -0,0 +1,22 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+afterEach(() => {
+ document.head.innerHTML = "";
+ vi.resetModules();
+});
+
+describe("initial server root path", () => {
+ it("uses the root when runtime metadata is absent", async () => {
+ const { serverRootPath } = await import("./serverRootPath");
+ expect(serverRootPath).toBe("/");
+ });
+
+ it("uses image runtime metadata before backend configuration arrives", async () => {
+ document.head.innerHTML = '';
+ const { serverRootPath, setServerRootPath } = await import("./serverRootPath");
+ expect(serverRootPath).toBe("/services/llm");
+ setServerRootPath("/configured");
+ const updated = await import("./serverRootPath");
+ expect(updated.serverRootPath).toBe("/configured");
+ });
+});
diff --git a/ui/litellm-dashboard/src/lib/serverRootPath.ts b/ui/litellm-dashboard/src/lib/serverRootPath.ts
index 76eb9d629db..b1d2d6e67a2 100644
--- a/ui/litellm-dashboard/src/lib/serverRootPath.ts
+++ b/ui/litellm-dashboard/src/lib/serverRootPath.ts
@@ -5,7 +5,10 @@
* networking module. `networking` re-exports `serverRootPath` and updates it via
* `setServerRootPath` from its UI-config bootstrap.
*/
-export let serverRootPath = "/";
+export let serverRootPath =
+ typeof document === "undefined"
+ ? "/"
+ : document.querySelector('meta[name="litellm-server-root-path"]')?.content || "/";
export const setServerRootPath = (rootPath: string): void => {
serverRootPath = rootPath;
diff --git a/ui/litellm-dashboard/src/utils/returnUrlUtils.test.ts b/ui/litellm-dashboard/src/utils/returnUrlUtils.test.ts
index 4432a39a7b8..279bd2dfa45 100644
--- a/ui/litellm-dashboard/src/utils/returnUrlUtils.test.ts
+++ b/ui/litellm-dashboard/src/utils/returnUrlUtils.test.ts
@@ -1,5 +1,7 @@
// @vitest-environment jsdom
+import { setServerRootPath } from "@/lib/serverRootPath";
+
import {
buildLoginUrlWithReturn,
clearStoredReturnUrl,
@@ -37,6 +39,7 @@ describe("returnUrlUtils", () => {
});
afterEach(() => {
+ setServerRootPath("/");
// Restore original location
Object.defineProperty(window, "location", {
value: originalLocation,
@@ -103,6 +106,24 @@ describe("returnUrlUtils", () => {
});
describe("getLoginUrl", () => {
+ it("keeps a nested root in same-origin SSO return URLs", () => {
+ setServerRootPath("/services/llm/");
+ expect(getLoginUrl()).toBe("/services/llm/ui/login/");
+ expect(new URL(getLoginUrl(), "https://platform.example.com").href).toBe(
+ "https://platform.example.com/services/llm/ui/login/",
+ );
+ expect(getLoginUrl("https://platform.example.com/services/llm/")).toBe(
+ "https://platform.example.com/services/llm/ui/login/",
+ );
+ });
+
+ it("keeps worker mount paths independent of the control plane prefix", () => {
+ setServerRootPath("/services/llm");
+ expect(getLoginUrl("https://worker.example.com")).toBe("https://worker.example.com/ui/login/");
+ expect(getLoginUrl("https://worker.example.com/worker/")).toBe("https://worker.example.com/worker/ui/login/");
+ expect(getLoginUrl("/")).toBe("/ui/login/");
+ });
+
it("should build a relative login URL with a trailing slash", () => {
expect(getLoginUrl()).toBe("/ui/login/");
});
diff --git a/ui/litellm-dashboard/src/utils/returnUrlUtils.ts b/ui/litellm-dashboard/src/utils/returnUrlUtils.ts
index 0259aa8c2ec..5b94aeb24f7 100644
--- a/ui/litellm-dashboard/src/utils/returnUrlUtils.ts
+++ b/ui/litellm-dashboard/src/utils/returnUrlUtils.ts
@@ -1,3 +1,6 @@
+import { serverRootPath } from "@/lib/serverRootPath";
+import { resolveApiBase } from "@/lib/http/resolveApiBase";
+
/**
* Utility functions for managing return URLs during authentication flows.
*
@@ -14,7 +17,8 @@ const RETURN_URL_COOKIE_NAME = "litellm_return_url";
const RETURN_URL_PARAM = "redirect_to";
export function getLoginUrl(baseUrl: string = ""): string {
- return `${baseUrl}/ui/login/`;
+ const base = baseUrl.trim();
+ return `${base ? base.replace(/\/+$/, "") : resolveApiBase({ serverRootPath })}/ui/login/`;
}
export function normalizeBackendPageUrlToUiOrigin(
diff --git a/ui/prepare-root-path.sh b/ui/prepare-root-path.sh
new file mode 100644
index 00000000000..c609c5422c3
--- /dev/null
+++ b/ui/prepare-root-path.sh
@@ -0,0 +1,58 @@
+#!/bin/sh
+set -eu
+
+source_dir=$1
+runtime_dir=$2
+source_config=$3
+runtime_config=$4
+prefix=${5%/}
+
+case "$prefix" in
+ ""|/*) ;;
+ *) echo "SERVER_ROOT_PATH must start with /" >&2; exit 1 ;;
+esac
+case "$prefix" in
+ *[!a-zA-Z0-9_./~-]*|*//*|*/./*|*/../*|*/.|*/..|*/)
+ echo "SERVER_ROOT_PATH must contain safe path segments without traversal" >&2
+ exit 1
+ ;;
+esac
+
+mkdir -p "$runtime_dir"
+cp -R "$source_dir/." "$runtime_dir/"
+chmod -R u+rwX,go+rX "$runtime_dir"
+
+if [ -n "$prefix" ]; then
+ find "$runtime_dir" -type f \( -name '*.html' -o -name '*.js' -o -name '*.css' -o -name '*.txt' -o -name '*.json' \) \
+ -exec sh -eu -c '
+ prefix=$1
+ shift
+ for file do
+ sed -e "s|/litellm-asset-prefix|$prefix|g" \
+ -e "s|/favicon.ico|$prefix/favicon.ico|g" \
+ "$file" > "$file.tmp"
+ case "$file" in
+ *.html)
+ sed -e "s|||g" \
+ -e "s|src=\"/ui/assets/|src=\"$prefix/ui/assets/|g" \
+ -e "s|href=\"/get_favicon\"|href=\"$prefix/get_favicon\"|g" \
+ "$file.tmp" > "$file"
+ rm "$file.tmp"
+ ;;
+ *) mv "$file.tmp" "$file" ;;
+ esac
+ done
+ ' sh "$prefix" {} +
+fi
+
+escaped_runtime=$(printf '%s' "$runtime_dir" | sed 's/[\\&|]/\\&/g')
+escaped_prefix=$(printf '%s' "$prefix" | sed 's/\./\\\\./g')
+sed "s|/usr/share/nginx/html|$escaped_runtime|g" "$source_config" > "$runtime_config"
+if [ -n "$prefix" ]; then
+ sed "/server_name _;/a\\
+ absolute_redirect off;\\
+ rewrite ^$escaped_prefix\$ $prefix/ui/ redirect;\\
+ rewrite ^$escaped_prefix(/.*)\$ \$1 last;\\
+" "$runtime_config" > "$runtime_config.tmp"
+ mv "$runtime_config.tmp" "$runtime_config"
+fi