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/, examples/wasm-*, 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:

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.95+, Deno, system packages, optional just and cargo-component. 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.

  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, demo/wasm/run.sh, and the multi-institution kinase-institutions notebook.

  9. Building WASM components — pure / read-capability / IO components via wasm-cbor-echo, wasm-doc-validator, wasm-read-query-probe, wasm-http-shout. Build with cargo-component, install with eigenius capability install.

  10. Building WASM institutions — D14 Institution trait implementations against the eigenius-institution-d14 WIT world (extract-typed / reify / query). Auto-registration from chain scan via runtime: wasm + inline wasm_binary. Walked through with the M8 dock-assay worked example.

  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 JustifiedBy(justification, proposition) certificates against ReasoningSentence resources at commit. Grounding constructors consume chain witnesses admitted by the D49 witness index, composing chain artifacts (axioms, observations, statistics verdicts, formal proofs) into auditable reasoning chains. See reasoning-institution/. 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