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

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.

# Post-install checklist

> Verify a self-hosted LangWatch AI Gateway with curl, from the pod to a completed chat request.

Run these checks in order after `helm install`. Each one builds on the previous one, so the first failure tells you which layer to fix. The commands assume the release name `langwatch` and the namespace `langwatch`.

## 1. The pod is running

```bash theme={null}
kubectl -n langwatch rollout status deploy/langwatch-gateway
kubectl -n langwatch logs deploy/langwatch-gateway --tail 50
```

Expected: `deployment "langwatch-gateway" successfully rolled out`, and a log line `aigateway_starting` with `addr: ":5563"`.

A pod in `CreateContainerConfigError` is missing the Secret or one of its keys. See [Helm chart](https://langwatch.ai/docs/ai-gateway/self-hosting/helm.md#common-failures).

## 2. The process answers in-cluster

```bash theme={null}
kubectl -n langwatch run curl --rm -it --image=curlimages/curl --restart=Never \
  -- curl -sS http://langwatch-gateway/healthz
```

Expected:

```json theme={null}
{ "status": "ok", "version": "local", "uptime_s": 42.1 }
```

`version` carries the `ENVIRONMENT` value, `local` unless you set it.

This probe reaches the gateway because `networkPolicy.enabled` is `false` by default. With the network policy on, the gateway admits only the selectors in `networkPolicy.ingressFrom`, and this pod is not one of them. Add a selector for the probe pod to `ingressFrom` to run it.

The chart Ingress is no way around this: it publishes `/v1` and `/health` only, so `/healthz` does not answer through it. To check the process from outside the cluster, use `/health` and read step 3, which covers what its `control_plane` field means. To reach `/healthz` from outside, add your own route to the gateway Service for it, as described in [Routing and ingress controllers](https://langwatch.ai/docs/self-hosting/deployment/routing.md).

## 3. The gateway reaches the control plane

```bash theme={null}
kubectl -n langwatch run curl --rm -it --image=curlimages/curl --restart=Never \
  -- curl -sS http://langwatch-gateway/health
```

Expected:

```json theme={null}
{ "status": "ok", "checks": { "gateway": "ok", "control_plane": "ok" } }
```

A `503` with `"control_plane":"unreachable for Ns"` means one of two things: the gateway cannot reach `LW_GATEWAY_BASE_URL`, or `LW_GATEWAY_INTERNAL_SECRET` differs between the app and the gateway pods. The probe runs every 15 seconds and the verdict flips after 60 seconds without a success, so wait one minute after a fix before you read it again. The log line `statusprobe_control_plane_unreachable` on the gateway pod carries the underlying error.

Confirm which control plane URL the pod resolved:

```bash theme={null}
kubectl -n langwatch run curl --rm -it --image=curlimages/curl --restart=Never \
  -- curl -sS http://langwatch-gateway/debug/control-plane
```

Expected: `{"control_plane_base_url":"http://langwatch-app:5560"}`.

## 4. The public hostname serves TLS

```bash theme={null}
curl -sS https://gateway.acme.com/health
```

Expected: the same `{"status":"ok",...}` body as step 3. A certificate error means the `gateway-tls` Secret is not issued yet; see [DNS and TLS](https://langwatch.ai/docs/ai-gateway/self-hosting/dns-and-tls.md).

## 5. Authentication rejects a missing key

```bash theme={null}
curl -si https://gateway.acme.com/v1/models
```

Expected: `HTTP/2 401`, an `X-LangWatch-Gateway-Version` header, and this body:

```json theme={null}
{
  "error": {
    "type": "invalid_api_key",
    "code": "invalid_api_key",
    "message": "missing API key; supply Authorization: Bearer <key>, x-api-key, x-goog-api-key, or xi-api-key header"
  }
}
```

## 6. A virtual key lists models

Add a model provider credential and create a virtual key in the LangWatch UI. See [Providers](https://langwatch.ai/docs/ai-gateway/providers/overview.md) and [Virtual keys](https://langwatch.ai/docs/ai-gateway/virtual-keys.md).

```bash theme={null}
export LW_VK=vk-lw-YOUR_VIRTUAL_KEY

curl -sS https://gateway.acme.com/v1/models \
  -H "Authorization: Bearer $LW_VK"
```

Expected: a `200` with a `data` array of models the key can route to.

## 7. A completion goes through

```bash theme={null}
curl -sS https://gateway.acme.com/v1/chat/completions \
  -H "Authorization: Bearer $LW_VK" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-6-luna","messages":[{"role":"user","content":"ping"}]}'
```

Expected: a `chat.completion` object from the provider. The response carries `X-LangWatch-Gateway-Request-Id`, the id to search for in [Trace Explorer](https://langwatch.ai/docs/ai-gateway/observability.md).

Then confirm the request produced a spend record:

```bash theme={null}
kubectl -n langwatch port-forward deploy/langwatch-gateway 9464:9464 &
curl -sS -H "Authorization: Bearer $METRICS_API_KEY" http://localhost:9464/metrics | grep -E 'gateway_spend_spool_appended_total|gateway_spend_spool_dropped_total'
```

Expected: `gateway_spend_spool_appended_total` is at least 1 and `gateway_spend_spool_dropped_total` is 0.

## 8. The control plane knows the public URL

The control plane hands the gateway URL to CLI users at sign-in. It reads `LW_GATEWAY_PUBLIC_URL`, which the chart sets from `gateway.publicUrl` or derives from `ingress.gateway.host` when the app Ingress is enabled.

```bash theme={null}
kubectl -n langwatch get deploy langwatch-app \
  -o jsonpath='{.spec.template.spec.containers[0].env[?(@.name=="LW_GATEWAY_PUBLIC_URL")].value}'
```

Expected: `https://gateway.acme.com`. An empty result means the install has neither `ingress.gateway.host` nor `gateway.publicUrl`. Set one and upgrade.

Members can then sign in from the CLI and get a [personal key](https://langwatch.ai/docs/ai-gateway/governance/personal-keys.md) bound to this gateway.

## What to read next

* [Config](https://langwatch.ai/docs/ai-gateway/self-hosting/config.md): every environment variable and its default.
* [Health checks](https://langwatch.ai/docs/ai-gateway/self-hosting/health-checks.md): probe semantics and the status endpoint.
* [Scaling](https://langwatch.ai/docs/ai-gateway/self-hosting/scaling.md): replicas, autoscaling and per-pod caches.
* [Admin setup](https://langwatch.ai/docs/ai-gateway/governance/admin-setup.md): routing policies and budgets for the whole organization.


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