Environment Variables

LangWatch is configured through environment variables. How you set them depends on your deployment method:

Docker Compose: Set in your .env file
Helm chart: Set via values.yaml (the chart maps values to env vars automatically)
Raw Kubernetes: Set directly in your Deployment manifests

When using the Helm chart, you rarely need to set environment variables directly. The values.yaml file provides a structured way to configure everything. See the Helm chart mapping table below.

Core Configuration

Variable	Description	Required	Default
`DATABASE_URL`	PostgreSQL connection string	Yes	,
`CLICKHOUSE_URL`	ClickHouse HTTP connection string (e.g. `http://user:pass@host:8123/langwatch`)	Yes	,
`REDIS_URL`	Redis connection string	Yes	,
`NODE_ENV`	Environment (`production`, `development`)	No	`production`
`BASE_HOST`	Internal base URL for the application	Yes	,
`NEXTAUTH_URL`	Public URL for authentication callbacks	Yes	Same as `BASE_HOST`
`START_WORKERS`	Run workers in-process (`true`/`false`)	No	`false`

Secrets

Variable	Description	Required
`API_TOKEN_JWT_SECRET`	JWT signing key for API tokens	Yes
`CREDENTIALS_SECRET`	Encryption key for stored API keys and credentials	Yes
`NEXTAUTH_SECRET`	Session encryption key for NextAuth.js	Yes
`CRON_API_KEY`	API key for authenticating internal cron job HTTP calls	Yes

Never commit secrets to version control. In production, use a secrets manager (AWS Secrets Manager, HashiCorp Vault) or Kubernetes Secrets with secretKeyRef in the Helm chart.

Authentication

Variable	Description	Default
`NEXTAUTH_PROVIDER`	Auth provider: `email`, `google`, `github`, `gitlab`, `azureAd`, `cognito`, `okta`, `auth0`	`email`

SSO Provider Variables

Each SSO provider requires specific variables. See SSO Configuration for detailed setup guides. Auth0:

Variable	Description
`AUTH0_CLIENT_ID`	Auth0 application client ID
`AUTH0_CLIENT_SECRET`	Auth0 application client secret
`AUTH0_ISSUER`	Auth0 issuer URL (e.g. `https://your-tenant.auth0.com`)

Azure AD:

Variable	Description
`AZURE_AD_CLIENT_ID`	Azure AD application client ID
`AZURE_AD_CLIENT_SECRET`	Azure AD application client secret
`AZURE_AD_TENANT_ID`	Azure AD tenant ID

AWS Cognito:

Variable	Description
`COGNITO_CLIENT_ID`	Cognito user pool client ID
`COGNITO_CLIENT_SECRET`	Cognito user pool client secret
`COGNITO_ISSUER`	Cognito issuer URL

GitHub:

Variable	Description
`GITHUB_CLIENT_ID`	GitHub OAuth app client ID
`GITHUB_CLIENT_SECRET`	GitHub OAuth app client secret

GitLab:

Variable	Description
`GITLAB_CLIENT_ID`	GitLab OAuth app client ID
`GITLAB_CLIENT_SECRET`	GitLab OAuth app client secret

Google:

Variable	Description
`GOOGLE_CLIENT_ID`	Google OAuth client ID
`GOOGLE_CLIENT_SECRET`	Google OAuth client secret

Okta:

Variable	Description
`OKTA_CLIENT_ID`	Okta application client ID
`OKTA_CLIENT_SECRET`	Okta application client secret
`OKTA_ISSUER`	Okta issuer URL

Services

Variable	Description	Default
`LANGWATCH_NLP_SERVICE`	URL of the NLP service	`http://langwatch-nlp:5561`
`LANGEVALS_ENDPOINT`	URL of the LangEvals service	`http://langevals:5562`

Object Storage (S3)

The dataplane S3 bucket is the general file-storage layer for all externalized byte content. Current consumers:

Stored objects — externalized byte content (audio, image, video, document) extracted from incoming events and dataset uploads. Bytes are content-addressed under {projectId}/{sha256} and served back via GET /api/files/:id.
Dataset uploads — persists rows uploaded through the dataset UI. Shares the same S3_BUCKET_NAME bucket.

When S3_BUCKET_NAME is set, all consumers use that bucket. When it is not set, stored-objects fall back to the local filesystem at LANGWATCH_LOCAL_STORAGE_PATH — fine for single-replica installs, not for horizontally-scaled deployments (see warning below).

Variable	Description	Default
`S3_BUCKET_NAME`	Dataplane bucket shared by datasets + stored-objects	—
`S3_ENDPOINT`	Custom S3 endpoint (for MinIO, etc.)	—
`S3_ACCESS_KEY_ID`	S3 access key ID	—
`S3_SECRET_ACCESS_KEY`	S3 secret access key	—
`S3_KEY_SALT`	Optional key salt for S3 object keys	—
`LANGWATCH_LOCAL_STORAGE_PATH`	Filesystem root used for stored-objects when no S3 is configured	`/var/lib/langwatch/objects`

