Skip to main content
IronClaw is configured by a file in your IronClaw home directory, not by a long list of environment variables. Environment variables exist to override individual values and to carry secrets.

​
Where Configuration Lives

Everything lives under ~/.ironclaw/reborn. Override the location with IRONCLAW_REBORN_HOME.
Two files matter, and both are optional — delete them and IronClaw falls back to built-in defaults. config.toml selects by id from the catalog providers.json defines. The compiled-in provider defaults are appended with your entries, and later entries override earlier ones by id.

​
Precedence

Each field resolves through four layers, later winning over earlier:
So ironclaw serve --port 3100 beats the port in config.toml, which beats the built-in default of 3000.

​
Editing Configuration

Generate a commented starter file:
It refuses to overwrite existing files unless you pass --force. Read and write individual keys with dot-separated paths:
list and get read every key. set is deliberately narrower — it accepts only the keys that have a routing destination:
Everything else — runner.*, webui.listen_port, budget.*, [llm.default] — is edited in config.toml directly. config set rejects an unsupported key rather than silently doing nothing. Secret-destination keys (<provider>.api_key, google.client_secret) reject a value on the command line and always prompt with input hidden, so the secret never reaches your shell history.

​
Applying a Change

config set never restarts anything. It writes the value and prints the step you still have to run:
Until you do, a running instance keeps serving the old value.
ironclaw service commands do not work on a NEAR AI hosted instance — there is no user service manager for them to talk to, so service restart fails rather than restarting anything.SSH in only to run the ironclaw config commands, then restart the agent from the Agent Dashboard. That is the only way to restart a hosted instance.

​
Secrets

Secrets are never stored in config.toml. Reference them by environment variable name:
Pasting a secret value where a variable name is expected is rejected at parse time, not silently accepted. api_key_env = "sk-ant-..." will fail to load.
Your master encryption key lives in the OS keychain. On a headless host, supply it through IRONCLAW_REBORN_SECRET_MASTER_KEY. See Security.

​
Profiles

A profile selects a composition of runtime behavior — how capabilities are mediated, what storage is expected, and how processes are isolated.
Set it in config.toml under [boot], or per-invocation with IRONCLAW_REBORN_PROFILE.
Profile choice is a security boundary, not a preset. A deployment that serves more than one user must not run a profile with single-user host semantics. See Security.

​
Configuration Reference

Run ironclaw config list to see every key with its current value. The main groups:
identity.tenant and identity.default_agent are optional overrides for the tenant and agent ids the runtime operates under. Leave them unset unless you know you need a different scope — a stale value here silently moves your work into another identity scope.identity.default_project is consumed by serve but not by run or repl; those two subcommands fail on startup rather than silently dropping it.
No slot is configured by default, so IronClaw falls back to provider environment variables until you set one.Uncommenting only the [llm.default] header with no fields does not fall through to the environment — an empty slot is still present, and resolution fails with a missing-provider-id error. Always set provider_id together with the header.See Inference Providers.
The database URL is environment-only; this file may name the variable but must never contain the URL itself. See Storage.
Also worker_count, max_concurrent_runs_per_user, max_concurrent_conversation_runs, and max_concurrent_trigger_runs. Those four have IRONCLAW_REBORN_RUNNER_* environment overrides; heartbeat_interval_secs and poll_interval_ms are file-only.
Caps agent spend so a runaway loop can’t run up a bill:
  • budget.user_daily_usd, budget.project_daily_usd
  • budget.warn_at, budget.pause_at
  • budget.heartbeat_per_tick_usd, budget.mission_per_tick_usd
  • budget.routine_standard_usd, budget.routine_lightweight_usd
  • budget.background_job_default_usd, budget.overestimate_factor, budget.default_tz
Controls how scheduled and event-driven work is picked up: enabled, poll_interval_secs, fires_per_tick, max_concurrent_fires_per_trigger, startup_jitter_max_secs, tick_jitter_max_secs.See Routines.
slack.* covers app ids, bot token and signing secret variable names, and channel routes. telegram.enabled turns the Telegram channel on. google.* carries the OAuth client id, redirect URI, and hosted-domain hint.Configure these from the web interface rather than by hand — see Channels.
When false, regex activation criteria no longer auto-load full skill context. Keyword and tag activation, and explicit $skill-name mentions, still work. See Skills.

​
Environment Variables

Overrides are namespaced IRONCLAW_REBORN_*. The ones you’re most likely to need: Provider API keys use each provider’s own variable name — ANTHROPIC_API_KEY, OPENAI_API_KEY, NEARAI_API_KEY, and so on.

​
Checking Your Configuration

Reports the resolved home and profile, whether each configuration file was found, and whether each driver initialized — without creating any state.