langgenius/dify-plugin-daemon

Dify Plugin Daemon

Overview

Dify Plugin Daemon is a service that manages the lifecycle of plugins. It's responsible for 3 types of runtimes:

1. Local runtime: runs on the same machine as the Dify server.
2. Debug runtime: listens to a port to wait for a debugging plugin to connect.
3. Serverless runtime: runs on a serverless platform such as AWS Lambda.

Dify api server will communicate with the daemon to get all the status of plugins like which plugin was installed to which workspace, and receive requests from Dify api server to invoke a plugin like a serverless function.

All requests from Dify api based on HTTP protocol, but depends on the runtime type, the daemon will forward the request to the corresponding runtime in different ways.

• For local runtime, daemon will start plugin as the subprocess and communicate with the plugin via STDIN/STDOUT.
• For debug runtime, daemon wait for a plugin to connect and communicate in full-duplex way, it's TCP based.
• For serverless runtime, plugin will be packaged to a third-party service like AWS Lambda and then be invoked by the daemon via HTTP protocol. You may refer to SRI Docs for more detailed information.

For more detailed introduction about Dify plugin, please refer to our docs https://docs.dify.ai/plugins/introduction.

CLI

A CLI tool is provided for plugin development on local environment.

• Install via brew

Both Linux and MacOS on either arm64 or amd64 architecture are supported.

1. Tapping the Homebrew tap for Dify CLI
2. Install Dify cli with brew

brew tap langgenius/dify
brew install dify

• Install with the binary file

Download the binary file from the assets' list in the release page.

Development

Run daemon

Firstly copy the .env.example file to .env and set the correct environment variables like DB_HOST etc.

cp .env.example .env

Run the daemon with the following command. It uses godotenv to load environment variables from the .env file.

go run github.com/joho/godotenv/cmd/godotenv@latest -f .env go run cmd/server/main.go

If you were using a non-AWS S3 storage before version 0.1.2, you need to manually set the S3_USE_AWS environment variable to false in the .env file.

Attention that the PYTHON_INTERPRETER_PATH is the path to the python interpreter, please specify the correct path according to your python installation and make sure the python version is 3.11 or higher, as dify-plugin-sdk requires.

We recommend you to use vscode to debug the daemon, and a launch.json file is provided in the .vscode directory.

Run db migration

go run ./cmd/commandline/ migrate

Python environment

UV

Daemon uses uv to manage the dependencies of plugins, before you start the daemon, you need to install uv by yourself.

Interpreter

There is a possibility that you have multiple python versions installed on your machine, a variable PYTHON_INTERPRETER_PATH is provided to specify the python interpreter path for you.

Deployment

Currently, the daemon only supports Linux and MacOS, lots of adaptions are needed for Windows, feel free to contribute if you need it.

Docker

NOTE: Since the daemon depends on a shared cwd directory for running plugins, it's not recommended to use network-based volumes or bind mounts from outside the host machine. This could result in poor performance, such as plugins not launching in a timely manner.

uses docker volume to share the directory with the host machine, it's better for performance.

Kubernetes

For now, Daemon community edition does not support smoothly scale out with the number of replicas, If you are interested in this feature, please contact us. we have a more production-ready version for enterprise users.

Redis namespacing

Enterprise deployments often share Redis across multiple systems or subsystems. The daemon supports a global Redis prefix via REDIS_KEY_PREFIX.

• Default value: plugin_daemon
• Applies to Redis keys and pub/sub channels used by the daemon
• Safe for Redis Cluster logical keys that already use hash tags such as {remote:key:manager}
• Changing the prefix changes the active namespace; existing cache and coordination data under the old prefix is not migrated automatically

HTTP Error Responses (unreleased)

Responses produced by InternalServerError now use the fixed message Internal Server Error across invocation, management, and cluster forwarding APIs. The HTTP status, response code, error type, and JSON structure are preserved; original errors and stack traces remain in server logs. Clients must use status and error codes instead of matching internal exception text.

Endpoint stream failures return a generic HTTP 500 before response headers are sent. After headers are sent, the daemon interrupts the response without appending an error message, including through other daemon nodes. Clients must handle response-body read errors and discard incomplete results. Explicit HTTP responses returned by plugins retain their status, headers, and body. Webhook plugins can still finish backwards invocations after the HTTP client disconnects, within the existing execution deadline.

Deploy this fix to every daemon node, then rebuild and deploy plugins with the SDK HTTP error fix in SDK 0.11.0 (unreleased). Both updates are required: older SDKs can include exception details in otherwise ordinary plugin responses.

Documentation

• Backwards LLM invocation timeouts

Development Guide

For developers working on this codebase, see our comprehensive development documentation:

• CLAUDE.md - Main development guide with architecture, code style, and setup
• Database Operations - Query builder patterns, models, and transactions
• Cache Operations - Redis caching, pub/sub, and distributed locks
• Stream Operations - Async streaming patterns and SSE handling
• Generic Types - Type-safe patterns used throughout the codebase
• HTTP Requests - HTTP client utilities and request handling

Runtime Documentation

• SRI Docs - Serverless Runtime Interface documentation

Recommend env config

PYTHON_COMPILE_ALL_EXTRA_ARGS="-x \.venv"

Using PYTHON_COMPILE_ALL_EXTRA_ARGS="-x .venv" prevents compileall from compiling files within the virtual environment, which reduces CPU usage during plugin initialization.

PLUGIN_IGNORE_UV_LOCK=true
PIP_MIRROR_AUTO_DETECT=true
PIP_MIRROR_URL=

Setting PLUGIN_IGNORE_UV_LOCK=true allows uv to ignore the uv.lock file and use the selected PyPI mirror for dependency resolution.

PIP_MIRROR_AUTO_DETECT is enabled by default. When enabled, the daemon probes official PyPI and each candidate mirror in parallel at startup, then selects the fastest candidate. If official PyPI responds faster than all candidates, no mirror is used.

PIP_MIRROR_URL manually specifies the PyPI mirror. When it is set, it takes precedence over auto-detection.

PIP_MIRROR_CANDIDATES is an optional comma-separated list of mirror URLs to probe. When unset, the built-in defaults (https://mirrors.aliyun.com/pypi/simple/ and https://pypi.tuna.tsinghua.edu.cn/simple/) are used.

Benchmark

Refer to Benchmark

LICENSE

Dify Plugin Daemon is released under the Apache-2.0 license.