Environment Variables

Configuration Files

Docker Compose reads Dify’s settings from three kinds of files.

docker/.env: deployment-wide settings, such as Compose profiles and published ports, and the shared credentials. For a new deployment, create it from docker/.env.example.
.defaults files under docker/envs/: the bundled defaults, which services load automatically. Leave them unedited: each release ships new versions of them.
Local .env files under docker/envs/: your overrides for the services that load them. Git ignores them, so checking out a new release leaves them in place.

When you run Dify from source code, set the variables in api/.env, web/.env.local, and docker/middleware.env for the middleware containers.

Set a Variable

Find the File

Set most variables in a local .env file under docker/envs/, and these two kinds in docker/.env:

Settings Compose reads before it loads any service file, such as COMPOSE_PROFILES and VECTOR_STORE.
Shared credentials, so every service that uses one gets the same value:
- PLUGIN_DAEMON_KEY and PLUGIN_DIFY_INNER_API_KEY: use a different strong value for each.
- DIFY_AGENT_API_TOKEN and DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN: use a different strong value for each.
- SANDBOX_API_KEY and CODE_EXECUTION_API_KEY: set both to the same value; if they differ, Code and Template nodes fail with HTTP 401.

For any other variable, search docker/envs/ for its name, then act on what the search finds:

One .defaults file: edit the local file named in its first comment. If that file doesn’t exist yet, copy the .defaults file to that name first.
Several .defaults files: edit the local file that every service using the variable loads; otherwise the services end up with different values.
An .env.example template, such as envs/security.env.example: copy it to the same name without .example. Skip envs/middleware.env.example, which only the separate middleware stack for source-code development reads.

When docker/.env and a local file set the same variable, the docker/.env value wins, with the exceptions in Precedence.

Edit the Value

In the local file, change the values you need and uncomment only the optional settings you want.

Leave the lines under Container variable mappings unchanged. Each passes the setting you edit to the variable name the container reads.

To go back to a bundled default, delete the line or comment it out; don’t leave it blank. A blank line such as CELERY_WORKER_AMOUNT= can still override the default with an empty value, and a blank line in docker/.env hides the value in your local file.

Apply the Change

From dify/docker, validate the configuration and recreate the affected containers:

docker compose config --quiet
docker compose up -d

Use up -d, not docker compose restart: restart keeps the containers’ old environment. To see the resolved values, run docker compose config. Its output contains secrets, so keep it private.For a worked example that ends by checking the running service, see Customize. To update to a new release without losing your local files, secrets, or data, follow Upgrade.

Precedence

When a variable is set in more than one place, which value a service uses depends on whether the service loads docker/.env:

Services That Load docker/.env
Other Services

The API, WebSocket API, workers, Beat, web, Code sandbox, plugin daemon, and agent backend use the first match, in this order:

docker/.env
The service’s local .env files
Its .defaults files
The application default

Variables under the Container variable mappings comment in a .defaults file always copy their value from another setting. Setting them directly has no effect, even in docker/.env, so change the setting they copy from instead.

Nginx, the databases, Redis, the vector stores, and the other supporting services don’t load docker/.env. Set their variables in the service’s local .env file, where it has one.The exception is a setting their .defaults file reads from docker/.env. For those, a value in docker/.env reaches the service and wins over its local file.

If a value doesn’t come from any of these files, check two more places:

A variable exported in the shell where you run Compose, which wins over docker/.env for ${...} values
The service’s environment: entry in the Compose file, such as MODE: api, which wins over every env file

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`, which is no longer read. Use `COMMUNITY` for the former `SELF_HOSTED` value.
`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: (empty; generated and saved in configured storage) Signs authentication tokens and file URLs, and encrypts system-level OAuth client credentials. When this variable is empty, Dify reuses the key in .dify_secret_key in its configured storage, or generates and saves one if none exists. With the bundled file system storage, the host path is docker/volumes/app/storage/.dify_secret_key. A nonempty SECRET_KEY takes precedence over the stored key. To supply your own key, generate a strong random value and set it before first launch:

