ironclaw config

Manage IronClaw configuration settings

ironclaw config

Manage application configuration settings. Settings are stored in the database (if available) or on disk, with environment variables taking precedence.

Subcommands

• init - Generate a default config.toml file
• list - List all settings and their current values
• get - Get a specific setting value
• set - Set a setting value
• reset - Reset a setting to its default value
• path - Show settings storage info

Settings Priority

Settings are resolved in this order (highest to lowest priority):

1. Environment variables - AGENT_NAME=mybot
2. config.toml file - ~/.ironclaw/config.toml
3. Database - Settings table
4. Defaults - Built-in defaults

---

ironclaw config init

Generate a default config.toml file with current settings.

Syntax

ironclaw config init [FLAGS]

Flags

--output, -o <PATH>

Output path for the config file.

• Default: ~/.ironclaw/config.toml

--force

Overwrite existing file.

Examples

# Generate config file in default location
ironclaw config init

# Generate in custom location
ironclaw config init --output /etc/ironclaw/config.toml

# Overwrite existing file
ironclaw config init --force

Output

Config file written to /Users/you/.ironclaw/config.toml

Edit the file to customize settings.
Priority: env var > config.toml > database > defaults

The generated file includes all settings with their current values, organized by category:

[agent]
name = "ironclaw"
max_parallel_jobs = 3

[heartbeat]
interval_seconds = 300
enabled = true

[llm]
provider = "nearai"
model = "anthropic/claude-sonnet-4"

---

ironclaw config list

List all settings and their current values.

Syntax

ironclaw config list [FLAGS]

Flags

--filter, -f <PREFIX>

Show only settings matching this prefix.

Examples

# List all settings
ironclaw config list

# Filter by category
ironclaw config list --filter agent
ironclaw config list --filter heartbeat
ironclaw config list --filter llm

Output

Settings (source: database):

  agent.name                          ironclaw
  agent.max_parallel_jobs             3
  heartbeat.enabled                   true
  heartbeat.interval_seconds          300
  llm.provider                        nearai
  llm.model                           anthropic/claude-sonnet-4
  llm.max_tokens                      8192

Long values are truncated:

  workspace.allowed_prefixes          ["/home/user/workspace", "/Users/user/proj...

---

ironclaw config get

Get a specific setting value.

Syntax

ironclaw config get <PATH>

Arguments

<PATH>

Setting path using dot notation (e.g., agent.name, llm.model).

Examples

# Get agent name
ironclaw config get agent.name
# Output: ironclaw

# Get LLM model
ironclaw config get llm.model
# Output: anthropic/claude-sonnet-4

# Get heartbeat interval
ironclaw config get heartbeat.interval_seconds
# Output: 300

Error Handling

ironclaw config get invalid.setting
# Error: Setting not found: invalid.setting

---

ironclaw config set

Set a setting value.

Syntax

ironclaw config set <PATH> <VALUE>

Arguments

<PATH>

Setting path using dot notation.

<VALUE>

Value to set. Can be a string, number, boolean, or JSON.

Examples

# Set agent name
ironclaw config set agent.name "my-assistant"
# Output: Set agent.name = my-assistant

# Set numeric value
ironclaw config set agent.max_parallel_jobs 5
# Output: Set agent.max_parallel_jobs = 5

# Set boolean
ironclaw config set heartbeat.enabled true
# Output: Set heartbeat.enabled = true

# Set JSON array
ironclaw config set workspace.allowed_prefixes '["~/workspace", "~/projects"]'
# Output: Set workspace.allowed_prefixes = ["~/workspace", "~/projects"]

Requirements

• Requires database connection
• Setting path must exist in the schema
• Value must be valid for the setting type

Error Handling

ironclaw config set invalid.path "value"
# Error: Unknown setting: invalid.path

ironclaw config set agent.max_parallel_jobs "not-a-number"
# Error: Invalid value for agent.max_parallel_jobs: expected integer

---

ironclaw config reset

Reset a setting to its default value.

Syntax

ironclaw config reset <PATH>

Arguments

<PATH>

Setting path to reset.

Examples

# Reset agent name to default
ironclaw config reset agent.name
# Output: Reset agent.name to default: ironclaw

# Reset heartbeat interval
ironclaw config reset heartbeat.interval_seconds
# Output: Reset heartbeat.interval_seconds to default: 300

Behavior

• Removes the setting from the database
• The default value will be used
• Environment variables and config.toml still take precedence

---

ironclaw config path

Show settings storage information.

Syntax

ironclaw config path

Output

Settings stored in: database (settings table)
Env config:         /Users/you/workspace/.env
TOML config:        /Users/you/.ironclaw/config.toml (found)

If config.toml doesn’t exist:

Settings stored in: PostgreSQL (not connected, using defaults)
Env config:         /Users/you/workspace/.env
TOML config:        /Users/you/.ironclaw/config.toml (not found, run `ironclaw config init` to create)

Common Settings

Agent Settings

agent.name                    # Agent display name
agent.max_parallel_jobs       # Maximum concurrent jobs

Heartbeat Settings

heartbeat.enabled             # Enable periodic heartbeat
heartbeat.interval_seconds    # Heartbeat interval

LLM Settings

llm.provider                  # LLM provider (nearai, anthropic, openai)
llm.model                     # Model identifier
llm.max_tokens                # Maximum tokens per request
llm.temperature               # Sampling temperature (0.0-1.0)

Workspace Settings

workspace.allowed_prefixes    # Allowed file path prefixes (JSON array)

Configuration File Format

The config.toml file uses TOML format:

# Agent configuration
[agent]
name = "ironclaw"
max_parallel_jobs = 3

# Heartbeat configuration
[heartbeat]
enabled = true
interval_seconds = 300

# LLM configuration
[llm]
provider = "nearai"
model = "anthropic/claude-sonnet-4"
max_tokens = 8192
temperature = 0.7

# Workspace configuration
[workspace]
allowed_prefixes = ["/home/user/workspace"]

Troubleshooting

”Database connection required”

config set and config reset require a database connection:

# Check database
ironclaw doctor

# Verify DATABASE_URL or LIBSQL_PATH is set
env | grep DATABASE

“Warning: Could not connect to database”

The command falls back to disk-based configuration. Settings will be read from defaults and config.toml only.

Settings not taking effect

Remember the priority order:

1. Check environment variables: env | grep -i <setting>
2. Check config.toml: cat ~/.ironclaw/config.toml
3. Check database: ironclaw config get <path>

Related Commands

• onboard - Initial configuration wizard
• doctor - Validate configuration