{
  "schemaVersion": "1.0",
  "title": "Deploy the Dify connector",
  "description": "Use this guide to deploy one immutable aip-host-dify instance. The result is an admitted, observable route with durable cancellation evidence and a defined replacement and rollback path.",
  "canonical": "https://getaip.org/docs/connectors/dify/operations/deployment",
  "route": "/docs/connectors/dify/operations/deployment",
  "source": "docs/connectors/dify/operations/deployment.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/dify/operations/deployment.md",
    "txt": "/docs/download/connectors/dify/operations/deployment.txt",
    "json": "/docs/download/connectors/dify/operations/deployment.json",
    "pdf": "/docs/download/connectors/dify/operations/deployment.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Deploy the Dify connector\ndescription: >-\n  Deploy an immutable Dify host with scoped credentials, durable task state,\n  admission, readiness gates, and controlled rollback\nkind: how-to\naudience: operator\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: dify\naliases:\n  - Dify connector deployment\n  - Run aip-host-dify\n---\n\n# Deploy the Dify connector\n\nUse this guide to deploy one immutable `aip-host-dify` instance. The result is\nan admitted, observable route with durable cancellation evidence and a defined\nreplacement and rollback path.\n\nThe repository fleet stack is qualification evidence. It is not a production\ndeployment template.\n\n## Define the deployment boundary\n\nOne logical instance owns:\n\n- one admitted connector type and immutable version;\n- one tenant and membership;\n- one fixed Dify origin;\n- a reviewed set of app and Knowledge descriptors;\n- one scoped key source per provider credential;\n- one coherent durable host-state boundary;\n- one or more uniquely identified replicas;\n- a fixed native AIP endpoint per replica.\n\nThe process serves native AIP on `0.0.0.0:8081` by default. Its advertised\nendpoint must be an absolute HTTPS URL ending in `/aip/v1/messages`.\n\nKeep the native port behind the selected TLS edge. Only explicit loopback\ndevelopment may opt into HTTP.\n\n## Map topology ownership\n\n| Connection | Direction | Owner | Required protection |\n|---|---|---|---|\n| Gateway to Dify host | Inbound native AIP | AIP platform | TLS, signed envelopes, trusted gateway identity |\n| Lifecycle service to host | Inbound control | AIP platform | Fixed endpoint, DID verification, lease fencing |\n| Host to Dify | Outbound provider API | Connector operator | HTTPS origin, scoped bearer keys, no authenticated redirects |\n| Host to PostgreSQL | Durable runtime state | Connector operator | Dedicated URL file, migrations, backups |\n| Host to stream callback | Optional outbound publication | AIP platform | Fixed endpoint and explicit network policy |\n\nReplicas of one logical instance share the admitted version and coherent\ndurable state. Each replica retains its own replica ID and signing identity.\n\n## 1. Freeze the release unit\n\nRecord these values before provisioning:\n\n| Release evidence | Required value |\n|---|---|\n| AIP source revision | Exact commit |\n| Host image | Immutable OCI digest |\n| Workspace version | Version embedded in the artifact |\n| Connector type and version | Exact admitted identities |\n| Dify compatibility baseline | Exact reviewed provider revision |\n| Descriptor set | Hashes of public app and Knowledge files |\n| Manifest | Exact projected capability set and digest |\n| Configuration revision | Positive monotonic value |\n| Admission package | Signature bound to artifact and manifest |\n| Trust policy | Exact policy used for admission |\n\nDo not deploy from a mutable image tag alone. A descriptor ID or mode changes\nthe manifest, so it requires a new immutable version and admission package.\n\nThe source fleet preparation script records a source digest, image ID, release\nID, and release revision. Apply the same identity discipline to the actual\nrelease pipeline.\n\n## 2. Provision durable state\n\nPlace the owner-only PostgreSQL URL in the file referenced by:\n\n```text\nAIP_CONNECTOR_HOST_DATABASE_URL_FILE\n```\n\nThe prepared host uses durable state for Action handling, lifecycle recovery,\nprofile state, replay fencing, and stream publication. The Dify binary also\ninstalls `ProfileStateDifyTaskStore` after host preparation.\n\nThat task store maps AIP actions to remote task IDs under the logical instance\nscope. It preserves cancellation evidence across restart and replica handoff.\n\nAll replicas for one instance need the same storage authority. Process-local\ntask state is not a production substitute.\n\nMigrate and verify storage before a replica registers. Back up runtime and\nprofile state as one documented recovery unit.\n\n## 3. Place identity and trust material\n\nProvision the shared connector-host identity:\n\n- Dify connector type and immutable version IDs;\n- logical instance and unique replica IDs;\n- tenant and membership IDs;\n- artifact digest and public native endpoint;\n- trust domain, gateway identity, and control-plane identity;\n- replica signing seed file;\n- optional private-PKI root;\n- complete credential revision and policy fields when credential fencing is\n  enabled.\n\nSigning seeds, database URLs, Dify keys, and private CA material belong in\nowner-controlled files. Environment variables carry file paths and non-secret\nidentifiers.\n\nThe public endpoint, manifest, artifact, version, and signer must agree with\nthe admitted record.\n\n## 4. Configure the provider boundary\n\nSet one fixed Dify origin and at least one descriptor domain:\n\n```text\nAIP_DIFY_BASE_URL=https://dify.example.test\nAIP_DIFY_APPS_FILE=/run/config/dify-apps.json\nAIP_DIFY_KNOWLEDGE_FILE=/run/config/dify-knowledge.json\n```\n\nThe app file can use one owner-only key file per app. A legacy global app key\nis permitted only when all configured apps intentionally share it.\n\nEvery Knowledge descriptor requires its own workspace-scoped key file. The\nglobal app key never supplies Knowledge authorization.\n\nKeep key material out of descriptor files. Mount public descriptors read-only\nand secret files through a separate bounded secret path.\n\nAn optional external-account identity must include both ID and system. Define\nits deployment meaning because one host can contain several app and Knowledge\nidentities.\n\n## 5. Check manifest capacity\n\nCompute the exact manifest before admission:\n\n```text\nsum(per-app projected capabilities) + 46 × Knowledge credential count\n```\n\nDescriptor parser ceilings allow up to 1,000 apps and 1,000 Knowledge\ncredentials. Global manifest admission normally establishes a lower practical\nlimit.\n\nSplit logical instances before weakening admission bounds. Preserve unique\ndescriptor IDs and explicit tenant ownership across the split.\n\n## 6. Admit before starting\n\nApply the connector admission package and trust policy before the replica\nstarts. Admission must bind:\n\n- connector type and immutable version;\n- semantic manifest and capability identities;\n- artifact digest and provenance;\n- native and Dify profile support;\n- tenant and external-account policy;\n- public endpoint and lifecycle expectations.\n\nUse separate registry credentials for admission, lifecycle control, and\ndata-plane reads. The host does not need an administrator credential.\n\nThe reviewed fleet graph completes `admit-dify` before `dify-acme-a`. Preserve\nthat dependency even when production service names differ.\n\n## 7. Start dependencies in order\n\nUse this order:\n\n1. PostgreSQL and required migrations;\n2. connector registry and the admitted Dify version;\n3. control plane and trusted gateway;\n4. TLS edge and fixed internal routes;\n5. optional stream callback ingress;\n6. Dify provider reachability and credential files;\n7. the Dify host replica;\n8. lifecycle registration and lease renewal;\n9. readiness and safe canaries;\n10. production route enablement.\n\nStop when an earlier authority is unavailable. Never start with a temporary\nidentity, unadmitted version, mutable digest, or substitute provider origin.\n\n## 8. Gate readiness\n\nRequire all applicable signals:\n\n| Gate | Established fact |\n|---|---|\n| Process | Host server and local supervisor are running |\n| Durable store | Runtime and profile-state operations are available |\n| Admission | Type, version, instance, replica, artifact, and manifest match |\n| Lifecycle | Replica is registered, healthy, leased, and not draining |\n| App health | Each app key reads `/v1/parameters` |\n| Knowledge health | Each Knowledge key reads `/v1/datasets?limit=1` |\n| Route | Gateway resolves the admitted instance and replica |\n| Callback, when configured | Endpoint and network policy are valid |\n\nProduct health proves credential and route reachability at one moment. It does\nnot qualify every projected operation or verify the configured app mode.\n\n## 9. Run read-only canaries\n\nBefore admitting mutations:\n\n1. read the discovered manifest through the tenant route;\n2. compare exact IDs and expected capability counts;\n3. invoke one app `parameters.get` when apps are configured;\n4. invoke `dataset.list` when Knowledge is configured;\n5. retain Action, gateway, replica, and provider request identities;\n6. verify the intended tenant, descriptor, and key served each action.\n\nDo not use model execution, upload, indexing, deletion, training, or pipeline\nrun as the first deployment canary.\n\n## 10. Enable traffic gradually\n\nStart with a bounded tenant and capability subset. Observe admission,\ncompletion, provider authentication, response bounds, task-store health,\ncancellation certainty, and lifecycle leases.\n\nEnable mutations only after approval and idempotency paths are exercised with\ncontrolled data. Enable streaming after callback ownership and durable task\ncorrelation are proven.\n\nReadiness is necessary but does not establish rollout success.\n\n## Replace a replica\n\nFor a same-version replacement:\n\n1. provision a new replica ID and signer;\n2. use the same logical instance and coherent durable state;\n3. start it with byte-identical product configuration;\n4. wait for registration, lease, health, route, and canary gates;\n5. stop new assignments to the old replica;\n6. let pinned work settle within the drain boundary;\n7. mark the old replica offline and stop it;\n8. retain lifecycle and Action evidence.\n\nProduct configuration is startup-owned. A key, descriptor, origin, response\nlimit, or manifest change requires replacement rather than live mutation.\n\n## Roll back safely\n\nKeep the previous artifact, admission record, descriptors, credential revision,\nand compatibility decision until the new version clears its rollout window.\n\nRollback routes new work to a previously admitted compatible version. It does\nnot overwrite the failed version in place.\n\nPreserve durable Action state, idempotency records, task correlation, provider\nrequest identity, and pinned work. Never replay an ambiguous provider mutation\nunder a new Action ID.\n\n## Retain deployment evidence\n\nRetain:\n\n- source revision, image digest, SBOM, and provenance identity;\n- connector type, version, instance, replica, and tenant;\n- descriptor, manifest, and configuration hashes;\n- admission package and trust-policy identity;\n- credential revision without secret contents;\n- migration, startup, lease, health, route, and canary outcomes;\n- rollout, drain, replacement, rollback, and operator decisions.\n\nRedact provider payloads and never store key contents as evidence.\n\n## Completion criteria\n\nDeployment is complete only when:\n\n- immutable artifact and manifest identities match admission;\n- descriptors and keys have explicit least-privilege ownership;\n- durable runtime and task correlation survive replica replacement;\n- identity, control, gateway, TLS, and provider dependencies are healthy;\n- the replica holds a valid non-draining lease;\n- exact manifest and read-only canaries pass;\n- streaming has callback and cancellation ownership when enabled;\n- rollback material and procedures remain available;\n- no mutation substitutes for a safe deployment check.\n\nThese gates establish a controlled deployment. They do not qualify every Dify\ncapability against a production provider.\n\n## Related documentation\n\n- [Dify connector configuration](../reference/configuration.md)\n- [Run the Dify connector quickstart](../getting-started/quickstart.md)\n- [Production deployment](../../../guides/production-deployment.md)\n- [Deploy the connector fleet](../../../guides/deploy-connector-fleet.md)\n- [Connector host lifecycle](../../../guides/connector-host-lifecycle.md)\n",
    "text": "Deploy the Dify connector\n\nUse this guide to deploy one immutable aip-host-dify instance. The result is\nan admitted, observable route with durable cancellation evidence and a defined\nreplacement and rollback path.\n\nThe repository fleet stack is qualification evidence. It is not a production\ndeployment template.\n\nDefine the deployment boundary\n\nOne logical instance owns:\n• one admitted connector type and immutable version;\n• one tenant and membership;\n• one fixed Dify origin;\n• a reviewed set of app and Knowledge descriptors;\n• one scoped key source per provider credential;\n• one coherent durable host-state boundary;\n• one or more uniquely identified replicas;\n• a fixed native AIP endpoint per replica.\n\nThe process serves native AIP on 0.0.0.0:8081 by default. Its advertised\nendpoint must be an absolute HTTPS URL ending in /aip/v1/messages.\n\nKeep the native port behind the selected TLS edge. Only explicit loopback\ndevelopment may opt into HTTP.\n\nMap topology ownership\n\n| Connection | Direction | Owner | Required protection |\n\n| Gateway to Dify host | Inbound native AIP | AIP platform | TLS, signed envelopes, trusted gateway identity |\n| Lifecycle service to host | Inbound control | AIP platform | Fixed endpoint, DID verification, lease fencing |\n| Host to Dify | Outbound provider API | Connector operator | HTTPS origin, scoped bearer keys, no authenticated redirects |\n| Host to PostgreSQL | Durable runtime state | Connector operator | Dedicated URL file, migrations, backups |\n| Host to stream callback | Optional outbound publication | AIP platform | Fixed endpoint and explicit network policy |\n\nReplicas of one logical instance share the admitted version and coherent\ndurable state. Each replica retains its own replica ID and signing identity.\n1. Freeze the release unit\n\nRecord these values before provisioning:\n\n| Release evidence | Required value |\n\n| AIP source revision | Exact commit |\n| Host image | Immutable OCI digest |\n| Workspace version | Version embedded in the artifact |\n| Connector type and version | Exact admitted identities |\n| Dify compatibility baseline | Exact reviewed provider revision |\n| Descriptor set | Hashes of public app and Knowledge files |\n| Manifest | Exact projected capability set and digest |\n| Configuration revision | Positive monotonic value |\n| Admission package | Signature bound to artifact and manifest |\n| Trust policy | Exact policy used for admission |\n\nDo not deploy from a mutable image tag alone. A descriptor ID or mode changes\nthe manifest, so it requires a new immutable version and admission package.\n\nThe source fleet preparation script records a source digest, image ID, release\nID, and release revision. Apply the same identity discipline to the actual\nrelease pipeline.\n2. Provision durable state\n\nPlace the owner-only PostgreSQL URL in the file referenced by:\n\nAIPCONNECTORHOSTDATABASEURLFILE\n\nThe prepared host uses durable state for Action handling, lifecycle recovery,\nprofile state, replay fencing, and stream publication. The Dify binary also\ninstalls ProfileStateDifyTaskStore after host preparation.\n\nThat task store maps AIP actions to remote task IDs under the logical instance\nscope. It preserves cancellation evidence across restart and replica handoff.\n\nAll replicas for one instance need the same storage authority. Process-local\ntask state is not a production substitute.\n\nMigrate and verify storage before a replica registers. Back up runtime and\nprofile state as one documented recovery unit.\n3. Place identity and trust material\n\nProvision the shared connector-host identity:\n• Dify connector type and immutable version IDs;\n• logical instance and unique replica IDs;\n• tenant and membership IDs;\n• artifact digest and public native endpoint;\n• trust domain, gateway identity, and control-plane identity;\n• replica signing seed file;\n• optional private-PKI root;\n• complete credential revision and policy fields when credential fencing is\n  enabled.\n\nSigning seeds, database URLs, Dify keys, and private CA material belong in\nowner-controlled files. Environment variables carry file paths and non-secret\nidentifiers.\n\nThe public endpoint, manifest, artifact, version, and signer must agree with\nthe admitted record.\n4. Configure the provider boundary\n\nSet one fixed Dify origin and at least one descriptor domain:\n\nAIPDIFYBASEURL=https://dify.example.test\nAIPDIFYAPPSFILE=/run/config/dify-apps.json\nAIPDIFYKNOWLEDGEFILE=/run/config/dify-knowledge.json\n\nThe app file can use one owner-only key file per app. A legacy global app key\nis permitted only when all configured apps intentionally share it.\n\nEvery Knowledge descriptor requires its own workspace-scoped key file. The\nglobal app key never supplies Knowledge authorization.\n\nKeep key material out of descriptor files. Mount public descriptors read-only\nand secret files through a separate bounded secret path.\n\nAn optional external-account identity must include both ID and system. Define\nits deployment meaning because one host can contain several app and Knowledge\nidentities.\n5. Check manifest capacity\n\nCompute the exact manifest before admission:\n\nsum(per-app projected capabilities) + 46 × Knowledge credential count\n\nDescriptor parser ceilings allow up to 1,000 apps and 1,000 Knowledge\ncredentials. Global manifest admission normally establishes a lower practical\nlimit.\n\nSplit logical instances before weakening admission bounds. Preserve unique\ndescriptor IDs and explicit tenant ownership across the split.\n6. Admit before starting\n\nApply the connector admission package and trust policy before the replica\nstarts. Admission must bind:\n• connector type and immutable version;\n• semantic manifest and capability identities;\n• artifact digest and provenance;\n• native and Dify profile support;\n• tenant and external-account policy;\n• public endpoint and lifecycle expectations.\n\nUse separate registry credentials for admission, lifecycle control, and\ndata-plane reads. The host does not need an administrator credential.\n\nThe reviewed fleet graph completes admit-dify before dify-acme-a. Preserve\nthat dependency even when production service names differ.\n7. Start dependencies in order\n\nUse this order:\n1. PostgreSQL and required migrations;\n2. connector registry and the admitted Dify version;\n3. control plane and trusted gateway;\n4. TLS edge and fixed internal routes;\n5. optional stream callback ingress;\n6. Dify provider reachability and credential files;\n7. the Dify host replica;\n8. lifecycle registration and lease renewal;\n9. readiness and safe canaries;\n10. production route enablement.\n\nStop when an earlier authority is unavailable. Never start with a temporary\nidentity, unadmitted version, mutable digest, or substitute provider origin.\n8. Gate readiness\n\nRequire all applicable signals:\n\n| Gate | Established fact |\n\n| Process | Host server and local supervisor are running |\n| Durable store | Runtime and profile-state operations are available |\n| Admission | Type, version, instance, replica, artifact, and manifest match |\n| Lifecycle | Replica is registered, healthy, leased, and not draining |\n| App health | Each app key reads /v1/parameters |\n| Knowledge health | Each Knowledge key reads /v1/datasets?limit=1 |\n| Route | Gateway resolves the admitted instance and replica |\n| Callback, when configured | Endpoint and network policy are valid |\n\nProduct health proves credential and route reachability at one moment. It does\nnot qualify every projected operation or verify the configured app mode.\n9. Run read-only canaries\n\nBefore admitting mutations:\n1. read the discovered manifest through the tenant route;\n2. compare exact IDs and expected capability counts;\n3. invoke one app parameters.get when apps are configured;\n4. invoke dataset.list when Knowledge is configured;\n5. retain Action, gateway, replica, and provider request identities;\n6. verify the intended tenant, descriptor, and key served each action.\n\nDo not use model execution, upload, indexing, deletion, training, or pipeline\nrun as the first deployment canary.\n10. Enable traffic gradually\n\nStart with a bounded tenant and capability subset. Observe admission,\ncompletion, provider authentication, response bounds, task-store health,\ncancellation certainty, and lifecycle leases.\n\nEnable mutations only after approval and idempotency paths are exercised with\ncontrolled data. Enable streaming after callback ownership and durable task\ncorrelation are proven.\n\nReadiness is necessary but does not establish rollout success.\n\nReplace a replica\n\nFor a same-version replacement:\n1. provision a new replica ID and signer;\n2. use the same logical instance and coherent durable state;\n3. start it with byte-identical product configuration;\n4. wait for registration, lease, health, route, and canary gates;\n5. stop new assignments to the old replica;\n6. let pinned work settle within the drain boundary;\n7. mark the old replica offline and stop it;\n8. retain lifecycle and Action evidence.\n\nProduct configuration is startup-owned. A key, descriptor, origin, response\nlimit, or manifest change requires replacement rather than live mutation.\n\nRoll back safely\n\nKeep the previous artifact, admission record, descriptors, credential revision,\nand compatibility decision until the new version clears its rollout window.\n\nRollback routes new work to a previously admitted compatible version. It does\nnot overwrite the failed version in place.\n\nPreserve durable Action state, idempotency records, task correlation, provider\nrequest identity, and pinned work. Never replay an ambiguous provider mutation\nunder a new Action ID.\n\nRetain deployment evidence\n\nRetain:\n• source revision, image digest, SBOM, and provenance identity;\n• connector type, version, instance, replica, and tenant;\n• descriptor, manifest, and configuration hashes;\n• admission package and trust-policy identity;\n• credential revision without secret contents;\n• migration, startup, lease, health, route, and canary outcomes;\n• rollout, drain, replacement, rollback, and operator decisions.\n\nRedact provider payloads and never store key contents as evidence.\n\nCompletion criteria\n\nDeployment is complete only when:\n• immutable artifact and manifest identities match admission;\n• descriptors and keys have explicit least-privilege ownership;\n• durable runtime and task correlation survive replica replacement;\n• identity, control, gateway, TLS, and provider dependencies are healthy;\n• the replica holds a valid non-draining lease;\n• exact manifest and read-only canaries pass;\n• streaming has callback and cancellation ownership when enabled;\n• rollback material and procedures remain available;\n• no mutation substitutes for a safe deployment check.\n\nThese gates establish a controlled deployment. They do not qualify every Dify\ncapability against a production provider.\n\nRelated documentation\n• Dify connector configuration (../reference/configuration.md)\n• Run the Dify connector quickstart (../getting-started/quickstart.md)\n• Production deployment (../../../guides/production-deployment.md)\n• Deploy the connector fleet (../../../guides/deploy-connector-fleet.md)\n• Connector host lifecycle (../../../guides/connector-host-lifecycle.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "1cfe0dcb732c49e7f470a665ed02912872f47c1e915c52e6fe68f31299900373"
  }
}