openssl rand -base64 42

If Dify cannot save a generated key, initialization fails. Make the configured storage writable or provide an explicit key.

Preserve the same key through upgrades and restores, whether you supply it explicitly or keep it in persistent storage. Changing it invalidates existing authentication tokens and signed file URLs, and prevents Dify from decrypting existing system-level OAuth client credentials. Restore the original key to recover access to those credentials.

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. 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.
`GUNICORN_KEEP_ALIVE`	`10`	How many seconds the API server (Gunicorn) keeps an idle connection open so the next request can reuse it.
`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: service-specific (api, worker, or beat in Docker Compose) Selects what the dify-api image runs at container start. The bundled Compose file sets MODE in each service’s environment, which takes precedence over env-file values. 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

Set this only 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. Choose one before the first start: Dify doesn’t move stored data when you change database types. For a new deployment with bundled MySQL and Weaviate, set these values in docker/.env:

DB_TYPE=mysql
DB_HOST=db_mysql
DB_PORT=3306
DB_USERNAME=root
COMPOSE_PROFILES=weaviate,mysql,collaboration

If you use another vector store, put its profile in place of weaviate. Set a custom DB_PASSWORD before the first start. To change the password later, change it on the database server first, then update DB_PASSWORD to match.

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`	WebSocket address the browser uses for real-time collaboration. The default works only for a browser on the server itself. For remote access, add it to `docker/.env` with Dify’s address, such as `wss://dify.example.com`, and run `docker compose up -d`. Use `ws://` for HTTP or `wss://` for HTTPS, and give the scheme, host, and port only; the `/socket.io/` path is fixed.
`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 databases that store knowledge base embeddings for similarity search.

VECTOR_STORE

Default: weaviate Selects the vector database for new knowledge bases. Existing knowledge bases keep using the one they were indexed in. 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_vector, tidb_on_qdrant, baidu, lindorm, huawei_cloud, upstash, matrixone, clickzetta, alibabacloud_mysql, iris, hologres. Bundled providers, each with a Compose profile of the same name: weaviate, qdrant, oceanbase, seekdb, couchbase, pgvector, pgvecto-rs, vastbase, chroma, iris, oracle, milvus, opensearch, opengauss, myscale, matrixone, elasticsearch, and elasticsearch-ja. For any other provider, or an external server, omit the bundled profile. Set the connection settings in the provider’s local .env file, or in envs/core-services/api-worker.env for a provider without one. To switch to another bundled provider:

Keep What Existing Knowledge Bases Use

Leave the old provider’s profile in COMPOSE_PROFILES. If it isn’t Weaviate, also copy its .defaults file to its local .env file, such as qdrant.defaults to qdrant.env. elasticsearch-ja uses the same elasticsearch.env as elasticsearch. Only the selected provider’s defaults load automatically; without the copy, existing knowledge bases lose their connection.

Select the New Provider

In docker/.env, set VECTOR_STORE and add the provider’s profile to COMPOSE_PROFILES, then run docker compose up -d.

OceanBase and seekdb share the OCEANBASE_* settings, so Dify connects to only one of them at a time. To switch between these two, migrate existing knowledge bases instead of keeping both. To move existing knowledge bases’ data to the new provider, see Vector Database Migration. To change a provider’s connection settings, follow Set a Variable. For providers that store user passwords, change the password in the database before updating the matching client setting.

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`	(development key in the bundled defaults; must be replaced for production)	API key the API and workers use to authenticate with Weaviate. Must match an entry in `WEAVIATE_AUTHENTICATION_APIKEY_ALLOWED_KEYS`. See Vector Database Service Configuration to require authentication and set matching client and server values.
`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

Both providers use the OCEANBASE_* variables. Set VECTOR_STORE to oceanbase or seekdb to load that provider’s connection defaults.

Variable	Default	Description
`OCEANBASE_VECTOR_HOST`	`oceanbase` / `seekdb`	Hostname or IP address. The bundled default follows `VECTOR_STORE`.
`OCEANBASE_VECTOR_PORT`	`2881`	Port number.
`OCEANBASE_VECTOR_USER`	`root@test` / `root`	Database username. The bundled default follows `VECTOR_STORE`.
`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. Set an empty value for an external server that does not require authentication.
`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://milvus-standalone:19530`	Milvus URI. For Zilliz Cloud, use the Public Endpoint.
`MILVUS_DATABASE`	`default`	Database name.
`MILVUS_TOKEN`	(empty)	Authentication token. For Zilliz Cloud, use the API Key.
`MILVUS_USER`	`root`	Username.
`MILVUS_PASSWORD`	`Milvus`	Password. To change it later, change the user’s password in Milvus first, then update this value to match.
`MILVUS_ENABLE_HYBRID_SEARCH`	`true`	Adds a BM25 sparse index so full-text search works alongside vector similarity. Needs Milvus 2.5.0 or later; with an older server, Dify skips the index on its own and full-text search returns no results. A collection created without the index must be recreated before full-text search works.
`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

For the bundled PGVector, leave the client username, password, and database unset: they follow the container settings under Vector Database Service Configuration. Set them for an external server.

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

For the bundled Vastbase, keep the defaults of VASTBASE_USER and VASTBASE_PASSWORD: they match VB_USERNAME and VB_PASSWORD in docker-compose.yaml. For an external server, set them to its credentials.

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

For the bundled PGVecto.RS, leave the client username, password, and database unset: they follow the container settings under Vector Database Service Configuration. Set them for an external server.

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_HOSTchromaChroma 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_CREDENTIALSdifyai123456Authentication credentials. For the bundled Chroma, leave it unset: it follows CHROMA_SERVER_AUTHN_CREDENTIALS. Set it for an external server.

Variable	Default	Description
`CHROMA_HOST`	`chroma`	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`	`difyai123456`	Authentication credentials. For the bundled Chroma, leave it unset: it follows `CHROMA_SERVER_AUTHN_CREDENTIALS`. Set it for an external server.

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

