Building from Source

Complete guide to building IronClaw from source code

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:

1. Verifies rustup installation
2. Adds the wasm32-wasip2 target
3. Installs wasm-tools
4. Runs cargo check to verify compilation
5. 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:

1. Builds all bundled channels in channels-src/
2. Builds IronClaw with --release
3. 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:

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

Additional Resources

• Rust Installation Guide
• Cargo Book
• WASM Component Model
• PostgreSQL Downloads
• pgvector Documentation