Configuration

IronShell reads one TOML settings file and environment variables. AI models are stored in a separate directory, described under Model Storage. Some keys in the TOML file are read but have no effect; the tables below say which.

Configuration File

Where it is read from

IronShell uses the first of these that applies:

1. The file named by IRONSHELL_CONFIG, if that variable is set. It is used even if it does not exist; then the defaults apply.
2. config.toml in the config directory, if that file exists. The config directory is IRONSHELL_CONFIG_HOME if set. Otherwise it is an ironshell directory in the OS config directory:
   • Linux: $XDG_CONFIG_HOME/ironshell (~/.config/ironshell when XDG_CONFIG_HOME is unset)
   • macOS: ~/Library/Application Support/ironshell
   • Windows: %APPDATA%\ironshell\config.toml
3. ~/.ironshellrc, if it exists. It is parsed as TOML if it looks like TOML; otherwise it is read as legacy key = value lines. The legacy keys it reads are color/colors, theme, vi_mode/vi-mode, auto_cd/auto-cd, banner/show_banner, history_size/history-size, editor/EDITOR, ai_model/model, and ai_provider/provider. Other lines are ignored.
4. Otherwise the built-in defaults. IronShell does not create a file at startup.

If the file exists but cannot be read or does not parse, IronShell starts with the defaults and prints one line to stderr naming the file and the error. config_set() and config_reload() report the error.

Creating and changing it

• config_init() writes a commented default file to the config directory. It does nothing if config.toml already exists.
• config_set(path, value) changes one key and saves the file. It accepts only these paths: colors.enabled, colors.force, colors.true_color, colors.theme, shell.show_banner, shell.show_tips, shell.vi_mode, shell.auto_cd, ai.default_model, ai.default_provider, ai.max_tokens, ai.streaming, history.enabled, history.max_size.
  • It writes the same file that the shell reads, which is the file config_path() reports as config_file: IRONSHELL_CONFIG if that is set; otherwise config.toml in the config directory if it exists; otherwise ~/.ironshellrc if it exists; otherwise a new config.toml in the config directory. Those are the rules in the list above. A file that the shell reads from ~/.ironshellrc is written back there, as TOML.
  • After the save, the running shell reloads the file, so the new value is in effect and config_get() returns it at once. The save rewrites the whole file from the settings IronShell knows, so comments and keys it does not read are dropped. The reply says (not applied: ...) for a key the shell stores but does not act on yet.
• Edits to the file take effect when you run config_reload() or start IronShell again. config_reload() replaces the settings in use; if the file cannot be read or does not parse, it fails and the settings in use stay.

Unknown keys are ignored. A key you leave out takes the default shown below.

Example

The values are the built-in defaults.

[shell]
show_banner = true
show_tips = true
default_directory = ""
vi_mode = false
auto_cd = false
glob_expansion = true
command_correction = true
bell_style = "none"

[colors]
enabled = true
theme = "catppuccin"
force = false
true_color = true

[colors.custom]          # used when theme = "custom"
number = "#a6e3a1"
string = "#a6e3a1"
boolean = "#cba6f7"
keyword = "#cba6f7"
punctuation = "#89b4fa"
key = "#89dceb"
uri = "#f9e2af"
error = "#f38ba8"
warning = "#fab387"
success = "#a6e3a1"
dim = "#6c7086"
comment = "#6c7086"

[prompt]
format = "{symbol}"
continuation = "… "
right = ""
show_git = true
show_time = true
time_threshold_ms = 1000
transient = false
style = "classic"
symbol = "❯"
segments = ["os", "cwd", "git", "status", "duration"]
powerline_separator = ""
abbreviate_path = true
max_path_segments = 0
two_line = false
show_user_host = false
show_git_dirty = false
autosuggestions = true

[prompt.segment_colors]  # e.g. cwd = "#1e1e2e:#89b4fa"

[prompt.abbreviations]   # e.g. gs = "git.status()"