To use the bundled OpenSearch for local development, set OPENSEARCH_VERIFY_CERTS=false in envs/vectorstores/opensearch.env: the image ships demo certificates. For production and external servers, use certificates the client trusts and keep verification on.

Variable	Default	Description
`OPENSEARCH_HOST`	`opensearch`	Hostname.
`OPENSEARCH_PORT`	`9200`	Port number.
`OPENSEARCH_SECURE`	`true`	Use HTTPS.
`OPENSEARCH_VERIFY_CERTS`	`true`	Verify TLS certificates for OpenSearch HTTPS connections.
`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`	`Qazwsxedc!@#123`	Password. Only used with `basic` auth. For the bundled OpenSearch, leave it unset: it follows `OPENSEARCH_INITIAL_ADMIN_PASSWORD`. Set it for an external server.
`OPENSEARCH_AWS_REGION`	(empty)	AWS region. Required with `aws_managed_iam` auth.
`OPENSEARCH_AWS_SERVICE`	(empty)	AWS service type: `es` (Managed Cluster) or `aoss` (OpenSearch Serverless). Required 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

For both VECTOR_STORE=elasticsearch and VECTOR_STORE=elasticsearch-ja, customize the connection in envs/vectorstores/elasticsearch.env, copied from elasticsearch.defaults.

