createOracleApp

​

Overview

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

​

CreateOracleAppOptions

export interface CreateOracleAppOptions {
  config: OracleConfig;
  features?: Partial<Record<BundledFeatureName | (string & {}), FeatureToggle>>;
  plugins?: OraclePlugin[];
  nestModules?: Array<Type | DynamicModule>;
  authExcludedRoutes?: AuthExcludedRoute[];
  bundledPlugins?: OraclePlugin[];
  env?: NodeJS.ProcessEnv;
  skipMatrixInit?: boolean;
  skipGracefulShutdown?: boolean;
  logger?: Logger;
  hooks?: MainAgentHooks;
}

config: {
  name: 'My Oracle',
  org: 'My Org',
  description: 'What this oracle is for',
  prompt: {
    opening: '...',
    communicationStyle: '...',
    capabilities: '...',
  },
}

config: {
  name: 'Aria',
  org: 'Acme Climate',
  description: 'A carbon-project advisory oracle for Acme Climate portfolio managers.',
  prompt: {
    opening: `You are Aria, the carbon-project advisory oracle operated by Acme Climate.
You help portfolio managers track project status, assess methodology compliance,
and draft stakeholder communications. You have deep knowledge of Verra VCS,
Gold Standard, and REDD+ frameworks.`,
    communicationStyle: `Be precise and data-driven. Lead with numbers and deadlines.
Use plain English — avoid jargon unless the user demonstrates familiarity.
When something is uncertain, say so explicitly rather than hedging with filler phrases.`,
    capabilities: `## What Aria can do
- Retrieve live project status and registry issuance data via the IXO domain indexer.
- Draft verification reports, CORSIAs letters, and board summaries.
- Search and cite methodology documents from the oracle knowledge base.
- Schedule follow-up reminders and track open action items across conversations.`,
  },
}

features: {
  slack: false,
  composio: true,
  domainIndexer: 'auto',
}

import { RequestMethod } from '@nestjs/common';

authExcludedRoutes: [
  { path: 'version', method: RequestMethod.GET },
]

​

OracleApp

export interface OracleApp {
  getNestApp(): INestApplication;
  ambient: AmbientServices;
  plugins: { status(): PluginStatusReport };
  beforeListen(fn: (nestApp: INestApplication) => Promise<void> | void): void;
  onError(handler: (err: Error, source: string) => void): void;
  onPluginStatusChange(handler: (event: PluginStatusChangeEvent) => void): void;
  listen(port?: number): Promise<void>;
}

{
  loaded: string[];
  excluded: Array<{ plugin: string; reason: string }>;
  softDepGaps: Array<{ plugin: string; missing: string }>;
}

{ plugin: 'matrix', from: 'pending', to: 'loaded' | 'failed', reason?: string }

​

Behaviour

1. Validates config (name required).
2. Resolves plugin set: bundled + your plugins, deduped by name, with features toggles and autoDetect predicates applied. Excluded plugins surface in plugins.status().excluded with their reason.
3. Topologically sorts by dependsOn. Cycles or missing hard deps fail boot.
4. Validates every plugin’s manifest. Hard violations fail boot.
5. Composes env schema (base + all loaded plugins’ configSchema) and validates process.env. Missing required vars fail boot with [boot-error] Plugin '<name>' env validation failed for '<field>'.
6. Cross-field check: the API key for the selected LLM_PROVIDER is present. (Schema-merge can’t express this.)
7. Builds the internal OracleIdentity from config + validated env.
8. Populates the six registries (tools, sub-agents, middleware, manifests, configSchema, sharedState).
9. Collects getNestModules from every loaded plugin.
10. Builds the dynamic RuntimeAppModule and bootstraps NestJS (NestFactory.create). CORS enabled with the framework’s allowed headers. Swagger UI mounts at /docs.
11. Builds AmbientServices.
12. Warms the boot caches (each registry runs its boot-time hooks once).
13. Wires the default checkpointer (UserMatrixSqliteSyncService + SqliteSaver), then merges host hooks over it.
14. Populates the OracleRuntimeBundleHolder so MessagesController can read it on each request.
15. Schedules background Matrix init (unless skipMatrixInit: true). Registers a graceful-shutdown handler (unless skipGracefulShutdown: true).
16. Returns the OracleApp.

​

Throws

• Error('createOracleApp: \'config\' is required.') — config missing.
• Error('createOracleApp: \'config.name\' is required.') — config.name empty.
• Plugin resolution errors (cycle, missing hard dep, manifest invalid, env invalid). Each error is reported via logger.error with [boot-error] … prefix and a remediation hint.
• Error('createOracleApp: ORACLE_ENTITY_DID env is required and was empty after validation.') — when the validated env’s ORACLE_ENTITY_DID is empty.
• Error('OracleApp.listen called twice.') — when listen() is called more than once.

​

Related guides

• Create your oracle — hands-on walkthrough.
• Using bundled plugins — the features field in detail.
• Plugin API reference — what plugin instances must implement.