Configuration

All configuration options for Iron Rain, from file discovery to every field.

Config file discovery

Iron Rain searches for a config file starting in the current directory, walking up to your home directory. It looks for these filenames in order:

1. iron-rain.json
2. iron-rain.jsonc (supports comments)
3. .iron-rainrc.json

The first file found wins. You can place it in your project root for per-project config, or in ~ for a global default.

Full config reference

{
  // Model slot assignments (required for multi-model)
  "slots": {
    "main":    { "provider": "anthropic", "model": "claude-opus-4-6" },
    "explore": { "provider": "ollama",    "model": "qwen2.5-coder:32b" },
    "execute": { "provider": "openai",    "model": "gpt-4o" }
  },

  // Provider credentials
  "providers": {
    "anthropic": { "apiKey": "env:ANTHROPIC_API_KEY" },
    "openai":    { "apiKey": "env:OPENAI_API_KEY" },
    "ollama":    { "apiBase": "http://localhost:11434" }
  },

  // Tool permissions
  "permission": {
    "*":    "allow",
    "bash": "ask",
    "edit": "ask"
  },

  // Thinking levels per slot
  // "off" | "low" | "medium" | "high"

  // Active agent profile
  "agent": "build",

  // Auto-update settings
  "updates": {
    "autoCheck": true,
    "channel": "stable"
  },

  // LCM (context management) settings
  "lcm": {
    "enabled": true,
    "episodes": {
      "maxEpisodeTokens": 4000
    }
  },

  // MCP servers
  "mcpServers": {
    "my-server": { "command": "node", "args": ["./server.js"] }
  },

  // Skill discovery
  "skills": {
    "autoDiscover": true,
    "paths": ["./custom-skills"]
  },

  // Auto-commit after plan tasks
  "autoCommit": {
    "enabled": false,
    "messagePrefix": "iron-rain:"
  },

  // Sandbox for command execution
  "sandbox": {
    "backend": "none",
    "allowNetwork": false
  },

  // Project rules injection
  "rules": { "disabled": false },

  // Session persistence
  "session": { "autoResume": true, "maxHistory": 50 },

  // Memory / lessons
  "memory": { "autoLearn": true, "maxLessons": 50 },

  // Repo map generation
  "repoMap": { "enabled": true, "maxTokens": 2000 },

  // Cost tracking overrides
  "costs": {
    "custom-model": { "input": 0.001, "output": 0.002 }
  },

  // Remote config URL
  "configUrl": "https://example.com/iron-rain.json",

  // TUI theme
  "theme": "default"
}

Slots

Each slot routes a category of work to a specific model. There are three slots:

Slot config fields

Thinking levels

Set thinkingLevel per slot to control reasoning depth. Each provider maps this to its native parameter:

You can also change thinking levels at runtime from the Settings screen.

Providers

The providers object maps provider names to their credentials. These are shared across all slots that reference the provider.

Permissions

Control which tools require confirmation before running:

Use "*" as a wildcard key for the default policy, then override specific tools.

LCM (Context Management)

MCP Servers

Iron Rain can connect to MCP (Model Context Protocol) servers. Tool descriptions from connected servers are injected into the system prompt automatically.

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["./mcp-server.js"]
    }
  }
}

Connections are established at startup (non-blocking). Tool descriptions are merged into the system prompt for every dispatch.

Skills

Iron Rain discovers and loads skill files from your project. Skills provide slash commands that extend the TUI.

{
  "skills": {
    "autoDiscover": true,
    "paths": ["./custom-skills"]
  }
}

Auto-Commit

Automatically commit changes after each plan task completes.

Sandbox

Run bash commands in an isolated sandbox to prevent unintended side effects.

Rules

Project rules are injected into every system prompt. Iron Rain looks for rules in IRON-RAIN.md, CLAUDE.md, and .iron-rain/rules/*.md.

Session

Control session persistence behavior.

Memory

Configure the persistent lesson system (~/.iron-rain/sessions.db).

Repo Map

Auto-generated repository map injected into system prompts for structural awareness.

The repo map walks the directory tree (respecting .ironrainignore and .gitignore), extracts file symbols (exports, functions, classes), and truncates to the token budget.

Costs

Override or add custom model pricing for cost tracking. Keys are model names, values specify per-token cost in dollars.

{
  "costs": {
    "my-custom-model": { "input": 0.001, "output": 0.002 },
    "claude-opus-4-6": { "input": 0.015, "output": 0.075 }
  }
}

Built-in models have default pricing. Use this section to override or add models not in the registry.

Plugins

Load plugins that hook into the dispatch lifecycle.

See the Plugin SDK for details on creating plugins.

Context

Fine-tune context management behavior.

Resilience

Configure retry and circuit breaker behavior for API calls.

LSP (experimental)

Connect Language Server Protocol servers for enhanced code intelligence.

{
  "lsp": {
    "enabled": true,
    "servers": {
      "typescript": { "command": "typescript-language-server", "args": ["--stdio"] }
    }
  }
}

Voice (experimental)

Enable voice input for hands-free interaction.

Remote Config

Fetch and merge a remote config at startup. Useful for team-wide settings.

{
  "configUrl": "https://example.com/team-iron-rain.json"
}

The remote config is deep-merged with the local config. Local values take precedence. The fetch runs at startup with a 5-second timeout.

Other fields