Skip to main content
This page installs LibreChat with Helm, then checks each part of the path in order: the gateway’s model list, a granted completion, an ungranted completion, and the browser sign-in. Complete Gateway access first. You need the virtual-account token and one granted model ID.

Before you start

Confirm the tools and the cluster context. Every command below runs against the current context.
The output shows a Helm 3 version, a kubectl version, and the context for the cluster you intend to use. If the context is wrong, switch to the right one before you continue.

Build the chart

The chart is in the LibreChat repository under helm/librechat. Clone the release you are deploying, then package the chart from a clean copy:
The result is ~/charts/librechat-3.2.1.tgz. Package from a clean copy. A .cache or .kube directory inside the chart folder enlarges the release secret, and Helm rejects the install with Request entity too large (see Troubleshooting).

Create the namespace and the app secret

LibreChat keeps four app secrets: two keys that encrypt stored credentials and two JWT secrets. Generate them when you create the secret. Do not write them into a values file or a chart.
Expected output:
Check the key names without printing the values:
Expected output:
To enable Meilisearch later, add MEILI_MASTER_KEY to this secret. This guide leaves Meilisearch off.

Write the configuration

LibreChat needs two files:
  • librechat.yaml is LibreChat’s own configuration. The chart mounts it into the pod.
  • gw-values.yaml is the Helm values file. It adds the gateway token to the pod’s environment, read from the secret.

librechat.yaml

Replace <tenant> with your control-plane host. Set models.default to a model you granted, in its provider-qualified form.

gw-values.yaml

This adds one environment variable to the LibreChat pod. Its value comes from the secret librechat-gateway-key, key TFY_GATEWAY_KEY, which you created in Gateway access. Check that both files parse:
Expected output: yaml ok. Each nested field sits two spaces to the right of its parent.

Install the chart

Wait for the rollout, then check the pods and volumes:
Expected: the rollout finishes, one LibreChat pod and one MongoDB pod show 1/1 Running, and the volume claims show Bound. Old pods from an earlier revision can show Completed for a while. Check the logs for the gateway endpoint:
You should see Connected to MongoDB, the custom endpoint TrueFoundry Gateway with your baseURL, and no ZodError. The line RAG API is either not running or not reachable is expected: this guide disables the RAG subchart. Confirm that the pod loaded your default model:
The output includes your models.default value.

Verify the gateway path

Run these checks in order. Each one isolates one part of the path, so a failure points to the part to fix. The LibreChat image has no curl. Run the checks with Node, which the image includes. The script reads the token from the pod’s environment, so the token never appears in the command.
1

List the models your token can see

Expected: status 200, then one provider-qualified model ID per line. Copy the ID you granted. This list can include models the token cannot call. The next two checks decide which ones it can.
2

Send a request to a granted model

Replace azure-openai-main/o4-mini with the model you granted.Expected: 200, with a completion in the response body.
3

Send a request to a model you did not grant

Run the same command with a model ID that the token has no grant for.Expected: 403, with a message that names the virtual account and the model. A 403 on an ungranted model is the correct result. An ungranted model must never return 200.
4

Open LibreChat in a browser

Forward the service to your machine:
Open http://localhost:8080. Then check the configuration endpoint, which returns 200:
Expected output: 200. This version has no /api/health endpoint, and it returns 404.
LibreChat rejects requests that lack a browser User-Agent with Illegal request. If your script sends requests to the LibreChat API, set a browser-like User-Agent header. The browser needs no change.

Sign in and send the first message

LibreChat ships with registration off. To create the first user for an evaluation, turn registration on for the install, create the account, then turn it off:
Turn registration off again after you create the users. Set ALLOW_REGISTRATION to false with the same command. Leave it on only for the evaluation.
Sign-up can ask you to verify an email address. Configure email delivery before you rely on self-service sign-up.
The sign-in page on the local port-forward address.

The sign-in page on the local port-forward address.

Sign in, open the model picker in the header, and choose TrueFoundry Gateway. Then choose the model you granted, for example azure-openai-main/o4-mini. Send a short message.
A reply from azure-openai-main/o4-mini, returned through the gateway.

A reply from azure-openai-main/o4-mini, returned through the gateway.

The badge in the header shows the provider-qualified model that answered. If it shows a different model, the request did not use the grant you set. Check the grants in Gateway access. If you open a new chat before the header has a model selected, LibreChat shows Unable to load this chat’s model or agent. Select a model in the header, then send the message.
A new chat before a model is selected in the header.

A new chat before a model is selected in the header.

What’s next