IronClaw Configuration — config.toml, Profiles & Budgets

Where it lives

ironclaw config path
# reborn_home:  ~/.ironclaw/reborn
# profile:      local-dev
# config_file:  ~/.ironclaw/reborn/config.toml
# providers:    ~/.ironclaw/reborn/providers.json

Change the home with IRONCLAW_REBORN_HOME. Precedence: compiled defaults < config.toml < environment variables < CLI flags. So ironclaw serve --port 3100 beats the port in the file.

Commands

ironclaw config init                      # commented starter files (won't overwrite without --force)
ironclaw config list                      # every key and its value
ironclaw config get llm.default.provider_id
ironclaw config set anthropic.api_key     # secret keys prompt with hidden input
ironclaw service restart                  # config set never restarts anything

config set deliberately accepts only a few keys: <provider>.api_key, google.client_id, google.client_secret, google.redirect_uri and webui.token --rotate. It routes each to the config file, the encrypted secret store or the token file. Edit everything else in config.toml. Since 1.4.1, a Google OAuth client set by an administrator in the web UI takes precedence over one supplied through the environment or config.toml. Retired keys such as the old [slack] section are refused. On a NEAR AI hosted instance, restart from the Agent Dashboard, not with service restart.

Secrets: name the variable, never paste the value

[llm.default]
provider_id = "anthropic"
model       = "<model-id>"
api_key_env = "ANTHROPIC_API_KEY"

Putting a key value where a variable name belongs (api_key_env = "sk-ant-…") is rejected when the file loads. Secrets live in the encrypted store, and its master key is in the OS keychain. An empty [llm.default] header with no provider_id fails rather than falling back to environment variables.

Profiles: a security boundary, not a preset

Set it under [boot] or with IRONCLAW_REBORN_PROFILE, and list the options with ironclaw profile list. A deployment serving more than one user must not run a single-user profile.

The main groups

• [boot], [identity]: profile and owner. Leave identity.tenant and default_agent unset unless you need them; a stale value silently moves your work into another scope.
• [llm.default]: provider and model (see above). No slot is set by default, so provider environment variables are used until you set one.
• [storage]: libSQL on file by default, or backend = "postgres" with the URL supplied only through an environment variable (url_env).
• budget.*: spend caps against runaway loops: user_daily_usd, project_daily_usd, warn_at, pause_at, per-tick heartbeat and mission caps, and routine and background-job defaults. Set these before leaving automations running.
• [runner]: worker counts and concurrency per user, conversation and trigger.
• [trigger_poller]: how scheduled and event-driven routines are picked up.
• [skills]: regex_activation_enabled.
• Channels are not in this file. Slack and Telegram are enabled by installing their extensions in the web interface, and their credentials go in the encrypted store.

Environment variables you'll actually use

IRONCLAW_REBORN_HOME, IRONCLAW_REBORN_PROFILE, IRONCLAW_REBORN_LOG (for example debug), IRONCLAW_REBORN_POSTGRES_URL, IRONCLAW_REBORN_SECRET_MASTER_KEY, IRONCLAW_REBORN_WEBUI_TOKEN and IRONCLAW_REBORN_WEBUI_BASE_URL (behind a proxy). Provider keys use each provider's own name: ANTHROPIC_API_KEY, OPENAI_API_KEY, NEARAI_API_KEY and so on. Check everything with ironclaw doctor.