Variable	Default	Description
`ELASTICSEARCH_HOST`	`elasticsearch`	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
`API_SENTRY_DSN`	(empty)	Sentry DSN for the API and workers. Empty disables Sentry for those services.
`API_SENTRY_TRACES_SAMPLE_RATE`	`1.0`	Fraction of API and worker requests to trace (0.01 = 1%, 1.0 = 100%). Traces track request flow across services. No effect while `API_SENTRY_DSN` is empty.
`API_SENTRY_PROFILES_SAMPLE_RATE`	`1.0`	Fraction of traced requests to profile for CPU and memory use. Profiles show where time is spent in code. The effective rate is the traces rate × this rate. No effect while `API_SENTRY_DSN` is empty.
`WEB_SENTRY_DSN`	(empty)	Sentry DSN for the web frontend. Empty disables Sentry there.
`PLUGIN_SENTRY_ENABLED`	`false`	Enable Sentry for the plugin daemon. Also set `PLUGIN_SENTRY_DSN`.
`PLUGIN_SENTRY_DSN`	(empty)	Sentry DSN for the plugin daemon.
`SENTRY_DSN`	(empty)	Sentry DSN that each container reads. With Docker Compose, set the per-service DSN instead: `API_SENTRY_DSN` for the API and workers, `WEB_SENTRY_DSN` for the web frontend, or `PLUGIN_SENTRY_DSN` for the plugin daemon.
`SENTRY_TRACES_SAMPLE_RATE`	`1.0`	Fraction of requests the API and workers trace. With Docker Compose, set `API_SENTRY_TRACES_SAMPLE_RATE` instead.
`SENTRY_PROFILES_SAMPLE_RATE`	`1.0`	Fraction of traced requests the API and workers profile. With Docker Compose, set `API_SENTRY_PROFILES_SAMPLE_RATE` instead.

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. Dify CLI (`difyctl`) commands such as `difyctl get skill` then fail with a 503 `skills_disabled` error.

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/api-worker.env.

Variable	Default	Description
`OPS_TRACE_QUEUE`	`ops_trace_v2`	The Celery queue that carries trace delivery and its retries, Agent trace export and recovery, the daily trace cleanup, and E2B sandbox usage metering. If you change it, set the same value for the API, workers, and Celery Beat; a task sent to a queue no worker listens on doesn’t run. The bundled Docker Compose worker listens on it automatically. If you set `CELERY_QUEUES` or `CELERY_WORKER_QUEUES` yourself, or start workers with your own `-Q` list, include this queue; otherwise those tasks don’t run, and traces don’t reach your tracing provider. For a rolling upgrade, follow Ops tracing rolling upgrades in the Dify repository. Letters, digits, `_`, `.`, and `-` only.
`OPS_TRACE_EXPORT_MAX_ATTEMPTS`	`6`	How many times Dify tries to send a trace while the tracing provider is temporarily unavailable, counting the first try. A trace the provider rejects isn’t retried. Must be at least 1. The wait between tries starts at 10 seconds and doubles, up to 10 minutes. At the default, the last try comes about 5 minutes after the first; raise it if your provider’s outages last longer. Replaces the former `OPS_TRACE_RETRYABLE_DISPATCH_MAX_RETRIES` and `OPS_TRACE_RETRYABLE_DISPATCH_DELAY_SECONDS`, which are no longer read. Don’t copy the old retry count: with the doubling wait, the same number of tries takes far longer.
`ENABLE_TRACE_PAYLOAD_SWEEP_TASK`	`true`	Runs a daily Celery Beat cleanup at 03:30 that deletes trace data an interrupted delivery left in storage, once it’s older than 2 days. The time follows `LOG_TZ` (UTC if unset). Set to `false` only if you delete old files under `trace_payloads/` in Dify’s storage another way; otherwise they stay.
`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 a new 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 `api-worker.env`: the agent backend doesn’t read that file. While it’s on, an Agent run that its app traces goes to the app’s tracing provider instead of trajectory export.
`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.

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. Takes effect only when `NEW_USER_DEFAULT_PLUGIN_IDS` is set: the defaults are applied once those plugins finish installing.

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 workers how to connect to the sandbox for Code nodes, Template nodes, Jinja2 prompts, and the built-in Code tool.

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`; set both to the same value in `docker/.env`.
`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 processes apply these limits to the output returned by Code and Template nodes; set them in envs/core-services/api-worker.env. The sandbox service doesn’t read them.

