> ## Documentation index
> Fetch the complete documentation index at: https://dify-docs.docs7.io/llms.txt
> Ask it with GET https://dify-docs.docs7.io/ask?q=<keywords or question>. Short keywords rank best.
> Use these to discover all available pages before exploring further.

# Plugin Debugging

> Run your in-development plugin locally and attach it to a live Dify workspace for end-to-end testing, no packaging required

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](/en/develop-plugin/getting-started/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.

<Tabs>
  <Tab title="Dify Cloud">
    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.
  </Tab>
  <Tab title="Self-hosted">
    The host defaults to `127.0.0.1:5003` and is configured by `PLUGIN_REMOTE_INSTALLING_HOST` / `PLUGIN_REMOTE_INSTALLING_PORT` in the plugin daemon's environment. Make sure port `5003` is reachable from your dev machine. If Dify runs in Docker on the same host, use the daemon container's bridge IP (or expose the port).
  </Tab>
</Tabs>

## Step 2: Configure the Plugin's `.env`

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

```bash
INSTALL_METHOD=remote
REMOTE_INSTALL_URL=debug-plugin.dify.dev:5003
REMOTE_INSTALL_KEY=********-****-****-****-************
```

<Note>
  `REMOTE_INSTALL_URL` is the combined `host:port` from Step 1, not two separate variables.
</Note>

## Step 3: Run the Plugin

From the plugin project directory:

```bash
pip install -r requirements.txt
python -m main
```

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.
</Check>

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

<AccordionGroup>
  <Accordion title="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**.
  </Accordion>
  <Accordion title="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.
  </Accordion>
  <Accordion title="`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.
  </Accordion>
  <Accordion title="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`.
  </Accordion>
</AccordionGroup>

## Related Resources

- [CLI](/en/develop-plugin/getting-started/cli)—Scaffold a plugin and set up `.env`
- [Plugin Logging](/en/develop-plugin/features-and-specs/plugin-types/plugin-logging)—Emit structured logs from inside your plugin
- [Package as Local File and Share](/en/develop-plugin/publishing/marketplace-listing/release-by-file)—Ship the plugin once debugging is done