Docs / Reference

Environment variables

Every IVRALO_* variable ivralo reads, with its default and what it changes, grouped by topic. Each one has a working default, so a home needs only the few you want to change.

How a setting is read

Each variable is read once, when ivralo starts, from three places. The first that has a value wins:

The environment of the process: what your shell, your service manager or a CI job exported. A file never changes a value that was exported.
The workspace's .ivralo/.env, at the root of the repository ivralo was started in, but only once you have trusted the folder. It never sets IVRALO_HOME, IVRALO_MODE, IVRALO_FORGE_GH or IVRALO_GITHUB_URL: a repository cannot grant itself an unattended push.
The home's .env, in your ivralo home.

A repository's own .env is never read; it holds the project's secrets, not ivralo's. A folder you trust during a session has its .ivralo/.env read at that moment.

How a value is parsed:

A switch is on for 1, true, yes or on, in any case. Anything else is off, and an unset switch keeps its default.
A number that is not a number falls back to the default. Where the table says "at least 1", zero and negatives also mean the default; where it says "below 1 counts as 1", they mean 1.
A choice that is not one of the allowed words falls back to the first one. For IVRALO_PROFILE the fallback is reported by ivralo doctor.

The provider SDKs read their own keys (ANTHROPIC_API_KEY, OPENAI_API_KEY and the rest); ivralo only checks that one was found. See Models.

Models

Variable	Default	What it does
`IVRALO_MODEL`	`gemma4:26b`	The model every role runs on unless something narrower names another. An Ollama tag, or `provider:model`.
`IVRALO_COORDINATOR_MODEL`	the main model	The main agent's model. Set this to run the main agent on a different model from the specialists.
`IVRALO_MODEL_<KEY>`	the main model	One specialist's model, by its preset key: `IVRALO_MODEL_CODER`, `IVRALO_MODEL_INVESTIGATOR`, `IVRALO_MODEL_ANALYST`. Keys are on Capabilities and presets.
`IVRALO_MEMORY_MODEL`	the main model	The small model that extracts memories and names conversations.
`IVRALO_OLLAMA_HOST`	`http://localhost:11434`	Where Ollama listens, for chat models and the embedder. Plain `OLLAMA_HOST` is not read.
`IVRALO_REQUEST_TIMEOUT`	`300`	Seconds one request to a model or the embedder may wait. It is retried once. `IVRALO_TIMEOUT` is the old name, read when this one is unset.
`IVRALO_NUM_CTX`	`16384`	Ollama's context window. Raising it costs memory on the GPU.
`IVRALO_OLLAMA_THINK`	`off`	`off` tells a thinking-capable Ollama model not to think; `on` leaves Ollama's own behaviour.
`IVRALO_NUM_PREDICT`	`8192`	Ollama's reply cap: a runaway generation stops here.
`IVRALO_KEEP_ALIVE`	`30m`	How long Ollama keeps the weights loaded between calls.
`IVRALO_TEMPERATURE`	`0.2`	Sampling temperature. A hosted model receives it only when the variable is set; otherwise it keeps its own default.
`IVRALO_MAX_TOKENS`	`8192`	The longest reply a hosted or OpenAI-compatible model may write.
`IVRALO_CONTEXT_WINDOW`	`0`	The window the context meter measures against. `0` means `IVRALO_NUM_CTX` for a local model and 128000 for a hosted one.
`IVRALO_<PACKAGE>_URL`	none	Where a provider package listens when it is not where it assumes: `IVRALO_VLLM_URL`, `IVRALO_LMSTUDIO_URL`, `IVRALO_LLAMA_CPP_URL`.
`IVRALO_OPENAI_COMPATIBLE_URL`	none	The server behind the `openai-compatible` provider: a LiteLLM proxy, llama.cpp's server, a gateway. Required for that provider.
`IVRALO_OPENAI_COMPATIBLE_KEY`	empty	Its API key. Kept out of the Python worker.

Embeddings and the knowledge index