[ai]
default_provider = "openai"
default_model = "gpt-4o-mini"
suggestions = false
max_tokens = 4096
temperature = 0.7
streaming = true
allowed_tools = []
blocked_tools = []
max_agent_steps = 10

[history]
enabled = true
max_size = 10000
ignore_duplicates = true
ignore_space = true
ignore_patterns = ["^exit$", "^quit$"]
share = false
timestamps = true

[editor]
# external defaults to $EDITOR, else notepad on Windows or vi elsewhere
tab_width = 4
syntax_highlighting = true
line_numbers = true
auto_indent = true
bracket_matching = true

[keybindings]
mode = "emacs"

[keybindings.custom]

[aliases]

[env]

Keys

“Applied” means the shell’s own code uses the value. “Not applied” means the key is read into the config and shown by config() and config_get(), and config_set() can change it, but nothing else in the shell acts on it.

[shell]

[colors]

[colors.custom] holds hex colours for number, string, boolean, keyword, punctuation, key, uri, error, warning, success, dim and comment. Its defaults are the Catppuccin Mocha colours shown in the example. It is applied when theme = "custom".

[prompt]

Applied. The prompt and the line editor use these keys.

[ai]

Not applied to ai(), to agents or to the TUI. These keys are read and shown by config() and config_get(), and config_set() can change some of them. The provider and model come from IRONSHELL_AI and the variables in AI Provider Setup.

[history]

History is saved to the history file in the data directory.

[editor]

Not applied. The external default is $EDITOR, else notepad on Windows or vi elsewhere.

[keybindings]

Not applied.

[aliases] and [env]

Not applied. [aliases] is a map from a name to a command. [env] is a map of variable names to values. IronShell does not set these variables. The settings are parsed and kept, but nothing reads them.

Environment Variables

The tables below cover every IRONSHELL_* variable the code reads, then the other names IronShell reads to make a decision. Each row gives the code location that reads it. Mode is Agent when the effect applies only in agent mode (--agent, IRONSHELL_MODE=agent, ish agent serve, ish mcp serve), and Both otherwise. Boolean switches accept only the values listed; any other value counts as unset.

Provider and model selection

Agent mode and safety

Limits and output

Audit, journal and telemetry

Directories, sessions and features

Network servers, registries and marketplace

Variables read from other tools

These are not IronShell settings. Each row names the decision the code makes with it, or says that the value is only reported.

Child processes: the shell removes its own IRONSHELL_* variables from a child’s environment, except the mode, policy, workspace, limit, allowlist, FIPS, deterministic, RBAC and audit settings, which pass through (CONFINING_ENV, strip_ironshell_env, src/safety.rs:1976, 2017). In agent mode, the child also loses secret-named variables unless they are in IRONSHELL_CHILD_ENV_KEEP, and the child receives IRONSHELL_MODE=agent. A variable set explicitly on the child’s command is kept.

Local evaluation records (IRONSHELL_RECORD)

Off by default. With IRONSHELL_RECORD=1, each top-level evaluation appends one JSON line to record.jsonl in the session directory (IRONSHELL_SESSION_DIR, or the per-project cache directory). Nothing is sent anywhere. Each line holds a version, a timestamp, a per-process sequence number, the surface (c, file, repl, api, sh), whether agent mode was on, the names of the builtins called at the top level, a 64-bit FNV-1a hash of the source, the duration, and on failure the error code, whether it is retryable, and whether it was a refusal. Outputs and argument values are not stored.

Each Agent API evaluation is one attempt: eval, call, pipeline, and their streamed and WebSocket forms. A pipeline is recorded as the IronShell source its steps compile to. A POSIX-subset script (ish -b, --bash input, and .sh files it runs natively) has surface sh. Its heads are the first word of each command, or an empty string when that word is not a literal. Its ok means exit status 0, and a non-zero status has no code, because the script’s own exit is not an IronShell failure. A failure that a try { } catch { } handles is not an attempt, so it is not recorded; only a failure that leaves the evaluation is.

