Environment Variables

Dify works out of the box with default settings. To customize your deployment, edit environment variables in the relevant file:

Essential startup values live in docker/.env, which you created from docker/.env.example during deployment. Edit them directly.
Optional or provider-specific settings have templates under docker/envs/. To override a default value, copy the matching template (drop the .example suffix), then edit your copy. For example:
cd dify/docker cp envs/vectorstores/milvus.env.example envs/vectorstores/milvus.env

Values in docker/.env take precedence over values in any docker/envs/*.env files.

After upgrading Dify, compare each .env.example with its matching .env for new or changed variables.

Common Variables

These URL variables configure the addresses of Dify’s various services. For single-domain deployments behind Nginx (the default Docker Compose setup), these can be left empty—the system auto-detects from the incoming request. Configure them when using custom domains, split-domain deployments, or a reverse proxy.

CONSOLE_API_URL

Default: (empty) The public URL of Dify’s backend API. Set this if you use OAuth login (GitHub, Google), Notion integration, or any plugin that requires OAuth—these features need an absolute callback URL to redirect users back after authorization. Also determines whether secure (HTTPS-only) cookies are used. Example: https://api.console.dify.ai

SERVER_CONSOLE_API_URL

Default: http://api:5001 The console API address the web frontend container uses for server-side requests, reaching the API directly over the internal Docker network rather than your public domain. Only the web frontend container uses this variable, not the Python backend; browser requests still go to CONSOLE_API_URL. If left empty, it falls back to CONSOLE_API_URL. Change it only if the API service is reachable at a different internal address.

CONSOLE_WEB_URL

Default: (empty) The public URL of Dify’s console frontend. Used to build links in all system emails (invitations, password resets, notifications) and to redirect users back to the console after OAuth login. Also serves as the default CORS allowed origin if CONSOLE_CORS_ALLOW_ORIGINS is not set. If empty, email links will be broken—even in single-domain setups, set this if you use email features. Example: https://console.dify.ai

SERVICE_API_URL

Default: (empty) The API Base URL shown to developers in the Dify console—the URL they copy into their code to call the Dify API. If empty, auto-detects from the current request (e.g., http://localhost/v1). Set this to ensure a consistent URL when your server is accessible via multiple addresses. Example: https://api.dify.ai

APP_API_URL

Default: (empty) The backend API URL for the web app frontend (published apps). This variable is only used by the web frontend container, not the Python backend. If empty, the Docker image defaults to http://127.0.0.1:5001. Example: https://api.app.dify.ai

APP_WEB_URL

Default: (empty) The public URL where published web apps are accessible. Required for the Human Input node in workflows—form links in email notifications are built as {APP_WEB_URL}/form/{token}. If empty, Human Input email delivery will not include valid form links. Example: https://app.dify.ai

TRIGGER_URL

Default: http://localhost The publicly accessible URL for webhook and integration trigger endpoints. External systems use this address to invoke your workflows. Dify builds trigger callback URLs like {TRIGGER_URL}/triggers/webhook/{id} and displays them in the console. For triggers to work from external systems, this must point to a public domain or IP address they can reach.

FILES_URL

Default: (empty; falls back to CONSOLE_API_URL) The base URL for file preview and download links. Dify generates signed, time-limited URLs for all files (uploaded documents, tool outputs, workspace logos) and serves them to the frontend and multi-modal models. Set this if you use file processing plugins, or if you want file URLs on a dedicated domain. If both FILES_URL and CONSOLE_API_URL are empty, file previews will not work. Example: https://upload.example.com or http://<your-ip>:5001

INTERNAL_FILES_URL

Default: (empty; falls back to FILES_URL) The file access URL used for communication between services inside the Docker network (e.g., plugin daemon, PDF/Word extractors). These internal services may not be able to reach the external FILES_URL if it routes through Nginx or a public domain. If empty, internal services use FILES_URL. Set this when internal services can’t reach the external URL. Example: http://api:5001

FILES_ACCESS_TIMEOUT

Default: 300 (5 minutes) How long signed file URLs remain valid, in seconds. After this time, the URL is rejected and the file must be re-requested. Increase for long-running processes; decrease for tighter security.

ENABLE_COLLABORATION_MODE

Default: true Enables real-time collaboration on the workflow canvas: simultaneous editing, in-canvas comments, and @mentions. If you access Dify on a host other than localhost, set NEXT_PUBLIC_SOCKET_URL to a WebSocket URL your browser can reach (see CORS Configuration). The default ws://localhost only works for local-only setups. To disable collaboration, set this to false. On Docker Compose, also remove collaboration from COMPOSE_PROFILES. Otherwise the dedicated api_websocket container keeps running but receives no traffic. If you use your own reverse proxy, forward Upgrade and Connection headers on /socket.io/ (the bundled nginx template already does this). Running multiple API replicas requires sticky sessions. If the editor keeps dropping and reconnecting while collaborators work on a large workflow, raise WEBSOCKET_MAX_HTTP_BUFFER_SIZE.

System Encoding

Variable	Default	Description
`LANG`	`C.UTF-8`	System locale setting. Ensures UTF-8 encoding.
`LC_ALL`	`C.UTF-8`	Locale override for all categories.
`PYTHONIOENCODING`	`utf-8`	Python I/O encoding.

Server Configuration

Logging

Variable	Default	Description
`LOG_LEVEL`	`INFO`	Minimum log severity. Controls what gets logged across all handlers (file + console). Levels from least to most severe: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.
`LOG_OUTPUT_FORMAT`	`text`	`text` produces human-readable lines with timestamp, level, thread, and trace ID. `json` produces structured JSON for log aggregation tools (ELK, Datadog, etc.).
`LOG_FILE`	`/app/logs/server.log`	Log file path. When set, enables file-based logging with automatic rotation. The directory is created automatically. When empty, logs only go to console.
`LOG_FILE_MAX_SIZE`	`20`	Maximum log file size in MB before rotation. When exceeded, the active file is renamed to `.1` and a new file is started.
`LOG_FILE_BACKUP_COUNT`	`5`	Number of rotated log files to keep. With defaults, at most 6 files exist: the active file plus 5 backups.
`LOG_DATEFORMAT`	`%Y-%m-%d %H:%M:%S`	Timestamp format for text-format logs (strftime codes). Ignored by JSON format.
`LOG_TZ`	`UTC`	Timezone for log timestamps (pytz format, e.g., `Asia/Shanghai`). Only applies to text format—JSON always uses UTC. Also sets Celery’s task scheduling timezone.

General

Variable	Default	Description
`DEBUG`	`false`	Enables verbose logging: tool execution details, full LLM prompts and responses, and app startup timing. Useful for local development; not recommended for production as it may expose sensitive data in logs.
`FLASK_DEBUG`	`false`	Standard Flask debug mode flag. Not actively used by Dify; `DEBUG` is the primary control.
`ENABLE_REQUEST_LOGGING`	`false`	Logs a compact access line (`METHOD PATH STATUS DURATION TRACE_ID`) for every HTTP request. When `LOG_LEVEL` is also set to `DEBUG`, additionally logs full request and response bodies as JSON.
`DEPLOY_ENV`	`PRODUCTION`	Tags monitoring data in Sentry and OpenTelemetry so you can filter errors and traces by environment. Also sent as the `X-Env` response header. Does not change application behavior.
`DEPLOYMENT_EDITION`	`COMMUNITY`	Which edition this deployment runs as: `COMMUNITY`, `ENTERPRISE`, or `CLOUD`. Keep the default. Replaces the former `EDITION`, `ENTERPRISE_ENABLED`, and `BILLING_ENABLED` variables, which are ignored from 1.17.0 onward.
`MIGRATION_ENABLED`	`true`	When `true`, runs database schema migrations (`flask upgrade-db`) automatically on container startup. Docker only. Set to `false` if you run migrations separately. For source code launches, run `flask db upgrade` manually.
`CHECK_UPDATE_URL`	`https://updates.dify.ai`	The console checks this URL for newer Dify versions. Set to empty to disable—useful for air-gapped environments or to prevent external HTTP calls.
`OPENAI_API_BASE`	`https://api.openai.com/v1`	Legacy variable. Not actively used by Dify’s own code. May be picked up by the OpenAI Python SDK if present in the environment.

SECRET_KEY

Default: (pre-filled in .env.example; must be replaced for production) Used for session cookie signing, JWT authentication tokens, file URL signatures (HMAC-SHA256), and encrypting third-party OAuth credentials (AES-256). Generate a strong key before first launch:

openssl rand -base64 42

Changing this key after deployment will immediately log out all users, invalidate all file URLs, and break any plugin integrations that use OAuth—their encrypted credentials become unrecoverable.

PASSWORD_PEPPER

Default: (empty) A server-side secret mixed into the passwords members use to sign in to Dify, so that a leaked copy of the database isn’t enough to crack them. Leave it empty and nothing changes. To use a pepper, set it before you create the admin account during first-time setup. Generate a high-entropy random value, for example:

openssl rand -base64 32

On Docker Compose, set it in docker/envs/core-services/api.env (create the file from api.env.example if you haven’t). Keep it out of docker/.env, which Compose also passes to the worker, plugin daemon, agent backend, web frontend, and code sandbox. On source deployments, set it in api/.env.

Setting, changing, or removing the pepper once accounts exist makes their current passwords fail at sign-in as invalid. To undo a mistake, put back the previous value, and every password that wasn’t reset in the meantime works again. Keep the value as safe as SECRET_KEY.

To turn it on for a deployment that already has accounts, give every member a way back in afterward:

Reset each account’s password with flask reset-password in the API container. See Reset admin password for the full command.
Have members reset their own password through the forgot-password email, which requires mail delivery.
If ENABLE_EMAIL_CODE_LOGIN is on, members can sign in with an email code instead.

KEY_PROVIDER_TYPE

Default: local Where Dify keeps the per-workspace keys that encrypt stored credentials—model provider API keys, tool credentials, and other workspace secrets:

local: generates an RSA key pair per workspace and keeps the private key in the STORAGE_TYPE backend.
azure-keyvault: keeps each workspace’s RSA key in Azure Key Vault instead, so the private key never leaves the vault; Dify authenticates with DefaultAzureCredential (managed identity, environment variables, or Azure CLI login).

Choose the provider before the first workspace is created. Credentials encrypted by one provider cannot be decrypted by the other, so switching on a deployment that already stores credentials makes them unreadable until re-entered.

Variable	Default	Description
`AZURE_KEYVAULT_VAULT_URL`	(empty)	Key Vault instance URL. Required when `KEY_PROVIDER_TYPE` is `azure-keyvault`; the API service fails to start without it. Example: `https://your-vault-name.vault.azure.net`
`AZURE_KEYVAULT_KEY_SIZE`	`2048`	RSA key size in bits for the per-workspace keys Dify provisions in the vault. Applies only when a new key is created; existing keys keep their size.
`AZURE_KEYVAULT_ROTATION_INTERVAL_DAYS`	(empty)	When set (minimum 7), each newly provisioned per-workspace key gets a Key Vault auto-rotation policy that rotates it every N days. Old key versions stay usable, so credentials encrypted before a rotation keep decrypting without re-encryption. Leave empty to manage rotation yourself in Azure.

INIT_PASSWORD

Default: (empty) Optional security gate for first-time setup. When set, the /install page requires this password before the admin account can be created—preventing unauthorized setup if your server is exposed. Once setup is complete, this variable has no further effect. Maximum length: 30 characters.

Token & Request Limits

Variable	Default	Description
`ACCESS_TOKEN_EXPIRE_MINUTES`	`60`	How long a login session’s access token stays valid (in minutes). When it expires, the browser silently refreshes it using the refresh token—users are not logged out.
`REFRESH_TOKEN_EXPIRE_DAYS`	`30`	How long a user can stay logged in without re-entering credentials (in days). If the user doesn’t visit within this period, they must log in again.
`APP_MAX_EXECUTION_TIME`	`3600`	Maximum time in seconds an app execution can run before it is terminated. An outer limit alongside `WORKFLOW_MAX_EXECUTION_TIME`: both default to one hour, with this one applied at the app queue level and the other at the workflow engine level. Increase both together if your workflows need more time. If you run agents, keep these outer limits at or above the agent run deadline (`DIFY_AGENT_RUN_TIMEOUT_SECONDS`); otherwise agent runs are cut short.
`APP_DEFAULT_ACTIVE_REQUESTS`	`0`	Default concurrent request limit per app, used when an app doesn’t have a custom limit set in the UI. `0` means unlimited. The effective limit is the smaller of this and `APP_MAX_ACTIVE_REQUESTS`.
`APP_MAX_ACTIVE_REQUESTS`	`0`	Global ceiling for concurrent requests per app. Overrides per-app settings if they exceed this value. `0` means unlimited.
`WEBSOCKET_MAX_HTTP_BUFFER_SIZE`	`10485760`	Maximum collaboration WebSocket message size in bytes (10 MiB by default). Raise it if saving a large workflow causes repeated disconnections because the workflow graph exceeds this limit. Set it on the API process serving `/socket.io/`: the `api_websocket` container in Docker Compose.

Container Startup Configuration

Only effective when starting with Docker image or Docker Compose.

Variable	Default	Description
`DIFY_BIND_ADDRESS`	`0.0.0.0`	Network interface the API server binds to. `0.0.0.0` listens on all interfaces; set to `127.0.0.1` to restrict to localhost only.
`DIFY_PORT`	`5001`	Port the API server listens on.
`SERVER_WORKER_AMOUNT`	`1`	Number of Gunicorn worker processes. With gevent (default), each worker handles multiple concurrent connections via greenlets, so 1 is usually sufficient. For sync workers, use `(2 x CPU cores) + 1`. Reference.
`SERVER_WORKER_CLASS`	`gevent`	Gunicorn worker type. Keep the default; other values break psycopg2 and gRPC patching.
`SERVER_WORKER_CONNECTIONS`	`10`	Maximum concurrent connections per worker. Only applies to async workers (gevent). If you experience connection rejections or slow responses under load, try increasing this value.
`GUNICORN_TIMEOUT`	`360`	If a worker doesn’t respond within this many seconds, Gunicorn kills and restarts it. Set to 360 (6 minutes) to support long-lived SSE connections used for streaming LLM responses.
`API_WEBSOCKET_WORKER_AMOUNT`	`1`	Docker Compose only. Number of Gunicorn workers in the dedicated `api_websocket` container serving real-time collaboration. Collaboration events sync across workers through Redis, so it’s safe to raise this when one worker saturates a CPU core under heavy editor traffic.
`API_WEBSOCKET_WORKER_CLASS`	`geventwebsocket.gunicorn.workers.GeventWebSocketWorker`	Docker Compose only. Worker class for the dedicated `api_websocket` container. Keep the default; other values break WebSocket support.
`API_WEBSOCKET_WORKER_CONNECTIONS`	`1000`	Docker Compose only. Maximum simultaneous WebSocket connections per `api_websocket` worker. Each open workflow editor in a browser tab uses one, so the default supports up to 1000 simultaneous editor sessions per worker; raise it or add workers if you expect more.
`API_WEBSOCKET_GUNICORN_TIMEOUT`	`360`	Docker Compose only. If an `api_websocket` worker doesn’t respond within this many seconds, Gunicorn restarts it. The default 360 seconds (6 minutes) supports long-lived WebSocket connections.
`CELERY_WORKER_CLASS`	(empty; defaults to gevent)	Celery worker type with the same gevent patching requirements as `SERVER_WORKER_CLASS`. Strongly discouraged to change.
`CELERY_WORKER_AMOUNT`	`4`	Number of Celery worker processes. Only used when autoscaling is disabled. Lower it on constrained VMs; for elastic throughput, enable `CELERY_AUTO_SCALE` instead of raising this.
`CELERY_AUTO_SCALE`	`false`	Enable dynamic autoscaling. When enabled, Celery monitors queue depth and spawns/kills workers between `CELERY_MIN_WORKERS` and `CELERY_MAX_WORKERS`.
`CELERY_MAX_WORKERS`	(empty; defaults to CPU count)	Maximum workers when autoscaling is enabled.
`CELERY_MIN_WORKERS`	(empty; defaults to 1)	Minimum workers when autoscaling is enabled.
`COMPOSE_WORKER_HEALTHCHECK_DISABLED`	`true`	Disable the Docker Compose health check for the Celery worker container. Disabled by default because `celery inspect ping` can be expensive on busy workers. Set to `false` to enable. Only applies to Docker Compose deployments.
`COMPOSE_WORKER_HEALTHCHECK_INTERVAL`	`30s`	Interval between Celery worker health checks. Only used when `COMPOSE_WORKER_HEALTHCHECK_DISABLED=false`. Accepts Docker Compose duration values (e.g., `30s`, `1m`).
`COMPOSE_WORKER_HEALTHCHECK_TIMEOUT`	`30s`	Timeout for each Celery worker health check. Only used when `COMPOSE_WORKER_HEALTHCHECK_DISABLED=false`.

MODE

Default: worker (the worker service’s shipped value; with the variable unset entirely, the container runs the API server) What the dify-api image runs at container start. Each of the three env example files pins the value for its own service: worker in worker.env.example, api in api.env.example, and beat in worker-beat.env.example. Accepted values:

api (and any empty or unrecognized value): the API server
worker: the Celery task consumer
beat: the scheduled-task dispatcher
job: run one Flask CLI command, then exit
migration: with MIGRATION_ENABLED=true, migrate the database and exit

The bundled Compose file pins the right value per service, so you only set this in custom setups such as Kubernetes. A wrong value runs the wrong process—with no worker, indexing and mail tasks queue forever.

API Tool Configuration

Variable	Default	Description
`API_TOOL_DEFAULT_CONNECT_TIMEOUT`	`10`	Maximum time (in seconds) to wait for establishing a TCP connection when API Tool nodes call external APIs.
`API_TOOL_DEFAULT_READ_TIMEOUT`	`60`	Maximum time (in seconds) to wait for receiving response data from external APIs called by API Tool nodes.

Database Configuration

The database uses PostgreSQL by default. OceanBase, MySQL, and seekdb are also supported.

Variable	Default	Description
`DB_TYPE`	`postgresql`	Database type. Supported values: `postgresql`, `mysql`, `oceanbase`, `seekdb`. MySQL-compatible databases like TiDB can use `mysql`.
`DB_USERNAME`	`postgres`	Database username. URL-encoded in the connection string, so special characters are safe to use.
`DB_PASSWORD`	`difyai123456`	Database password. URL-encoded in the connection string, so characters like `@`, `:`, `%` are safe to use.
`DB_HOST`	`db_postgres`	Database server hostname.
`DB_PORT`	`5432`	Database server port. If using MySQL, set this to `3306`.
`DB_DATABASE`	`dify`	Database name.

Connection Pool

These control how Dify manages its pool of database connections. The defaults work well for most deployments.

Variable	Default	Description
`SQLALCHEMY_POOL_SIZE`	`30`	Number of persistent connections kept in the pool.
`SQLALCHEMY_MAX_OVERFLOW`	`10`	Additional temporary connections allowed when the pool is full. With default settings, up to 40 connections (30 + 10) can exist simultaneously.
`SQLALCHEMY_POOL_RECYCLE`	`3600`	Recycle connections after this many seconds to prevent stale connections.
`SQLALCHEMY_POOL_TIMEOUT`	`30`	How long to wait for a connection when the pool is exhausted. Requests fail with a timeout error if no connection frees up in time.
`SQLALCHEMY_POOL_RESET_ON_RETURN`	`rollback`	Action SQLAlchemy takes when a connection returns to the pool. `rollback` clears any uncommitted transaction state before reuse; `commit` commits it instead.
`SQLALCHEMY_POOL_PRE_PING`	`false`	Test each connection with a lightweight query before using it. Prevents “connection lost” errors but adds slight latency. Recommended for production with unreliable networks.
`SQLALCHEMY_POOL_USE_LIFO`	`false`	Reuse the most recently returned connection (LIFO) instead of rotating evenly (FIFO). LIFO keeps fewer connections “warm” and can reduce overhead.
`SQLALCHEMY_ECHO`	`false`	Print all SQL statements to logs. Useful for debugging query issues.

PostgreSQL Performance Tuning

These are passed as startup arguments to the PostgreSQL container—they configure the database server, not the Dify application.

Variable	Default	Description
`POSTGRES_MAX_CONNECTIONS`	`200`	Maximum number of database connections. Keep at least `SERVER_WORKER_AMOUNT × SERVER_WORKER_CONNECTIONS + CELERY_WORKER_AMOUNT + headroom` to avoid `too many connections` errors when API and Celery workers both open pools. Reference
`POSTGRES_SHARED_BUFFERS`	`128MB`	Shared memory for buffers. Recommended: 25% of available memory. Reference
`POSTGRES_WORK_MEM`	`4MB`	Memory per database worker for working space. Reference
`POSTGRES_MAINTENANCE_WORK_MEM`	`64MB`	Memory reserved for maintenance activities. Reference
`POSTGRES_EFFECTIVE_CACHE_SIZE`	`4096MB`	Planner’s assumption about effective cache size. Reference
`POSTGRES_STATEMENT_TIMEOUT`	`0`	Max statement duration before termination (ms). `0` means no timeout. Reference
`POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT`	`0`	Max idle-in-transaction session duration (ms). `0` means no timeout. Reference

MySQL Performance Tuning

These are passed as startup arguments to the MySQL container—they configure the database server, not the Dify application.

Variable	Default	Description
`MYSQL_MAX_CONNECTIONS`	`1000`	Maximum number of MySQL connections.
`MYSQL_INNODB_BUFFER_POOL_SIZE`	`512M`	InnoDB buffer pool size. Recommended: 70-80% of available memory for dedicated MySQL server. Reference
`MYSQL_INNODB_LOG_FILE_SIZE`	`128M`	InnoDB log file size. Reference
`MYSQL_INNODB_FLUSH_LOG_AT_TRX_COMMIT`	`2`	InnoDB flush log at transaction commit. Options: `0` (no flush), `1` (flush and sync), `2` (flush to OS cache). Reference

Redis Configuration

Configure these to connect Dify to your Redis instance. Dify supports three deployment modes: standalone (default), Sentinel, and Cluster.

Variable	Default	Description
`REDIS_HOST`	`redis`	Redis server hostname. Only used in standalone mode; ignored when Sentinel or Cluster mode is enabled.
`REDIS_PORT`	`6379`	Redis server port. Only used in standalone mode.
`REDIS_USERNAME`	(empty)	Redis 6.0+ ACL username. Applies to all modes (standalone, Sentinel, Cluster).
`REDIS_PASSWORD`	`difyai123456`	Redis authentication password. For Cluster mode, use `REDIS_CLUSTERS_PASSWORD` instead.
`REDIS_DB`	`0`	Redis database number (0–15). Only applies to standalone and Sentinel modes. Make sure this doesn’t collide with Celery’s database (configured in `CELERY_BROKER_URL`; default is DB 1).
`REDIS_KEY_PREFIX`	(empty)	Optional global prefix applied to all Redis keys, pub/sub channels, Redis Streams names, and Celery broker queues and result-backend keys. Dify automatically inserts a colon between the prefix and the key, so setting `staging` produces keys like `staging:session:abc`. Useful when multiple Dify instances share one Redis deployment (for example, staging and production) to prevent key collisions. Leave empty to preserve unprefixed behavior. Turning the prefix on for an existing deployment strands any keys written under the previous (empty or different) prefix.
`REDIS_USE_SSL`	`false`	Enable SSL/TLS for the Redis connection. Does not automatically apply to Sentinel protocol.
`REDIS_MAX_CONNECTIONS`	(empty)	Maximum connections in the Redis pool. Leave unset for the library default. Set this to match your Redis server’s `maxclients` if needed.
`REDIS_KEEPALIVE`	`true`	Enable TCP keepalive on Redis connections, so idle connections silently dropped by a firewall or load balancer are detected and re-established instead of failing on next use.
`REDIS_KEEPALIVE_IDLE`	`30`	Seconds a connection stays idle before the first TCP keepalive probe (`TCP_KEEPIDLE`). Applies when `REDIS_KEEPALIVE=true`.
`REDIS_KEEPALIVE_INTERVAL`	`10`	Seconds between TCP keepalive probes (`TCP_KEEPINTVL`). Applies when `REDIS_KEEPALIVE=true`.
`REDIS_KEEPALIVE_COUNT`	`10`	Number of unacknowledged probes before the connection is treated as dead (`TCP_KEEPCNT`). Applies when `REDIS_KEEPALIVE=true`.

Redis SSL Configuration

Only applies when REDIS_USE_SSL=true. These same settings are also used by the Celery broker when its URL uses the rediss:// scheme.

Variable	Default	Description
`REDIS_SSL_CERT_REQS`	`CERT_NONE`	Certificate verification level: `CERT_NONE` (no verification), `CERT_OPTIONAL`, or `CERT_REQUIRED` (full verification).
`REDIS_SSL_CA_CERTS`	(empty)	Path to CA certificate file for verifying the Redis server.
`REDIS_SSL_CERTFILE`	(empty)	Path to client certificate for mutual TLS authentication.
`REDIS_SSL_KEYFILE`	(empty)	Path to client private key for mutual TLS authentication.

Redis Sentinel Mode

Sentinel provides automatic master discovery and failover for high availability. Mutually exclusive with Cluster mode.

Variable	Default	Description
`REDIS_USE_SENTINEL`	`false`	Enable Redis Sentinel mode. When enabled, `REDIS_HOST`/`REDIS_PORT` are ignored; Dify connects to Sentinel nodes instead and asks for the current master.
`REDIS_SENTINELS`	(empty)	Sentinel node addresses. Format: `<ip1>:<port1>,<ip2>:<port2>,<ip3>:<port3>`. These are the Sentinel instances, not the Redis servers.
`REDIS_SENTINEL_SERVICE_NAME`	(empty)	The logical service name Sentinel monitors (configured in `sentinel.conf`). Dify calls `master_for(service_name)` to discover the current master.
`REDIS_SENTINEL_USERNAME`	(empty)	Username for authenticating with Sentinel nodes. Separate from `REDIS_USERNAME`, which authenticates with the Redis master/replicas.
`REDIS_SENTINEL_PASSWORD`	(empty)	Password for authenticating with Sentinel nodes. Separate from `REDIS_PASSWORD`.
`REDIS_SENTINEL_SOCKET_TIMEOUT`	`0.1`	Socket timeout (in seconds) for communicating with Sentinel nodes. Default 0.1s assumes fast local network. For cloud/WAN deployments, increase to 1.0–5.0s to prevent intermittent timeouts.

Redis Cluster Mode

Cluster mode provides automatic sharding across multiple Redis nodes. Mutually exclusive with Sentinel mode.

Variable	Default	Description
`REDIS_USE_CLUSTERS`	`false`	Enable Redis Cluster mode.
`REDIS_CLUSTERS`	(empty)	Cluster nodes. Format: `<ip1>:<port1>,<ip2>:<port2>,<ip3>:<port3>`
`REDIS_CLUSTERS_PASSWORD`	(empty)	Password for the Redis Cluster.

Redis Connection Resilience

These tune client-side retry, timeout, and health-check behavior for Redis connections. Defaults are conservative; increase timeouts for cloud or WAN deployments where network latency is higher.

Variable	Default	Description
`REDIS_RETRY_RETRIES`	`3`	Maximum retries per Redis command on transient failures (`ConnectionError`, `TimeoutError`, `socket.timeout`). Set to `0` to disable retries. Uses exponential backoff with jitter.
`REDIS_RETRY_BACKOFF_BASE`	`1.0`	Base delay in seconds for exponential backoff between retries.
`REDIS_RETRY_BACKOFF_CAP`	`10.0`	Maximum backoff delay in seconds between retries.
`REDIS_SOCKET_TIMEOUT`	`5.0`	Socket timeout in seconds for Redis read/write operations. Increase if you see intermittent command timeouts under load.
`REDIS_SOCKET_CONNECT_TIMEOUT`	`5.0`	Socket timeout in seconds for establishing a Redis connection.
`REDIS_HEALTH_CHECK_INTERVAL`	`30`	Interval in seconds between client-side health checks on idle connections. Set to `0` to disable. Not applied in Cluster mode (silently stripped by `redis-py`).

Celery Configuration

Configure the background task queue used for dataset indexing, email sending, and scheduled jobs.

CELERY_BROKER_URL

Default: redis://:difyai123456@redis:6379/1 Redis connection URL for the Celery message broker. Direct connection format:

redis://<redis_username>:<redis_password>@<redis_host>:<redis_port>/<redis_database>

Sentinel mode format (separate multiple nodes with semicolons):

sentinel://<redis_username>:<redis_password>@<sentinel_host>:<sentinel_port>/<redis_database>

Variable	Default	Description
`CELERY_BACKEND`	`redis`	Where Celery stores task results. Options: `redis` (fast, in-memory) or `database` (stores in your main database).
`BROKER_USE_SSL`	`false`	Auto-enabled when `CELERY_BROKER_URL` uses `rediss://` scheme. Applies the Redis SSL certificate settings to the broker connection.
`CELERY_USE_SENTINEL`	`false`	Enable Redis Sentinel mode for the Celery broker.
`CELERY_SENTINEL_MASTER_NAME`	(empty)	Sentinel service name (Master Name).
`CELERY_SENTINEL_PASSWORD`	(empty)	Password for Sentinel authentication. Separate from `REDIS_SENTINEL_PASSWORD`; the two can differ if caching and task queuing use different Sentinel clusters.
`CELERY_SENTINEL_SOCKET_TIMEOUT`	`0.1`	Timeout for connecting to Sentinel in seconds.
`CELERY_TASK_ANNOTATIONS`	`null`	Apply runtime settings to specific tasks (e.g., rate limits). Format: JSON dictionary. Example: `{"tasks.add": {"rate_limit": "10/s"}}`. Most users don’t need this.

CORS Configuration

Controls cross-domain access policies for the frontend.

Variable	Default	Description
`WEB_API_CORS_ALLOW_ORIGINS`	`*`	Allowed origins for cross-origin requests to the Web API. Example: `https://dify.app`
`CONSOLE_CORS_ALLOW_ORIGINS`	`*`	Allowed origins for cross-origin requests to the console API. If not set, falls back to `CONSOLE_WEB_URL`.
`COOKIE_DOMAIN`	(empty)	Set to the shared top-level domain (e.g., `example.com`) when frontend and backend run on different subdomains. This allows authentication cookies to be shared across subdomains. When empty, cookies use the most secure `__Host-` prefix and are locked to a single domain.
`NEXT_PUBLIC_COOKIE_DOMAIN`	(empty)	Frontend flag for cross-subdomain cookies. Set to `1` (or any non-empty value) to enable—the actual domain is read from `COOKIE_DOMAIN` on the backend.
`NEXT_PUBLIC_SOCKET_URL`	`ws://localhost`	Browser-side WebSocket endpoint for real-time collaboration. Scheme + host + port only (path `/socket.io/` is fixed). Swap `http(s)://` for `ws(s)://`. Example: `wss://dify.example.com`. The default targets the bundled nginx on port 80. Applied at runtime; container restart picks up changes.
`NEXT_PUBLIC_BATCH_CONCURRENCY`	`5`	Frontend-only. Controls how many concurrent API calls the UI makes during batch operations.

Dify CLI and Programmatic API

The /openapi/v1/* surface is the user-scoped programmatic API that the Dify CLI (difyctl) and other clients authenticate against with OAuth bearer tokens. It ships disabled: set both OPENAPI_ENABLED and ENABLE_OAUTH_BEARER to true to use the CLI against your deployment.

Variable	Default	Description
`OPENAPI_ENABLED`	`false`	Master switch for the `/openapi/v1/` programmatic API used by the Dify CLI (`difyctl`). When `false`, every `/openapi/v1/` endpoint returns 404 and `difyctl login` cannot start. Enable together with `ENABLE_OAUTH_BEARER`.
`ENABLE_OAUTH_BEARER`	`false`	Binds the OAuth bearer authenticator for `/openapi/v1/*` and gates device-flow login approval. With `OPENAPI_ENABLED=true` but this `false`, `difyctl login` fails with 503 at the approval step. Both must be `true` for the CLI to work.
`OPENAPI_KNOWN_CLIENT_IDS`	`difyctl`	Comma-separated OAuth client IDs allowed to start a device-flow login. Add IDs to admit other clients without code changes; removing `difyctl` breaks CLI login with `unsupported_client`.
`OAUTH_TTL_DAYS`	`14`	How many days a `difyctl login` stays valid, counted from the login. Accepts 1–365; values outside that range are clamped to the nearest end. Changes apply only to new logins.
`OPENAPI_CORS_ALLOW_ORIGINS`	(empty)	Browser origins allowed to call `/openapi/v1/*` cross-origin, comma-separated. Empty allows none, which is fine for the standard deployment and irrelevant to non-browser clients like the CLI.
`OPENAPI_RATE_LIMIT_PER_TOKEN`	`60`	Requests per minute per OAuth bearer token across `/openapi/v1/*`, shared across API replicas via Redis. Exceeding it returns 429 with a `Retry-After` header. `0` disables the limit.
`DEVICE_FLOW_APPROVE_RATE_LIMIT_PER_HOUR`	`10`	Device-flow login approvals or denials one browser session can perform per hour. Beyond that, approvals return 429 until the window passes. Cannot be `0`.

File Storage Configuration

Configure where Dify stores uploaded files, dataset documents, and encryption keys. Each storage type has its own credential variables—configure only the one you’re using.

STORAGE_TYPE

Default: opendal Selects the file storage backend. Supported values: opendal, s3, azure-blob, aliyun-oss, google-storage, huawei-obs, volcengine-tos, tencent-cos, baidu-obs, oci-storage, supabase, clickzetta-volume, local (deprecated; internally uses OpenDAL with filesystem scheme).

OpenDAL (Default)

Default storage backend using Apache OpenDAL, a unified interface supporting many storage services. Dify automatically scans environment variables matching OPENDAL_<SCHEME>_* and passes them to OpenDAL. For example, with OPENDAL_SCHEME=s3, set OPENDAL_S3_ACCESS_KEY_ID, OPENDAL_S3_SECRET_ACCESS_KEY, etc.

Variable	Default	Description
`OPENDAL_SCHEME`	`fs`	Storage service to use. Examples: `fs` (local filesystem), `s3`, `gcs`, `azblob`.

For the default fs scheme:

Variable	Default	Description
`OPENDAL_FS_ROOT`	`storage`	Root directory for local filesystem storage. Created automatically if it doesn’t exist.

For all available schemes and their configuration options, see the OpenDAL services documentation.

Variable	Default	Description
`S3_ENDPOINT`	(empty)	S3 endpoint address. Required for non-AWS S3-compatible services (MinIO, etc.).
`S3_REGION`	`us-east-1`	S3 region.
`S3_BUCKET_NAME`	`difyai`	S3 bucket name.
`S3_ACCESS_KEY`	(empty)	S3 Access Key. Not needed when using IAM roles.
`S3_SECRET_KEY`	(empty)	S3 Secret Key. Not needed when using IAM roles.
`S3_ADDRESS_STYLE`	`auto`	S3 addressing style: `auto`, `path`, or `virtual`. Controls whether bucket names appear in the URL path (`path`) or as a subdomain (`virtual`). Only applies when `S3_USE_AWS_MANAGED_IAM` is `false`.
`S3_USE_AWS_MANAGED_IAM`	`false`	Use AWS IAM roles (EC2 instance profile, ECS task role) instead of explicit access key/secret key. When enabled, credentials are auto-discovered from the instance metadata.

Azure Blob

Variable	Default	Description
`AZURE_BLOB_ACCOUNT_NAME`	`difyai`	Azure storage account name.
`AZURE_BLOB_ACCOUNT_KEY`	`difyai`	Azure storage account key.
`AZURE_BLOB_CONTAINER_NAME`	`difyai-container`	Azure Blob container name.
`AZURE_BLOB_ACCOUNT_URL`	`https://<your_account_name>.blob.core.windows.net`	Azure Blob account URL.

Google Cloud Storage

Variable	Default	Description
`GOOGLE_STORAGE_BUCKET_NAME`	(empty)	Google Cloud Storage bucket name.
`GOOGLE_STORAGE_SERVICE_ACCOUNT_JSON_BASE64`	(empty)	Base64-encoded service account JSON key.

Alibaba Cloud OSS

Variable	Default	Description
`ALIYUN_OSS_BUCKET_NAME`	(empty)	OSS bucket name.
`ALIYUN_OSS_ACCESS_KEY`	(empty)	OSS access key.
`ALIYUN_OSS_SECRET_KEY`	(empty)	OSS secret key.
`ALIYUN_OSS_ENDPOINT`	`https://oss-ap-southeast-1-internal.aliyuncs.com`	OSS endpoint. Regions and endpoints reference.
`ALIYUN_OSS_REGION`	`ap-southeast-1`	OSS region.
`ALIYUN_OSS_AUTH_VERSION`	`v4`	OSS authentication version.
`ALIYUN_OSS_PATH`	(empty)	Object path prefix. Don’t start with `/`. Reference.
`ALIYUN_CLOUDBOX_ID`	(empty)	CloudBox ID for CloudBox-based OSS deployments.

Tencent Cloud COS

Variable	Default	Description
`TENCENT_COS_BUCKET_NAME`	(empty)	COS bucket name.
`TENCENT_COS_SECRET_KEY`	(empty)	COS secret key.
`TENCENT_COS_SECRET_ID`	(empty)	COS secret ID.
`TENCENT_COS_REGION`	(empty)	COS region, e.g., `ap-guangzhou`. Reference.
`TENCENT_COS_SCHEME`	(empty)	Protocol to access COS (`http` or `https`).
`TENCENT_COS_CUSTOM_DOMAIN`	(empty)	Custom domain for COS access.

OCI Object Storage

Variable	Default	Description
`OCI_ENDPOINT`	(empty)	OCI endpoint URL.
`OCI_BUCKET_NAME`	(empty)	OCI bucket name.
`OCI_ACCESS_KEY`	(empty)	OCI access key.
`OCI_SECRET_KEY`	(empty)	OCI secret key.
`OCI_REGION`	`us-ashburn-1`	OCI region.

Huawei OBS

Variable	Default	Description
`HUAWEI_OBS_BUCKET_NAME`	(empty)	OBS bucket name.
`HUAWEI_OBS_ACCESS_KEY`	(empty)	OBS access key.
`HUAWEI_OBS_SECRET_KEY`	(empty)	OBS secret key.
`HUAWEI_OBS_SERVER`	(empty)	OBS server URL. Reference.
`HUAWEI_OBS_PATH_STYLE`	`false`	Use path-style URLs instead of virtual-hosted-style.

Volcengine TOS

Variable	Default	Description
`VOLCENGINE_TOS_BUCKET_NAME`	(empty)	TOS bucket name.
`VOLCENGINE_TOS_ACCESS_KEY`	(empty)	TOS access key.
`VOLCENGINE_TOS_SECRET_KEY`	(empty)	TOS secret key.
`VOLCENGINE_TOS_ENDPOINT`	(empty)	TOS endpoint URL. Reference.
`VOLCENGINE_TOS_REGION`	(empty)	TOS region, e.g., `cn-guangzhou`.

Baidu OBS

Variable	Default	Description
`BAIDU_OBS_BUCKET_NAME`	(empty)	Baidu OBS bucket name.
`BAIDU_OBS_ACCESS_KEY`	(empty)	Baidu OBS access key.
`BAIDU_OBS_SECRET_KEY`	(empty)	Baidu OBS secret key.
`BAIDU_OBS_ENDPOINT`	(empty)	Baidu OBS server URL.

Supabase

Variable	Default	Description
`SUPABASE_BUCKET_NAME`	(empty)	Supabase storage bucket name.
`SUPABASE_API_KEY`	(empty)	Supabase API key.
`SUPABASE_URL`	(empty)	Supabase server URL.

ClickZetta Volume

Variable	Default	Description
`CLICKZETTA_VOLUME_TYPE`	`user`	Volume type. Options: `user` (personal/small team), `table` (enterprise multi-tenant), `external` (data lake integration).
`CLICKZETTA_VOLUME_NAME`	(empty)	External volume name (required only when `TYPE=external`).
`CLICKZETTA_VOLUME_TABLE_PREFIX`	`dataset_`	Table volume table prefix (used only when `TYPE=table`).
`CLICKZETTA_VOLUME_DIFY_PREFIX`	`dify_km`	Dify file directory prefix for isolation from other apps.

ClickZetta Volume reuses the CLICKZETTA_* connection parameters configured in the Vector Database section.

Archive Storage

Separate S3-compatible storage for archiving workflow run logs. The archive-workflow-runs maintenance command packs runs older than a chosen cutoff into monthly Parquet bundles; CSV exports generated from those archives are staged in the export bucket.

Variable	Default	Description
`ARCHIVE_STORAGE_ENABLED`	`false`	Enable archive storage for workflow log archival.
`ARCHIVE_STORAGE_ENDPOINT`	(empty)	S3-compatible endpoint URL.
`ARCHIVE_STORAGE_ARCHIVE_BUCKET`	(empty)	Bucket for archived workflow run logs.
`ARCHIVE_STORAGE_EXPORT_BUCKET`	(empty)	Bucket for temporary CSV export ZIPs generated from archived logs. Safe to auto-expire with a bucket lifecycle rule.
`ARCHIVE_STORAGE_ACCESS_KEY`	(empty)	Access key.
`ARCHIVE_STORAGE_SECRET_KEY`	(empty)	Secret key.
`ARCHIVE_STORAGE_REGION`	`auto`	Storage region.
`ARCHIVE_STORAGE_ADDRESS_STYLE`	`path`	S3 addressing style for archive storage, which sets where the bucket name goes in request URLs. Switch to `virtual` if your provider rejects path-style requests. `path` puts it in the path (`https://<endpoint>/<bucket>/...`) `virtual` in the hostname (`https://<bucket>.<endpoint>/...`) `auto` lets the S3 client decide. Applies to both the archive and export buckets, including the download links for CSV exports. Set separately from `S3_ADDRESS_STYLE`, which has a different default.

Vector Database Configuration

Configure the vector database used for knowledge base embedding storage and similarity search. Each provider has its own set of credential variables—configure only the one you’re using.

VECTOR_STORE

Default: weaviate Selects the vector database backend. If a dataset already has an index, the dataset’s stored type takes precedence over this setting. When switching providers in Docker Compose, COMPOSE_PROFILES automatically starts the matching container based on this value. Supported values: weaviate, oceanbase, seekdb, qdrant, milvus, myscale, relyt, pgvector, pgvecto-rs, chroma, opensearch, oracle, tencent, elasticsearch, elasticsearch-ja, analyticdb, couchbase, vikingdb, opengauss, tablestore, vastbase, tidb, tidb_on_qdrant, baidu, lindorm, huawei_cloud, upstash, matrixone, clickzetta, alibabacloud_mysql, iris, hologres.

Variable	Default	Description
`VECTOR_INDEX_NAME_PREFIX`	`Vector_index`	Prefix added to collection names in the vector database. Change this if you share a vector database instance across multiple Dify deployments.

Weaviate

Variable	Default	Description
`WEAVIATE_ENDPOINT`	`http://weaviate:8080`	Weaviate REST API endpoint.
`WEAVIATE_API_KEY`	(empty)	API key for Weaviate authentication.
`WEAVIATE_GRPC_ENDPOINT`	`grpc://weaviate:50051`	Separate gRPC endpoint for high-performance binary protocol. Significantly faster for batch operations. Falls back to inferring from HTTP endpoint if not set.
`WEAVIATE_TOKENIZATION`	`word`	Tokenization method for text fields. Options: `word` (splits on whitespace and punctuation), `whitespace` (splits on whitespace only), `character` (character-level, better for CJK languages).

OceanBase / seekdb

seekdb is the lite version of OceanBase and shares the same connection configuration.

Variable	Default	Description
`OCEANBASE_VECTOR_HOST`	`oceanbase`	Hostname or IP address.
`OCEANBASE_VECTOR_PORT`	`2881`	Port number.
`OCEANBASE_VECTOR_USER`	`root@test`	Database username.
`OCEANBASE_VECTOR_PASSWORD`	`difyai123456`	Database password.
`OCEANBASE_VECTOR_DATABASE`	`test`	Database name.
`OCEANBASE_CLUSTER_NAME`	`difyai`	Cluster name (Docker deployment only).
`OCEANBASE_MEMORY_LIMIT`	`6G`	Memory limit for OceanBase (Docker deployment only).
`SEEKDB_MEMORY_LIMIT`	`2G`	Memory limit for seekdb (Docker deployment only).
`OCEANBASE_ENABLE_HYBRID_SEARCH`	`false`	Enable fulltext index for BM25 queries alongside vector search. Requires OceanBase >= 4.3.5.1. Collections must be recreated after enabling.
`OCEANBASE_FULLTEXT_PARSER`	`ik`	Fulltext parser. Built-in: `ngram`, `beng`, `space`, `ngram2`, `ik`. External (require plugin): `japanese_ftparser`, `thai_ftparser`.

Qdrant

Variable	Default	Description
`QDRANT_URL`	`http://qdrant:6333`	Qdrant endpoint address.
`QDRANT_API_KEY`	`difyai123456`	API key for Qdrant.
`QDRANT_CLIENT_TIMEOUT`	`20`	Client timeout in seconds.
`QDRANT_GRPC_ENABLED`	`false`	Enable gRPC communication.
`QDRANT_GRPC_PORT`	`6334`	gRPC port.
`QDRANT_REPLICATION_FACTOR`	`1`	Number of replicas per shard.

Milvus

Variable	Default	Description
`MILVUS_URI`	`http://host.docker.internal:19530`	Milvus URI. For Zilliz Cloud, use the Public Endpoint.
`MILVUS_DATABASE`	(empty)	Database name.
`MILVUS_TOKEN`	(empty)	Authentication token. For Zilliz Cloud, use the API Key.
`MILVUS_USER`	(empty)	Username.
`MILVUS_PASSWORD`	(empty)	Password.
`MILVUS_ENABLE_HYBRID_SEARCH`	`false`	Enable BM25 sparse index for full-text search alongside vector similarity. Requires Milvus >= 2.5.0. If the collection was created without this enabled, it must be recreated.
`MILVUS_ANALYZER_PARAMS`	(empty)	Analyzer parameters for text fields.
`MILVUS_SECURE`	`false`	Enable one-way TLS for the Milvus connection. When enabled, the client connects over gRPC with TLS and verifies the server certificate.
`MILVUS_SERVER_PEM_PATH`	(empty)	Path inside the container to the Milvus server certificate (PEM), used to verify the server when `MILVUS_SECURE` is enabled.
`MILVUS_SERVER_NAME`	(empty)	Server name (TLS SNI, matching the certificate’s CN or SAN) to verify against. Required when `MILVUS_SERVER_PEM_PATH` is set.

MyScale

Variable	Default	Description
`MYSCALE_HOST`	`myscale`	MyScale host.
`MYSCALE_PORT`	`8123`	MyScale port.
`MYSCALE_USER`	`default`	Username.
`MYSCALE_PASSWORD`	(empty)	Password.
`MYSCALE_DATABASE`	`dify`	Database name.
`MYSCALE_FTS_PARAMS`	(empty)	Full-text search params. Multi-language support reference.

Couchbase

Variable	Default	Description
`COUCHBASE_CONNECTION_STRING`	`couchbase://couchbase-server`	Connection string for the Couchbase cluster.
`COUCHBASE_USER`	`Administrator`	Username.
`COUCHBASE_PASSWORD`	`password`	Password.
`COUCHBASE_BUCKET_NAME`	`Embeddings`	Bucket name.
`COUCHBASE_SCOPE_NAME`	`_default`	Scope name.

Hologres

Variable	Default	Description
`HOLOGRES_HOST`	(empty)	Hostname.
`HOLOGRES_PORT`	`80`	Port number.
`HOLOGRES_DATABASE`	(empty)	Database name.
`HOLOGRES_ACCESS_KEY_ID`	(empty)	Access key ID (used as PG username).
`HOLOGRES_ACCESS_KEY_SECRET`	(empty)	Access key secret (used as PG password).
`HOLOGRES_SCHEMA`	`public`	Schema name.
`HOLOGRES_TOKENIZER`	`jieba`	Tokenizer for text fields.
`HOLOGRES_DISTANCE_METHOD`	`Cosine`	Distance method.
`HOLOGRES_BASE_QUANTIZATION_TYPE`	`rabitq`	Quantization type.
`HOLOGRES_MAX_DEGREE`	`64`	HNSW max degree.
`HOLOGRES_EF_CONSTRUCTION`	`400`	HNSW ef_construction parameter.

PGVector

Variable	Default	Description
`PGVECTOR_HOST`	`pgvector`	Hostname.
`PGVECTOR_PORT`	`5432`	Port number.
`PGVECTOR_USER`	`postgres`	Username.
`PGVECTOR_PASSWORD`	`difyai123456`	Password.
`PGVECTOR_DATABASE`	`dify`	Database name.
`PGVECTOR_MIN_CONNECTION`	`1`	Minimum pool connections.
`PGVECTOR_MAX_CONNECTION`	`5`	Maximum pool connections.
`PGVECTOR_PG_BIGM`	`false`	Enable pg_bigm extension for full-text search.

Vastbase

Variable	Default	Description
`VASTBASE_HOST`	`vastbase`	Hostname.
`VASTBASE_PORT`	`5432`	Port number.
`VASTBASE_USER`	`dify`	Username.
`VASTBASE_PASSWORD`	`Difyai123456`	Password.
`VASTBASE_DATABASE`	`dify`	Database name.
`VASTBASE_MIN_CONNECTION`	`1`	Minimum pool connections.
`VASTBASE_MAX_CONNECTION`	`5`	Maximum pool connections.

PGVecto.RS

Variable	Default	Description
`PGVECTO_RS_HOST`	`pgvecto-rs`	Hostname.
`PGVECTO_RS_PORT`	`5432`	Port number.
`PGVECTO_RS_USER`	`postgres`	Username.
`PGVECTO_RS_PASSWORD`	`difyai123456`	Password.
`PGVECTO_RS_DATABASE`	`dify`	Database name.

AnalyticDB

Variable	Default	Description
`ANALYTICDB_KEY_ID`	(empty)	Aliyun access key ID. Create AccessKey.
`ANALYTICDB_KEY_SECRET`	(empty)	Aliyun access key secret.
`ANALYTICDB_REGION_ID`	`cn-hangzhou`	Region identifier.
`ANALYTICDB_INSTANCE_ID`	(empty)	Instance ID, e.g., `gp-xxxxxx`. Create instance.
`ANALYTICDB_ACCOUNT`	(empty)	Account name. Create account.
`ANALYTICDB_PASSWORD`	(empty)	Account password.
`ANALYTICDB_NAMESPACE`	`dify`	Namespace (schema). Created automatically if not exists.
`ANALYTICDB_NAMESPACE_PASSWORD`	(empty)	Namespace password. Used when creating a new namespace.
`ANALYTICDB_HOST`	(empty)	Direct connection host (alternative to API-based access).
`ANALYTICDB_PORT`	`5432`	Direct connection port.
`ANALYTICDB_MIN_CONNECTION`	`1`	Minimum pool connections.
`ANALYTICDB_MAX_CONNECTION`	`5`	Maximum pool connections.

TiDB Vector

Variable	Default	Description
`TIDB_VECTOR_HOST`	`tidb`	Hostname.
`TIDB_VECTOR_PORT`	`4000`	Port number.
`TIDB_VECTOR_USER`	(empty)	Username.
`TIDB_VECTOR_PASSWORD`	(empty)	Password.
`TIDB_VECTOR_DATABASE`	`dify`	Database name.
`TIDB_VECTOR_ENABLE_FULLTEXT_SEARCH`	`false`	Unlocks the Full-Text Search and Hybrid Search retrieval options for knowledge bases on TiDB Vector. New knowledge base tables get a multilingual full-text index; existing tables gain it the next time documents are indexed. Requires a TiDB deployment that supports full-text indexes.

MatrixOne

Variable	Default	Description
`MATRIXONE_HOST`	`matrixone`	Hostname.
`MATRIXONE_PORT`	`6001`	Port number.
`MATRIXONE_USER`	`dump`	Username.
`MATRIXONE_PASSWORD`	`111`	Password.
`MATRIXONE_DATABASE`	`dify`	Database name.

Chroma

VariableDefaultDescription
CHROMA_HOST127.0.0.1Chroma server host.
CHROMA_PORT8000Chroma server port.
CHROMA_TENANTdefault_tenantTenant name.
CHROMA_DATABASEdefault_databaseDatabase name.
CHROMA_AUTH_PROVIDERchromadb.auth.token_authn.TokenAuthClientProviderAuth provider class.
CHROMA_AUTH_CREDENTIALS(empty)Auth credentials.

Variable	Default	Description
`CHROMA_HOST`	`127.0.0.1`	Chroma server host.
`CHROMA_PORT`	`8000`	Chroma server port.
`CHROMA_TENANT`	`default_tenant`	Tenant name.
`CHROMA_DATABASE`	`default_database`	Database name.
`CHROMA_AUTH_PROVIDER`	`chromadb.auth.token_authn.TokenAuthClientProvider`	Auth provider class.
`CHROMA_AUTH_CREDENTIALS`	(empty)	Auth credentials.

Oracle

Variable	Default	Description
`ORACLE_USER`	`dify`	Oracle username.
`ORACLE_PASSWORD`	`dify`	Oracle password.
`ORACLE_DSN`	`oracle:1521/FREEPDB1`	Data source name.
`ORACLE_CONFIG_DIR`	`/app/api/storage/wallet`	Oracle configuration directory.
`ORACLE_WALLET_LOCATION`	`/app/api/storage/wallet`	Wallet location for Autonomous DB.
`ORACLE_WALLET_PASSWORD`	`dify`	Wallet password.
`ORACLE_IS_AUTONOMOUS`	`false`	Whether using Oracle Autonomous Database.

AlibabaCloud MySQL

Variable	Default	Description
`ALIBABACLOUD_MYSQL_HOST`	`127.0.0.1`	Hostname.
`ALIBABACLOUD_MYSQL_PORT`	`3306`	Port number.
`ALIBABACLOUD_MYSQL_USER`	`root`	Username.
`ALIBABACLOUD_MYSQL_PASSWORD`	`difyai123456`	Password.
`ALIBABACLOUD_MYSQL_DATABASE`	`dify`	Database name.
`ALIBABACLOUD_MYSQL_MAX_CONNECTION`	`5`	Maximum pool connections.
`ALIBABACLOUD_MYSQL_HNSW_M`	`6`	HNSW M parameter.

Relyt

Variable	Default	Description
`RELYT_HOST`	`db`	Hostname.
`RELYT_PORT`	`5432`	Port number.
`RELYT_USER`	`postgres`	Username.
`RELYT_PASSWORD`	`difyai123456`	Password.
`RELYT_DATABASE`	`postgres`	Database name.

OpenSearch

Variable	Default	Description
`OPENSEARCH_HOST`	`opensearch`	Hostname.
`OPENSEARCH_PORT`	`9200`	Port number.
`OPENSEARCH_SECURE`	`true`	Use HTTPS.
`OPENSEARCH_VERIFY_CERTS`	`true`	Verify SSL certificates.
`OPENSEARCH_AUTH_METHOD`	`basic`	`basic` uses username/password. `aws_managed_iam` uses AWS SigV4 request signing via Boto3 credentials (for AWS Managed OpenSearch or Serverless).
`OPENSEARCH_USER`	`admin`	Username. Only used with `basic` auth.
`OPENSEARCH_PASSWORD`	`admin`	Password. Only used with `basic` auth.
`OPENSEARCH_AWS_REGION`	`ap-southeast-1`	AWS region. Only used with `aws_managed_iam` auth.
`OPENSEARCH_AWS_SERVICE`	`aoss`	AWS service type: `es` (Managed Cluster) or `aoss` (OpenSearch Serverless). Only used with `aws_managed_iam` auth.

Tencent Cloud VectorDB

Variable	Default	Description
`TENCENT_VECTOR_DB_URL`	`http://127.0.0.1`	Access address. Console.
`TENCENT_VECTOR_DB_API_KEY`	`dify`	API key. Key Management.
`TENCENT_VECTOR_DB_TIMEOUT`	`30`	Request timeout in seconds.
`TENCENT_VECTOR_DB_USERNAME`	`dify`	Account name. Account Management.
`TENCENT_VECTOR_DB_DATABASE`	`dify`	Database name. Create Database.
`TENCENT_VECTOR_DB_SHARD`	`1`	Number of shards.
`TENCENT_VECTOR_DB_REPLICAS`	`2`	Number of replicas.
`TENCENT_VECTOR_DB_ENABLE_HYBRID_SEARCH`	`false`	Enable hybrid search. Sparse Vector docs.

Elasticsearch

Variable	Default	Description
`ELASTICSEARCH_HOST`	`0.0.0.0`	Hostname.
`ELASTICSEARCH_PORT`	`9200`	Port number.
`ELASTICSEARCH_USERNAME`	`elastic`	Username.
`ELASTICSEARCH_PASSWORD`	`elastic`	Password.
`ELASTICSEARCH_USE_CLOUD`	`false`	Switch to Elastic Cloud mode. When `true`, uses `ELASTICSEARCH_CLOUD_URL` and `ELASTICSEARCH_API_KEY` instead of host/port/username/password.
`ELASTICSEARCH_CLOUD_URL`	(empty)	Elastic Cloud endpoint URL. Required when `ELASTICSEARCH_USE_CLOUD=true`.
`ELASTICSEARCH_API_KEY`	(empty)	Elastic Cloud API key. Required when `ELASTICSEARCH_USE_CLOUD=true`.
`ELASTICSEARCH_VERIFY_CERTS`	`false`	Verify SSL certificates.
`ELASTICSEARCH_CA_CERTS`	(empty)	Path to CA certificates.
`ELASTICSEARCH_REQUEST_TIMEOUT`	`100000`	Request timeout in milliseconds.
`ELASTICSEARCH_RETRY_ON_TIMEOUT`	`true`	Retry on timeout.
`ELASTICSEARCH_MAX_RETRIES`	`10`	Maximum retry attempts.

Baidu Vector DB

Variable	Default	Description
`BAIDU_VECTOR_DB_ENDPOINT`	`http://127.0.0.1:5287`	Endpoint URL.
`BAIDU_VECTOR_DB_CONNECTION_TIMEOUT_MS`	`30000`	Connection timeout in milliseconds.
`BAIDU_VECTOR_DB_ACCOUNT`	`root`	Account name.
`BAIDU_VECTOR_DB_API_KEY`	`dify`	API key.
`BAIDU_VECTOR_DB_DATABASE`	`dify`	Database name.
`BAIDU_VECTOR_DB_SHARD`	`1`	Number of shards.
`BAIDU_VECTOR_DB_REPLICAS`	`3`	Number of replicas.
`BAIDU_VECTOR_DB_INVERTED_INDEX_ANALYZER`	`DEFAULT_ANALYZER`	Inverted index analyzer.
`BAIDU_VECTOR_DB_INVERTED_INDEX_PARSER_MODE`	`COARSE_MODE`	Inverted index parser mode.
`BAIDU_VECTOR_DB_AUTO_BUILD_ROW_COUNT_INCREMENT`	`500`	Absolute row-count increment that triggers an automatic index rebuild on the Baidu Vector DB side. Works alongside `_RATIO`; whichever threshold is crossed first wins.
`BAIDU_VECTOR_DB_AUTO_BUILD_ROW_COUNT_INCREMENT_RATIO`	`0.05`	Relative growth (new rows / existing rows) that triggers an automatic index rebuild. Whichever threshold is crossed first wins.
`BAIDU_VECTOR_DB_REBUILD_INDEX_TIMEOUT_IN_SECONDS`	`300`	Maximum time the client waits for an index rebuild to complete. On timeout, the client call fails but the server-side rebuild may still finish; retrying the query after a delay typically succeeds.

VikingDB

Variable	Default	Description
`VIKINGDB_ACCESS_KEY`	(empty)	Access key.
`VIKINGDB_SECRET_KEY`	(empty)	Secret key.
`VIKINGDB_REGION`	`cn-shanghai`	Region.
`VIKINGDB_HOST`	`api-vikingdb.xxx.volces.com`	API host. Replace with your region-specific endpoint.
`VIKINGDB_SCHEME`	`http`	Protocol scheme (`http` or `https`).
`VIKINGDB_CONNECTION_TIMEOUT`	`30`	Connection timeout in seconds.
`VIKINGDB_SOCKET_TIMEOUT`	`30`	Socket timeout in seconds.

Lindorm

Variable	Default	Description
`LINDORM_URL`	`http://localhost:30070`	Lindorm search engine URL. Console.
`LINDORM_USERNAME`	`admin`	Username.
`LINDORM_PASSWORD`	`admin`	Password.
`LINDORM_USING_UGC`	`true`	Use UGC mode.
`LINDORM_QUERY_TIMEOUT`	`1`	Query timeout in seconds.

OpenGauss

Variable	Default	Description
`OPENGAUSS_HOST`	`opengauss`	Hostname.
`OPENGAUSS_PORT`	`6600`	Port number.
`OPENGAUSS_USER`	`postgres`	Username.
`OPENGAUSS_PASSWORD`	`Dify@123`	Password.
`OPENGAUSS_DATABASE`	`dify`	Database name.
`OPENGAUSS_MIN_CONNECTION`	`1`	Minimum pool connections.
`OPENGAUSS_MAX_CONNECTION`	`5`	Maximum pool connections.
`OPENGAUSS_ENABLE_PQ`	`false`	Enable PQ acceleration.

Huawei Cloud Search

Variable	Default	Description
`HUAWEI_CLOUD_HOSTS`	`https://127.0.0.1:9200`	Cluster endpoint URL.
`HUAWEI_CLOUD_USER`	`admin`	Username.
`HUAWEI_CLOUD_PASSWORD`	`admin`	Password.

Upstash Vector

Variable	Default	Description
`UPSTASH_VECTOR_URL`	(empty)	Upstash Vector endpoint URL.
`UPSTASH_VECTOR_TOKEN`	(empty)	Upstash Vector API token.

TableStore

Variable	Default	Description
`TABLESTORE_ENDPOINT`	`https://instance-name.cn-hangzhou.ots.aliyuncs.com`	Endpoint address. Replace `instance-name` with your instance.
`TABLESTORE_INSTANCE_NAME`	(empty)	Instance name.
`TABLESTORE_ACCESS_KEY_ID`	(empty)	Access key ID.
`TABLESTORE_ACCESS_KEY_SECRET`	(empty)	Access key secret.
`TABLESTORE_NORMALIZE_FULLTEXT_BM25_SCORE`	`false`	Normalize fulltext BM25 scores.

ClickZetta

Variable	Default	Description
`CLICKZETTA_USERNAME`	(empty)	Username.
`CLICKZETTA_PASSWORD`	(empty)	Password.
`CLICKZETTA_INSTANCE`	(empty)	Instance name.
`CLICKZETTA_SERVICE`	`api.clickzetta.com`	Service endpoint.
`CLICKZETTA_WORKSPACE`	`quick_start`	Workspace name.
`CLICKZETTA_VCLUSTER`	`default_ap`	Virtual cluster.
`CLICKZETTA_SCHEMA`	`dify`	Schema name.
`CLICKZETTA_BATCH_SIZE`	`100`	Batch size for operations.
`CLICKZETTA_ENABLE_INVERTED_INDEX`	`true`	Enable inverted index.
`CLICKZETTA_ANALYZER_TYPE`	`chinese`	Analyzer type.
`CLICKZETTA_ANALYZER_MODE`	`smart`	Analyzer mode.
`CLICKZETTA_VECTOR_DISTANCE_FUNCTION`	`cosine_distance`	Distance function.

InterSystems IRIS

Variable	Default	Description
`IRIS_HOST`	`iris`	Hostname.
`IRIS_SUPER_SERVER_PORT`	`1972`	Super server port.
`IRIS_USER`	`_SYSTEM`	Username.
`IRIS_PASSWORD`	`Dify@1234`	Password.
`IRIS_DATABASE`	`USER`	Database name.
`IRIS_SCHEMA`	`dify`	Schema name.
`IRIS_CONNECTION_URL`	(empty)	Full connection URL (overrides individual settings).
`IRIS_MIN_CONNECTION`	`1`	Minimum pool connections.
`IRIS_MAX_CONNECTION`	`3`	Maximum pool connections.
`IRIS_TEXT_INDEX`	`true`	Enable text indexing.
`IRIS_TEXT_INDEX_LANGUAGE`	`en`	Text index language.

Knowledge Configuration

Variable	Default	Description
`UPLOAD_FILE_SIZE_LIMIT`	`15`	Maximum file size in MB for document uploads (PDFs, Word docs, etc.). Users see a “file too large” error when exceeded. Does not apply to images, videos, or audio—they have separate limits below.
`UPLOAD_FILE_BATCH_LIMIT`	`5`	Maximum number of files the frontend allows per upload batch.
`UPLOAD_FILE_EXTENSION_BLACKLIST`	(empty)	Security blocklist of file extensions that cannot be uploaded. Comma-separated, lowercase, no dots. Example: `exe,bat,cmd,com,scr,vbs,ps1,msi,dll`. Empty allows all types.
`SINGLE_CHUNK_ATTACHMENT_LIMIT`	`10`	Maximum number of images that can be embedded in a single knowledge base segment (chunk).
`IMAGE_FILE_BATCH_LIMIT`	`10`	Maximum number of image files per upload batch.
`ATTACHMENT_IMAGE_FILE_SIZE_LIMIT`	`2`	Maximum size in MB for images fetched from external URLs during knowledge base indexing. Images larger than this are skipped. Different from `UPLOAD_IMAGE_FILE_SIZE_LIMIT` which applies to direct uploads.
`ATTACHMENT_IMAGE_DOWNLOAD_TIMEOUT`	`60`	Timeout in seconds when downloading images from external URLs during knowledge base indexing. Slow or unresponsive image servers are abandoned after this timeout.
`ETL_TYPE`	`dify`	Document extraction library. `dify` supports txt, md, pdf, html, xlsx, docx, csv. `Unstructured` adds support for doc, msg, eml, ppt, pptx, xml, epub (requires `UNSTRUCTURED_API_URL`).
`UNSTRUCTURED_API_URL`	(empty)	Unstructured.io API endpoint. Required when `ETL_TYPE` is `Unstructured`. Also needed for `.ppt` file support. Example: `http://unstructured:8000/general/v0/general`.
`UNSTRUCTURED_API_KEY`	(empty)	API key for Unstructured.io authentication.
`SCARF_NO_ANALYTICS`	`true`	Disable Unstructured library’s telemetry/analytics collection.
`TOP_K_MAX_VALUE`	`10`	Maximum value users can set for the `top_k` parameter in knowledge base retrieval (how many results to return per search).
`DATASET_MAX_SEGMENTS_PER_REQUEST`	`0`	Maximum number of segments per dataset API request. `0` means unlimited.

Annotation Import

Variable	Default	Description
`ANNOTATION_IMPORT_FILE_SIZE_LIMIT`	`2`	Maximum CSV file size in MB for annotation import. Returns HTTP 413 when exceeded.
`ANNOTATION_IMPORT_MAX_RECORDS`	`10000`	Maximum number of records per annotation import. Files with more records must be split into batches.
`ANNOTATION_IMPORT_MIN_RECORDS`	`1`	Minimum number of valid records required per annotation import.
`ANNOTATION_IMPORT_RATE_LIMIT_PER_MINUTE`	`5`	Maximum annotation import requests per minute per workspace. Returns HTTP 429 when exceeded.
`ANNOTATION_IMPORT_RATE_LIMIT_PER_HOUR`	`20`	Maximum annotation import requests per hour per workspace.
`ANNOTATION_IMPORT_MAX_CONCURRENT`	`5`	Maximum concurrent annotation import tasks per workspace. Stale tasks are auto-cleaned after 2 minutes.

Model Configuration

Variable	Default	Description
`PLUGIN_BASED_TOKEN_COUNTING_ENABLED`	`false`	Use plugin-based token counting for accurate usage tracking. When disabled, token counting returns 0 (faster but cost tracking is less accurate).

Variable	Default	Description
`MULTIMODAL_SEND_FORMAT`	`base64`	How files are sent to multi-modal LLMs. `base64` embeds file data in the request (more compatible, works offline, larger payloads). `url` sends a signed URL for the model to fetch (faster, smaller requests, but the model must be able to reach `FILES_URL`).
`UPLOAD_IMAGE_FILE_SIZE_LIMIT`	`10`	Maximum image file size in MB for direct uploads (jpg, png, webp, gif, svg).
`UPLOAD_VIDEO_FILE_SIZE_LIMIT`	`100`	Maximum video file size in MB for direct uploads (mp4, mov, mpeg, webm).
`UPLOAD_AUDIO_FILE_SIZE_LIMIT`	`50`	Maximum audio file size in MB for direct uploads (mp3, m4a, wav, amr, mpga).

All upload size limits are also gated by NGINX_CLIENT_MAX_BODY_SIZE (default 100M). If you increase any upload limit above 100 MB, also increase NGINX_CLIENT_MAX_BODY_SIZE to match—otherwise Nginx rejects the upload with a 413 error.

Sentry Configuration

Sentry provides error tracking and performance monitoring. Each service has its own DSN to separate error reporting.

Variable	Default	Description
`SENTRY_DSN`	(empty)	Sentry DSN shared across services.
`API_SENTRY_DSN`	(empty)	Sentry DSN for the API service. Overrides `SENTRY_DSN` if set. Empty disables Sentry for the backend.
`API_SENTRY_TRACES_SAMPLE_RATE`	`1.0`	Fraction of requests to include in performance tracing (0.01 = 1%, 1.0 = 100%). Traces track request flow across services.
`API_SENTRY_PROFILES_SAMPLE_RATE`	`1.0`	Fraction of requests to include in CPU/memory profiling (0.01 = 1%). Profiles show where time is spent in code.
`SENTRY_TRACES_SAMPLE_RATE`	`1.0`	Direct name for `API_SENTRY_TRACES_SAMPLE_RATE`, used by the config files under `docker/envs/core-services/`. In the Compose stack the `API_SENTRY_*` value wins. No effect while the Sentry DSN is empty.
`SENTRY_PROFILES_SAMPLE_RATE`	`1.0`	Direct name for `API_SENTRY_PROFILES_SAMPLE_RATE`, used by the same config files. Profiling only samples requests already selected by the traces rate, so effective volume is traces rate × profiles rate.
`WEB_SENTRY_DSN`	(empty)	Sentry DSN for the web frontend (Next.js). Frontend-only.
`PLUGIN_SENTRY_ENABLED`	`false`	Enable Sentry for the plugin daemon service.
`PLUGIN_SENTRY_DSN`	(empty)	Sentry DSN for the plugin daemon.

Notion Integration Configuration

Connect Dify to Notion as a knowledge base data source. Get integration credentials at https://www.notion.so/my-integrations.

Variable	Default	Description
`NOTION_INTEGRATION_TYPE`	`public`	`public` uses standard OAuth 2.0 (requires HTTPS redirect URL, needs CLIENT_ID + CLIENT_SECRET). `internal` uses a direct integration token (works with HTTP). Use `internal` for local deployments.
`NOTION_CLIENT_SECRET`	(empty)	OAuth client secret. Required for `public` integration.
`NOTION_CLIENT_ID`	(empty)	OAuth client ID. Required for `public` integration.
`NOTION_INTERNAL_SECRET`	(empty)	Direct integration token from Notion. Required for `internal` integration.

Mail Configuration

Dify sends emails for account invitations, password resets, login codes, and Human Input node notifications. Configure one of the three supported providers. Email links require CONSOLE_WEB_URL to be set—see Common Variables.

Variable	Default	Description
`MAIL_TYPE`	`resend`	Mail provider: `resend`, `smtp`, or `sendgrid`.
`MAIL_DEFAULT_SEND_FROM`	(empty)	Default “From” address for all outgoing emails. Required.

Resend

Variable	Default	Description
`RESEND_API_URL`	`https://api.resend.com`	Resend API endpoint. Override for self-hosted Resend or proxy.
`RESEND_API_KEY`	(empty)	Resend API key. Required when `MAIL_TYPE=resend`.

SMTP

Three TLS modes: implicit TLS (SMTP_USE_TLS=true, SMTP_OPPORTUNISTIC_TLS=false, port 465), STARTTLS (SMTP_USE_TLS=true, SMTP_OPPORTUNISTIC_TLS=true, port 587), or plain (SMTP_USE_TLS=false, port 25).

Variable	Default	Description
`SMTP_SERVER`	(empty)	SMTP server address.
`SMTP_PORT`	`465`	SMTP server port. Use `587` for STARTTLS mode.
`SMTP_USERNAME`	(empty)	SMTP username. Can be empty for IP-whitelisted servers.
`SMTP_PASSWORD`	(empty)	SMTP password. Can be empty for IP-whitelisted servers.
`SMTP_USE_TLS`	`true`	Enable TLS. When `true` with `SMTP_OPPORTUNISTIC_TLS=false`, uses implicit TLS (`SMTP_SSL`).
`SMTP_OPPORTUNISTIC_TLS`	`false`	Use STARTTLS (explicit TLS) instead of implicit TLS. Must be used with `SMTP_USE_TLS=true`.
`SMTP_LOCAL_HOSTNAME`	(empty)	Override the hostname sent in SMTP HELO/EHLO. Required in Docker when your SMTP server rejects container hostnames (common with Google Workspace, Microsoft 365). Set to your domain, e.g., `mail.yourdomain.com`.

SendGrid

Variable	Default	Description
`SENDGRID_API_KEY`	(empty)	SendGrid API key. Required when `MAIL_TYPE=sendgrid`.

For more details, see the SendGrid documentation.

Other Configuration

Console Features

Variable	Default	Description
`ENABLE_LEARN_APP`	`true`	Shows the Learn Dify section: tutorial templates on the Explore page, the getting-started panel when Studio has no apps, and its show/hide toggle in the help menu. Set to `false` to hide all three.
`ENABLE_SKILL`	`true`	Shows the Skills entry in the main navigation. Set to `false` to hide skills from the workspace UI.

Authentication and Accounts

By default, sign-in is email + password, and new accounts come from workspace invitations or the initial setup wizard. The toggles below relax or tighten that.

Variable	Default	Description
`ENABLE_EMAIL_PASSWORD_LOGIN`	`true`	Sign in to the console with email and password. When disabled, the password form disappears from the sign-in page and the password login, password reset, and self-serve signup endpoints all return 403. Keep at least one sign-in method enabled—if every method is off, the sign-in page shows “Authentication method not configured” and no one can log in until you change the setting back.
`ENABLE_EMAIL_CODE_LOGIN`	`false`	Sign in with a one-time 6-digit code sent by email instead of a password. Requires mail delivery to be configured (see Mail Configuration)—without it, codes are never delivered. With `ALLOW_REGISTER=true`, entering a code for an unknown email also creates the account, so this doubles as a self-serve signup path.
`EMAIL_CODE_LOGIN_TOKEN_EXPIRY_MINUTES`	`5`	How long a sign-in code stays valid (in minutes). An expired code is rejected; request a new one to continue.
`EMAIL_CODE_LOGIN_MAX_ATTEMPTS`	`5`	How many wrong entries one sign-in code survives before it is invalidated and a new code must be requested.
`ENABLE_SOCIAL_OAUTH_LOGIN`	`false`	Shows GitHub and Google sign-in buttons on the console sign-in page. The buttons only work if the matching GitHub or Google OAuth app credentials are also configured on the API service; with the flag on but no credentials, sign-in attempts fail. First-time OAuth sign-ins create an account only when `ALLOW_REGISTER=true`.
`ALLOW_REGISTER`	`false`	Lets people create their own accounts: shows the sign-up link on the sign-in page (with password login enabled) and allows first-time email-code or OAuth sign-ins to create accounts. Leave `false` for an invite-only deployment—workspace invitations and the initial setup wizard always work regardless.
`ALLOW_CREATE_WORKSPACE`	`false`	Automatically creates a workspace for an account that doesn’t belong to one—during self-serve registration and at email-code or OAuth sign-in. When `false`, such accounts must wait for a workspace invitation. The admin workspace created by the setup wizard is unaffected.
`ENABLE_CHANGE_EMAIL`	`true`	Lets users change their account’s email address from the account settings page. The flow confirms the change with emailed verification codes, so it requires mail delivery to be configured. Set to `false` to lock account emails, e.g. when they must match an external directory.

LLMOps Trace Delivery

Traces of app runs are delivered to the configured LLMOps provider (Langfuse, LangSmith, Arize/Phoenix, and so on) by a background task. For Docker Compose deployments, set these variables in docker/envs/core-services/shared.env.

Variable	Default	Description
`OPS_TRACE_UNIFIED_ENABLED`	`false`	Set to `true` to give LangSmith and Arize/Phoenix traces a common structure for workflow runs, nodes, and their parent-child relationships. The default `false` uses each provider’s original tracing implementation. Other providers are unaffected. Each app still needs LLMOps enabled and a provider configured.
`OPS_AGENT_TRACE_ENABLED`	`false`	Set to `true` to include Agent model and tool calls in the traces of Agent apps and of Workflow and Chatflow apps with an Agent node. Agents inside a workflow tool that the app calls aren’t included. Also set `DIFY_AGENT_APPLICATION_TRACING_ENABLED` to `true`. While this is `false`, the tracing settings of Agent, Workflow, and Chatflow apps say Agent tracing isn’t available. Each app still needs tracing enabled, a provider configured, and Capture Agent internals on (the default).
`DIFY_AGENT_APPLICATION_TRACING_ENABLED`	`false`	The agent backend’s half of `OPS_AGENT_TRACE_ENABLED`; set both to `true` to trace Agents. Set it in `docker/envs/core-services/dify-agent.env`, not `shared.env`: the agent backend doesn’t read that file.
`ENABLE_APPLICATION_TRACE_RECONCILE_TASK`	`true`	Used only when `OPS_AGENT_TRACE_ENABLED` is `true`. Runs a background job every 30 seconds that resends Agent traces still waiting for delivery and deletes the Agent trace data Dify stores after the retention period (7 days by default). Traces already delivered to your tracing provider stay there.
`OPS_TRACE_RETRYABLE_DISPATCH_MAX_RETRIES`	`780`	How many times a trace delivery is retried after a transient failure before the trace is dropped. The default retry window (retries × `OPS_TRACE_RETRYABLE_DISPATCH_DELAY_SECONDS`) is sized to outlast the one-hour workflow limit plus the export grace period. Today only Arize/Phoenix tracing of nested workflows hits this path (a child trace arriving before its parent’s context). Cannot be `0`.
`OPS_TRACE_RETRYABLE_DISPATCH_DELAY_SECONDS`	`5`	Seconds between those retries; the total tolerance window is delay × max retries (about 65 minutes at defaults). Lower delivers nested traces sooner but exhausts the retry budget faster. Cannot be `0`.
`OPS_TRACE_PARENT_CONTEXT_TTL_SECONDS`	`3900`	How long in seconds a parent workflow’s trace context stays available for nested child traces to attach to. When `OPS_TRACE_UNIFIED_ENABLED` is `true`, keep this at or above the retry window (retries × delay). A lower value prevents Dify from loading its configuration.

Indexing

Variable	Default	Description
`INDEXING_MAX_SEGMENTATION_TOKENS_LENGTH`	`4000`	Maximum token length per text segment when chunking documents for the knowledge base. Larger values retain more context per chunk; smaller values provide finer granularity.

New User Defaults

Variable	Default	Description
`NEW_USER_DEFAULT_PLUGIN_IDS`	(empty)	Comma-separated Marketplace plugin IDs installed automatically when a new workspace is created.
`NEW_USER_DEFAULT_MODELS`	(empty)	Default models set up for a new workspace, comma-separated in `model_type:provider:model` format.

Workflow Generation

Variable	Default	Description
`WORKFLOW_GENERATION_TIMEOUT_MS`	`180000`	How long the UI waits for one `/create` or `/refine` app generation run. Read by the web container.
`WORKFLOW_GENERATOR_NODE_BUILDER_MAX_WORKERS`	`6`	Maximum concurrent node-builder LLM calls per `/create` or `/refine` generation request.

Token & Invitation

All token expiry variables control how long a one-time-use token stored in Redis remains valid. After expiry, the user must request a new token.

Variable	Default	Description
`INVITE_EXPIRY_HOURS`	`72`	How long a workspace invitation link stays valid (in hours).
`RESET_PASSWORD_TOKEN_EXPIRY_MINUTES`	`5`	Password reset token validity in minutes.
`EMAIL_REGISTER_TOKEN_EXPIRY_MINUTES`	`5`	Email registration token validity in minutes.
`CHANGE_EMAIL_TOKEN_EXPIRY_MINUTES`	`5`	Change email token validity in minutes.
`OWNER_TRANSFER_TOKEN_EXPIRY_MINUTES`	`5`	Workspace owner transfer token validity in minutes.

Code Execution Sandbox

These settings tell the API and Worker how to connect to the sandbox, a separate service that executes Code node (Python, JavaScript) and Template Transform (Jinja2) code in isolation.

Variable	Default	Description
`CODE_EXECUTION_ENDPOINT`	`http://sandbox:8194`	Sandbox service endpoint.
`CODE_EXECUTION_API_KEY`	`dify-sandbox`	API key for sandbox authentication. Must match `SANDBOX_API_KEY` in the sandbox service.
`CODE_EXECUTION_SSL_VERIFY`	`true`	Verify SSL for sandbox connections. Disable for development with self-signed certificates.
`CODE_EXECUTION_CONNECT_TIMEOUT`	`10`	Connection timeout in seconds.
`CODE_EXECUTION_READ_TIMEOUT`	`60`	Read timeout in seconds.
`CODE_EXECUTION_WRITE_TIMEOUT`	`10`	Write timeout in seconds.
`CODE_EXECUTION_POOL_MAX_CONNECTIONS`	`100`	Maximum concurrent HTTP connections to the sandbox service.
`CODE_EXECUTION_POOL_MAX_KEEPALIVE_CONNECTIONS`	`20`	Maximum idle connections kept alive in the sandbox connection pool.
`CODE_EXECUTION_POOL_KEEPALIVE_EXPIRY`	`5.0`	Seconds before idle sandbox connections are closed.

Code and Template Output Limits

The API and Worker apply these limits to the output returned by Code and Template Transform nodes; the sandbox service does not read them. Changes take effect after you restart the API and Worker, not the sandbox.

Variable	Default	Description
`CODE_MAX_NUMBER`	`9223372036854775807`	Maximum numeric value allowed in Code node output (max 64-bit signed integer).
`CODE_MIN_NUMBER`	`-9223372036854775808`	Minimum numeric value allowed in Code node output (min 64-bit signed integer).
`CODE_MAX_STRING_LENGTH`	`400000`	Maximum string length in Code node output. Prevents memory exhaustion from unbounded string generation.
`CODE_MAX_DEPTH`	`5`	Maximum nesting depth for output data structures.
`CODE_MAX_PRECISION`	`20`	Maximum decimal places for floating-point numbers in output.
`CODE_MAX_STRING_ARRAY_LENGTH`	`30`	Maximum number of elements in a string array output.
`CODE_MAX_OBJECT_ARRAY_LENGTH`	`30`	Maximum number of elements in an object array output.
`CODE_MAX_NUMBER_ARRAY_LENGTH`	`1000`	Maximum number of elements in a number array output.
`TEMPLATE_TRANSFORM_MAX_LENGTH`	`400000`	Maximum character length for Template Transform node output.

Workflow Runtime

Variable	Default	Description
`WORKFLOW_MAX_EXECUTION_STEPS`	`500`	Maximum number of node executions per workflow run, including nodes inside workflow tools that the run’s Tool nodes call. Exceeding this terminates the workflow.
`WORKFLOW_MAX_EXECUTION_TIME`	`3600`	Maximum wall-clock time in seconds per workflow run. Exceeding this terminates the workflow. An outer limit paired with `APP_MAX_EXECUTION_TIME` (both default to one hour): increase both together. If you run agents, keep them at or above the agent run deadline (`DIFY_AGENT_RUN_TIMEOUT_SECONDS`).
`WORKFLOW_CALL_MAX_DEPTH`	`5`	Maximum depth for nested workflow-calls-workflow. Prevents infinite recursion.
`MAX_VARIABLE_SIZE`	`204800`	Maximum size in bytes (200 KB) for a single workflow variable.
`WORKFLOW_FILE_UPLOAD_LIMIT`	`10`	Upper bound for the max-files setting on a single file-upload field (e.g., a User Input File List). The node panel’s max-files slider is capped at this value; raise to allow larger per-field configurations.
`WORKFLOW_NODE_EXECUTION_STORAGE`	`rdbms`	Where workflow node execution records are stored. `rdbms` stores everything in the database. `hybrid` stores new data in object storage and reads from both.
`DSL_EXPORT_ENCRYPT_DATASET_ID`	`true`	Encrypt dataset IDs when exporting DSL files. Set to `false` to export plain IDs for easier cross-environment import.

Workflow Storage Repository

These select which backend implementation handles workflow execution data. The default SQLAlchemy repositories store everything in the database. Alternative implementations (e.g., Celery, Logstore) can be used for different storage strategies.

Variable	Default	Description
`CORE_WORKFLOW_EXECUTION_REPOSITORY`	`core.repositories.sqlalchemy_workflow_execution_repository.SQLAlchemyWorkflowExecutionRepository`	Repository implementation for workflow execution records.
`CORE_WORKFLOW_NODE_EXECUTION_REPOSITORY`	`core.repositories.sqlalchemy_workflow_node_execution_repository.SQLAlchemyWorkflowNodeExecutionRepository`	Repository implementation for workflow node execution records.
`API_WORKFLOW_RUN_REPOSITORY`	`repositories.sqlalchemy_api_workflow_run_repository.DifyAPISQLAlchemyWorkflowRunRepository`	Service-layer repository for workflow run API operations.
`API_WORKFLOW_NODE_EXECUTION_REPOSITORY`	`repositories.sqlalchemy_api_workflow_node_execution_repository.DifyAPISQLAlchemyWorkflowNodeExecutionRepository`	Service-layer repository for workflow node execution API operations.
`LOOP_NODE_MAX_COUNT`	`100`	Maximum iterations for Loop nodes. Prevents infinite loops.
`MAX_PARALLEL_LIMIT`	`10`	Maximum number of parallel branches in a workflow.
`GRAPH_ENGINE_MAX_WORKERS`	`10`	Number of workers per GraphEngine instance.

Workflow Log Cleanup

Variable	Default	Description
`WORKFLOW_LOG_CLEANUP_ENABLED`	`false`	Enable automatic cleanup of workflow execution logs at 2:00 AM daily.
`WORKFLOW_LOG_RETENTION_DAYS`	`30`	Number of days to retain workflow logs before cleanup.
`WORKFLOW_LOG_CLEANUP_BATCH_SIZE`	`100`	Number of log entries processed per cleanup batch. Adjust based on system performance.
`WORKFLOW_LOG_CLEANUP_SPECIFIC_WORKFLOW_IDS`	(empty)	Comma-separated list of workflow IDs to limit cleanup to. When empty, all workflow logs are cleaned.

HTTP Request Node

These configure the HTTP Request node used in workflows to call external APIs.

Variable	Default	Description
`HTTP_REQUEST_NODE_MAX_TEXT_SIZE`	`1048576`	Maximum text response size in bytes (1 MB). Responses larger than this are truncated.
`HTTP_REQUEST_NODE_MAX_BINARY_SIZE`	`10485760`	Maximum binary response size in bytes (10 MB).
`HTTP_REQUEST_NODE_SSL_VERIFY`	`true`	Verify SSL certificates. Disable for testing with self-signed certificates.
`HTTP_REQUEST_MAX_CONNECT_TIMEOUT`	`10`	Maximum connect timeout users can set in the workflow editor (in seconds). Per-node timeouts cannot exceed this.
`HTTP_REQUEST_MAX_READ_TIMEOUT`	`600`	Maximum read timeout ceiling (in seconds).
`HTTP_REQUEST_MAX_WRITE_TIMEOUT`	`600`	Maximum write timeout ceiling (in seconds).

Webhook

Variable	Default	Description
`WEBHOOK_REQUEST_BODY_MAX_SIZE`	`10485760`	Maximum webhook payload size in bytes (10 MB). Larger payloads are rejected with a 413 error.

SSRF Protection

All outbound HTTP requests from Dify (HTTP nodes, image downloads, etc.) are routed through a proxy that blocks requests to internal/private IP ranges, preventing Server-Side Request Forgery (SSRF) attacks.

Variable	Default	Description
`SSRF_PROXY_HTTP_URL`	`http://ssrf_proxy:3128`	SSRF proxy URL for HTTP requests.
`SSRF_PROXY_HTTPS_URL`	`http://ssrf_proxy:3128`	SSRF proxy URL for HTTPS requests.
`SSRF_POOL_MAX_CONNECTIONS`	`100`	Maximum concurrent connections in the SSRF HTTP client pool.
`SSRF_POOL_MAX_KEEPALIVE_CONNECTIONS`	`20`	Maximum idle connections kept alive in the SSRF pool.
`SSRF_POOL_KEEPALIVE_EXPIRY`	`5.0`	Seconds before idle SSRF connections are closed.

Agent Configuration

Variable	Default	Description
`MAX_TOOLS_NUM`	`10`	Maximum number of tools an agent can use simultaneously.
`MAX_ITERATIONS_NUM`	`99`	Maximum reasoning iterations per agent execution. Prevents infinite agent loops.

Web Frontend Service

These variables are used by the Next.js web frontend container only, and do not affect the Python backend.

Variable	Default	Description
`TEXT_GENERATION_TIMEOUT_MS`	`60000`	Frontend timeout for streaming text generation UI. If a stream stalls for longer than this, the UI pauses rendering.
`ALLOW_INLINE_STYLES`	`false`	Allow inline `style` attributes and `<style>` blocks in user-generated Markdown content. Disabled by default for security (inline styles can be used for phishing). Enable only if you need rich styling from trusted content sources.
`ALLOW_UNSAFE_DATA_SCHEME`	`false`	Allow rendering URLs with the `data:` scheme. Disabled by default for security.
`MAX_TREE_DEPTH`	`50`	Maximum number of nodes along a single execution path. Longer paths cannot be published. Changes apply only to newly published workflows.
`MARKDOWN_FORM_FIELD_NAME_EXTRA_CHARS`	(empty)	Extra characters accepted in the `name` attributes of form fields that apps render from Markdown in chat responses. By default a field name must start with a letter and may contain letters, digits, underscores, and hyphens; fields whose names use other characters are not rendered. Set the additional characters as one string; both half-width and full-width characters work, e.g. `()！？`.
`MARKDOWN_FORM_FIELD_NAME_MAX_LENGTH`	`128`	Maximum length of the `name` attribute of form fields that apps render from Markdown in chat responses; fields with longer names are not rendered. Works alongside `MARKDOWN_FORM_FIELD_NAME_EXTRA_CHARS`, which governs the characters a name may contain. Raise it if generated field names run past the limit and the rendered form is missing those fields. Must be a positive integer.

NEXT_PUBLIC_ENABLE_FEATURE_PREVIEW

Default: true Enables the /create and /refine slash commands in the Go to Anything command palette, which generate and refine Workflow and Chatflow apps from a natural-language description. Set to false to hide them.

Agent (New)

The new Agent runs as extra services in the Docker Compose deployment: an agent backend, a sandbox, and a dedicated egress proxy for the sandbox. All start with docker compose up once you set DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN. The feature is enabled by default, and most of its settings derive from your existing Compose values, so only the variables below usually need attention.

DIFY_AGENT_SERVER_SECRET_KEY

Default: (development key pre-filled in .env.example; must be replaced for production) Root secret the agent backend uses to derive the keys for its internal tokens, including the bearer tokens that authenticate the sandboxed agent’s calls back into the backend. A publicly known development key ships as the default, so the stack starts out of the box, but anyone who knows the key can forge those tokens. Replace it before production use. The value must be unpadded base64url text that decodes to exactly 32 bytes; the agent backend refuses to start on a malformed value. Generate one with:

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

DIFY_AGENT_API_TOKEN

Default: (development token pre-filled in .env.example; must be replaced for production) Bearer token the Dify API presents when calling the agent backend’s run API. Compose passes the same value to both services, so setting it once keeps them in agreement. A publicly known development token ships as the default, so the stack starts out of the box—but anyone who can reach the agent backend and knows the token can start runs. Replace it with your own random value before production use.

DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN

Default: (empty; required with the default local runtime backend) Shared secret that authenticates the agent backend to the bundled sandbox. While it’s empty, both services exit at startup and keep restarting, so set it before you start Dify. Set it once in docker/.env, and Compose passes it to both services. A value set only in a file under docker/envs/ doesn’t take effect. Generate one with:

openssl rand -base64 32

Replaces the former DIFY_AGENT_SHELLCTL_AUTH_TOKEN, which still works as a legacy alias.

NEXT_PUBLIC_ENABLE_AGENT_V2

Default: true Shows the new Agent in the web UI: the Agents item in the main navigation and the new Agent node in the workflow node picker. Set to false to hide it and fall back to the classic Agent node. Replaces ENABLE_AGENT_V2, which still works as a fallback.

UPLOAD_SKILL_FILE_SIZE_LIMIT

Default: 50 Maximum size in MB for a skill package (.zip or .skill), whether uploaded to an agent or imported into the skill library. Larger packages are rejected with a size error. If you raise it above 100, also raise NGINX_CLIENT_MAX_BODY_SIZE to match; otherwise Nginx rejects the upload with a 413 error. This variable limits only the packed file. What’s inside the package has its own limits, set in bytes:

Variable	Default	Description
`SKILL_PACKAGE_MAX_UNCOMPRESSED_BYTES`	`209715200`	Maximum total unpacked size of a skill package in bytes (200 MB). Packages over it are rejected with `archive_too_large` (uploads to an agent) or `skill_too_large` (skill library).
`SKILL_PACKAGE_MAX_ENTRIES`	`5000`	Maximum number of entries in a skill package. Folders count, for uploads to an agent as well as library imports. Packages over it are rejected with `too_many_entries` or `too_many_files`.
`SKILL_PACKAGE_MAX_SKILL_MD_BYTES`	`1048576`	Maximum size in bytes (1 MB) of the package’s `SKILL.md`, rejected with `skill_md_too_large`. Applies to skills uploaded to an agent and to skills bundled in app packages, not to skill library imports.

Agent and App Package Limits

These limits apply to every app package (.ifpkg), not only to agents: every app type exports to this format by default. They’re checked on export and on import, whether the package is uploaded as a file or imported from a URL. A package over any of them fails the whole export or import until you raise the limit it exceeds. For package uploads above 100 MB, also raise NGINX_CLIENT_MAX_BODY_SIZE; otherwise Nginx rejects them first. Each skill bundled in a package must also fit the skill limits:

On import, a skill over UPLOAD_SKILL_FILE_SIZE_LIMIT fails the whole import. A skill over a SKILL_PACKAGE_* limit is skipped instead, and the import finishes with a warning. To bring that skill in, raise the limit it exceeds and import the package again.
On export, a skill over a SKILL_PACKAGE_* limit fails the whole export until you raise that limit.

Variable	Default	Description
`AGENT_PACKAGE_MAX_BYTES`	`536870912`	Maximum package size in bytes (512 MB), checked both packed and unpacked. The unpacked size includes the contents of bundled skills. Raise it when apps or agents with large bundled files or skills fail to export or import.
`AGENT_PACKAGE_MAX_MANIFEST_BYTES`	`5242880`	Maximum size in bytes (5 MB) of each YAML file in a package: the manifest and, in an agent package, the agent’s configuration. Bundled skills and files count toward `AGENT_PACKAGE_MAX_BYTES` instead, so raise this one only if an agent’s configuration alone outgrows 5 MB. Doesn’t apply to an app’s DSL, which keeps its fixed 10 MB limit.
`AGENT_PACKAGE_MAX_ENTRIES`	`5000`	Maximum number of items in a package: one per bundled skill, file, and icon, plus a few fixed entries. Raise it if an app or agent with thousands of bundled skills and files fails to export or import.

AGENT_BACKEND_BASE_URL

Default: http://agent_backend:5050 Address the API uses to reach the agent backend. Keep the default on Docker Compose. The remaining variables configure the bundled services or derive from your existing Compose values, and don’t normally need changes.

Variable	Default	Description
`DIFY_AGENT_REDIS_URL`	(empty; derives from `REDIS_PASSWORD`)	Redis connection for the agent backend’s run state; the Compose default points at the bundled `redis` on database 2.
`DIFY_AGENT_REDIS_PREFIX`	`dify-agent`	Key prefix for the agent backend’s Redis entries.
`DIFY_AGENT_SHUTDOWN_GRACE_SECONDS`	`30`	How long a stopping agent backend waits for in-flight runs to finish.
`DIFY_AGENT_RUN_RETENTION_SECONDS`	`7200`	How long to keep each agent run’s record and event stream in Redis, in seconds after its last write (2 hours by default). Lower it to free Redis memory sooner, at the cost of a shorter window for replaying events after a dropped connection.
`DIFY_AGENT_RUN_EVENT_STREAM_MAX_LENGTH`	`5000`	Approximate maximum number of events to keep in each agent run’s Redis stream. Lower it to reduce Redis memory use per run. New events trim the oldest ones once the limit is reached. Trimmed events cannot be replayed after a dropped connection.
`DIFY_AGENT_STREAM_TEXT_DELTA_COALESCING_ENABLED`	`true`	Batches consecutive model text deltas before writing them to Redis and streaming them. Keep enabled to reduce Redis writes and event counts. Set to `false` to stream each delta separately. Tool calls and other non-text events remain unchanged and in order.
`DIFY_AGENT_STREAM_TEXT_DELTA_FLUSH_INTERVAL_MS`	`100`	Target interval in milliseconds for publishing batched text deltas. Lower it for more frequent text updates; raise it for fewer, larger batches. This is not a strict timing limit. Batches can be published sooner when they reach `DIFY_AGENT_STREAM_TEXT_DELTA_MAX_CHARS`. Minimum: 1. To disable batching, set `DIFY_AGENT_STREAM_TEXT_DELTA_COALESCING_ENABLED` to `false`.
`DIFY_AGENT_STREAM_TEXT_DELTA_MAX_CHARS`	`4096`	Character threshold for publishing a text-delta batch before the flush interval elapses. Lower it to publish smaller batches sooner. A batch can exceed this threshold because deltas are added whole. Minimum: 1.
`DIFY_AGENT_RUN_TIMEOUT_SECONDS`	`3600`	Wall-clock deadline for one agent run’s model and tool work. A run that exceeds it fails with `agent_run_limit_exceeded`. Replaces the former `AGENT_BACKEND_RUN_TIMEOUT_SECONDS`. The API-side `APP_MAX_EXECUTION_TIME` and `WORKFLOW_MAX_EXECUTION_TIME` (default `3600`) cap runs earlier if set below this. On the `e2b` backend, the sandbox’s `DIFY_AGENT_E2B_ACTIVE_TIMEOUT_SECONDS` (ceiling 3600) still applies, so E2B runs stay capped at one hour. On the `local` backend, values above an hour take effect: to allow longer runs, raise this and both API-side limits.
`AGENT_BACKEND_STREAM_READ_TIMEOUT_SECONDS`	`30`	Read timeout for one SSE connection to the agent backend.
`AGENT_BACKEND_STREAM_MAX_RECONNECTS`	`3`	How many times the API reconnects a dropped agent-backend stream before failing the run.
`DIFY_AGENT_PLUGIN_DAEMON_URL`	(empty; derives from `PLUGIN_DAEMON_URL`)	Plugin daemon address the agent backend calls tools through.
`DIFY_AGENT_PLUGIN_DAEMON_API_KEY`	(empty; derives from `PLUGIN_DAEMON_KEY`)	Credential for the plugin daemon.
`DIFY_AGENT_OUTBOUND_HTTP_CONNECT_TIMEOUT`	`10`	Connect timeout in seconds for the agent service’s outbound HTTP calls, such as tool and plugin traffic.
`DIFY_AGENT_OUTBOUND_HTTP_READ_TIMEOUT`	`600`	Read timeout in seconds; generous by default so slow tool responses and large downloads can finish.
`DIFY_AGENT_OUTBOUND_HTTP_WRITE_TIMEOUT`	`30`	Write timeout in seconds for outbound requests.
`DIFY_AGENT_OUTBOUND_HTTP_POOL_TIMEOUT`	`10`	How long in seconds a request waits for a free connection from the pool.
`DIFY_AGENT_OUTBOUND_HTTP_MAX_CONNECTIONS`	`100`	Connection pool size for the agent service’s outbound HTTP.
`DIFY_AGENT_OUTBOUND_HTTP_MAX_KEEPALIVE_CONNECTIONS`	`20`	How many idle connections stay pooled for reuse.
`DIFY_AGENT_OUTBOUND_HTTP_KEEPALIVE_EXPIRY`	`30`	Seconds an idle pooled connection is kept before it closes.
`DIFY_AGENT_INNER_API_URL`	(empty; derives from `PLUGIN_DIFY_INNER_API_URL`)	Dify API address for the agent backend’s internal calls.
`DIFY_AGENT_INNER_API_KEY`	(empty; derives from `PLUGIN_DIFY_INNER_API_KEY`)	Must match the API service’s `INNER_API_KEY_FOR_PLUGIN`, not `INNER_API_KEY`.
`DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT`	`http://local_sandbox:5004`	Address of the bundled sandbox service. Replaces the former `DIFY_AGENT_SHELLCTL_ENTRYPOINT`, which still works as a legacy alias.
`EXPOSE_LOCAL_SANDBOX_PORT`	`5004`	Host port at which the middleware stack for source-code deployments publishes the agent sandbox, so an agent backend run from source reaches it at `http://localhost:5004`. Set it in that stack’s `middleware.env`; if you change it, point `DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT` in the agent backend’s `.env` at the new port. Middleware stack only: the full Compose stack keeps the sandbox on an internal network.
`DIFY_AGENT_STUB_API_BASE_URL`	`http://agent_backend:5050/agent-stub`	Callback address the sandboxed agent uses to reach the agent backend. Keep the default with the bundled `local` sandbox. On the `openshell` backend, sandboxes can’t resolve Compose service names. Set this in `docker/.env` to an address they can reach that routes to the agent backend’s `/agent-stub` path, and publish or proxy the agent backend’s port 5050.
`DIFY_AGENT_SANDBOX_FILES_BASE_URL`	`http://api:5001`	Dify API address the sandboxed agent uses for file transfers. Keep the default on Docker Compose. A remote sandbox backend needs your publicly reachable Dify address here.
`AGENT_BACKEND_BINDING_FILE_DOWNLOAD_TIMEOUT_SECONDS`	`240`	How long the API waits when fetching a file from an agent’s sandbox before failing the transfer. Keep it above the agent-side `DIFY_AGENT_BINDING_FILE_DOWNLOAD_COMMAND_TIMEOUT_SECONDS`.
`AGENT_BACKEND_HOME_SNAPSHOT_TIMEOUT_SECONDS`	`45`	How long the API waits on agent backend calls that transfer a home snapshot: capturing or deleting one, and starting a run that restores one. If applying a build or starting runs fails for agents with large home environments, increase this.
`DIFY_AGENT_BINDING_FILE_DOWNLOAD_COMMAND_TIMEOUT_SECONDS`	`210`	How long the sandbox command serving that file may run. The default stays below the API’s timeout so the agent’s own error surfaces first.
`DIFY_AGENT_STUB_UPLOAD_FILE_SIZE_LIMIT`	`50`	Maximum size in MiB for one file the sandboxed agent uploads back to Dify, such as the files it generates for a reply.
`SHELLCTL_ENABLE_PATH_ISOLATION`	`true`	Kernel-enforced (Landlock) limits on which paths the sandbox can read and write. Requires Linux 5.13 or later with Landlock enabled. Since 1.18.0, if the sandbox can’t apply Landlock, it refuses to run any command. Set in `docker/envs/core-services/local-sandbox.env`; `.env` values don’t reach the sandbox container.
`DIFY_AGENT_SHELL_REDACT_PATTERNS`	(empty)	JSON array of regex patterns masked out of shell output before the agent reads it, for secrets like API keys. The agent’s internal bearer token is always masked.
`LOGFIRE_CONSOLE`	`false`	Set to `true` while debugging to have the agent backend print its own request, outbound HTTP, and Redis spans to its container log. Unrelated to trajectory export, which never prints there. Since 1.18.0, agent-run spans no longer appear in this log. To follow agent runs, use trajectory export.

DIFY_AGENT_RUNTIME_BACKEND

Default: local Selects where agent sandboxes run:

local: the bundled sandbox container.
e2b: an E2B cloud VM for each agent’s sandbox, for stronger isolation than the bundled container provides.
openshell: an NVIDIA OpenShell gateway you operate, so sandboxes run on your own infrastructure.

Set this and the two callback addresses, DIFY_AGENT_STUB_API_BASE_URL and DIFY_AGENT_SANDBOX_FILES_BASE_URL, in docker/.env. Compose passes these three to the agent backend from there, so values in envs/core-services/dify-agent.env have no effect. Each remote backend reads its own group of variables:

E2B

The docker/docker-compose.e2b.yaml overlay adjusts the Compose stack for this backend.

Variable	Default	Description
`DIFY_AGENT_E2B_API_KEY`	(empty; falls back to `E2B_API_KEY`/`E2B_API_TOKEN`)	E2B account key; required for the `e2b` backend.
`DIFY_AGENT_E2B_TEMPLATE`	`difys-default-team/dify-agent-local-sandbox`	E2B sandbox template agents run in.
`EXPOSE_AGENT_BACKEND_PORT`	`15050`	Host port at which the `docker-compose.e2b.yaml` overlay publishes the agent backend (container port `5050`). Change it when 15050 is already taken on the host.
`DIFY_AGENT_E2B_ACTIVE_TIMEOUT_SECONDS`	`3600`	How long one E2B sandbox stays active, spanning a complete agent run. 3600 is also the hard ceiling: higher values are rejected. Keep it at or above `DIFY_AGENT_RUN_TIMEOUT_SECONDS`. If the sandbox’s active time is shorter than the run’s allowed time, runs lose their sandbox while still within their limit.
`DIFY_AGENT_E2B_SHELLCTL_PORT`	`5004`	Port the sandbox control service listens on inside the E2B VM.

OpenShell

Before switching to openshell, have these in place:

An OpenShell gateway, version 0.0.106 or later, reachable from the agent_backend container.
Gateway credentials: a bearer token, an mTLS client certificate pair, or both. Compose ships no certificate mount, so mount the files into agent_backend yourself, read-only and readable by UID 1001.
A runtime image that the gateway can start sandboxes from.
A shared volume for the persistent files agents keep across conversations, created outside Compose so that docker compose down -v can’t delete it.
A network path from the sandboxes back to Dify:
- Callback addresses the sandboxes can reach.
- A route to the agent backend’s /agent-stub path. The base Compose file doesn’t publish the agent backend’s port 5050, and that port also serves the API that starts agent runs, so expose only /agent-stub, for example through a reverse proxy.

To switch to OpenShell:

See the OpenShell setup guide to set up the gateway and everything above: building the runtime image, initializing the volume, mounting certificates, Kubernetes setup, and a smoke test.
In docker/.env, set DIFY_AGENT_RUNTIME_BACKEND to openshell and fill in the variables below.
Recreate the agent backend with docker compose up -d. It refuses to start if a required value is missing or malformed.
Run an agent to confirm the setup. The agent backend first contacts the gateway when an agent runs, or when you click Apply in an Agent’s build chat, so a wrong endpoint, credential, or image shows up only then, as a failed run or a failed apply.

Sandboxes keep running on the gateway after a run ends, until Dify removes them, so plan gateway capacity for idle sandboxes as well as active ones.The bundled sandbox’s egress proxy doesn’t cover OpenShell sandboxes. To restrict their network access, set DIFY_AGENT_OPENSHELL_EGRESS_ALLOW.

Variable	Default	Description
`DIFY_AGENT_OPENSHELL_GATEWAY_ENDPOINT`	(empty)	Required for the `openshell` backend; the agent backend won’t start without it. Address of the OpenShell gateway as `host:port`, with no scheme. It must be reachable from inside the `agent_backend` container. For a gateway on the Docker host, use `host.docker.internal:<port>` rather than `localhost`, and on Linux also map that name to the host with `extra_hosts`. Example: `gateway.example.com:17670`
`DIFY_AGENT_OPENSHELL_BEARER_TOKEN`	(empty)	OIDC bearer token the agent backend presents to the gateway. Use it, the mTLS client certificate pair, or both, to match how your gateway authenticates. Read once at startup: after rotating it, recreate the agent backend.
`DIFY_AGENT_OPENSHELL_TLS_CA_PATH`	(empty)	Path inside the `agent_backend` container to the CA certificate that signed the gateway’s certificate. Ignored when `DIFY_AGENT_OPENSHELL_INSECURE` is `true`.
`DIFY_AGENT_OPENSHELL_TLS_CLIENT_CERT_PATH`	(empty)	Path inside the `agent_backend` container to the mTLS client certificate. Set it together with `DIFY_AGENT_OPENSHELL_TLS_CLIENT_KEY_PATH` or leave both empty; with only one set, the agent backend won’t start.
`DIFY_AGENT_OPENSHELL_TLS_CLIENT_KEY_PATH`	(empty)	Path inside the `agent_backend` container to the mTLS client private key. Set it together with `DIFY_AGENT_OPENSHELL_TLS_CLIENT_CERT_PATH` or leave both empty; with only one set, the agent backend won’t start.
`DIFY_AGENT_OPENSHELL_INSECURE`	`false`	Connects to the gateway over plaintext gRPC instead of TLS, without using the TLS paths. A bearer token, if set, is still sent over that connection. Only for local development against a plaintext gateway.
`DIFY_AGENT_OPENSHELL_WORKSPACE`	`default`	OpenShell workspace in which the agent backend creates and manages sandboxes. This is a namespace on the gateway, not a Dify workspace.
`DIFY_AGENT_OPENSHELL_SANDBOX_IMAGE`	`docker.io/library/dify-agent-runtime:latest`	Container image the gateway starts for each sandbox. The default is the tag that the build command in the OpenShell setup guide produces. The image must be available to the gateway’s compute driver, not only to the Docker daemon running Dify: load it into the gateway’s Docker daemon, or push it to a registry the gateway pulls from and use that reference. Set it explicitly. If no env file sets it, the agent backend falls back to `langgenius/dify-agent-local-sandbox:latest`, which may be an older image that can’t start under OpenShell.
`DIFY_AGENT_OPENSHELL_DRIVER_CONFIG`	(empty)	Required for the `openshell` backend. JSON the gateway’s compute driver applies to every sandbox; it must mount the shared volume at `DIFY_AGENT_OPENSHELL_SHARED_MOUNT_PATH`. Its shape depends on the driver. Invalid JSON or an empty object stops the agent backend from starting. Dify doesn’t check the mounts themselves, so the agent backend starts even if the volume is mounted at another path. Double-check the target. Example for the Docker driver: `{"docker":{"mounts":[{"type":"volume","source":"dify-agent-shared","target":"/mnt/dify-agent-shared","read_only":false}]}}`
`DIFY_AGENT_OPENSHELL_SHARED_MOUNT_PATH`	`/mnt/dify-agent-shared`	Where the shared volume is mounted inside each sandbox; must match the mount target in `DIFY_AGENT_OPENSHELL_DRIVER_CONFIG`. Agents’ persistent files are saved here each time you click Apply in an Agent’s build chat. Must be an absolute path, or the agent backend won’t start.
`DIFY_AGENT_OPENSHELL_SHELLCTL_AUTH_TOKEN`	(empty)	Required for the `openshell` backend; the agent backend won’t start without it. Shared secret that authenticates the agent backend to the command service it starts inside each sandbox. Set any random string. Separate from `DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN`, which secures the bundled sandbox.
`DIFY_AGENT_OPENSHELL_EGRESS_ALLOW`	(empty)	Comma-separated `host:port` endpoints that sandboxes may connect to, with no scheme or path. Empty sends no network policy, so egress follows the gateway’s default. When set, sandboxes reach only the listed endpoints, so package installs and web access stop working unless their hosts are listed. Include the hosts of `DIFY_AGENT_STUB_API_BASE_URL` and `DIFY_AGENT_SANDBOX_FILES_BASE_URL`, or agent runs can’t call back into Dify. A malformed entry stops the agent backend from starting. Example: `agent.example.com:443,dify.example.com:443`
`DIFY_AGENT_OPENSHELL_SHELLCTL_PORT`	`5004`	Loopback port the command service listens on inside each sandbox. The agent backend reaches it through the gateway, so no port needs opening. Change it only if your runtime image already uses 5004.
`DIFY_AGENT_OPENSHELL_READY_TIMEOUT_SECONDS`	`300`	How long in seconds to wait for a new or restarted sandbox to become ready. If agent runs fail while sandboxes are still starting on a busy gateway, raise it.
`DIFY_AGENT_OPENSHELL_EXEC_TIMEOUT_SECONDS`	`120`	Time limit in seconds for each setup command the agent backend runs in a sandbox through the gateway, such as copying in an agent’s persistent files or starting the command service. Doesn’t limit the commands the agent itself runs. If new sessions of agents with large persistent files fail to start, raise it.

Agent Trajectory Export

To see what your agents did in a tracing backend you already run, turn on trajectory export. The agent backend then sends a trace of each agent run, with its model requests and tool calls, to an OpenTelemetry collector over OTLP/HTTP. One collector receives the runs of every workspace on the deployment. Every span carries the IDs of its workspace, app, agent, end user, conversation, workflow run, and node, so you can narrow traces to one app or one conversation by attributes such as dify.app_id or dify.conversation.id. These IDs are exported even with content export off. Trajectory export is separate from LLMOps Trace Delivery, which app builders set up per app with providers such as Langfuse, and from the OpenTelemetry instrumentation of the API and Worker. Their settings don’t affect it. To turn it on:

In docker/.env, set DIFY_AGENT_TRAJECTORY_ENABLED to true and DIFY_AGENT_TRAJECTORY_OTLP_TRACES_ENDPOINT to your collector’s traces URL. Put any credentials in DIFY_AGENT_TRAJECTORY_OTLP_HEADERS. These variables have no effect in shared.env, which the agent backend doesn’t read.
Recreate the agent backend with docker compose up -d. If a value is invalid, the agent backend won’t start, and agent runs fail until you fix it.
Run an agent on a task that calls a tool, then look in your tracing backend for a tool-call span under the service name dify-agent-trajectory.

With DIFY_AGENT_TRAJECTORY_INCLUDE_CONTENT set to true, the collector receives prompts, system instructions, model replies, and tool arguments and results from every workspace. Restrict access to the collector as you would to the conversations themselves.

Variable	Default	Description
`DIFY_AGENT_TRAJECTORY_ENABLED`	`false`	Turns trajectory export on. Requires `DIFY_AGENT_TRAJECTORY_OTLP_TRACES_ENDPOINT`; with `true` and no endpoint, the agent backend won’t start.
`DIFY_AGENT_TRAJECTORY_OTLP_TRACES_ENDPOINT`	(empty)	Full URL of your collector’s OTLP/HTTP traces endpoint, including the path; it’s used as is. gRPC endpoints aren’t supported. Must use `http` or `https`, with no credentials and no `#` fragment, or the agent backend won’t start. Put credentials in `DIFY_AGENT_TRAJECTORY_OTLP_HEADERS` instead. Example: `https://collector.example.com/v1/traces`
`DIFY_AGENT_TRAJECTORY_OTLP_HEADERS`	`{}`	Headers sent with every export, as a JSON object, such as `{"Authorization":"Bearer <token>"}`. Use it for collector credentials. A value that isn’t JSON, such as `Authorization=Bearer <token>`, stops the agent backend from starting.
`DIFY_AGENT_TRAJECTORY_SERVICE_NAME`	`dify-agent-trajectory`	The `service.name` set on every exported span, to filter on in your tracing backend. Can’t be empty.
`DIFY_AGENT_TRAJECTORY_INCLUDE_CONTENT`	`false`	Set to `true` to add conversation content to the spans: prompts, system instructions, model replies, and tool arguments and results. Binary content is never exported. Without it, traces show each run’s steps and timing but not what was said. Turn it on when you need to see why an agent answered or acted as it did, and only if your collector may hold every workspace’s conversations.
`DIFY_AGENT_TRAJECTORY_TRACE_CONTEXT_MODE`	`isolated`	How agent spans relate to other traces. `isolated` starts a new trace for each agent run. `shared` makes agent spans join the current trace and follow its sampling decision. Keep `isolated` unless the agent backend’s own telemetry also goes to this tracing backend, which happens only if you’ve set `LOGFIRE_TOKEN` or the standard `OTEL_EXPORTER_OTLP_*` variables for it. Otherwise `shared` can leave traces with missing root spans.
`DIFY_AGENT_TRAJECTORY_MAX_QUEUE_SIZE`	`2048`	Maximum number of spans waiting to be exported. If spans go missing under heavy load, raise it.
`DIFY_AGENT_TRAJECTORY_MAX_EXPORT_BATCH_SIZE`	`512`	Maximum number of spans per export request. Must not exceed `DIFY_AGENT_TRAJECTORY_MAX_QUEUE_SIZE`, or the agent backend won’t start.
`DIFY_AGENT_TRAJECTORY_SCHEDULE_DELAY_MS`	`5000`	Delay in milliseconds between batch exports.
`DIFY_AGENT_TRAJECTORY_EXPORT_TIMEOUT_MS`	`5000`	Time limit in milliseconds for exporting one batch. Doesn’t change the timeout of each HTTP request to the collector, which is fixed at 5 seconds.

Database Service

These configure the database and Redis containers directly in Docker Compose. Rows marked middleware stack apply only to the stack that source-code deployments start, and are set in its middleware.env; the full Compose stack keeps those services on an internal network.

Variable	Default	Description
`PGDATA`	`/var/lib/postgresql/data/pgdata`	PostgreSQL data directory inside the container.
`MYSQL_HOST_VOLUME`	`./volumes/mysql/data`	Host path mounted as MySQL data volume.
`PGDATA_HOST_VOLUME`	`./volumes/db/data`	Host path mounted as the PostgreSQL data volume. Middleware stack; the full Compose stack mounts `./volumes/db/data` directly.
`REDIS_HOST_VOLUME`	`./volumes/redis/data`	Host path mounted as the Redis data volume. Middleware stack.
`EXPOSE_POSTGRES_PORT`	`5432`	Host port at which the middleware stack publishes PostgreSQL.
`EXPOSE_MYSQL_PORT`	`3306`	Host port at which the middleware stack publishes MySQL.
`EXPOSE_REDIS_PORT`	`6379`	Host port at which the middleware stack publishes Redis.

Sandbox Service

The sandbox is an isolated service for executing code nodes (Python, JavaScript, Jinja2). Network access can be disabled for security.

Variable	Default	Description
`SANDBOX_API_KEY`	`dify-sandbox`	API key for sandbox authentication. Must match `CODE_EXECUTION_API_KEY` in the API service.
`SANDBOX_GIN_MODE`	`release`	Sandbox service mode: `release` or `debug`.
`SANDBOX_WORKER_TIMEOUT`	`15`	Maximum execution time in seconds for a single code run.
`SANDBOX_ENABLE_NETWORK`	`true`	Allow code to make outbound HTTP requests. Disable to prevent code nodes from accessing external services.
`SANDBOX_HTTP_PROXY`	`http://ssrf_proxy:3128`	HTTP proxy for SSRF protection when network is enabled.
`SANDBOX_HTTPS_PROXY`	`http://ssrf_proxy:3128`	HTTPS proxy for SSRF protection.
`SANDBOX_PORT`	`8194`	Sandbox service port.

Nginx Reverse Proxy

Variable	Default	Description
`NGINX_SERVER_NAME`	`_`	Nginx server name. `_` matches any hostname.
`NGINX_HTTPS_ENABLED`	`false`	Enable HTTPS. When `true`, place your SSL certificate and key in `./nginx/ssl/`.
`NGINX_PORT`	`80`	HTTP port.
`NGINX_SSL_PORT`	`443`	HTTPS port (only used when `NGINX_HTTPS_ENABLED=true`).
`NGINX_SSL_CERT_FILENAME`	`dify.crt`	SSL certificate filename in `./nginx/ssl/`.
`NGINX_SSL_CERT_KEY_FILENAME`	`dify.key`	SSL private key filename in `./nginx/ssl/`.
`NGINX_SSL_PROTOCOLS`	`TLSv1.2 TLSv1.3`	Allowed TLS protocol versions.
`NGINX_WORKER_PROCESSES`	`auto`	Number of Nginx worker processes. `auto` matches CPU core count.
`NGINX_CLIENT_MAX_BODY_SIZE`	`100M`	Maximum request body size. Affects file upload limits at the proxy level.
`NGINX_KEEPALIVE_TIMEOUT`	`65`	Keepalive timeout in seconds.
`NGINX_PROXY_READ_TIMEOUT`	`3600s`	Proxy read timeout. Set high (1 hour) to support long-running SSE streams.
`NGINX_PROXY_SEND_TIMEOUT`	`3600s`	Proxy send timeout.
`NGINX_ENABLE_CERTBOT_CHALLENGE`	`false`	Accept Let’s Encrypt ACME challenge requests at `/.well-known/acme-challenge/`. Enable for automated certificate renewal.
`NGINX_SOCKET_IO_UPSTREAM`	`api_websocket:5001`	Upstream that Nginx forwards `/socket.io/` traffic to. Defaults to the dedicated `api_websocket` container started by the `collaboration` profile. Change only if you run the WebSocket service outside Docker Compose.

After enabling HTTPS, also update the URL variables in Common Variables (e.g., CONSOLE_API_URL, CONSOLE_WEB_URL) to use https://.

Certbot Configuration

Variable	Default	Description
`CERTBOT_EMAIL`	(empty)	Email address required by Let’s Encrypt for certificate notifications.
`CERTBOT_DOMAIN`	(empty)	Domain name for the SSL certificate.
`CERTBOT_OPTIONS`	(empty)	Additional certbot CLI options (e.g., `--force-renewal`, `--dry-run`).

RESPECT_XFORWARD_HEADERS_ENABLED

Default: true on Docker Compose; false on source deployments When on, Dify takes each visitor’s IP address from the X-Forwarded-For header sent by the proxy directly in front of the API. On Docker Compose behind Cloudflare, a load balancer, or another proxy, leave this on and configure the bundled Nginx to trust your proxy. Until you do, every visitor appears with the proxy’s address and shares its limits, such as the one on sign-in emails.

With this on, anything that connects to the API directly can choose the address Dify sees. A forged address can get around per-IP rate limits and ends up in records such as an account’s last sign-in IP.Docker Compose doesn’t publish the API port, but containers on the same Docker networks, such as the code sandbox, can still connect directly. Marking a Docker network internal doesn’t stop them.Allow direct connections only from callers you trust. If those containers run code you don’t trust, isolate them with network or firewall rules. Any API calls they still need to make should go through a gateway that rewrites X-Forwarded-For.If you have published the API port, close it rather than turning this off: with this off, every visitor appears with Nginx’s address.

On source deployments, turn it on when the API runs behind a single proxy that sets X-Forwarded-For and is the only way to reach it.

SSRF Proxy

These configure the Squid-based SSRF proxy container that blocks requests to internal/private networks.

Variable	Default	Description
`SSRF_HTTP_PORT`	`3128`	Proxy listening port.
`EXPOSE_SSRF_PROXY_PORT`	`3128`	Host port at which the middleware stack (source-code deployments) publishes the proxy’s `SSRF_HTTP_PORT`. Set it in that stack’s `middleware.env`; the full Compose stack keeps the proxy on an internal network.
`EXPOSE_SANDBOX_PORT`	`8194`	Host port at which the middleware stack publishes the proxy’s sandbox port (`SSRF_SANDBOX_PROXY_PORT`), so code run from source reaches the sandbox through the proxy.
`SSRF_COREDUMP_DIR`	`/var/spool/squid`	Core dump directory.
`SSRF_SANDBOX_PROXY_PORT`	`8194`	Port the SSRF proxy listens on to reverse-proxy egress to the sandbox service.
`SSRF_SANDBOX_PROXY_HOST`	`sandbox`	Hostname of the sandbox service the SSRF proxy forwards to.
`SSRF_PROXY_ALLOW_PRIVATE_IPS`	(empty)	Comma-separated private IP addresses or CIDR ranges the SSRF proxy lets through for HTTP Request nodes, tools, and Sync from website with a self-hosted Firecrawl or WaterCrawl server. For a hostname, use `SSRF_PROXY_ALLOW_PRIVATE_DOMAINS`. Every address in an allowed range becomes reachable from any HTTP Request node or tool as well, so list only the hosts Dify must reach, not a whole private network. Set it in `docker/.env`. A value in `envs/infrastructure/ssrf-proxy.env` has no effect. Example: `192.168.0.189,10.0.20.0/29`
`SSRF_PROXY_ALLOW_PRIVATE_DOMAINS`	(empty)	Comma-separated hostnames the SSRF proxy lets through even when they resolve to a private address. A name matches only that exact host; a leading dot (`.corp.internal`) also covers its subdomains. Keep it as narrow as `SSRF_PROXY_ALLOW_PRIVATE_IPS` and set it the same way. `docker/.env.example` has no line for it, so add one. Example: `firecrawl.internal`
`SSRF_DEFAULT_TIME_OUT`	`5`	Default overall timeout in seconds for proxied requests.
`SSRF_DEFAULT_CONNECT_TIME_OUT`	`5`	Default connection timeout in seconds.
`SSRF_DEFAULT_READ_TIME_OUT`	`5`	Default read timeout in seconds.
`SSRF_DEFAULT_WRITE_TIME_OUT`	`5`	Default write timeout in seconds.

Docker Compose

These variables stay in docker/.env because Docker Compose uses them to select profiles and expose ports before containers start.

Variable	Default	Description
`COMPOSE_PROFILES`	`${VECTOR_STORE:-weaviate},${DB_TYPE:-postgresql},collaboration`	Selects which service containers to start. The default includes the matching vector store and database (so `DB_TYPE=mysql` starts MySQL instead of PostgreSQL), plus the `collaboration` profile that starts the dedicated `api_websocket` container. Remove `collaboration` to skip the separate WebSocket service.
`EXPOSE_NGINX_PORT`	`80`	Host port mapped to Nginx HTTP.
`EXPOSE_NGINX_SSL_PORT`	`443`	Host port mapped to Nginx HTTPS.

ModelProvider & Tool Position Configuration

Customize which tools and model providers are available in the app interface and their display order. Use comma-separated values with no spaces between items.

Variable	Default	Description
`POSITION_TOOL_PINS`	(empty)	Pin specific tools to the top of the list. Example: `bing,google`.
`POSITION_TOOL_INCLUDES`	(empty)	Only show listed tools. If unset, all tools are available.
`POSITION_TOOL_EXCLUDES`	(empty)	Hide specific tools (pinned tools are not affected).
`POSITION_PROVIDER_PINS`	(empty)	Pin specific model providers to the top. Example: `openai,anthropic`.
`POSITION_PROVIDER_INCLUDES`	(empty)	Only show listed providers. If unset, all providers are available.
`POSITION_PROVIDER_EXCLUDES`	(empty)	Hide specific providers (pinned providers are not affected).

Plugin Daemon Configuration

The plugin daemon is a separate service that manages plugin lifecycle (installation, execution, upgrades). The API communicates with it via HTTP.

Variable	Default	Description
`PLUGIN_DAEMON_URL`	`http://plugin_daemon:5002`	Plugin daemon service URL.
`PLUGIN_DAEMON_KEY`	(auto-generated)	Authentication key for the plugin daemon.
`PLUGIN_DAEMON_PORT`	`5002`	Plugin daemon listening port.
`DB_SSL_MODE`	`disable`	PostgreSQL `sslmode` for the plugin daemon’s database connection. Set `require` when the database enforces TLS. There is no `.env.example` entry: set it in `docker/.env` for the full Compose stack, or in `middleware.env` for the middleware stack.
`PLUGIN_DAEMON_TIMEOUT`	`600.0`	Timeout in seconds for all plugin daemon requests (installation, execution, listing).
`PLUGIN_MAX_PACKAGE_SIZE`	`52428800`	Maximum plugin package size in bytes (50 MB). Validated during marketplace downloads.
`PLUGIN_MAX_FILE_SIZE`	`52428800`	Maximum size in bytes (50 MB) for a single file a plugin returns to Dify, such as a tool plugin outputting a generated image or document. A larger file fails the invocation with a “file is too large” error.
`PLUGIN_MODEL_SCHEMA_CACHE_TTL`	`3600`	How long to cache plugin model schemas in seconds. Reduces repeated lookups.
`PLUGIN_MODEL_PROVIDERS_CACHE_ENABLED`	`true`	Whether each tenant’s plugin model provider list is cached in Redis at all. Disable when plugins are installed by an external system that can’t invalidate this deployment’s cache when a tenant’s plugins change.
`PLUGIN_MODEL_PROVIDERS_CACHE_TTL`	`86400`	How long to cache each tenant’s plugin model provider list in Redis, in seconds (24 hours). Dify invalidates this cache when a tenant installs, uninstalls, or upgrades a plugin.
`PLUGIN_DIFY_INNER_API_KEY`	(auto-generated)	API key the plugin daemon uses to call back to the Dify API. Must match `DIFY_INNER_API_KEY` in the plugin daemon service config.
`INNER_API_KEY_FOR_PLUGIN`	(pre-filled in the env example; replace for production)	The API-service side of the same secret, under its direct name from `docker/envs/core-services/`; in the Compose stack `PLUGIN_DIFY_INNER_API_KEY` feeds both sides. The API checks it on every plugin callback (model invocation, tool calls, file transfer). On mismatch those calls fail while plugin install keeps working. Replace the shipped default: it is public in the Dify repo and is the only auth on the plugin callback API.
`PLUGIN_DIFY_INNER_API_URL`	`http://api:5001`	Internal API URL the plugin daemon calls back to.
`PLUGIN_DEBUGGING_HOST`	`0.0.0.0`	Host for plugin remote debugging connections.
`PLUGIN_DEBUGGING_PORT`	`5003`	Port for plugin remote debugging connections.
`PLUGIN_REMOTE_INSTALL_HOST`	`localhost`	Address the console shows plugin developers for remote plugin debugging. Display-only: the daemon’s listener is unaffected. Set it (via `EXPOSE_PLUGIN_DEBUGGING_HOST` in the Compose stack) to a host developers can reach; `localhost` only works when developing on the Docker host itself.
`PLUGIN_REMOTE_INSTALL_PORT`	`5003`	Port half of the advertised debugging address. Must match the published daemon debugging port (`EXPOSE_PLUGIN_DEBUGGING_PORT`); the Compose stack keeps the two in sync from that one knob.
`MARKETPLACE_ENABLED`	`true`	Controls whether Dify Marketplace is available for plugins. When disabled, the console hides the entry points for Marketplace plugin browsing and installation, the API rejects Marketplace plugin installs and upgrades, and the periodic upgrade check (`ENABLE_CHECK_UPGRADABLE_PLUGIN_TASK`) stops. Template import itself is unaffected. However, if an imported template requires Marketplace plugins that are not already installed, those dependencies cannot be installed while Marketplace is disabled. Already-installed plugins keep working, and installing from GitHub or a local package stays available when permitted by the installation policy.
`MARKETPLACE_API_URL`	`https://marketplace.dify.ai`	Marketplace API endpoint for browsing and downloading plugins and templates, and checking plugin upgrades. The Dify API service, background workers, web service, and users’ browsers use this URL, so it must be reachable from each environment.
`MARKETPLACE_URL`	(empty; the Compose stack falls back to `https://marketplace.dify.ai`)	Base URL for Marketplace links, including plugin detail pages and the Integrations page’s Marketplace entry. Dify also uses it to generate Creator Center guide links. Distinct from `MARKETPLACE_API_URL`, the endpoint for Marketplace data and packages.
`FORCE_VERIFYING_SIGNATURE`	`true`	Require valid signatures before installing plugins. Prevents installing tampered or unsigned packages.
`PLUGIN_MAX_EXECUTION_TIMEOUT`	`600`	Plugin execution timeout in seconds (plugin daemon side). Should match `PLUGIN_DAEMON_TIMEOUT` on the API side.
`PIP_MIRROR_URL`	(empty)	Custom PyPI mirror URL used by the plugin daemon when installing plugin dependencies. Useful for faster installs or air-gapped environments.

Creator Center Configuration

Creator Center (creators.dify.ai) is the submission portal where users upload Dify apps as templates. Submitted templates are reviewed and, once approved, listed on Dify Marketplace. The Dify console opens Creator Center pages in a new browser tab. In Studio, the Publish to Marketplace action exports the app as an app package (.ifpkg) and uploads it to Creator Center, where the user completes the submission. See Publish Apps to Marketplace for the user-facing flow.

Variable	Default	Description
`CREATORS_PLATFORM_FEATURES_ENABLED`	`true`	Controls whether the Publish to Marketplace action appears in the app’s Publish panel. Set to `false` to hide the action; the underlying console API also returns 403. Useful on deployments where users shouldn’t have a one-click path to submit templates externally.
`CREATORS_PLATFORM_API_URL`	`https://creators.dify.ai`	Base URL of the Creator Center service. The API service and users’ browsers both use this URL, so it must be reachable from both.
`CREATORS_PLATFORM_OAUTH_CLIENT_ID`	(empty)	OAuth client ID for passwordless SSO to Creator Center. Leave it empty on self-hosted deployments. Publishing still works, but users who are not already signed in must log in to Creator Center manually. An ID not registered with the deployment’s OAuth server makes Publish to Marketplace fail.

OTLP / OpenTelemetry Configuration

OpenTelemetry provides distributed tracing and metrics collection. When enabled, Dify instruments Flask and exports telemetry data to an OTLP collector.

Variable	Default	Description
`ENABLE_OTEL`	`false`	Master switch for OpenTelemetry instrumentation.
`OTLP_TRACE_ENDPOINT`	(empty)	Dedicated trace endpoint URL. If unset, falls back to `{OTLP_BASE_ENDPOINT}/v1/traces`.
`OTLP_METRIC_ENDPOINT`	(empty)	Dedicated metric endpoint URL. If unset, falls back to `{OTLP_BASE_ENDPOINT}/v1/metrics`.
`OTLP_BASE_ENDPOINT`	`http://localhost:4318`	Base OTLP collector URL. Used as fallback when specific trace/metric endpoints are not set.
`OTLP_API_KEY`	(empty)	API key for OTLP authentication. Sent as `Authorization: Bearer` header.
`OTEL_EXPORTER_TYPE`	`otlp`	Exporter type. `otlp` exports to a collector; other values use a console exporter (for debugging).
`OTEL_EXPORTER_OTLP_PROTOCOL`	(empty)	Protocol for OTLP export. `grpc` uses gRPC exporters; anything else uses HTTP.
`OTEL_SAMPLING_RATE`	`0.1`	Fraction of requests to trace (0.1 = 10%). Lower values reduce overhead in high-traffic production environments.
`OTEL_BATCH_EXPORT_SCHEDULE_DELAY`	`5000`	Delay in milliseconds between batch exports.
`OTEL_MAX_QUEUE_SIZE`	`2048`	Maximum number of spans queued before dropping.
`OTEL_MAX_EXPORT_BATCH_SIZE`	`512`	Maximum spans per export batch.
`OTEL_METRIC_EXPORT_INTERVAL`	`60000`	Metric export interval in milliseconds.
`OTEL_BATCH_EXPORT_TIMEOUT`	`10000`	Batch span export timeout in milliseconds.
`OTEL_METRIC_EXPORT_TIMEOUT`	`30000`	Metric export timeout in milliseconds.

Miscellaneous

Variable	Default	Description
`CSP_WHITELIST`	(empty)	Additional domains to allow in Content Security Policy headers.
`NEXT_TELEMETRY_DISABLED`	`0`	Set to `1` to turn off Next.js’s anonymous telemetry, which the Compose stack otherwise leaves on.
`ALLOW_EMBED`	`false`	Allow Dify pages to be embedded in iframes. When `false`, sets `X-Frame-Options: DENY` to prevent clickjacking.
`SWAGGER_UI_ENABLED`	`false`	Expose Swagger UI at `SWAGGER_UI_PATH` for browsing API documentation. Swagger endpoints bypass authentication.
`SWAGGER_UI_PATH`	`/swagger-ui.html`	URL path for Swagger UI.
`MAX_SUBMIT_COUNT`	`100`	Maximum concurrent task submissions in the thread pool used for parallel workflow node execution.
`TENANT_ISOLATED_TASK_CONCURRENCY`	`1`	Number of document indexing or RAG pipeline tasks processed simultaneously per tenant. Increase for faster indexing with more database load.
`DIFY_ENV_NACOS_REQUEST_TIMEOUT`	`10.0`	Timeout in seconds for HTTP requests to the Nacos configuration server.
`DIFY_ENV_NACOS_CONNECT_TIMEOUT`	`3.0`	Timeout in seconds for establishing a connection to the Nacos configuration server.

Scheduled Tasks Configuration

Dify uses Celery Beat to run background maintenance tasks on configurable schedules.

Variable	Default	Description
`ENABLE_CLEAN_EMBEDDING_CACHE_TASK`	`false`	Delete expired embedding cache records from the database at 2:00 AM daily. Manages database size.
`ENABLE_CLEAN_UNUSED_DATASETS_TASK`	`false`	Disable documents in knowledge bases that haven’t had activity within the retention period. Runs at 3:00 AM daily.
`ENABLE_CLEAN_MESSAGES`	`false`	Delete conversation messages older than `SANDBOX_EXPIRED_RECORDS_RETENTION_DAYS` at 4:00 AM daily.
`ENABLE_MAIL_CLEAN_DOCUMENT_NOTIFY_TASK`	`false`	Email workspace owners a list of knowledge bases that had documents auto-disabled by the cleanup task. Runs every Monday at 10:00 AM.
`ENABLE_DATASETS_QUEUE_MONITOR`	`false`	Monitor the dataset processing queue backlog in Redis. Sends email alerts when the queue exceeds the threshold.
`QUEUE_MONITOR_INTERVAL`	`30`	How often to check the queue (in minutes).
`QUEUE_MONITOR_THRESHOLD`	`200`	Queue size that triggers an alert email.
`QUEUE_MONITOR_ALERT_EMAILS`	(empty)	Email addresses to receive queue alerts (comma-separated).
`ENABLE_CHECK_UPGRADABLE_PLUGIN_TASK`	`true`	Check the marketplace for newer plugin versions every 15 minutes. Dispatches upgrade tasks based on each tenant’s auto-upgrade schedule.
`ENABLE_WORKFLOW_SCHEDULE_POLLER_TASK`	`true`	Enable the workflow schedule poller that checks for and triggers scheduled workflow runs.
`WORKFLOW_SCHEDULE_POLLER_INTERVAL`	`1`	How often to check for due scheduled workflows (in minutes).
`WORKFLOW_SCHEDULE_POLLER_BATCH_SIZE`	`100`	Maximum number of due schedules fetched per poll cycle.
`WORKFLOW_SCHEDULE_MAX_DISPATCH_PER_TICK`	`0`	Circuit breaker: maximum schedules dispatched per tick. `0` means unlimited.
`ENABLE_WORKFLOW_RUN_CLEANUP_TASK`	`false`	Enable automatic cleanup of workflow run records.
`ENABLE_CREATE_TIDB_SERVERLESS_TASK`	`false`	Pre-create TiDB Serverless clusters for vector database pooling.
`ENABLE_UPDATE_TIDB_SERVERLESS_STATUS_TASK`	`false`	Update TiDB Serverless cluster status periodically.
`ENABLE_HUMAN_INPUT_TIMEOUT_TASK`	`true`	Check for expired Human Input forms and resume or stop timed-out workflows.
`HUMAN_INPUT_TIMEOUT_TASK_INTERVAL`	`1`	How often to check for expired Human Input forms (in minutes).
`ENABLE_CONVERSATION_CLEANUP_TASK`	`true`	Safety net for conversation deletion. A deleted conversation disappears instantly while a background job removes its messages and the files generated by tools during the conversation. Files end users uploaded are kept. This sweep re-runs that job for conversations whose cleanup was lost, so their data does not linger.
`CONVERSATION_CLEANUP_TASK_INTERVAL`	`5`	How often the sweep runs (in minutes).
`CONVERSATION_CLEANUP_BATCH_SIZE`	`100`	Maximum conversations re-dispatched per sweep.

Record Retention & Cleanup

These control the scheduled cleanup of old messages and workflow run records: anything older than the retention window is deleted in batches.

Variable	Default	Description
`SANDBOX_EXPIRED_RECORDS_RETENTION_DAYS`	`30`	Records older than this many days are eligible for deletion.
`SANDBOX_EXPIRED_RECORDS_CLEAN_BATCH_SIZE`	`1000`	Number of records processed per cleanup batch.
`SANDBOX_EXPIRED_RECORDS_CLEAN_BATCH_MAX_INTERVAL`	`200`	Maximum random delay in milliseconds between cleanup batches to reduce database load.
`SANDBOX_EXPIRED_RECORDS_CLEAN_TASK_LOCK_TTL`	`90000`	Redis lock TTL in seconds (~25 hours) to prevent concurrent cleanup task execution.

Aliyun SLS Logstore Configuration

Optional integration with Aliyun Simple Log Service for storing workflow execution logs externally instead of in the database. Enable by setting the repository configuration variables to use logstore implementations.

Variable	Default	Description
`ALIYUN_SLS_ACCESS_KEY_ID`	(empty)	Aliyun access key ID for SLS authentication.
`ALIYUN_SLS_ACCESS_KEY_SECRET`	(empty)	Aliyun access key secret for SLS authentication.
`ALIYUN_SLS_ENDPOINT`	(empty)	SLS service endpoint URL (e.g., `cn-hangzhou.log.aliyuncs.com`).
`ALIYUN_SLS_REGION`	(empty)	Aliyun region (e.g., `cn-hangzhou`).
`ALIYUN_SLS_PROJECT_NAME`	(empty)	SLS project name for storing workflow logs.
`ALIYUN_SLS_LOGSTORE_TTL`	`365`	Data retention in days for SLS logstores. Use `3650` for permanent storage.
`LOGSTORE_DUAL_WRITE_ENABLED`	`false`	Write workflow data to both SLS and PostgreSQL simultaneously. Useful during migration to SLS.
`LOGSTORE_DUAL_READ_ENABLED`	`true`	Fall back to PostgreSQL when SLS returns no results. Useful during migration when historical data exists only in the database.
`LOGSTORE_ENABLE_PUT_GRAPH_FIELD`	`true`	Include the full workflow graph definition in SLS logs. Set to `false` to reduce storage by omitting large graph data.

Event Bus Configuration

Redis-based event transport between API and Celery workers.

Variable	Default	Description
`EVENT_BUS_REDIS_URL`	(empty)	Redis connection URL for event streaming. When empty, uses the main Redis connection settings.
`EVENT_BUS_REDIS_CHANNEL_TYPE`	`pubsub`	Transport type: `pubsub` (Pub/Sub, at-most-once delivery), `sharded` (sharded Pub/Sub), or `streams` (Redis Streams, at-least-once delivery).
`EVENT_BUS_REDIS_USE_CLUSTERS`	`false`	Enable Redis Cluster mode for event bus. Recommended for large deployments.

Vector Database Service Configuration

These configure the vector database containers themselves (not the Dify client connection). Only the variables for your chosen VECTOR_STORE are relevant.

Weaviate Service

Variable	Default	Description
`WEAVIATE_PERSISTENCE_DATA_PATH`	`/var/lib/weaviate`	Data persistence directory inside the container.
`WEAVIATE_QUERY_DEFAULTS_LIMIT`	`25`	Default query result limit.
`WEAVIATE_AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED`	`true`	Allow anonymous access.
`WEAVIATE_DEFAULT_VECTORIZER_MODULE`	`none`	Default vectorizer module.
`WEAVIATE_CLUSTER_HOSTNAME`	`node1`	Cluster node hostname.
`WEAVIATE_AUTHENTICATION_APIKEY_ENABLED`	`true`	Enable API key authentication.
`WEAVIATE_AUTHENTICATION_APIKEY_ALLOWED_KEYS`	(auto-generated)	Allowed API keys. Must match `WEAVIATE_API_KEY` in the client config.
`WEAVIATE_AUTHENTICATION_APIKEY_USERS`	`hello@dify.ai`	Users associated with API keys.
`WEAVIATE_AUTHORIZATION_ADMINLIST_ENABLED`	`true`	Enable admin list authorization.
`WEAVIATE_AUTHORIZATION_ADMINLIST_USERS`	`hello@dify.ai`	Admin users.
`WEAVIATE_DISABLE_TELEMETRY`	`false`	Disable Weaviate telemetry.
`WEAVIATE_ENABLE_TOKENIZER_GSE`	`false`	Enable GSE tokenizer (Chinese).
`WEAVIATE_ENABLE_TOKENIZER_KAGOME_JA`	`false`	Enable Kagome tokenizer (Japanese).
`WEAVIATE_ENABLE_TOKENIZER_KAGOME_KR`	`false`	Enable Kagome tokenizer (Korean).
`WEAVIATE_HOST_VOLUME`	`./volumes/weaviate`	Host path mounted as the Weaviate data volume. Middleware stack (source-code deployments), set in its `middleware.env`; the full Compose stack mounts `./volumes/weaviate` directly.
`EXPOSE_WEAVIATE_PORT`	`8080`	Host port at which the middleware stack (source-code deployments) publishes Weaviate’s REST API, so Dify running from source reaches it at `http://localhost:8080`. Change it when 8080 is already taken on the host, and point `WEAVIATE_ENDPOINT` at the new port. Middleware stack only; the full Compose stack keeps Weaviate on an internal network.
`EXPOSE_WEAVIATE_GRPC_PORT`	`50051`	Host port at which the middleware stack publishes Weaviate’s gRPC API, reached at `grpc://localhost:50051`. If you change it, point `WEAVIATE_GRPC_ENDPOINT` at the new port.

Milvus Service (ETCD + MinIO)

Variable	Default	Description
`ETCD_AUTO_COMPACTION_MODE`	`revision`	ETCD auto compaction mode.
`ETCD_AUTO_COMPACTION_RETENTION`	`1000`	Auto compaction retention in number of revisions.
`ETCD_QUOTA_BACKEND_BYTES`	`4294967296`	Backend quota in bytes (4 GB).
`ETCD_SNAPSHOT_COUNT`	`50000`	Number of changes before triggering a snapshot.
`ETCD_ENDPOINTS`	`etcd:2379`	ETCD service endpoints.
`MINIO_ACCESS_KEY`	`minioadmin`	MinIO access key.
`MINIO_SECRET_KEY`	`minioadmin`	MinIO secret key.
`MINIO_ADDRESS`	`minio:9000`	MinIO service address.
`MILVUS_AUTHORIZATION_ENABLED`	`true`	Enable Milvus security authorization.

OpenSearch Service

Variable	Default	Description
`OPENSEARCH_DISCOVERY_TYPE`	`single-node`	Discovery type for cluster formation.
`OPENSEARCH_BOOTSTRAP_MEMORY_LOCK`	`true`	Lock memory on startup to prevent swapping.
`OPENSEARCH_JAVA_OPTS_MIN`	`512m`	Minimum JVM heap size.
`OPENSEARCH_JAVA_OPTS_MAX`	`1024m`	Maximum JVM heap size.
`OPENSEARCH_INITIAL_ADMIN_PASSWORD`	`Qazwsxedc!@#123`	Initial admin password for the OpenSearch service.
`OPENSEARCH_MEMLOCK_SOFT`	`-1`	Soft memory lock limit (`-1` = unlimited).
`OPENSEARCH_MEMLOCK_HARD`	`-1`	Hard memory lock limit (`-1` = unlimited).
`OPENSEARCH_NOFILE_SOFT`	`65536`	Soft file descriptor limit.
`OPENSEARCH_NOFILE_HARD`	`65536`	Hard file descriptor limit.

PGVector / PGVecto.RS Service

Variable	Default	Description
`PGVECTOR_PGUSER`	`postgres`	PostgreSQL user for the PGVector container.
`PGVECTOR_POSTGRES_PASSWORD`	(auto-generated)	PostgreSQL password for the PGVector container.
`PGVECTOR_POSTGRES_DB`	`dify`	Database name in the PGVector container.
`PGVECTOR_PGDATA`	`/var/lib/postgresql/data/pgdata`	Data directory inside the container.
`PGVECTOR_PG_BIGM_VERSION`	`1.2-20240606`	Version of the pg_bigm extension.

Oracle / Chroma / Elasticsearch Services

Variable	Default	Description
`ORACLE_PWD`	`Dify123456`	Oracle database password for the container.
`ORACLE_CHARACTERSET`	`AL32UTF8`	Oracle character set.
`CHROMA_SERVER_AUTHN_CREDENTIALS`	(auto-generated)	Authentication credentials for the Chroma server container.
`CHROMA_SERVER_AUTHN_PROVIDER`	`chromadb.auth.token_authn.TokenAuthenticationServerProvider`	Authentication provider for the Chroma server.
`CHROMA_IS_PERSISTENT`	`TRUE`	Enable persistent storage for Chroma.
`KIBANA_PORT`	`5601`	Kibana port (Elasticsearch UI).

IRIS / Other Services

Variable	Default	Description
`IRIS_WEB_SERVER_PORT`	`52773`	IRIS web server management port.
`IRIS_TIMEZONE`	`UTC`	Timezone for the IRIS container.
`DB_PLUGIN_DATABASE`	`dify_plugin`	Separate database name for plugin data.

Plugin Daemon Storage Configuration

The plugin daemon can store plugin packages in different storage backends. Configure only the provider matching PLUGIN_STORAGE_TYPE.

Variable	Default	Description
`PLUGIN_STORAGE_TYPE`	`local`	Plugin storage backend: `local`, `aws_s3`, `tencent_cos`, `azure_blob`, `aliyun_oss`, `volcengine_tos`.
`PLUGIN_STORAGE_LOCAL_ROOT`	`/app/storage`	Root directory for local plugin storage.
`PLUGIN_WORKING_PATH`	`/app/storage/cwd`	Working directory for plugin execution.
`PLUGIN_INSTALLED_PATH`	`plugin`	Subdirectory for installed plugins.
`PLUGIN_PACKAGE_CACHE_PATH`	`plugin_packages`	Subdirectory for cached plugin packages.
`PLUGIN_MEDIA_CACHE_PATH`	`assets`	Subdirectory for cached media assets.
`PLUGIN_STORAGE_OSS_BUCKET`	(empty)	Object storage bucket name (shared across S3/COS/OSS/TOS providers).
`PLUGIN_PPROF_ENABLED`	`false`	Enable Go pprof profiling for the plugin daemon.
`PLUGIN_PYTHON_ENV_INIT_TIMEOUT`	`120`	Timeout in seconds for initializing Python environments for plugins.
`PLUGIN_STDIO_BUFFER_SIZE`	`1024`	Buffer size in bytes for plugin stdio communication.
`PLUGIN_STDIO_MAX_BUFFER_SIZE`	`5242880`	Maximum buffer size in bytes (5 MB) for plugin stdio communication.
`ENDPOINT_URL_TEMPLATE`	`http://localhost/e/{hook_id}`	URL template for plugin endpoints. `{hook_id}` is replaced with the actual hook ID.
`EXPOSE_PLUGIN_DAEMON_PORT`	`5002`	Host port mapped to the plugin daemon.
`EXPOSE_PLUGIN_DEBUGGING_HOST`	`localhost`	Host for plugin remote debugging.
`EXPOSE_PLUGIN_DEBUGGING_PORT`	`5003`	Host port for plugin remote debugging.

Plugin S3 Storage

Variable	Default	Description
`PLUGIN_S3_USE_AWS`	`false`	Use AWS S3 (vs S3-compatible services).
`PLUGIN_S3_USE_AWS_MANAGED_IAM`	`false`	Use IAM roles instead of explicit credentials.
`PLUGIN_S3_ENDPOINT`	(empty)	S3 endpoint URL.
`PLUGIN_S3_USE_PATH_STYLE`	`false`	Use path-style URLs instead of virtual-hosted.
`PLUGIN_AWS_ACCESS_KEY`	(empty)	AWS access key.
`PLUGIN_AWS_SECRET_KEY`	(empty)	AWS secret key.
`PLUGIN_AWS_REGION`	(empty)	AWS region.

Plugin Azure Blob Storage

Variable	Default	Description
`PLUGIN_AZURE_BLOB_STORAGE_CONTAINER_NAME`	(empty)	Azure Blob container name.
`PLUGIN_AZURE_BLOB_STORAGE_CONNECTION_STRING`	(empty)	Azure Blob connection string.

Plugin Tencent COS Storage

Variable	Default	Description
`PLUGIN_TENCENT_COS_SECRET_KEY`	(empty)	Tencent COS secret key.
`PLUGIN_TENCENT_COS_SECRET_ID`	(empty)	Tencent COS secret ID.
`PLUGIN_TENCENT_COS_REGION`	(empty)	Tencent COS region.

Plugin Aliyun OSS Storage

Variable	Default	Description
`PLUGIN_ALIYUN_OSS_REGION`	(empty)	Aliyun OSS region.
`PLUGIN_ALIYUN_OSS_ENDPOINT`	(empty)	Aliyun OSS endpoint.
`PLUGIN_ALIYUN_OSS_ACCESS_KEY_ID`	(empty)	Aliyun OSS access key ID.
`PLUGIN_ALIYUN_OSS_ACCESS_KEY_SECRET`	(empty)	Aliyun OSS access key secret.
`PLUGIN_ALIYUN_OSS_AUTH_VERSION`	`v4`	Aliyun OSS authentication version.
`PLUGIN_ALIYUN_OSS_PATH`	(empty)	Aliyun OSS path prefix.

Plugin Volcengine TOS Storage

Variable	Default	Description
`PLUGIN_VOLCENGINE_TOS_ENDPOINT`	(empty)	Volcengine TOS endpoint.
`PLUGIN_VOLCENGINE_TOS_ACCESS_KEY`	(empty)	Volcengine TOS access key.
`PLUGIN_VOLCENGINE_TOS_SECRET_KEY`	(empty)	Volcengine TOS secret key.
`PLUGIN_VOLCENGINE_TOS_REGION`	(empty)	Volcengine TOS region.

Last modified on October 23, 2026

​Common Variables

​CONSOLE_API_URL

​SERVER_CONSOLE_API_URL

​CONSOLE_WEB_URL

​SERVICE_API_URL

​APP_API_URL

​APP_WEB_URL

​TRIGGER_URL

​FILES_URL

​INTERNAL_FILES_URL

​FILES_ACCESS_TIMEOUT

​ENABLE_COLLABORATION_MODE

​System Encoding

​Server Configuration

​Logging

​General

​SECRET_KEY

​PASSWORD_PEPPER

​KEY_PROVIDER_TYPE

​INIT_PASSWORD

​Token & Request Limits

​Container Startup Configuration

​MODE

​API Tool Configuration

​Database Configuration

​Connection Pool

​PostgreSQL Performance Tuning

​MySQL Performance Tuning

​Redis Configuration

​Redis SSL Configuration

​Redis Sentinel Mode

​Redis Cluster Mode

​Redis Connection Resilience

​Celery Configuration

​CELERY_BROKER_URL

​CORS Configuration

​Dify CLI and Programmatic API

​File Storage Configuration

​STORAGE_TYPE

​Archive Storage

​Vector Database Configuration

​VECTOR_STORE

​Knowledge Configuration

​Annotation Import

​Model Configuration

​Multi-modal Configuration

​Sentry Configuration

​Notion Integration Configuration

​Mail Configuration

​Other Configuration

​Console Features

​Authentication and Accounts

​LLMOps Trace Delivery

​Indexing

​New User Defaults

​Workflow Generation

​Token & Invitation

​Code Execution Sandbox

​Code and Template Output Limits

​Workflow Runtime

​Workflow Storage Repository

​Workflow Log Cleanup

​HTTP Request Node

​Webhook

​SSRF Protection

​Agent Configuration

​Web Frontend Service

​NEXT_PUBLIC_ENABLE_FEATURE_PREVIEW

​Agent (New)

​DIFY_AGENT_SERVER_SECRET_KEY

​DIFY_AGENT_API_TOKEN

​DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN

​NEXT_PUBLIC_ENABLE_AGENT_V2

​UPLOAD_SKILL_FILE_SIZE_LIMIT

​Agent and App Package Limits

​AGENT_BACKEND_BASE_URL

​DIFY_AGENT_RUNTIME_BACKEND

​Agent Trajectory Export

​Database Service

​Sandbox Service

Common Variables

CONSOLE_API_URL

SERVER_CONSOLE_API_URL

CONSOLE_WEB_URL

SERVICE_API_URL

APP_API_URL

APP_WEB_URL

TRIGGER_URL

FILES_URL

INTERNAL_FILES_URL

FILES_ACCESS_TIMEOUT

ENABLE_COLLABORATION_MODE

System Encoding

Server Configuration

Logging

General

SECRET_KEY

PASSWORD_PEPPER

KEY_PROVIDER_TYPE

INIT_PASSWORD

Token & Request Limits

Container Startup Configuration

MODE

API Tool Configuration

Database Configuration

Connection Pool

PostgreSQL Performance Tuning

MySQL Performance Tuning

Redis Configuration

Redis SSL Configuration

Redis Sentinel Mode

Redis Cluster Mode

Redis Connection Resilience

Celery Configuration

CELERY_BROKER_URL

CORS Configuration

Dify CLI and Programmatic API

File Storage Configuration

STORAGE_TYPE

Archive Storage

Vector Database Configuration

VECTOR_STORE

Knowledge Configuration

Annotation Import

Model Configuration

Multi-modal Configuration

Sentry Configuration

Notion Integration Configuration

Mail Configuration

Other Configuration

Console Features

Authentication and Accounts

LLMOps Trace Delivery

Indexing

New User Defaults

Workflow Generation

Token & Invitation

Code Execution Sandbox

Code and Template Output Limits

Workflow Runtime

Workflow Storage Repository

Workflow Log Cleanup

HTTP Request Node

Webhook

SSRF Protection

Agent Configuration

Web Frontend Service

NEXT_PUBLIC_ENABLE_FEATURE_PREVIEW

Agent (New)

DIFY_AGENT_SERVER_SECRET_KEY

DIFY_AGENT_API_TOKEN

DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN

NEXT_PUBLIC_ENABLE_AGENT_V2

UPLOAD_SKILL_FILE_SIZE_LIMIT

Agent and App Package Limits

AGENT_BACKEND_BASE_URL

DIFY_AGENT_RUNTIME_BACKEND

Agent Trajectory Export

Database Service

Sandbox Service