Variable	Default	What it does
`IVRALO_KNOWLEDGE`	on	The workspace's knowledge index and the Librarian that searches it. Off drops both.
`IVRALO_EMBED_MODEL`	`nomic-embed-text`	The embedder. A bare name is an Ollama tag.
`IVRALO_EMBED_DIMENSIONS`	`768`	The vector size. It must match the embedder; change it, then run `ivralo index --rebuild --all`.
`IVRALO_EMBED_CODE_HOSTED`	off	Whether a hosted embedder may embed code for semantic code search. Off, it refuses code.
`IVRALO_KNOWLEDGE_RESULTS`	`5`	How many hits a search returns.
`IVRALO_CHUNK_SIZE`	`1500`	The size of one indexed chunk.
`IVRALO_INDEX_LANGUAGE`	`simple`	The PostgreSQL text-search configuration for the keyword half of the search. `simple` matches codes and names in any language; `english` or `turkish` adds stemming. Needs `ivralo index --rebuild`.
`IVRALO_INDEX_VECTOR_WEIGHT`	`0.5`	How much the vector half weighs against the keyword half, from 0 to 1.

See Embeddings and The knowledge index.

Database

ivralo keeps its own state (sessions, runs, memory, jobs, the index) in PostgreSQL. See PostgreSQL.

Variable	Default	What it does
`IVRALO_DB_URL`	empty	A full SQLAlchemy URL. When set it wins over every part below. `ivralo init --postgres` writes it.
`IVRALO_PG_HOST`	`127.0.0.1`	The host. The IPv4 loopback on purpose: `localhost` can resolve to IPv6 first on Windows.
`IVRALO_PG_PORT`	`5432`	The port.
`IVRALO_PG_USER`	`ivralo`	The user.
`IVRALO_PG_PASSWORD`	`ivralo`	The password. `ivralo init` offers to generate one.
`IVRALO_PG_DB`	`ivralo`	The database.
`IVRALO_PG_SCHEMA`	`ivralo`	The schema every table goes in.
`IVRALO_PG_CONNECT_TIMEOUT`	`5`	Seconds to wait for the connection before giving up. Anything under 2 counts as 2.

Home, workspace and files

Variable	Default	What it does
`IVRALO_HOME`	the checkout	The ivralo home: its `.env`, skills and settings files. Without it, ivralo uses the checkout you are in, or the one it runs from.
`IVRALO_WORKSPACE`	the repository you are in	Where the team reads and writes. Outside a repository, `workspace/` in the home.
`IVRALO_SKILLS_DIR`	`skills/` in the home	The shipped skill shelf.
`IVRALO_SKILLS_LOCAL_DIR`	`skills.local/` in the home	Installed and scaffolded skills, with `assignments.json`.
`IVRALO_MCP_CONFIG`	`mcp.json` in the home	The MCP servers file.
`IVRALO_PERMISSIONS`	`permissions.json` in the home	The home's permissions file.
`IVRALO_DATABASES`	`databases.json` in the home	The home's named databases.
`IVRALO_IDENTIFIERS`	`identifiers.json` in the home	The home's list of identifiers to mask in incident evidence.
`IVRALO_GOOGLE_TOKEN`	`google-token.json` in the home	The Google sign-in token.
`IVRALO_SCHEDULES`	`schedules.json` in the home	The schedules file.
`IVRALO_BRAND_FILE`	`brand.json` in the home	The house colours every document, deck and chart uses.
`IVRALO_SESSION_ID`	the shared session	Attach this terminal to a named session, as `ivralo -s` does.
`IVRALO_USER_ID`	`owner`	Whose memories and sessions these are.

Every file is described on Settings files.

Modes, profile and grants

Variable	Default	What it does
`IVRALO_MODE`	`developer`	`developer` or `server`: what a run nobody attends may do. `server` also lets it commit, push a branch ivralo made and open a draft pull request. Home or environment only.
`IVRALO_FORGE_GH`	off	Whether opening a pull request may use the gh CLI's own login. Written only by a yes at a terminal during `ivralo init --server`. Home or environment only.
`IVRALO_PROFILE`	`normal`	`normal`, or `strict`: no shell, no web, no sending, no writes to Google or GitHub, no edits or commits, no MCP servers. It only narrows.
`IVRALO_MAIN_GRANTS`	the whole declared set	Narrow what the main agent may hold: grant names separated by commas or spaces, or `none` to leave it only its hand-offs. It never widens.

