Skip to main content
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

VariableDescriptionRequiredDefault
DATABASE_URLPostgreSQL connection stringYes—
CLICKHOUSE_URLClickHouse HTTP connection string (e.g. http://user:pass@host:8123/langwatch)Yes—
REDIS_URLRedis connection stringYes—
NODE_ENVEnvironment (production, development)Noproduction
BASE_HOSTInternal base URL for the applicationYes—
NEXTAUTH_URLPublic URL for authentication callbacksYesSame as BASE_HOST
START_WORKERSRun workers in-process (true/false)Nofalse

​
Secrets

VariableDescriptionRequired
API_TOKEN_JWT_SECRETJWT signing key for API tokensYes
CREDENTIALS_SECRETEncryption key for stored API keys and credentialsYes
NEXTAUTH_SECRETSession encryption key for NextAuth.jsYes
CRON_API_KEYAPI key for authenticating internal cron job HTTP callsYes
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

VariableDescriptionDefault
NEXTAUTH_PROVIDERAuth provider: email, google, github, gitlab, azureAd, cognito, okta, auth0email

​
SSO Provider Variables

Each SSO provider requires specific variables. See SSO Configuration for detailed setup guides. Auth0:
VariableDescription
AUTH0_CLIENT_IDAuth0 application client ID
AUTH0_CLIENT_SECRETAuth0 application client secret
AUTH0_ISSUERAuth0 issuer URL (e.g. https://your-tenant.auth0.com)
Azure AD:
VariableDescription
AZURE_AD_CLIENT_IDAzure AD application client ID
AZURE_AD_CLIENT_SECRETAzure AD application client secret
AZURE_AD_TENANT_IDAzure AD tenant ID
AWS Cognito:
VariableDescription
COGNITO_CLIENT_IDCognito user pool client ID
COGNITO_CLIENT_SECRETCognito user pool client secret
COGNITO_ISSUERCognito issuer URL
GitHub:
VariableDescription
GITHUB_CLIENT_IDGitHub OAuth app client ID
GITHUB_CLIENT_SECRETGitHub OAuth app client secret
GitLab:
VariableDescription
GITLAB_CLIENT_IDGitLab OAuth app client ID
GITLAB_CLIENT_SECRETGitLab OAuth app client secret
Google:
VariableDescription
GOOGLE_CLIENT_IDGoogle OAuth client ID
GOOGLE_CLIENT_SECRETGoogle OAuth client secret
Okta:
VariableDescription
OKTA_CLIENT_IDOkta application client ID
OKTA_CLIENT_SECRETOkta application client secret
OKTA_ISSUEROkta issuer URL

​
Services

VariableDescriptionDefault
LANGWATCH_NLP_SERVICEURL of the NLP servicehttp://langwatch-nlp:5561
LANGEVALS_ENDPOINTURL of the LangEvals servicehttp://langevals:5562

​
Object Storage (S3)

VariableDescriptionDefault
DATASET_OBJECT_STORAGE_ENABLEDEnable S3 for dataset storagefalse
DATASET_OBJECT_STORAGE_PROVIDERStorage provider (awsS3)awsS3
DATASET_OBJECT_STORAGE_BUCKETS3 bucket namelangwatch-dataset
S3_ENDPOINTCustom S3 endpoint (for MinIO, etc.)—
S3_ACCESS_KEY_IDS3 access key ID—
S3_SECRET_ACCESS_KEYS3 secret access key—
S3_KEY_SALTOptional key salt for S3 object keys—
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.

​
Email

VariableDescriptionDefault
EMAIL_ENABLEDEnable email notificationsfalse
EMAIL_PROVIDEREmail provider (sendgrid)sendgrid
SENDGRID_API_KEYSendGrid API key—
EMAIL_DEFAULT_FROMDefault “from” address—

​
Evaluator Providers

VariableDescriptionDefault
AZURE_OPENAI_EVALUATOR_ENABLEDEnable Azure OpenAI for evaluationsfalse
AZURE_OPENAI_EVALUATOR_ENDPOINTAzure OpenAI endpoint URL—
AZURE_OPENAI_EVALUATOR_API_KEYAzure OpenAI API key—
GOOGLE_EVALUATOR_ENABLEDEnable Google AI for evaluations (PII detection)false
GOOGLE_CREDENTIALS_JSONGoogle service account credentials JSON—

​
Feature Flags

VariableDescriptionDefault
SKIP_ENV_VALIDATIONSkip environment variable validation on startupfalse
DISABLE_PII_REDACTIONDisable automatic PII redaction in tracesfalse
SKIP_PRISMA_MIGRATESkip PostgreSQL migrations on startupfalse

​
Telemetry

VariableDescriptionDefault
DISABLE_USAGE_STATSDisable anonymous usage analyticsfalse
SENTRY_DSNSentry DSN for error tracking—
METRICS_API_KEYAPI 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 ValueEnvironment Variable
app.http.baseHostBASE_HOST
app.http.publicUrlNEXTAUTH_URL
app.nextAuth.providerNEXTAUTH_PROVIDER
app.nextAuth.secret.valueNEXTAUTH_SECRET
app.credentialsEncryptionKey.valueCREDENTIALS_SECRET
app.cronApiKey.valueCRON_API_KEY
app.features.skipEnvValidationSKIP_ENV_VALIDATION
app.features.disablePiiRedactionDISABLE_PII_REDACTION
app.email.enabledEMAIL_ENABLED
app.email.providerEMAIL_PROVIDER
app.email.providers.sendgrid.apiKey.valueSENDGRID_API_KEY
app.evaluators.azureOpenAI.enabledAZURE_OPENAI_EVALUATOR_ENABLED
app.evaluators.azureOpenAI.endpoint.valueAZURE_OPENAI_EVALUATOR_ENDPOINT
app.evaluators.azureOpenAI.apiKey.valueAZURE_OPENAI_EVALUATOR_API_KEY
app.evaluators.google.enabledGOOGLE_EVALUATOR_ENABLED
app.evaluators.google.credentials.valueGOOGLE_CREDENTIALS_JSON
app.telemetry.usage.enabledInverse of DISABLE_USAGE_STATS
app.datasetObjectStorage.enabledDATASET_OBJECT_STORAGE_ENABLED
app.datasetObjectStorage.bucketDATASET_OBJECT_STORAGE_BUCKET
postgresql.external.connectionString.valueDATABASE_URL
redis.external.connectionString.valueREDIS_URL
workers.enabledInverse of START_WORKERS
For production, use secretKeyRef instead of inline values. This references a Kubernetes Secret:
app:
  credentialsEncryptionKey:
    secretKeyRef:
      name: langwatch-secrets
      key: credentialsEncryptionKey