Skip to main content

Remote debugging is the fastest way to iterate on a plugin. You run the plugin process on your laptop, and Dify treats it as if it were installed in the workspace. Save your edits and restart the process, and the changes take effect immediately.

Prerequisites#

  • A Dify workspace where you can open Debugging in Integrations. It appears only for members allowed by the Who can debug? setting, which the workspace owner and admins control.
  • A scaffolded plugin project (see CLI if you haven’t created one yet).
  • Python 3.12 and the plugin’s dependencies installed (pip install -r requirements.txt).

Step 1: Get the Debug URL and Key#

In Integrations, click Debugging at the bottom of the sidebar, then copy both the port and key values.

The host is something like debug-plugin.dify.dev:5003. The key is unique to your workspace; anyone with the key can attach a plugin, so do not share it.

Step 2: Configure the Plugin’s .env#

In your plugin project, copy .env.example to .env and fill in the values:

Note

REMOTE_INSTALL_URL is the combined host:port from Step 1, not two separate variables.

Step 3: Run the Plugin#

From the plugin project directory:

The process stays in the foreground and logs incoming invocations. Edit your code and restart the process to apply changes.

Step 4: Verify the Install#

Back in Integrations, find the plugin in the section for its type, for example with the tool plugins if you built a tool.

Check

The plugin tile shows a debug indicator and your local terminal logs the first registration handshake. You’re attached.

Other members of the workspace can also see and use it, but only while your local process is connected.

Trigger the plugin as you would any other: call it from a workflow node, run it as a tool inside an Agent, or hit an endpoint URL. Invocations land on your local process and you can attach a debugger.

Troubleshooting#

Connection refused / cannot reach host

The daemon is not listening on the address you put in REMOTE_INSTALL_URL. On self-hosted setups, confirm the daemon container has PLUGIN_REMOTE_INSTALLING_ENABLED=true and that port 5003 is exposed. On cloud, double-check you copied the host:port exactly as shown in Debugging.

Plugin starts but never appears in the plugin list

The most common cause is a stale or wrong REMOTE_INSTALL_KEY. Copy the current key from Debugging into .env and rerun python -m main. Also confirm the daemon log shows the incoming registration.

`plugin_unique_identifier is not valid`

The author field in manifest.yaml or in provider/*.yaml doesn’t match a value the daemon accepts. Set it to your GitHub handle, then restart.

Changes don't take effect

The plugin process needs to restart after every edit; there’s no hot reload. Stop with Ctrl+C and rerun python -m main.