# How to Develop and Install Plugins Using the Paperclip Local Plugin Runtime

> Learn to develop and install plugins with the Paperclip local plugin runtime. Use the plugin SDK and CLI commands to author and execute plugins locally without cloud deployment.

- Repository: [Paperclip/paperclip](https://github.com/paperclipai/paperclip)
- Tags: how-to-guide
- Published: 2026-08-18

---

**The Paperclip local plugin runtime enables developers to author, install, and execute plugins locally using the `@paperclipai/plugin-sdk` package and CLI commands without requiring cloud marketplace deployment.**

The `paperclipai/paperclip` repository ships an early local plugin runtime that transforms how developers extend Paperclip functionality. This runtime allows you to develop plugins using a dedicated SDK, install them directly from local paths or npm, and manage their lifecycle through a comprehensive CLI—all while maintaining complete isolation via worker processes.

## Understanding the Local Plugin Runtime Architecture

The Paperclip plugin runtime consists of several coordinated components that manage plugin discovery, validation, and execution.

### Core SDK Components

The **`@paperclipai/plugin-sdk`** provides the foundational APIs for plugin development. The `definePlugin()` function, implemented in [`packages/plugins/sdk/src/define-plugin.ts`](https://github.com/paperclipai/paperclip/blob/main/packages/plugins/sdk/src/define-plugin.ts) at line 520, serves as the single entry point for declaring a plugin's capabilities, UI components, and actions. The `runWorker()` function, defined in [`packages/plugins/sdk/src/worker-rpc-host.ts`](https://github.com/paperclipai/paperclip/blob/main/packages/plugins/sdk/src/worker-rpc-host.ts) at line 273, launches the plugin in its own process and establishes RPC communication with the host.

### Manifest Configuration

Every plugin requires a [`manifest.ts`](https://github.com/paperclipai/paperclip/blob/main/manifest.ts) file that declares the plugin's metadata, including its unique ID, version, SDK compatibility range (`sdkVersion`), UI slots, capabilities, and required secrets. The host validates this manifest during installation to ensure version compatibility (e.g., `">=1.4.0 <2.0.0"`).

### CLI Installation Commands

The **`paperclipai` CLI** provides essential plugin management commands:

- `plugin init` – Scaffolds a new plugin skeleton
- `plugin install <path|npm>` – Installs a plugin from a local directory or npm package
- `plugin list` – Displays installed plugins and their status
- `plugin uninstall` – Removes a plugin with a 30-day grace period

According to the plugin specification at [`doc/plugins/PLUGIN_SPEC.md`](https://github.com/paperclipai/paperclip/blob/main/doc/plugins/PLUGIN_SPEC.md) (lines 248-251), the install command writes a record to the Postgres `plugins` table and copies the package into the host's plugin directory.

### Host Process and Hot-Reloading

On startup, the host process reads persisted installation records from the `plugins` table, loads each package, and launches dedicated workers via `runWorker()`. The runtime supports **hot-install**, **hot-uninstall**, and **hot-upgrade** capabilities without requiring a server restart, enabling rapid development cycles. Plugin code resides in a writable `plugins/` directory, making the runtime global to the Paperclip instance.

## Creating Your First Plugin

Developing a plugin requires scaffolding the project structure and implementing the core plugin definition.

### Scaffolding a New Plugin

Initialize a new plugin using the CLI:

```bash
npx paperclipai plugin init my-plugin

```

This command generates a skeleton structure including [`manifest.ts`](https://github.com/paperclipai/paperclip/blob/main/manifest.ts), [`worker.ts`](https://github.com/paperclipai/paperclip/blob/main/worker.ts), and [`package.json`](https://github.com/paperclipai/paperclip/blob/main/package.json) with the SDK pre-configured.

### Minimal Plugin Implementation

Create a functional plugin by exporting a sealed plugin object via `definePlugin()`:

```typescript
// src/worker.ts
import { definePlugin, runWorker } from "@paperclipai/plugin-sdk";
import { z } from "@paperclipai/plugin-sdk";

const plugin = definePlugin({
  id: "hello-world",
  version: "0.1.0",
  sdkVersion: ">=1.4.0 <2.0.0",
  
  ui: {
    slots: [{ 
      id: "plugin-hello", 
      title: "Hello", 
      component: "./ui/hello.tsx" 
    }],
  },

  actions: {
    greet: {
      description: "Return a greeting string",
      input: z.object({ name: z.string() }),
      output: z.string(),
      async run({ input }) {
        return `Hello, ${input.name}!`;
      },
    },
  },

  async setup() {
    console.log("Hello-World plugin started");
  },
});

runWorker(plugin, import.meta.url);

```

The `definePlugin()` function validates the definition and seals the plugin object, while `runWorker()` initiates the child process and establishes the RPC channel with the host. The SDK exports `z` for schema validation to ensure type-safe action inputs and outputs.

## Installing Plugins into the Local Runtime

Once developed, plugins must be installed into the running Paperclip instance to become available to agents and the UI.

### Local Installation Workflow

Install your plugin from a local directory during development:

```bash

# Install the local plugin

npx paperclipai plugin install ./my-plugin

# Verify installation status

npx paperclipai plugin list

```

For production distribution, install directly from npm:

```bash
npx paperclipai plugin install package-name@version

```

During installation, the CLI runs `npm install` in the host's plugin directory (as implemented in [`packages/plugins/create-paperclip-plugin/src/index.ts`](https://github.com/paperclipai/paperclip/blob/main/packages/plugins/create-paperclip-plugin/src/index.ts) at line 350), ensuring all dependencies resolve correctly.

### Installation Mechanics and Validation

The installation process performs several critical validation steps:

1. **Manifest validation** – Verifies that the plugin's `sdkVersion` range satisfies the host's installed SDK version
2. **Persistence** – Records the installation in the Postgres `plugins` table with fields for `plugin_id`, `installed_at`, `status`, and `install_order`
3. **Worker initialization** – Immediately starts a dedicated worker process via `runWorker()`

The host serves UI bundles from the endpoint `/_plugins/:id/ui/:version/`, making components available to the frontend instantly after installation.

## Calling Plugin Actions from Agents

Once installed, agents can invoke plugin actions through the API:

```typescript
const result = await agentApi.runAction({
  pluginId: "hello-world",
  action: "greet",
  input: { name: "Alice" },
});
// Returns: "Hello, Alice!"

```

The runtime routes these calls through the worker RPC host to the appropriate plugin process, maintaining isolation while enabling seamless integration with agent workflows.

## Summary

- The Paperclip local plugin runtime uses `@paperclipai/plugin-sdk` with `definePlugin()` and `runWorker()` as core APIs for plugin development.
- Plugins are installed globally via the `paperclipai` CLI using `plugin install <path|npm>`, which validates manifests and persists records to Postgres.
- The architecture supports hot-installation and hot-upgrades without server restarts, enabling rapid development workflows.
- Workers run in isolated processes communicating via RPC, with UI bundles served dynamically from `/_plugins/:id/ui/:version/`.
- The `plugins` table tracks installation state, while the `plugin_state` and `plugin_entities` tables store runtime data subject to 30-day grace periods upon uninstallation.

## Frequently Asked Questions

### How does the Paperclip local plugin runtime handle plugin updates?

The runtime supports hot-upgrades by detecting file changes during development and automatically stopping old workers before spawning updated ones. For production updates, running `npx paperclipai plugin install` with a new version updates the package in the host directory and restarts the worker process without requiring a full server restart.

### What SDK version constraints are required for local plugins?

Plugins must specify an `sdkVersion` range in their manifest (e.g., `">=1.4.0 <2.0.0"`) that satisfies the host's installed SDK version. The host validates this compatibility at installation time, refusing to load plugins with incompatible SDK requirements to ensure API contract adherence.

### Can I distribute Paperclip plugins via npm?

Yes, plugins are distributed as standard npm packages. The `plugin install` command accepts either a local filesystem path or an npm package specifier (including version tags), and the host runs `npm install` in the plugin directory to resolve dependencies, supporting complex dependency graphs and semantic versioning.

### How does plugin isolation work in the local runtime?

Each plugin runs in its own child process launched by `runWorker()` from [`packages/plugins/sdk/src/worker-rpc-host.ts`](https://github.com/paperclipai/paperclip/blob/main/packages/plugins/sdk/src/worker-rpc-host.ts). The Worker RPC Host manages communication between the main Paperclip process and plugin workers via RPC channels, ensuring that plugin crashes or resource consumption do not affect the host system or other plugins.