KeelBase — Build and Run Business-safe AI Applications

Build AI applications that enterprises can trust — from scratch or from existing systems. Governed, auditable and private by default.

Open-source Business-safe AI Runtime — connect AI agents with existing business systems, without replacing existing technology stacks.

The KeelBase DNA — AI Generates. Architecture Constrains. Runtime Governs. Tests Verify. Humans Decide. Business boundaries are enforced by the Runtime, not prompts; an Agent's capability ≠ its authority; trust is proven by runnable verification, not claimed; important actions are recoverable. Full engineering philosophy: docs/keelbase-dna.md.

🚀 Try in 60 Seconds

Prefer instant? Open the live demo → keelbase-demo (alex/Alex@2026$Demo — workbench, ask "which customers need attention?"). Visit guide: demo-live.md.

Or watch the demo video → English demo (GitHub Pages) · China mirror (4-min, with real system demos; download: GitHub release).

Or read the series → Runtime over Prompt · Why AI Writes Need Risk Tiers.

Docker only — one command brings up the entire application (backend + workbench + Admin Console + mobile preview), no build:

docker run -d --name keelbase -p 3000:3000 ghcr.io/rain6fish/keelbase:latest

No LLM API key needed to try it: when no cloud/local model is configured, the AI runs in deterministic demo mode — the full golden path (analyze → confirm → create → audit → revoke) works out of the box. Bring your own DeepSeek/Qwen/OpenAI/Ollama key (-e DEEPSEEK_API_KEY=...) for real LLM responses.

Reset to a clean demo state anytime: docker rm -f keelbase && docker run -d --name keelbase -p 3000:3000 ghcr.io/rain6fish/keelbase:latest — data lives in the container's SQLite (no volume), so removing the container wipes demo data and the seed re-runs on next start.

Then walk the golden path in 6 steps:

1. Open http://localhost:3000            (workbench) — /admin is the Admin Console
2. Sign in — alex/Alex@2026$Demo, or admin/Admin@2026$KeelBase (consistent across all environments)
3. Ask: "Which customers are at the highest risk this week?"
4. Watch AI analyze real business data
5. Approve a follow-up task              (human confirmation)
6. Open the audit trace                  (every action recorded & reversible)

Prefers a local demo? ./deploy/demo.sh → http://localhost:3000 (opens the AI CRM Golden Flow workbench).

🎯 See AI Actually Do Business

KeelBase's flagship AI CRM is not a demo — it's a working product loop:

You:
"Which customers are at the highest risk this week?"

KeelBase AI:
3 customers require attention…
  → Analyze customer risk
  → Read authorized orders and activities
  → Create a follow-up task
  → Ask for your confirmation
  → Write to the CRM
  → Record audit
  → Allow revoke

One business scenario says more than a list of twenty features.

🎯 Who It's For

Two ways to meet KeelBase — one runtime underneath.

For AI-native builders — ship an AI business application without rebuilding the foundation:

• Generate a full business module (entities / CRUD / permissions / AI tools / audit) from a protocol in ~30 minutes — real, editable code, not a low-code engine
• Bring your own LLM (cloud or local); data stays under your control

For teams with existing business systems — you already run CRM / ERP / OA or a decade-old Java stack, and you want it to think:

• Bridge existing systems in (OpenAPI / SQL schema / Java service) without rewriting them
• AI acts as a business assistant on your real data — risk analysis, follow-ups, summaries, approvals
• Private deployment: Docker / offline / local models — data never leaves your perimeter

Standalone or connected — KeelBase is a complete application development platform in its own right (generate full-stack business apps from a protocol), and a Business-safe AI Runtime for existing systems. No legacy system required.

🔐 Business-safe by Design

User Request → AI Understanding → Business Data → Tool Call
        → Permission Check → Human Confirmation
        → Side Effect → Audit → Revoke

AI can act — but only within explicit business boundaries.

• User-scoped tools — every call carries the authenticated user; AI acts inside that user's data scope — their own records, plus their organization's where the resource is org-scoped — and never outside it
• Human confirmation — writes at higher risk levels require a human's explicit approval before execution; low-risk writes execute under the configured policy
• Audit & revoke — actions land on a tamper-evident audit hash chain (audit granularity is configurable; the default records everything); AI-created side effects are tracked, and reversible for the tools that declare a way to undo them
• Explainable — "why did the AI do that?" is answered by a decision trace, not a black box

🏗 Build — Protocol-Driven Generation

Build AI applications from new business models or existing systems:

• Application Protocol — a human/AI-readable schema describing an application
• keelbase init — natural language / SQL schema / OpenAPI → Protocol → a complete business module with permissions, AI tools, confirmation, and audit
• AI Bridge — connect a Java/legacy system; AI reads and acts on it under governance

Generated artifacts are normal source code. No proprietary runtime metadata. No drag-and-drop lock-in.

