Reviewed: 2026-10-02 · Code-grounded.
XE Local AI Engine (product name XE AI-Engine) is a self-contained local AI node. A single
Node Web Server process (XE-Local-AI-Engine.Client) serves the React management UI, exposes
loopback-only local APIs (/api/local/v1) plus SignalR hubs, persists selected sensitive payloads in SQLite with per-column AEAD encryption, and runs the local model runtimes
as node-owned, supervised host child processes — llama.cpp (llama-server) for text,
stable-diffusion.cpp (sd-server) for images and whisper.cpp (whisper-server) for speech-to-text.
This wiki is the contributor deep-dive for the current codebase. docs/ai-runtime.md is a companion, not a
predecessor: it holds the AI-seam maintenance rules and the current Microsoft.Extensions.AI / Microsoft Agent
Framework pins, while the wiki covers architecture.
- New to the repo: Architecture Overview, then Project Layout.
- Inference or models: Local Runtime & Providers, Model-fit / Advisor.
- Agents or chat: Agent Mode, Chat.
- Data: Data & Persistence. Shipping or running it: Hosting & Deployment.
- Reviewing architecture or security without source access: the Technical/Security Architecture Dossier, a baseline description with evidence limitations, not an assurance or compliance package.
- Each page opens with a short summary (what it covers, who should read it, where to skip to); long pages follow it with a
Contentslist. - The largest pages keep their explanation and move lookup material (option tables, flag catalogues, route and mode matrices) to
reference/NN-*.md; the parent page keeps every heading as a stub that links there, so a citation such aswiki 03 §2.5still lands. - Code comments and other docs cite sections as
wiki NN §Mand link to heading anchors, so headings are never renamed or renumbered. - The
Reviewed:date on line 3 is the last time the page was checked against the code. Where the page and the code disagree, the code wins. - Pages describe how things work. The traps (failures already paid for, and the rule that prevents each) live in the companion agent-knowledge index.
- Inference runs in host child processes the node supervises itself —
llama-serverfor text,sd-serverfor images,whisper-serverfor speech-to-text. There is no container and no agent between the host and a model runtime. XE-Local-AI-Engine.HostAgent.*does not exist; the host owns the runtime directly.- Docker appears in exactly two places, neither on the inference path: the Development Mode container
sandbox provider, which is opt-in (
Development:Sandbox:Provider=docker, unset in the shipped config) per ADR 0004, and the engine-owned container runtime behind External Apps. - Detail: Architecture Overview, Local Runtime & Providers, Security & Privacy.
- The Open Canvas import runs at startup and stops startup if it fails. Saved canvases become Graph Workflow definitions; the encrypted source is staged, so a failed conversion retries on the next start. Read Graph Workflows §9 before upgrading a node whose canvases matter.
- "No Docker anywhere" is stale (it predates ADR 0004), and so is "Docker on the inference path". The Docker bullet above is the current rule.
| # | Page | Covers |
|---|---|---|
| 01 | Architecture Overview | System boundary, layering, dataflow, Development Mode source/worktree flow, the architecture invariants |
| 02 | Project Layout | Every .csproj, dependency graph, central package mgmt, analyzer wall |
| 03 | Local Runtime & Providers | llama.cpp supervisor, GPU variant select, binary acquisition (prebuilt / BYO override / in-app source build), provider seams across every Providers.* project registered in XE-Local-AI-Engine.slnx (Abstractions, LlamaServer, HuggingFace, Ollama, CodexOAuth, Capabilities, StableDiffusionCpp, Training) |
| 04 | Agent Mode | MAF wiring, tool registries, AgentHome, Playbook P1–P5, Memory, Capacity, Coder, sub-agent spawn |
| 05 | Chat | RuntimeChatClient per-send routing, ordered parts, sampling, attribution, at-rest encryption |
| 06 | Scheduler | Quartz.NET jobs, run history, cancellation, live hub, encoded gotchas |
| 07 | Model-fit / Advisor | Cache-read vs scheduler refresh, MemoryFitEstimator, hardware profiler, sanitization |
| 08 | Data & Persistence | EF Core + SQLite, per-column AEAD encryption, entities, schema milestones |
| 09 | API & Hubs | FastEndpoints /api/local/v1 (one route family per nested class in LocalApiRoutes), the local SignalR hubs registered by the MapHub<> block in Client/Program.cs (all unconditional except DevelopmentAttemptHub) — this page owns the hub list, operator-authored custom tools, the inbound MCP tool surface, OpenAPI→hey-api |
| 10 | React Client | The feature directories under Client.React/src/features/, TanStack Query/Zustand, hey-api, shared hub connections, dialog system, i18n, SPA serving |
| 11 | Hosting & Deployment | Aspire AppHost, desktop launcher, native desktop shell, publish profiles, update channels, vault unlock, legacy/manual cleanup |
| 12 | Security & Privacy | Egress boundary, secret handling, vault key custody, web access consent, loopback/Host-Origin, redaction, node-local AI ops, Development Mode execution boundary |
| 13 | Testing & Validation | Test topology, validation commands, E2E, RC evidence |
| 14 | Image Generation | Local stable-diffusion.cpp: sd-server supervisor, serialized job coordinator, encrypted image store |
| 15 | Knowledge Base / RAG | Offline document KB: ingestion pipeline, hybrid FTS+vector search, reranker, agent tools |
| 16 | Code Organization Conventions | Where a type/file goes: *ServiceModels.cs, DTO aggregation, mapper colocation, feature-folder rules, load-bearing suppressions |
| 17 | Writing Tests | Contributor authoring guide: which project a test belongs in, the TestServerWebAppFactory patterns, parallelism keys, migration/hub/hosted-service/React/E2E recipes, how to run a scoped subset |
| 18 | Training | Local fine-tuning: the Providers.Training uv/Python runtime, dataset generation, training runs, export/promote/eval |
| 19 | Compute Tools | Sandboxed code execution: the run_python tool, process-sandbox isolation, uv-pinned venv (numpy/scipy/sympy), security/gating (WriteExecute + approval-required, profile-opt-in), Linux x64 and Windows x64, operator enablement |
| 20 | Benchmarks | Task suites and long-context probes, freeze fan-out and cell ranking, verifiable criteria incl. pythonTests execution scoring, pairwise Bradley-Terry and paired-difference intervals, quant fidelity (perplexity/KLD, base-logit cache, comparability digest), the four-kind work queue, scheduled matrices and the training hand-off, export schema 4 |
| 21 | Graph Workflows | Operator-authored DAGs: the graph contract and its validation rules, the run and node-run lifecycles, the node kinds including direct LLM calls, chat inputs and decision models and their documents, Standard vs Chat graphs, the route family and the graphWorkflowChanged hub contract, the React editor and run view, the options table, and the one-shot Open Canvas import |
| 22 | Workflow Engines Divergence Register | Dev Workflows vs. Graph Workflows: status/decision vocabulary, approval model, restart/reconciler behavior, the cross-node fix loop, persistence and hub shape, MAF/MEAI boundary, feature flags — what was deliberately dropped and what is an unintentional gap, with convergence explicitly deferred. Dev Workflows themselves are page 25; this register carries only the comparison |
| 23 | External Apps | Curated containerised applications: the catalog document and its fingerprint, the engine-owned container runtime layer beside the sandbox SPI, the container policy and what it verifies on read-back, per-instance storage and the storage-wipe helper container, the lifecycle and the boot reconciler, runtime selection and the daemon identity pin, the ExternalApps:Enabled kill switch and what disabling does not do |
| 24 | Audio Transcription | Local speech-to-text on whisper.cpp: the supervised whisper-server runtime in brief, the encrypted session and segment tables and their AAD layout, the batch upload path (streaming multipart, engine-owned temp slot, container sniffing, engine-side ffmpeg transcode, Seq from 1), the session route family, the React feature area, the never-persist-audio rule and its four enforcement points, the options table, and what the live capture slices have not built yet |
| 25 | Development Workflows | Templated graphs over a code work item: the database-as-truth tick and its serialized-write invariant, the agent/tool/dev-task lanes and the write declaration, decomposition and the task-package contract, the provenance rule that gates an apply, the cross-node fix loop and its budgets, operator retry reasons and the task statuses that carry none, telemetry and rule-set policy text, artifact promotion, startup recovery, and the options table |
Lookup material split out of the largest pages. Each is complete on its own and names the parent section it came from.
| Parent | Reference pages |
|---|---|
| 03 Local Runtime & Providers | supervisor internals · launch flags · clients · runtime binaries & tuning · satellite & cloud providers |
| 04 Agent Mode | AI.Agent runtime · application services · agent skills · work sessions |
| 12 Security & Privacy | admin API surface · sandbox modes & options |
- Every structural claim cites source as
path/to/File.cs(and symbol names where useful). - Every page carries a
Reviewed:date on line 3. When you change a subsystem, update the matching page. - Architecture invariants (egress, secrets, loopback, node-local privacy ops) are rules, not suggestions — see Security & Privacy and Architecture Overview.