Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt

Use this file to discover all available pages before exploring further.

​
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>
  • onboard - Initial configuration wizard
  • doctor - Validate configuration

Build docs developers (and LLMs) love

Get started for freeTalk to us