Quick Start

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

Before You Begin

Make sure you have:

IronClaw Installed

Follow the Installation Guide to install IronClaw on your system.

Database Ready

PostgreSQL 15+ with pgvector, or libSQL (embedded, no setup needed).

Setup Wizard

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

Run the onboarding wizard

ironclaw onboard

The wizard saves progress after each step. If you exit early, re-running ironclaw onboard will resume where you left off.

Configure database

Choose your database backend:

libSQL (Embedded)
PostgreSQL

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

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

Ensure PostgreSQL 15+ is running and the pgvector extension is installed. See Installation → PostgreSQL Setup.

The wizard will test the connection and run migrations automatically.

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)

OS Keychain (Recommended)
Environment Variable
Skip (No Secrets)

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.

Select 2 to generate a key and display it for manual setup:

export SECRETS_MASTER_KEY=a1b2c3d4e5f6...

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

Select inference provider

Choose your LLM provider:

Select your inference provider:

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

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.

NEAR AI provides access to multiple models (GLM, Claude, GPT) with a single account.

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

Make sure Ollama is running and you’ve pulled at least one model:

ollama pull llama3.2

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)

Select model

The wizard will fetch available models from your provider and display a list:

Available models:

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

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

You can change the model later by re-running ironclaw onboard or editing ~/.ironclaw/.env.

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

Semantic search lets you find notes and context by meaning, not just keywords. Highly recommended.

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)

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)

Telegram Bot

Interact with IronClaw via Telegram DMs.The wizard will prompt for:

Telegram bot token (get one from @BotFather)

After setup, send /start to your bot in Telegram to pair.

Signal Messaging

Interact with IronClaw via Signal.Requires a running signal-cli daemon. See Signal Setup for details.

Cloudflare Tunnel

Expose your local IronClaw instance to the internet via Cloudflare Tunnel (ngrok alternative).Requires cloudflared to be installed.

You can skip this step and configure channels later with ironclaw onboard --channels-only.

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.

You can install extensions later via the CLI or web gateway.

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

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

Your First Conversation

Start the interactive REPL:

ironclaw

You’ll see the IronClaw prompt:

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

>

Try these commands:

Ask a question

> What can you do?

IronClaw will explain its capabilities, including tool use, memory management, and channel support.

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.

Search your workspace

> Search my workspace for notes about Rust

If you enabled embeddings, IronClaw will perform a semantic search across your notes.

Exit the REPL

> exit

Or press Ctrl+D.

Running as a Service

To keep IronClaw running in the background:

Docker
systemd (Linux)
launchd (macOS)

Create a docker-compose.yml:

docker-compose.yml

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:

docker-compose up -d

Create a systemd service file at /etc/systemd/system/ironclaw.service:

/etc/systemd/system/ironclaw.service

[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:

sudo systemctl daemon-reload
sudo systemctl enable ironclaw
sudo systemctl start ironclaw
sudo systemctl status ironclaw

Create a launch agent at ~/Library/LaunchAgents/ai.near.ironclaw.plist:

~/Library/LaunchAgents/ai.near.ironclaw.plist

<?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:

launchctl load ~/Library/LaunchAgents/ai.near.ironclaw.plist
launchctl start ai.near.ironclaw

Next Steps

Configuration

Learn how to configure LLM providers, channels, and secrets

Tools & Extensions

Explore built-in tools and install extensions

Channels

Set up Telegram, HTTP webhooks, and web gateway

CLI Reference

Explore all available commands

Troubleshooting

Wizard exits with database error

Problem: Failed to connect to databaseSolution:

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

Authentication fails for NEAR AI

Problem: Browser doesn’t open or authentication times outSolution:

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

No models found (Ollama)

Problem: No models found. Pull one first: ollama pull llama3Solution:

# Pull a model
ollama pull llama3.2

# Verify it's available
ollama list

# Re-run wizard
ironclaw onboard

REPL doesn't start

Problem: ironclaw command hangs or crashesSolution:

Check logs: RUST_LOG=ironclaw=debug ironclaw
Verify database connection: psql $DATABASE_URL
Re-run setup: ironclaw onboard

Getting Started

Core Concepts

CLI Reference

Channels

Tools & Extensions

Advanced

Security

Development

Before You Begin

IronClaw Installed

Database Ready

Setup Wizard

Your First Conversation

Try these commands:

Running as a Service

Next Steps

Configuration

Tools & Extensions

Channels

CLI Reference

Troubleshooting

Build docs developers (and LLMs) love

Getting Started

Core Concepts

CLI Reference

Channels

Tools & Extensions

Advanced

Security

Development

Documentation Index

​Before You Begin

IronClaw Installed

Database Ready

​Setup Wizard

​Your First Conversation

​Try these commands:

​Running as a Service

​Next Steps

Configuration

Tools & Extensions

Channels

CLI Reference

​Troubleshooting

Build docs developers (and LLMs) love

Before You Begin

Setup Wizard

Your First Conversation

Try these commands:

Running as a Service

Next Steps

Troubleshooting