--- title: Configuration via Environment Variables (self-hosted) description: Langfuse has extensive configuration options via environment variables. label: "Version: v4" sidebarTitle: "Environment Variables" --- # 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](https://www.prisma.io/docs/orm/prisma-migrate/understanding-prisma-migrate/shadow-database#cloud-hosted-shadow-databases-must-be-created-manually) for detailed instructions. | | `CLICKHOUSE_MIGRATION_URL` | Required | Migration URL (TCP protocol) for the clickhouse instance. Pattern: `clickhouse://:(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)://:(8123/8443)` | | `CLICKHOUSE_USER` | Required | Username of the clickhouse database. Needs the grants listed under [user permissions](/self-hosting/deployment/infrastructure/clickhouse#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](/self-hosting/configuration/scaling#clickhouse-read-only-url). | | `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](/self-hosting/deployment/infrastructure/cache#configuration). | | `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](/self-hosting/deployment/infrastructure/cache#redis-sentinel-mode). | | `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](/self-hosting/deployment/infrastructure/cache#timeout-configuration). | | `REDIS_AUTH` | | Authentication string for the Redis instance or cluster. | | `NEXTAUTH_URL` | Required | URL of your Langfuse web deployment, e.g. `https://yourdomain.com` or `http://localhost:3000`. Required for successful authentication via OAUTH and sending valid Links via Slack integration. | | `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` | | Browser- and SDK-reachable endpoint used to upload and download 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_ALLOWED_HOSTS` | | Comma-separated additional hostnames or origins accepted by the MCP endpoint when a reverse proxy forwards a different `Host` header than `NEXTAUTH_URL`. 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 [#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. | ## Additional Features There are additional features that can be enabled and configured via environment variables. - [Authentication & SSO](/self-hosting/security/authentication-and-sso) - [Automated Access Provisioning](/self-hosting/administration/automated-access-provisioning) - [Caching](/self-hosting/configuration/caching) - [Code evaluators](/self-hosting/configuration/code-evaluators) - [Custom Base Path](/self-hosting/configuration/custom-base-path) - [Encryption](/self-hosting/configuration/encryption) - [Headless Initialization](/self-hosting/administration/headless-initialization) - [Data Masking](/self-hosting/security/data-masking) - [Networking](/self-hosting/security/networking) - [Organization Creators (EE)](/self-hosting/administration/organization-creators) - [Instance Management API (EE)](/self-hosting/administration/instance-management-api) - [Health and Readiness Check](/self-hosting/configuration/health-readiness-endpoints) - [Observability via OpenTelemetry](/self-hosting/configuration/observability) - [Transactional Emails](/self-hosting/configuration/transactional-emails) - [UI Customization (EE)](/self-hosting/administration/ui-customization) --- If you experience any issues when self-hosting Langfuse, please: 1. Check out [Troubleshooting & FAQ](/self-hosting/troubleshooting-and-faq) page. 2. Use [Ask AI](/ask-ai) to get instant answers to your questions. 3. Ask the maintainers on [GitHub Discussions](/gh-support). 4. Create a bug report or feature request on [GitHub](/issues). Enterprise-grade support is available when self-hosting Langfuse. Learn more on our [pricing page](/pricing-self-host). --- ## Agent Instructions This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/self-hosting/configuration.md`. ### Querying these docs If the answer is not on this page, query the documentation instead of guessing: - **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question: ```bash curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?" ``` - **Index of every page**: , with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt). ### Before writing Langfuse code - **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results. - **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application. - **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples. - **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api `) to read or write traces, prompts, datasets, and scores from the terminal. Found an error in these docs? Please open an issue at .