Building

Kairos Substrate supports three distribution targets, each with different build profiles and optimization strategies.

Rust Toolchain

The project requires Rust 1.94.0+ with the WASM target:

rust-toolchain.toml

[toolchain]
channel = "1.94.0"
components = ["rustfmt", "clippy"]
targets = ["wasm32-unknown-unknown"]

Build Profiles

Two release profiles serve different optimization goals:

[profile.release]
opt-level = "z"        # Optimize for binary size
lto = true
codegen-units = 1
strip = true

[profile.release-native]
inherits = "release"
opt-level = 3          # Optimize for speed
strip = true

Profile	opt-level	Use case
dev	0	Development and debugging
release	z (size)	WASM targets only
release-native	3 (speed)	CLI, native library, Python bindings

The default --release profile uses opt-level = "z" for minimum binary size, which is correct for WASM but significantly underperforms for CPU-bound workloads. Always use --profile release-native for native builds.

Build Commands

CLI Binary

cargo build -p kairos-cli --profile release-native

With TUI dashboard support:

cargo build -p kairos-cli --features tui --profile release-native

Output: target/release-native/kairos

Native Library (C FFI)

# Core engine only
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 research-mode constructors
cargo build -p kairos-ffi --profile release-native --features fly-by-wire,dynamic-config

Outputs:

• Linux: target/release-native/libkairos_engine.so
• macOS: target/release-native/libkairos_engine.dylib
• Windows: target/release-native/kairos_engine.dll
• Header: crates/kairos-ffi/kairos_engine.h

Python Wheel

cd crates/kairos-pylib
maturin build --release
pip install target/wheels/kairos_engine-*.whl

Requires pip install maturin. Python 3.9+.

WASM Module

# Default (WasmEngine only)
wasm-pack build crates/kairos-wasm --target web

# With fly-by-wire
wasm-pack build crates/kairos-wasm --target web --features fly-by-wire

# For Node.js
wasm-pack build crates/kairos-wasm --target nodejs --features fly-by-wire

Output: npm package in crates/kairos-wasm/pkg/

Cross-Compilation

Use cross for cross-platform builds:

cargo install cross

Supported Targets

# Linux x86_64
cross build -p kairos-ffi --profile release-native --target x86_64-unknown-linux-gnu

# Linux ARM64
cross build -p kairos-ffi --profile release-native --target aarch64-unknown-linux-gnu

# Windows x86_64
cross build -p kairos-ffi --profile release-native --target x86_64-pc-windows-gnu

Platform Matrix

Platform	Architecture	Target triple	Notes
Linux	x86_64	x86_64-unknown-linux-gnu	GLIBC 2.17+ (CentOS 7+)
Linux	ARM64	aarch64-unknown-linux-gnu
macOS	x86_64	x86_64-apple-darwin
macOS	ARM64	aarch64-apple-darwin	Apple Silicon native
Windows	x86_64	x86_64-pc-windows-gnu	MinGW toolchain
Browser/Node	WASM	wasm32-unknown-unknown	Via wasm-pack

Feature Flags

Feature flags control which capabilities are compiled in. See Feature Flags for the full matrix.

Key build-time choices:

Feature	Effect
tui	Enables kairos observe TUI dashboard (CLI only)
fly-by-wire	Enables Substrate session and HITL protocol
slm	Enables Sentinel SLM backend (SmolLM2 inference)
license	Enables cryptographic policy/license verification
dynamic-config	Enables research-mode constructors with file paths

CI Integration

The scripts/ci-check.sh script runs the standard verification pipeline:

./scripts/ci-check.sh         # Full check
./scripts/ci-check.sh --quick  # Lib tests only (faster)

Steps:

1. cargo clippy --workspace -- -D warnings — lint with warnings-as-errors
2. cargo test --workspace — full test suite (or --lib in quick mode)
3. wasm-pack build — WASM build verification