Variable	Default	Description
`CODE_MAX_NUMBER`	`9223372036854775807`	Maximum numeric value allowed in Code node output (max 64-bit signed integer).
`CODE_MIN_NUMBER`	`-9223372036854775807`	Minimum numeric value allowed in Code node output.
`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 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 in the bundled defaults; 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. The bundled default is a publicly known development key. Anyone who knows it can forge those tokens, so 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 in the bundled defaults; must be replaced for production) Bearer token the Dify API and workers present when calling the agent backend’s run API. Set it in docker/.env so the API, workers, and agent backend use the same value. The bundled default is a publicly known development token. Anyone who can reach the agent backend and knows the token can start runs, so 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. Without a token, both services exit at startup and keep restarting, so set it before you start Dify. Generate one:

openssl rand -hex 32

Set it in docker/.env so the agent backend and the bundled sandbox (local_sandbox) use the same value. It replaces the former DIFY_AGENT_SHELLCTL_AUTH_TOKEN, which Compose still reads from docker/.env when this variable is unset or empty. A value set only in envs/core-services/dify-agent.env doesn’t take effect. If yours is there, move it to docker/.env and run docker compose up -d from dify/docker.

NEXT_PUBLIC_ENABLE_AGENT_V2

Default: true (Docker Compose) Shows the new Agent in the web UI: the Agents item in the main navigation and the new Agent node in the node picker of Workflow apps. It replaces the former ENABLE_AGENT_V2, which has no effect with the current Compose files. Set it to false in docker/envs/core-services/web.env to hide the new Agent and fall back to the classic Agent node; set it back to true to show it again. Either way, recreate the web container, then hard-refresh your browser:

docker compose up -d web

NEXT_PUBLIC_ENABLE_AGENT_V2_IN_CHATFLOW

Default: false Set to true to add the new Agent node to the node picker of Chatflow apps too. Works only while NEXT_PUBLIC_ENABLE_AGENT_V2 is true.

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, skills, or workflows 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.
`APP_PACKAGE_MAX_WORKFLOW_TOOLS`	`20`	Maximum number of workflows a package bundles. When an app calls published workflows as workflow tools, exporting it bundles those workflows, plus any workflows they call in turn. Raise it if an app that calls many workflow tools fails to export or import. Must be at least 1.

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`. The API-side `APP_MAX_EXECUTION_TIME` and `WORKFLOW_MAX_EXECUTION_TIME` (default `3600`) cap runs earlier if set below this. On the `local` backend, values above an hour take effect: to allow longer runs, raise this and both API-side limits. 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. Replaces the former `AGENT_BACKEND_RUN_TIMEOUT_SECONDS`, which is no longer read.
`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. With Docker Compose, set `PLUGIN_DAEMON_KEY` in `docker/.env` instead.
`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`)	Credential for the Dify API’s plugin callbacks. Must match the API service’s `INNER_API_KEY_FOR_PLUGIN`, not `INNER_API_KEY`. With Docker Compose, set `PLUGIN_DIFY_INNER_API_KEY` in `docker/.env` instead.
`DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT`	`http://local_sandbox:5004`	Address of the bundled sandbox service. Replaces the former `DIFY_AGENT_SHELLCTL_ENTRYPOINT`, which Compose still reads when this variable is unset or empty.
`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 to an address they can reach that routes to the agent backend’s `/agent-stub` path. Expose only that path, for example through a reverse proxy: port 5050 also serves the API that starts agent runs.
`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 envs/core-services/dify-agent.env. Each remote backend reads its own group of variables:

E2B

