Skip to main content

​
Overview

IronClaw configuration follows this priority: env var > database settings > defaults. Most settings can be configured via the onboarding wizard or by editing:
  • ~/.ironclaw/.env (bootstrap variables)
  • Environment variables in your shell

​
Database Configuration

VariableDescriptionDefaultRequired
DATABASE_BACKENDBackend type (postgres or libsql)postgresNo
DATABASE_URLPostgreSQL connection URL-Yes (for postgres)
DATABASE_POOL_SIZEMax connections in pool10No
DATABASE_SSLMODESSL mode (disable, prefer, require)preferNo
LIBSQL_PATHLocal libSQL database file~/.ironclaw/ironclaw.dbYes (for libsql)
LIBSQL_URLTurso remote URL (optional)-No
LIBSQL_AUTH_TOKENTurso auth token-Yes (if LIBSQL_URL set)
Example (PostgreSQL): 
DATABASE_BACKEND=postgres
DATABASE_URL=postgres://user:password@localhost:5432/ironclaw
DATABASE_POOL_SIZE=10
DATABASE_SSLMODE=prefer
Example (libSQL): 
DATABASE_BACKEND=libsql
LIBSQL_PATH=~/.ironclaw/ironclaw.db
# Optional Turso sync:
# LIBSQL_URL=libsql://your-db.turso.io
# LIBSQL_AUTH_TOKEN=your-token

​
LLM Provider Configuration

​
General

VariableDescriptionDefaultRequired
LLM_BACKENDProvider (nearai, openai, anthropic, ollama, openai_compatible)nearaiNo

​
NEAR AI

VariableDescriptionDefaultRequired
NEARAI_MODELModel to usezai-org/GLM-latestNo
NEARAI_BASE_URLAPI base URLhttps://private.near.aiNo
NEARAI_AUTH_URLAuth/refresh endpoint base URLhttps://private.near.aiNo
NEARAI_SESSION_TOKENSession token (for hosting providers)-No
NEARAI_SESSION_PATHPath to session file~/.ironclaw/session.jsonNo
NEARAI_API_KEYAPI key from cloud.near.ai-No
NEARAI_CHEAP_MODELCheap/fast model for lightweight tasks-No
NEARAI_FALLBACK_MODELFallback model for automatic failover-No
NEARAI_MAX_RETRIESMax retry attempts for transient errors3No
CIRCUIT_BREAKER_THRESHOLDConsecutive failures before circuit opens-No
CIRCUIT_BREAKER_RECOVERY_SECSCircuit breaker recovery timeout30No
RESPONSE_CACHE_ENABLEDEnable in-memory response cachingfalseNo
RESPONSE_CACHE_TTL_SECSCache TTL in seconds3600No
RESPONSE_CACHE_MAX_ENTRIESMax cached responses1000No
LLM_FAILOVER_COOLDOWN_SECSFailover cooldown duration300No
LLM_FAILOVER_THRESHOLDConsecutive failures before cooldown3No
SMART_ROUTING_CASCADEEnable cascade for smart routingtrueNo
Example: 
LLM_BACKEND=nearai
NEARAI_MODEL=anthropic::claude-sonnet-4-20250514
NEARAI_CHEAP_MODEL=zai-org/GLM-latest
NEARAI_FALLBACK_MODEL=openai::gpt-4o-mini
NEARAI_MAX_RETRIES=3

​
Anthropic

VariableDescriptionDefaultRequired
ANTHROPIC_API_KEYAnthropic API key-Yes
ANTHROPIC_MODELModel to useclaude-sonnet-4-20250514No
ANTHROPIC_BASE_URLCustom base URL (proxy)-No
Example: 
LLM_BACKEND=anthropic
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022

​
OpenAI

VariableDescriptionDefaultRequired
OPENAI_API_KEYOpenAI API key-Yes
OPENAI_MODELModel to usegpt-4oNo
OPENAI_BASE_URLCustom base URL (proxy)-No
Example: 
LLM_BACKEND=openai
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini

​
Ollama

VariableDescriptionDefaultRequired
OLLAMA_BASE_URLOllama server URLhttp://localhost:11434No
OLLAMA_MODELModel to usellama3No
Example: 
LLM_BACKEND=ollama
OLLAMA_MODEL=llama3.2
OLLAMA_BASE_URL=http://localhost:11434

​
OpenAI-Compatible

