How the Dify plugin daemon fits into a production deployment
If you run self-hosted Dify with plugins or custom tools, the plugin daemon is the component that decides whether those extensions behave predictably under load. The Dify Docker Compose deployment starts it as one of the core services alongside the api, worker, web, PostgreSQL, Redis, Weaviate, Nginx, the code sandbox and the SSRF proxy. That placement matters: every model call, tool invocation and plugin-driven step in a workflow passes through the daemon before it reaches the rest of the stack. Start by confirming on your own host which containers are running after a deployment, and record how the plugin daemon is wired to the api service in your .env file so your team knows where to look during an incident.
Teams usually need to tune the daemon when they move beyond the default Marketplace plugins. Custom tools that call internal systems can return large payloads, slow responses or long-running operations, and private plugins add packages that must be installed and kept current. Each of these pressures the daemon in a different way. Before you change any setting, ask your Dify vendor or your own platform team to confirm which plugin-related variables your release exposes in the environment reference, since names and behavior can change between minor releases. Track the release notes for each upgrade, because the Dify releases arrive roughly monthly and plugin behavior has shifted across versions.
Plugin failures often look like workflow failures. A user sees a node that stops, a run that errors or an answer that never arrives, and the first instinct is to inspect the prompt, the model or the workflow logic. When the cause is the daemon, such as a timeout, a rejected package, or a plugin that cannot load its model schema, the error surfaces inside the workflow run even though the defect lives elsewhere. Build your runbook so that on-call staff check the plugin daemon logs and the api logs for the same time window before they edit a workflow. Note which errors in your own environment originate in the daemon, because that mapping saves hours during the first production incident.
Dify plugin daemon settings to review before production
This table lists the plugin daemon settings that most often need a deliberate value before go-live, grouped by area. Use it as a review checklist: the setting names and defaults must come from the .env.example and environment variable reference for your exact Dify version, and each value should be tested against your own plugin workloads.
| Setting area | What it controls | When it matters | What to confirm |
|---|---|---|---|
| Timeouts | How long the API service waits for a plugin daemon response before failing a tool, model or datasource call | Slow internal APIs, large model responses or long-running tool calls that exceed the default wait | Confirm the timeout variable names in .env.example for your version, then test your slowest internal call end to end |
| Package size limits | Maximum size of a plugin package (.difypkg) the daemon will accept for install or upload | Plugins that bundle large dependencies, models or static assets | Confirm the package limit variable and build a representative package to check it fits within the limit |
| File size limits | Maximum size of files passed to plugins, such as documents for datasource or tool plugins | Document-heavy knowledge pipelines or tools that return or accept binary content | Compare the file limit with your largest real documents and the upload limit enforced by Nginx or your proxy |
| Model schema cache | How long the daemon keeps model provider schemas and parameter definitions before refreshing them | After a model plugin update, a new parameter or a changed credential schema that users do not see | Confirm the cache setting and the procedure for forcing a refresh after upgrading or changing a model plugin |
| Remote debugging port | Whether the daemon exposes a port for remote plugin debugging and where that port is reachable | Development and test environments where plugins are debugged against a running daemon | Confirm the port variable and default, keep it closed in production, and verify host firewall and container networking rules |
| Inner API key | The shared secret the plugin daemon and API service use to authenticate each other on internal calls | Every deployment, and especially after changing secrets, restoring backups or rotating credentials across services | Confirm the variable is set to a unique value in .env, that all services read the same value after restart, and that the rotation steps are documented |
| Plugin daemon resources | CPU and memory available to the daemon process while plugins run tool, model and parsing work | Concurrent plugin calls, large packages or heavy parsing inside a plugin | Confirm the container limits in your Compose or Kubernetes manifest against the load observed in staging |
Failure modes that trace back to the plugin daemon
Most plugin daemon incidents show up in the app as a failed tool call, a rejected install or a model that stops responding, and the cause often sits in a setting rather than in the plugin code. The cards below pair each pattern with the symptom a user sees and the first check an operator should make.
Plugin calls time out
A workflow node that calls a slow internal system stops with a timeout while the same request succeeds when run directly. The first check is whether the timeout sits in the daemon, the API or the plugin itself, because each layer has its own limit and raising only one of them changes nothing. Compare the time the internal system takes under load with the configured limits, and confirm the path from the daemon to the internal host is allowed through the SSRF proxy.
Packages and files rejected
A plugin package or a file uploaded through a plugin fails at install or upload, while smaller files pass. The symptom is an install or upload that stops partway, and the first check is the size limit in effect at each hop, including the reverse proxy in front of Dify, because a limit set only in the application will not stop a proxy from rejecting the request first. Confirm the limit against the version you run, since limits change between releases.
Stale model schemas after a change
After a model provider updates its supported models or parameters, the app still offers the old model list or rejects a parameter the provider now accepts. Users see a model missing from the picker or a parameter error during a run. Check whether the cached schema for that provider was refreshed, then confirm the plugin version matches the provider's current release before you edit any workflow.
Debug port left reachable
A remote debugging port left open on the daemon host lets anyone who can reach it attach to a running plugin process. Users may see nothing wrong, which is why this failure is easy to miss. The first check is the listening socket on the daemon host and the network policy in front of it: confirm the debug port is bound only where you intend, is closed in production, and is absent from any published port mapping in the Compose file.
API and daemon key mismatch
After a configuration change, plugin installs or tool calls fail with authorization errors while the web console still loads. This happens when the API service and the plugin daemon hold different values for the shared inner API key. The first check is whether both services were restarted with the same value from the same environment file, since a change made to only one service leaves them disagreeing until both are restarted together.
Setting up the Dify plugin daemon for production
This sequence takes a self-hosted Dify from an unpinned test setup to a plugin daemon that is version-pinned, sized to your plugin workloads, locked down for debugging, and recorded in version control so the configuration can be reproduced and audited.
Pin the target Dify release
Choose the Dify release you will run and record its exact version tag from the GitHub releases page, not a floating latest image. Read the release notes for security changes and plugin-related items, and follow the upgrade guide for that version before you begin. Done means your deployment files reference one explicit version and the release notes have been reviewed and filed with your change record.
Read the daemon settings in the reference files
Open the .env.example file that ships with your target release and the Dify environment variable reference, then list every key that controls the plugin daemon, including its timeouts, package and file size limits, and the inner API key shared with the API service. Compare each key against your current .env. Done means you have a written list of daemon keys with their defaults and the value you intend to set for each, and you have noted any keys that are new in this release.
Set timeouts and size limits from tested workloads
Run your intended plugins against representative inputs in a non-production environment, and record how long calls take and how large the packages and files they handle are. Set the daemon timeout and size limits to values that cover those measurements with a margin you choose, rather than leaving defaults or setting very large values. Done means each limit has a documented reason tied to a test result, and an oversized test input is rejected with the expected error rather than hanging the workflow.
Confirm the inner key matches on both services
Verify that the inner API key used between the API service and the plugin daemon is set to the same value in every service that reads it, and that it comes from your secret store rather than a value committed to a file. Restart the affected services after any change. Done means a check of the running containers' environment shows an identical value for both, the key is absent from version control, and the plugin list loads in the console without authentication errors.
Disable or restrict remote debugging
Confirm whether the remote debugging port for the plugin daemon is enabled in your configuration. If you do not need it in production, turn it off. If developers need it, restrict it to a named administrative network or a bastion host and do not publish it through the public load balancer. Done means a port scan from outside the admin network shows the debugging port closed, and a note in your runbook records who may open it and how it is turned off again.
Run an end-to-end test plugin call
Install a test plugin in a non-production workspace, invoke one of its tools from a workflow, and confirm the request passes through the API service, the plugin daemon and back to the workflow with a valid response. Include one call that exceeds a size or time limit to confirm the failure is reported clearly. Done means the test workflow completes, the failure case produces the expected error in the logs, and you have saved the workflow export and log excerpts as evidence.
Record the configuration in version control
Commit the pinned version, the daemon keys with non-secret values, the size and timeout rationale, and the debugging policy to your infrastructure repository. Keep secret values in your secret manager and reference them by name. Done means a second person can rebuild the daemon configuration from the repository alone, a review has approved the change, and the commit hash is linked from your change record.
Why the inner API key between the plugin daemon and the API service matters
The inner API key is the credential that the api service and the plugin daemon present to each other, and it is part of the trust boundary for every plugin call. The Dify 1.16.1 release notes describe token-based API authentication between services, so the daemon depends on this shared value to accept requests from the api service. Generate the key as a long random value, store it in your secrets manager, and inject the same value into both containers from that single source. Confirm the exact variable name and any related settings in .env.example for your target version, because the name is what your deployment templates and secret injection must reference.
Both sides must hold the identical value. When they do not, the failure usually shows up as plugin calls being refused, so models, tools or datasource plugins look unavailable even though the containers are healthy. Check the api and plugin daemon logs for authentication rejections after any change to secrets or environment files. Keep this key separate in your thinking from SECRET_KEY. The Dify environment variable reference says SECRET_KEY signs session cookies and JWTs and encrypts OAuth credentials, and changing it after deployment logs out all users. Rotating the inner key does not log anyone out, but rotating SECRET_KEY has user-facing and credential-related effects, so the two need separate change records.
Plan rotation of the inner key as a maintenance window, because the api service and the plugin daemon must move to the new value together and in a controlled order. Rehearse the change in a staging environment built from the same configuration pattern as production, then verify that a model call, a tool invocation and a plugin installation all succeed before you touch production. Take a backup first, as the Dify Docker Compose guidance recommends before any upgrade, and record which version you are running. If the rotation coincides with a version upgrade, read the upgrade guide for that release and review new variables in .env.example before you change anything.
How the plugin daemon setup changes by deployment model
In the single-host layout, the plugin daemon runs as one of the compose services next to the api, worker, web and data services. The Docker Compose deployment is the simplest place to see the daemon's settings, because they sit in the same .env file and compose file as the rest of the stack. Your team owns the host, the file and the restart behavior, so most troubleshooting starts with the container logs and the environment values.
- Settings live in one place: Daemon-related variables are read from
.env, so review that file against.env.exampleafter each upgrade. - Service restarts are coupled: Restarting the whole stack to change one daemon value is common, so plan a short maintenance window.
- Resource contention is shared: The daemon competes with the api and worker for the same CPU and memory on one host, which matters at the 2 CPU and 4 GB minimum.
- Backups must cover the host: Take a backup of the volumes and
.envbefore any daemon change, as the Docker Compose docs recommend before every upgrade. - Single failure domain: A host outage takes the daemon down with the rest of the stack.
Before you rely on this layout, confirm that a test plugin installs, runs a tool call and survives a stack restart on the same host.
In a self-managed production layout, PostgreSQL, Redis and object storage move to services you run or buy separately, while the Dify containers still run under Compose. The daemon configuration travels with your .env file and any compose override files you maintain, so those files become the record of how the daemon behaves. Ownership is split: your team owns the external services and their networking, and the daemon depends on them being reachable and correctly sized.
- Overrides carry the changes: Keep daemon settings in version-controlled
.envand override files so that a rebuild reproduces them. - Network paths are yours to verify: Confirm the daemon can reach the external database, Redis and storage endpoints from its container network.
- Storage locations affect plugin files: Confirm where packages and cached files are written and that the target volume is backed up and has room to grow.
- Secrets need a single source: Keep the inner API key and other values in your secret store and inject them at deploy time, not in shared files.
- Upgrades need a config diff: Compare your overrides with the new release's
.env.exampleand the upgrade guide for the target version.
Before you go live, test a restore of the external database and object storage, then confirm the daemon still loads plugins after the restore.
Dify Enterprise runs on Kubernetes with Helm, which changes the ownership model: the plugin daemon is deployed, scaled and restarted through cluster objects rather than a Compose file on a host. The supplied documentation describes the platform requirements, including Kubernetes 1.24 or later, Helm 3.14 or later, PostgreSQL 14 or later, Redis 6 or later and a Qdrant vector database, but it does not describe daemon-level configuration. Ask the vendor how the daemon is packaged, what values you may set, and whether it can be scaled independently of the API and workers.
- Packaging is vendor-defined: Confirm whether the daemon ships as a separate workload, and which Helm values control it.
- Scaling and placement need confirmation: Ask whether the daemon can run with multiple replicas and how node placement is set.
- Upgrades follow the chart: Confirm how daemon versions move with the rest of the release and what rollback looks like.
- Secret handling differs: Ask how the inner API key is stored and rotated in the cluster.
- Observability depends on your stack: Confirm which daemon logs and metrics are exposed to your cluster monitoring.
Before accepting this layout, get the vendor's written answers on these five points and test one plugin install and one upgrade in a non-production cluster.
Securing the plugin daemon and its debugging access
The plugin daemon runs code that talks to models, internal systems and the public internet, so it needs the same boundaries as the api and worker services. The cards below cover network paths, secrets, outbound filtering, plugin trust and logging, which together decide how far a compromised plugin or a forgotten debug port can reach.
Keep remote debugging closed
Remote debugging lets a developer attach to a running plugin, and that port should never be reachable from public networks. Keep it bound to a管理 host or closed entirely in production, and open it only for a time-boxed session with a named owner and a removal date. Check your firewall rules and container port mappings after every upgrade, since a default that exposed the port in one version can persist into the next compose file you copy.
Restrict network paths to the daemon
Only the api and worker services should open connections to the plugin daemon, and the daemon should accept nothing from elsewhere. Write explicit allow rules between those containers or hosts and deny the rest, including direct access from user-facing networks. Confirm the rules with a connection test from a non-Dify host, because a flat Docker network often allows more traffic than the compose file suggests.
Store the inner key in your secrets store
The inner API key is the shared credential between the api service and the plugin daemon. Keep it in your secrets manager, inject it at container start, and rotate it through a planned change window that restarts both services together. Do not commit it to the .env file in version control or paste it into tickets. Ask your team to confirm who can read it and where the value appears in logs.
Route plugin egress through the SSRF proxy
Plugins that call external or internal HTTP services should send that traffic through the SSRF proxy rather than directly. The environment reference says SSRF_PROXY settings route outbound requests through a proxy that blocks internal and private IP ranges, which protects against plugins reaching metadata endpoints or private databases. Maintain an explicit allowlist for internal systems a plugin legitimately needs, and review each entry when the plugin changes.
Review plugin trust and install policy
Every installed plugin runs with the daemon's access, so the install list is a security decision. Decide which sources are acceptable, such as the Marketplace, your own Git repository or signed local packages, and record which versions are approved in production. Remove plugins that no longer have an owner, and check that signature verification stays enabled on production instances rather than being relaxed to get a package installed.
Send daemon events to central logging
Plugin install, failure, timeout and restart events are the first evidence you need when an integration misbehaves or a package changes unexpectedly. Forward daemon container logs to the same central system that collects api and worker logs, with retention set by your own policy. Test that a plugin installation and a deliberate failed call both appear in the central system, and that log entries do not include the inner key or credentials passed to plugins.
Questions teams ask before running the plugin daemon in production
How much effort does it take to tune and verify the plugin daemon?
The effort depends less on the daemon itself than on how many plugins your organization runs, how many workspaces load them, and how much of their behavior is tested before each change reaches production. Tuning covers request timeouts for slow internal tools, package and file size limits for plugins that handle documents, and the model schema cache behavior for custom model providers. Verification means exercising each plugin path in a staging environment that mirrors production settings, including the shared inner API key configuration between the API service and the daemon. Ask any partner to show the test cases, the staging parity checklist and the change record they will produce before you agree on the scope.
What would a partner do that our internal team would not?
A partner typically brings repeated experience with the failure modes of the daemon across deployments, such as timeouts that appear only under concurrent workflow runs, or size limits that break a plugin only after a document type changes. Your internal team holds the knowledge of your systems, your identity model and your change windows, which a partner needs from you. A fixed-scope engagement with DeployOpen usually splits the work this way: DeployOpen plans the configuration, tests it, documents the settings and hands over a runbook, while your engineers own the plugin code, approvals and day-to-day operation. Confirm the split in writing so neither side assumes the other owns the on-call response.
Can we run the plugin daemon work ourselves without outside help?
Yes, if your team has Docker Compose or Kubernetes operations experience, can read the Dify environment reference, and has a staging environment where plugin changes can be tested before production. The main risks for an internal team are missing settings that differ between environments, leaving the remote debugging port reachable after troubleshooting, and upgrading without checking the .env.example file for new variables. Teams that build this capability internally usually write their own verification checklist and keep a record of each configuration change. An outside review can be useful as a one-time check against that checklist, and it can be scoped separately from ongoing operations.
How long does a verification cycle take for the plugin daemon?
The duration of a verification cycle depends on the number of plugins in use, the test coverage your team or a partner can build for each one, and how your change control process approves and schedules the results. A small set of plugins with existing tests moves faster than many custom plugins with no tests and several approval gates. Ask for a timeline that lists each gate and who signs off on it, rather than a single end date. Written scope is the place to fix these dates, so any change to plugin count or test coverage is visible before work starts.
What do we need to provide before the work starts?
Four inputs make the engagement predictable: access to the hosts or cluster that run the Dify services, an inventory of every installed and planned plugin with its owner and the systems it calls, a documented secrets process for the shared inner API key and provider credentials, and a staging environment that matches production in version and configuration. Without the inventory, timeouts and size limits are set by guesswork. Without a secrets process, the inner API key is often copied into tickets or chat. Without staging, every test happens in production. Confirm that your secrets tooling and network paths allow the work before the scope is signed.
How do Dify upgrades affect the plugin daemon?
Dify publishes minor releases roughly monthly. Dify 1.16.0 was released on July 17, 2026, 1.17.0 on August 25, 2026, and 1.17.1 on September 10, 2026, according to the GitHub releases page. Each upgrade can change the daemon's configuration, the inner API key handling, and plugin compatibility, so the Docker Compose documentation advises taking a backup before every upgrade and checking .env.example for new variables afterward. Plan a staging upgrade, rerun the plugin verification suite, and read the release notes and the upgrade guide for the target version before production. A monthly cadence means the verification cycle repeats often, so budget for it as a recurring cost rather than a one-time project.
Which settings in the daemon should we check first?
Start with the shared inner API key, because it authenticates the API service to the plugin daemon and a mismatch or exposure affects every plugin. Then review the timeout and size limit settings against your largest plugin workload, and confirm the remote debugging port is disabled or restricted in production. Check that the daemon's outbound calls go through the approved proxy path, since the SSRF proxy blocks internal and private IP ranges by default and internal plugin targets may need an explicit allowlist. Record each value and its reason in your configuration documentation so the next upgrade does not silently reset it.
Limits to confirm for your Dify version and environment
The plugin daemon has settings that look minor on paper but decide whether a plugin fails under load, rejects a valid package or keeps stale model metadata. Several of these details change between releases, so confirm each one against the release you run before you size or harden the deployment. The cards below list what to check and where to check it.
Timeout and size limit keys
Confirm the exact names, defaults and units of the timeout and package or file size settings that govern plugin installation and plugin calls in your target release. Check the environment variable reference first, then the .env.example shipped with that version, since a value can be documented in one place and set differently in the other. Record each value in your deployment notes so an upgrade does not silently reset it.
Schema cache refresh behavior
Find out whether cached model schemas refresh when a model provider plugin is updated or its credentials change, or whether the api and plugin daemon need a restart. Test this in a non-production instance by changing a provider parameter and checking the console. Stale schemas can make a workflow send parameters the provider no longer accepts, so treat the answer as an operational rule, not a footnote.
Available debugging options
Confirm which remote debugging and log verbosity options the version in use exposes for the plugin daemon, and what each one opens. Ask the vendor whether any debugging port is enabled by default and whether it can be bound to a private interface only. A debugging channel that reaches the plugin runtime should never be reachable from user networks, and you should confirm that in your own environment rather than from memory.
Inner API key rotation
Establish whether the shared inner API key between the API service and the plugin daemon can be rotated without downtime, and what the required order of changes is. Check the release notes for the version in use and the token-based authentication changes described in the 1.16.1 notes. Ask the vendor for a documented procedure, then rehearse it on a staging copy before any production change.
Scaling against worker count
Confirm how the plugin daemon behaves as you add api and worker replicas, including whether it can run as a single shared instance, how concurrent plugin invocations are handled and what resource requests to set. Ask the vendor for sizing guidance for your workload and measure memory and latency under a realistic test before you set limits. The Docker Compose minimums are a floor, not a sizing result.
Enterprise exposure of these settings
Ask whether Dify Enterprise exposes the same daemon settings, whether they are managed through its Kubernetes deployment or the Helm values, and whether changes require a support request. The Enterprise resources checklist describes the cluster baseline, but it does not settle which daemon keys are tunable. Get the answer in writing before you plan a Community to Enterprise move, because the configuration path may differ.
How DeployOpen scopes and supports plugin daemon operations
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, including the plugin daemon that a self-hosted Dify depends on. We start from a written scope that names the timeouts, size limits, cache behavior, debug port settings and inner API key handling your environment needs, then deliver and hand over the runbooks your team will use.
How we scope
- Inventory the Dify version, plugin set and where the plugin daemon runs relative to the api service
- Record the timeout, package size and file size values your plugins and workflows require
- Agree in writing which plugin sources, debug port settings and inner API key ownership are in scope
How we build
- Set plugin daemon configuration in your own environment files and deployment manifests under version control
- Test large plugin installs, slow tool calls and model schema refresh behavior before production changes
- Confirm the debug port is closed or restricted in every environment outside development
How we hand over
- Deliver a runbook covering each setting, its default, its owner and the symptom that signals it needs review
- Document the shared inner API key rotation steps, including the order in which api and plugin daemon are restarted
- Walk your operators through log locations, restart procedures and the checks to run after each Dify upgrade
How we support
- Offer ongoing support, upgrade assistance and continuous testing as a retainer once the handover is complete
- Review plugin daemon settings again when Dify releases change the plugin architecture or configuration keys
- Agree response expectations and escalation paths in the written scope before work starts
