Creating a plugin host

Create an independent service with @remedia/plugin-host, register operations, then choose direct dispatch or an HTTP adapter. Operations can return JSON data or encoded audio.

npm install @remedia/plugin-host

The package requires Node.js 22.18 or newer, uses standard Fetch APIs, and starts no listener until your application supplies one. Register a deployed service with the server CLI.

Define and call operationsCopy Anchor Link

Declare operation inputs and outputs once. Register initialized plugins with explicit schemas. Operation names and semantics belong to the application.

import { createPluginHost, type Operation } from '@remedia/plugin-host';

type Operations = {
  resolve: Operation<{ id: string }, { id: string; title: string }>;
};
const host = createPluginHost<Operations>({ name: 'My Host' });
host.register<Operations>({
  id: 'example.source',
  operations: {
    resolve: async ({ id }, { signal }) => {
      signal.throwIfAborted();
      return { id, title: 'Example' };
    },
  },
});
try {
  const outcome = await host.handle({
    pluginId: 'example.source',
    operation: 'resolve',
    input: { id: '123' },
  });
  if (outcome.handled) console.log(outcome.result.title);
} finally {
  await host.close();
}

Direct dispatch passes input and result objects by reference. Returning undefined declines the request. See the host API for registration rules, typed schemas, cancellation, and cleanup.

Register the host with RemediaCopy Anchor Link

Once the host is reachable over HTTP, add it to your server configuration:

remedia-server plugins install https://plugins.example.com --token-env REMEDIA_PLUGIN_TOKEN

The command discovers your host's operations and lets you choose which ones Remedia may run. Then see Playing audio through plugins and Executing plugin operations. Lifecycle, cancellation, the HTTP protocol and error codes are in the @remedia/plugin-host reference.

Detailed referencesCopy Anchor Link

• Serve a plugin host
• Return encoded audio