VariableDescriptionDefaultRequired
LLM_BASE_URLAPI base URL-Yes
LLM_API_KEYAPI key (if required)-No
LLM_MODELModel to usedefaultNo
LLM_EXTRA_HEADERSComma-separated Key:Value HTTP headers-No
Example (OpenRouter): 
LLM_BACKEND=openai_compatible
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_API_KEY=sk-or-...
LLM_MODEL=anthropic/claude-sonnet-4
LLM_EXTRA_HEADERS=HTTP-Referer:https://myapp.com,X-Title:MyApp
Example (LM Studio): 
LLM_BACKEND=openai_compatible
LLM_BASE_URL=http://localhost:1234/v1
LLM_MODEL=llama-3.2-3b-instruct-q4_K_M
# No API key needed

​
Embeddings Configuration

VariableDescriptionDefaultRequired
EMBEDDINGS_PROVIDERProvider (nearai or openai)-No
EMBEDDINGS_MODELModel to usetext-embedding-3-smallNo
EMBEDDINGS_ENABLEDEnable semantic search-No
Example: 
EMBEDDINGS_PROVIDER=openai
EMBEDDINGS_MODEL=text-embedding-3-small
EMBEDDINGS_ENABLED=true

​
Channel Configuration

​
HTTP Webhook

VariableDescriptionDefaultRequired
HTTP_HOSTBind address0.0.0.0No
HTTP_PORTPort8080No
HTTP_WEBHOOK_SECRETHMAC secret for webhook verification-No
Example: 
HTTP_HOST=127.0.0.1
HTTP_PORT=8080
HTTP_WEBHOOK_SECRET=your-webhook-secret

​
Slack Bot

VariableDescriptionDefaultRequired
SLACK_BOT_TOKENBot User OAuth Token (xoxb-...)-Yes
SLACK_APP_TOKENApp-Level Token (xapp-...)-Yes
SLACK_SIGNING_SECRETSigning secret for webhook verification-Yes
Example: 
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
SLACK_SIGNING_SECRET=...

​
Telegram Bot

VariableDescriptionDefaultRequired
TELEGRAM_BOT_TOKENBot token from @BotFather-Yes
Example: 
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

​
Signal Channel

VariableDescriptionDefaultRequired
SIGNAL_HTTP_URLsignal-cli HTTP daemon URLhttp://127.0.0.1:8080No
SIGNAL_ACCOUNTSignal phone number-Yes
SIGNAL_ALLOW_FROMComma-separated allowed senders (* for all)-No
SIGNAL_ALLOW_FROM_GROUPSComma-separated allowed group IDs-No
SIGNAL_DM_POLICYDM policy (open, allowlist, pairing)pairingNo
SIGNAL_GROUP_POLICYGroup policy (allowlist, open, disabled)allowlistNo
SIGNAL_GROUP_ALLOW_FROMComma-separated allowed senders in groups-No
SIGNAL_IGNORE_ATTACHMENTSIgnore attachmentsfalseNo
SIGNAL_IGNORE_STORIESIgnore storiestrueNo
Example: 
SIGNAL_HTTP_URL=http://127.0.0.1:8080
SIGNAL_ACCOUNT=+1234567890
SIGNAL_ALLOW_FROM=+1234567890,uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
SIGNAL_DM_POLICY=pairing

​
Agent Settings

VariableDescriptionDefaultRequired
AGENT_NAMEAgent nameironclawNo
AGENT_MAX_PARALLEL_JOBSMax concurrent jobs5No
AGENT_JOB_TIMEOUT_SECSJob timeout in seconds3600No
AGENT_STUCK_THRESHOLD_SECSThreshold for stuck job detection300No
AGENT_USE_PLANNINGEnable planning phase before executiontrueNo
Example: 
AGENT_NAME=ironclaw
AGENT_MAX_PARALLEL_JOBS=10
AGENT_JOB_TIMEOUT_SECS=7200
AGENT_USE_PLANNING=true

​
Self-Repair Settings

VariableDescriptionDefaultRequired
SELF_REPAIR_CHECK_INTERVAL_SECSCheck interval in seconds60No
SELF_REPAIR_MAX_ATTEMPTSMax repair attempts3No
Example: 
SELF_REPAIR_CHECK_INTERVAL_SECS=120
SELF_REPAIR_MAX_ATTEMPTS=5

​
Heartbeat Settings