The docker/docker-compose.e2b.yaml overlay is for testing E2B with a separate, empty PostgreSQL volume; don’t apply it to an existing deployment.

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. If the deployment serves tenants that don’t trust each other, give each its own OpenShell workspace and volume. A shared volume can’t reliably keep one tenant out of another’s persistent files.
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 envs/core-services/dify-agent.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 (single-tenant, such as local development): `{"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 traces of agent runs, with their 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 the OpenTelemetry instrumentation of the API and Worker. It isn’t separate from LLMOps Trace Delivery, which app builders set up per app with providers such as Langfuse. With Agent tracing turned on there, a run that its app traces goes only to the app’s tracing provider, and every other Agent run reaches the collector. To turn it on:

In docker/envs/core-services/dify-agent.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 api-worker.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 service runs Code nodes, Template nodes, Jinja2 prompts, and the built-in Code tool. To replace the default API key, set SANDBOX_API_KEY and CODE_EXECUTION_API_KEY to the same strong secret in docker/.env, then run docker compose up -d. If they differ, Code and Template nodes fail with HTTP 401. Keep SANDBOX_ENABLE_NETWORK=true. Dify requests network access for every sandbox run, even when the code makes no network calls. With false, these features fail with network is disabled, please enable it in the configuration. Code in the sandbox can’t reach the internet directly: outbound HTTP and HTTPS requests go through the SSRF proxy. It can still connect directly to the API, workers, plugin daemon, and other services on the same internal network (ssrf_proxy_network). If code must not reach them, isolate the sandbox’s network yourself.

Variable	Default	Description
`SANDBOX_API_KEY`	`dify-sandbox`	API key for sandbox authentication. Must match `CODE_EXECUTION_API_KEY`; set both to the same value in `docker/.env`.
`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`	Required for Code nodes, Template nodes, Jinja2 prompts, and the built-in Code tool. Keep it `true`.
`SANDBOX_HTTP_PROXY`	`http://ssrf_proxy:3128`	HTTP proxy for SSRF protection, used by proxy-aware clients.
`SANDBOX_HTTPS_PROXY`	`http://ssrf_proxy:3128`	HTTPS proxy for SSRF protection, used by proxy-aware clients.
`SANDBOX_PORT`	`8194`	Sandbox service port. If you change it, update `CODE_EXECUTION_ENDPOINT` in `docker/envs/core-services/api-worker.env` to use the same 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 `envs/infrastructure/ssrf-proxy.env`. 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 in `envs/infrastructure/ssrf-proxy.env`. 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

Keep Compose settings in docker/.env: Compose reads them before it starts any container. When you change DB_TYPE or VECTOR_STORE, update COMPOSE_PROFILES to match; see Database Configuration and VECTOR_STORE for the steps.

Variable	Default	Description
`COMPOSE_PROFILES`	`weaviate,postgresql,collaboration`	Selects which bundled service containers start. Include the profiles of your bundled database and vector store, such as `postgresql` and `weaviate`; a bundled service whose profile is missing doesn’t start. The `collaboration` profile starts the dedicated `api_websocket` container. Remove it only when you set `ENABLE_COLLABORATION_MODE` to `false`.
`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`	(development key in the bundled defaults; must be replaced for production)	Authenticates the API, workers, and agent backend to the plugin daemon. Set it in `docker/.env` so the daemon and its clients use the same value. If they differ, calls to the plugin daemon fail to authenticate. Use a strong secret separate from `PLUGIN_DIFY_INNER_API_KEY`. Keep the working value when you upgrade.
`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. For the full Compose stack, set it in `docker/envs/core-services/plugin-daemon.env`. For the separate middleware stack, set it in `middleware.env`.
`DB_PLUGIN_DATABASE`	`dify_plugin`	Name of the plugin daemon’s database, separate from the main Dify database.
`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`	(development key in the bundled defaults; must be replaced for production)	Shared credential for callbacks to the Dify API. Set it in `docker/.env` so the API, workers, plugin daemon, and agent backend use the same value. If they differ, plugin callbacks fail to authenticate. Use a strong secret separate from `PLUGIN_DAEMON_KEY`. Keep the working value when you upgrade.
`INNER_API_KEY_FOR_PLUGIN`	(development key in the bundled defaults; must be replaced for production)	Plugin callback secret that the API and workers read. With Docker Compose, set `PLUGIN_DIFY_INNER_API_KEY` in `docker/.env` instead. The API checks this secret on plugin callbacks, including model invocation, tool calls, and file transfer. On mismatch, those calls fail while plugin installation can still work.
`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. You also can’t switch plugin versions. The console drops the remaining Marketplace entry points too: Creator Center in the help menu, View more above the home page’s templates, and the `@plugin` scope in Go to Anything. 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.
`UV_CACHE_DIR`	(empty; falls back to `.uv-cache` in `PLUGIN_WORKING_PATH`)	Directory where the plugin daemon caches Python packages while installing plugin dependencies. Set it to a path inside the container, such as `/tmp/.uv-cache`, if installing plugin dependencies fails with permission errors on a Docker or WSL bind mount. Set it in `docker/envs/core-services/plugin-daemon.env`. Requires plugin daemon 0.6.11 or later.

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 variables configure the vector database containers themselves.