IRONSHELL_RECORD=full also stores the source text in a cmd field. Use it only when that text is safe to keep, since it can contain secrets.

record_summary() reads the current session’s file and reports attempts, failures, refusals, failures by code, retries, recoveries and first-try successes. Any other value of the variable records nothing.

Setting Environment Variables

In your shell config (.bashrc, .zshrc, etc.):

export OPENAI_API_KEY="sk-your-key-here"
export IRONSHELL_AI="openai"
export AGENT_ALLOW_CMDS="ls,cat,grep,find,curl,http_get"

Or in IronShell:

env_set("OPENAI_API_KEY", "sk-your-key-here")

AI Provider Setup

IRONSHELL_AI chooses the backend that ai() uses. The [ai] keys in config.toml do not choose it. Set the key variable for the provider, then select the provider with IRONSHELL_AI. IRONSHELL_AI=<name>:<model> also sets the model for the providers listed below.

OpenAI

export OPENAI_API_KEY="sk-..."
export OPENAI_MODEL="gpt-4o"   # optional

With IRONSHELL_AI=openai, the model is OPENAI_MODEL, or gpt-4o-mini when that is unset.

Anthropic (Claude)

export ANTHROPIC_API_KEY="sk-ant-..."

With IRONSHELL_AI=anthropic (or claude) the model is claude-sonnet-4-20250514. No variable changes it. Use IRONSHELL_AI=anthropic:<model> to choose another model.

Google (Gemini)

export GOOGLE_API_KEY="AIza..."

With IRONSHELL_AI=google (or gemini) the model is gemini-2.5-flash. Use IRONSHELL_AI=google:<model> to choose another model.

Local Models (Ollama)

1. Install Ollama: https://ollama.ai
2. Pull a model: ollama pull llama3
3. Use in IronShell:

IRONSHELL_AI=ollama ish -c 'ai("Hello")'

OLLAMA_URL sets the server (default http://localhost:11434), and OLLAMA_MODEL sets the model (default llama3).

Other providers

Multiple Providers

ai() takes no model argument. Choose the provider per run with IRONSHELL_AI:

IRONSHELL_AI=openai ish -c 'ai("Query")'
IRONSHELL_AI=ollama ish -c 'ai("Query")'
IRONSHELL_AI=openrouter ish -c 'ai("Query")'

Model Storage

AI model files and their index are stored in an ai-models directory, not in the IronShell data directory. IRONSHELL_DATA_HOME does not move them.

• Data directory (models, metadata, cache, index): $XDG_DATA_HOME/ai-models if XDG_DATA_HOME is set, else $HOME/.local/share/ai-models if HOME is set, else %APPDATA%\ai-models.
• Config directory (config.toml, providers.toml, aliases.toml): $XDG_CONFIG_HOME/ai-models, else $HOME/.config/ai-models, else %APPDATA%\ai-models.

Inside the data directory:

• models/gguf, models/safetensors, models/pytorch and models/onnx hold the model files, one directory per format.
• metadata/ holds model metadata.
• cache/ holds temporary files and downloads.
• index.json is the model index.

The storage section of the ai-models config.toml can set custom_data_dir and custom_config_dir to use other directories. It can also set max_cache_size_gb and auto_cleanup_days. The same file holds the [server], [providers], [security] and [logging] sections for the model API. IRONSHELL_MODEL_DIR adds one more directory that is scanned for local models.

Command-Line Options

ish [OPTIONS] [FILE]
ish <SUBCOMMAND>

With no file, no -c and no subcommand, ish starts the REPL.

Subcommands:

ish agent serve listens on port 3002 by default, and ish ai serve on port 8080. The API token can come from IRONSHELL_API_TOKEN instead of --token, which keeps it out of the process list.

Startup Scripts

IronShell does not run a startup script. config_path() reports the path of init.ish in the config directory, but nothing executes that file. No code reads login.ish.