Installation

System Requirements

Database

PostgreSQL 15+ with pgvector extension, OR
libSQL/SQLite (embedded, zero dependencies)

Runtime

Rust 1.92+ (if building from source)
4GB RAM minimum, 8GB recommended
macOS, Linux, or Windows (WSL supported)

PostgreSQL users: The pgvector extension is required for semantic search. See the PostgreSQL Setup section below for installation instructions.

Quick Install

Choose your platform and installation method:

macOS / Linux
Windows
Build from Source

Install via shell script

Download and run the installer:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh

This installs IronClaw to ~/.cargo/bin/ironclaw.

Verify installation

Check that IronClaw is installed:

ironclaw --version

You should see the version number (e.g., ironclaw 0.13.1).

Alternative: Homebrew (macOS/Linux)

brew install ironclaw

Homebrew automatically adds IronClaw to your PATH.

PowerShell Installer
MSI Installer
WSL (Windows Subsystem for Linux)

Run installer script

Open PowerShell and run:

irm https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.ps1 | iex

This installs IronClaw to your user profile.

Verify installation

ironclaw --version

You should see the version number.

Download MSI package

Download the Windows Installer from the releases page.

Run installer

Double-click the .msi file and follow the installation wizard.

Verify installation

Open a new PowerShell window:

ironclaw --version

Install Rust

If you don’t have Rust installed, get it from rustup.rs:

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

Ensure you have Rust 1.92 or newer:

rustc --version

Clone the repository

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

Build release binary

cargo build --release

The binary will be at target/release/ironclaw.

(Optional) Install globally

cargo install --path .

This adds ironclaw to ~/.cargo/bin, which is usually in your PATH.

Run tests

cargo test

Some tests require a database connection. Set DATABASE_URL or skip integration tests.

Building channels and tools from source

IronClaw bundles precompiled WASM channels (Telegram, Slack, etc.) in the binary. If you modify channel sources, rebuild them before compiling:

./scripts/build-all.sh
cargo build --release

Database Setup

IronClaw supports two database backends:

PostgreSQL (Recommended for Production)
libSQL/SQLite (Embedded, Zero Dependencies)

PostgreSQL Setup

Install PostgreSQL 15+

brew install postgresql@15
brew services start postgresql@15

Install pgvector extension

The pgvector extension is required for IronClaw’s semantic search features.

brew install pgvector

If using Docker with the pgvector/pgvector image, pgvector is already installed.

Create database

# Create database
createdb ironclaw

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

On Docker, run:

docker exec -it ironclaw-postgres createdb -U postgres ironclaw
docker exec -it ironclaw-postgres psql -U postgres ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"

Set DATABASE_URL

The setup wizard will ask for your database URL, or you can set it now:

export DATABASE_URL=postgres://localhost/ironclaw
# Or with credentials:
export DATABASE_URL=postgres://user:password@localhost:5432/ironclaw

Using a managed PostgreSQL provider

IronClaw works with cloud PostgreSQL providers like:

Neon — Serverless PostgreSQL with auto-scaling
Supabase — PostgreSQL with built-in auth and storage
Render — Managed PostgreSQL with free tier
AWS RDS — Production-grade managed PostgreSQL

Make sure pgvector is enabled (Neon and Supabase include it by default).

libSQL Setup

libSQL is perfect for local development and single-user deployments. No external database server required.

Choose local or remote

IronClaw supports:

Local file — Embedded SQLite database (default: ~/.ironclaw/ironclaw.db)
Turso — Cloud-synced SQLite with remote replicas

Set environment variables

For local file only:

export DATABASE_BACKEND=libsql
export LIBSQL_PATH=~/.ironclaw/ironclaw.db

For Turso cloud sync:

export DATABASE_BACKEND=libsql
export LIBSQL_PATH=~/.ironclaw/ironclaw.db
export LIBSQL_URL=libsql://your-db.turso.io
export LIBSQL_AUTH_TOKEN=eyJhbGc...

The setup wizard will guide you through this. You can skip manual configuration and run ironclaw onboard directly.

No installation required

libSQL is embedded in the IronClaw binary. The database file is created automatically on first run.

When to use libSQL vs PostgreSQL

Feature	libSQL	PostgreSQL
Setup	Zero dependencies	Requires server
Performance	Fast for single-user	Better for high concurrency
Deployment	Perfect for local/embedded	Production-ready at scale
Vector search	Basic support	Advanced (pgvector)
Cloud sync	Turso (optional)	Managed providers

Use libSQL if: You want zero-dependency local deployment or are developing/testing.Use PostgreSQL if: You need production-grade persistence, high concurrency, or advanced vector search.

Verify Installation

Run the version command to confirm IronClaw is installed:

ironclaw --version

You should see output like:

ironclaw 0.13.1

Next Steps

Quick Start

Complete the setup wizard and chat with IronClaw

Configuration

Configure LLM providers, secrets, and channels

Updating IronClaw

To update to the latest version:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh

IronClaw includes an automatic updater. Run ironclaw update to check for and install the latest version.

Troubleshooting

pgvector extension not found

Error: pgvector extension not found on your PostgreSQL serverSolution:

Install pgvector for your PostgreSQL version (see PostgreSQL Setup)
Restart PostgreSQL: sudo systemctl restart postgresql (Linux) or brew services restart postgresql@15 (macOS)
Re-run setup: ironclaw onboard

PostgreSQL version too old

Error: PostgreSQL 14 detected. IronClaw requires PostgreSQL 15 or laterSolution: Upgrade PostgreSQL to version 15 or later. See https://www.postgresql.org/download/ for instructions.

ironclaw command not found

Error: command not found: ironclawSolution:

Make sure ~/.cargo/bin is in your PATH (Rust installer adds this automatically)
Restart your terminal or run source ~/.bashrc (or ~/.zshrc)
If using Homebrew, run brew doctor to check for PATH issues

Database connection failed

Error: Failed to connect to databaseSolution:

Ensure PostgreSQL is running: brew services list (macOS) or systemctl status postgresql (Linux)
Check your DATABASE_URL is correct: echo $DATABASE_URL
Test connection manually: psql $DATABASE_URL
For libSQL, ensure the parent directory exists: mkdir -p ~/.ironclaw

Getting Started

Core Concepts

CLI Reference

Channels

Tools & Extensions

Advanced

Security

Development

System Requirements

Database

Runtime

Quick Install

Database Setup

PostgreSQL Setup

libSQL Setup

Verify Installation

Next Steps

Quick Start

Configuration

Updating IronClaw

Troubleshooting

Build docs developers (and LLMs) love

Getting Started

Core Concepts

CLI Reference

Channels

Tools & Extensions

Advanced

Security

Development

Documentation Index

​System Requirements

Database

Runtime

​Quick Install

​Database Setup

​PostgreSQL Setup

​libSQL Setup

​Verify Installation

​Next Steps

Quick Start

Configuration

​Updating IronClaw

​Troubleshooting

Build docs developers (and LLMs) love

System Requirements

Quick Install

Database Setup

PostgreSQL Setup

libSQL Setup

Verify Installation

Next Steps

Updating IronClaw

Troubleshooting