Enable bundled plugins

Toggle the 14 bundled QiForge plugins via the features map — opt out, force on, or let auto-detect handle it — and retune their manifests.

Copy-paste recipe

The whole API is a features map handed to createOracleApp. Each key is a bundled plugin name, each value is true / false / 'auto'.

import { createOracleApp } from '@ixo/oracle-runtime';
import { config } from './config.js';

const app = await createOracleApp({
  config,
  features: {
    composio: true,       // force on (set COMPOSIO_API_KEY)
    'matrix-group-chats': false,  // force off
    firecrawl: 'auto',    // same as omitting — runs autoDetect
  },
  plugins: [],            // your own plugins go here
});

await app.listen();

That’s the whole surface. The runtime pre-loads every bundled plugin instance from BUNDLED_PLUGINS; features only controls which ones survive resolution. Reference oracle: apps/qiforge-example/src/main.ts.

How resolution works

1. The runtime starts with the bundled list

   BUNDLED_PLUGINS is a fixed 14-plugin tuple — memory, portal, firecrawl, domain-indexer, composio, sandbox, skills, editor, agui, tasks, user-preferences, matrix-group-chats, vfs, oracle-payments.

   You do not import or instantiate the plugins you want at defaults — they are already there. credits, slack, calls, and flows are not in the tuple: features never reaches them, so you construct each one and pass it in plugins.

2. Each plugin gets a feature decision

   For every bundled plugin, resolvePlugins reads features[plugin.name]:

   type FeatureToggle = boolean | 'auto';
   
   features?: Partial<Record<string, FeatureToggle>>;
   

   Value	Behaviour
   true	Force the plugin on. If its autoDetect(env) returns false, boot fails with boot.plugin.env_missing.
   false	Force the plugin off. Skip autoDetect entirely.
   'auto' (or omitted)	Run plugin.autoDetect(env). Include if true, exclude otherwise.

3. Your own plugins are added next

   Plugins from the plugins: [] array are always loaded — they’re not gated by features. If a name collides with a bundled plugin, your instance wins (the loader dedupes by name).

4. Hard-dep cascades resolve transitively

   If a loaded plugin has dependsOn: ['removed-plugin'] and that dep ended up excluded, the dependent cascades off too. Soft deps (softDependsOn) only log a warning.

What every bundled plugin does by default

Each plugin’s autoDetect predicate decides whether to opt in when you leave it on 'auto'.

Plugin	Auto-detects when	Notes
memory	MEMORY_MCP_URL set	Visibility always
portal	always on	Visibility on-demand
firecrawl	FIRECRAWL_MCP_URL set	Visibility on-demand
domain-indexer	always on	Visibility on-demand
composio	COMPOSIO_API_KEY set	Visibility on-demand
sandbox	SANDBOX_MCP_URL set	Visibility always
skills	always on	Visibility always; depends on sandbox
editor	always on	Visibility on-demand — auto-loaded whenever the request carries an active editor session (editorRoomId/spaceId), no load_capability step needed. Needs matrixClient — instantiate explicitly
agui	always on	Visibility on-demand
tasks	REDIS_URL set	Visibility on-demand; BullMQ-backed async tasks (needs REDIS_URL)
user-preferences	always on	Visibility always
matrix-group-chats	always on	Visibility on-demand; gating middleware + tools fire only in Matrix group rooms (memberCount > 2)
vfs	always on	Visibility on-demand, except vfs_search + vfs_read which are per-tool always so file recall needs no load step. Worker URLs derived from NETWORK. Contributes tools only when the oracle has a UCAN signing key and the user granted filesystem access
oracle-payments	unless ORACLE_PAYMENTS_DISABLED=true	Visibility always; Matrix-only commerce lane. A no-op until the oracle publishes an Agent Card, and paid work needs EVAL_ENGINE_URL

Full per-plugin env vars: plugin catalog and environment variables reference.

Opt out of a plugin

1. Set the feature flag to false

   const app = await createOracleApp({
     config,
     features: {
       composio: false,
       'domain-indexer': false,
     },
   });
   

   The plugin is dropped before autoDetect runs. Its configSchema is also removed from the merged env schema, so its env vars become optional.