▶️ Run — AI Does Real Business Work

• Tool calling, RAG, memory, sub-agents, proactive AI
• AI reads and acts on business data — not just chat
• Every tool call scoped, every write confirmed, every action audited

🔒 Trust — Governance & Audit

Where KeelBase differs from a plain agent framework:

• CASL row-level permissions · tool governance · write confirmation
• Audit hash chain (tamper-evident) · side-effect idempotency · revoke
• Decision trace · AI eval · prompt-injection defense

Enterprise Safety Validation

These aren't just claims — every one is verified by an executable test that ships with the repo:

• ✓ Permission boundary tests — cross-user access denied via CASL (authorization matrix, asserted case by case)
• ✓ Tool governance tests — abuse / confirmation-bypass / prompt-injection blocked (security eval — scripts/verify-security-eval.sh)
• ✓ Human approval tests — writes stay untouched until a human confirms (Golden Flow e2e)
• ✓ Audit integrity tests — audit hash chain verifies, tampering fails (/audit/verify)
• ✓ Agent behavior tests — decision trace + business-safe agent benchmark (Run/Trust/Safety dimensions, scripts/benchmark/agent-benchmark.mjs)
• ✓ End-to-end business flow — AI CRM: read → risk → task → confirm → write → audit → revoke (deterministic e2e)

Boundaries matter — what "audit / revoke / tamper-evident" does and does not promise (e.g. within-application only, not vs. DBA/root; revoke is scoped per revokeClass, not a cross-system rollback): SECURITY.md → Trust Boundaries (Not-a-*)

🏠 Deploy — Private by Design

Cloud LLM  OR  Local Model / Ollama
        → Local Embedding → Local RAG → Business-safe Agent → Local Audit

Run the entire AI application locally when your data cannot leave your environment.

Docker single-container · offline / intranet deploy · local models & embeddings.

🛠 Build Your First Application

git clone --recurse-submodules https://github.com/rain6fish/KeelBase.git && cd KeelBase
cd Server-NestJS && npm install && cp .env.example .env && cd ..
npm run preflight    # before anything else: Node / Docker / ports / .env / contract submodule
node scripts/keelbase-init.mjs --spec specs/invoices.json

--recurse-submodules is required: Server-NestJS/specs/protocol is a submodule holding the wire schemas and protocol vectors that the test suites read. Already cloned without it (or downloaded a ZIP — those never carry submodules)? Run git submodule update --init --recursive. npm run preflight reports that gap — and any other setup one — before you start.

Natural Language → Module Spec → Protocol → Application Code → AI Tools → Governance. The CLI ships with the repo (scripts/keelbase-init.mjs) — no global install; --desc "…" generates from a sentence instead of a spec file (needs a model key configured).

Full flow: Build an AI CRM in 30 minutes · 30-minute acceptance · Dev Challenge — 中文 · EN · EN · EN

📦 Existing System AIization

Existing DB / OpenAPI / Java System
        → Application Protocol → Generated Module
        → AI Tools + Governance → Business Agent

Give a 10-year-old business system AI capability without rewriting it.

Java Starter (Spring Boot)

For Java/Spring teams: annotate existing @RestController methods with @KeelbaseTool and they become governed KeelBase AI tools — delegated identity, human-confirmed writes, audit and revocation are handled by the KeelBase runtime. No rewrite. Requires Spring Boot 3.x + Java 17+ (Boot 2 / Java 8 go through the API-proxy path).

Get started — Maven cn.com.keelbase:keelbase-spring-boot-starter (Maven Central) → github.com/rain6fish/KeelBase-java-starter — 5-minute trial, reference projects (CRM / PM / Approval), development guide.

🧩 Architecture

One main thread — Build → Run → Trust → Private Deploy:

• Build — Protocol-driven generation: Application Protocol (conventions); AI generates the business modules — AI-native Application Engineering, not a traditional low-code engine
• Run — Business-safe Agent Runtime: user-scoped tools, human-confirmed writes, full audit and revoke
• Trust / Private Deploy — Data Sovereignty: data stays on-prem; AI stays accountable and reversible

The core is UI-framework-agnostic; Flutter / Vue / React are Renderers (architecture-boundary · EN).

📍 Where KeelBase Sits

KeelBase is a Business-safe AI Runtime — it connects AI agents with existing business systems, adding identity, governance, auditability, and private deployment, without replacing existing technology stacks.

      AI Applications / Agents
      Agent Frameworks
  LangGraph · AutoGen · CrewAI
  Custom Agents · MCP Clients
                    ▲
                    │ identity · policy · governance
                    │ audit · runtime · deployment
              ┌─────────────┐
              │  KeelBase   │
              └─────────────┘
                    │
                    │ bridge · protocol · capability mapping
                    ▼
      Existing Business Systems
      CRM · ERP · OA · MES · Database

