Skip to content
Eigenius

Platform user guide

How to install, run, manage, and extend the Eigenius platform. This guide is the practical companion to the surface-language guides — it covers everything around writing ESL, EigenQL, or formula values: the CLI, the kernel server, the orchestrator, persistence, WASM and substrate extensions, and deployment.

The guide is grounded in the implementation in cli/, kernel/src/server/, orchestration/, storage/rocksdb/, crates/runtime-substrate/, julia/, and deploy/. Every command shape, env var, and config detail links to the source.

How to read this guide

If you’re new: read chapters 1–5 sequentially, then jump to chapter 14 — Notebook for the most accessible UX. After that, the guide is a reference — jump to the chapter for the question you have.

The most-used reference chapters are:

  • 14. Notebook — the React notebook UX, served by the orchestrator at http://localhost:8080/notebooks/
  • 15. Tags, branches, and history — the workspace panels that drive named refs and chain navigation
  • 16. Merge resolution — picking a per-conflict strategy, the cascade gate, provenance records
  • 17. TypeScript SDK — the Eigen class the notebook is built on, also usable from your own browser / Deno / Node code
  • 4. CLI reference — every eigenius subcommand
  • 6. Database management — durable mode, exports, backups
  • 9. Building WASM components and 10. Building WASM institutions — the sandboxed WASM extension surface (REMOVED 2026-07-08; chapters retained as historical record)
  • 11. Runtime substrate — the language-runtime extension surface (Julia in v1)
  • julia-institutions/ — slow-walk tutorials for each of the v1 Julia institutions
  • lean-institution/ — the platform’s first verification institution: Lean 4 in-process via nanoda_lib
  • statistics-institution/ — D52 measurement-statistics institution: recompute statistical claims from raw replicate data, opinionated stances (one-sided witnessing, dual-verdict outlier exclusion, Passing-Bablok for method comparison, epistemic-scope guard)
  • justification-logic/ — D39 justification-logic institution: type-check justification:Grounds certificates against (justification, proposition) pairs, composing chain artifacts as evidence through the D49 witness-index mechanism

Chapters

  1. Introduction — what this guide is for, system topology at a glance, the seven ways to interact with the platform.

  2. Installation and prerequisites — Rust 1.97+, Deno, system packages, optional just. Optional WordNet provisioning for the DCG / lexicon engine. WSL 2 notes for Windows users.

  3. Building and testing — just build, just test, just check. What just build does that plain cargo build does not.

  4. CLI reference — every eigenius subcommand, grouped by purpose: file commands, knowledge-graph commands, program commands, server, database, branch, mirror, env, institution, capability, tasks, data.

  5. Running the platform locally — three-terminal model (orchestrator + kernel + CLI), Docker Compose, what state survives restarts.

  6. Database management — serve --db <path>, RocksDB persistence, drift refusal, db stats/compact/export, backup strategy.

  7. The orchestrator — what it does (IO component dispatch + LLM adapter + MCP server + substrate addon), real vs. mock LLM mode, the built-in CompleteText and CompleteJson components, when you don’t need it.

  8. Worked demos — step-throughs of demo/run.sh, demo/patent/run.sh, the multi-institution kinase-institutions notebook, the Lean verification audit chain, and the prose-to-formulas demo (parsed sentences committed as certificates, then edited until the kernel refuses them).

  9. Building WASM components — REMOVED (2026-07-08). Retained as historical record; WASM component hosting and eigenius capability install no longer exist.

  10. Building WASM institutions — REMOVED (2026-07-08). Retained as historical record; the institution framework (D14) is intact, but the WASM backend is gone (use in-process Rust or external/substrate institutions).

  11. Runtime substrate — the orchestrator-spawned, container-hosted runtime layer for institutions backed by full language ecosystems (Julia in v1, Python and others tracked). The mirror create → env build → env create → institution install lifecycle. WASM vs. substrate trade-off table. Cross-links to julia-institutions/.

  12. Deployment — Docker Compose (production-quality today), Azure ContainerApps via Bicep (preliminary; templates exist but haven’t been deployed end-to-end yet), embedding the kernel as a library.

  13. Troubleshooting and FAQ — common build / runtime / connection issues.

  14. Notebook — the React SPA the orchestrator serves at /notebooks/. Cell types (markdown / esl / eigenql / typescript / program-run / chart), the file format, publish-to-layer, the patent-analysis and kinase-institutions demos, KaTeX math rendering.

  15. Tags, branches, and history — the workspace rail’s chain destinations: Branches (switch / create / delete), Tags (immutable named refs that pin against GC), History (chain walker + time-travel read-pin). The BranchBar at the top, the create-branch dialog’s four start-from modes, mental model of mutable vs. immutable.

  16. Merge resolution — folding one branch into another when contributions conflict. The six-state flow (loading → picking → previewing → acknowledging → committing → done), the four strategies (Witness / Rename / SchemaQuotient / Restructure with KeepBoth/KeepOne/KeepNeither sub-flavours), the cascade gate, merge-resolution provenance records, off-span witness discovery, worked examples, CLI mirror.

  17. TypeScript SDK — @eigenius/client and the Eigen class. The SDK that powers the notebook, also usable from your own code. Five-line examples for inspect / query / load / runProgramByIri / layerTopology / publishNotebook.

  18. Appendix — environment variables, file locations, source index, related documents.

Julia institution tutorials

Slow-walk tutorials for the five v1 Julia institutions live in julia-institutions/. Read the intervals tutorial first for the substrate plumbing slow-walk; then the others go domain-specific.

Lean institution tutorial

The platform’s first verification institution (D28). In-process via nanoda_lib for the verification side; substrate-hosted for the authoring side. Walks the closed audit chain D28 §5.7 promises against the lean-verification notebook. See lean-institution/.

When bumping the pinned Lean toolchain, follow the checklist at docs/notes/lean-toolchain-upgrade.md — the substrate’s image-digest model treats every toolchain change as a new content-addressed LeanEnvironment, so existing verified proofs stay valid against their original env digest.

Statistics institution (D52)

The platform’s measurement-statistics institution. In-process; recomputes statistical claims from raw replicate data using deterministic IEEE-754 numerics. Covers seven dispatch positions (SingleSampleEstimate / IID / Paired / Factorial / RCBD / SplitPlot / RepeatedMeasures) and four opinionated stances (§7.1 OneSidedWitnessed + ImpossibilityWitness, §7.2 dual-verdict outlier exclusion, §7.3 MethodComparisonAnalysisPlan + Passing-Bablok, §7.4 epistemic-scope guard). See statistics-institution/.

Reasoning institution (D39)

The platform’s justification-logic institution. In-process; type-checks justification:Grounds(justification, proposition) certificates against justification:Conclusion resources at commit. Grounding constructors consume chain witnesses admitted by the D49 witness admission, composing chain artifacts (axioms, observations, statistics verdicts, formal proofs) into auditable reasoning chains. See justification-logic/. For the full statistics + reasoning composition, see composition guide chapter 7.

The full design-document set lives in docs/design/.

Ready to start? → 1. Introduction