Skip to content
Eigenius

1. Introduction

This guide explains how to operate the Eigenius platform — install it, run it, manage data, write WASM and substrate extensions, and deploy. It is the practical companion to the surface-language guides (ESL, EigenQL, Formula) which target program/query authors. Where this guide is operational, the language guides are reference material for what you write into the system.

1.1. System topology

Eigenius is a small set of cooperating processes:

┌──────────────┐  Connect-RPC                     ┌──────────────────┐
│  Notebook    │ ────────────────────────────►   │  Orchestrator    │
│  (browser)   │  /notebooks/* (static SPA)       │  (Deno)          │
└──────────────┘  /eigenius.v1.* (RPC)            │  - LLM adapter   │
                                                  │  - MCP server    │
┌─────────┐  CLI commands         ┌──────────────┤  - IO components │
│   CLI   │ ──────────────────►  │   Kernel     │  - Notebook SPA  │
└─────────┘     gRPC :50051       │   (Rust)     │  - Substrate     │
                                  │  - Layer chain    addon         │
                                  │  - Type theory    Connect :8080│
                                  │  - EigenQL        └────┬───────┘
                                  │  - Institutions        │
                                  └────┬─────────────┘     │ spawn
                                       ▲                   ▼ workers
                                       │ component   ┌──────────────┐
                                       │ dispatch    │   Worker     │
                                       │             │  containers  │
                                       │             │  (Julia,     │
                                       │             │   Python…)   │
                                       │             │  UDS +       │
                                       │             │  Eigon-CBOR  │
                                       │             └──────────────┘
                                       │
                                       │             /var/lib/eigenius/
                                       │             substrate-depot/
                                       │             (host bind-mount,
                                       │              UDS sockets)

Kernel (kernel/) — Rust binary. Holds the layer chain (knowledge graph), type-checks programs via the EigenTT kernel, evaluates programs and queries, dispatches IO components and external runtimes to the orchestrator. Exposes a gRPC service on port 50051. Optionally persists state to RocksDB via serve --db <path>.

Orchestrator (orchestration/) — Deno/TypeScript service. Four roles: (a) hosts IO component implementations the kernel cannot embed directly (LLM adapters, HTTP-bearing components); (b) exposes the Model Context Protocol (MCP) server surface for external LLM agents to call kernel operations as tools; (c) serves the notebook SPA at /notebooks/* and proxies the kernel’s RPC surface to browsers via Connect-RPC under /eigenius.v1.*; (d) hosts the runtime substrate addon that spawns sibling worker containers for substrate-hosted institutions (Julia in v1; see chapter 11). Listens on port 8080.

Worker containers — when the kernel dispatches against a substrate-hosted institution, the orchestrator’s substrate addon spawns (or reuses, from a per-image cache) a sibling container running the institution’s language runtime. Workers are siblings of the orchestrator container — Docker-out-of-Docker via the bind-mounted Docker socket — and communicate over a Unix domain socket whose path lives under the depot bind-mount (/var/lib/eigenius/substrate-depot/, reachable at the same path on host and orchestrator). See chapter 11 §11.1.

Notebook (notebooks/) — React + TypeScript single-page app. Bundled into the orchestrator image at build time, served at http://localhost:8080/notebooks/ from a single origin. Cells run ESL, EigenQL, TypeScript, and program invocations against the live kernel; outputs auto-render as typed inspectors, result tables, layer-stack diagrams, and program-trace trees. See chapter 14.

CLI (cli/) — Rust binary (eigenius). Two operation modes:

  • In-process — for file commands and read-only ontology inspection. No kernel server needed.
  • Remote — for live operations against a running kernel. Pass --endpoint http://localhost:50051.

TypeScript SDK (clients/eigenius-ts/) — @eigenius/client. Wraps the orchestrator’s two Connect-RPC services in a single typed Eigen class. The notebook uses it; you can use it programmatically from any TypeScript runtime (browser, Deno, Node). See chapter 17.

1.2. Seven ways to interact with the platform

You’ll touch the platform through one of seven interfaces depending on what you’re doing:

  1. The notebook — the most accessible UX. A React SPA the orchestrator serves at http://localhost:8080/notebooks/ once docker compose up -d is running; cells (markdown, ESL, EigenQL, TypeScript, program-run) run against the live kernel and auto-render typed outputs. Notebook documents are JSON files and can be saved, loaded, or published into the kernel as queryable resources. See chapter 14.

  2. The TypeScript SDK — for programmatic browser / Deno / Node use of the same RPC surface the notebook drives. The Eigen class wraps inspect / query / load / runProgram / runProgramByIri / layerTopology / publishNotebook and a few more. See chapter 17.

  3. The CLI — for ad-hoc operations: load a file, run a program, query the graph, inspect a resource, install a substrate institution, consolidate or merge the chain. The eigenius binary in cli/ is the everyday tool. See chapter 4.

  4. The gRPC API — for programmatic non-TS clients. The kernel exposes a tonic-based gRPC service at --port (default 50051) when running under eigenius serve. Protobuf definitions live in proto/. The CLI and the orchestrator’s TypeScript SDK are both clients of this API.

  5. The kernel as a library — for embedding the kernel in another Rust process. Add eigenius_kernel as a Cargo dependency and use the modules under kernel/src/ directly. This is what the kernel server itself does — the gRPC layer is a thin wrapper over the in-process API.

  6. In-process Rust institutions — for first-party reasoners that need the kernel’s own data structures and a full Cargo dependency tree. The institution is a Rust struct compiled into the kernel binary, pre-registered at startup, then picked up by the boot-time chain scan over Institution declarations carrying runtime: in_process. eigenius-lean and eigenius-statistics are the shipped examples. (eigenius-reasoning was a third until P7 deleted it: checking a certificate is type checking, which the kernel does not delegate.) (A third path, sandboxed WASM extensions, was removed on 2026-07-08: wasmtime is no longer a dependency, eigenius capability install is gone, and the wit/ and sdk/wasm-sdk/ trees were deleted. Chapters 9 and 10 are retained as a historical record of it.)

  7. Runtime substrate institutions — for institutions backed by full language ecosystems (Julia in v1; Python and others planned). Sibling worker containers spawned by the orchestrator’s substrate addon, communicating with the kernel via Eigon-CBOR over UDS. The right path when the institution wants a heavy native library — Symbolics.jl, OrdinaryDiffEq.jl, JuMP+HiGHS, etc. — and the path that replaced WASM extensibility for third-party reasoners. The chain shapes (RuntimePackageMirror, RuntimeEnvironment, RuntimeMethodSignature, Institution { runtime: external }) are committed via eigenius mirror create / env build / env create / institution install. See chapter 11.

1.3. The twenty bootstrap layers

When the kernel starts, it loads twenty immutable layers in a parent-pointer chain. BOOTSTRAP_CHAIN in kernel/src/bootstrap/mod.rs is the single source of truth, root-first — array order is the parent chain:

core → eigentt-type-fragment → program → reflection → obo → institution →
runtime → formulas → lean-expressions → lean-runtime-classes →
lean-institution → reasoning → statistics → notebook → ingest → reference →
logic → lexicon → ontology → closed-class

These are baked into the kernel binary as the embedded ontology, include_str!’d from ontologies/ — ten .json, three Lean .eigon.json, and seven .esl. Every subsequent layer (loaded via eigenius load or eigen.load(...)) sits on top of the whole chain. The notebook layer (ontologies/notebook/notebook-ontology.json) defines Notebook, Cell, and CellType so notebooks published from the UI (chapter 14 §14.5) validate against a live, queryable schema without having to load anything first.

When running with --db <path>, the kernel also seeds a SHA-256 manifest of the embedded ontology on first start. Subsequent restarts verify that the embedded ontologies haven’t drifted from the persisted manifest — see chapter 6 and D13.

1.4. What this guide covers

The chapters in order:

  • Chapters 2–3 — get a development environment building.
  • Chapter 4 — every CLI command, with what it does in process vs. against a running kernel.
  • Chapters 5–7 — running locally, persistence, the orchestrator.
  • Chapter 8 — three of the eleven demo/ scripts, worked end to end.
  • Chapters 9–10 — WASM components and institutions. Removed 2026-07-08; retained as a historical record, nothing in them runs.
  • Chapter 11 — extending the kernel with runtime-substrate-hosted institutions (Julia in v1).
  • Chapter 12 — Docker Compose and Azure ContainerApps deployment.
  • Chapters 13 — troubleshooting.
  • Chapter 14 — the notebook UX (cells, file format, publish-to-layer, the patent and kinase-institutions demos).
  • Chapter 15 — tags, branches, and history in the notebook (the workspace rail’s chain destinations + time-travel read-pin).
  • Chapter 16 — merge resolution: picking strategies (Witness / Rename / SchemaQuotient / Restructure), the cascade gate, provenance records.
  • Chapter 17 — the TypeScript SDK that powers the notebook and that you can use programmatically.
  • Chapter 18 — appendix (env vars, file locations, source index).

1.5. What this guide does not cover

  • ESL syntax / semantics — see the ESL user guide.
  • EigenQL syntax / semantics — see the EigenQL user guide.
  • Formula language — the chain-mirrored EigenTT fragment used by every numerical institution; see the formula language guide.
  • Kernel internals — type theory, NbE, ontology-as-types resolution, etc. See the design documents in docs/design/.

Next: 2. Installation and prerequisites →