Environment variables

Set them in the environment or in a .env file the CLI and the IRIS API read at start.

• Applies: when a change takes effect (the next call, the next scheduled run, or a restart).
• Guarded: the web console asks the owner to confirm a change.
• On/off settings take 1/true/yes/on and 0/false/no/off.

Stable settings

What an install of iris-harness[email] needs: the settings the getting-started pages, the email guide and iris doctor name. They are part of the stable API: a name or a default changes only after a deprecation cycle. src/iris_harness/sdk/stable_tier.yaml lists them.

Variable	Kind	Default	Applies	Description
IRIS_AUTH_SECRET	secret		next call	Shared bearer secret every request to the IRIS API, the governor and the channel gateway must present, except their liveness probes (a paired device presents its own token instead); unset or blank, those services refuse every such request rather than run open. The learning eval sandbox forwards it (default 'eval-sandbox') into its container. Guarded.
IRIS_API_HOST	url	127.0.0.1	next call	Host iris serve binds the IRIS API to (as scripts/start_iris.sh binds every service), and the host health checks probe the local services on and the model inventory queries Ollama's /api/tags on.
IRIS_API_PORT	url	8003	restart	Port iris serve binds the IRIS API to, and the port the health watch probes for its /healthz endpoint (default 8003).
IRIS_API_URL	url	http://localhost:8003	restart	Base URL the CLI commands and the channel gateway use to reach the IRIS API (CLI defaults vary between http://localhost:8003 and http://127.0.0.1:8003).
IRIS_PUBLIC_URL	url		next call	Absolute base URL the web console is reached at (https://). Its host is one the HTTP services answer to (the Host-header guard), and it is the base of the links IRIS sends out (an OAuth callback, the morning digest's Telegram buttons); empty answers to the built-in names only and sends no such links.
IRIS_ALLOWED_HOSTS	list		restart	Comma-separated host names (host, host:port or a URL) the HTTP services answer to besides the built-in ones (loopback, testserver, the compose service names, this machine's hostname, the host of IRIS_PUBLIC_URL and their short names); any other Host is refused with 400 (DNS rebinding). An IP literal is always accepted. '' turns the check off. Guarded.*
IRIS_HOME	path	~/.iris	restart	Relocates the identity tree, plugin home, session logs and (when set) the governance data/config dirs.
IRIS_VAULT_MASTER_KEY	secret		restart	Fernet master key for the credential vault and the file vault, used instead of the OS keyring. Guarded.
IRIS_PROFILE	str	default	restart	Selects which shipped profile (config/profiles/.yaml) decides which plugins mount, in what order and with what trust. Unset, IRIS runs default, or email when the email plugins are installed. Guarded.
IRIS_DEMO_HOME	path		next call	Where iris email demo keeps its own isolated IRIS home (default ~/.iris-demo); never the owner's profile.
IRIS_TZ	str	UTC	restart	The owner's IANA time zone (e.g. America/Chicago). The morning digest's time, reminders and schedules are read in it; the Docker Compose files also set the container clock (TZ) from it. Unset or not a zone name means UTC.
IRIS_EMAIL_JUDGE	bool	on	next run	When on (default), the email judge sorts each new non-promo email into Bill, Event, Needs reply, FYI or Unsure three times a day, on a local model only. New email stays hidden until it is judged, so off means new email waits and stays hidden.
IRIS_EMAIL_JUDGE_LABELS	bool	on	next run	When on (default), each judged email gets one IRIS/* label in Gmail (never archived, never marked read); off keeps the judgments in IRIS only.
IRIS_EMAIL_JUDGE_UNSURE_BELOW	float	0.7	next run	A judgment less sure than this is filed as Unsure and asked on an Action Center card.

Third-party model backends

Not IRIS_*, so outside the settings catalog's scope -- the local-model backends' own address variables, read wherever the harness talks to them.

Variable	Default	Description
OLLAMA_BASE_URL	http://localhost:11434	Ollama's base URL (a trailing /v1 is accepted and trimmed). Set it to move the local-model backend to another box -- the cloud harness reaches the Mac's Ollama over the tailnet this way.
LM_STUDIO_BASE_URL	http://localhost:1234	LM Studio's base URL, shared with the LLM failover proxy -- told apart by port (the proxy's IRIS_PROXY_PORT, default 4000, vs. LM Studio's 1234).

Every other setting

The full catalog of the email profile (not stable)

Every IRIS_* setting the install reads, from the settings catalog: the core's (src/iris_harness/foundation/settings/catalog.yaml) and each plugin's in the email profile (its manifest's settings:). A test fails when the code reads an IRIS_* name no catalog declares. The stable settings above are listed again here, marked Stable.

These are configuration, not part of the stable API: a name or a default may change in a 0.x release, and the release notes say so.

From core

Variable	Kind	Default	Applies	Description
IRIS_ACTIVITY_WORKERS	int	1	restart	Sets how many worker threads the background ActivityRunner uses (minimum 1).
IRIS_ADAPTIVE_TIERS	bool	off	restart	When on, the tier router's ResourceGovernor downshifts large local model tiers under host pressure (RAM, CPU load, thermal throttling); skipped entirely if IRIS_DISABLE_ARBITER is set.
IRIS_AGENTIC_CORE_ENABLED	enum	1	restart	Selects the AgenticCore governed loop rollout: 0/false/no/off turns it off, 'shadow' runs it in shadow, anything else (default) turns it on.
IRIS_AGENTIC_CORE_P4	bool	off	restart	When on, routes the calendar and planner intents through the one governed agentic loop (requires the base loop rollout on/shadow).
IRIS_AGENT_SELF_MANAGEMENT	bool	off	next call	Adds the ADR-0086 self-management ReAct tools (introspect the agent's own brain, one of which compacts the conversation) to each turn's tool loop.
IRIS_ALLOWED_HOSTS	list		restart	Comma-separated host names (host, host:port or a URL) the HTTP services answer to besides the built-in ones (loopback, testserver, the compose service names, this machine's hostname, the host of IRIS_PUBLIC_URL and their short names); any other Host is refused with 400 (DNS rebinding). An IP literal is always accepted. '' turns the check off. Guarded. Stable.*
IRIS_API_HOST	url	127.0.0.1	next call	Host iris serve binds the IRIS API to (as scripts/start_iris.sh binds every service), and the host health checks probe the local services on and the model inventory queries Ollama's /api/tags on. Stable.
IRIS_API_PORT	url	8003	restart	Port iris serve binds the IRIS API to, and the port the health watch probes for its /healthz endpoint (default 8003). Stable.
IRIS_API_URL	url	http://localhost:8003	restart	Base URL the CLI commands and the channel gateway use to reach the IRIS API (CLI defaults vary between http://localhost:8003 and http://127.0.0.1:8003). Stable.
IRIS_AUTH_SECRET	secret		next call	Shared bearer secret every request to the IRIS API, the governor and the channel gateway must present, except their liveness probes (a paired device presents its own token instead); unset or blank, those services refuse every such request rather than run open. The learning eval sandbox forwards it (default 'eval-sandbox') into its container. Guarded. Stable.
IRIS_BEHAVIOR_BROAD_INTENTS	list	general,system,chat,other	restart	Comma-separated intents treated as catch-all when matching behavior files, so they get the lower broad-intent weight instead of the full intent weight.
IRIS_BEHAVIOR_BROAD_INTENT_WEIGHT	float	0.5	restart	Sets the relevance weight a catch-all intent (general, system, chat, other) contributes when matching stored behaviors to a turn.
IRIS_BEHAVIOR_INTENT_WEIGHT	float	2.0	restart	Sets the relevance weight a behavior file earns when one of its specific match_intents matches the turn's intent.
IRIS_BEHAVIOR_KEYWORD_WEIGHT	float	1.0	restart	Sets the relevance weight a keyword match contributes when deciding which behavior files to inject into a turn.
IRIS_BEHAVIOR_MATCH_THRESHOLD	float	2.0	restart	Minimum relevance score the best-matching behavior must reach in match_behavior before it is used for a turn; below it no behavior is selected.
IRIS_BEHAVIOR_MINER	bool	off	restart	Turns on the local-tier behavior-pattern miner (digital-twin layer 1) that proposes behaviors for user approval; this env value is the default the learning console reverts to on restart.
IRIS_CHANNEL_GATEWAY_PORT	url	8006	restart	Port the channel gateway listens on (launcher) and that the health check probes; default 8006.
IRIS_CHANNEL_GATEWAY_TELEGRAM_ENABLED	bool	on	restart	When on, the channel gateway runs the Telegram long-poller; when off (and IRIS_RUNTIME_TELEGRAM_POLLER_ENABLED unset) the runtime's own Telegram poller starts instead. Guarded.
IRIS_CHANNEL_GATEWAY_TRACING_ENABLED	bool	off	restart	Sets up OpenTelemetry tracing for the channel gateway service at startup; spans export only when an OTLP endpoint is set (OTEL_EXPORTER_OTLP_ENDPOINT).
IRIS_COMPACTION_KEEP_RECENT	int	10	restart	Sets how many of the most recent conversation turns are kept verbatim when the conversation is compacted.
IRIS_COMPACTION_RATIO	float	0.8	restart	Fraction of the compactor's token budget the running history must reach before it is compacted (values outside 0-1 fall back to 0.8); also sizes the kept-verbatim window.
IRIS_COMPACTION_THRESHOLD	int	20	restart	Turn-count floor at which a conversation is compacted into a summary (with the token budget also able to trigger compaction).
IRIS_COMPACTION_TOKEN_BUDGET	int		restart	Sets the token budget at which the conversation compactor summarises older turns; unset uses a budget derived from the communication tier's context window.
IRIS_CONFIG_DIR	path		restart	Points the harness at the directory holding its YAML config (memory, skills, profiles, governance, finance categories, plugin dump); cached after first read. Unset resolves, in order, to the checkout's config/ when running from a checkout, else the defaults shipped inside the installed package (foundation/paths.py config_dir).
IRIS_CRYSTALLIZE_PREFLIGHT	bool	off	restart	When on, each newly crystallized skill proposal is replayed through an isolated eval runtime and quarantined as preflight_failed if it fails quality.
IRIS_CURATOR_ESCALATION	bool	off	restart	When truthy, builds the escalation judge that grades answers and (in enforce mode) re-runs capability gaps at a stronger tier; the env can only turn it on, config/escalation.yaml enabled:true also turns it on.
IRIS_CURATOR_ESCALATION_CLOUD	bool	off	restart	When on (or cloud.allow in escalation.yaml), the escalation judge may escalate a turn to a cloud tier for content classified as eligible (default only 'public'; 'secret' never). Guarded.
IRIS_CURATOR_ESCALATION_MODE	enum	shadow	restart	Overrides the escalation judge mode from config/escalation.yaml: 'shadow' only diagnoses and records, 'enforce' lets the judge act (escalate) when it is enabled; other values are ignored. Guarded.
IRIS_CURATOR_ESCALATION_PRIORS	bool	off	restart	When on (or escalation.yaml priors.enabled), applies start-tier priors mined from escalation history to the router instead of running them in shadow. Guarded.
IRIS_CURATOR_FAITHFULNESS_LLM	bool	off	restart	Builds an LLM faithfulness judge for the ResponseCurator's strict mode so answers are checked against their sources.
IRIS_CURATOR_GROUNDING_LLM	bool	off	restart	When on, an LLM grounding judge client is built for the curator to check responses that carry retrieved context.
IRIS_CURATOR_LEAK_JUDGE	bool	on	restart	When not set to 0/false/no/off, builds an LLM leak judge that may clear responses the deterministic dump-phrase guard flagged; when off, that guard's halt stands. Guarded.
IRIS_CURATOR_OUTPUT_SAFETY	bool	off	restart	When on, builds the Llama Guard 3 output-safety judge the curator uses to check responses (shadow/warn-only unless enforce categories are configured). Guarded.
IRIS_CURATOR_OUTPUT_SAFETY_TIMEOUT_S	float	12.0	restart	Per-call time budget in seconds (clamped 1-60) for the output-safety guard, which fails open on timeout. Guarded.
IRIS_DATA_DIR	path	data	restart	Relocates every local data store (memory.db, chroma, tasks.db, finance and email stores, etc.).
IRIS_DEPLOYMENT_LABEL	str		next call	Sets the deployment name returned to the web console, which shows it as a badge; empty when unset.
IRIS_DISABLE_ARBITER	bool	off	restart	Any non-empty value (even 0) skips attaching the Ollama arbiter ResourceGovernor to the tier router.
IRIS_DISABLE_EXTERNAL_WRITES	bool	off	next call	When set to 1, calendar writes stay local (no Apple or Google Calendar providers are registered); the playground and learning preflight set it for their sandboxes.
IRIS_DISABLE_WARMUP	bool	off	restart	When set to any non-empty value, skips the background warm-up calls that pre-load the router and executor models at startup (the playground and eval harness also set it for their own runtimes).
IRIS_EMBED_BACKEND	enum	onnx	next call	Chooses the embedding backend for corpus embeddings: 'onnx' (the shared ONNX MiniLM, default model only) or 'sentence-transformers' (needs the optional ML extra); any other value raises an error.
IRIS_ENABLE_COPILOT_BACKEND	bool	off	restart	Opts in to the GitHub Copilot cloud LLM provider (providers report available when set; copilot_auth requires exactly '1' before any network call); errors.py:20 only matches it in an error message. Guarded.
IRIS_EVALUATOR_PORT	url	8090	restart	Port where the remote governance evaluator sidecar is probed for /healthz.
IRIS_EVAL_SANDBOX	enum	effect	restart	Chooses how skill-proposal pre-flight replays are contained: effect (neutralize side effects), docker (full container), or off (no containment). Guarded.
IRIS_EXPORT_DIR	path	~/.iris/exports	restart	The one folder the web API's POST /memory/export may write under; a request names a sub-folder of it, never a path. Point it at an Obsidian vault's parent to export straight into one. Created owner-only (0700). The CLI (iris memory export --to PATH) is not limited by it.
IRIS_FACT_EXTRACTION_MODE	enum	llm	next call	Set to regex to extract user facts with regex patterns instead of the LLM extractor; any other value uses the LLM.
IRIS_FACT_HISTORY_RETENTION_DAYS	int	180	next call	Sets the default age in days used by the iris facts retention command when no --older-than value is given.
IRIS_FAKE_MODEL_SCRIPT	path		next call	The YAML script the scripted fake model (provider fake) answers from when no script was installed in-process (iris_harness.testing does that).
IRIS_FEEDBACK_CAPTURE	bool	off	next call	When on, the API reports feedback_capture=true so the web UI shows the thumbs up/down answer-feedback control.
IRIS_FEEDBACK_CLARIFY	bool	off	next call	When exactly '1', appends one gentle invitation to refine to an answer when the judge or router signals uncertainty (never on a confident answer).
IRIS_FILEMANAGER_AGENT	bool	off	restart	When on, registers a first-class filemanager agent to answer the files intent (requires the base loop rollout on/shadow).
IRIS_GENERAL_TOOL_MAX_TURNS	int	4	next call	Base number of tool turns (bounded 1-128) the general agent loop may take before stopping; the cap var lifts it for continuation/auth-related queries.
IRIS_GENERAL_TOOL_MAX_TURNS_CAP	int	8	next call	Upper bound (clamped 1-128) on tool-call turns in the general tool loop, including the adaptive bump.
IRIS_GOVERNANCE_ALLOWED_TOOLS	list		restart	Comma-separated exact tool names the governance kernel allows; unset means no allowlist (all tools). Guarded.
IRIS_GOVERNANCE_APPROVALS_ENABLED	bool	on	restart	When on, require_approval verdicts enqueue an approval and notify channels; when off, halts are advisory only. Guarded.
IRIS_GOVERNANCE_AUDIT_DB_PATH	path		restart	Overrides where the governance audit ledger database is stored (default: governance data dir/audit.db).
IRIS_GOVERNANCE_BLOCKED_TOOLS	list		restart	Comma-separated tool names the governance kernel blocks. Guarded.
IRIS_GOVERNANCE_COMMAND_SANDBOX	bool	on	restart	Registers the governance CommandSandbox (on by default); 0/false/no/off disables it without dropping the rest of the kernel. Guarded.
IRIS_GOVERNANCE_CONFIRM_ONCE_TOOLS	list		restart	Comma-separated tool names that must ask for confirmation once, added on top of each tool's own declaration; unset or 'none' adds nothing. Guarded.
IRIS_GOVERNANCE_COST_ENFORCE	bool	on	restart	When on, a call that would pass the daily cost cap is refused; off only records spend. Guarded.
IRIS_GOVERNANCE_COST_LEDGER_DB_PATH	path		restart	Path of the SQLite cost ledger the cost limiter writes and the cost summary reads; unset uses CostStore's default location.
IRIS_GOVERNANCE_COST_LIMITER_ENABLED	bool	off	restart	When truthy, registers the cost limiter, which records LLM spend and (with cost enforce on) refuses calls past the daily cap. Guarded.
IRIS_GOVERNANCE_DAILY_COST_CAP_USD	float	5.0	restart	Daily spend cap in USD the cost limiter enforces when IRIS_GOVERNANCE_COST_LIMITER_ENABLED is on (unparseable values fall back to $5.00). Guarded.
IRIS_GOVERNANCE_DISPLAY_MASK	bool	on	next call	Masks email addresses in displayed text and streams (on unless explicitly turned off); the audit ledger keeps originals. Guarded.
IRIS_GOVERNANCE_DRIFT_EXEMPTIONS_DB_PATH	path		restart	Overrides where approved goal-drift exemptions are stored; unset uses the governance data dir drift_exemptions.db. Guarded.
IRIS_GOVERNANCE_ENABLED	bool	on	restart	Enables the governance kernel (secure by default; only an explicit 0/false/no/off disables it). Guarded.
IRIS_GOVERNANCE_EVALUATOR_MODE	enum	local	restart	Set to remote to have the kernel use the remote evaluator sidecar (IRIS_GOVERNANCE_EVALUATOR_URL) instead of the in-process evaluator registry; health checks then also probe the sidecar. Guarded.
IRIS_GOVERNANCE_EVALUATOR_TIMEOUT_S	float	5.0	restart	Sets the timeout in seconds for calls to the remote governance evaluator; on failure local-tier runs fail open and cloud-tier runs fail closed. Guarded.
IRIS_GOVERNANCE_EVALUATOR_URL	url	http://127.0.0.1:8090	restart	Base URL of the remote governance evaluator used when evaluator mode is 'remote'; the CLI evaluator commands also use it. Guarded.
IRIS_GOVERNANCE_EXTERNAL_CONTENT_FLOOR	bool	on	restart	On by default. Text a tool, capability or MCP server declares content: external (a web page, a feed, an email, a retrieved document) reaches the model inside an untrusted-content envelope, and a small set of deterministic patterns (instruction overrides, chat-template and tool-call syntax, exfiltration instructions, hidden characters) is redacted with a ledger row. No model, no weights, no network. Plain boolean: on is unset, blank, 1, true, yes or on; off is only 0, false, no or off (anything else stays on). The model guard (IRIS_GOVERNANCE_PROMPT_GUARD) is separate and stays opt-in. Guarded.
IRIS_GOVERNANCE_FS_JAIL	bool	on	restart	Registers the governance FSJail (on by default); 0/false/no/off disables it without dropping the rest of the kernel. Guarded.
IRIS_GOVERNANCE_GOAL_DRIFT_MAX_DISTANCE	float		restart	Sets the goal_drift signal's max distance (0.0-2.0) before a turn is flagged; unset keeps the signal default of 0.90. Guarded.
IRIS_GOVERNANCE_INPUT_SAFETY	bool	off	restart	When truthy, screens every user turn for hazards (self-harm, violence, ...) with the output guard's Llama Guard model before anything answers it, deterministic handlers included. Follows config/governance/threat-detection.yaml mode (shadow logs, enforce refuses). Guarded.
IRIS_GOVERNANCE_JUDGE_CLOUD_OPT_IN	bool	off	restart	Let judge_from_env's judge use tier_3 (cloud); production does not build that judge.
IRIS_GOVERNANCE_JUDGE_ENABLED	bool	off	next call	After every agent run that used tools, a background judge scores the trace and the answer for hallucination, goal alignment, tool misuse and danger, on the model IRIS_GOVERNANCE_JUDGE_TIER picks; a halt recommendation alerts your channels, the rest go to the audit log. Guarded.
IRIS_GOVERNANCE_JUDGE_MODEL_TIER	enum	tier_2	restart	Picked a governance tier label for the judge built by judge_from_env, which production does not use.
IRIS_GOVERNANCE_JUDGE_TIER	str	run	next call	Which model reviews a run: 'run' judges each run on the same route the run used (a run that stayed on local models is judged on local models); any tier name from llm_tiers.yaml (e.g. tier2, private, tier3), local or cloud, judges every run on that tier. An unknown name falls back to 'run'. Guarded.
IRIS_GOVERNANCE_JUDGE_TIMEOUT_S	float	30.0	next call	How long one post-run review may take before it is recorded as a judge failure (non-positive or invalid values fall back to 30).
IRIS_GOVERNANCE_LOOP_DETECT_ENABLED	bool	off	restart	When truthy, builds an embedder and registers the governance loop-detection signal; off by default. Guarded.
IRIS_GOVERNANCE_MCP_ALLOWLIST	bool	on	restart	When on, the MCP allowlist hook enforces mcp-servers.yaml governance; 0 disables the hook entirely. Guarded.
IRIS_GOVERNANCE_NETWORK_EGRESS	bool	on	restart	Enables the governance NetworkEgress control; 0/false/no/off disables it. Guarded.
IRIS_GOVERNANCE_OWNER_PII	enum	off	restart	Owner-PII masking across the guards (ADR-0125): off (default) or shadow, which audits what each guard would do with the owner's name, email, phone, address and handles and changes nothing (read it with iris governance pii-shadow). Any other value, enforce included, runs shadow with a startup warning; enforce arrives kind by kind in PR 5. Guarded.
IRIS_GOVERNANCE_PROMPT_GUARD	bool	off	restart	When truthy, installs the inbound and retrieved-content prompt-injection guard hooks using config/governance/threat-detection.yaml. Guarded.
IRIS_GOVERNANCE_REDACTION_ENABLED	bool	off	restart	When truthy, builds the vault store the governance kernel uses to redact stored secrets from content. Guarded.
IRIS_GOVERNANCE_SIDE_EFFECT_LEDGER	bool	on	restart	On (the default, the same as unset) the side-effect ledger (side_effects.db in the governance data dir, $IRIS_HOME/governance when IRIS_HOME is set, else ~/.local/share/iris) always covers the high-risk class. A destructive tool's or a pinned write's row is written before the call runs, and plain writes and reads leave no row and open no file; setting this to true or 1 does not widen that, use IRIS_GOVERNANCE_SIDE_EFFECT_LEDGER_ALL. Off denies every destructive tool and pinned write, since none may run without a durable record. Guarded.
IRIS_GOVERNANCE_SIDE_EFFECT_LEDGER_ALL	bool	off	restart	Only meaningful while IRIS_GOVERNANCE_SIDE_EFFECT_LEDGER is on. On also records every other non-read call's side effect after it runs (commits, pushes, file writes, sends), on top of the high-risk class the ledger always covers. Off (the default) records the high-risk class only. With the ledger off this has no effect and logs a warning. Before this setting existed, IRIS_GOVERNANCE_SIDE_EFFECT_LEDGER=1 meant this; it no longer does.
IRIS_GOVERNANCE_SIDE_EFFECT_LEDGER_DB_PATH	path		restart	SQLite path for the governance side-effect ledger; unset uses side_effects.db in the governance data dir ($IRIS_HOME/governance when IRIS_HOME is set, else ~/.local/share/iris).
IRIS_GOVERNANCE_TRUSTED_CLOUD_FOR	list		restart	Comma-separated data classes ('personal', 'internal') the egress gate lets reach cloud models; other values are dropped. Guarded.
IRIS_GOVERNANCE_VAULT_DB_PATH	path		restart	Overrides the database path of the vault used for secret redaction.
IRIS_GOVERNOR_AUDIT_DB	path		restart	Path of the governor service's audit database; unset uses the service's repo default.
IRIS_GOVERNOR_BASE_URL	url		restart	Where a deployment that runs the standalone governor service says it is (docker-compose sets it). When set, the health check expects the governor to answer; unset, a desktop install that never started it is not reported as broken.
IRIS_GOVERNOR_POLICY_PATH	path		restart	Path to the policy file the standalone governor service loads instead of the repository default. Guarded.
IRIS_GOVERNOR_PORT	url	8080	restart	Port the governor service listens on (launcher) and that the health check probes; default 8080.
IRIS_HEALTH_ENABLED	bool	on	next run	Master switch for the health subsystem; off makes the health heartbeat skip.
IRIS_HEALTH_NET_PROBE	bool	off	next run	When on, credential health checks make live network probes outside a manual refresh.
IRIS_HEALTH_WATCH_ENABLED	bool		restart	Overrides the enabled flag from config/health_watch.yaml (which defaults to true); a falsy value turns the connector health watcher off.
IRIS_HOME	path	~/.iris	restart	Relocates the identity tree, plugin home, session logs and (when set) the governance data/config dirs. Stable.
IRIS_INTENTION_ROLLUP	bool	off	restart	Turns on the local-tier intention-rollup analyst (digital-twin layer 3) that proposes rolled-up goals for approval; this env value is the default the learning console reverts to on restart.
IRIS_INTENT_ROUTER_SEMANTIC	bool	off	restart	When on, an embedding classifier becomes the primary intent router (deferring to keyword/LLM when unsure) and calendar create-intent uses it.
IRIS_INTENT_ROUTER_SEMANTIC_MARGIN	float	0.05	restart	How far the winning intent must beat the runner-up for the semantic intent classifier to decide instead of deferring.
IRIS_INTENT_ROUTER_SEMANTIC_THRESHOLD	float	0.42	restart	Sets the minimum similarity the semantic intent classifier needs to decide an intent itself (only used when IRIS_INTENT_ROUTER_SEMANTIC=1).
IRIS_INTERACTIVE_SESSION	bool	on	next call	When set to 0, approval requests are not prompted on the terminal even when stdin is a TTY.
IRIS_INTERCEPTS_CONFIG	path		restart	Path to the intercept chain YAML; when unset uses intercepts.yaml in the resolved config directory (IRIS_CONFIG_DIR, else the checkout's config/, else the packaged defaults).
IRIS_LEARNING_ANALYST	bool	off	restart	Turns on the local-tier agentic learning analyst that interprets learning telemetry into a report (never acts); this env value is the default the learning console reverts to on restart.
IRIS_LEARNING_CORRECTION_JUDGE	bool	off	restart	When on (or outcomes.yaml user_correction.enabled), spends a governed LLM call on turns that look like corrections to judge whether the prior answer was corrected.
IRIS_LESSON_CAPTURE_ENABLED	bool	on	restart	Enables capturing lessons into memory; 0/false/False disables it.
IRIS_LESSON_DOMAIN_ALLOW	list		restart	Comma-separated domains; when set, only lessons whose domain is in the list are captured/recalled.
IRIS_LESSON_DOMAIN_BLOCK	list		restart	Comma-separated lesson domains excluded when retrieving lessons for a turn.
IRIS_LESSON_TOP_K	int	3	restart	Default number of lessons LessonCapture retrieves (negative values clamp to 0; invalid falls back to 3).
IRIS_LLM_PROVIDER	str		restart	Puts every model tier on this provider, which must be declared in the providers block of llm_tiers.yaml; fake runs everything on the scripted fake model (tests and iris email demo), offline and deterministic.
IRIS_LOG_LEVEL	enum	INFO	restart	Sets the root logging level (e.g. DEBUG, INFO, WARNING); unknown names fall back to INFO.
IRIS_LOG_PROMPT_CAP	int	8192	next call	Most characters of each LLM prompt message written to the session log (the middle is cut beyond it). Raise it to capture whole ReAct prompts for a model bake-off; values below 8192 are ignored.
IRIS_MCP_KEYS_DIR	path	~/.config/iris/mcp-keys	next call	Directory where the mcp CLI keeps its signing keys.
IRIS_MCP_SERVERS_CONFIG_PATH	path	config/coding-agent/mcp-servers.yaml	restart	Path of the mcp-servers.yaml governance map used by the MCP allowlist hook; missing file runs the hook in degraded allow+warn mode. Guarded.
IRIS_MEMORY_MAX_PROFILE_CHARS	int	8000	restart	Maximum characters of the curated USER.md profile injected into the memory context.
IRIS_MEMORY_MIN_FACT_CONFIDENCE	float	0.35	restart	Facts below this confidence are dropped from memory recall; 0.0 stops dropping.
IRIS_MEMORY_RECALL_MAX_DISTANCE	float	1.45	restart	Relevance cutoff for cross-session recall and memory_search fact results; results farther than this distance are dropped.
IRIS_MEMORY_RECALL_MODE	enum	push	next call	How turns from OTHER conversations reach a prompt. push (default) puts up to 4 related turns in every prompt; pointer puts a one-line note naming up to 2 related conversations that recall_conversation can read on demand, and pushes the nearest 2 turns only when the message clearly refers back (config/memory/recall.yaml). Anything else is push. Switch back at any time.
IRIS_MEMORY_UNCERTAIN_BELOW	float	0.6	restart	Facts recalled with confidence below this value are kept but marked uncertain ('unconfirmed') in the prompt.
IRIS_MISSION_AUTOCREATE	bool	off	next call	When truthy, successful multi-step turns and recurring episodic patterns are proposed as pending missions awaiting approval.
IRIS_OBSERVABILITY_METRICS_ENABLED	bool	off	next call	When on, the /observability/llm-metrics endpoint returns an LLM metrics summary; when off it returns 404.
IRIS_OLLAMA_BREAKER	bool	on	next call	When on, the circuit breaker applies to local-provider LLM calls; 0/false/no/off disables it.
IRIS_OLLAMA_PORT	url	11434	next run	Port used to reach Ollama for its health probe and the local model inventory.
IRIS_OTEL_HTTPX_ENABLED	bool	on	restart	When on, instruments httpx calls for OpenTelemetry tracing (only while an OTLP endpoint is set).
IRIS_OTEL_LANGCHAIN_ENABLED	bool	on	restart	Enables OpenTelemetry instrumentation of LangChain while an OTLP endpoint is set.
IRIS_PLAYGROUND_DIR	path		next call	Directory holding playground scenario suites; unset uses playground/ in the resolved config directory (IRIS_CONFIG_DIR, else the checkout's config/, else the packaged defaults).
IRIS_PLUGINS_DISABLE	list		restart	Comma-separated plugin names removed from the active profile. Guarded.
IRIS_PLUGINS_ENABLE	list		restart	Comma-separated plugin names forced on over the profile. Guarded.
IRIS_PROFILE	str	default	restart	Selects which shipped profile (config/profiles/.yaml) decides which plugins mount, in what order and with what trust. Unset, IRIS runs default, or email when the email plugins are installed. Guarded. Stable.
IRIS_PROVIDERS_CONFIG	path	~/.iris/providers.json	restart	Path to the LLM providers JSON; in iris_code an empty value disables the global provider override.
IRIS_PROXY_PORT	url	4000	restart	Port an LLM failover proxy listens on, when the deployment runs one; the health checks also use it to tell the proxy from LM Studio.
IRIS_PUBLIC_URL	url		next call	Absolute base URL the web console is reached at (https://). Its host is one the HTTP services answer to (the Host-header guard), and it is the base of the links IRIS sends out (an OAuth callback, the morning digest's Telegram buttons); empty answers to the built-in names only and sends no such links. Stable.
IRIS_RAG_UPLOAD_DIR	path	<repo>/data/rag_uploads	restart	Directory where uploaded RAG documents are stored.
IRIS_REACT_ASK_USER	bool	on	restart	Lets the conversational ReAct loop pause and ask the user a question; 0/false/no/off disables the ask tool.
IRIS_REACT_HISTORY_TOKEN_BUDGET	int		restart	Overrides the token budget for the running ReAct transcript; unset, the harness loop derives it from the tier-2 context window and the email agent uses 3000.
IRIS_REACT_MAX_ITERATIONS	int	10	restart	Caps how many tool-use iterations the ReAct loops (general and email) run per turn.
IRIS_REACT_MEMORY_TOKEN_BUDGET	int		restart	Overrides the token budget for the memory block admitted into the ReAct loop; unset uses the context controller's window-derived budget.
IRIS_REACT_TIER_BUMP_TOOL_COUNT	int	6	next call	When a tier-1 intent faces more tools than this number (and governance is on), the ReAct loop borrows the multi-step (tier-2) routing intent.
IRIS_REACT_TIMEOUT_SECONDS	int	120	restart	Timeout in seconds for the ReAct agentic loop (general and email agents).
IRIS_REACT_TOOL_CAP	int	12	next call	Maximum number of tools shortlisted into the ReAct tool menu each turn.
IRIS_RECENT_TURNS_BUDGET_SHARE	float	0.45	restart	Sets the share of the memory token budget the live conversation transcript may fill.
IRIS_RESEARCH_AGENT	bool	off	restart	Registers the dedicated research persona and remaps the 'search' intent to it; off by default.
IRIS_RESTART_ON_REQUEST	bool	on	restart	Under a supervisor, whether this server exits when the app's Restart harness asks. A deployment whose governor owns the network namespace the other services share sets it off on the governor.
IRIS_ROUTINE_REFLECTION	bool	off	next run	When on, each routine-reflection heartbeat run posts approval requests proposing changes to failing/stale routines (never mutates a routine).
IRIS_RUNTIME_TELEGRAM_POLLER_ENABLED	bool	off	restart	When set, explicitly decides whether the runtime's own Telegram poller starts; unset defers to the inverse of IRIS_CHANNEL_GATEWAY_TELEGRAM_ENABLED. Guarded.
IRIS_SANDBOX_EGRESS_ALLOWLIST	list		next call	Comma-separated hosts the code sandbox may reach; unset uses the built-in default list (PyPI, GitHub, Yahoo quotes). Guarded.
IRIS_SANDBOX_PREFLIGHT	bool	off	next run	When on, promoted experiments are replayed through an isolated eval runtime under baseline vs variant and the verdict is stamped; the change is never applied.
IRIS_SANDBOX_RUNTIME	enum		restart	Overrides the code sandbox runtime with docker, gvisor or firecracker (otherwise config/governance/sandbox.yaml, default docker). Guarded.
IRIS_SEARCH_SYNTHESIS_MODEL	str	gpt-5-mini	restart	Copilot model used for cloud search synthesis when IRIS_SEARCH_SYNTHESIS_PROVIDER=copilot and IRIS_ENABLE_COPILOT_BACKEND is set. Guarded.
IRIS_SEARCH_SYNTHESIS_PROVIDER	enum		restart	Set to 'copilot' (with IRIS_ENABLE_COPILOT_BACKEND) to synthesize search results with a GitHub Copilot cloud model (default gpt-5-mini) instead of the local search tier. Guarded.
IRIS_SECRET_BACKEND	enum	keyring	next call	Chooses where secrets are stored: the OS keyring or the Fernet-encrypted vault. Guarded.
IRIS_SESSION_LOG_DIR	path	$IRIS_HOME/logs (~/.iris/logs)	restart	Directory where session logs are written.
IRIS_SESSION_MEMORY_MAX_SESSIONS	int	256	restart	How many conversations keep their live window in the server's memory; the least recently used beyond this are dropped and reload from the memory store on their next turn.
IRIS_SETTINGS_SIDECAR_CATALOGS	path		restart	Settings catalogs (YAML files separated by the path separator, each naming its owner) of processes the deployment runs beside the harness, such as an LLM proxy; the app lists their settings and leaves changing them to that process's environment.
IRIS_SKILL_HOTRELOAD	bool	off	restart	When truthy, watches the skills directory and reloads skills when their files change.
IRIS_SKILL_ROUTER_SEMANTIC	bool	on	restart	When on, routine authoring and briefing-section extraction use an embedding-based SemanticSkillRouter; off forces the legacy keyword scorer.
IRIS_SKILL_ROUTER_THRESHOLD	float	0.45	restart	Embedding-similarity threshold the semantic skill router uses to match a request to a skill (default 0.45 from semantic_router.py:29).
IRIS_SKILL_SYNTHESIS	bool	off	restart	When on, the crystallizer uses a local-tier LLM to synthesize skills instead of falling back to a scaffold.
IRIS_STANDING_INSTRUCTIONS	bool	on	next call	When on, a chat message that teaches a rule is saved as a behavior and honored on later matching turns.
IRIS_SUPERVISED	bool	off	restart	Set by a deployment whose supervisor restarts every server that exits (a compose file with restart policies, for example); only then may the app's Restart harness ask the servers to exit.
IRIS_SYNC_MEMORY_BLOCKING	bool	off	restart	When on, the startup memory-to-index sync runs inline before build_runtime returns instead of on a background thread.
IRIS_SYNC_WIKI_BLOCKING	bool	off	restart	When on (and wiki ingest is enabled), re-indexes wiki pages synchronously at startup instead of in a background thread.
IRIS_THREAT_DETECTION_CONFIG	path	config/governance/threat-detection.yaml	restart	Overrides the path of the threat-detection (prompt guard) YAML config. Guarded.
IRIS_TZ	str	UTC	restart	The owner's IANA time zone (e.g. America/Chicago). The morning digest's time, reminders and schedules are read in it; the Docker Compose files also set the container clock (TZ) from it. Unset or not a zone name means UTC. Stable.
IRIS_USER_ID	str	local	restart	User id under which LLM spend is recorded and summed against the daily cost cap. Guarded.
IRIS_VAULT_MASTER_KEY	secret		restart	Fernet master key for the credential vault and the file vault, used instead of the OS keyring. Guarded. Stable.
IRIS_VAULT_PASSPHRASE	secret		next call	Passphrase from which the encrypted-file vault key is derived (scrypt) when IRIS_SECRET_BACKEND=vault; unset uses a keychain-held key. Guarded.
IRIS_WEBUI_ALLOW_WRITES	bool	off	next call	Allows gated control writes from callers without a paired device (shared secret or no credentials); paired devices are judged by their own scope regardless. Guarded.
IRIS_WEBUI_DIST	path	/app/webui/dist	restart	Directory the API serves the built web UI from; without an index.html there the UI is not served.
IRIS_WEBUI_PORT	int	5181	next call	Port the setup wizard's closing "open the web UI" hint shows; it reads this to reflect a custom port mapping but does not itself change which port the web UI binds to.
IRIS_WEB_PUSH_SUBJECT	url	https://github.com/evarness-ai/iris-harness	next call	Contact subject (URL or mailto) sent in Web Push VAPID claims.
IRIS_WEB_PUSH_VAPID_PRIVATE_KEY	secret		next call	PEM EC private key used to sign web push requests instead of the generated key file; changing it breaks existing subscriptions. Guarded.
IRIS_WIKI_INGEST	bool	off	restart	When on, chat turns and classified emails are automatically ingested into wiki pages and pages are re-embedded at startup.

From plugin code_exec

Variable	Kind	Default	Applies	Description
IRIS_CODE_EXEC_MAX_ITERATIONS	int	8	next call	Sets the base number of loop iterations a code_exec task gets (bounded 1-128; the cap env is raised to match if lower).
IRIS_CODE_EXEC_MAX_ITERATIONS_CAP	int	14	next call	Sets the maximum iteration budget for a code_exec loop (clamped 1-128, never below IRIS_CODE_EXEC_MAX_ITERATIONS).

From plugin email_workflows

Variable	Kind	Default	Applies	Description
IRIS_DEMO_HOME	path		next call	Where iris email demo keeps its own isolated IRIS home (default ~/.iris-demo); never the owner's profile. Stable.
IRIS_EMAIL_DEFAULT_SENDER	str		next call	Names the connected mail account (address or account id) a new email is sent from when no sender is given; if it names an unconnected account the send is refused, and when unset the first account in sorted order is used.
IRIS_EMAIL_JUDGE	bool	on	next run	When on (default), the email judge sorts each new non-promo email into Bill, Event, Needs reply, FYI or Unsure three times a day, on a local model only. New email stays hidden until it is judged, so off means new email waits and stays hidden. Stable.
IRIS_EMAIL_JUDGE_LABELS	bool	on	next run	When on (default), each judged email gets one IRIS/ label in Gmail (never archived, never marked read); off keeps the judgments in IRIS only. Stable.*
IRIS_EMAIL_JUDGE_MAX	int	100	next run	The most emails the judge reads in one run; the rest wait, hidden, and are judged first next run.
IRIS_EMAIL_JUDGE_UNSURE_BELOW	float	0.7	next run	A judgment less sure than this is filed as Unsure and asked on an Action Center card. Stable.
IRIS_EMAIL_SEMANTIC_SEARCH	bool	on	restart	When on (default), the email tools search by meaning as well as by words, the index follows new mail, and a heartbeat fills in older mail in small batches; 0 turns it off.
IRIS_FOLLOWUP_ACTIONABLE_ROOTS	list		next call	Comma-separated email category roots that may create follow-up tasks; unset uses personal, work, finance, jobs, travel, community.

From plugin research

Variable	Kind	Default	Applies	Description
IRIS_REDIS_URL	url	redis://localhost:6379/0	restart	Redis URL for the research result cache when the Redis backend is selected.
IRIS_RESEARCH_CACHE	enum	sqlite	restart	Selects the research cache: sqlite (default), redis (falls back to sqlite), or off/none to disable.
IRIS_RESEARCH_CRAWLER	enum	trafilatura	next call	Selects the research page extraction backend: crawl4ai, otherwise trafilatura fetch-and-extract.
IRIS_RESEARCH_NEWS_SOURCES	path	plugins_builtin/research/news_sources.yaml	next call	Path of the YAML file giving per-domain trust scores for news search ranking.
IRIS_RESEARCH_RERANKER	enum		restart	Set to bge or cross-encoder to rerank research results with a cross-encoder; any other value leaves order unchanged.
IRIS_RESEARCH_RERANKER_MODEL	str	BAAI/bge-reranker-base	restart	sentence-transformers CrossEncoder model used to rerank research results when IRIS_RESEARCH_RERANKER is 'bge' or 'cross-encoder'.
IRIS_SEARXNG_URL	url		next call	Base URL of a self-hosted SearXNG instance; when set it becomes the first research search provider.

From plugin web_channel

Variable	Kind	Default	Applies	Description
IRIS_WEB_SESSION	str	default	restart	Web chat session id that channel messages without a recipient (e.g. heartbeat notices) are delivered into.