# The Plugin System


## Overview

Dify keeps models, tools, agent strategies, datasources, triggers, and plugin endpoints outside the core so the platform can change one capability without forcing a full release of the rest. That split cuts dependency bloat, shortens iteration, and makes room for a third party plugin ecosystem instead of a closed core. The public plugin docs already cover type selection and type specific development, so this chapter stays at the architectural boundary. The code in `api/core/plugin/entities/plugin.py` and `api/core/plugin/plugin_service.py` shows a small core that owns policy, discovery, caching, and lifecycle while plugin capabilities attach only where the product needs them.

## The plugin types and their seams

`PluginCategory` names six supported categories: `Tool`, `Model`, `Extension`, `AgentStrategy`, `Datasource`, and `Trigger`. `PluginDeclaration` does not treat category as a free form label. It infers the category from the manifest content itself: if the declaration carries `tool`, `model`, `datasource`, `agent_strategy`, or `trigger` data, it selects the matching category, and it falls back to `Extension` when none of those fields appear. That keeps the manifest aligned with the subsystem that will consume it.

The daemon facing entities in `api/core/plugin/entities/plugin_daemon.py` reinforce the same split. They carry a plugin identifier, a unique identifier, the provider name, and a typed declaration object, which gives the API enough structure to rebind plugin supplied providers back into tenant scope without guessing what kind of capability the package exposes.

- `Tool` plugs into `core.tools` through `PluginToolManager` in `api/core/plugin/impl/tool.py`. The call flow runs from the application into the daemon for discovery, credential checks, and tool execution, then returns tool messages back into the normal tool engine.
- `Model` plugs into the shared model runtime through `api/core/plugin/impl/model.py` and `api/core/plugin/impl/model_runtime.py`. The runtime adapter keeps plugin backed models on the same contract as the rest of the platform, and the sibling chapter [/06-the-model-runtime.md](./06-the-model-runtime.md) explains that shared runtime in more depth.
- `AgentStrategy` plugs into the agent layer through `api/core/plugin/impl/agent.py`. The API asks the daemon for strategy discovery and strategy execution, and then hands the resulting messages back to the agent flow.
- `Extension` plugs into endpoint management through `api/core/plugin/impl/endpoint.py`, `api/services/plugin/endpoint_service.py`, and `api/controllers/inner_api/plugin/plugin.py`. This seam does not add a new runtime primitive; it lets a plugin own managed endpoints while the API controls create, update, enable, disable, and delete operations.
- `Datasource` plugs into `api/core/plugin/impl/datasource.py` and the workflow datasource node in `api/core/workflow/nodes/datasource/datasource_node.py`. The workflow node consumes the datasource output and turns it into normal workflow data, including the local file datasource path that the code keeps alongside plugin sourced datasources.
- `Trigger` plugs into `api/core/plugin/impl/trigger.py` and `api/core/workflow/nodes/trigger_plugin/trigger_event_node.py`. The daemon publishes trigger providers and events, and the workflow layer turns those events into workflow entry points and subscription lifecycles.

The official Dify plugin docs already explain how to choose a type and how to build each one. This chapter leaves those tutorials there and focuses on the boundary: which subsystem each plugin type attaches to, which direction the calls move, and which adjacent layer receives the result.

## The runtime boundary

The repository shows the plugin daemon as a separate service, not as in process code. `docker/docker-compose.yaml` starts `plugin_daemon` beside `api`, `worker`, and `agent_backend`, and `docker/envs/core-services/plugin-daemon.env.example` wires the API URL, the daemon key, the debugging port, and the working path. `BasePluginClient` in `api/core/plugin/impl/base.py` owns the HTTP hop from the API process to that daemon. It sends every request under a tenant scoped path such as `plugin/{tenant_id}/...`, adds the `X-Api-Key` header from configuration, and adds `X-Plugin-ID` wherever the call needs to name a specific plugin. The client code also keeps the request path clean and rejects traversal attempts before it sends anything outward.

