Version: v4
Environment Variables
Langfuse (self-hosted) has extensive configuration options via environment variables. These need to be passed to all application containers.
| Variable | Required / Default | Description |
|---|---|---|
DATABASE_URL | Required | Connection string of your Postgres database. Instead of DATABASE_URL, you can also use DATABASE_HOST, DATABASE_USERNAME, DATABASE_PASSWORD, DATABASE_NAME, and DATABASE_ARGS. |
DIRECT_URL | DATABASE_URL | Connection string of your Postgres database used for database migrations. Use this if you want to use a different user for migrations or use connection pooling on DATABASE_URL. For large deployments, configure the database user with long timeouts as migrations might need a while to complete. |
SHADOW_DATABASE_URL | If your database user lacks the CREATE DATABASE permission, you must create a shadow database and configure the "SHADOW_DATABASE_URL". This is often the case if you use a Cloud database. Refer to the Prisma docs for detailed instructions. | |
CLICKHOUSE_MIGRATION_URL | Required | Migration URL (TCP protocol) for the clickhouse instance. Pattern: clickhouse://<hostname>:(9000/9440) |
CLICKHOUSE_MIGRATION_SSL | false | Set to true to establish an SSL connection to Clickhouse for the database migration. |
CLICKHOUSE_URL | Required | Hostname of the clickhouse instance. Pattern: http(s)://<hostname>:(8123/8443) |
CLICKHOUSE_USER | Required | Username of the clickhouse database. Needs the grants listed under user permissions. |
CLICKHOUSE_PASSWORD | Required | Password of the clickhouse user. |
CLICKHOUSE_DB | default | Name of the ClickHouse database to use. |
CLICKHOUSE_CLUSTER_ENABLED | true | Whether to run ClickHouse commands ON CLUSTER. Set to false for single-container setups. |
LANGFUSE_AUTO_CLICKHOUSE_MIGRATION_DISABLED | false | Whether to disable automatic ClickHouse migrations on startup. |
CLICKHOUSE_READ_ONLY_URL | Optional read-only endpoint used for UI and public-API read queries on traces, observations, scores, and sessions. Falls back to CLICKHOUSE_URL when unset. Reuses CLICKHOUSE_USER, CLICKHOUSE_PASSWORD, and CLICKHOUSE_DB. Primarily useful on compute-compute separated ClickHouse clusters (ClickHouse Cloud, BYOC). See Scaling. | |
REDIS_CONNECTION_STRING | Required | Connection string of your redis instance. Instead of REDIS_CONNECTION_STRING, you can also use REDIS_HOST, REDIS_PORT, REDIS_USERNAME and REDIS_AUTH. To configure TLS check the detailed Cache Configuration Documentation. |
REDIS_CLUSTER_ENABLED | false | Set to true to enable Redis cluster mode. When enabled, you must also provide REDIS_CLUSTER_NODES. |
REDIS_CLUSTER_NODES | Comma-separated list of Redis cluster nodes in the format host:port. Required when REDIS_CLUSTER_ENABLED is true. Example: redis-node1:6379,redis-node2:6379,redis-node3:6379. | |
REDIS_CLUSTER_SLOTS_REFRESH_TIMEOUT | 5000 | Timeout in milliseconds for the Redis cluster slots refresh operation. Increase this value if you experience timeout errors during cluster topology updates. |
REDIS_SENTINEL_ENABLED | false | Set to true to enable Redis Sentinel mode. Cannot be enabled simultaneously with cluster mode. When enabled, you must also provide REDIS_SENTINEL_NODES and REDIS_SENTINEL_MASTER_NAME. |
REDIS_SENTINEL_NODES | Comma-separated list of Redis Sentinel nodes in the format host:port. Required when REDIS_SENTINEL_ENABLED is true. Example: sentinel1:26379,sentinel2:26379,sentinel3:26379. | |
REDIS_SENTINEL_MASTER_NAME | Name of the Redis Sentinel master. Required when REDIS_SENTINEL_ENABLED is true. This must match the master name configured in your Sentinel setup. | |
REDIS_SENTINEL_USERNAME | Username for Redis Sentinel authentication (optional). Used when Sentinels require authentication. | |
REDIS_SENTINEL_PASSWORD | Password for Redis Sentinel authentication (optional). Used when Sentinels require authentication. | |
REDIS_SENTINEL_TLS_ENABLED | false | Set to true to also apply TLS to the connections to the Sentinel nodes, in addition to the Redis master/replica connections. Requires REDIS_TLS_ENABLED=true; otherwise it is ignored. See Cache Configuration. |
REDIS_SOCKET_TIMEOUT_MS | 30000 | Socket timeout in milliseconds for all Redis connections including BullMQ queue workers. Set to 0 to disable; positive values must be at least 10000 to accommodate blocking operations like BZPOPMIN. See Cache Configuration. |
REDIS_AUTH | Authentication string for the Redis instance or cluster. | |
NEXTAUTH_URL | Required | Public URL of your Langfuse web deployment, e.g. https://yourdomain.com or http://localhost:3000. Used for authentication and user-facing links in emails, Slack notifications, and integration settings. Keep it public on web and worker. On >=v4.25.0, use LANGFUSE_MCP_BASE_URL for a separate internal MCP route; if its hostname differs, add it to LANGFUSE_MCP_ALLOWED_HOSTS on web. See Langfuse MCP. |
NEXTAUTH_SECRET | Required | Used to validate login session cookies, generate secret with at least 256 entropy using openssl rand -base64 32. |
SALT | Required | Used to salt hashed API keys, generate secret with at least 256 entropy using openssl rand -base64 32. |
ENCRYPTION_KEY | Required | Used to encrypt sensitive data. Must be 256 bits, 64 string characters in hex format, generate via: openssl rand -hex 32. |
LANGFUSE_CSP_ENFORCE_HTTPS | false | Set to true to set CSP headers to only allow HTTPS connections. |
PORT | 3000 / 3030 | Port the server listens on. 3000 for web, 3030 for worker. |
HOSTNAME | localhost | In some environments it needs to be set to 0.0.0.0 to be accessible from outside the container (e.g. Google Cloud Run). |
LANGFUSE_CACHE_API_KEY_ENABLED | true | Enable or disable API key caching. Set to false to disable caching of API keys. Plain-text keys are never stored in Redis, only hashed or encrypted keys. |
LANGFUSE_CACHE_API_KEY_TTL_SECONDS | 300 | Time-to-live (TTL) in seconds for cached API keys. Determines how long API keys remain in the cache before being refreshed. |
LANGFUSE_CACHE_PROMPT_ENABLED | true | Enable or disable prompt caching. Set to false to disable caching of prompts. |
LANGFUSE_CACHE_PROMPT_TTL_SECONDS | 300 | Time-to-live (TTL) in seconds for cached prompts. Determines how long prompts remain in the cache before being refreshed. |
LANGFUSE_S3_EVENT_UPLOAD_BUCKET | Required | Name of the bucket in which event information should be uploaded. |
LANGFUSE_S3_EVENT_UPLOAD_PREFIX | "" | Prefix to store events within a subpath of the bucket. Defaults to the bucket root. If provided, must end with a /. |
LANGFUSE_S3_EVENT_UPLOAD_REGION | Region in which the bucket resides. | |
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT | Endpoint to use to upload events. | |
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID | Access key for the bucket. Must have List, Get, and Put permissions. | |
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY | Secret access key for the bucket. | |
LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE | Whether to force path style on requests. Required for MinIO. | |
LANGFUSE_S3_BATCH_EXPORT_ENABLED | false | Whether to enable Langfuse S3 batch exports. This must be set to true to enable batch exports. |
LANGFUSE_S3_BATCH_EXPORT_BUCKET | Required | Name of the bucket in which batch exports should be uploaded. |
LANGFUSE_S3_BATCH_EXPORT_PREFIX | "" | Prefix to store batch exports within a subpath of the bucket. Defaults to the bucket root. If provided, must end with a /. |
LANGFUSE_S3_BATCH_EXPORT_REGION | Region in which the bucket resides. | |
LANGFUSE_S3_BATCH_EXPORT_ENDPOINT | Endpoint to use to upload batch exports. | |
LANGFUSE_S3_BATCH_EXPORT_ACCESS_KEY_ID | Access key for the bucket. Must have List, Get, and Put permissions. | |
LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY | Secret access key for the bucket. | |
LANGFUSE_S3_BATCH_EXPORT_FORCE_PATH_STYLE | Whether to force path style on requests. Required for MinIO. | |
LANGFUSE_S3_BATCH_EXPORT_EXTERNAL_ENDPOINT | Optional external endpoint for generating presigned URLs. If not provided, the main endpoint is used. Useful, if langfuse traffic to the blobstorage should remain within the VPC. | |
BATCH_EXPORT_PAGE_SIZE | 500 | Optional page size for streaming exports to S3 to avoid memory issues. The page size can be adjusted if needed to optimize performance. |
BATCH_EXPORT_ROW_LIMIT | 1_500_000 | Maximum amount of rows that can be exported in a single batch export. |
LANGFUSE_S3_MEDIA_UPLOAD_BUCKET | Required | Name of the bucket in which media files should be uploaded. |
LANGFUSE_S3_MEDIA_UPLOAD_PREFIX | "" | Prefix to store media within a subpath of the bucket. Defaults to the bucket root. If provided, must end with a /. |
LANGFUSE_S3_MEDIA_UPLOAD_REGION | Region in which the bucket resides. | |
LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT | Endpoint to use to upload media files. | |
LANGFUSE_S3_MEDIA_UPLOAD_INTERNAL_ENDPOINT | Optional endpoint that the Langfuse server can use to read media from object storage. Set this when the public media endpoint is not reachable from the web or worker containers. | |
LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID | Access key for the bucket. Must have List, Get, and Put permissions. | |
LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY | Secret access key for the bucket. | |
LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE | Whether to force path style on requests. Required for MinIO. | |
LANGFUSE_S3_MEDIA_MAX_CONTENT_LENGTH | 1_000_000_000 | Maximum file size in bytes that is allowed for upload. Default is 1GB. |
LANGFUSE_S3_MEDIA_DOWNLOAD_URL_EXPIRY_SECONDS | 3600 | Presigned download URL expiry in seconds. Defaults to 1h. |
LANGFUSE_S3_CONCURRENT_WRITES | 50 | Maximum number of concurrent writes to S3. Useful for errors like @smithy/node-http-handler:WARN - socket usage at capacity=50. |
LANGFUSE_S3_CONCURRENT_READS | 50 | Maximum number of concurrent reads from S3. Useful for errors like @smithy/node-http-handler:WARN - socket usage at capacity=50. |
LANGFUSE_AUTO_POSTGRES_MIGRATION_DISABLED | false | Set to true to disable automatic database migrations on docker startup. Not recommended. |
LANGFUSE_LOG_LEVEL | info | Set the log level for the application. Possible values are trace, debug, info, warn, error, fatal. |
LANGFUSE_LOG_FORMAT | text | Set the log format for the application. Possible values are text, json. |
LANGFUSE_LOG_PROPAGATED_HEADERS | Comma-separated list of HTTP header names to propagate through logs via OpenTelemetry baggage. Header names are case-insensitive and will be normalized to lowercase. Useful for debugging and observability. Example: x-request-id,x-user-id. | |
LANGFUSE_MCP_BASE_URL | Optional worker-only base URL for the Langfuse MCP server, available on >=v4.25.0. Takes precedence over NEXTAUTH_URL for MCP endpoint derivation. If its hostname differs from NEXTAUTH_URL, add it to LANGFUSE_MCP_ALLOWED_HOSTS on web. See Langfuse MCP. | |
LANGFUSE_MCP_ALLOWED_HOSTS | Comma-separated additional hostnames or origins accepted by the MCP endpoint when a reverse proxy, Docker service name, or Kubernetes service forwards a different Host header than NEXTAUTH_URL. Required for the Langfuse Assistant when LANGFUSE_MCP_BASE_URL uses another hostname. Not needed when web and worker share a public NEXTAUTH_URL the worker can reach. Prefer preserving the public host at the proxy. Values must be exact hostnames or origins; wildcards and paths are not supported. | |
LANGFUSE_MARKDOWN_RENDER_CHARACTER_LIMIT | 150000 | Character count above which trace and observation input/output renders as plain text instead of markdown. |
LLM-as-a-Judge media
Self-hosted Langfuse sends media used by LLM-as-a-Judge evaluators inline by default. This lets model providers receive attachments even when they cannot access your object storage. Configure these variables on both the web and worker containers.
| Variable | Required / Default | Description |
|---|---|---|
LANGFUSE_EVALUATOR_MEDIA_TRANSPORT | inline | How media is sent to the LLM-as-a-Judge model: inline makes the worker download the attachment and send its bytes; url makes the worker create a signed URL without downloading the attachment, so the model provider downloads it; disabled leaves media references as text. |
LANGFUSE_EVALUATOR_MEDIA_INLINE_MAX_BYTES | 20_000_000 | Maximum size in bytes for each inline attachment. Evaluations fail when an attachment exceeds this limit. |
When using inline, set LANGFUSE_S3_MEDIA_UPLOAD_INTERNAL_ENDPOINT if the Langfuse server needs a different object storage address than browsers and SDKs. For example, Docker Compose can use http://localhost:9090 as the public endpoint and http://minio:9000 as the internal endpoint.
Code evaluators
| Variable | Required / Default | Description |
|---|---|---|
LANGFUSE_CODE_EVAL_DISPATCHER | Dispatcher used for code evaluator execution and UI availability. Set to aws-lambda for production self-hosted deployments. Set to insecure-local only when all evaluator code is fully trusted. | |
QUEUE_CONSUMER_CODE_EVAL_EXECUTION_QUEUE_IS_ENABLED | false | Set to true to enable the worker consumer for the code evaluator execution queue. Required when enabling code evaluator execution. |
LANGFUSE_CODE_EVAL_AWS_LAMBDA_NODE_FUNCTION_NAME | code-based-eval-executor-node | AWS Lambda function name for TypeScript/JavaScript code evaluator execution when LANGFUSE_CODE_EVAL_DISPATCHER=aws-lambda. |
LANGFUSE_CODE_EVAL_AWS_LAMBDA_PYTHON_FUNCTION_NAME | code-based-eval-executor-python | AWS Lambda function name for Python code evaluator execution when LANGFUSE_CODE_EVAL_DISPATCHER=aws-lambda. |
LANGFUSE_CODE_EVAL_AWS_LAMBDA_ENDPOINT | Optional custom AWS Lambda endpoint for local or compatible endpoints. | |
LANGFUSE_CODE_EVAL_EXECUTION_QUEUE_SHARD_COUNT | Optional number of shards for the code evaluator execution queue. | |
LANGFUSE_CODE_EVAL_EXECUTION_WORKER_CONCURRENCY | Optional worker concurrency for code evaluator execution. | |
LANGFUSE_CODE_EVAL_LOCAL_TIMEOUT_MS | Optional timeout in milliseconds for locally executed code evaluators. |
Langfuse Assistant
The Assistant is available from >=v4.28.0. It stays hidden until LANGFUSE_IN_APP_AGENT_ENABLED=true is set on the web container and on each worker that should execute Assistant runs. It then uses one instance-wide Langfuse AI model, on Amazon Bedrock, the Anthropic Messages API, an OpenAI-compatible endpoint, or Google Vertex AI (Gemini Enterprise Agent Platform, from >=v4.39.0). We recommend the AWS Lambda MicroVM sandbox. The LANGFUSE_IN_APP_AGENT_SANDBOX_* variables are worker-only. See Langfuse Assistant.
| Variable | Required / Default | Description |
|---|---|---|
LANGFUSE_IN_APP_AGENT_ENABLED | Set to true on web and on the workers that should execute Assistant runs. Workers with it set consume the run queue. Unset or false hides it. Does not gate Ask AI. | |
LANGFUSE_AI_PROVIDER | Required to enable | bedrock, anthropic, openai, or vertex. Unset leaves Langfuse AI unconfigured. |
LANGFUSE_AI_MODEL | Model ID for the selected provider. On Bedrock, a geo inference profile ID such as eu.anthropic.claude-opus-5. On Vertex, a Claude or Gemini ID such as claude-opus-5. | |
LANGFUSE_AI_SMALL_MODEL | Optional model for conversation titles and Ask AI. Defaults to LANGFUSE_AI_MODEL. | |
LANGFUSE_AI_AWS_BEDROCK_REGION | Bedrock Region. Optional when the workload already runs in that Region. | |
LANGFUSE_AI_VERTEX_LOCATION | global | Vertex location. Optional, defaults to global. Vertex only. |
LANGFUSE_AI_API_KEY | API key. Required when LANGFUSE_AI_PROVIDER is anthropic or openai, not used on Bedrock or Vertex. | |
LANGFUSE_AI_BASE_URL | Optional. Full API base including /v1, such as https://gateway.internal/v1. | |
LANGFUSE_AI_EXTRA_HEADERS | Optional JSON object of additional request headers, on anthropic and openai. Invalid JSON fails validation at boot. | |
LANGFUSE_AI_USE_RESPONSES_API | Optional. Set to true to call the OpenAI Responses API instead of Chat Completions. openai only. | |
LANGFUSE_IN_APP_AGENT_RUN_QUEUE_PROCESSING_CONCURRENCY | 5 | Concurrent Assistant runs on the worker. |
LANGFUSE_IN_APP_AGENT_MAX_ACTIVE_RUNS_PER_USER | 5 | Concurrent runs admitted per user on the web service. |
LANGFUSE_IN_APP_AGENT_MAX_ACTIVE_RUNS_PER_ORG | 20 | Concurrent runs admitted per organization on the web service. |
LANGFUSE_AI_FEATURES_PROJECT_ID | Optional. Project on this instance that receives Assistant and Ask AI traces. Unset records nothing. See Langfuse Assistant. | |
LANGFUSE_IN_APP_AGENT_SANDBOX_PROVIDER | Unset | Set to lambda-microvm on the worker for production. Unset runs the Assistant with Langfuse tools only. |
LANGFUSE_IN_APP_AGENT_SANDBOX_AWS_LAMBDA_MICROVM_IMAGE_IDENTIFIER | Required | MicroVM image ARN. Required when the sandbox provider is lambda-microvm. |
LANGFUSE_IN_APP_AGENT_SANDBOX_AWS_LAMBDA_MICROVM_EXECUTION_ROLE_ARN | Required | MicroVM execution role ARN. Required when the sandbox provider is lambda-microvm. |
LANGFUSE_IN_APP_AGENT_SANDBOX_AWS_LAMBDA_MICROVM_REGION | Required | AWS Region for the MicroVM. Required when the sandbox provider is lambda-microvm. |
LANGFUSE_IN_APP_AGENT_SANDBOX_AWS_LAMBDA_MICROVM_EGRESS_NETWORK_CONNECTOR_ARN | Unset | Optional egress network connector ARN. When unset, AWS attaches INTERNET_EGRESS and sandboxed code reaches the public internet. See Langfuse Assistant. |
Additional Features
There are additional features that can be enabled and configured via environment variables.
Authentication & SSO
Automated Access Provisioning
Caching
Code evaluators
Langfuse Assistant
Custom Base Path
Encryption
Headless Initialization
Data Masking
Networking
Organization Creators (EE)
Instance Management API (EE)
Health and Readiness Check
Observability via OpenTelemetry
Transactional Emails
UI Customization (EE)
If you experience any issues when self-hosting Langfuse, please:
- Check out Troubleshooting & FAQ page.
- Use Ask AI to get instant answers to your questions.
- Ask the maintainers on GitHub Discussions.
- Create a bug report or feature request on GitHub.
Enterprise-grade support is available when self-hosting Langfuse. Learn more on our pricing page.
Was this page helpful?
Last updated on
