Installation

Kairos Substrate is distributed as a native package for Linux and macOS. The installer places only the kairos binary on your system PATH — no configuration files, services, or databases are created.

Native Package Install

Linux (.deb)

Download kairos-substrate_<version>_amd64.deb from the release artifacts, then install:

sudo dpkg -i kairos-substrate_<version>_amd64.deb

Verify:

kairos --help

Uninstall

sudo dpkg -r kairos-substrate

macOS (.pkg)

Download kairos-substrate-<version>-arm64.pkg from the release artifacts.

Caution

The macOS package is not currently signed with a Developer ID certificate. macOS Gatekeeper will block the installer by default. To proceed:

1. Right-click (or Control-click) the .pkg file in Finder.
2. Select Open from the context menu.
3. Click Open in the dialog to confirm.

Alternatively, remove the quarantine attribute from the terminal:

xattr -d com.apple.quarantine kairos-substrate-<version>-arm64.pkg

Then double-click to install normally.

The package installs the binary to /usr/local/bin/kairos.

Verify:

kairos --help

Uninstall

macOS packages do not include a native uninstall mechanism. Remove the binary manually:

sudo rm /usr/local/bin/kairos

To also remove the package receipt (optional):

sudo pkgutil --forget dev.anankelabs.kairos-substrate

Verify Download Integrity

Each release includes a SHA256SUMS file listing all release artifacts. To verify a specific download, extract its line from the manifest:

grep kairos-substrate_<version>_amd64.deb SHA256SUMS | sha256sum -c -

Starter Kit

The starter kit is a separate versioned archive containing reference configuration files and quick-start documentation. It is not required for CLI usage but is useful for coordinator deployments.

Download kairos-substrate-starter-kit-<version>.tar.gz from the release artifacts:

tar xzf kairos-substrate-starter-kit-<version>.tar.gz

Contents:

File	Purpose
README.md	Quick-start guide
coordinator.example.toml	Reference HITL coordinator config (template only)
deployment-policy.reference.json	Reference policy schema (not valid for evaluation)

These files are illustrative. A real signed deployment policy must be obtained from Ananke.

Build from Source

For development, integration targets (native library, Python, WASM), or platforms without a native package, build 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

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.

CLI Binary

# 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

Python Wheel

cd crates/kairos-pylib
maturin build --release

WASM Module

wasm-pack build crates/kairos-wasm --release

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.

Next Steps

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