The API process does not execute plugin code itself. It treats the daemon as the execution surface for plugin behavior and only consumes typed responses, streamed events, and error envelopes. The repository does not include the daemon implementation, so this chapter stops at the client side and the deployment surface the code makes visible.

## Execution environments

The compose file and env example prove the deployment wiring: `plugin_daemon` listens on `PLUGIN_DAEMON_PORT` with a default of `5002`, exposes `PLUGIN_DEBUGGING_PORT` with a default of `5003`, and reads `PLUGIN_DAEMON_URL`, `PLUGIN_DAEMON_KEY`, `PLUGIN_DIFY_INNER_API_URL`, `PLUGIN_DIFY_INNER_API_KEY`, and the plugin working path from the environment. The API and worker services point at that daemon, and `agent_backend` uses its own plugin daemon URL and key. Dify’s public runtime material describes local process, debug connection, and hosted operation as part of the same plugin story; this repository only proves the container and environment wiring behind that split.

## Reverse invocation

Plugins also call back into Dify. The inner API controller in `api/controllers/inner_api/plugin/plugin.py` exposes the reverse invocation surface, and its decorators in `api/controllers/inner_api/plugin/wraps.py` show the safety rails around it. `plugin_inner_api_only` gates access to trusted callers, `plugin_data` validates the payload shape, and `get_user_tenant` plus `get_user` resolve tenant and user context before the controller enters the request body. That means the inner API does not trust plugin supplied identity on its own; it rebuilds the trusted tenant and user context before it runs anything else.

The backwards invocation package splits the outbound surface into clear paths: `app.py` invokes workflows and app modes, `model.py` invokes models and model runtime helpers, `tool.py` invokes tools, and `node.py` invokes node like helpers such as parameter extraction and question classification. The important point is architectural rather than procedural: a plugin can orchestrate platform capabilities from inside the same boundary that normally serves plugin requests outward. The official reverse invocation docs should serve as the operational reference; this chapter only maps the system boundary that the code exposes.

## Lifecycle in one view

`api/core/plugin/plugin_service.py` owns the life of a plugin after installation. It orchestrates install, uninstall, upgrade, cache invalidation, and provider discovery, while `api/services/plugin/oauth_service.py` creates short lived OAuth proxy contexts for credential flows. `api/services/plugin/plugin_permission_service.py` stores tenant plugin install and debug permissions, `api/services/plugin/plugin_auto_upgrade_service.py` keeps auto upgrade policy category scoped, and `api/services/plugin/endpoint_service.py` wraps endpoint CRUD and enablement. The lifecycle also covers the sources that the code accepts today: marketplace, package, GitHub, and remote install paths. The policy layer keeps credentials, cache, and upgrade decisions tenant scoped so one workspace cannot silently reshape another workspace’s plugin surface.

## Architecture note

The plugin boundary acts as the platform’s outermost port. Dify’s public Beehive naming fits that same modular, cell like direction: each subsystem keeps a narrow surface and exchanges typed data with the neighbors that need it. As of mid-2026, the newer `dify-agent/` stack continues the same split boundary direction, but this chapter stops at the API and deployment surface that the repository shows.

## Where to look in the code

- `api/core/plugin/entities/plugin.py` — plugin categories, manifest inference, and installation source types.
- `api/core/plugin/impl/base.py` — tenant scoped HTTP transport to the daemon, including `X-Api-Key` and request path guards.
- `api/core/plugin/impl/model_runtime.py` — the adapter that ties plugin backed models into the shared runtime.
- `api/controllers/inner_api/plugin/plugin.py` — reverse invocation endpoints for apps, models, tools, nodes, and related helpers.
- `api/core/plugin/plugin_service.py` — install, upgrade, uninstall, cache invalidation, and provider discovery policy.
- `docker/docker-compose.yaml` — the separate `plugin_daemon` service and the deployment wiring around it.