Configuration

Iris reads configuration from /iris/.env (written by bootstrap) and CLI flags (--provider, --model, --sandbox, --transport, --api-port). Flags override env vars.

Environment variables

Models and providers

The runtime loads provider endpoints and model definitions from <workspace>/models.json (generated from data/models.json.template at bootstrap). Anthropic and OpenAI work out of the box; custom endpoints (Azure AI Foundry, DeepSeek, Mistral, AWS Bedrock) are defined in the template. Switch with:

IRIS_PROVIDER=anthropic
IRIS_MODEL=claude-sonnet-4-5

For Azure AI Foundry (azure-foundry), bootstrap asks for the bare account name (e.g. my-account-eastus2), not the full endpoint URL. Pasted URLs or hostnames are trimmed automatically, and the generated baseUrl is validated — bootstrap aborts on a malformed hostname and warns if it doesn't resolve in DNS. Its Kimi-K2.5 / Kimi-K2.6 entries declare "input": ["text", "image"] — both are natively multimodal.

Each model entry's "input" array is a capability declaration, not a hint: pi-ai strips image content out of the request for any model that doesn't list "image", silently on the wire. Iris now catches this at her end too — an image attachment sent to a text-only model is diverted into a <dropped_image_attachments> note in the prompt (and a logged warning) instead of being sent and vanishing, and the read tool reports the same file as unreadable rather than claiming success. If a model here does accept images but a Slack/Telegram photo isn't getting through, check "input" for that model id first.

Separately, "is this attachment an image" is decided from the file's actual content (magic-byte sniffing), not its filename or extension — a Telegram document with no filename, or any attachment with a missing/wrong extension, is still recognized correctly. If "input" includes "image" and an attachment still isn't picked up, it likely isn't a supported format (jpeg, png, gif, webp).

An image over 2000px on its longest edge or 4.5MB once base64-encoded is downscaled before it's sent — an unresized phone photo can otherwise exceed a provider's per-image payload limit and fail the whole turn. This is automatic and has no env var to tune; a decode failure just falls back to sending the original size as-is. An animated GIF or WebP over those limits is sent as-is rather than resized, to avoid silently collapsing it to a single still frame.

A PDF attachment is listed in the prompt like any other non-image file; the read tool then extracts its text layer via the core-shipped pdf-text read handler (pdftotext from poppler-utils, installed by bootstrap.sh) rather than handing the model raw binary. A scanned or image-only PDF has no text layer and reads back empty — there's no OCR fallback in core, so a photo of a document should be sent as an image instead, or an overlay can add its own OCR-capable handler.

The openai provider defaults to gpt-5.6-luna (gpt-5.4-mini and gpt-5.6-terra are also available) and uses pi-ai's openai-responses module, not openai-completions — these models 400 on /v1/chat/completions when tool calls are present unless reasoning_effort is explicitly "none", which openai-completions has no way to force. Do not switch it back to openai-completions.

DeepSeek (deepseek) and Mistral (mistral, including Devstral) need only an API key — both go through pi-ai's openai-completions provider module, since Mistral's /v1/chat/completions endpoint is OpenAI-compatible and pi-ai's native mistral provider module hangs indefinitely on every call (see the Fixed entry in iris-runtime/CHANGELOG.md — do not switch Mistral's api back to "mistral"). Both ship ready-to-use model entries in the template (deepseek-chat / deepseek-reasoner, devstral-medium-latest / mistral-large-latest / mistral-medium-latest). mistral-medium-latest (Mistral Medium 3.5 — 256k context window, text+image input) is the largest-context model in the Mistral lineup; devstral-medium-latest and mistral-large-latest remain selectable.

For any other OpenAI-compatible endpoint (Kimi/Moonshot direct, a self-hosted vLLM/Ollama gateway, etc.), pick custom — bootstrap asks for a short provider name (used as the models.json key), the base URL, the API key, and the exact model id the endpoint expects, and writes a fresh openai-completions provider block. To add one without bootstrap, add a block by hand — see data/README.md for the shape.

azure-foundry was named foundry-e2 before this repo supported more than one custom provider; the name was a leftover from its original eastus2 deployment. Bootstrap migrates IRIS_PROVIDER=foundry-e2 and the FOUNDRY_E2_KEY/FOUNDRY-E2-KEY secret automatically on re-run, but a hand-edited models.json needs its foundry-e2 key renamed manually.

MCP servers

External toolsets connect via <workspace>/meta/mcp.json (optional, hot-reloaded per message; secrets referenced as ${VAR} from .env) — see MCP Servers.

Internal API security

The internal API binds to loopback by default. If sub-agent containers reach Iris via the Docker gateway (172.18.0.1:3000), set IRIS_API_HOST=0.0.0.0 and IRIS_API_TOKEN — never expose the API beyond loopback without a token. Iris logs a warning at startup if you do.

LLM resilience

Two mechanisms keep long-running channels healthy:

• Retry with backoff — failed LLM calls (429, timeout, connection reset) retry up to IRIS_LLM_MAX_RETRIES times with jittered exponential backoff, posting a visible _Retrying (n/3)..._ notice.
• Auto-compaction — before each prompt, if the estimated context exceeds IRIS_COMPACT_THRESHOLD (default 70%) of the model window, Iris summarises older history down toward IRIS_COMPACT_TARGET (up to 3 passes). This is a char-count estimate over the system prompt and message history computed before the new turn's message (and any image attachments) is appended, so it can't see an oversized attachment in the turn that introduces it — the post-run check at ≥70% real usage (hardcoded, not env-configurable) is the backstop that catches that case, using actual token counts from the provider's response.

Prompt caching

Anthropic and Bedrock cache the prompt on a strict byte-for-byte prefix match: any change anywhere in the system prompt invalidates the entire cached prefix (tools + system + full message history) for that turn. The system prompt is kept fully static across turns for a given channel and skill set — MEMORY.md contents and live MCP server connection status, both of which change turn to turn, are prepended to the current turn's user message instead (visible as a <dynamic_context> block in last_prompt.jsonl), after the cached history, where their churn doesn't invalidate anything. The Slack/Telegram channel/user directory embedded in the system prompt is also sorted by id before rendering, rather than left in Map insertion order — insertion order reorders every time a new user or channel is discovered, which would invalidate the cache even though nothing about the directory's actual content changed.

Iris's per-channel Agent is constructed with sessionId set to the channel id. Anthropic and Bedrock ignore it — they cache off explicit cache_control breakpoints — but pi-ai's openai-responses provider forwards it as prompt_cache_key, and Mistral's native provider uses it for the x-affinity header (KV-cache prefix affinity). Channel id is a stable, natural session boundary since each channel already gets its own long-lived runner and message history.