Building from Source

Prerequisites

Before building IronClaw, ensure you have the following installed:

Required

Rust 1.85+: Install via rustup

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

WASM target: Required for building bundled channels
```
rustup target add wasm32-wasip2
```
wasm-tools: Required for WASM component model
```
cargo install wasm-tools --locked
```

Database Options

Choose one or both:

PostgreSQL (Recommended for Production)

PostgreSQL 15+ with pgvector extension

# macOS
brew install postgresql@15 pgvector

# Ubuntu/Debian
sudo apt-get install postgresql-15 postgresql-15-pgvector

# Create database
createdb ironclaw

# Enable pgvector
psql ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"

libSQL (For Development)

No installation needed - embedded database included
Perfect for development and testing
Zero-dependency local mode

Quick Setup

The fastest way to get started:

# Clone the repository
git clone https://github.com/nearai/ironclaw.git
cd ironclaw

# Run developer setup script
./scripts/dev-setup.sh

This script:

Verifies rustup installation
Adds the wasm32-wasip2 target
Installs wasm-tools
Runs cargo check to verify compilation
Runs tests using libSQL (no external database needed)

Manual Build Process

1. Clone the Repository

git clone https://github.com/nearai/ironclaw.git
cd ironclaw

2. Development Build

Build with default features (PostgreSQL + libSQL):

cargo build

The binary will be at target/debug/ironclaw.

3. Release Build

Build optimized binary:

cargo build --release

The binary will be at target/release/ironclaw.

4. Run the Binary

# Development build
cargo run

# Or use the binary directly
./target/release/ironclaw

Build Features

IronClaw supports multiple feature flags for different configurations.

Default Features

# Build with postgres + libsql + html-to-markdown
cargo build

Includes:

postgres: PostgreSQL database support
libsql: Embedded database support
html-to-markdown: HTML content conversion

PostgreSQL Only

cargo build --no-default-features --features postgres

libSQL Only (Embedded)

cargo build --no-default-features --features libsql

All Features

cargo build --all-features

Building WASM Channels

IronClaw bundles WASM channels directly into the binary. After modifying channel source code, rebuild them:

Build Specific Channel

# Telegram channel
./channels-src/telegram/build.sh

# Then rebuild IronClaw
cargo build --release

Build All Channels

Use the convenience script:

./scripts/build-all.sh

This script:

Builds all bundled channels in channels-src/
Builds IronClaw with --release
Outputs binary to target/release/ironclaw

Build Configuration

Cargo.toml Overview

Key configuration from Cargo.toml:

[package]
name = "ironclaw"
version = "0.13.1"
edition = "2024"
rust-version = "1.92"

[features]
default = ["postgres", "libsql", "html-to-markdown"]
postgres = [...]
libsql = ["dep:libsql"]
integration = []
html-to-markdown = ["dep:html-to-markdown-rs", "dep:readabilityrs"]

Build Profiles

Development (default)

cargo build

Fast compilation
Debug symbols included
No optimizations

Release

cargo build --release

Full optimizations
Stripped debug symbols
Slower compilation

Distribution

cargo build --profile dist

Used by cargo-dist for releases
Thin LTO for smaller binaries
Inherits from release profile

Platform-Specific Builds

macOS

# Intel Mac
rustup target add x86_64-apple-darwin
cargo build --release --target x86_64-apple-darwin

# Apple Silicon
rustup target add aarch64-apple-darwin
cargo build --release --target aarch64-apple-darwin

Linux

# x86_64
rustup target add x86_64-unknown-linux-gnu
cargo build --release --target x86_64-unknown-linux-gnu

# ARM64
rustup target add aarch64-unknown-linux-gnu
cargo build --release --target aarch64-unknown-linux-gnu

Windows

# MSVC toolchain
rustup target add x86_64-pc-windows-msvc
cargo build --release --target x86_64-pc-windows-msvc

Cross-Compilation

For cross-compilation, use cross:

cargo install cross

# Build for ARM64 Linux on x86_64
cross build --release --target aarch64-unknown-linux-gnu

Troubleshooting