VariableDescriptionDefaultRequired
HEARTBEAT_ENABLEDEnable periodic background executionfalseNo
HEARTBEAT_INTERVAL_SECSInterval in seconds1800No
HEARTBEAT_NOTIFY_CHANNELChannel for notificationscliNo
HEARTBEAT_NOTIFY_USERUser ID for notificationsdefaultNo
Example: 
HEARTBEAT_ENABLED=true
HEARTBEAT_INTERVAL_SECS=3600
HEARTBEAT_NOTIFY_CHANNEL=telegram
HEARTBEAT_NOTIFY_USER=default

​
Memory Hygiene Settings

VariableDescriptionDefaultRequired
MEMORY_HYGIENE_ENABLEDEnable automatic cleanuptrueNo
MEMORY_HYGIENE_RETENTION_DAYSDelete docs older than N days30No
MEMORY_HYGIENE_CADENCE_HOURSMin hours between cleanups12No
Example: 
MEMORY_HYGIENE_ENABLED=true
MEMORY_HYGIENE_RETENTION_DAYS=60
MEMORY_HYGIENE_CADENCE_HOURS=24
Identity files (IDENTITY.md, SOUL.md) are never deleted.

​
Safety Settings

VariableDescriptionDefaultRequired
SAFETY_MAX_OUTPUT_LENGTHMax tool output length (bytes)100000No
SAFETY_INJECTION_CHECK_ENABLEDEnable prompt injection detectiontrueNo
Example: 
SAFETY_MAX_OUTPUT_LENGTH=200000
SAFETY_INJECTION_CHECK_ENABLED=true

​
Secrets Configuration

VariableDescriptionDefaultRequired
SECRETS_MASTER_KEY256-bit hex-encoded encryption key-No
Example: 
SECRETS_MASTER_KEY=abc123...  # Generated by wizard
Store the master key securely. If lost, encrypted secrets cannot be recovered.

​
Logging

VariableDescriptionDefaultRequired
RUST_LOGLogging level and filtersironclaw=infoNo
Example: 
# Debug mode
RUST_LOG=ironclaw=debug,tower_http=debug

# Trace all modules
RUST_LOG=trace

# Info with specific debug targets
RUST_LOG=ironclaw=info,ironclaw::llm=debug

​
Onboarding

VariableDescriptionDefaultRequired
ONBOARD_COMPLETEDOnboarding completion flag-No
IRONCLAW_OAUTH_CALLBACK_URLOAuth callback URL (for remote servers)http://127.0.0.1:9876No
Example (remote server): 
IRONCLAW_OAUTH_CALLBACK_URL=https://myserver.example.com:9876

​
Complete Example

Here’s a complete ~/.ironclaw/.env file for a typical setup: 
# Database
DATABASE_BACKEND=postgres
DATABASE_URL=postgres://user:password@localhost:5432/ironclaw
DATABASE_POOL_SIZE=10

# LLM Provider
LLM_BACKEND=openai_compatible
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_API_KEY=sk-or-...
LLM_MODEL=anthropic/claude-sonnet-4
LLM_EXTRA_HEADERS=HTTP-Referer:https://myapp.com,X-Title:MyApp

# Embeddings
EMBEDDINGS_PROVIDER=openai
EMBEDDINGS_MODEL=text-embedding-3-small
EMBEDDINGS_ENABLED=true

# Channels
HTTP_HOST=0.0.0.0
HTTP_PORT=8080
HTTP_WEBHOOK_SECRET=your-webhook-secret

TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

# Agent
AGENT_NAME=ironclaw
AGENT_MAX_PARALLEL_JOBS=5
AGENT_USE_PLANNING=true

# Heartbeat
HEARTBEAT_ENABLED=true
HEARTBEAT_INTERVAL_SECS=1800
HEARTBEAT_NOTIFY_CHANNEL=telegram

# Safety
SAFETY_INJECTION_CHECK_ENABLED=true

# Logging
RUST_LOG=ironclaw=debug

# Onboarding
ONBOARD_COMPLETED=true

​
Loading Priority

IronClaw loads configuration in this order:
  1. Current directory .env (highest priority, via dotenvy)
  2. ~/.ironclaw/.env (bootstrap variables)
  3. Database settings (from settings table)
  4. Hardcoded defaults (lowest priority)
Environment variables always override database settings.

Build docs developers (and LLMs) love

Get started for freeTalk to us