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

# Configuration

> Configure IronClaw's LLM providers, database, secrets, channels, and more

## Configuration Overview

IronClaw's configuration is loaded with the following priority:

```
Environment Variables > TOML Config File > Database Settings > Defaults
```

<Tabs>
  <Tab title="Setup Wizard (Recommended)">
    The easiest way to configure IronClaw is via the interactive wizard:

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

    The wizard saves settings to the database and writes bootstrap variables to `~/.ironclaw/.env`.
  </Tab>

  <Tab title="Environment Variables">
    Create a `.env` file in your project root or `~/.ironclaw/.env`:

    ```bash ~/.ironclaw/.env theme={null}
    DATABASE_URL=postgres://localhost/ironclaw
    LLM_BACKEND=nearai
    NEARAI_MODEL=zai-org/GLM-latest
    ```

    IronClaw loads `.env` automatically on startup via `dotenvy`.
  </Tab>

  <Tab title="TOML Config File">
    Create `~/.ironclaw/config.toml` for structured configuration:

    ```toml ~/.ironclaw/config.toml theme={null}
    [llm]
    backend = "nearai"
    selected_model = "zai-org/GLM-latest"

    [database]
    backend = "postgres"
    url = "postgres://localhost/ironclaw"

    [embeddings]
    enabled = true
    provider = "nearai"
    ```

    TOML values override database settings but are overridden by environment variables.
  </Tab>
</Tabs>

## Database Configuration

IronClaw supports PostgreSQL and libSQL backends.

### PostgreSQL

<ParamField path="DATABASE_BACKEND" type="string" default="postgres">
  Database backend to use (`postgres` or `libsql`)
</ParamField>

<ParamField path="DATABASE_URL" type="string" required>
  PostgreSQL connection URL

  ```bash theme={null}
  DATABASE_URL=postgres://user:password@host:port/database
  ```

  Examples:

  * Local: `postgres://localhost/ironclaw`
  * Neon: `postgres://user:pass@ep-cool-darkness-123456.us-east-2.aws.neon.tech/ironclaw?sslmode=require`
  * Supabase: `postgres://postgres:pass@db.projectid.supabase.co:5432/postgres`
</ParamField>

<ParamField path="DATABASE_POOL_SIZE" type="integer" default="10">
  Maximum number of database connections in the pool
</ParamField>

<ParamField path="DATABASE_SSLMODE" type="string" default="prefer">
  SSL/TLS mode for PostgreSQL connections

  * `disable` — No TLS (local development only)
  * `prefer` — Try TLS, fall back to plaintext (default)
  * `require` — Require TLS or fail
</ParamField>

<Warning>
  **PostgreSQL 15+ and pgvector are required.** See [Installation → PostgreSQL Setup](/installation#postgresql-setup).
</Warning>

### libSQL (Embedded SQLite)

<ParamField path="LIBSQL_PATH" type="string" default="~/.ironclaw/ironclaw.db">
  Path to the local libSQL database file
</ParamField>

<ParamField path="LIBSQL_URL" type="string">
  Turso cloud URL for remote replica sync (optional)

  ```bash theme={null}
  LIBSQL_URL=libsql://your-db.turso.io
  ```
</ParamField>

<ParamField path="LIBSQL_AUTH_TOKEN" type="string">
  Turso authentication token (required if `LIBSQL_URL` is set)
</ParamField>

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

## LLM Provider Configuration

### NEAR AI (Default)

NEAR AI provides multi-model access via a single account.

<ParamField path="LLM_BACKEND" type="string" default="nearai">
  Set to `nearai` to use NEAR AI
</ParamField>

<ParamField path="NEARAI_MODEL" type="string" default="zai-org/GLM-latest">
  Model to use for inference

  Popular options:

  * `zai-org/GLM-latest` — Fast, default
  * `anthropic::claude-sonnet-4-20250514` — Best quality
  * `openai::gpt-5.3-codex` — Flagship coding model
</ParamField>

<ParamField path="NEARAI_BASE_URL" type="string" default="https://private.near.ai">
  NEAR AI API base URL
</ParamField>

<ParamField path="NEARAI_AUTH_URL" type="string" default="https://private.near.ai">
  NEAR AI authentication URL
</ParamField>

<ParamField path="NEARAI_SESSION_TOKEN" type="string">
  Session token from browser OAuth (auto-generated by setup wizard)

  Stored in `~/.ironclaw/session.json` by default.
</ParamField>

<ParamField path="NEARAI_API_KEY" type="string">
  API key from cloud.near.ai (alternative to session token)

  If set, the base URL defaults to `https://cloud-api.near.ai`.
</ParamField>

<Tip>
  The setup wizard handles NEAR AI authentication automatically via browser OAuth.
</Tip>

### Anthropic (Claude)

<ParamField path="LLM_BACKEND" type="string">
  Set to `anthropic` to use Anthropic's API
</ParamField>

<ParamField path="ANTHROPIC_API_KEY" type="string" required>
  Your Anthropic API key

  Get one from: [https://console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys)
</ParamField>

<ParamField path="ANTHROPIC_MODEL" type="string" default="claude-sonnet-4-20250514">
  Claude model to use

  Options:

  * `claude-sonnet-4-20250514` — Latest Sonnet (recommended)
  * `claude-opus-4-20250514` — Most capable
  * `claude-3-5-sonnet-20241022` — Previous generation
</ParamField>

### OpenAI

<ParamField path="LLM_BACKEND" type="string">
  Set to `openai` to use OpenAI's API
</ParamField>

<ParamField path="OPENAI_API_KEY" type="string" required>
  Your OpenAI API key

  Get one from: [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys)
</ParamField>

<ParamField path="OPENAI_MODEL" type="string" default="gpt-4">
  OpenAI model to use

  Options:

  * `gpt-5.3-codex` — Latest flagship
  * `gpt-5.2` — General purpose
  * `gpt-4o` — Multimodal
  * `gpt-4-turbo` — Fast and capable
</ParamField>

### Ollama (Local Models)

<ParamField path="LLM_BACKEND" type="string">
  Set to `ollama` to use local Ollama models
</ParamField>

<ParamField path="OLLAMA_BASE_URL" type="string" default="http://localhost:11434">
  Ollama server URL
</ParamField>

<ParamField path="OLLAMA_MODEL" type="string" default="llama3.2">
  Ollama model to use

  Must be pulled first: `ollama pull llama3.2`
</ParamField>

<Note>
  Ollama runs models locally on your machine. No API key required. See [ollama.ai](https://ollama.ai) for installation.
</Note>

### OpenRouter (200+ Models)

<ParamField path="LLM_BACKEND" type="string">
  Set to `openai_compatible` for OpenRouter
</ParamField>

<ParamField path="LLM_BASE_URL" type="string">
  Set to `https://openrouter.ai/api/v1`
</ParamField>

<ParamField path="LLM_API_KEY" type="string" required>
  Your OpenRouter API key

  Get one from: [https://openrouter.ai/settings/keys](https://openrouter.ai/settings/keys)
</ParamField>

<ParamField path="LLM_MODEL" type="string">
  Model ID from OpenRouter

  Examples:

  * `anthropic/claude-sonnet-4`
  * `openai/gpt-5.3-codex`
  * `google/gemini-pro-1.5`
  * `meta-llama/llama-3.3-70b-instruct`

  See [openrouter.ai/models](https://openrouter.ai/models) for the full list.
</ParamField>

<ParamField path="LLM_EXTRA_HEADERS" type="string">
  Custom HTTP headers (comma-separated key:value pairs)

  ```bash theme={null}
  LLM_EXTRA_HEADERS=HTTP-Referer:https://myapp.com,X-Title:MyApp
  ```
</ParamField>

### OpenAI-Compatible (vLLM, LiteLLM, Together, Fireworks)

<ParamField path="LLM_BACKEND" type="string">
  Set to `openai_compatible`
</ParamField>

<ParamField path="LLM_BASE_URL" type="string" required>
  Base URL of the OpenAI-compatible endpoint

  Examples:

  * vLLM: `http://localhost:8000/v1`
  * LM Studio: `http://localhost:1234/v1`
  * Together AI: `https://api.together.xyz/v1`
  * Fireworks AI: `https://api.fireworks.ai/inference/v1`
</ParamField>

<ParamField path="LLM_API_KEY" type="string">
  API key (optional for local servers)
</ParamField>

<ParamField path="LLM_MODEL" type="string" required>
  Model identifier

  Examples:

  * `meta-llama/Llama-3.3-70B-Instruct-Turbo` (Together AI)
  * `accounts/fireworks/models/llama4-maverick-instruct-basic` (Fireworks)
  * `llama-3.2-3b-instruct-q4_K_M` (LM Studio)
</ParamField>

<Accordion title="Full LLM provider examples">
  <CodeGroup>
    ```bash NEAR AI theme={null}
    LLM_BACKEND=nearai
    NEARAI_MODEL=zai-org/GLM-latest
    NEARAI_BASE_URL=https://private.near.ai
    ```

    ```bash Anthropic theme={null}
    LLM_BACKEND=anthropic
    ANTHROPIC_API_KEY=sk-ant-...
    ANTHROPIC_MODEL=claude-sonnet-4-20250514
    ```

    ```bash OpenAI theme={null}
    LLM_BACKEND=openai
    OPENAI_API_KEY=sk-proj-...
    OPENAI_MODEL=gpt-5.3-codex
    ```

    ```bash Ollama theme={null}
    LLM_BACKEND=ollama
    OLLAMA_BASE_URL=http://localhost:11434
    OLLAMA_MODEL=llama3.2
    ```

    ```bash OpenRouter theme={null}
    LLM_BACKEND=openai_compatible
    LLM_BASE_URL=https://openrouter.ai/api/v1
    LLM_API_KEY=sk-or-...
    LLM_MODEL=anthropic/claude-sonnet-4
    ```

    ```bash Together AI theme={null}
    LLM_BACKEND=openai_compatible
    LLM_BASE_URL=https://api.together.xyz/v1
    LLM_API_KEY=...
    LLM_MODEL=meta-llama/Llama-3.3-70B-Instruct-Turbo
    ```
  </CodeGroup>
</Accordion>

## Embeddings Configuration

Embeddings enable semantic search across your workspace.

<ParamField path="EMBEDDINGS_ENABLED" type="boolean" default="true">
  Enable vector embeddings for semantic search
</ParamField>

<ParamField path="EMBEDDINGS_PROVIDER" type="string" default="nearai">
  Embeddings provider (`nearai`, `openai`, or same as `LLM_BACKEND`)
</ParamField>

<ParamField path="EMBEDDINGS_MODEL" type="string">
  Model to use for embeddings

  * NEAR AI: `text-embedding-3-small` (default)
  * OpenAI: `text-embedding-3-small`, `text-embedding-3-large`
</ParamField>

<Info>
  Embeddings require PostgreSQL with pgvector or libSQL with vector support.
</Info>

## Secrets Configuration

Secrets (API keys, tokens) are encrypted with a master key.

<ParamField path="SECRETS_MASTER_KEY" type="string">
  Master encryption key (256-bit hex string)

  Generated by the setup wizard and stored in OS keychain or environment.
</ParamField>

<Tabs>
  <Tab title="OS Keychain (Recommended)">
    The setup wizard stores the key in your system keychain:

    * **macOS**: Keychain Access
    * **Linux**: GNOME Keyring or KWallet

    No environment variable needed — IronClaw loads it automatically.
  </Tab>

  <Tab title="Environment Variable">
    For CI/Docker deployments, set the key manually:

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

    Generate a key:

    ```bash theme={null}
    openssl rand -hex 32
    ```
  </Tab>
</Tabs>

<Warning>
  **Keep your master key secure!** If lost, encrypted secrets cannot be recovered.
</Warning>

## Agent Configuration

<ParamField path="AGENT_NAME" type="string" default="ironclaw">
  Agent display name
</ParamField>

<ParamField path="AGENT_MAX_PARALLEL_JOBS" type="integer" default="5">
  Maximum number of concurrent jobs
</ParamField>

<ParamField path="AGENT_JOB_TIMEOUT_SECS" type="integer" default="3600">
  Job timeout in seconds (default: 1 hour)
</ParamField>

<ParamField path="AGENT_STUCK_THRESHOLD_SECS" type="integer" default="300">
  Time before marking a job as stuck (default: 5 minutes)
</ParamField>

<ParamField path="AGENT_USE_PLANNING" type="boolean" default="true">
  Enable planning phase before tool execution

  When enabled, the agent plans its approach before executing tools, improving accuracy.
</ParamField>

## Channel Configuration

### HTTP Webhook Server

<ParamField path="HTTP_HOST" type="string" default="0.0.0.0">
  Host to bind the HTTP server to
</ParamField>

<ParamField path="HTTP_PORT" type="integer" default="8080">
  Port for the HTTP webhook server
</ParamField>

<ParamField path="HTTP_WEBHOOK_SECRET" type="string">
  Secret for authenticating webhook requests
</ParamField>

### Telegram Bot

<ParamField path="TELEGRAM_BOT_TOKEN" type="string">
  Telegram bot token from [@BotFather](https://t.me/botfather)
</ParamField>

After setting the token, send `/start` to your bot in Telegram to pair.

### Signal Messaging

<ParamField path="SIGNAL_HTTP_URL" type="string" default="http://127.0.0.1:8080">
  signal-cli daemon HTTP URL
</ParamField>

<ParamField path="SIGNAL_ACCOUNT" type="string">
  Your Signal phone number (e.g., `+1234567890`)
</ParamField>

<ParamField path="SIGNAL_ALLOW_FROM" type="string">
  Comma-separated list of allowed senders (`*` for all)
</ParamField>

<ParamField path="SIGNAL_DM_POLICY" type="string" default="pairing">
  DM policy: `open`, `allowlist`, or `pairing`
</ParamField>

<Note>
  Signal requires a running `signal-cli` daemon. See [Signal Setup](/channels/signal).
</Note>

### Slack Bot (WASM Channel)

<ParamField path="SLACK_BOT_TOKEN" type="string">
  Slack bot token (`xoxb-...`)
</ParamField>

<ParamField path="SLACK_APP_TOKEN" type="string">
  Slack app-level token (`xapp-...`)
</ParamField>

<ParamField path="SLACK_SIGNING_SECRET" type="string">
  Slack request signing secret
</ParamField>

## Safety Configuration

<ParamField path="SAFETY_MAX_OUTPUT_LENGTH" type="integer" default="100000">
  Maximum tool output length (characters)
</ParamField>

<ParamField path="SAFETY_INJECTION_CHECK_ENABLED" type="boolean" default="true">
  Enable prompt injection detection
</ParamField>

## Heartbeat Configuration

The heartbeat system runs background tasks on a schedule.

<ParamField path="HEARTBEAT_ENABLED" type="boolean" default="false">
  Enable background heartbeat tasks
</ParamField>

<ParamField path="HEARTBEAT_INTERVAL_SECS" type="integer" default="1800">
  Heartbeat interval in seconds (default: 30 minutes)
</ParamField>

<ParamField path="HEARTBEAT_NOTIFY_CHANNEL" type="string" default="cli">
  Channel to send heartbeat notifications to
</ParamField>

<ParamField path="HEARTBEAT_NOTIFY_USER" type="string" default="default">
  User ID to notify
</ParamField>

<Tip>
  Heartbeat reads `HEARTBEAT.md` from your workspace and reports findings on the schedule.
</Tip>

## Memory Hygiene Configuration

Automatic cleanup of stale workspace documents.

<ParamField path="MEMORY_HYGIENE_ENABLED" type="boolean" default="true">
  Enable automatic cleanup of old daily notes
</ParamField>

<ParamField path="MEMORY_HYGIENE_RETENTION_DAYS" type="integer" default="30">
  Delete daily/ documents older than this many days
</ParamField>

<ParamField path="MEMORY_HYGIENE_CADENCE_HOURS" type="integer" default="12">
  Minimum hours between cleanup passes
</ParamField>

<Note>
  Identity files (`IDENTITY.md`, `SOUL.md`) are never deleted.
</Note>

## Docker Sandbox Configuration

<ParamField path="SANDBOX_MODE" type="string" default="disabled">
  Docker sandbox mode: `disabled`, `enabled`
</ParamField>

<ParamField path="SANDBOX_IMAGE" type="string" default="ironclaw-sandbox:latest">
  Docker image for sandbox execution
</ParamField>

<ParamField path="SANDBOX_TIMEOUT_SECS" type="integer" default="300">
  Sandbox execution timeout (default: 5 minutes)
</ParamField>

## Logging Configuration

<ParamField path="RUST_LOG" type="string" default="ironclaw=info">
  Logging level and filters

  Examples:

  ```bash theme={null}
  # Debug everything
  RUST_LOG=ironclaw=debug

  # Debug specific modules
  RUST_LOG=ironclaw::agent=debug,ironclaw::tools=trace

  # JSON output
  RUST_LOG=ironclaw=info,json
  ```
</ParamField>

## Configuration Files Reference

<CardGroup cols={2}>
  <Card title="~/.ironclaw/.env" icon="file">
    Bootstrap environment variables (database URL, LLM backend)

    Written by the setup wizard. Loaded on startup.
  </Card>

  <Card title="~/.ironclaw/config.toml" icon="file-code">
    Structured TOML configuration (optional)

    Overrides database settings, overridden by environment variables.
  </Card>

  <Card title="~/.ironclaw/session.json" icon="file-lock">
    NEAR AI session token (auto-generated)

    Created during OAuth flow. Do not edit manually.
  </Card>

  <Card title="Database settings table" icon="database">
    Persistent settings stored in the database

    Lowest priority. Managed via the wizard or API.
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <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">
    Configure Telegram, HTTP webhooks, and more
  </Card>

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

  <Card title="Development" icon="code" href="/development">
    Build custom tools and contribute to IronClaw
  </Card>
</CardGroup>