Missing wasm32-wasip2 Target

Error: error: can't find target wasm32-wasip2 Solution:

rustup target add wasm32-wasip2

wasm-tools Not Found

Error: Build script fails with “wasm-tools not found” Solution:

cargo install wasm-tools --locked

PostgreSQL Connection Failed

Error: could not connect to server Solution:

# Check PostgreSQL is running
pg_isready

# Start PostgreSQL
brew services start postgresql@15  # macOS
sudo systemctl start postgresql    # Linux

# Verify database exists
psql -l | grep ironclaw

pgvector Extension Missing

Error: extension "vector" is not available Solution:

# Install pgvector
brew install pgvector              # macOS
sudo apt install postgresql-15-pgvector  # Ubuntu

# Enable in database
psql ironclaw -c "CREATE EXTENSION vector;"

OpenSSL Errors (Linux)

Error: could not find system library 'openssl' Solution:

# Ubuntu/Debian
sudo apt-get install libssl-dev pkg-config

# Fedora/RHEL
sudo dnf install openssl-devel pkg-config

Compilation Memory Issues

Error: Compiler runs out of memory Solution:

# Reduce parallel jobs
cargo build --release -j 2

# Or set in ~/.cargo/config.toml
[build]
jobs = 2

Linker Errors on macOS

Error: ld: library not found Solution:

# Install Xcode Command Line Tools
xcode-select --install

Build Scripts

IronClaw includes convenience scripts for common build tasks:

dev-setup.sh

Complete development environment setup:

./scripts/dev-setup.sh

Checks dependencies
Adds WASM targets
Installs wasm-tools
Runs initial build and tests

build-all.sh

Full release build with channels:

./scripts/build-all.sh

Builds all WASM channels
Builds IronClaw with --release
Outputs to target/release/ironclaw

Build Time Optimization

Use Cargo Cache

# Install sccache
cargo install sccache

# Configure in ~/.cargo/config.toml
[build]
rustc-wrapper = "sccache"

Incremental Compilation

Enabled by default for debug builds:

# In Cargo.toml
[profile.dev]
incremental = true

Parallel Builds

Maximize CPU usage:

# Use all CPU cores (default)
cargo build --release

# Limit parallel jobs
cargo build --release -j 4

Verifying Your Build

Check Version

./target/release/ironclaw --version
# ironclaw 0.13.1

Run Tests

cargo test

See Running Tests for detailed testing guide.

Run the REPL

./target/release/ironclaw

You should see the IronClaw interactive prompt.

Next Steps

After building successfully:

Configure IronClaw: Run ironclaw onboard for setup wizard
Run Tests: See Running Tests
Start Contributing: Read Contributing Guide
Check Feature Parity: Review Feature Parity

Getting Started

Core Concepts

CLI Reference

Channels

Tools & Extensions

Advanced

Security

Development

Documentation Index

​Prerequisites

​Required

​Database Options

​PostgreSQL (Recommended for Production)

​libSQL (For Development)

​Quick Setup

​Manual Build Process

​1. Clone the Repository

​2. Development Build

​3. Release Build

​4. Run the Binary

​Build Features

​Default Features

​PostgreSQL Only

​libSQL Only (Embedded)

​All Features

​Building WASM Channels

​Build Specific Channel

​Build All Channels

​Build Configuration

​Cargo.toml Overview

​Build Profiles

​Development (default)

​Release

​Distribution

​Platform-Specific Builds

​macOS

​Linux

​Windows

​Cross-Compilation

​Troubleshooting

​Missing wasm32-wasip2 Target

​wasm-tools Not Found

​PostgreSQL Connection Failed

​pgvector Extension Missing

​OpenSSL Errors (Linux)

​Compilation Memory Issues

​Linker Errors on macOS

​Build Scripts

​dev-setup.sh

​build-all.sh

​Build Time Optimization

​Use Cargo Cache

​Incremental Compilation

​Parallel Builds

​Verifying Your Build

​Check Version

​Run Tests

​Run the REPL

​Next Steps

​Additional Resources

Build docs developers (and LLMs) love