Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ixo.world/llms.txt

Use this file to discover all available pages before exploring further.

​
The three layers

A QiForge deployment has exactly three layers. Knowing what each one owns saves a lot of confusion.

​
Layer 1 — Your oracle

Typically apps/your-oracle/src/main.ts (a createOracleApp(...) call), a config.ts for identity, and any custom plugins or Nest modules. You own: the entry point, your oracle’s identity, custom plugins, custom Nest modules. You don’t own: the agent loop, the graph state shape, the checkpointer, the auth flow, the meta-tools, the bundled plugins’ internals.

​
Layer 2 — @ixo/oracle-runtime

The framework. Owns the bootstrap (createOracleApp), the always-on Nest modules (Sessions, Messages, WebSocket, Secrets, UCAN, Auth, Subscription, Throttler, Health), the per-request agent builder, the four always-on middleware, the Matrix-backed SQLite checkpointer, and the plugin API. You never edit this layer. Updates come via pnpm update @ixo/oracle-runtime.

​
Layer 3 — Bundled plugins

15 plugins shipped inside the runtime package, each independently toggleable via features. See the Plugin catalog for what each one does.

​
Bootstrap, in one picture

The HTTP server accepts requests immediately; auth-requiring routes 401 until Matrix init finishes and the UCAN signing mnemonic loads. Defined in create-oracle-app.ts.

​
The six registries

Plugins don’t talk to the runtime directly. They push contributions into one of six registries at boot; the agent builder reads from them per request.
RegistryHoldsCollision rule
ToolRegistryAll plugin toolsFlat namespace — collision is a boot error
SubAgentRegistryAll plugin sub-agentsFlat namespace — collision is a boot error
MiddlewareRegistryAll plugin middlewareOrdered topologically; no names
ManifestRegistryAll plugin manifestsTitle collision = soft warn
ConfigSchemaRegistryAll plugin Zod schemasMerged; later wins with warning
SharedStateRegistryPlugin shared-state accessorsFlat namespace — collision is a boot error
Source: packages/oracle-runtime/src/registries/.

​
What’s pluggable vs fixed

PluggableFixed
Plugin set (bundled toggles + your plugins)Agent loop (LangChain createAgent)
nestModules (your Nest modules)Graph state shape (except one new loadedPlugins field)
authExcludedRoutes (host + plugin)Checkpointer (Matrix-backed SQLite)
LLM provider (env-driven)Auth flow (UCAN delegation)
hooks.checkpointerForUser (advanced)The four always-on middleware
System prompt (via OracleConfig.prompt)The Tier-1 block format
Anything inside a custom pluginThe six registries
If you find yourself wanting to swap something on the “Fixed” side, you’re probably trying to do something the framework explicitly doesn’t allow — and you should either work within the model (e.g. write a plugin) or fork the runtime.

Request lifecycle

What happens between user message and streamed response.

Build your first oracle

The recipe for wiring createOracleApp.