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