See Capabilities and presets and Server mode.

Team and limits

Variable	Default	What it does
`IVRALO_TOOL_CALL_LIMIT`	`20`	Tool calls per run for a specialist that sets no limit of its own.
`IVRALO_TOOL_CALL_LIMIT_<KEY>`	the preset's own	One specialist's limit, by preset key. The Code Engineer's is 200 and the Investigator's 40. `IVRALO_TOOL_CALL_LIMIT_COORDINATOR` is the main agent's, 200 by default.
`IVRALO_CODERS`	`3`	How many Code Engineers can work at once in a repository. Below 1 counts as 1.
`IVRALO_INSTANCES`	`24`	Open instances one agent may hold. `0` takes instances away.
`IVRALO_INSTANCE_DEPTH`	`2`	How deep instances may nest. Below 1 counts as 1.
`IVRALO_INSTANCES_PER_OPENER`	`8`	How many instances one instance may hold open. Below 1 counts as 1.
`IVRALO_INSTANCE_BUDGET`	`1000000`	Tokens a top-level instance and everything under it share. `0` turns the budget off.
`IVRALO_ASK_MEMBER`	on	Whether a specialist may put a question to a colleague mid-task.
`IVRALO_ASK_MEMBER_TIMEOUT`	`300`	Seconds one such question may take. At least 1.
`IVRALO_ASK_MEMBER_LIMIT`	`5`	Questions one specialist's run may ask. At least 1.
`IVRALO_SHARE_INTERACTIONS`	off	Whether each hand-off to a specialist is given the tasks and replies of the hand-offs that ended before it in the same run.
`IVRALO_TEAM_MODE`	`coordinate`	The team's routing mode in agno: `coordinate`, `route`, `broadcast` or `tasks`.
`IVRALO_MAX_ITERATIONS`	`8`	The team's iteration cap in agno.
`IVRALO_HISTORY_RUNS`	`5`	How many past runs stay in the model's context.
`IVRALO_HISTORY_TOOL_CALLS`	`6`	Of the tool calls in that history, how many newest keep their results.

See Instances and Parallel coders.

Plans, memory and context

Variable	Default	What it does
`IVRALO_AUTO_PLAN`	on	A request that reads as several steps is planned and approved before anything runs.
`IVRALO_PLAN_MODE`	off	The session starts in plan mode: every message is planned first.
`IVRALO_PLAN_PARALLEL`	on	Plan steps that do not need each other run together, a wave at a time. Off, every step is its own wave.
`IVRALO_MEMORY`	on	Long-term memory about you.
`IVRALO_MEMORY_UNATTENDED`	off	Whether runs nobody attends (`ivralo ask`, a schedule, a job, the API) also extract memories. They read memories either way.
`IVRALO_COMPACT_THRESHOLD`	`0.85`	The fraction of the context window at which the meter turns red and, with auto-compact on, the session is summarized.
`IVRALO_AUTO_COMPACT`	on	Summarize automatically after a turn that crossed the threshold. Off, you are warned and run `/compact` yourself.
`IVRALO_VERBOSE`	off	Print agno's own panels, with every tool argument in full.
`IVRALO_DEBUG`	off	agno's debug output.

Editing and code

