Build an Oracle

QiForge is the framework for shipping Agentic Oracles — governed AI evaluators and workflow actors with verifiable identity, encrypted per-user storage, and a plugin runtime you wire up in ~30 lines of TypeScript.

An Agentic Oracle is a governed AI evaluator and workflow actor. It performs P-Functions over verifiable state—turning claims, evidence, models, and context into accountable intelligence: typed facts, predictions, recommendations, attestations, determinations, risk signals, compliance checks, payment triggers, and permitted workflow actions.

Unlike a generic AI agent, an oracle is identity-bound, authority-scoped, evidence-grounded, protocol-governed, and audit-producing. Unlike a blockchain or data oracle, it does not merely relay information; it evaluates what information means, which rules apply, which actions are allowed, and what proof must be left behind.

QiForge ships the runtime for that pattern: verifiable identity (IXO entity DID), UCAN delegation, encrypted per-user Matrix storage, and typed plugins (@ixo/oracle-runtime). Your oracle is a main.ts plus the plugins you want. For the full concept model, see Agentic Oracles.

What QiForge does for you

import { createOracleApp } from '@ixo/oracle-runtime';
import { MyPlugin } from './plugins/my-plugin/my-plugin.plugin.js';

const app = await createOracleApp({
  config: { name: 'My Oracle', org: 'Acme' },
  plugins: [new MyPlugin()],
});
await app.listen();

That's a working oracle. One call to createOracleApp and the framework gives you:

A NestJS app, fully wired

HTTP + WebSocket, request validation, OpenAPI at /docs, CORS, throttling, graceful shutdown — already configured.

UCAN-based identity and auth

Every request is authenticated by a user-signed UCAN invocation (Authorization: Bearer … + X-Auth-Type: ucan). The oracle has an IXO entity DID; users delegate scoped capabilities it can act on downstream.

Encrypted per-user storage

Each user gets a Matrix room; conversation history + agent checkpoints are E2E-encrypted and synced automatically.

A LangGraph agent

Per-request agent build, dynamic tool loading via meta-tools, four always-on middleware (capability gating, tool validation, repetition guard, retry).

16 bundled plugins

memory, skills, sandbox, portal, firecrawl, composio, editor, agui, slack, credits, user-preferences, and more — toggle them via the features map.

A plugin API for your code

9 typed hooks let your plugin contribute tools, sub-agents, middleware, HTTP routes, shared state, and env vars. Boot-time and per-request flavours.

You ship the green box on top. The framework handles the rest.

Where do you want to start?

Build now

10-minute quickstart → recipes → ship. Code-first the whole way.

Deep dive

The mental model, the runtime layers, plugins vs skills.

I'm an AI agent

One dense page with every signature, env var, and template you need.

Quick map

Build track

Task-by-task recipes. createOracleApp, plugin recipes, testing, deploy.

Deep dive

Concepts. Read when you want depth — never required to ship.

Reference

Every option, every env var, every bundled plugin in a flat table.

CLI

qiforge-cli commands — new, plugin new, create-entity, --chat.

What people build with this

Domain-specific agents

Climate oracles that analyse emissions data, carbon DAO assistants, supply-chain MRV agents.

Workflow copilots

AG-UI copilots driving a portal, filling forms, navigating the browser. Bundled agui + portal plugins.

Integration hubs

Agents calling Gmail, GitHub, Linear, Slack, Notion through the bundled composio plugin.

Skill runners

Discover + execute IXO skill capsules inside a per-user Linux sandbox. Bundled skills + sandbox plugins.

Don't skip these

  1. Quickstart — get a working oracle in front of you before reading anything else.
  2. createOracleApp options — every option you can pass.
  3. Write a plugin — the canonical end-to-end recipe.