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

# Quick Start

> Get up and running with IronClaw in 5 minutes

<Info>
  This guide walks you through installing IronClaw, running the setup wizard, and having your first conversation.
</Info>

## Before You Begin

Make sure you have:

<CardGroup cols={2}>
  <Card title="IronClaw Installed" icon="download">
    Follow the [Installation Guide](/installation) to install IronClaw on your system.
  </Card>

  <Card title="Database Ready" icon="database">
    PostgreSQL 15+ with pgvector, **or** libSQL (embedded, no setup needed).
  </Card>
</CardGroup>

## Setup Wizard

IronClaw includes an interactive setup wizard that guides you through configuration.

<Steps>
  <Step title="Run the onboarding wizard">
    ```bash theme={null}
    ironclaw onboard
    ```

    <Tip>
      The wizard saves progress after each step. If you exit early, re-running `ironclaw onboard` will resume where you left off.
    </Tip>
  </Step>

  <Step title="Configure database">
    Choose your database backend:

    <Tabs>
      <Tab title="libSQL (Embedded)">
        **Recommended for local development** — zero dependencies, no server required.

        The wizard will prompt:

        ```
        Database file path (default: ~/.ironclaw/ironclaw.db):
        ```

        Press Enter to use the default, or specify a custom path.

        ```
        Enable Turso cloud sync (remote replica)? [y/N]:
        ```

        * **No** (default) — Local file only
        * **Yes** — Enter your Turso URL and auth token for cloud sync
      </Tab>

      <Tab title="PostgreSQL">
        **Recommended for production** — scalable, production-ready persistence.

        The wizard will prompt:

        ```
        Enter your PostgreSQL connection URL.
        Format: postgres://user:password@host:port/database

        Database URL:
        ```

        Example:

        ```
        postgres://localhost/ironclaw
        # Or with credentials:
        postgres://myuser:mypass@localhost:5432/ironclaw
        ```

        <Warning>
          Ensure PostgreSQL 15+ is running and the **pgvector** extension is installed. See [Installation → PostgreSQL Setup](/installation#postgresql-setup).
        </Warning>

        The wizard will test the connection and run migrations automatically.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure security">
    IronClaw encrypts secrets (API keys, tokens) with a master key.

    The wizard will prompt:

    ```
    The secrets master key encrypts sensitive data like API tokens.
    Choose where to store it:

    1. OS Keychain (recommended for local installs)
    2. Environment variable (for CI/Docker)
    3. Skip (disable secrets features)
    ```

    <Tabs>
      <Tab title="OS Keychain (Recommended)">
        Select **1** to generate and store the key in your system keychain (macOS Keychain, GNOME Keyring, KWallet).

        The key is stored securely and loaded automatically on startup.
      </Tab>

      <Tab title="Environment Variable">
        Select **2** to generate a key and display it for manual setup:

        ```bash theme={null}
        export SECRETS_MASTER_KEY=a1b2c3d4e5f6...
        ```

        Add this to your shell profile (`~/.bashrc`, `~/.zshrc`) or `.env` file.
      </Tab>

      <Tab title="Skip (No Secrets)">
        Select **3** to disable secrets encryption. You'll need to set all API keys via environment variables.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Select inference provider">
    Choose your LLM provider:

    ```
    Select your inference provider:

    1. NEAR AI          - multi-model access via NEAR account
    2. Anthropic        - Claude models (direct API key)
    3. OpenAI           - GPT models (direct API key)
    4. Ollama           - local models, no API key needed
    5. OpenRouter       - 200+ models via single API key
    6. OpenAI-compatible - custom endpoint (vLLM, LiteLLM, etc.)
    ```

    <Tabs>
      <Tab title="NEAR AI (Default)">
        Select **1** for NEAR AI.

        The wizard will open your browser to authenticate via GitHub or Google OAuth. After authentication, your session token is saved automatically.

        <Tip>
          NEAR AI provides access to multiple models (GLM, Claude, GPT) with a single account.
        </Tip>
      </Tab>

      <Tab title="Anthropic (Claude)">
        Select **2** and enter your Anthropic API key when prompted.

        Get your key from: [https://console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys)
      </Tab>

      <Tab title="OpenAI">
        Select **3** and enter your OpenAI API key when prompted.

        Get your key from: [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys)
      </Tab>

      <Tab title="Ollama (Local)">
        Select **4** for Ollama.

        The wizard will prompt for your Ollama base URL (default: `http://localhost:11434`).

        <Note>
          Make sure Ollama is running and you've pulled at least one model:

          ```bash theme={null}
          ollama pull llama3.2
          ```
        </Note>
      </Tab>

      <Tab title="OpenRouter">
        Select **5** and enter your OpenRouter API key when prompted.

        Get your key from: [https://openrouter.ai/settings/keys](https://openrouter.ai/settings/keys)

        OpenRouter provides access to 200+ models from multiple providers.
      </Tab>

      <Tab title="OpenAI-compatible">
        Select **6** for custom endpoints like vLLM, LiteLLM, Together AI, Fireworks AI, etc.

        The wizard will prompt for:

        * Base URL (e.g., `http://localhost:8000/v1`)
        * API key (optional for local servers)
      </Tab>
    </Tabs>
  </Step>

  <Step title="Select model">
    The wizard will fetch available models from your provider and display a list:

    ```
    Available models:

    1. GLM Latest (default, fast)
    2. Claude Sonnet 4 (best quality)
    3. GPT-5.3 Codex (flagship)
    4. Custom model ID
    ```

    Select your preferred model, or choose **Custom model ID** to enter a specific model identifier.

    <Tip>
      You can change the model later by re-running `ironclaw onboard` or editing `~/.ironclaw/.env`.
    </Tip>
  </Step>

  <Step title="Configure embeddings (optional)">
    Embeddings enable semantic search across your workspace memory.

    ```
    Enable semantic search? [Y/n]:
    ```

    * **Yes** (default) — The wizard will configure embeddings using your LLM provider or OpenAI
    * **No** — Workspace will use keyword search only

    <Info>
      Semantic search lets you find notes and context by meaning, not just keywords. Highly recommended.
    </Info>
  </Step>

  <Step title="Configure channels (optional)">
    IronClaw supports multiple communication channels:

    ```
    Select channels to enable (space to toggle, enter to confirm):

    [ ] HTTP Webhook Server
    [ ] Telegram Bot
    [ ] Signal Messaging
    [ ] Cloudflare Tunnel (ngrok alternative)
    ```

    <Accordion title="HTTP Webhook Server">
      Exposes a REST API for triggering tasks via HTTP.

      The wizard will prompt for:

      * Host (default: `0.0.0.0`)
      * Port (default: `8080`)
      * Webhook secret (for request authentication)
    </Accordion>

    <Accordion title="Telegram Bot">
      Interact with IronClaw via Telegram DMs.

      The wizard will prompt for:

      * Telegram bot token (get one from [@BotFather](https://t.me/botfather))

      After setup, send `/start` to your bot in Telegram to pair.
    </Accordion>

    <Accordion title="Signal Messaging">
      Interact with IronClaw via Signal.

      Requires a running `signal-cli` daemon. See [Signal Setup](/channels/signal) for details.
    </Accordion>

    <Accordion title="Cloudflare Tunnel">
      Expose your local IronClaw instance to the internet via Cloudflare Tunnel (ngrok alternative).

      Requires `cloudflared` to be installed.
    </Accordion>

    <Tip>
      You can skip this step and configure channels later with `ironclaw onboard --channels-only`.
    </Tip>
  </Step>

  <Step title="Install extensions (optional)">
    The wizard can install pre-built WASM tools from the registry:

    ```
    Install extensions from registry? [y/N]:
    ```

    Select **Yes** to browse and install tools like GitHub, Gmail, Google Calendar, etc.

    <Note>
      You can install extensions later via the CLI or web gateway.
    </Note>
  </Step>

  <Step title="Configure Docker sandbox (optional)">
    The Docker sandbox runs code in isolated containers.

    ```
    Enable Docker sandbox for code execution? [y/N]:
    ```

    * **Yes** — Requires Docker to be installed and running
    * **No** (default) — Code execution disabled
  </Step>

  <Step title="Configure heartbeat (optional)">
    The heartbeat system runs background tasks on a schedule (e.g., monitoring, maintenance).

    ```
    Enable background tasks (heartbeat)? [y/N]:
    ```

    * **Yes** — The wizard will prompt for interval (default: 30 minutes)
    * **No** (default) — No background tasks
  </Step>
</Steps>

<Success>
  Setup complete! IronClaw is configured and ready to use.
</Success>

## Your First Conversation

Start the interactive REPL:

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

You'll see the IronClaw prompt:

```
╭─ IronClaw v0.13.1
╰─ Type 'help' for commands, 'exit' to quit

>
```

### Try these commands:

<Steps>
  <Step title="Ask a question">
    ```
    > What can you do?
    ```

    IronClaw will explain its capabilities, including tool use, memory management, and channel support.
  </Step>

  <Step title="Use a tool">
    ```
    > Create a note in my workspace called "ideas.md" with the content "Build a Rust CLI tool"
    ```

    IronClaw will use the `workspace_write` tool to create the file.
  </Step>

  <Step title="Search your workspace">
    ```
    > Search my workspace for notes about Rust
    ```

    If you enabled embeddings, IronClaw will perform a semantic search across your notes.
  </Step>

  <Step title="Exit the REPL">
    ```
    > exit
    ```

    Or press `Ctrl+D`.
  </Step>
</Steps>

## Running as a Service

To keep IronClaw running in the background:

<Tabs>
  <Tab title="Docker">
    Create a `docker-compose.yml`:

    ```yaml docker-compose.yml theme={null}
    version: '3.8'
    services:
      ironclaw:
        image: ghcr.io/nearai/ironclaw:latest
        environment:
          - DATABASE_URL=postgres://postgres:postgres@db:5432/ironclaw
          - NEARAI_MODEL=zai-org/GLM-latest
        volumes:
          - ~/.ironclaw:/root/.ironclaw
        depends_on:
          - db

      db:
        image: pgvector/pgvector:pg15
        environment:
          - POSTGRES_PASSWORD=postgres
          - POSTGRES_DB=ironclaw
        volumes:
          - postgres-data:/var/lib/postgresql/data

    volumes:
      postgres-data:
    ```

    Start the services:

    ```bash theme={null}
    docker-compose up -d
    ```
  </Tab>

  <Tab title="systemd (Linux)">
    Create a systemd service file at `/etc/systemd/system/ironclaw.service`:

    ```ini /etc/systemd/system/ironclaw.service theme={null}
    [Unit]
    Description=IronClaw AI Assistant
    After=network.target postgresql.service

    [Service]
    Type=simple
    User=youruser
    WorkingDirectory=/home/youruser
    ExecStart=/home/youruser/.cargo/bin/ironclaw
    Restart=on-failure
    RestartSec=10
    Environment="DATABASE_URL=postgres://localhost/ironclaw"

    [Install]
    WantedBy=multi-user.target
    ```

    Enable and start the service:

    ```bash theme={null}
    sudo systemctl daemon-reload
    sudo systemctl enable ironclaw
    sudo systemctl start ironclaw
    sudo systemctl status ironclaw
    ```
  </Tab>

  <Tab title="launchd (macOS)">
    Create a launch agent at `~/Library/LaunchAgents/ai.near.ironclaw.plist`:

    ```xml ~/Library/LaunchAgents/ai.near.ironclaw.plist theme={null}
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
        <key>Label</key>
        <string>ai.near.ironclaw</string>
        <key>ProgramArguments</key>
        <array>
            <string>/Users/youruser/.cargo/bin/ironclaw</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
        <key>KeepAlive</key>
        <true/>
        <key>StandardOutPath</key>
        <string>/Users/youruser/.ironclaw/stdout.log</string>
        <key>StandardErrorPath</key>
        <string>/Users/youruser/.ironclaw/stderr.log</string>
    </dict>
    </plist>
    ```

    Load the agent:

    ```bash theme={null}
    launchctl load ~/Library/LaunchAgents/ai.near.ironclaw.plist
    launchctl start ai.near.ironclaw
    ```
  </Tab>
</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/configuration">
    Learn how to configure LLM providers, channels, and secrets
  </Card>

  <Card title="Tools & Extensions" icon="puzzle-piece" href="/tools/overview">
    Explore built-in tools and install extensions
  </Card>

  <Card title="Channels" icon="comment" href="/channels/overview">
    Set up Telegram, HTTP webhooks, and web gateway
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli/overview">
    Explore all available commands
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Wizard exits with database error">
    **Problem:** `Failed to connect to database`

    **Solution:**

    * Ensure PostgreSQL is running: `brew services list` (macOS) or `systemctl status postgresql` (Linux)
    * Verify pgvector is installed: `psql -c "SELECT * FROM pg_available_extensions WHERE name = 'vector';" ironclaw`
    * For libSQL, ensure parent directory exists: `mkdir -p ~/.ironclaw`
  </Accordion>

  <Accordion title="Authentication fails for NEAR AI">
    **Problem:** Browser doesn't open or authentication times out

    **Solution:**

    * Check your internet connection
    * Manually visit the auth URL printed by the wizard
    * Try API key mode instead: Set `NEARAI_API_KEY` in your environment
  </Accordion>

  <Accordion title="No models found (Ollama)">
    **Problem:** `No models found. Pull one first: ollama pull llama3`

    **Solution:**

    ```bash theme={null}
    # Pull a model
    ollama pull llama3.2

    # Verify it's available
    ollama list

    # Re-run wizard
    ironclaw onboard
    ```
  </Accordion>

  <Accordion title="REPL doesn't start">
    **Problem:** `ironclaw` command hangs or crashes

    **Solution:**

    * Check logs: `RUST_LOG=ironclaw=debug ironclaw`
    * Verify database connection: `psql $DATABASE_URL`
    * Re-run setup: `ironclaw onboard`
  </Accordion>
</AccordionGroup>