When running on AWS with IRSA (IAM Roles for Service Accounts), you don’t need to set S3 access keys. The pod’s service account will assume the IAM role automatically.

LANGWATCH_LOCAL_STORAGE_PATH is single-replica only. Multi-pod Kubernetes deployments must NOT rely on it: pods do not share a local filesystem, so a write from pod A is invisible to pod B and bytes vanish on every pod restart. Single-replica self-host installs (small footprints, hobbyist / air-gapped / pre-pilot deployments) can use it safely — the Helm chart refuses to render localFilesystem.enabled=true together with replicaCount > 1 so the misconfiguration can’t reach a cluster. Use S3_BUCKET_NAME (or the equivalent Helm app.dataplane.enabled toggle) for any horizontally-scaled deployment.

Email

Variable	Description	Default
`EMAIL_ENABLED`	Enable email notifications	`false`
`EMAIL_PROVIDER`	Email provider (`sendgrid`)	`sendgrid`
`SENDGRID_API_KEY`	SendGrid API key	,
`EMAIL_DEFAULT_FROM`	Default “from” address	,

Evaluator Providers

Variable	Description	Default
`AZURE_OPENAI_EVALUATOR_ENABLED`	Enable Azure OpenAI for evaluations	`false`
`AZURE_OPENAI_EVALUATOR_ENDPOINT`	Azure OpenAI endpoint URL	,
`AZURE_OPENAI_EVALUATOR_API_KEY`	Azure OpenAI API key	,
`GOOGLE_EVALUATOR_ENABLED`	Enable Google AI for evaluations (PII detection)	`false`
`GOOGLE_CREDENTIALS_JSON`	Google service account credentials JSON	,

Feature Flags

Variable	Description	Default
`SKIP_ENV_VALIDATION`	Skip environment variable validation on startup	`false`
`SKIP_PRISMA_MIGRATE`	Skip PostgreSQL migrations on startup	`false`

Telemetry

Variable	Description	Default
`DISABLE_USAGE_STATS`	Disable anonymous usage analytics	`false`
`SENTRY_DSN`	Sentry DSN for error tracking	,
`METRICS_API_KEY`	API key for metrics collection	,

Helm Chart Mapping

When using the Helm chart, configuration is set in values.yaml rather than environment variables directly. Here’s how key values map:

Helm Value	Environment Variable
`app.http.baseHost`	`BASE_HOST`
`app.http.publicUrl`	`NEXTAUTH_URL`
`app.nextAuth.provider`	`NEXTAUTH_PROVIDER`
`app.nextAuth.secret.value`	`NEXTAUTH_SECRET`
`app.credentialsEncryptionKey.value`	`CREDENTIALS_SECRET`
`app.cronApiKey.value`	`CRON_API_KEY`
`app.features.skipEnvValidation`	`SKIP_ENV_VALIDATION`
`app.email.enabled`	`EMAIL_ENABLED`
`app.email.provider`	`EMAIL_PROVIDER`
`app.email.providers.sendgrid.apiKey.value`	`SENDGRID_API_KEY`
`app.evaluators.azureOpenAI.enabled`	`AZURE_OPENAI_EVALUATOR_ENABLED`
`app.evaluators.azureOpenAI.endpoint.value`	`AZURE_OPENAI_EVALUATOR_ENDPOINT`
`app.evaluators.azureOpenAI.apiKey.value`	`AZURE_OPENAI_EVALUATOR_API_KEY`
`app.evaluators.google.enabled`	`GOOGLE_EVALUATOR_ENABLED`
`app.evaluators.google.credentials.value`	`GOOGLE_CREDENTIALS_JSON`
`app.telemetry.usage.enabled`	Inverse of `DISABLE_USAGE_STATS`
`app.dataplane.enabled`	`USE_S3_STORAGE`
`app.dataplane.bucket`	`S3_BUCKET_NAME`
`postgresql.external.connectionString.value`	`DATABASE_URL`
`redis.external.connectionString.value`	`REDIS_URL`
`workers.enabled`	Inverse of `START_WORKERS`

For production, use secretKeyRef instead of inline values. This references a Kubernetes Secret:

app:
  credentialsEncryptionKey:
    secretKeyRef:
      name: langwatch-secrets
      key: credentialsEncryptionKey

Overview

Configuration

Deployment

Infrastructure

Operations

Ops Console

Environment Variables

Core Configuration

Secrets

Authentication

SSO Provider Variables

Services

Object Storage (S3)

Email

Evaluator Providers

Feature Flags

Telemetry

Helm Chart Mapping

​Core Configuration

​Secrets

​Authentication

​SSO Provider Variables

​Services

​Object Storage (S3)

​Email

​Evaluator Providers

​Feature Flags

​Telemetry

​Helm Chart Mapping

Core Configuration

Secrets

Authentication

SSO Provider Variables

Services

Object Storage (S3)

Email

Evaluator Providers

Feature Flags

Telemetry

Helm Chart Mapping