What a Dify migration involves
A Dify migration starts with YAML DSL export and import, but that step only moves app definitions. According to the Dify docs, exports carry app configuration, workflow nodes, model parameters, prompts and knowledge base connections. They do not carry third-party API keys, knowledge base document content or usage logs. Plan to re-enter every model provider credential and tool key on the target instance, re-upload or re-index every knowledge base source, and accept that run history stays behind in the source system.
Most moves are triggered by one of three situations: leaving Dify Cloud for data residency or direct control of the infrastructure, consolidating several Dify or other LLM tool instances into one environment, or porting flows from another tool. Each trigger changes the work. A cloud-to-self-hosted move is mostly a re-keying and re-indexing exercise. A consolidation may need workspace mapping and name conflict decisions. A port from another tool means redesigning prompts and node logic, because no export format carries them over directly.
A team that already runs Docker or Kubernetes and knows Dify well can often move a handful of simple apps itself. The work is mainly export, import, credential entry and testing. Larger app catalogs, many knowledge bases and sensitive credentials usually justify a fixed-scope partner engagement, since the risks sit in secret handling, re-indexing and verification rather than in the import itself. Ask any partner to state the app inventory, knowledge base count, credential list and acceptance tests in writing before work starts.
DSL import is the starting point, not the whole job. Before cutover, confirm the target version matches the source behavior, check that model providers and tools resolve on the new instance, rebuild each knowledge base and compare retrieval results on a fixed set of test questions, and check that app access and workspace roles match what users had before. Keep the source instance running until these checks pass.
What the migration work includes
The migration breaks into seven work packages, from inventory through cutover, and ends with a defined set of handover deliverables. Each package has a different owner and a different failure mode, so scope them separately in the written proposal.
Inventory of apps and dependencies
Every app, workflow, knowledge base, tool, model provider and user account is listed with its owner and its dependencies. This inventory sets the scope for every other package. Check that it covers apps shared across workspaces and apps that call Dify through the backend-as-a-service APIs, since those callers break silently if the endpoint or key changes.
DSL export and import
Apps are exported and imported as YAML DSL files, which carry app configuration, workflow nodes, model parameters, prompts and knowledge base connections. The DSL does not carry third-party API keys, knowledge base content or usage logs. Validate each imported app against its source, because references to knowledge bases and tools may need manual relinking after import.
Knowledge base rebuild
Knowledge base documents are not part of the export, so each knowledge base is rebuilt from its original sources. The team records which document sources are used, plus the chunking and indexing settings for each base. Retrieval results are compared before and after the rebuild, because a change in chunk size alters the answers the apps return.
Credential re-entry and register
Model provider keys and tool credentials are entered again in the target environment, and each one is recorded in a credential register with its owner, scope and rotation date. Use separate keys for the new environment where the provider supports it, and confirm the encryption setup for stored secrets before entering production keys.
Porting from other LLM tools
Prompts and flows from other tools are mapped node by node to Dify node types, such as LLM, knowledge retrieval, conditional and code nodes. Expect some logic to need redesign rather than a direct mapping. Record each mapping decision so that reviewers can trace why a node behaves differently from the original tool.
Testing against expected outputs
Each app is tested against outputs recorded from the source system, using the same inputs where possible. Agree in advance which differences are acceptable, such as wording variation, and which are failures, such as a missing tool call or a wrong knowledge base result. The test evidence is kept as a deliverable for the change record.
Cutover and rollback path
Cutover moves users and API callers to the self-hosted instance in a planned window, with the source system kept available for rollback. Confirm in writing who can trigger rollback, how API endpoints are switched back, and how data written during the window is handled. Take a backup of the target before cutover, as recommended before any Dify upgrade.
What drives migration effort
This table lists each driver of migration effort, why it changes the work and how to keep it down, and it assumes an app inventory with a stated expected output for every app before scoping starts.
| Driver | Why it matters | How to keep it down |
|---|---|---|
| Number of apps and workflows | Each app needs its own DSL import, configuration check and test pass, and node count sets how much verification each one needs. | Inventory every app with its owner and expected output before scoping. Retire unused apps first. |
| Knowledge bases and source documents | Document content is not exported, so each knowledge base is rebuilt from source files, and document volume drives indexing and checks. | Keep source files in a known location. Remove stale or duplicate documents before re-indexing. |
| Model providers and API keys | Keys are not exported and must be re-entered and tested for each provider in each workspace. | List every provider and key owner up front. Confirm which keys are valid for the new environment. |
| Custom tools and internal API integrations | Each integration needs a network path from the self-hosted stack, valid credentials and a fresh test run. | Document endpoints, authentication methods and network routes. Confirm reachability from the target network early. |
| Code nodes in the sandbox | Code nodes run in the sandbox, so libraries, timeouts and outbound calls must be checked against the target settings. | List imports and outbound calls for each code node. Test them in staging with the same sandbox settings. |
| Flows ported from other tools | Prompts and logic from other tools are rebuilt as Dify nodes, and outputs must be compared against the original behavior. | Map each source step to a Dify node. Agree on the expected output for each ported flow before rebuilding. |
| Environments (dev, test, production) | Each environment needs its own keys, storage, knowledge bases and DSL imports, so every extra environment repeats checks. | Agree on the fewest environments the team can run. Promote DSL files through one path with a written checklist. |
| Users, workspaces and access structure | Roles, workspace layout and web app access must be recreated. The Community edition is limited to a single workspace. | Map current roles to target roles. Decide the workspace count and confirm the edition before import. |
| Compliance evidence for cutover | Assessors may ask for configuration, access and backup records taken at cutover. Auditors issue assessment results, not DeployOpen. | Agree the evidence list with your assessor before cutover. Collect records during testing, not after go-live. |
Migration phases and outputs
The sequence moves each app, its data and its credentials onto a self-hosted Dify in a controlled order, and each phase closes with a record the team can check.
Inventory source apps and data
Your team lists every app, workflow, knowledge base, model provider, plugin and integration on the source platform, with its owner and active users. The output is an app inventory and a dependency map showing which API keys, external tools and documents each app relies on. The step is done when every app has a disposition: migrate, rebuild, retire or keep in place.
Design the target platform
Choose Docker Compose or Kubernetes, the metadata database (PostgreSQL is the default), file storage, the vector store and the Dify version to target. Check the prerequisites and the release notes for that version before committing. The output is a design record and a version decision that the owners sign off before any build starts.
Build the environment and secrets
Deploy the target Dify instance in your infrastructure and set SECRET_KEY, database and storage settings through your secrets store. Record SECRET_KEY before first use, since changing it after deployment logs out all users. The output is a build record and a secrets register, confirmed by a working administrator login and a passing health check.
Export, import and check DSL compatibility
Export each app as a YAML DSL file from the source and import it into the target workspace. Exports carry app configuration, workflow nodes, model parameters, prompts and knowledge base connections, but they exclude third-party API keys, knowledge base content and usage logs. The output is a compatibility report per app that lists nodes or settings needing manual edits on the target version.
Rebuild knowledge bases and re-enter credentials
Recreate each knowledge base on the target, upload the source documents again and re-index them with the chosen vector store and embedding settings. Re-enter each model provider and third-party API key through a controlled process, logging the owner and the date of each entry. The output is a knowledge base rebuild log and a credential register.
Port flows, test and pilot
Repair the prompts and workflows that failed the compatibility check, then run a test matrix covering each app, input type, tool call and knowledge base query. A pilot group of actual users then works in the target for a set period. The output is a test matrix with pass or fail results and a pilot feedback log that the owners review before cutover.
Cut over and decommission the source
Freeze changes on the source, run a final DSL and credential check, and switch users and API callers to the target using a cutover checklist. Confirm each integration responds, then keep the source read-only for the retention period your policy sets. The output is a signed cutover checklist and a decommissioning record with archived exports and logs.
Which parts stay in-house and which go to a partner
This table shows, for each part of a Dify migration, whether your team usually keeps it, a partner usually takes it, or both share it, along with the skills each part needs.
| Work part | Usually kept in-house | Usually outsourced | Skills needed |
|---|---|---|---|
| Inventory and business owner sign-off | Your team lists apps, owners, knowledge bases and model providers, and business owners approve what moves and what retires | Partner may draft the inventory template and run the discovery workshops | Business process knowledge, app ownership mapping, change approval |
| Target infrastructure build | Either: your platform team can build the hosts, network and storage | Either: a partner can build the Compose or Kubernetes stack in your accounts or data center | Docker or Kubernetes operations, PostgreSQL and object storage administration |
| DSL migration and knowledge base rebuild | Review of imported apps and sign-off on behavior | Often a partner for volume, since document content must be re-uploaded and re-indexed | Dify app editing, document ingestion, chunking and retrieval tuning |
| Credential handling and key storage | Owner of API keys, the SECRET_KEY and key storage decisions, who issues and rotates provider accounts | Partner supports secret rotation scripts, re-entry procedures and documentation | LLM provider accounts, security review, secrets management |
| Porting from other tools | Prompt and flow owners confirm intent and accept behavior changes | Partner when node mapping from another tool is non-trivial or needs custom code | Prompt and flow ownership, workflow design, source tool expertise |
| Testing and acceptance | Business owners run acceptance tests on real questions and sign off results | Partner writes test sets, compares outputs and records regressions | Prompt and flow ownership, evaluation design, security review of outputs |
| Cutover and decommissioning | Your owner schedules the switch, updates user links and retires the Dify Cloud workspace or old tool | Partner may prepare runbooks and rollback steps | Operations ownership, access control, LLM provider account administration |
What usually goes wrong and how to prevent it
Most failures in this move come from wrong assumptions about what a DSL export carries and how the target runtime enforces its rules. Each risk below has a prevention step to build into the scope before cutover.
Knowledge bases assumed to move
A DSL export keeps knowledge base connections but leaves out document content, so the target workspace starts with empty or missing indexes. Teams that treat the move as a file copy find this at cutover. Inventory each knowledge base, its source files and chunking settings, plan a re-ingestion step, and check retrieval answers against the source.
Keys and SECRET_KEY set late
Model provider and tool API keys are not in the export, so they get re-entered app by app, often after users have started testing. Keep a credential register that names each key, its owner and its target environment. Set SECRET_KEY once before the first login, because changing it after deployment logs out every user.
Version mismatch on import
A DSL written for one Dify release can contain settings or variables that another release reads differently or rejects. Pin the target version before scoping, read the release notes for each minor version between source and target, and test an import of every app on that exact build. Plan the upgrade path for later releases, which arrive roughly monthly.
Tools and code nodes in the sandbox
Tools that call internal systems can fail because the SSRF proxy blocks internal and private IP ranges by design. Code nodes run in the sandbox, which can behave differently from the source environment. Request an allowlist entry for each internal endpoint with its owner, then run every code node in the target with representative inputs before go-live.
Prompt output drift by model
A prompt tuned on one model provider or model version can return different wording, structure or refusals on another. Build a per-app test matrix that lists each prompt, model, version and the output checks it must pass, such as JSON shape and tool-call behavior. Rerun the matrix whenever the provider or model version changes.
Flows that stop at cutover
Undocumented automations, such as scheduled runs, webhooks or apps embedded in other tools, can stop when the source workspace is turned off. Inventory every trigger, endpoint and consumer before scoping, then run source and target in parallel for an agreed period while outputs are compared. Retire the source only after the comparison passes.
How the work changes by starting point
Moving from Dify Cloud is mostly a rebuild. Each app can be exported as a YAML DSL file that carries app configuration, workflow nodes, model parameters, prompts and knowledge base connections. Everything else must be recreated on the self-hosted instance.
- Re-enter API keys: exports do not include third-party API keys, so every model and tool credential is entered again.
- Rebuild knowledge bases: document content is not exported, so source files must be re-uploaded and indexed.
- Check connections: confirm each knowledge base reference points to a dataset that exists on the new instance.
- Review multi-tenant use: the Dify Open Source License prohibits running a multi-tenant environment, where one tenant is one workspace, without written authorization. Confirm the terms before you run one.
- Plan for usage history: usage logs are not part of the export, so decide whether any historical data must be kept elsewhere.
Moving between self-hosted Dify versions is mainly a planning exercise. The work depends on whether DSL files load cleanly on the target version and how the upgrade is sequenced.
- Confirm DSL compatibility: import a representative set of apps into a test instance running the target version.
- Read the release notes: cover every version between your current release and the target. For example, Dify 1.16.1 changed agent sandbox network isolation through a Squid proxy, token-based authentication between services and sandboxed Jinja2 template rendering, so agent apps and custom templates need testing.
- Back up before each step: take backups of the database, file storage and configuration before every upgrade.
- Compare environment variables: check .env.example for the target version and add any new variables to your configuration.
- Follow each upgrade guide: agree the version sequence with the team and follow the upgrade guide for each target release.
Porting from another LLM tool means translating its structure into Dify concepts before any content moves. Prompt rework usually takes the most effort, because each prompt must be adapted to Dify's variables, model settings and output handling.
- Map components first: build a table that maps each component of the source tool to a Dify workflow node, knowledge base or tool, and agree it with the application owner.
- Rebuild retrieval: recreate document pipelines as knowledge bases and set chunking and retrieval options again.
- Rewrite prompts: adapt each prompt in the prompt IDE, then test it against the same sample inputs used in the source tool.
- Rebuild integrations: move external calls into API-based or custom tools, with credentials stored in Dify.
- Document gaps: some logic may have no direct equivalent, so record how each gap is handled and who signed off on it.
Air-gapped and Kubernetes starts change delivery and storage decisions before any application work begins. Confirm each choice against the documentation for your target version.
- Deliver images and plugins: confirm how container images and plugins reach the isolated network, including the plugin daemon, and who maintains the internal copies for each update.
- Choose file storage: Dify supports OpenDAL, S3-compatible storage and other providers, so confirm which option your environment can operate and back up.
- Select the vector store: Weaviate is the default, with Qdrant, Milvus, pgvector, OpenSearch and Elasticsearch also supported. The choice affects import and retrieval testing.
- Confirm the edition for Kubernetes: the Enterprise checklist lists Kubernetes 1.24 or later, Helm 3.14 or later, PostgreSQL 14 or later, Redis 6 or later and a Qdrant cluster. Confirm with DeployOpen and the vendor which edition supports your high availability requirements.
- Re-test after the move: repeat DSL imports and model connections, since provider endpoints may need local addresses.
What you need to provide before the work starts
Before any migration work starts, your team has to hand over a defined set of inputs. The migration cannot be scoped or cut over without them, and the largest readiness gap we usually see is not technical: it is that no one owns each app. Assign one named business owner per app before the project begins, and make that person responsible for approving what the app should output.
On the source side, provide an account with owner rights on the Dify Cloud workspace, and an export of each app's YAML DSL file. DSL exports carry app configuration, workflow nodes, model parameters, prompts and knowledge base connections, but not third-party API keys, knowledge base documents or usage logs. Also provide a list of every app in use, with its owner, its users and its dependencies. For knowledge bases, supply the original source documents or their storage locations, since document content must be re-ingested on the new platform.
Next, build a register of model provider accounts and tool credentials, with the named owner of each. Each key will need to be re-entered in the self-hosted instance, so the owner must be able to rotate or reissue it. On the target side, confirm the infrastructure or cloud accounts, their access rules and who grants and reviews access. Decide the Dify version to deploy, the metadata database (PostgreSQL is the default, MySQL and OceanBase are listed as options), the vector store and the object storage provider before design starts, because each choice changes the build.
Finally, name the test users who will compare outputs against the source apps, and agree a cutover window with a named rollback owner who can make the call to revert. Confirm that test users can reach both environments during the parallel run. If you are migrating from another LLM tool rather than Dify Cloud, the same register applies, but expect to supply prompts and flow definitions in a readable form, since there is no DSL file to export. Confirm each item with your own owners and environment before the scope is agreed in writing.
Frequently asked questions
Does a Dify DSL export include knowledge bases and API keys?
No. A DSL file carries app configuration, workflow nodes, model parameters, prompts and knowledge base connections, but not third-party API keys, knowledge base content or usage logs. Plan to do three things by hand: re-enter every model provider and tool credential in the new workspace, re-upload or re-sync the source documents into new knowledge bases, and confirm each connection points to the right dataset after import. Ask your partner to list these items per app in the written scope.
What drives the effort of a Dify migration?
Effort follows the inventory: how many apps, how many workflows and nodes per app, how many knowledge bases and how large their source documents are, how many model providers and external tools each app calls, and how much output testing your owners require. Ask a partner to quote each of these separately, along with environment setup, test runs, cutover support and handover. A written scope should name which apps are in and which are out.
How long does a Dify migration take?
The duration depends on the inventory rather than on a standard number of days. A small set of apps without knowledge bases moves much faster than dozens of workflows backed by large document collections that must be re-indexed. Ask for a timeline tied to the agreed app list, with dependencies such as document access, credential approval and test sign-off marked as client-side tasks that can delay the schedule.
Can our own team migrate from Dify Cloud without a partner?
Yes, a capable team can export DSL files, import them into a self-hosted instance and rebuild knowledge bases itself. The work that usually needs experienced hands is the environment build, secrets handling, access design, backup setup and structured testing of outputs. Decide which of these your team will own before you start, and ask a partner to quote only the parts you choose to hand over.
Does migration keep prompts and flows exactly the same?
Migration preserves the exported configuration, including prompts, workflow nodes and model parameters. It does not guarantee identical output, because a different model provider, model version or retrieval setup can change responses. Test each app against its expected results on the new model setup before cutover, and record acceptance criteria in the scope. Prompts and flows from other LLM tools usually need manual porting and the same testing.
Do we need to upgrade Dify during the migration?
Not necessarily, but you should confirm the version before you import. Dify ships minor releases roughly monthly, and each release has its own upgrade guide, new .env variables and security changes. Read the release notes for the target version, take a backup before any upgrade, and check .env.example after upgrading. Ask your partner to state which Dify version the migration targets and how later upgrades are handled.
How DeployOpen scopes and delivers Dify migrations
DeployOpen moves Dify apps from Dify Cloud or other LLM tools into a self-hosted Dify that runs in infrastructure you control, treating exports, knowledge bases and credentials as separate workstreams. Each engagement is scoped in writing before work starts.
How we scope
- Inventory every Dify Cloud app, workflow and agent in scope, noting which ones depend on knowledge bases, plugins or custom tools.
- Record which model providers, API keys and external tools each app uses, so credentials can be re-entered securely on the new instance.
- Agree in writing which apps, knowledge bases and source tools are covered, plus the acceptance checks that close each migration item.
How we build
- Export apps as YAML DSL files and import them into the self-hosted instance, then review prompts, workflow nodes and model parameters for drift.
- Rebuild knowledge bases from the original source documents, since document content is not carried in the DSL export.
- Port prompts and flows from other LLM tools by mapping their logic to Dify workflow nodes, and test each ported app against recorded sample inputs.
How we hand over
- Deliver a migration log listing each app, its import status, rebuilt knowledge bases, re-entered credentials and open items.
- Document the deployment, environment settings and backup steps, so your team can repeat the process for future apps.
- Walk your operators through the running instance, including who holds credentials and where secrets are stored.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after the migration closes.
- Confirm with your team how you want to handle later Dify releases, which arrive roughly monthly, and how backups are taken before each upgrade.
- Ask for the support scope, response expectations and change process in the written quote before the engagement starts.
