Why private Dify plugin distribution needs a deliberate design
An internal team that has built a plugin for a self-hosted Dify now needs it running in several workspaces without lowering the trust bar that production depends on. This page covers three decisions: choosing a distribution channel for the plugin, versioning its releases, and signing its packages so that signature checks stay on in production. Those decisions are easy to make by accident and hard to unwind once several workspaces depend on the package.
Dify is an LLM application development platform released under the Dify Open Source License, a modified Apache License 2.0. The license permits self-hosting for your own use but forbids operating the source code as a multi-tenant environment without written authorization, and it requires the logo and copyright information in the console to stay intact. The Community edition is free and limited to a single workspace. The self-hosted Enterprise edition adds multiple workspaces, SSO and professional support, which matters here because a private plugin reaching several workspaces is the situation where a single-workspace Community install stops being enough. Confirm your workspace count and license position against the Dify LICENSE file and the current Dify pricing page before you commit to a layout.
Plugin architecture, package format and the plugin daemon are covered on the sibling pages, so this page does not repeat them. What is left to decide is who approves a release, who holds the signing key, and how a rollback works. Implementation is scoped in writing, with the channel, version policy and signing workflow agreed before any build starts. Ask your team to name the owner of each decision now, because those owners will be the ones who answer when a workspace fails to install a package.
What private plugin distribution covers in a self-hosted Dify
Private plugin distribution sits between writing a plugin and running it in production. The decisions below connect how a package is built, where it is published, how its versions move through environments, and how signatures are checked before installation. Confirm each capability against the current Dify plugin documentation for your version before you commit to a design.
Packaging a plugin as .difypkg
A plugin is delivered as a .difypkg package, which is the unit every distribution channel moves. Packaging settles the plugin identifier, version number, declared manifest and bundled dependencies, so a mistake here reaches every later stage. Check that the package builds from a tagged source commit, that the manifest version matches the release tag, and that the package installs cleanly into a non-production instance before anything else is done with it.
Choosing the distribution channel
Internal plugins can reach workspaces through the Marketplace, a GitHub repository, or a local .difypkg file uploaded by an administrator. Each channel trades reviewability, access control and audit trail against convenience. Decide who may publish, where the source of truth lives, and whether the channel can be restricted to your network. Confirm with the current plugin documentation which channels your Dify edition supports and how each one is configured.
Controlling versions per environment
Each plugin release should move through the same environments as the application it supports, such as test, staging and production. Pin the version each environment runs, record which release is installed where, and keep the previous package available for rollback. Confirm how Dify handles upgrading an installed plugin in place and whether an older version can be reinstalled without losing workspace configuration.
Signing and verifying packages
Signing ties a package to the key that produced it, so the platform can refuse a file that was changed after release. The main production risk is switching signature checks off to get an install working, which removes the protection for every later package. Confirm the signing tool, the key storage location, how the public key is distributed to the plugin daemon, and the exact behavior when verification fails.
Installing into workspaces
A signed package still has to be installed into each workspace that needs it, and the install record should show who approved it and which version is live. Plan the workspace list up front, so an internal tool does not appear in a workspace where it was never reviewed. Confirm whether the Community edition, which is limited to a single workspace, differs from Enterprise in how installs are distributed and governed.
Operating the plugin daemon
The plugin daemon loads and runs installed packages, so a release that installs cleanly can still fail under load, time out or exceed size limits. Test each new package against the daemon settings used in production, not only against a default local setup. Confirm the timeout and file size settings, and watch daemon logs after each release for errors that only appear once real traffic reaches the plugin.
Choosing Marketplace, GitHub or local .difypkg for internal plugins
This table compares the three distribution channels for an internal Dify plugin across audience, installation rights, update control, network needs, auditability, regulated fit, signing and environment coverage. Read each row as a question to answer for your own environment, and confirm the flagged points with Dify or your platform team before you commit. For most internal plugins, the local package path gives the most control, provided your team runs signing and artifact tracking itself.
| Decision factor | Marketplace | GitHub | Local .difypkg |
|---|---|---|---|
| Intended audience | Published plugins for any Dify user; a weak match for tools that only your organization uses | Teams that already manage code in a repository and want shared access to plugin source | Internal operators who receive a built package from your build process |
| Who can install | Workspace admins with plugin permissions; confirm what your edition allows | Users with repository access who follow the install path your Dify version supports; confirm the path | Anyone with the file and an admin role in the target workspace |
| Update control | Versions follow the publisher's releases; you choose when to upgrade, but not what the publisher ships | Pinned to tags or commits you select, so updates happen only when your team merges and tags a release | Full control: each version is a file your team builds, tests and approves |
| Network dependency | Needs outbound access from the Dify host to the marketplace; confirm the endpoints with the vendor | Needs reachable GitHub access from the install path, which restricted networks often block | No external call once the file reaches the host, which suits isolated networks |
| Auditability | Depends on publisher metadata and changelogs; internal review still requires source access | Commit history, tags and pull request reviews give a clear change trail | Only as strong as the artifact store, checksums and approval records you keep |
| Air-gapped or regulated fit | Usually a poor fit; confirm whether any offline option exists | Weak fit for air-gapped networks; workable only on a mirrored internal git host | Strongest fit, since the package moves through transfer controls you already run |
| Signing decision | Confirm with Dify whether signature checks apply to packages you install and keep them enabled in production | Signing is your responsibility unless your pipeline adds it; confirm the signing format Dify accepts for your version | You control key custody and verification; confirm the signature format and where checks run in your version |
| Environments served (development, staging, production) | Each environment pulls the version it finds; policy must keep versions aligned across all three | Suits development and staging; production should install only tagged, signed releases | Best for promoting one identical, verified file through all three environments |
Rollout sequence from plugin build to signed production release
This sequence moves an internal Dify plugin from an inventory entry to a signed package running in production, with each step closing on a named artifact so the platform team can audit progress. It keeps signature checks enabled from the first production promotion and hands the operating team a runbook they can use without the original builders.
Inventory internal plugins and owners
List every internal plugin or custom tool the organization intends to run, including the systems it calls, the data it touches and the workspaces that will use it. Assign a named owner who answers for code, releases and credentials. Confirm which plugin types each item needs by checking the sibling guidance on plugin types, since a tool plugin and a model plugin have different packaging and trust implications. Done when the team holds an inventory with one owner per plugin and a list of target workspaces.
Select the distribution channel
For each plugin, choose Marketplace, GitHub or a local .difypkg file based on who must see it, how often it changes and where your change control lives. Marketplace listing suits plugins meant for broad external distribution, while private plugins usually move as local packages or from a private repository your organization controls. Record the decision per plugin with the reason. Confirm with your Dify version and administrators how plugin installation is permitted in your deployment before committing to a channel. Output: a channel decision record for each inventory item.
Define version and release rules
Write the rules that map code changes to version numbers, state which branch or tag produces a release candidate, and decide who approves promotion from test to production. Include how a plugin built against one Dify release is tested when the platform itself moves to a newer minor release, since Dify minor releases arrive roughly monthly according to the release history. Output: a short versioning standard and an approval matrix that the owners have signed off.
Set up build and packaging
Configure a repeatable build that produces the .difypkg artifact from a clean checkout, with pinned dependencies and a manifest that matches the released version. Store the output in an artifact location with access controls and retention. Verify that a second person can rebuild the same package from the tagged source. Output: a build pipeline that emits a versioned package and a log showing the source revision it came from.
Establish signing keys and custody
Generate the signing key pair in a controlled environment, store the private key in a managed secrets store or hardware-backed custody, and restrict signing to the build pipeline and named release approvers. Document key ownership, rotation steps and what happens if a key is lost or compromised. Confirm with Dify's plugin documentation the exact signing and verification mechanism your version supports before you rely on it. Output: a key custody record, a rotation procedure and a test package signed and verified successfully.
Test in a non-production instance
Install the signed package on a non-production Dify instance that mirrors production settings, including the plugin daemon configuration, outbound proxy rules and any SSO-linked workspace roles. Exercise each tool or action against a test endpoint, confirm that installation fails when the signature is altered, and record plugin resource behavior under expected load. Output: a test report listing the version tested, the checks passed, and any defects routed back to the owner.
Promote to production with signature checks enabled
Move the same signed artifact that passed testing into production, without rebuilding it, and confirm that signature verification remains on in the production configuration. Check the installed plugin's version and signature state against the release record, and keep the previous approved version available for rollback. Output: a production change record linking the artifact hash, the approver, the verification result and the rollback version.
Hand over a runbook
Write a runbook covering installing and upgrading each plugin, rotating signing keys, rolling back a version, responding to a failed signature check and onboarding a new workspace. Walk the operations team through one upgrade and one rollback on the non-production instance and capture the questions they raised. Output: a signed-off runbook stored with the inventory, with each owner and operator named against the procedures they perform.
How to keep signature checks on in production
The failure to avoid is turning off signature verification so that an unsigned or mis-signed package will install. It is usually done under deadline pressure, when a build from the internal pipeline is rejected and someone wants the workspace unblocked. The cost is that the check was the only thing confirming that the package in production came from your release process. Keeping checks on depends less on any single setting than on who controls the signing key, who approves a release, and what happens when the key is no longer trusted. Treat a request to disable verification as a change that needs the same approval as a production release, and record it if it ever happens.
Start with key ownership. The signing key should be held by a named team, stored in a managed secret store or hardware-backed module, and never kept on a developer workstation or in a repository. Separate the roles that build a .difypkg from the roles that approve it for production. The build pipeline produces the artifact and its signature, while a different approver, or an automated gate that a human signs off, decides which version may be promoted into the production Dify environment. Write down which environment variables and verification options the production API and plugin daemon use, and confirm their names and defaults in the Dify environment variable reference and the release notes for the version you run, because these settings change between releases.
Plan rotation before you need it. Define how often the signing key is rotated, how the new public key reaches each environment, and how packages signed with the old key remain installable during the overlap window, so that rotation does not become a reason to disable checks. If a key is compromised, the response should be scripted in advance: revoke trust in the old key in every environment, rebuild and re-sign the packages still in use, reinstall them from the approved source, and review plugin activity in the period the key may have been misused. Confirm with Dify how revocation is handled in the version you run, since the mechanism is not described in the sources supplied here, and rehearse the procedure in a staging instance first.
What drives the cost and effort of private plugin distribution
This table lists the factors that change how much work private plugin distribution takes and who pays for it. Read each row as a question to answer before requesting a quote, since most drivers multiply each other across workspaces, environments and release cycles.
| Driver | Effect on cost or effort | What to ask for in a written quote |
|---|---|---|
| Number of internal plugins | Each plugin adds its own packaging, versioning, testing and release record. Cost rises with count more than with any single plugin's size. | Per-plugin scope listing plugin type, version policy and who maintains each one after handover |
| Number of workspaces and environments | Community edition is limited to a single workspace, so multi-workspace or staged setups need more install and verification steps per environment. | Environment list with which workspaces install which plugin versions and how promotion is verified |
| Existing CI pipeline | Teams with CI already running can reuse build and signing steps. Without it, the build and release path is added work and a recurring maintenance item. | Confirmation of what CI tooling exists and whether the packaging job will be built into it |
| Air-gap requirements | Offline environments need local .difypkg transfer, internal artifact storage and manual verification, which adds steps to every release. | Description of the transfer path, the approval steps for moving packages in and the evidence kept for each move |
| Signing and key custody needs | Holding signing keys in a controlled store with rotation and access logging adds one-time setup and recurring key management work. | Key generation, storage location, rotation schedule, who holds signing rights and how revocation is handled |
| Dify minor release frequency | Dify minor releases arrive roughly monthly (1.16.0 on July 17, 2026; 1.17.0 on August 25, 2026, per the Dify releases page), so each release can trigger compatibility checks of plugins and the daemon. | Retest scope per Dify minor version, whether upgrades are included in the retainer and how breaking plugin API changes are priced |
| Number of internal reviewers | Each reviewer who must approve a plugin release adds waiting time and a sign-off step. Reviewer availability often sets release pace more than engineering does. | Approval workflow with named roles, expected review turnaround owned by your side and the record kept per release |
How private plugins connect to the rest of the Dify platform
A private plugin touches several parts of a self-hosted Dify at once: the daemon that loads the package, the API service that calls it, the workspace where it is installed, and the internal systems it reaches. Each connection is a place where a release can work in a test workspace and fail or leak in production.
Plugin daemon loads the package
The plugin daemon is the component that loads a .difypkg package and runs its code, so the daemon is where a signature check either passes or fails at install time. Confirm which daemon version your Compose or Helm release runs before you choose a packaging format, because signing and install behavior depend on it. Keep the daemon's timeouts and size limits in mind when a plugin bundles large assets. Operating the daemon in production is covered in the sibling topic on the plugin daemon.
API service calls the plugin
The Dify API service sends tool and model requests to the plugin daemon, and the Dify docs describe token-based authentication between services as part of the 1.16.1 security changes. A plugin release that changes its declared tools or credential schema affects what the API service expects, so test the API and daemon together. Ask your vendor or your own test plan to confirm how the internal service token is rotated during an upgrade.
Workspace and installation scope
A plugin is installed into a workspace, and in Community edition that means a single workspace. Each installed version is a separate decision for the people who administer that workspace, so a release can reach some workspaces before others. Record which workspace runs which plugin version in your release log. Policy for installing one approved version across many workspaces belongs to the Enterprise plugin installation policy topic.
Internal systems and their credentials
Most private plugins exist to call an internal system such as a ticketing API, document store or CRM. The credential the plugin uses is a separate secret from the Dify secrets, and its scope decides what a compromised workflow can read or change. Ask the owner of each internal system for a service identity with the narrowest permissions the plugin needs, and document who rotates it and how the rotation reaches the plugin configuration.
SSRF proxy and outbound allowlist
Dify routes outbound requests through an SSRF proxy that blocks internal and private IP ranges, which means a plugin calling an internal host can fail even when the host is reachable from your network. Your plugin needs an explicit path to that host through the proxy configuration, and that path should be as narrow as the use case allows. The Dify environment reference describes the SSRF_PROXY settings, so review them with your network team before the first production install.
Source control and build pipeline
The package that reaches production is only as trustworthy as the pipeline that built it. Source control holds the plugin code, the CI system builds and tags the .difypkg, and the signing key should live outside the repository, in a store that only the release job can read. Decide who can approve a release tag, keep build logs with the artifact hash, and make sure the same signed file is what gets installed in every environment.
Versioning internal plugin releases alongside Dify upgrades
Version each internal plugin package on its own schedule, separately from the Dify release it runs on. A .difypkg carries its own version in its manifest, so a plugin release number tells the reader what changed in the plugin, while the Dify version tells them which platform it was tested against. Record both in your release log, along with the package checksum and the signing key used. Keep the compatibility claim explicit: a plugin that was approved on one Dify minor release has been verified on that release only. Confirm the minimum Dify version declared in your plugin manifest with the plugin developer documentation before you publish.
Dify minor releases arrive roughly monthly, according to the release history on the langgenius/dify GitHub releases page, so a plugin will be exposed to a platform change several times a year. Treat every Dify upgrade as a trigger to retest each internal plugin, including the plugin daemon behavior it depends on, even when the plugin code has not changed. Follow the upgrade guide for the target version, and take a backup before every upgrade, as the Docker Compose documentation recommends. After upgrading, compare your .env file with .env.example in the new release, because new variables may affect how the plugin daemon and the API service communicate.
Pin the approved plugin version separately in each environment. A common pattern is to promote the same signed package from a test instance to staging and then to production, recording the Dify version, plugin version and checksum at each step. Production should only install a version that has passed retesting on the exact Dify release it runs, so an upgrade of Dify becomes a planned change with a documented plugin check. Ask your plugin team to confirm how the installed version is recorded in the environment and how a rollback to the previous signed package would be performed if a new Dify release breaks a tool.
Questions teams ask before bringing in a partner for plugin distribution
What does private plugin distribution cost, and what drives the price?
The cost has three parts: scoping, the build and release pipeline, and handover. Scoping covers which plugins exist, which Dify versions and instances they target, and which distribution route each plugin uses. The build covers packaging each plugin as a .difypkg file, setting up signing and a repeatable release process, and documenting installation. Handover covers training the people who will run the process after the engagement. The Community edition of self-hosted Dify is free but limited to a single workspace, while the self-hosted Enterprise edition is custom priced, according to the Dify pricing page. Recurring cost comes from keeping plugins compatible as Dify ships minor releases roughly monthly. Ask for a quote built from a written scope that lists each plugin, each environment and each release step.
How long does setting up private plugin distribution usually take?
Duration depends mainly on how many plugins you distribute, whether they already exist as working code, and how mature your CI pipeline is. Other drivers include the number of Dify instances and environments that receive plugins, the signing key decision, and how many approvals each release needs from your security or platform team. Plugins that still need building add more time than plugins that only need packaging and signing. No duration is fixed in advance. A fixed-scope agreement sets the timeline in writing before work starts, so ask the partner to tie each milestone to a named deliverable and to a named owner on your side who can approve it.
What must our team provide before a partner starts plugin work?
Your team needs to supply the inputs that the work cannot invent. The main items are:
- Plugin source code, or a written specification for plugins that do not exist yet
- A named owner for each plugin who can answer questions and approve releases
- CI runner access and repository permissions that match your current source control policy
- A key custody decision: who holds the signing key, where it is stored, and who can rotate it
- The Dify versions and environments each plugin must support
- The network path from Dify to the internal systems each plugin calls
Confirm these items with your platform and security leads before the scoping call, since missing key custody decisions are a common reason for delay.
Can one internal engineer set up plugin distribution without a partner?
Yes, if that engineer already knows Dify plugin packaging, can run a signing workflow and has time to maintain it through each release. The harder part is ongoing operation. Dify has shipped minor releases roughly monthly, so someone must check each plugin against new versions and rebuild releases when needed. A single engineer also creates a single point of knowledge, which matters for key handling and incident response. Ask yourself three questions: who approves a release, who rotates the key, and who responds if a signed package fails verification in production. If two or more people can answer all three, an internal build is a reasonable option. Confirm current packaging steps in the Dify plugin documentation before committing.
Does Dify Enterprise change how we distribute internal plugins?
Enterprise changes the surrounding platform more than the packaging steps. According to the Dify pricing page, the Enterprise edition adds SSO, multiple workspaces, advanced security, a commercial license and professional support, and it is custom priced. The Dify Enterprise resources checklist lists Kubernetes 1.24 or later, Helm 3.14 or later, PostgreSQL 14 or later and Redis 6 or later, so distribution that spans several workspaces or clusters needs a deployment plan first. Controls for which plugin sources each workspace may install from are a separate question. Confirm with Dify how Enterprise manages plugin installation policy and whether one approved plugin version can be applied across all workspaces before you design the release flow.
What should a partner not be expected to deliver for plugins?
A partner should not be expected to issue audit reports, attestations or certifications for your plugins or your Dify deployment. DeployOpen prepares systems, controls and evidence for compliance assessments, but independent auditors and certification bodies issue the outcomes. A partner also cannot promise that a Marketplace listing will be accepted or that a vendor will approve a plugin. Keep these boundaries in the written scope. Ask the partner which evidence it will hand over, such as build records, signing procedures and release logs, and which decisions stay with your own security and compliance owners, such as risk acceptance for each plugin.
Does signing a plugin package make it safe to run?
No. A signature check confirms that a package came from the holder of the signing key and that its contents have not changed since signing. It does not review what the code does, whether its dependencies are safe, or whether it calls systems it should not. Keep signature checks enabled in production, and confirm in the Dify documentation how verification is configured for your version. Separately, review each plugin's code, its outbound calls and its credential handling before the first release, and test it against the network controls that already apply to your Dify deployment. Treat the signing key as a high-value secret with a documented owner and rotation procedure.
How DeployOpen scopes and delivers private plugin distribution
DeployOpen starts private plugin distribution with a written scope that settles the plugin inventory, the distribution channels, the environments and the signing approach before any build work begins. For each internal plugin, the scope should name the plugin type, the owning team, the channel it ships through (Marketplace, GitHub or a local .difypkg file), the version scheme, and who holds the signing key. It should also state which Dify environments receive each release and which ones only test it. DeployOpen is a Chainscore Labs company, and it does not publish a price list. A quote follows from that written scope, so the more precisely the plugins, channels and environments are listed, the more precisely the quote can reflect the work.
Delivery covers the distribution setup itself and a runbook that your operators can follow without DeployOpen in the room. The runbook documents how a release is packaged, how it is signed, how the signature is verified before installation, how a rollback is performed and who approves a production change. DeployOpen tests the full path in a non-production Dify instance first, including installing a signed package, upgrading it and confirming that an unsigned or altered package is refused, so that the first real release does not become the first test. Your team should confirm which Dify version and plugin daemon configuration the test environment must match, and whether your production instance will run with signature checks enforced.
After delivery, most organizations keep a small ongoing need: a new plugin version for each Dify minor release, key rotation, and review of plugin behavior when Dify changes its plugin interfaces. DeployOpen offers ongoing support and upgrade retainers for this work, and these are agreed separately from the initial fixed-scope engagement. Ask for the retainer terms in writing, including what is covered for upgrades to a new Dify release, how urgent security fixes are handled, and who on each side is responsible for signing keys. Those answers, more than the initial build, determine whether private plugins stay trusted over time.
