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 fromdocker/.env.example..defaultsfiles underdocker/envs/: the bundled defaults, which services load automatically. Leave them unedited: each release ships new versions of them.- Local
.envfiles underdocker/envs/: your overrides for the services that load them. Git ignores them, so checking out a new release leaves them in place.
api/.env, web/.env.local, and docker/middleware.env for the middleware containers.
Set a Variable
Find the File
.env file under docker/envs/, and these two kinds in docker/.env:- Settings Compose reads before it loads any service file, such as
COMPOSE_PROFILESandVECTOR_STORE. - Shared credentials, so every service that uses one gets the same value:
PLUGIN_DAEMON_KEYandPLUGIN_DIFY_INNER_API_KEY: use a different strong value for each.DIFY_AGENT_API_TOKENandDIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN: use a different strong value for each.SANDBOX_API_KEYandCODE_EXECUTION_API_KEY: set both to the same value; if they differ, Code and Template nodes fail with HTTP 401.
docker/envs/ for its name, then act on what the search finds:- One
.defaultsfile: edit the local file named in its first comment. If that file doesn’t exist yet, copy the.defaultsfile to that name first. - Several
.defaultsfiles: edit the local file that every service using the variable loads; otherwise the services end up with different values. - An
.env.exampletemplate, such asenvs/security.env.example: copy it to the same name without.example. Skipenvs/middleware.env.example, which only the separate middleware stack for source-code development reads.
docker/.env and a local file set the same variable, the docker/.env value wins, with the exceptions in Precedence.Edit the Value
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
dify/docker, validate the configuration and recreate the affected containers:-p, -f, --env-file, or profiles, add the same options to these commands.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 loadsdocker/.env:
- Services That Load docker/.env
- Other Services
docker/.env- For the public URLs, in the web service, API, and workers: the values you set in
envs/core-services/urls.env - The service’s local
.envfiles - Its
.defaultsfiles - The application default
.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.- A variable exported in the shell where you run Compose, which wins over
docker/.envfor${...}values - The service’s
environment:entry in the Compose file, such asMODE: api, which wins over every env file
Common Variables
The public URLs are empty by default. Whether to set them depends on your deployment:- Everything runs at one address, with no emails, OAuth, or Human Input requests: leave them empty. Dify works without them.
- Everything runs at one address, with emails, OAuth, or Human Input requests: set them all to that full address, such as
https://dify.example.com. See each URL’s entry below for the features that need it. - Services run at separate addresses, such as the API at
api.example.com: set each URL to its own full address. If the console and the API are on different subdomains, also setCOOKIE_DOMAINandNEXT_PUBLIC_COOKIE_DOMAIN; see CORS Configuration for details.
-
If
docker/envs/core-services/urls.envdoesn’t exist, create it from the bundled defaults. The web service, API, and Celery workers all load this file, so they use the same addresses. -
In
urls.env, write each URL withhttp://orhttps://, plus the port if your address has one, such ashttps://dify.example.com:8443. Don’t add/console/api,/api, or/v1at the end: Dify appends them automatically. Ifdocker/.envalso sets any of these URLs, that value wins overurls.env, so change or remove it there. - Apply the change with the commands in Set a Variable.
-
To check the result, open the console and a published app at their public addresses. If you set the URLs for emails, also send a member invitation and check that its link starts with your address.
If an address is still wrong, run
docker compose configto see the value each service receives. Its output contains secrets, so keep it private.
CONSOLE_API_URL
Default: (empty) The public base URL of the console API. Set a full address for GitHub or Google login and for integrations that connect through OAuth. Secure cookies require bothCONSOLE_API_URL and CONSOLE_WEB_URL to start with https://.
Example: https://api.console.dify.ai
SERVER_CONSOLE_API_URL
Default:http://api:5001
The console API address the web service uses for server-side requests; browser requests use CONSOLE_API_URL. Set it in docker/envs/core-services/web.env if the API is reachable at a different internal address.
In a source-code deployment, it falls back to CONSOLE_API_URL when unset.
CONSOLE_WEB_URL
Default: (empty) The public base URL of the console. Set a full address for email links (such as invitation and sign-in links) and for redirects after OAuth login. Required for the new Human Input node’s requests to workspace members, sent by email or as link messages in IM (instant messaging app). The address doesn’t need to be reachable from the internet if members use Dify on an internal network. Example:https://console.dify.ai
SERVICE_API_URL
Default: (empty) The public API base URL shown in the console for developers to copy. Dify appends/v1 to this value. When empty, the console shows the address it’s opened at, such as http://localhost/v1.
If your server is reachable at several addresses, such as an IP address and a domain, set this to the one developers should use.
Example: https://api.dify.ai
APP_API_URL
Default: (empty) The public API base URL used by published web apps. When empty, a web app sends requests to/api at the address it’s opened at.
Example: https://api.app.dify.ai
APP_WEB_URL
Default: (empty) The public base URL of published web apps. When empty, the console builds an app’s sharing link from the address it’s opened at. Set a full address for Human Input requests sent by email or to external contacts. Recipients must be able to open this address. 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.
IMs that show Human Input requests as cards send button clicks to this address too, through the Callback URL in Settings > Channels.
FILES_URL
Default: (empty; falls back toCONSOLE_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 toFILES_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
Server Configuration
Logging
General
SECRET_KEY
Default: (empty; generated and saved in configured storage) Signs authentication tokens and file URLs, verifies personal access tokens, 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:
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: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.
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-passwordin 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_LOGINis 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 theSTORAGE_TYPEbackend. -
azure-keyvault: keeps each workspace’s RSA key in Azure Key Vault instead, so the private key never leaves the vault; Dify authenticates withDefaultAzureCredential(managed identity, environment variables, or Azure CLI login).
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
Container Startup Configuration
Only effective when starting with Docker image or Docker Compose.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 serverworker: the Celery task consumerbeat: the scheduled-task dispatcherjob: run one Flask CLI command, then exitmigration: withMIGRATION_ENABLED=true, migrate the database and exit
API Tool Configuration
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 indocker/.env:
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.
Connection Pool
These control how Dify manages its pool of database connections. The defaults work well for most deployments.PostgreSQL Performance Tuning
These are passed as startup arguments to the PostgreSQL container—they configure the database server, not the Dify application.MySQL Performance Tuning
These are passed as startup arguments to the MySQL container—they configure the database server, not the Dify application.Redis Configuration
Configure these to connect Dify to your Redis instance. Dify supports three deployment modes: standalone (default), Sentinel, and Cluster.Redis SSL Configuration
Only applies whenREDIS_USE_SSL=true. These same settings are also used by the Celery broker when its URL uses the rediss:// scheme.
Redis Sentinel Mode
Sentinel provides automatic master discovery and failover for high availability. Mutually exclusive with Cluster mode.Redis Cluster Mode
Cluster mode provides automatic sharding across multiple Redis nodes. Mutually exclusive with Sentinel mode.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.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:
CORS Configuration
Controls cross-domain access policies for the frontend.Dify CLI and Programmatic API
The Dify CLI (difyctl) and personal access tokens are on by default. To turn both off, set OPENAPI_ENABLED to false.
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)
OpenDAL (Default)
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.fs scheme:S3
S3
Azure Blob
Azure Blob
Google Cloud Storage
Google Cloud Storage
Alibaba Cloud OSS
Alibaba Cloud OSS
Tencent Cloud COS
Tencent Cloud COS
OCI Object Storage
OCI Object Storage
Huawei OBS
Huawei OBS
Volcengine TOS
Volcengine TOS
Baidu OBS
Baidu OBS
Supabase
Supabase
ClickZetta Volume
ClickZetta Volume
CLICKZETTA_* connection parameters configured in the Vector Database section.Archive Storage
Separate S3-compatible storage for archiving workflow run logs. Thearchive-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.
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
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
docker/.env, set VECTOR_STORE and add the provider’s profile to COMPOSE_PROFILES, then run docker compose up -d.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.
Weaviate
Weaviate
OceanBase / seekdb
OceanBase / seekdb
OCEANBASE_* variables. Set VECTOR_STORE to oceanbase or seekdb to load that provider’s connection defaults.Qdrant
Qdrant
Milvus
Milvus
MyScale
MyScale
Couchbase
Couchbase
Hologres
Hologres
PGVector
PGVector
Vastbase
Vastbase
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.PGVecto.RS
PGVecto.RS
AnalyticDB
AnalyticDB
TiDB Vector
TiDB Vector
MatrixOne
MatrixOne
Chroma
Chroma
Oracle
Oracle
AlibabaCloud MySQL
AlibabaCloud MySQL
Relyt
Relyt
OpenSearch
OpenSearch
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.Tencent Cloud VectorDB
Tencent Cloud VectorDB
Elasticsearch
Elasticsearch
VECTOR_STORE=elasticsearch and VECTOR_STORE=elasticsearch-ja, customize the connection in envs/vectorstores/elasticsearch.env, copied from elasticsearch.defaults.Baidu Vector DB
Baidu Vector DB
VikingDB
VikingDB
Lindorm
Lindorm
OpenGauss
OpenGauss
Huawei Cloud Search
Huawei Cloud Search
Upstash Vector
Upstash Vector
TableStore
TableStore
ClickZetta
ClickZetta
InterSystems IRIS
InterSystems IRIS
Knowledge Configuration
File Security Scan
To let knowledge bases scan uploaded files for malware, setFILE_SCAN_ENABLED to true. On Docker Compose, set this section’s variables in docker/envs/core-services/api-worker.env, which both the API and the worker load.
To reach a scanner on a private address, such as a Custom Endpoint, also let it through the SSRF proxy with SSRF_PROXY_ALLOW_PRIVATE_IPS or SSRF_PROXY_ALLOW_PRIVATE_DOMAINS. For https, the proxy allows only port 443.
Once the variables are set, add a scanner and turn on scanning in the knowledge bases that need it. See Scan Uploaded Files for Malware for the steps.
Annotation Import
Model Configuration
Multi-modal Configuration
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.Notion Integration Configuration
Connect Dify to Notion as a knowledge base data source. Get integration credentials at https://www.notion.so/my-integrations.Mail Configuration
Dify sends emails for account invitations, password resets, login codes, and Human Input requests. Configure one of the three supported providers. Links in these emails are built fromCONSOLE_WEB_URL and APP_WEB_URL, so set those too.
Resend
Resend
SMTP
SMTP
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).SendGrid
SendGrid
Other Configuration
Console Features
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.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 indocker/envs/core-services/api-worker.env.
Indexing
New User Defaults
Workflow Generation
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.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.Code and Template Output Limits
The API and worker processes apply these limits to the output returned by Code and Template nodes; set them inenvs/core-services/api-worker.env. The sandbox service doesn’t read them.
Workflow Runtime
Workflow Storage Repository
These select which backend implementation handles workflow execution data. The defaultSQLAlchemy repositories store everything in the database. Alternative implementations (e.g., Celery, Logstore) can be used for different storage strategies.
Workflow Log Cleanup
HTTP Request Node
These configure the HTTP Request node used in workflows to call external APIs.Webhook
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.Agent Configuration
HUMAN_INPUT_GLOBAL_TIMEOUT_SECONDS
Default:604800 (7 days)
How long, in seconds, a workflow run can wait for people before Dify stops it.
How the time is counted depends on the node:
- New Human Input node: from when the run started, shared by every Human Input node in the run. A change applies to requests created after it.
- Old Human Input node: from when each form was created, separately for each node. A change also applies to forms already waiting.
0 or an empty value keeps the API, worker, and beat services from starting.
Web Frontend Service
These variables are used by the Next.js web frontend container only, and do not affect the Python backend.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.
NEXT_PUBLIC_ENABLE_HITL_IM
Default:true
Set to false to turn off the new Human Input node, along with Contacts and Channels. While it’s on, workspace owners and admins see Contacts in the main navigation and Channels in Settings.
The new Human Input node also needs:
CONSOLE_WEB_URLandAPP_WEB_URLset to addresses recipients can open- Mail configured, for requests by email
TRIGGER_URLset to an address your IM can reach, for IMs that show requests as cards
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 withdocker 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: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 indocker/.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 defaultlocal 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:
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:
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:
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_LIMITfails the whole import. A skill over aSKILL_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.
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.
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. Agents don’t keep files or installed tools across conversations. Apply in a build chat still saves the agent’s configuration, including files added in the configuration panel.
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
E2B
docker/docker-compose.e2b.yaml overlay is for testing E2B with a separate, empty PostgreSQL volume; don’t apply it to an existing deployment.OpenShell
OpenShell
openshell, have these in place:-
An OpenShell gateway, version 0.1.3 or later, with its gRPC endpoint reachable from the
agent_backendcontainer. -
Service addresses on the gateway that the
agent_backendcontainer can reach. The agent backend sends the agent’s commands to each sandbox over HTTP, through an address the gateway returns for that sandbox, rather than through the gRPC endpoint. With Docker Compose, have the gateway hand outhttpsaddresses whose names resolve from the container. Plainhttpaddresses don’t work with Docker Compose: the agent backend accepts them only for loopback and*.openshell.localhost, which point at its own container. The container must reach these addresses directly: the agent backend ignoresHTTP_PROXYandHTTPS_PROXYfor this traffic. -
Gateway credentials: a bearer token, an mTLS client certificate pair, or both. Compose ships no certificate mount, so mount the files into
agent_backendyourself, read-only and readable by UID 1001. - A runtime image that the gateway can start sandboxes from.
-
A network path from the sandboxes back to Dify:
- Callback addresses the sandboxes can reach.
- A route to the agent backend’s
/agent-stubpath, kept at that path: ifDIFY_AGENT_STUB_API_BASE_URLhas any other path, the agent backend won’t start. 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.
- Follow the OpenShell setup guide to set up the gateway and everything above, including the
httpsservice domain behind the service addresses, the runtime image build, and the certificate mounts. - In
envs/core-services/dify-agent.env, setDIFY_AGENT_RUNTIME_BACKENDtoopenshelland 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. A wrong endpoint, credential, image, gateway version, or service address therefore shows up only then, as a failed run or a failed Apply.
DIFY_AGENT_OPENSHELL_EGRESS_ALLOW.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 asdify.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, setDIFY_AGENT_TRAJECTORY_ENABLEDtotrueandDIFY_AGENT_TRAJECTORY_OTLP_TRACES_ENDPOINTto your collector’s traces URL. Put any credentials inDIFY_AGENT_TRAJECTORY_OTLP_HEADERS. These variables have no effect inapi-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.
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 itsmiddleware.env; the full Compose stack keeps those services on an internal network.
Sandbox Service
Thesandbox 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.
Nginx Reverse Proxy
CONSOLE_API_URL, CONSOLE_WEB_URL) to use https://.Certbot Configuration
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.
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.Docker Compose
Keep Compose settings indocker/.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.
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.Plugin Daemon Configuration
The plugin daemon is a separate service that manages plugin lifecycle (installation, execution, upgrades). The API communicates with it via HTTP.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.
OTLP / OpenTelemetry Configuration
OpenTelemetry provides distributed tracing and metrics collection. When enabled, Dify instruments Flask and exports telemetry data to an OTLP collector.Miscellaneous
Scheduled Tasks Configuration
Dify uses Celery Beat to run background maintenance tasks on configurable schedules.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.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.Event Bus Configuration
Redis-based event transport between API and Celery workers.Vector Database Service Configuration
These variables configure the vector database containers themselves.Weaviate Service
Weaviate Service
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.Milvus Service (ETCD + MinIO)
Milvus Service (ETCD + MinIO)
OpenSearch Service
OpenSearch Service
OPENSEARCH_MEMLOCK_* and OPENSEARCH_NOFILE_* in docker/.env: Compose reads them before it loads service files.Qdrant Service
Qdrant Service
docker/.env: Compose reads them before it loads service files.PGVector / PGVecto.RS Service
PGVector / PGVecto.RS Service
Oracle / Chroma / Elasticsearch Services
Oracle / Chroma / Elasticsearch Services
IRIS / Other Services
IRIS / Other Services
Plugin Daemon Storage Configuration
The plugin daemon can store plugin packages in different storage backends. Configure only the provider matchingPLUGIN_STORAGE_TYPE.
Plugin S3 Storage
Plugin S3 Storage
Plugin Azure Blob Storage
Plugin Azure Blob Storage
Plugin Tencent COS Storage
Plugin Tencent COS Storage
Plugin Aliyun OSS Storage
Plugin Aliyun OSS Storage
Plugin Volcengine TOS Storage
Plugin Volcengine TOS Storage