2. Check for dependents

   If another loaded plugin lists the disabled plugin in its dependsOn, boot fails with a boot.plugin.dep_missing error naming both. Disable the dependent too, or keep the dependency loaded.

Force a plugin on

1. Set the feature flag to true

   const app = await createOracleApp({
     config,
     features: {
       composio: true,
     },
   });
   

   The plugin loads even if autoDetect would skip it.

2. Set every env var the plugin needs

   With features: { composio: true } and no COMPOSIO_API_KEY, the runtime throws at boot:

   boot.plugin.env_missing: plugin 'composio' enabled via features but precondition failed (COMPOSIO_API_KEY).
   Set the required env or disable: features: { composio: false }
   

   See the plugin’s page in the plugin catalog for its full env requirements.

Plugins that are not bundled

credits, slack, calls, and flows ship inside @ixo/oracle-runtime but are absent from BUNDLED_PLUGINS, so features never reaches them. Load one by constructing it and passing it in plugins — anything in that array loads unconditionally.

The same array is how you replace a bundled plugin with a custom-constructed instance (the loader dedupes by name, and yours wins). editor is the usual case: the bundled instance builds its own Matrix client from the MATRIX_* admin env vars, so pass matrixClient only to reuse a client your app already keeps synced.

import { createOracleApp, EditorPlugin, CreditsPlugin } from '@ixo/oracle-runtime';
import * as sdk from 'matrix-js-sdk';
import Redis from 'ioredis';

const matrixClient = sdk.createClient({
  baseUrl: process.env.MATRIX_BASE_URL!,
  userId: process.env.MATRIX_ORACLE_ADMIN_USER_ID!,
  accessToken: process.env.MATRIX_ORACLE_ADMIN_ACCESS_TOKEN!,
});

const redis = process.env.REDIS_URL ? new Redis(process.env.REDIS_URL) : null;

const app = await createOracleApp({
  config,
  plugins: [
    new EditorPlugin({ matrixClient }),                              // overrides the bundled instance
    ...(redis ? [new CreditsPlugin({ redis, network: 'devnet' })] : []), // not bundled — this is the only way it loads
  ],
});

Live example: apps/qiforge-example/src/main.ts.

credits without a Redis client loads in pass-through mode and skips the settlement cron. Since it is also where LLM token metering lives, an oracle that never wires it has no metering at all.

Retune a bundled plugin’s manifest

features decides whether a bundled plugin loads. To change how it’s advertised — most usefully its visibility tier, but also summary, tags, or whenToUse — use manifestOverrides instead of forking the plugin. The override is shallow-merged onto the plugin’s own manifest at boot, validated like any authored manifest, and seen by every downstream reader (Tier-1 prompt, list_capabilities / load_capability, visibility index).

const app = await createOracleApp({
  config,
  manifestOverrides: {
    // Promote an `on-demand` bundled plugin into the Tier-1 prompt so the
    // agent sees it without a `load_capability` step.
    'domain-indexer': { visibility: 'always' },
    // Hide a transport plugin entirely; its tools still bind.
    portal: { visibility: 'silent' },
  },
});

Override keys that don’t match a loaded plugin are logged (boot.plugin.manifest_override_unknown) and ignored — so disabling a plugin via features and leaving its override entry behind is safe.

Inspect what loaded

1. Read app.plugins.status() after boot

   const status = app.plugins.status();
   // {
   //   loaded: ['memory', 'domain-indexer', 'editor', 'user-preferences', 'weather'],
   //   excluded: [
   //     { plugin: 'composio', reason: 'auto-detect precondition not met (COMPOSIO_API_KEY)' },
   //     { plugin: 'tasks',    reason: 'feature flag set to false' },
   //   ],
   //   softDepGaps: [],
   // }
   

   Each excluded entry is { plugin, reason } — surface the reason in your boot logs so operators see why a plugin came up missing. (softDepGaps entries are { plugin, missing }.)

Where to read next

Plugin catalog

Every bundled plugin in detail.

Environment variables

Core vars plus per-plugin vars.

createOracleApp reference

Every option, exhaustively.

Write a plugin

Build your own next to the bundled set.