Dify Enterprise app deployment limits: what can be promoted and why it matters
Not every Dify app moves cleanly from a workspace into a production environment, and apps that depend on knowledge retrieval, agents or human input need deliberate design before promotion. A team that has built and tested an app in a workspace should treat promotion as a separate engineering step, not a copy operation. The first question is what actually travels. Dify's docs say an app exported as a YAML DSL file carries the app configuration, workflow nodes, model parameters, prompts and knowledge base connections. It does not carry third-party API keys, knowledge base content or usage logs. That split decides most of the work: the logic arrives, but every credential, document set and log history must be provisioned or rebuilt in the target environment.
Teams need this check whenever an app crosses an environment boundary, whether from a staging workspace to a production one or from a self-hosted instance to another. It is most important for apps that call external tools, rely on a populated knowledge base or pause for a person to approve output. In each case the imported app may look complete in the console while failing at runtime because a key is missing, an index is empty or a review step has no assigned reviewer. Before scheduling a promotion, confirm with your administrators which credentials and knowledge sources the target environment will hold, who owns each one, and how the knowledge base will be populated and refreshed. Check the exact list of nodes and integrations your app uses against the Dify docs for the version you run, because node behavior and supported integrations change between releases.
Which app types and nodes behave differently in deployed environments
Workflow apps run a defined graph of nodes from start to end, triggered by an API call or a user action. In a deployed environment, most of their dependencies sit outside the graph itself: model credentials for LLM nodes, the code sandbox for code nodes, and outbound network paths for HTTP and tool nodes.
- Model calls: Each LLM node resolves a model provider at run time, so the provider and its credential must exist in the target environment before the app is promoted.
- Code nodes: Code nodes run in the code sandbox. The Docker Compose deployment starts this as a separate service, so confirm it is healthy and reachable in every environment.
- HTTP and tool nodes: Outbound requests can pass through the SSRF proxy, which blocks internal and private IP ranges. Endpoints inside your network may be blocked unless you configure an allowed route.
- Variables and secrets: DSL exports carry the workflow structure and prompts but not third-party API keys, so each environment needs its own values.
Confirm node-level support for your Dify version in the App management docs and the release notes before you finalize the node list.
Chatflow apps handle multi-turn conversations, so they carry state between messages in addition to the node graph. That state, and the model calls made on each turn, shape the database capacity and the credentials the target environment needs.
- Conversation state: Conversation history and related records are stored by the platform, so the metadata database in each environment needs sizing, retention and backup decisions.
- Model credentials: Every model used in the chat flow must be configured for the workspace that runs it. A credential that works in staging does not transfer automatically.
- Retrieval nodes: If a chatflow queries a knowledge base, the knowledge base content is not included in the DSL export, so the target environment needs its own content.
- Usage records: Exports do not include usage logs, so token and call history stays with the source environment unless you export it separately.
Before promotion, run a representative conversation in the target environment and confirm that memory, model calls and any retrieval steps behave as they did in staging. Check the behavior against the version your environment runs.
Knowledge-backed apps depend on data that a DSL file does not carry. The app export keeps the knowledge base connection, but the documents, chunks and vector index belong to the environment where they were built, so a promoted app can point at an empty or mismatched knowledge base.
- Content transfer: Plan how documents and their indexes will be created or loaded in the target environment, and who approves that content before it is served.
- Vector store: The vector store defaults to Weaviate, and other options include Qdrant, Milvus, pgvector, OpenSearch and Elasticsearch. The target environment must run the same store type that the knowledge base expects.
- Embedding and rerank models: Retrieval depends on the embedding model used at index time and on any rerank model used at query time. Both need credentials in the target environment, and changing either may require re-indexing.
- File storage: Uploaded source files depend on the configured file storage backend, so confirm the target environment reads from the same storage type and location.
Ask the platform team to confirm the vector store, embedding model and file storage settings for each environment, then run retrieval tests on the promoted knowledge base. Compare results with the source environment before release.
Agent apps let the model choose tools and take multiple steps, so their runtime depends on tool credentials, sandboxed execution and network reach. Because the agent decides which tools to call, a permission gap in the target environment can appear only when a particular path runs.
- Sandbox network isolation: The Dify 1.16.1 release notes describe agent sandbox network isolation through a Squid proxy. Network rules that worked before an upgrade may behave differently afterward, so test sandbox egress in each environment.
- Tool credentials: Each tool needs its own credential in the target environment. Store these in the environment settings rather than in prompts or exported files.
- Service authentication: The 1.16.1 notes also describe token-based API authentication between services. Internal calls depend on this configuration being consistent across the deployment.
- Template rendering: Sandboxed Jinja2 template rendering was introduced in the same release, so templates that rely on unrestricted rendering need review.
- Cluster deployments: Enterprise deployments on Kubernetes may require additional sandbox setup. Confirm the requirements in your Enterprise documentation.
Review each tool the agent can call and test a run that exercises every tool path in the target environment. Confirm the sandbox and network behavior for your specific version in the release notes.
Apps that pause for human input hold a run open while a person reviews, approves or supplies information, then resume it. The pause depends on run state being kept safely, on the worker processes staying available, and on the right people reaching the app through their identity.
- Run state: A paused run must survive while it waits. Confirm how long paused runs persist, and what happens to them during restarts, upgrades or scaling events.
- Worker availability: Resumption depends on background workers. Include worker health in monitoring before any approval step goes into production.
- Reviewer access: Reviewers need web app access under the correct SSO scope. The Enterprise SSO documentation separates workspace access from web app access, so a reviewer with workspace access alone may not be able to act on the step.
- Notifications: If reviewers are alerted by email or another channel, the delivery settings are environment-specific and must be tested in the target environment.
Before promotion, pause and resume a test run in the target environment with a real reviewer identity from your directory. Confirm the pause and resume behavior in the App management docs for your version.
What must be redesigned before a retrieval, agent or human input app is promoted
Before a retrieval, agent or human input app goes to production, treat it as a set of references that must be rebuilt for the target environment, not as a copy. Knowledge base references and dataset IDs created in staging do not carry meaning in production, so each retrieval node must be re-pointed to a dataset the production workspace owns and can read. Confirm that the production environment can reach the same vector store and document sources the app expects, since a retrieval step that points at staging data or an unreachable index will return empty or stale results without an obvious error. Give each environment its own credentials and variables, including model keys and the SECRET_KEY value, so that a staging key never silently serves production traffic. Record which dataset, index and credential each environment uses in your release checklist so the promotion can be reviewed.
Agent apps need a network and sandbox review before promotion. The Dify 1.16.1 release notes describe agent sandbox network isolation through a Squid proxy and sandboxed Jinja2 template rendering, and your production controls should be checked against those behaviors rather than assumed. Confirm which outbound destinations the agent's tools need, whether the sandbox can reach them through the proxy, and whether any internal service the agent calls falls inside the private ranges that the SSRF proxy blocks. Plan the Kubernetes sandbox approval with your cluster administrators early, because the agent-sandbox controller is a dependency that the platform team, not the app owner, must approve. Human input steps need a named owner who receives the request, a documented timeout and a defined fallback, such as rejecting the action or escalating to a second approver. Test the timeout path in staging, because a paused workflow with no owner will otherwise stall silently.
Promotion options for each app pattern and when each fits
This table compares three ways to move a Dify app toward production: promote as-is, rebuild with environment-specific resources, or hold the app in staging until a prerequisite is met. Read each row against the app pattern you have, then check the owner and main risk before choosing a path. The main takeaway is that apps using knowledge retrieval, agents or human input need more planning than a simple DSL import.
| Promotion option | What carries over and what must be recreated | Main risk and owning team |
|---|---|---|
| Promote as-is (DSL export and import) | Carries app configuration, workflow nodes, model parameters, prompts and knowledge base connections. Recreate third-party API keys, knowledge base content and usage logs in the target environment. | Connections point at resources the target does not hold, so the app fails or uses the wrong data. Owned by the platform team with app owner sign-off. |
| Rebuild with environment-specific credentials and knowledge bases | Workflow logic is rebuilt or re-imported, then credentials, variables and knowledge bases are bound to production values. Documents are re-ingested into production stores. | Staging content or test credentials reach production, and retrieval quality differs from what was tested. Owned by the app team with data owners for the knowledge sources. |
| Hold agent apps in staging until the sandbox prerequisite is met | Agent configuration can be prepared and tested in staging, but production promotion waits until the required runtime is in place. Confirm the sandbox requirements in the sibling topic on the agent sandbox on Kubernetes. | Production launch slips, or the agent runs on an unapproved runtime. Owned by the platform team, with cluster administrators approving the infrastructure change. |
| Hold human-input apps until review ownership is defined | Workflow steps that pause for a person can be built and tested, but reviewers, notification routes and timeout behavior must be set in the target environment before launch. | Requests wait with no reviewer, or the wrong group approves. Owned by the business process owner, with the platform team confirming routing. |
| Hold knowledge retrieval apps for a data review | The workflow can move as-is, but the knowledge base must be rebuilt from approved sources, with access rules and retention checked for production data. | Restricted documents are indexed without approval, or citations point to outdated content. Owned by the data owner and the security team. |
| Keep app in staging when environment runtime is not ready | Apps stay in the staging environment until shared or isolated runtime settings, credentials and quotas are defined. See the sibling topic on staging and production environments. | Production traffic runs on shared resources that were never sized for it. Owned by the platform team with the organization's Enterprise administrators. |
| Rollback planning before any promotion | Record the previous app version and its bindings before promotion, so a rollback can restore a known state. Confirm rollback behavior in the sibling topic on staging and production environments. | A rollback restores the app but not the credentials or data it depended on. Owned by the platform team and the app owner together. |
How to check an app before promoting it to production
This sequence turns a staging app into a promotion decision: every node, integration and credential is accounted for, the exported DSL is understood, and the team knows how to roll back if production behaves differently.
Inventory every node and integration
Open the app in staging and list every node type in the workflow or agent graph, along with each knowledge retrieval node, tool node, agent node, human input node, code or template node and outbound HTTP call. Mark each item as runs as-is, needs redesign or needs a credential or connection in the target environment. The owner of the app signs off on this list. You know this step is done when every node on the canvas appears on the list and each one has a status, with no unlabeled items left.
Export the DSL and confirm its contents
Export the app as a YAML DSL file and open it in a text editor. Confirm that it holds the app configuration, workflow nodes, model parameters, prompts and knowledge base connections. Then confirm what it leaves out: third-party API keys, knowledge base content and usage logs. Check the file for any literal secret or internal hostname that should not travel, and record which values the target environment must supply. The check is complete when the team can name, for each missing item, where it will come from in production.
Recreate knowledge bases and model credentials
In the target environment, rebuild each knowledge base connection and attach model and tool credentials through the environment's own credential store rather than copying them from staging. Confirm that each knowledge base in production is populated from the approved source, and that embedding and rerank models are the ones the approved list names. You know this step is done when a test query against each retrieval node returns results from the production knowledge base and each model call succeeds with a production credential.
Run the app in staging with production-like controls
Run the app in staging under the same data controls production will use: the same data classification rules, the same sign-in path for users, and no real personal or confidential data unless your policy allows it in that environment. Run representative inputs, including adversarial ones, and capture outputs, errors and durations from the invocation logs. The check passes when results match the expected behavior and any failure has a documented fix or an accepted risk owner.
Confirm agent sandbox and outbound request paths
For apps that use agent or code nodes, confirm that the sandbox can run in the target cluster, including any cluster-admin approval it needs, and that the sandbox mode matches your security policy. Trace every outbound request the app makes, such as HTTP request nodes and tool calls, and confirm each one passes through the configured SSRF proxy and reaches only approved destinations. Document any destination that is blocked. You know this step is done when a test call to an internal address is refused and each approved external destination responds through the expected path.
Test human input pauses end to end
If the workflow has a human input node, run it from start to finish with the same roles and sign-in that production users will have. Pause at the input step, confirm that the reviewer receives the request, submit a response, and confirm the workflow resumes with the response in the expected variable. Also test what happens when no one responds, and record how the timeout or fallback behaves. The check is complete when the pause, resume and fallback paths have each been observed and written down by the tester.
Record the promotion and rollback plan
Write a promotion record that names the app version, the DSL file hash, the owner, the approver, the credentials and knowledge bases used in production, and the test results from the previous steps. Describe the rollback: which previous app version is restored, who can trigger it, and how the team confirms the rollback worked. Confirm that the rollback target is still available in the environment before the promotion starts. The step is done when the approver has signed the record and the rollback has been checked in the environment.
Security controls that shape what an app can do after promotion
These controls decide what a promoted app can reach, which secrets it depends on and who can move it into production. Each one changes a concrete setting that the promotion review should record, so the review covers configuration as well as the app's workflow.
SECRET_KEY and credential handling
The SECRET_KEY signs session cookies and JWTs and encrypts OAuth credentials, so changing it after deployment logs out all users. Treat it as a fixed value set during installation, stored in your secrets manager, and included in your restore procedure. Confirm that staging and production do not share it, and that a rotation plan exists before any promoted app depends on stored OAuth credentials.
SSRF proxy outbound filtering
The SSRF_PROXY settings route outbound requests from apps through a proxy that blocks internal and private IP ranges. A promoted app that calls an internal API, a private model endpoint or a file host on a private address will fail until that destination is reached through an approved route. Map every external call in the workflow, then confirm each one works in production without relaxing the proxy rules.
Workspace encryption key storage
Workspace encryption keys can be stored locally or in Azure Key Vault. The choice decides who can read the keys, how they are backed up and what happens when a workspace moves between environments. Record the storage location in the deployment design, confirm the production key store is separate from staging, and test that encrypted credentials still resolve after a restore.
Agent sandbox network isolation
Release 1.16.1 added agent sandbox network isolation through a Squid proxy. Agent apps run tool calls inside this sandbox, so their reachable network depends on the proxy policy rather than on the app's own settings. Before promoting an agent, list the hosts its tools must reach, confirm the proxy allows them, and review whether any tool expects direct access that the isolation now blocks.
Token-based service authentication
Release 1.16.1 also added token-based API authentication between Dify services. Internal calls between the api, worker and sandbox components now depend on tokens that operators must manage with the rest of the deployment configuration. Promotion does not change these tokens, but a mismatch after an upgrade can break promoted workflows. Include token configuration in the upgrade checklist and check it on staging before production.
Who may approve promotion
Promotion moves an app that may hold changed prompts, knowledge base links and credentials into production. Decide in advance which roles can approve a promotion, which of those roles must review the SSRF, sandbox and credential settings, and whether a second person must confirm. Write the approval rule into the change process and confirm that the Enterprise role model supports it before go-live.
Questions teams ask before promoting Dify apps to production
How much effort does promoting a Dify app to production take?
Effort depends on how much of the app relies on things that a DSL file does not carry. A simple chat app with a few nodes and one model credential is a small review. Effort rises with node count, since each branch must be tested in the target environment. It rises with knowledge base count, since each base must be reconnected and its content loaded separately. It also rises with agent use, because agent behavior and runtime settings must be checked on the target platform, and with human review steps, because someone must own the review queue and its timeouts. Ask any provider to size the work from a written inventory of apps, nodes, knowledge bases and integrations rather than from a headline app count.
Can our internal team promote Dify apps without outside help?
Yes, if the team can operate the deployment, administer the Dify Enterprise environments and own each app's business behavior. Internal teams usually handle simple promotions well. Gaps tend to appear in knowledge base rebuilding, secrets handling, outbound network rules for tools and test design for agent behavior. Check whether the people who will run promotion have access to both staging and production, can change environment variables and can read logs in both places. Decide who signs off on each release. A team that has not yet run a rollback should practice one in staging before its first production move, so the process is repeatable on every release.
What does promotion work require from our team?
Plan for environment access, named owners and test data before the work starts. Access means accounts on the source and target environments, read access to the cluster or host where Dify runs, and rights to change credentials and variables for each environment. Each app needs a business owner who accepts its behavior and a technical owner who maintains its nodes and prompts. Test data should resemble production in shape without exposing production records. Include sample documents for every knowledge base, plus scripted inputs for agent and human review paths. Confirm which of these exist today, because missing access often delays promotion more than the technical work does.
How long does promoting Dify apps take for different scopes?
Duration depends on scope, and the answer differs for each organization. The main drivers are the number of apps, the node count per app, whether knowledge bases must be rebuilt, whether agent apps need their runtime prepared on the cluster, how many integrations need new credentials and how many approval steps your change process requires. Re-indexing scales with document volume, so large knowledge bases can extend the schedule even when the app design is simple. Ask for a plan that lists each phase: inventory, redesign, staging tests, production cutover and rollback test. Each phase should name the person who approves it before the next one begins.
Does exporting a Dify app as DSL include knowledge base content?
No. A DSL export carries app configuration, workflow nodes, model parameters, prompts and knowledge base connections. It does not carry third-party API keys, knowledge base content or usage logs. An imported app may therefore point at knowledge bases that are empty or missing in the target environment, and each model and tool will need credentials configured there. Plan a separate path for documents: retrieve or re-ingest the source files, rebuild the indexes and check retrieval results against your test questions. Also review each exported file for secrets before it goes into version control. The app management docs describe the export format in more detail.
Do agent and human input apps need redesign before promotion?
Often yes, but confirm the exact limits for your Dify Enterprise version before finalizing the design. Agent apps depend on an agent runtime that must be available in the target environment, and on Kubernetes that can require cluster-level setup. Human input steps depend on a review path, notification routing and timeout behavior that must work outside the development environment. Knowledge retrieval apps depend on the vector store and indexes being present in production. Check the Enterprise documentation for each node type and integration your apps use. Treat any app with these features as a redesign candidate until its staging tests pass.
When is a partner worth bringing in for Dify app promotion?
A partner is worth considering when the portfolio is large, when apps depend on knowledge retrieval, agents or human input steps that need redesign, or when your team lacks capacity to run staging tests and cutover in parallel with its normal work. DeployOpen plans, implements, integrates, hardens and documents self-hosted platforms inside your own infrastructure. Most engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts, and the quote follows from that written scope. DeployOpen does not publish a price list. Ask any provider for named deliverables, the rollback test, the handover format and the support that follows go-live. Ongoing support is available as a retainer.
How DeployOpen scopes and delivers app promotion work
DeployOpen scopes app promotion work in writing before any build starts, because the decisions that matter sit upstream of the cutover. The first step is an app inventory covering every app intended for a deployed environment, with its type, its nodes, its knowledge base connections, any agent tools it calls, and every point where a human input step pauses a run. Each dependency is then classified as promotable as built, promotable after redesign, or not promotable in the target environment. Knowledge retrieval, agent and human-input designs usually land in the second or third group, so the written scope names those apps and states the redesign for each: which knowledge bases must be recreated on the target vector store and file storage, which agent tools must run through the agent sandbox, and where a human review step needs an owner and a channel outside the app. The client confirms the Enterprise version, the Kubernetes and database targets, and the exact Dify release each environment runs before the inventory is signed off, since those versions determine which behaviors can be tested.
Delivery follows that scope in order. Redesigned apps are validated in the staging environment with production-like credentials, variables and knowledge data, and the test evidence records each redesigned path, including the failure paths. Promotion to production is a separate, written step with a named approver, a cutover window and a rollback plan that restores the previous app version and the environment variables it depended on. DYSL exports are not a complete backup, because they omit third-party API keys, knowledge base content and usage logs, so the rollback plan names where those are held. Ongoing support is optional and sold as a retainer, typically covering upgrades, because each Dify minor release can change agent, sandbox and plugin behavior and needs its own regression pass against the inventory. DeployOpen works inside the client's own cloud accounts, data centers or air-gapped networks, and it prepares evidence for assessments without issuing audit reports or certifications, which remain the job of independent auditors and certification bodies.
