Prerequisites Before installing IronClaw, ensure you have the following:
PostgreSQL 15+ with pgvector extensionNEAR AI account (authentication handled via setup wizard)Rust 1.85+ (only if building from source)
Download or build Visit the Releases page to see the latest updates.
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
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 will:
Install IronClaw and dependencies
Add IronClaw to your PATH
Keep it updated with brew upgrade
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:
You should see output like:
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
Download and install from postgresql.org
Install pgvector extension
macOS
Ubuntu/Debian
From source
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: Select libSQL when prompted for database backend.
Create a Turso account at turso.tech
Create a database:
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: 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: 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;"
Ensure you have the latest Rust toolchain: If you’re building with custom features, ensure all dependencies are installed. Check the building tools guide for details. 