Skip to main content

​
Overview

The ironclaw config command provides subcommands for viewing and modifying IronClaw settings. Settings are stored in the database with fallback to disk, following the precedence: environment variables > config.toml > database > defaults.

​
Subcommands

​
init

Generate a default config.toml file: 
ironclaw config init [OPTIONS]
​
-o, --output
path
Output path for the config file. Defaults to ~/.ironclaw/config.toml.
​
--force
flag
Overwrite existing config file if it exists.
Example: 
ironclaw config init
ironclaw config init --output ./config.toml --force

​
list

List all settings and their current values: 
ironclaw config list [OPTIONS]
​
-f, --filter
string
Show only settings matching this prefix (e.g., “agent”, “heartbeat”, “embeddings”).
Example: 
ironclaw config list
ironclaw config list --filter agent
Output: 
Settings (source: database):

  agent.name                    ironclaw
  agent.max_parallel_jobs       5
  agent.max_iterations          50
  heartbeat.enabled             true
  heartbeat.interval_secs       300
  embeddings.enabled            false
  embeddings.provider           openai
  embeddings.model              text-embedding-3-small

​
get

Get the value of a specific setting: 
ironclaw config get <PATH>
​
path
string
required
Setting path using dot notation (e.g., “agent.max_parallel_jobs”).
Example: 
ironclaw config get agent.name
# Output: ironclaw

ironclaw config get heartbeat.interval_secs
# Output: 300

​
set

Set a setting value: 
ironclaw config set <PATH> <VALUE>
​
path
string
required
Setting path using dot notation (e.g., “agent.max_parallel_jobs”).
​
value
string
required
Value to set. Will be parsed as JSON if possible, otherwise stored as a string.
Example: 
ironclaw config set agent.name "my-agent"
ironclaw config set agent.max_parallel_jobs 10
ironclaw config set heartbeat.enabled true
Output: 
Set agent.max_parallel_jobs = 10
Changes made with set require a restart of the agent to take effect.

​
reset

Reset a setting to its default value: 
ironclaw config reset <PATH>
​
path
string
required
Setting path to reset (e.g., “agent.name”).
Example: 
ironclaw config reset agent.name
# Output: Reset agent.name to default: ironclaw

​
path

Show information about where settings are stored: 
ironclaw config path
Output: 
Settings stored in: database (settings table)
Env config:         /home/user/.ironclaw/.env
TOML config:        /home/user/.ironclaw/config.toml (not found)

​
Available Settings

Key settings you can configure:

​
Agent Settings

  • agent.name - Agent display name (default: “ironclaw”)
  • agent.max_parallel_jobs - Maximum concurrent jobs (default: 5)
  • agent.max_iterations - Maximum iterations per agent loop (default: 50)
  • agent.timeout_secs - Job timeout in seconds (default: 300)

​
Heartbeat Settings

  • heartbeat.enabled - Enable periodic heartbeat loop (default: true)
  • heartbeat.interval_secs - Seconds between heartbeats (default: 300)

​
Embeddings Settings

  • embeddings.enabled - Enable semantic search (default: false)
  • embeddings.provider - Embeddings provider (“openai”, “local”) (default: “openai”)
  • embeddings.model - Model to use (default: “text-embedding-3-small”)
  • embeddings.batch_size - Batch size for indexing (default: 100)

​
Channel Settings

  • channels.http_enabled - Enable HTTP API (default: false)
  • channels.http_port - HTTP server port (default: 3000)

​
WASM Settings

  • wasm.max_memory_mb - Maximum memory per WASM instance (default: 512)
  • wasm.max_execution_time_ms - Execution timeout (default: 30000)

​
Configuration Precedence

Settings are resolved in this order (highest to lowest priority):
  1. Environment variables - AGENT_NAME, HEARTBEAT_ENABLED, etc.
  2. config.toml - TOML configuration file
  3. Database - Settings stored in the database
  4. Defaults - Built-in default values

​
Examples

​
View all agent settings

ironclaw config list --filter agent

​
Change agent name

ironclaw config set agent.name "production-agent"

​
Enable heartbeat with custom interval

ironclaw config set heartbeat.enabled true
ironclaw config set heartbeat.interval_secs 600

​
Generate config file from current settings

ironclaw config init --force
This creates a config.toml file reflecting your current configuration, which you can then edit directly.

​
Editing config.toml

You can also edit the TOML file directly: 
[agent]
name = "my-agent"
max_parallel_jobs = 10
max_iterations = 50

[heartbeat]
enabled = true
interval_secs = 300

[embeddings]
enabled = true
provider = "openai"
model = "text-embedding-3-small"
Changes to config.toml take effect when the agent restarts.

ironclaw status

View current configuration status

ironclaw doctor

Validate configuration

ironclaw onboard

Reconfigure with interactive wizard

Build docs developers (and LLMs) love

Get started for freeTalk to us