FAQ
General
What is IronShell?
IronShell is a next-generation shell written in Rust that combines typed functional programming with multimodal AI capabilities. Unlike traditional shells that pass raw text between commands, IronShell uses structured data types (records, arrays, tables) throughout its pipeline system.
How is IronShell different from Bash/Zsh?
| Feature | Bash/Zsh | IronShell |
|---|---|---|
| Data model | Raw text | Typed values (Int, Record, Array, …) |
| Pipelines | Text streams | Structured data flow |
| Functions | String-based | Typed lambdas with inference |
| AI | None | Built-in LLM, agents, RAG |
| Pattern matching | Case statements | match expressions |
| Error handling | Exit codes | Result types with context |
Can I use IronShell as my daily driver?
IronShell is under active development. It’s excellent for data processing, AI automation, and scripting. For interactive daily use, you may want to keep your current shell available while adopting IronShell incrementally.
How do I run Bash commands in IronShell?
Use the sh builtin:
sh "git status"
sh "docker ps"
Language
Why typed pipelines?
Typed pipelines eliminate an entire class of bugs. When ls returns an array of records with known fields, where, map, and sort_by can validate their arguments at parse time rather than failing silently at runtime.
Does IronShell support loops?
IronShell favors functional iteration via map, each, reduce, and where. Recursion is supported for looping patterns:
let countdown = fn(n) => if n > 0 { echo n; countdown(n - 1) } else { echo "done" }
countdown 5
What is fn(x) => expr?
This is a lambda (anonymous function). Lambdas are first-class values — they can be stored in variables, passed to builtins, and returned from functions:
let double = fn(x) => x * 2
[1,2,3] | map(double) # [2, 4, 6]
AI
Which AI providers are supported?
IronShell supports six providers via model URIs:
openai:gpt-4o— OpenAIollama:llama3— Local Ollamacompat:mixtral— OpenAI-compatible APIstgi:model— HuggingFace Text Generation Inferencevllm:model— vLLM servingllamacpp:model— llama.cpp server
Do I need an API key?
For cloud providers (OpenAI), yes — set OPENAI_API_KEY. For local providers (Ollama, llama.cpp), no API key is needed.
How do agents work?
Agents use a ReAct (Reason + Act) loop: they think about the task, choose a tool, execute it, observe the result, and repeat until the goal is met:
agent {
goal: "Find the largest file in the current directory",
tools: ["ls", "sort_by"],
max_steps: 5
}
What is a swarm?
A swarm is a group of AI agents that collaborate on a task. A coordinator routes subtasks to specialized agents, and they share state via a blackboard:
swarm {
goal: "Analyze this project",
tools: ["ls", "cat", "grep"],
max_steps: 20
}
TUI
How do I launch the TUI?
ish tui
What are the TUI tabs?
- Chat — AI conversation interface
- Agent Swarm — Monitor multi-agent collaboration
- Media Browser — View images, audio, video
- Settings — Configure providers and appearance
- Distributed — Manage cluster nodes
- Reasoning — Advanced chain-of-thought display
- Search — Search chat history
How do I switch tabs?
Press Tab and Shift+Tab to cycle through tabs, or press 1–7 in Normal mode.
Troubleshooting
cargo build fails with OpenSSL errors
Install OpenSSL development headers:
# Ubuntu/Debian
sudo apt install libssl-dev pkg-config
# macOS
brew install openssl
AI commands return “no provider configured”
Set the provider environment variable:
export IRONSHELL_AI=openai
export OPENAI_API_KEY=sk-...
Tests fail with “connection refused”
Some tests require a running Ollama instance or API keys. Tests that need external services will skip gracefully if the required environment is not available.
TUI looks broken
Ensure your terminal supports 256 colors and Unicode. Recommended terminals: Windows Terminal, iTerm2, Alacritty, kitty.