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

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.

2. The process answers in-cluster

kubectl -n langwatch run curl --rm -it --image=curlimages/curl --restart=Never \
  -- curl -sS http://langwatch-gateway/healthz

Expected:

{ "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.

3. The gateway reaches the control plane

kubectl -n langwatch run curl --rm -it --image=curlimages/curl --restart=Never \
  -- curl -sS http://langwatch-gateway/health

Expected:

{ "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:

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

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.

5. Authentication rejects a missing key

curl -si https://gateway.acme.com/v1/models

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

{
  "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 and Virtual keys.

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

curl -sS https://gateway.acme.com/v1/chat/completions \
  -H "Authorization: Bearer $LW_VK" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-5-mini","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.

Then confirm the request produced a spend record:

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.

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 bound to this gateway.

What to read next

• Config: every environment variable and its default.
• Health checks: probe semantics and the status endpoint.
• Scaling: replicas, autoscaling and per-pod caches.
• Admin setup: routing policies and budgets for the whole organization.