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:
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh
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:
# Create the database
createdb ironclaw

# Enable pgvector extension
psql ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"
If you prefer an embedded database, IronClaw supports libSQL/Turso:
# No setup needed - libSQL creates the database automatically
# Database will be stored at ~/.local/share/ironclaw/ironclaw.db
Configure it during onboarding by selecting libSQL as your database backend.
3

Run the onboarding wizard

Configure IronClaw with the interactive setup wizard:
ironclaw onboard
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:
ironclaw run
You should see the IronClaw boot screen:
╔════════════════════════════════════════════════════════════════╗
║                         IronClaw v0.13.1                       ║
║              Your secure personal AI assistant                 ║
╚════════════════════════════════════════════════════════════════╝

Agent: my-agent
LLM: nearai (claude-3-5-sonnet-20241022)
Database: postgres (connected)
Tools: 42 available
Channels: repl, gateway
Security: WASM sandbox active, prompt injection defense enabled

Web UI: http://localhost:3000/

Type /help for commands, or start chatting...
Try some example prompts:
> What can you help me with?
> Search my workspace for notes about project X
> Create a new tool that fetches weather data
> Show me the status of my jobs

​
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us