Aleph
Development

Building

Build Aleph from source — prerequisites, workspace structure, feature flags, and release profiles.

This guide covers everything you need to compile Aleph from source, from installing the Rust toolchain to producing optimized release binaries.

Prerequisites

Rust Toolchain

Aleph requires Rust 1.95 or later (edition 2021). The MSRV is raised by sysinfo 0.39, and rust-toolchain.toml pins the build to 1.96.0. Install via rustup:

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Accept the rust-toolchain.toml pin
rustup show

# Verify the version
rustc --version   # must be >= 1.95
cargo --version

If you plan to build the Control Plane UI (the embedded web dashboard), you also need the WASM target:

rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli

System Dependencies

Aleph bundles most of its dependencies via Cargo, but a few system-level libraries are needed:

DependencyPurposeNotes
SQLiteSession storage, memory DBBundled via rusqlite bundled feature — no system install needed
OpenSSLTLS for HTTP clientsmacOS: provided by the system. Linux: libssl-dev (Debian) or openssl-devel (Fedora)
pkg-configLocating system librariesLinux only: apt install pkg-config or dnf install pkgconf
C compilerNative dependency compilationXcode Command Line Tools (macOS) or build-essential (Linux)
Node.js + npmControl Plane CSS build (optional)Only required when building with the control-plane feature

On macOS, the Xcode Command Line Tools provide everything:

xcode-select --install

On Debian/Ubuntu:

sudo apt update
sudo apt install build-essential pkg-config libssl-dev

Environment Variables

The server requires an API key at runtime (not at build time):

# Set in your shell profile or ~/.aleph/config.toml
export ANTHROPIC_API_KEY="your-api-key"

Workspace Structure

Aleph uses a Cargo workspace with members organized by role:

Aleph/
├── Cargo.toml                  # Workspace root + alephcore package
├── src/                        # alephcore — main library + server binary
│   ├── lib.rs                  # Library crate entrypoint
│   └── bin/aleph-server/       # Server binary
├── desktop/
│   ├── shared/                 # DesktopCapability trait + IPC protocol
│   ├── shell/                  # Tauri desktop shell
│   ├── macos/                  # macOS native implementation
│   ├── linux/                  # Linux native implementation
│   └── windows/                # Windows native implementation
├── shared/
│   ├── protocol/               # aleph-protocol — shared types
│   ├── logging/                # Logging infrastructure
│   ├── ui_logic/               # Shared UI logic
│   └── client/                 # Shared client utilities
└── interfaces/
    ├── cli/                    # Terminal client
    ├── tui/                    # TUI client
    └── webchat/                # Web-based chat interface (WASM)

The workspace root Cargo.toml defines shared dependency versions so all members stay in sync:

[workspace]
resolver = "2"
members = [
    "desktop/shared",
    "desktop/macos",
    "desktop/linux",
    "desktop/windows",
    "desktop/shell",
    "shared/logging",
    "shared/protocol",
    "shared/ui_logic",
    "shared/client",
    "interfaces/cli",
    "interfaces/tui",
    "interfaces/webchat",
]

[workspace.package]
version = "26.7.21"   # CalVer; keep in sync with the VERSION file
edition = "2021"
license = "MIT"
rust-version = "1.95"

Feature Flags

Aleph compiles all production features by default. Only test and experimental features are gated (kept in sync with Cargo.toml):

[features]
default = []
loom = ["dep:loom"]               # Concurrency testing with Loom
test-helpers = []                  # Integration test utilities
control-plane = []                 # Experimental: Control Plane UI (Leptos/WASM dashboard)
disabled-tests = []                # Disabled test modules (awaiting rewrite)
plugin-wasm = []                   # Placeholder for the in-flight WASM plugin runtime; keeps `tests/wasm_capability_test.rs`'s `cfg(feature = "plugin-wasm")` gate

No feature flags are required for production builds. All channels, tools, and integrations are compiled and enabled/disabled at runtime via config.toml configuration.

Building

# Default build (all production features)
cargo run -p alephcore --bin aleph-server

# Release build
cargo build -p alephcore --bin aleph-server --release

# With Loom concurrency testing
cargo test -p alephcore --features loom --lib loom

Build Profiles

Debug Build (Development)

# Fast compilation, slower runtime, full debug symbols
cargo build -p alephcore --bin aleph-server

# Run directly (build + execute)
cargo run -p alephcore --bin aleph-server

Debug builds compile quickly but produce large, unoptimized binaries. Use this for day-to-day development.

Release Build (Production)

# Optimized binary
cargo build -p alephcore --bin aleph-server --release

# Binary location
ls -lh target/release/aleph-server

The workspace release profile strips debug symbols:

[profile.release]
strip = true

Verifying a Build

# Check version
./target/release/aleph-server --version

# Check help
./target/release/aleph-server --help

# Verify embedded UI assets (if built with control-plane)
strings target/release/aleph-server | grep "index.html"

Building the WebChat Panel UI

The WebChat Panel is a web-based chat interface compiled to WASM and served by the Gateway. The just build pipeline handles this automatically via the wasm recipe.

Manual WASM Build

If you need to build the WASM panel separately:

