> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install IronClaw on Windows, macOS, Linux, or build from source

## System Requirements

<CardGroup cols={2}>
  <Card title="Database" icon="database">
    * PostgreSQL 15+ with pgvector extension, **OR**
    * libSQL/SQLite (embedded, zero dependencies)
  </Card>

  <Card title="Runtime" icon="microchip">
    * Rust 1.92+ (if building from source)
    * 4GB RAM minimum, 8GB recommended
    * macOS, Linux, or Windows (WSL supported)
  </Card>
</CardGroup>

<Warning>
  **PostgreSQL users:** The pgvector extension is required for semantic search. See the [PostgreSQL Setup](#postgresql-setup) section below for installation instructions.
</Warning>

## Quick Install

Choose your platform and installation method:

<Tabs>
  <Tab title="macOS / Linux">
    <Steps>
      <Step title="Install via shell script">
        Download and run the installer:

        ```bash theme={null}
        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`.
      </Step>

      <Step title="Verify installation">
        Check that IronClaw is installed:

        ```bash theme={null}
        ironclaw --version
        ```

        You should see the version number (e.g., `ironclaw 0.13.1`).
      </Step>
    </Steps>

    <Accordion title="Alternative: Homebrew (macOS/Linux)">
      ```bash theme={null}
      brew install ironclaw
      ```

      Homebrew automatically adds IronClaw to your PATH.
    </Accordion>
  </Tab>

  <Tab title="Windows">
    <Tabs>
      <Tab title="PowerShell Installer">
        <Steps>
          <Step title="Run installer script">
            Open PowerShell and run:

            ```powershell theme={null}
            irm https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.ps1 | iex
            ```

            This installs IronClaw to your user profile.
          </Step>

          <Step title="Verify installation">
            ```powershell theme={null}
            ironclaw --version
            ```

            You should see the version number.
          </Step>
        </Steps>
      </Tab>

      <Tab title="MSI Installer">
        <Steps>
          <Step title="Download MSI package">
            Download the [Windows Installer](https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-x86_64-pc-windows-msvc.msi) from the releases page.
          </Step>

          <Step title="Run installer">
            Double-click the `.msi` file and follow the installation wizard.
          </Step>

          <Step title="Verify installation">
            Open a new PowerShell window:

            ```powershell theme={null}
            ironclaw --version
            ```
          </Step>
        </Steps>
      </Tab>

      <Tab title="WSL (Windows Subsystem for Linux)">
        If you use WSL, follow the **macOS / Linux** instructions above inside your WSL terminal.
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Build from Source">
    <Steps>
      <Step title="Install Rust">
        If you don't have Rust installed, get it from [rustup.rs](https://rustup.rs):

        ```bash theme={null}
        curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
        ```

        Ensure you have Rust 1.92 or newer:

        ```bash theme={null}
        rustc --version
        ```
      </Step>

      <Step title="Clone the repository">
        ```bash theme={null}
        git clone https://github.com/nearai/ironclaw.git
        cd ironclaw
        ```
      </Step>

      <Step title="Build release binary">
        ```bash theme={null}
        cargo build --release
        ```

        The binary will be at `target/release/ironclaw`.
      </Step>

      <Step title="(Optional) Install globally">
        ```bash theme={null}
        cargo install --path .
        ```

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

      <Step title="Run tests">
        ```bash theme={null}
        cargo test
        ```

        <Note>
          Some tests require a database connection. Set `DATABASE_URL` or skip integration tests.
        </Note>
      </Step>
    </Steps>

    <Accordion title="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:

      ```bash theme={null}
      ./scripts/build-all.sh
      cargo build --release
      ```
    </Accordion>
  </Tab>
</Tabs>

## Database Setup

IronClaw supports two database backends:

<Tabs>
  <Tab title="PostgreSQL (Recommended for Production)">
    ### PostgreSQL Setup

    <Steps>
      <Step title="Install PostgreSQL 15+">
        <CodeGroup>
          ```bash macOS (Homebrew) theme={null}
          brew install postgresql@15
          brew services start postgresql@15
          ```

          ```bash Ubuntu/Debian theme={null}
          sudo apt update
          sudo apt install postgresql-15 postgresql-contrib-15
          sudo systemctl start postgresql
          ```

          ```bash Fedora/RHEL theme={null}
          sudo dnf install postgresql15-server postgresql15-contrib
          sudo postgresql-setup --initdb
          sudo systemctl start postgresql
          ```

          ```yaml Docker theme={null}
          # Use pgvector image which includes PostgreSQL + pgvector
          docker run -d \
            --name ironclaw-postgres \
            -e POSTGRES_PASSWORD=postgres \
            -e POSTGRES_DB=ironclaw \
            -p 5432:5432 \
            pgvector/pgvector:pg15
          ```
        </CodeGroup>
      </Step>

      <Step title="Install pgvector extension">
        <Warning>
          The **pgvector** extension is **required** for IronClaw's semantic search features.
        </Warning>

        <CodeGroup>
          ```bash macOS (Homebrew) theme={null}
          brew install pgvector
          ```

          ```bash Ubuntu/Debian theme={null}
          sudo apt install postgresql-15-pgvector
          ```

          ```bash From source theme={null}
          git clone --branch v0.7.0 https://github.com/pgvector/pgvector.git
          cd pgvector
          make
          sudo make install
          ```
        </CodeGroup>

        <Note>
          If using Docker with the `pgvector/pgvector` image, pgvector is already installed.
        </Note>
      </Step>

      <Step title="Create database">
        ```bash theme={null}
        # Create database
        createdb ironclaw

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

        <Tip>
          On Docker, run:

          ```bash theme={null}
          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;"
          ```
        </Tip>
      </Step>

      <Step title="Set DATABASE_URL">
        The setup wizard will ask for your database URL, or you can set it now:

        ```bash theme={null}
        export DATABASE_URL=postgres://localhost/ironclaw
        # Or with credentials:
        export DATABASE_URL=postgres://user:password@localhost:5432/ironclaw
        ```

        <Accordion title="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).
        </Accordion>
      </Step>
    </Steps>
  </Tab>

  <Tab title="libSQL/SQLite (Embedded, Zero Dependencies)">
    ### libSQL Setup

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

    <Steps>
      <Step title="Choose local or remote">
        IronClaw supports:

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

      <Step title="Set environment variables">
        For **local file only**:

        ```bash theme={null}
        export DATABASE_BACKEND=libsql
        export LIBSQL_PATH=~/.ironclaw/ironclaw.db
        ```

        For **Turso cloud sync**:

        ```bash theme={null}
        export DATABASE_BACKEND=libsql
        export LIBSQL_PATH=~/.ironclaw/ironclaw.db
        export LIBSQL_URL=libsql://your-db.turso.io
        export LIBSQL_AUTH_TOKEN=eyJhbGc...
        ```

        <Note>
          The setup wizard will guide you through this. You can skip manual configuration and run `ironclaw onboard` directly.
        </Note>
      </Step>

      <Step title="No installation required">
        libSQL is embedded in the IronClaw binary. The database file is created automatically on first run.
      </Step>
    </Steps>

    <Accordion title="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.
    </Accordion>
  </Tab>
</Tabs>

## Verify Installation

Run the version command to confirm IronClaw is installed:

```bash theme={null}
ironclaw --version
```

You should see output like:

```
ironclaw 0.13.1
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Complete the setup wizard and chat with IronClaw
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration">
    Configure LLM providers, secrets, and channels
  </Card>
</CardGroup>

## Updating IronClaw

To update to the latest version:

<CodeGroup>
  ```bash Shell script install theme={null}
  curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh
  ```

  ```bash Homebrew theme={null}
  brew upgrade ironclaw
  ```

  ```bash Cargo (from source) theme={null}
  cd ironclaw
  git pull
  cargo install --path .
  ```

  ```powershell Windows PowerShell theme={null}
  irm https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.ps1 | iex
  ```
</CodeGroup>

<Check>
  IronClaw includes an automatic updater. Run `ironclaw update` to check for and install the latest version.
</Check>

## Troubleshooting

<AccordionGroup>
  <Accordion title="pgvector extension not found">
    **Error:** `pgvector extension not found on your PostgreSQL server`

    **Solution:**

    1. Install pgvector for your PostgreSQL version (see [PostgreSQL Setup](#postgresql-setup))
    2. Restart PostgreSQL: `sudo systemctl restart postgresql` (Linux) or `brew services restart postgresql@15` (macOS)
    3. Re-run setup: `ironclaw onboard`
  </Accordion>

  <Accordion title="PostgreSQL version too old">
    **Error:** `PostgreSQL 14 detected. IronClaw requires PostgreSQL 15 or later`

    **Solution:**
    Upgrade PostgreSQL to version 15 or later. See [https://www.postgresql.org/download/](https://www.postgresql.org/download/) for instructions.
  </Accordion>

  <Accordion title="ironclaw command not found">
    **Error:** `command not found: ironclaw`

    **Solution:**

    * 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
  </Accordion>

  <Accordion title="Database connection failed">
    **Error:** `Failed to connect to database`

    **Solution:**

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