> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install LibreChat with Helm

> Install the LibreChat chart on Kubernetes, point it at the TrueFoundry gateway, and verify the gateway path and the first chat.

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](https://www.truefoundry.com/docs/ai-gateway/librechat/gateway-access.md) 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.

```bash theme={"dark"}
helm version --short
kubectl version --client
kubectl config 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:

```bash theme={"dark"}
git clone --depth 1 --branch v0.8.9 https://github.com/danny-avila/LibreChat.git
cd LibreChat/helm
helm dependency build librechat
helm package librechat -d ~/charts
```

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](https://www.truefoundry.com/docs/ai-gateway/librechat/operate.md#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.

```bash theme={"dark"}
kubectl create namespace librechat

kubectl -n librechat create secret generic librechat-credentials-env \
  --from-literal=CREDS_KEY="$(openssl rand -hex 32)" \
  --from-literal=CREDS_IV="$(openssl rand -hex 16)" \
  --from-literal=JWT_SECRET="$(openssl rand -hex 32)" \
  --from-literal=JWT_REFRESH_SECRET="$(openssl rand -hex 32)"
```

Expected output:

```text theme={"dark"}
secret/librechat-credentials-env created
```

Check the key names without printing the values:

```bash theme={"dark"}
kubectl -n librechat get secret librechat-credentials-env \
  -o jsonpath='{.data}' | python3 -c "import sys,json;print(sorted(json.load(sys.stdin)))"
```

Expected output:

```text theme={"dark"}
['CREDS_IV', 'CREDS_KEY', 'JWT_REFRESH_SECRET', 'JWT_SECRET']
```

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

```yaml filename="librechat.yaml" theme={"dark"}
version: 1.2.8
cache: true
endpoints:
  custom:
    - name: "TrueFoundry Gateway"
      apiKey: "${TFY_GATEWAY_KEY}"
      baseURL: "https://<tenant>/api/llm/v1"
      models:
        default: ["azure-openai-main/o4-mini"]
        fetch: true
      titleConvo: true
      titleModel: "current_model"
      modelDisplayLabel: "TrueFoundry Gateway"
```

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

| Field | What it does | Notes |
| - | - | - |
| `version` | The config schema version | Match it to your LibreChat release. This guide uses `1.2.8` with v0.8.9 |
| `cache` | Caches model lists in memory | Leave on for one replica |
| `endpoints.custom[].name` | The label in the model picker | Any name |
| `apiKey` | The key LibreChat sends to the gateway | `${TFY_GATEWAY_KEY}` is read from the environment at start-up. Never write the key inline |
| `baseURL` | The gateway's OpenAI-compatible base path | Ends in `/api/llm/v1`. Copy it from **Playground → Code Snippet** for your tenant |
| `models.default` | The models LibreChat offers | **Required when `fetch` is `true`.** Without it, LibreChat fails to start |
| `models.fetch` | Lists the gateway's models in the picker | Shows every model the gateway knows, not only the ones granted to this token. A listed model can still return `403` |
| `titleConvo`, `titleModel` | Titles each conversation with a model | `current_model` uses the conversation's model |
| `modelDisplayLabel` | The label on the model badge in the header | Any name |

### gw-values.yaml

```yaml filename="gw-values.yaml" theme={"dark"}
global:
  librechat:
    env:
      - name: TFY_GATEWAY_KEY
        valueFrom:
          secretKeyRef:
            name: librechat-gateway-key
            key: TFY_GATEWAY_KEY
```

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](https://www.truefoundry.com/docs/ai-gateway/librechat/gateway-access.md#store-the-token-in-the-cluster).

Check that both files parse:

```bash theme={"dark"}
python3 -c "import yaml; yaml.safe_load(open('librechat.yaml')); yaml.safe_load(open('gw-values.yaml')); print('yaml ok')"
```

Expected output: `yaml ok`. Each nested field sits two spaces to the right of its parent.

## Install the chart

```bash theme={"dark"}
helm upgrade --install librechat ~/charts/librechat-3.2.1.tgz \
  -n librechat \
  -f gw-values.yaml \
  --set-string librechat.existingSecretName=librechat-credentials-env \
  --set-file librechat.configYamlContent=librechat.yaml \
  --set ingress.enabled=false \
  --set meilisearch.enabled=false \
  --set-string librechat.configEnv.SCHEDULES_SINGLE_PROCESS=true \
  --timeout 8m
```

| Flag | Why |
| - | - |
| `-f gw-values.yaml` | Adds the gateway token from the secret |
| `librechat.existingSecretName` | Uses the app secret you created, instead of generating one |
| `librechat.configYamlContent` | Mounts `librechat.yaml` into the pod |
| `ingress.enabled=false` | No ingress in this guide. Reach LibreChat with a port-forward, or with your own ingress |
| `meilisearch.enabled=false` | Message search is off |
| `SCHEDULES_SINGLE_PROCESS=true` | Lets the scheduler start on one replica without Redis |
| `--timeout 8m` | The first start pulls the LibreChat and MongoDB images |

Wait for the rollout, then check the pods and volumes:

```bash theme={"dark"}
kubectl -n librechat rollout status deploy/librechat --timeout=5m
kubectl -n librechat get pods
kubectl -n librechat get pvc
```

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:

```bash theme={"dark"}
kubectl -n librechat logs deploy/librechat --tail=200 | grep -iE "mongo|TrueFoundry|error"
```

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:

```bash theme={"dark"}
POD=$(kubectl -n librechat get pods -l app.kubernetes.io/instance=librechat -o jsonpath='{.items[0].metadata.name}')
kubectl -n librechat exec "$POD" -- grep -n "default" /app/librechat.yaml
```

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**

```bash theme={"dark"}
kubectl -n librechat exec -it "$POD" -- node -e "
(async()=>{
  const r = await fetch('https://<tenant>/api/llm/v1/models', {
    headers: {'Authorization': 'Bearer ' + process.env.TFY_GATEWAY_KEY}
  });
  const j = await r.json();
  console.log('status', r.status);
  (j.data || []).forEach(m => console.log(m.id));
})()"
```

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**

```bash theme={"dark"}
kubectl -n librechat exec "$POD" -- node -e "
(async()=>{
  const r = await fetch('https://<tenant>/api/llm/v1/chat/completions', {
    method: 'POST',
    headers: {'Authorization': 'Bearer ' + process.env.TFY_GATEWAY_KEY, 'Content-Type': 'application/json'},
    body: JSON.stringify({model: 'azure-openai-main/o4-mini', messages: [{role: 'user', content: 'Reply with one short sentence: what is 2+2?'}], max_tokens: 50})
  });
  const t = await r.text();
  console.log(r.status, t.slice(0, 200).replace(/\s+/g, ' '));
})()"
```

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:

```bash theme={"dark"}
kubectl -n librechat port-forward svc/librechat 8080:3080
```

Open `http://localhost:8080`. Then check the configuration endpoint, which returns `200`:

```bash theme={"dark"}
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/api/config
```

Expected output: `200`. This version has no `/api/health` endpoint, and it returns `404`.

> [!NOTE]
>
> 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:

```bash theme={"dark"}
helm upgrade librechat ~/charts/librechat-3.2.1.tgz -n librechat --reuse-values \
  --set-string librechat.configEnv.ALLOW_REGISTRATION=true
```

> [!WARNING]
>
> 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.](https://mintcdn.com/truefoundry/fqJXGOrZ4JcvbYVx/images/ai-gateway/librechat-ui-login.jpg?fit=max\&auto=format\&n=fqJXGOrZ4JcvbYVx\&q=85\&s=4931ff28d7aa32381b568af1bc8c3140)

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.](https://mintcdn.com/truefoundry/fqJXGOrZ4JcvbYVx/images/ai-gateway/librechat-ui-conversation.jpg?fit=max\&auto=format\&n=fqJXGOrZ4JcvbYVx\&q=85\&s=f17d8dfb1895b4586caa51bf29f7b85f)

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](https://www.truefoundry.com/docs/ai-gateway/librechat/gateway-access.md#grant-a-model).

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.](https://mintcdn.com/truefoundry/fqJXGOrZ4JcvbYVx/images/ai-gateway/librechat-ui-new-chat.jpg?fit=max\&auto=format\&n=fqJXGOrZ4JcvbYVx\&q=85\&s=6b492e64ec9e670a2ab9cd158b444cd5)

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

## What's next

* To change the default model, rotate the token, or remove the release, see [Operate and troubleshoot](https://www.truefoundry.com/docs/ai-gateway/librechat/operate.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.