Variable	Default	What it does
`IVRALO_CHANGESET`	off	Stage each turn's edits as one changeset, in the session and in `ivralo ask`.
`IVRALO_HISTORY`	on	Copy a file to `.ivralo/history/` before it is overwritten.
`IVRALO_HISTORY_KEEP`	`10`	Versions kept per file.
`IVRALO_WHOLE_FILE_WRITES`	off	Let `write_file` replace a file that exists. Off, an existing file changes only by a named edit.
`IVRALO_EDIT_REFUSES_ON_DIAGNOSTIC`	off	Roll a symbol edit back when the language server reports a new error, instead of reporting it beside the edit.
`IVRALO_LSP_TIMEOUT`	`30`	Seconds one request to a language server may take.
`IVRALO_LSP_WARMUP_WAIT`	`15`	Seconds a tool waits for a language server that is still starting.
`IVRALO_CODE_INDEX_BUDGET`	`2.0`	Seconds a turn's start may spend refreshing the code index. `0` turns that refresh off.
`IVRALO_EXPLORATION_BUDGET`	`0`	Exploration tokens one agent may spend in a turn before wide reads are refused. `0` counts nothing.
`IVRALO_EXPLORATION_FILE_LINES`	`200`	The widest file read that is never refused.
`IVRALO_SLICE_BUDGET`	`2000`	Tokens a code slice fills when the call names none, held between 200 and 8000.
`IVRALO_BISECT_STEPS`	`20`	The most commands one `ivralo bisect` runs.
`IVRALO_BISECT_STEP_TIMEOUT`	`900`	Seconds one bisect step may run; past it the commit is skipped.
`IVRALO_INSTALL_TIMEOUT`	`1800`	Seconds the project's install step may run during `ivralo init --server`.

See Code intelligence, Changesets and Git.

The Python worker

Variable	Default	What it does
`IVRALO_PYTHON_ISOLATION`	`process`	`process` runs a specialist's Python in a worker process of its own, capped in time and memory, with no credential in its environment. `inline` runs it in ivralo's own process, for a debugger only.
`IVRALO_PYTHON_TIMEOUT`	`300`	Seconds one Python run may take.
`IVRALO_PYTHON_MAX_MB`	`4096`	The worker's memory cap in MB. `0` lifts it.

See The Python worker.

Server, API, jobs and incidents

Variable	Default	What it does
`IVRALO_API_PORT`	`61017`	The loopback port `ivralo serve` listens on.
`IVRALO_API_APPROVAL_TIMEOUT`	`1800`	Seconds an approval through the API waits before the call is rejected.
`IVRALO_JOB_LEASE_SECONDS`	`60`	Seconds a running job's heartbeat stays good. Past it, the next process may take the job over.
`IVRALO_JOB_HEARTBEAT_SECONDS`	`10.0`	Seconds between a running job's heartbeats.
`IVRALO_ALERT_DEDUP_SECONDS`	`21600`	Seconds an alert's investigation stands for that alert: the same alert again within them starts no second job.
`IVRALO_ALERT_STUBS_KEEP`	`200`	Alert folders kept under `alerts/`. `0` keeps them all.
`IVRALO_INCIDENT_HOSTED_MODEL`	off	Whether a hosted model may read incident evidence. It also needs `IVRALO_INCIDENT_MASK`. `ivralo incident --hosted` turns it on for one run.
`IVRALO_INCIDENT_MASK`	off	Replace the identifiers in `identifiers.json`, and IP and e-mail addresses, with placeholders before a model reads the evidence.

See Local API, Jobs, Alert intake and Privacy and masking.

The web

Variable	Default	What it does
`IVRALO_WEB`	on	The Librarian's web search, read and save. Only the query leaves the machine.
`IVRALO_WEB_RENDER`	on	Render a blocked page or a rate-limited search in headless Chromium.
`IVRALO_WEB_TIMEOUT`	`20`	Seconds one web request may take.
`IVRALO_SEARXNG_URL`	empty	A self-hosted Searxng, used as a further search backend.
`IVRALO_SEARXNG_SECRET`	empty	The secret the Searxng container signs cookies with. ivralo only checks that it is set.
`IVRALO_REASONING`	off	agno's think and analyze tools on the Librarian.

Integrations

