Skip to main content
Get your secure AI assistant running in just a few steps. This guide will take you from zero to a working IronClaw installation.

​
Prerequisites

Before you begin, make sure you have:
  • Rust 1.85+ (if building from source)
  • PostgreSQL 15+ with pgvector extension
  • A NEAR AI account (free tier available) or API key for another LLM provider
If you don’t have PostgreSQL installed, see the database configuration guide for installation instructions.

​
Quick start

1

Install IronClaw

Choose your preferred installation method:
The installer adds ironclaw to your PATH automatically. Restart your terminal if the command isn’t found.
2

Set up your database

Create a PostgreSQL database and enable the pgvector extension:
If you prefer an embedded database, IronClaw supports libSQL/Turso:
Configure it during onboarding by selecting libSQL as your database backend.
3

Run the onboarding wizard

Configure IronClaw with the interactive setup wizard:
The wizard will guide you through:
  1. Database setup - Enter your PostgreSQL connection string or choose libSQL
  2. LLM provider - Authenticate with NEAR AI or configure an alternative provider
  3. Secrets encryption - Choose OS keychain, environment variable, or skip
  4. Embeddings - Enable semantic search with OpenAI, Ollama, or NEAR AI
  5. Channels - Optional setup for Telegram, HTTP webhooks, or Signal
  6. Extensions - Enable dynamic tool building
  7. Docker sandbox - Enable isolated job execution (requires Docker)
  8. Heartbeat - Enable proactive background monitoring
For most users, the default options (NEAR AI + OS keychain + basic features) are a great starting point. You can always reconfigure later with ironclaw onboard --channels-only or by editing settings.
4

Start using IronClaw

Launch the interactive REPL:
You should see the IronClaw boot screen:
Try some example prompts:

​
What’s next?

Core concepts

Learn about IronClaw’s philosophy, architecture, and security model

Configuration

Configure alternative LLM providers, channels, and advanced features

Features

Explore multi-channel support, dynamic tools, and persistent memory

CLI reference

Complete reference for all commands and options

​
Troubleshooting

The installer should add ironclaw to your PATH automatically. If it doesn’t work:
  1. Restart your terminal to reload PATH
  2. Manually add the installation directory to PATH:
    • Linux/macOS: Add export PATH="$HOME/.cargo/bin:$PATH" to ~/.bashrc or ~/.zshrc
    • Windows: The installer modifies the system PATH—restart your terminal
  3. Verify the binary exists: ls ~/.cargo/bin/ironclaw (Linux/macOS) or where ironclaw (Windows)
Common causes:
  • PostgreSQL not running: Start it with brew services start postgresql (macOS) or sudo systemctl start postgresql (Linux)
  • Wrong credentials: Check your connection string format: postgresql://user:pass@localhost/ironclaw
  • pgvector not installed: Run psql ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"
  • Database doesn’t exist: Create it with createdb ironclaw
See the database configuration guide for detailed troubleshooting.
If the browser OAuth flow doesn’t work:
  1. Get an API key from near.ai
  2. Set it in your environment: export NEARAI_API_KEY=your-key
  3. Re-run ironclaw onboard --skip-auth
Alternatively, configure a different LLM provider during onboarding.
The Docker sandbox requires Docker to be installed and running:After installing, start Docker and verify: docker ps
For more help, run ironclaw doctor to diagnose common issues or check the troubleshooting guide.