Dify connector configuration

This reference describes the product settings accepted by aip-host-dify at the reviewed source revision. A complete process combines these settings with the shared connector-host identity, storage, routing, signing, lifecycle, and optional stream-callback settings.

All Dify product settings and key files are read at startup. Only the shared non-secret credential-revision policy is re-read before provider side effects.

Configuration identity

Environment variables and flags contain non-secret values or file paths. API keys, database credentials, and signing seeds belong in bounded owner-controlled files.

Dify-specific settings

At least one app or Knowledge descriptor is required. A host may serve only apps, only Knowledge, or both domains.

Configure application descriptors

The app file is a JSON array. Each object rejects unknown fields.

[
  {
    "id": "support-chat",
    "name": "Support chat",
    "mode": "chat",
    "description": "Published customer-support application",
    "api_key_file": "/run/secrets/dify-support-chat"
  }
]

App IDs must be unique. The file may contain at most 1,000 descriptors and at most 4 MiB of JSON. Those are parser ceilings, not a promise that such a set fits the global admitted-manifest capability limit.

If AIP_DIFY_API_KEY_FILE is set, every app must omit api_key_file. If the global key is absent, every app must name its own file. Mixed or missing sources fail startup.

Configure Knowledge credentials

The Knowledge file is also a JSON array with unknown fields denied.

[
  {
    "id": "main-workspace",
    "name": "Main knowledge workspace",
    "description": "Reviewed workspace Knowledge API boundary",
    "api_key_file": "/run/secrets/dify-main-knowledge"
  }
]

Knowledge IDs must be unique. The file shares the 4 MiB read bound and has a 1,000-descriptor parser ceiling. Each descriptor publishes 46 capabilities, so manifest validation normally constrains the practical count first.

The global application key never supplies a Knowledge credential.

Configure provider origin and keys

The Dify base URL must be an origin:

• HTTPS is required except for explicit loopback HTTP;
• credentials, path prefix, query, and fragment are rejected;
• authenticated redirects are disabled;
• provider connection establishment has a 10-second timeout.

The base URL does not identify a Dify source commit or image. Bind provider artifact identity and compatibility evidence outside this string.

Every API-key file is read as non-empty UTF-8 with a 16 KiB bound. Descriptor and configuration files may be public only when they contain no key material.

Set the response-size limit

AIP_DIFY_MAX_RESPONSE_BYTES accepts an integer from 1 through 67108864. Omission uses 8388608 bytes.

The connector checks declared content length and accumulated stream bytes. The same active limit applies to blocking JSON, text, binary data before base64 projection, and the complete SSE response.

Increasing this setting does not increase the common native-envelope request limit, JSON encoder bound, decoded upload limit, per-frame SSE limit, or event count.

Apply relevant shared host settings

The global connector-host reference owns the complete matrix. These groups are required for Dify behavior.

Identity and route

An optional external-account ID and system must appear together. Dify can contain several app and workspace identities, so deployment policy must define what that single external-account reference means.

Storage, signing, and lifecycle

Shared credential ID, issuer, scope, revision, and revision-policy settings are optional as one complete unit. They fence route authorization and do not replace Dify API-key files.

Stream callback

Streaming publication can use the common fixed callback endpoint and its explicit network policy:

Configure callback behavior according to the selected gateway topology. The product configuration does not make a callback mandatory for non-streaming operations.

Use the effective limits

The effective request ceiling is the smallest applicable limit. The 8 MiB JSON encoder and 48 MiB encoded upload schema do not enlarge the common 4 MiB native envelope limit.

Understand readiness

Product health checks every configured credential:

The connector runs at most 32 checks concurrently and reports ready only after all succeed. Host readiness also requires durable storage, valid lease, non-draining lifecycle state, and common host readiness.

Readiness does not exercise app invocation, every mode-supported operation, mutation approval, stream termination, cancellation, binary response, upload, or provider compatibility beyond these reads.

Know startup and reload ownership

Change startup-owned values through a replacement replica and a new configuration or admission revision. Editing a file does not update the running manifest, key map, mode, task-store scope, or response limit.

Diagnose configuration failures

Related documentation

• Dify connector overview
• Authentication and credential scopes
• Connector host configuration
• Connector host lifecycle
• Environment variables