From 15c7ce059a3cba19c7a3dddb46cab950c46f295e Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Wed, 24 Jun 2026 22:08:58 +0000 Subject: [PATCH] docs: document LOCALAI_BASE_URL and reverse-proxy headers Refs #10482 Assisted-by: Claude:claude-opus-4-8 Signed-off-by: Ettore Di Giacinto --- docs/content/advanced/reverse-proxy-tls.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/content/advanced/reverse-proxy-tls.md b/docs/content/advanced/reverse-proxy-tls.md index 24af55c62..d36a64ae4 100644 --- a/docs/content/advanced/reverse-proxy-tls.md +++ b/docs/content/advanced/reverse-proxy-tls.md @@ -14,6 +14,26 @@ When running LocalAI behind a TLS termination reverse proxy, the Web UI may fail LocalAI uses the `X-Forwarded-Proto` HTTP header to determine the protocol used by clients. When this header is set to `https`, LocalAI will generate HTTPS URLs for static assets in the Web UI. +## Running behind a reverse proxy (HTTPS / subpath) + +LocalAI does not terminate TLS itself, so HTTPS is provided by a reverse +proxy in front of it. Self-referential links (generated image and video +URLs, async job status URLs, OAuth callbacks) need the externally visible +scheme, host and port. + +LocalAI determines these in this order: + +1. `LOCALAI_BASE_URL` - if set, it is authoritative for the origin. Set it to + the externally visible base URL, e.g. `LOCALAI_BASE_URL=https://localai.example.com` + or `https://192.168.0.13:34567`. Recommended whenever links come back with + the wrong scheme or host. +2. Otherwise, the `X-Forwarded-Proto` and `X-Forwarded-Host` headers (or the + RFC 7239 `Forwarded` header) sent by the proxy. Ensure your proxy forwards + `X-Forwarded-Proto: https`. + +A reverse-proxy subpath mount is supported via `X-Forwarded-Prefix`; it is +appended to `LOCALAI_BASE_URL` when both are present. + ## Required Headers Your reverse proxy must forward these headers to LocalAI: