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

Setup Wizard (Recommended)

The easiest way to configure IronClaw is via the interactive wizard:

ironclaw onboard

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

Environment Variables

Create a .env file in your project root or ~/.ironclaw/.env:

~/.ironclaw/.env

DATABASE_URL=postgres://localhost/ironclaw
LLM_BACKEND=nearai
NEARAI_MODEL=zai-org/GLM-latest

IronClaw loads .env automatically on startup via dotenvy.

TOML Config File

Create ~/.ironclaw/config.toml for structured configuration:

~/.ironclaw/config.toml

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

Database Configuration

IronClaw supports PostgreSQL and libSQL backends.

PostgreSQL

DATABASE_BACKEND · string · default: "postgres"

Database backend to use (postgres or libsql)

DATABASE_URL · string · required

PostgreSQL connection URL

DATABASE_URL=postgres://user:password@host:port/database

Examples:

• Local: postgres://localhost/ironclaw
• Neon: postgres://user:[e-mail]/ironclaw?sslmode=require
• Supabase: postgres://postgres:[e-mail]:5432/postgres

DATABASE_POOL_SIZE · integer · default: "10"

Maximum number of database connections in the pool

DATABASE_SSLMODE · 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

PostgreSQL 15+ and pgvector are required. See Installation → PostgreSQL Setup.

libSQL (Embedded SQLite)

LIBSQL_PATH · string · default: "~/.ironclaw/ironclaw.db"

Path to the local libSQL database file

LIBSQL_URL · string

Turso cloud URL for remote replica sync (optional)

LIBSQL_URL=libsql://your-db.turso.io

LIBSQL_AUTH_TOKEN · string

Turso authentication token (required if LIBSQL_URL is set)

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

LLM Provider Configuration

NEAR AI (Default)

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

LLM_BACKEND · string · default: "nearai"

Set to nearai to use NEAR AI

NEARAI_MODEL · 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

NEARAI_BASE_URL · string · default: "https://private.near.ai"

NEAR AI API base URL

NEARAI_AUTH_URL · string · default: "https://private.near.ai"

NEAR AI authentication URL

NEARAI_SESSION_TOKEN · string

Session token from browser OAuth (auto-generated by setup wizard)

Stored in ~/.ironclaw/session.json by default.

NEARAI_API_KEY · string

API key from cloud.near.ai (alternative to session token)

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

The setup wizard handles NEAR AI authentication automatically via browser OAuth.

Anthropic (Claude)

LLM_BACKEND · string

Set to anthropic to use Anthropic’s API

ANTHROPIC_API_KEY · string · required

Your Anthropic API key

Get one from: https://console.anthropic.com/settings/keys

ANTHROPIC_MODEL · 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

OpenAI

LLM_BACKEND · string

Set to openai to use OpenAI’s API

OPENAI_API_KEY · string · required

Your OpenAI API key

Get one from: https://platform.openai.com/api-keys

OPENAI_MODEL · 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

Ollama (Local Models)

LLM_BACKEND · string

Set to ollama to use local Ollama models

OLLAMA_BASE_URL · string · default: "http://localhost:11434"

Ollama server URL

OLLAMA_MODEL · string · default: "llama3.2"

Ollama model to use

Must be pulled first: ollama pull llama3.2

Ollama runs models locally on your machine. No API key required. See ollama.ai for installation.

OpenRouter (200+ Models)

LLM_BACKEND · string

Set to openai_compatible for OpenRouter

LLM_BASE_URL · string

Set to https://openrouter.ai/api/v1

LLM_API_KEY · string · required

Your OpenRouter API key

Get one from: https://openrouter.ai/settings/keys

LLM_MODEL · 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 for the full list.

LLM_EXTRA_HEADERS · string

Custom HTTP headers (comma-separated key:value pairs)

LLM_EXTRA_HEADERS=HTTP-Referer:https://myapp.com,X-Title:MyApp

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

LLM_BACKEND · string

Set to openai_compatible

LLM_BASE_URL · 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

LLM_API_KEY · string

API key (optional for local servers)

LLM_MODEL · 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)

Full LLM provider examples

NEAR AI

LLM_BACKEND=nearai
NEARAI_MODEL=zai-org/GLM-latest
NEARAI_BASE_URL=https://private.near.ai

Embeddings Configuration

Embeddings enable semantic search across your workspace.

EMBEDDINGS_ENABLED · boolean · default: "true"

Enable vector embeddings for semantic search

EMBEDDINGS_PROVIDER · string · default: "nearai"

Embeddings provider (nearai, openai, or same as LLM_BACKEND)

EMBEDDINGS_MODEL · string

Model to use for embeddings

• NEAR AI: text-embedding-3-small (default)
• OpenAI: text-embedding-3-small, text-embedding-3-large

Embeddings require PostgreSQL with pgvector or libSQL with vector support.

Secrets Configuration

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

SECRETS_MASTER_KEY · string

Master encryption key (256-bit hex string)

Generated by the setup wizard and stored in OS keychain or environment.

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.

Environment Variable

For CI/Docker deployments, set the key manually:

SECRETS_MASTER_KEY=a1b2c3d4e5f6...

Generate a key:

openssl rand -hex 32

Keep your master key secure! If lost, encrypted secrets cannot be recovered.

Agent Configuration

AGENT_NAME · string · default: "ironclaw"

Agent display name

AGENT_MAX_PARALLEL_JOBS · integer · default: "5"

Maximum number of concurrent jobs

AGENT_JOB_TIMEOUT_SECS · integer · default: "3600"

Job timeout in seconds (default: 1 hour)

AGENT_STUCK_THRESHOLD_SECS · integer · default: "300"

Time before marking a job as stuck (default: 5 minutes)

AGENT_USE_PLANNING · boolean · default: "true"

Enable planning phase before tool execution

When enabled, the agent plans its approach before executing tools, improving accuracy.

Channel Configuration

HTTP Webhook Server

HTTP_HOST · string · default: "0.0.0.0"

Host to bind the HTTP server to

HTTP_PORT · integer · default: "8080"

Port for the HTTP webhook server

HTTP_WEBHOOK_SECRET · string

Secret for authenticating webhook requests

Telegram Bot

TELEGRAM_BOT_TOKEN · string

Telegram bot token from @BotFather

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

Signal Messaging

SIGNAL_HTTP_URL · string · default: "http://127.0.0.1:8080"

signal-cli daemon HTTP URL

SIGNAL_ACCOUNT · string

Your Signal phone number (e.g., [phone])

SIGNAL_ALLOW_FROM · string

Comma-separated list of allowed senders (* for all)

SIGNAL_DM_POLICY · string · default: "pairing"

DM policy: open, allowlist, or pairing

Signal requires a running signal-cli daemon. See Signal Setup.

Slack Bot (WASM Channel)

SLACK_BOT_TOKEN · string

Slack bot token (xoxb-...)

SLACK_APP_TOKEN · string

Slack app-level token (xapp-...)

SLACK_SIGNING_SECRET · string

Slack request signing secret

Safety Configuration

SAFETY_MAX_OUTPUT_LENGTH · integer · default: "100000"

Maximum tool output length (characters)

SAFETY_INJECTION_CHECK_ENABLED · boolean · default: "true"

Enable prompt injection detection

Heartbeat Configuration

The heartbeat system runs background tasks on a schedule.

HEARTBEAT_ENABLED · boolean · default: "false"

Enable background heartbeat tasks

HEARTBEAT_INTERVAL_SECS · integer · default: "1800"

Heartbeat interval in seconds (default: 30 minutes)

HEARTBEAT_NOTIFY_CHANNEL · string · default: "cli"

Channel to send heartbeat notifications to

HEARTBEAT_NOTIFY_USER · string · default: "default"

User ID to notify

Heartbeat reads HEARTBEAT.md from your workspace and reports findings on the schedule.

Memory Hygiene Configuration

Automatic cleanup of stale workspace documents.

MEMORY_HYGIENE_ENABLED · boolean · default: "true"

Enable automatic cleanup of old daily notes

MEMORY_HYGIENE_RETENTION_DAYS · integer · default: "30"

Delete daily/ documents older than this many days

MEMORY_HYGIENE_CADENCE_HOURS · integer · default: "12"

Minimum hours between cleanup passes

Identity files (IDENTITY.md, SOUL.md) are never deleted.

Docker Sandbox Configuration

SANDBOX_MODE · string · default: "disabled"

Docker sandbox mode: disabled, enabled

SANDBOX_IMAGE · string · default: "ironclaw-sandbox:latest"

Docker image for sandbox execution

SANDBOX_TIMEOUT_SECS · integer · default: "300"

Sandbox execution timeout (default: 5 minutes)

Logging Configuration

RUST_LOG · string · default: "ironclaw=info"

Logging level and filters

Examples:

# Debug everything
RUST_LOG=ironclaw=debug

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

# JSON output
RUST_LOG=ironclaw=info,json

Configuration Files Reference

~/.ironclaw/.env

Bootstrap environment variables (database URL, LLM backend)

Written by the setup wizard. Loaded on startup.

~/.ironclaw/config.toml

Structured TOML configuration (optional)

Overrides database settings, overridden by environment variables.

~/.ironclaw/session.json

NEAR AI session token (auto-generated)

Created during OAuth flow. Do not edit manually.

Database settings table

Persistent settings stored in the database

Lowest priority. Managed via the wizard or API.

Next Steps

Tools & Extensions

Explore built-in tools and install extensions

Channels

Configure Telegram, HTTP webhooks, and more

CLI Reference

Explore all available commands

Development

Build custom tools and contribute to IronClaw