Installation

Prerequisites

Before installing IronClaw, ensure you have the following:

PostgreSQL 15+ with pgvector extension
NEAR AI account (authentication handled via setup wizard)
Rust 1.85+ (only if building from source)

You can also use libSQL/Turso as an embedded database alternative. See the database configuration guide for details.

Download or build

Visit the Releases page to see the latest updates.

Windows
macOS
Linux
WSL

Windows Installer (recommended)

Download and run the Windows Installer.The installer will:

Install IronClaw to Program Files
Add IronClaw to your PATH
Create a desktop shortcut

PowerShell script

Run this command in PowerShell:

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

The script will:

Download the latest release
Extract to %LOCALAPPDATA%\ironclaw
Add IronClaw to your PATH

Cargo (build from source)

Install with cargo, requires Rust installed:

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

# Build
cargo build --release

# Run tests
cargo test

For full release (after modifying channel sources), run ./scripts/build-all.sh to rebuild channels first.

Homebrew (recommended)

brew install ironclaw

Homebrew will:

Install IronClaw and dependencies
Add IronClaw to your PATH
Keep it updated with brew upgrade

Shell script

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

The script will:

Download the latest release
Extract to ~/.ironclaw/bin
Add IronClaw to your PATH

Cargo (build from source)

Install with cargo, requires Rust installed:

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

# Build
cargo build --release

# Run tests
cargo test

For full release (after modifying channel sources), run ./scripts/build-all.sh to rebuild channels first.

Shell script (recommended)

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

The script will:

Download the latest release
Extract to ~/.ironclaw/bin
Add IronClaw to your PATH

Cargo (build from source)

Install with cargo, requires Rust installed:

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

# Build
cargo build --release

# Run tests
cargo test

For full release (after modifying channel sources), run ./scripts/build-all.sh to rebuild channels first.

Shell script (recommended)

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

The script will:

Download the latest release
Extract to ~/.ironclaw/bin
Add IronClaw to your PATH

Verify installation

After installation, verify that IronClaw is in your PATH:

ironclaw --version

You should see output like:

ironclaw 0.1.0

Database setup

IronClaw requires PostgreSQL with the pgvector extension for persistent storage and semantic search.

Install PostgreSQL

macOS
Ubuntu/Debian
Windows

brew install postgresql@15
brew services start postgresql@15

sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql

Install pgvector extension

macOS
Ubuntu/Debian
From source

brew install pgvector

sudo apt install postgresql-15-pgvector

git clone https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install

Create database

# Create database
createdb ironclaw

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

If you encounter permission errors, you may need to run these commands as the postgres user:

sudo -u postgres createdb ironclaw
sudo -u postgres psql ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"

Verify database connection

psql ironclaw -c "SELECT version();"

You should see PostgreSQL version information.

If you see an error about pgvector not being installed:

ERROR:  extension "vector" is not available

Ensure the pgvector extension is properly installed and restart PostgreSQL:

# macOS
brew services restart postgresql@15

# Ubuntu/Debian
sudo systemctl restart postgresql

Then re-run:

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

Alternative: libSQL/Turso

If you prefer an embedded database, you can use libSQL (SQLite-compatible) or Turso (cloud SQLite):

libSQL (local)
Turso (cloud)

No installation required. IronClaw will create a local database file at ~/.ironclaw/ironclaw.db automatically.Set the database backend during onboarding:

ironclaw onboard

Select libSQL when prompted for database backend.

Create a Turso account at turso.tech
Create a database:
turso db create ironclaw

Get your database URL and auth token:

turso db show ironclaw --url
turso db tokens create ironclaw

Set environment variables:

export LIBSQL_URL=libsql://your-db.turso.io
export LIBSQL_AUTH_TOKEN=your-token

Embedding dimension compatibility: The libSQL schema uses F32_BLOB(1536) which requires exactly 1536 dimensions. If using non-OpenAI embedding models with different dimensions, use PostgreSQL instead.

Next steps

Now that IronClaw is installed and your database is set up, proceed to the onboarding wizard:

Run onboarding

Configure IronClaw with the interactive setup wizard

Troubleshooting

Command not found: ironclaw

The IronClaw binary is not in your PATH. Add it manually:

macOS/Linux
Windows

export PATH="$HOME/.ironclaw/bin:$PATH"

Add this to your shell profile (~/.bashrc, ~/.zshrc, etc.) to make it permanent.

Add %LOCALAPPDATA%\ironclaw\bin to your PATH environment variable:

Open System Properties → Advanced → Environment Variables
Edit the PATH variable
Add %LOCALAPPDATA%\ironclaw\bin
Restart your terminal

PostgreSQL connection refused

Ensure PostgreSQL is running:

macOS
Ubuntu/Debian
Windows

brew services start postgresql@15

sudo systemctl start postgresql

Start the PostgreSQL service from Services (Win+R → services.msc)

pgvector extension not found

Install pgvector and restart PostgreSQL:

macOS
Ubuntu/Debian

brew install pgvector
brew services restart postgresql@15

sudo apt install postgresql-15-pgvector
sudo systemctl restart postgresql

Then enable the extension:

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

Cargo build fails

Ensure you have the latest Rust toolchain:

rustup update

If you’re building with custom features, ensure all dependencies are installed. Check the building tools guide for details.

Get Started

Core Concepts

Configuration

Features

Security

Guides

Prerequisites

Download or build

Verify installation

Database setup

Alternative: libSQL/Turso

Next steps

Run onboarding

Troubleshooting

​Prerequisites

​Download or build

​Verify installation

​Database setup

​Alternative: libSQL/Turso

​Next steps

Run onboarding

​Troubleshooting

Prerequisites

Download or build

Verify installation

Database setup

Alternative: libSQL/Turso

Next steps

Troubleshooting