• Up — the AI world (northbound): any agent can enter governance. Agent frameworks connect via open standards (MCP / OpenAPI / function calling) — KeelBase does not re-build orchestration, agent loops, or memory strategies
• Down — the business world (southbound): any existing system can become AI-capable. Business systems connect via the Bridge (protocol + capability mapping) — no rip-and-replace
• In between — the trust layer: identity, policy, permission, human confirmation, side-effect control, audit & revoke, private deployment

🧬 The KeelBase family

KeelBase is one protocol with several implementations and hosts — not a set of competing
products. The contract is the source of truth; runtimes and hosts consume it, and none of them
owns it. Every repository here is Apache-2.0.

  host adapters   KeelBase-YuDao
                  └ governance added to a mature enterprise platform (yudao)

  runtimes        KeelBase (TypeScript)   ·   KeelBase4J (Java / Spring)
                  └ two carriers of the same protocol — peers, not translations

  bridge          KeelBase-java-starter
                  └ wire an existing Java/Spring system in as governed AI tools

  contract        keelbase-contract
                  └ wire schemas + conformance vectors + the version line they share

Where to start — see it run: KeelBase (60-second
Docker) · make an existing Java system AI-capable:
KeelBase-java-starter · you already run yudao:
KeelBase-YuDao · implement the protocol:
keelbase-contract.

Which contract version each runtime answers for is maintained once, in the main repository — see
Compatibility. It is not duplicated here.

🧭 Compatibility

The protocol has its own version line, independent of any runtime's. This table says which contract
version a runtime answers for — which objects it has committed to speaking. It is maintained from the
first release rather than assembled when someone asks.

A runtime that is behind the current contract is not broken; it simply does not yet answer for the
newer version's objects. What moves a runtime forward is a deliberate act — the contract never reaches
into a runtime on its own.

The unreleased row is there on purpose. If you are choosing what to deploy, the difference between what
is published and what is on main is exactly what you need to see.

📚 Documentation

Every guide ships in 中文 and English — pick your language below.

• Quick Start 快速开始 — 中文 · English
• Tutorial 零基础教程 — 中文 · English
• Concept Map 概念地图 — 中文 · English
• Rules Map 规则地图 — 中文 · English
• Build an AI CRM in 30 minutes 30 分钟构建 AI CRM — 中文 · English
• 30-Minute Acceptance 30 分钟验收 — 中文 · English
• Dev Challenge 开发者 30 分钟挑战 — 中文 · English
• FAQ 常见问题 — 中文 · English
• Operations 运维手册 — 中文 · English
• Development 开发手册 — 中文 · English
• Private AI Verification 私有 AI 验证 — 中文 · English
• Flagship Apps Spec 旗舰应用规格 — 中文 · English
• Enterprise Capabilities 企业能力声明 — 中文 · English
• Compliance Mapping 合规映射 — 中文 · English
• Product Language 产品语言词汇表 — 中文 · English
• Architecture Boundary 架构边界 — 中文 · English
• Authorization Architecture 权限架构 — 中文 · English
• External system integration 外部系统集成
  • AI Bridge 存量系统 AI 化 — 中文 · English
  • Capability Declaration 轻量能力声明 — 中文 · English
  • External CRM Demo 外部 CRM 接入演示 — 中文 · English
  • Framework Adapter Agent 框架接入 — 中文 · English
  • Java Starter (Spring Boot) — turn Java/Spring methods into governed KeelBase AI tools with @KeelbaseTool: delegated identity, read/write confirmation, audit and revocation are all handled by the KeelBase runtime. → GitHub: rain6fish/KeelBase-java-starter
  • Customer scenario — legacy Java CRM × LangChain4j agent 客户场景样板 — one-page topology + phased PoC plan (bilingual) → integrator-kit/java-crm-langchain4j-solution.md
• CLAUDE.md (architecture & conventions) · AGENTS.md (AI build rules) · SECURITY.md
• Threat Model & Trust Boundaries 威胁模型与信任边界 — 中文 · English
• Versioning 版本策略（公开版本计划） — docs/versioning.md（中英双语）
• Explore all capabilities → docs/

🤝 Community & Contributing

• Contributing · Code of Conduct · Apache-2.0 licensed
• Issues & feature requests → github.com/rain6fish/KeelBase/issues
• Demo accounts: alex/Alex@2026$Demo (workbench / mobile) · admin/Admin@2026$KeelBase (Admin Console) — consistent across all environments

Repositories

Tech Stack

Flutter 3.x · Vue3 + Element Plus · React 19 (preview) · NestJS 11 + TypeORM · SQLite / PostgreSQL · Redis + BullMQ · JWT + CASL · OpenAI-compatible LLMs (DeepSeek / Qwen / OpenAI / Claude / Gemini) · pino + Prometheus + OpenTelemetry · Docker / Nginx · CI (GitHub Actions)