# The justfile handles the full WASM build pipeline:
just wasm

This will:

  1. Compile Tailwind CSS (interfaces/webchat)
  2. Build the Rust code to WASM (cargo build -p aleph-panel --target wasm32-unknown-unknown)
  3. Generate JavaScript bindings with wasm-bindgen
  4. Create the runtime index.html

The Gateway serves the WASM assets directly from interfaces/webchat/dist/.

The project includes a justfile with common build tasks. Install just first:

cargo install just

Available recipes:

# Show all available recipes
just --list

# Development: build WASM panel + run server in debug mode
just dev

# Full release build (WASM + Swift bridge + server)
just build

# Build server only (debug)
just build-debug

# Build WASM Panel UI only
just wasm

# Quick compilation check
cargo check -p alephcore

# Run core tests
just test

# Run all tests (core + desktop + proptest)
just test-all

# Lint with clippy
just clippy

# Clean build artifacts
just clean

Cross-Compilation Notes

Aleph is primarily developed and tested on macOS (ARM64). Cross-compilation targets to be aware of:

TargetStatusNotes
aarch64-apple-darwinPrimaryDefault development target
x86_64-apple-darwinSupportedIntel Mac builds
x86_64-unknown-linux-gnuSupportedLinux server deployment
aarch64-unknown-linux-gnuSupportedLinux ARM (Raspberry Pi, etc.)
wasm32-unknown-unknownRequiredControl Plane UI only

For Linux cross-compilation from macOS, consider using cross:

cargo install cross
cross build --bin aleph-server --target x86_64-unknown-linux-gnu --release

Build Troubleshooting

rusqlite Fails to Compile

The bundled feature flag compiles SQLite from source, requiring a C compiler. On Linux:

sudo apt install build-essential

OpenSSL Linking Errors

If reqwest fails to link OpenSSL on Linux:

sudo apt install libssl-dev pkg-config

On macOS, this should not occur because native-tls uses the system Security framework.

WASM Build Fails

If the Control Plane WASM build fails, ensure the target is installed:

rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli

Note: The server builds successfully without the UI. If the dist/ directory exists, build.rs skips the UI build step. The control-plane feature is optional.

Port Already in Use

If the server fails to start because port 18790 is occupied:

# Find the process using the port
lsof -i :18790

# Kill it
kill -9 <PID>

# Or start on a different port
cargo run --bin aleph-server -- --port 8080

Slow Builds

For faster incremental builds during development:

# Use the mold linker (Linux)
cargo install mold
RUSTFLAGS="-C link-arg=-fuse-ld=mold" cargo build

# Or reduce codegen units in dev profile (already the default)
# [profile.dev]
# codegen-units = 256  # More units = faster compile, slower runtime

Consider using cargo check instead of cargo build when you only need to verify compilation without producing a binary.

26.7.x Addendum

Rust Toolchain 1.95+

26.7.x: rust-version in Cargo.toml has been bumped to 1.95. Use rustup install 1.95 or rust-toolchain.toml in development.

Harness 12 Files + Line-Count Ratchet

Code is the authority — every doc number is just a copy of CEILING:

  • Top-level 8 + agent/ 4 = 12 files (tests under tests/ do not count toward the ratchet)
  • Line count gated by src/harness/tests/budget.rs ratchet, bound to the CEILING constant
  • Current CEILING = 5,055 (src/harness/tests/budget.rs:335, 2026-07-26 revision); treat any line count reproduced here as a stale copy
  • The 3 questions before adding code: scaffolding vs cognition? Will a model upgrade still need it? How many real consumers does it have?

YAGNI Withdrawal

Any abstraction with zero consumers is deleted immediately. ~5,200 lines of dead code were removed cumulatively during harness dissolution.

Fail-Closed

26.7.21 hardening: when a policy file is missing or permissive_default disagrees with Default::default(), authorization is refused.

Process-Isolation Kernel

26.7.x: sandbox restricted-token / job-object / AppContainer / integrity-level / SID·ACL syscalls are issued in-place at spawn — a legitimate carve-out from R1.

aleph-server prompt-size

R9 prompt-scaffolding size check command.

Full RPC ~265

26.7.x the gateway exposes ~265 RPC methods — when developing new methods, refer to Gateway Methods Reference.

See Also

Configuration Management

Read, write, validate, and reload Aleph configuration from the CLI

Testing

Test framework, test categories, running tests, mocking patterns, and CI pipeline.

On this page

PrerequisitesRust ToolchainSystem DependenciesEnvironment VariablesWorkspace StructureFeature FlagsBuildingBuild ProfilesDebug Build (Development)Release Build (Production)Verifying a BuildBuilding the WebChat Panel UIManual WASM BuildUsing Just (Recommended)Cross-Compilation NotesBuild Troubleshootingrusqlite Fails to CompileOpenSSL Linking ErrorsWASM Build FailsPort Already in UseSlow Builds26.7.x AddendumRust Toolchain 1.95+Harness 12 Files + Line-Count RatchetYAGNI WithdrawalFail-ClosedProcess-Isolation Kernelaleph-server prompt-sizeFull RPC ~265See Also