Variable	Default	What it does
`IVRALO_MAIL`	empty	`smtp` or `resend` gives the team a Courier that sends mail. Empty means no mail.
`IVRALO_MAIL_FROM`	empty	The sender address.
`IVRALO_MAIL_ALLOWED`	empty	Addresses or `@domains` mail may go to, comma separated. Empty allows any.
`IVRALO_MAIL_MAX_MB`	`10`	The attachment cap in MB.
`IVRALO_SMTP_HOST`	empty	The SMTP server.
`IVRALO_SMTP_PORT`	`587`	Its port.
`IVRALO_SMTP_USER`	empty	The SMTP user.
`IVRALO_SMTP_PASSWORD`	empty	The SMTP password.
`IVRALO_SMTP_SECURITY`	`starttls`	`starttls`, `ssl` or `none`.
`IVRALO_RESEND_API_KEY`	empty	The Resend API key.
`IVRALO_TELEGRAM_BOT_TOKEN`	empty	A Telegram bot for short messages. Needs the chat id too.
`IVRALO_TELEGRAM_CHAT_ID`	empty	The chat the bot posts to.
`IVRALO_SLACK_WEBHOOK_URL`	empty	A Slack incoming webhook for short messages.
`IVRALO_GOOGLE_SERVICES`	empty	Google services the Secretary connects to: any of `sheets`, `drive`, `calendar`, `gmail`, comma separated. Empty means no Secretary.
`IVRALO_GOOGLE_WRITE`	off	Let the Secretary draft, create and update. It never sends.
`GOOGLE_CLIENT_ID`	empty	The Google desktop OAuth client.
`GOOGLE_CLIENT_SECRET`	empty	Its secret.
`GITHUB_ACCESS_TOKEN`	empty	A GitHub token. Setting it puts the GitHub Clerk on the team; it is also the token a draft pull request is opened with.
`IVRALO_GITHUB_WRITE`	off	Add GitHub's write tools, each call approved.
`IVRALO_GITHUB_URL`	github.com	A GitHub Enterprise API base (`https://host/api/v3`). Home or environment only.
`IVRALO_SQL_URL`	empty	Your own database for the analyst, read-only: the connection named `default`.
`IVRALO_SQL_ROW_CAP`	`200`	Rows one query returns at most.
`IVRALO_SQL_TIMEOUT`	`20`	Seconds one query may run.
`IVRALO_UNSPLASH_ACCESS_KEY`	empty	Unsplash's key, for stock photos in documents.

See E-mail and chat, Google Workspace, GitHub and Documents and data.

Observability

Variable	Default	What it does
`IVRALO_OTEL_ENDPOINT`	empty	An OTLP/HTTP collector to send spans to. Empty means nothing leaves the machine. `/v1/traces` is added when the URL has no path.
`IVRALO_OTEL_SERVICE`	`ivralo`	The `service.name` the spans carry.

See Observability.

The session and documents

Variable	Default	What it does
`IVRALO_PREVIEW_IMAGES`	on	Show the pictures a turn produced under the reply.
`IVRALO_PREVIEW_ROWS`	`14`	Terminal rows one picture takes.
`IVRALO_PREVIEW_MAX`	`3`	Pictures shown per turn.
`IVRALO_PREVIEW_RENDERER`	`auto`	`auto`, `sixel`, `tgp`, `halfcell` or `unicode`, when the detection is wrong.
`IVRALO_FOLLOW_UP`	on	One suggested next message after each reply.
`IVRALO_REDUCED_MOTION`	off	Still spinners and no fades, in the session and the CLI.
`IVRALO_SESSION_TITLE`	on	The memory model names a conversation after its first reply.
`IVRALO_FONT`	DejaVu Sans	A TrueType font file for PDFs. Its `-Bold`, `-Oblique` and `-BoldOblique` siblings are used when they exist.
`IVRALO_DOCLING`	`docling` on the PATH	The docling program used for OCR.
`IVRALO_OCR_LANGS`	`tr,en`	OCR languages, comma separated.

Evals

These matter only to someone running ivralo's own evals. See Evals.

Variable	Default	What it does
`IVRALO_EVAL_JOBS`	`1`	Eval runs at once without `--jobs`.
`IVRALO_TUNE_MODEL`	the main model	The model `ivralo eval --tune` asks for a skill rewrite.
`IVRALO_TUNER_INPUT_TOKENS`	`16000`	Tokens one tuner call may be handed.