Build verified AI agents with blockchain identity, encrypted communication, and a growing library of skills — deploy once, live instantly.
QiForge is a full-stack framework for building Agentic Oracles on the IXO network. Each oracle is an autonomous AI agent with a verified on-chain identity, private encrypted channels for every user, and the ability to discover and execute new skills at runtime — without redeployment.
Most AI frameworks give you a chatbot. QiForge gives you a verified, autonomous agent that can reason, remember, learn new skills, charge for its work, and prove its identity — all out of the box.
| QiForge | Typical AI Framework | |
|---|---|---|
| Verified identity | Blockchain DID — users can verify who your agent is | None |
| Encrypted comms | Every conversation in a private Matrix room | Plain text / logs |
| Skills at runtime | 40+ community skills, no redeployment needed | Hardcoded tools |
| Multi-LLM | GPT-4, Claude, Gemini, Llama via OpenRouter | Vendor lock-in |
| Built-in billing | Token billing + service claims, automatic | DIY |
| Multi-client | Portal, CLI, Matrix, Slack — one oracle, every interface | Single client |
| Persistent memory | Cross-session memory with knowledge scopes | External DB required |
| Sub-agents | 6 specialist agents pre-wired, add your own | Roll your own |
# Install the CLI
npm install -g qiforge-cli
# Scaffold a new oracle project
qiforge --init
# Install, build, run
pnpm install && pnpm build && pnpm dev
# Chat with your oracle instantly
qiforge chatYour first oracle is live. Customize the name, personality, and skills — then deploy.
Full walkthrough: Quickstart Guide →
graph LR
U[User] -->|Portal / CLI / Matrix / Slack| API[Oracle API]
API --> AI[AI Engine + Sub-Agents]
AI -->|discovers| SK[Skills Registry]
AI -->|remembers| ME[Memory Engine]
AI -->|executes| MCP[MCP Servers]
AI -->|stores| MX[Encrypted Matrix Rooms]
API -->|identity & billing| BC[IXO Blockchain]
Users send messages through any client. The AI Engine reasons, delegates to sub-agents, discovers skills, and streams responses back. Conversations persist in encrypted Matrix rooms. Identity and billing live on the blockchain.
Skills are like apps on a phone. Your oracle discovers and loads them from a shared registry at runtime — presentations, PDFs, data analysis, web search, invoices, and more.
User: "Create a slide deck about renewable energy"
→ Oracle finds presentation skill in registry
→ Reads instructions, executes in sandbox
→ Returns finished slides
No code changes. No redeployment. Publish your own skills with a markdown file and a PR.
Delegate complex tasks to purpose-built agents that ship out of the box:
| Agent | What It Does |
|---|---|
| Memory Agent | Retrieves user context, preferences, and history |
| Skills Agent | Searches the skill registry and loads capabilities |
| Portal Agent | Handles browser/UI interactions from the client SDK |
| Firecrawl Agent | Web search and scraping |
| Editor Agent | Real-time document editing with BlockNote |
| Domain Indexer | Searches and analyzes IXO blockchain entities |
Need a specialist that doesn't exist? Define a name, description, tools, and prompt — wire it in.
Every tool call passes through middleware checkpoints:
- Token Limiter — checks credits before each call, deducts after
- Safety Guardrail — blocks leaked secrets, PII, and harmful content
- Tool Validation — catches bad inputs with helpful error messages
- Tool Retry — handles network blips automatically
Write custom middlewares with beforeModel, afterModel, afterAgent, and wrapToolCall hooks.
Connect external services via the Model Context Protocol:
// mcp.ts — add a new server in one line
{ name: 'github', url: 'https://mcp.github.com/sse' }Built-in servers: Memory Engine, Firecrawl, Sandbox, Subscription. Tools are auto-discovered — no hardcoding.
Persistent memory across conversations with three knowledge scopes:
- User memories — private preferences and context per user
- Org public — customer-facing FAQs and docs
- Org private — internal processes and policies
Your oracle starts every conversation with relevant context already loaded.
Two revenue streams, zero custom code:
- Token billing — automatic per-token charges with escrow
- Service claims — explicit charges for deliverables (PDFs, images, reports)
Users approve claims through the Portal. Funds release from escrow. Disable during development with DISABLE_CREDITS=true.
apps/app/ → Main NestJS oracle application
packages/
@ixo/common → AI services, session management, checkpointer
@ixo/matrix → Matrix client, encrypted room management
@ixo/events → SSE/WebSocket event streaming
@ixo/oracles-chain-client → Blockchain ops, claims, payments, ECIES
@ixo/oracles-client-sdk → React SDK (useChat() hook)
@ixo/slack → Slack bot integration
A step-by-step guide from zero to production oracle — written for humans and AI alike.
| Chapter | What You'll Achieve |
|---|---|
| 00 — Overview | Understand what an oracle is |
| 01 — Quickstart | A running oracle in minutes |
| 02 — Project Structure | Know your codebase |
| 03 — Customize | Name, personality, and purpose |
| 04 — Skills | Use and build skills |
| 05 — Sub-Agents | Add specialist agents |
| 06 — Middlewares | Safety, billing, guardrails |
| 07 — MCP Servers | Connect external tools |
| 08 — Deployment | Ship to production |
Standalone guides: Publish Your First Oracle · Memory Engine · Payments & Claims · Building Skills
Reference: CLI Commands · Environment Variables · API Endpoints · State Schema · Troubleshooting
Deploy with Docker or Fly.io. The included Dockerfile and fly.toml handle everything.
# Fly.io (recommended)
flyctl launch
flyctl secrets set $(cat .env | xargs)
flyctl deploy
# Docker
docker build -t my-oracle .
docker compose up -dGraceful shutdown saves all state to Matrix before restart — zero data loss.
pnpm install # Install all dependencies
pnpm build # Build all packages
pnpm dev # Start in watch mode
pnpm test # Run tests
pnpm lint # Lint (must pass before commit)
pnpm format # Format codePrerequisites: Node.js 22+, pnpm 10+, IXO Mobile App, OpenRouter API key
QiForge is under active development. New skills, agents, and capabilities ship regularly. Here's what's coming:
- More skills in the registry — the community grows every week
- Voice & video calls — LiveAgent integration with double encryption
- Enhanced sandbox — richer execution environment for skills
- More deployment targets — one-click deploy to Railway, Render, and more
Star this repo to stay updated.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Run
pnpm lint && pnpm formatbefore committing - Push and open a Pull Request
Publish a skill: Fork ai-skills, add your skill folder, open a PR. Every oracle benefits immediately.
Apache License 2.0 — see LICENSE