Plugin Daemon Architecture#

The Dify API communicates with the plugin daemon — a separate Go-based service (default port 5002) — for all plugin execution. The API never runs plugin code directly; every plugin invocation, model dispatch, tool call, and credential validation is proxied over HTTP to the daemon 1.

Dify API ──(HTTP/SSE)──► Plugin Daemon :5002
             X-Api-Key, X-Plugin-ID headers
             URL path: plugin/{tenant_id}/...

The daemon maintains its own PostgreSQL database (dify_plugin, separate from the main dify DB) and its own filesystem layout for installed plugin packages 2.

Request Routing: Headers and URL Structure#

All requests flow through BasePluginClient in api/core/plugin/impl/base.py. The request routing uses two complementary identification mechanisms:

• Tenant ID — in the URL path: Every endpoint is prefixed with plugin/{tenant_id}/, scoping the request to a specific workspace. For example: plugin/{tenant_id}/dispatch/llm/invoke 3.
• Plugin ID — in the X-Plugin-ID header: The specific installed plugin to invoke is set in the HTTP header on every dispatch call, e.g. "X-Plugin-ID": plugin_id 4. This is consistent across all plugin client implementations: model, tool, agent, trigger, datasource, and oauth 5 6.

A third header, X-Api-Key, carries PLUGIN_DAEMON_KEY and is injected by _prepare_request() on every call for daemon authentication 7. An optional traceparent header is appended when OpenTelemetry is enabled 8.

URL Patterns#

9 10 11

Response Format#

Responses are wrapped in a PluginDaemonBasicResponse envelope; non-zero code values trigger structured error handling in _handle_plugin_daemon_error(). Streaming endpoints (LLM, embeddings, rerank) use SSE; the client reads newline-delimited JSON lines via _stream_request() 12.

Configuration#

Configured in PluginConfig (api/configs/feature/__init__.py):

In Docker Compose the URL is typically http://plugin_daemon:5002 13. The HTTP connection pool is bounded at 50 keep-alive / 100 max connections 14.

Version Synchronization#

The plugin daemon is versioned in lockstep with the Dify API. Protocol changes between releases cause complete communication failures if the versions diverge 15. Known pairings:

16

When the daemon version does not match the API, the daemon logs "failed to find the version of the plugin sdk" and the API returns connection errors 15.

Upgrade Checklist#

After any major version upgrade:

1. Run the Alembic migration: docker compose exec api flask upgrade-db 2
2. Run the plugin backfill: docker compose exec api flask backfill-plugin-auto-upgrade — normalizes plugin records after version identifier changes 2
3. Confirm the daemon image tag matches the Dify release 16
4. Remove stale plugin version directories from PLUGIN_INSTALLED_PATH 17

Common Upgrade Failures#

• "record not found" / "Plugin table missing" (1.15.0+): Stale plugin version directories remain on disk; the backfill command resolves this 18 2.
• "Credential with id … not found" (1.14.x): model_type enum values were renamed without a data migration; see Plugin Database Integrity for the SQL fix 19.
• Duplicate plugin_unique_identifier (SQLSTATE 23505): Daemon crashes on startup during index creation; deduplicate the dify_plugin.plugins table before restarting 2.

Key Source References#