Installation

Kairos Substrate is distributed as source code. You build the specific target you need from the kairos-engine workspace.

Prerequisites

Tool	Version	Purpose
Rust	1.94+ (edition 2024)	Core toolchain — pinned via rust-toolchain.toml
wasm-pack	Latest	WASM builds only
maturin	Latest	Python wheel builds only

Platform Matrix

Platform	Architecture	CLI	Native lib	Python	WASM
Linux	x86_64	Yes	Yes	Yes	Yes
Linux	aarch64	Yes	Yes	Yes	Yes
macOS	x86_64	Yes	Yes	Yes	Yes
macOS	aarch64 (Apple Silicon)	Yes	Yes	Yes	Yes
Windows	x86_64	Yes	Yes	Yes	Yes

WASM builds are platform-independent — wasm32-unknown-unknown produces identical output on any host.

Build Profiles

Two release profiles exist because WASM and native targets have opposing optimization goals:

Profile	opt-level	Use case
release	z (size)	WASM only
release-native	3 (speed)	CLI, FFI, Python

Caution

Do not use --release for native targets. The release profile uses size optimization (opt-level="z"), which causes 20–40% performance degradation on CPU-bound simulation work. Always use --profile release-native for CLI, FFI, and Python builds.

Build Commands

CLI Binary

# Standard CLI (speed-optimized)
cargo build -p kairos-cli --profile release-native

# CLI with the observe TUI dashboard
cargo build -p kairos-cli --features tui --profile release-native

The built binary is at target/release-native/kairos.

Native Library (C FFI)

# Shared + static library
cargo build -p kairos-ffi --profile release-native

# With fly-by-wire session support
cargo build -p kairos-ffi --profile release-native --features fly-by-wire

# With dynamic artifact loading (research mode)
cargo build -p kairos-ffi --profile release-native --features fly-by-wire,dynamic-config

The generated C header is kairos_engine.h. The shared library is libkairos_engine.so (Linux), libkairos_engine.dylib (macOS), or kairos_engine.dll (Windows).

Python Wheel

cd crates/kairos-pylib
maturin build --release

The wheel is placed in target/wheels/.

WASM Module

# Standard WASM (size-optimized)
wasm-pack build crates/kairos-wasm --release

# WASM with fly-by-wire session bindings
wasm-pack build crates/kairos-wasm --release --features fly-by-wire

Running Tests

# All workspace tests
cargo test --workspace

# Tests with fly-by-wire features
cargo test --workspace --features fly-by-wire

# HITL regression without license feature
cargo test -p kairos-rosetta-inbound --test hitl_no_license_test \
  --no-default-features --features fly-by-wire

Next Steps

After building, you need to activate a license before running evaluations.