Weaviate Service

To require authentication, set WEAVIATE_AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=false in docker/envs/vectorstores/weaviate.env. In the same file, set WEAVIATE_API_KEY to a strong secret and include it in WEAVIATE_AUTHENTICATION_APIKEY_ALLOWED_KEYS.Replacing keys alone leaves anonymous access enabled.

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. Set to `false` to require authentication.
`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`	(development key in the bundled defaults; must be replaced for production)	Allowed API keys. The bundled key matches the default `WEAVIATE_API_KEY`. When replacing it, also update the client key.
`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

Set OPENSEARCH_MEMLOCK_* and OPENSEARCH_NOFILE_* in docker/.env: Compose reads them before it loads service files.

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. Also supplies the default `OPENSEARCH_PASSWORD`; an explicit client override must match.
`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.

Qdrant Service

Set these in docker/.env: Compose reads them before it loads service files.

Variable	Default	Description
`QDRANT_NOFILE_SOFT`	`524288`	Soft limit on the number of files the bundled Qdrant container can open. Raise it if Qdrant reports too many open files.
`QDRANT_NOFILE_HARD`	`524288`	Hard limit on the number of files the bundled Qdrant container can open. The soft limit can’t exceed it.

PGVector / PGVecto.RS Service

Variable	Default	Description
`PGVECTOR_PGUSER`	`postgres`	PostgreSQL user for the PGVector and PGVecto.RS containers. Also supplies their default client username.
`PGVECTOR_POSTGRES_PASSWORD`	`difyai123456`	Initialization password for the PGVector and PGVecto.RS containers. Also supplies the default `PGVECTOR_PASSWORD` and `PGVECTO_RS_PASSWORD`; explicit client overrides must match. Changing it later doesn’t change the password in an existing database: change it in PostgreSQL first, then update this value to match.
`PGVECTOR_POSTGRES_DB`	`dify`	Database name in the PGVector and PGVecto.RS containers. Also supplies their default client database name.
`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 administrator password, separate from the Dify client password in `ORACLE_PASSWORD`.
`ORACLE_CHARACTERSET`	`AL32UTF8`	Oracle character set.
`CHROMA_SERVER_AUTHN_CREDENTIALS`	`difyai123456`	Authentication credentials for the Chroma server container. Also supplies the default `CHROMA_AUTH_CREDENTIALS`; an explicit client override must match.
`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.

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 November 4, 2026

Configuration Files

Set a Variable

Precedence

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

NEXT_PUBLIC_ENABLE_AGENT_V2_IN_CHATFLOW

UPLOAD_SKILL_FILE_SIZE_LIMIT

Agent and App Package Limits

AGENT_BACKEND_BASE_URL