Configuration

Iva is configured by one file: .env in the install directory. The setup wizard fills it in for you — run iva config any time to redo a step (cli.md). .env.example in the repo root is the template. This page documents every variable.

Model, key and provider changes need only a restart. Iva reads these .env settings at startup. After editing:

iva restart

Swapping a model, key or provider is edit → restart, without a rebuild.

MEMORY_NIGHT_TIME=HH:mm sets the local time of the single memory-night Schedule in ASSISTANT_TIMEZONE (default 04:00; strict 00:00..23:59). This is a build setting: after editing .env, run iva update --force; in a development checkout use npm run build and iva restart. Editing .env alone moves neither the Schedule nor catch-up. /menu → ⏰ shows the active schedule and any pending time. Schedule and catch-up read one build artifact; a failed build or rollback preserves its previous time. Older builds without the artifact keep 04:00.

One exception: the reply language. The 🌐 Language button in /menu writes data/settings.json, which both processes re-read live — the switch takes effect immediately, no restart. See menu.md.

Model provider

Six providers. Pick one with MODEL_PROVIDER and fill only that block. ollama/opencode/openrouter are OpenAI-compatible API keys; codex rides your OpenAI (ChatGPT) subscription via OAuth — no key; claude rides your Claude Pro/Max subscription through the claude CLI signed in on the same server — no key either; custom is any OpenAI-compatible endpoint you point Iva at yourself. Prices and full model lists: providers.md.

*_VISION_MODEL is a fallback, not the main path. On the first incoming picture Iva asks the chat model itself with one tiny request whether it takes images. If it does, the picture goes straight to it — full pixels, no retelling — and the vision model is not called at all. If it answers with a refusal, the picture goes to *_VISION_MODEL as before and the model gets its description. The answer is remembered until the process restarts, so after a restart or a model change the question is asked again. One consequence of switching to a model without vision: pictures you sent earlier have no description saved for them, so send the photo again if the answer needs it.

Those six names, spelled exactly. Any other value — a typo, a different case — stops the agent at startup and prints the accepted names, instead of running Ollama under a name nobody configured; iva doctor and /menu → 📊 Status report the same thing (troubleshooting.md). No MODEL_PROVIDER line at all still means ollama.

For custom nothing is guessed: CUSTOM_BASE_URL and CUSTOM_MODEL are the two lines the provider cannot work without, and a blank one is a startup refusal naming the variable, not a silent default. THINKING_EFFORT is ignored on custom on purpose — OpenAI compatibility promises nothing about reasoning_effort, and sending it blind to an unknown endpoint risks an HTTP 400 on every turn. Full walkthrough: providers.md.

For codex there is no API key in .env: run iva login (device code, headless-friendly) or iva login --browser. The OAuth token lives in data/codex-auth.json (chmod 600, gitignored) and is auto-refreshed before it expires. Full flow: providers.md.

For claude there is no API key either: install the CLI on the server as the service user (npm install -g --prefix ~/.local @anthropic-ai/claude-code, no root) and sign it in once (claude auth login). Iva never sees a key — it calls that CLI, and iva doctor reports the plan from claude auth status. Keep ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_FOUNDRY_API_KEY, ANTHROPIC_BASE_URL and any CLAUDE_CODE_USE_* out of .env: each of them sends the CLI somewhere other than your subscription, so Iva refuses to use this provider and says which variable is in the way rather than quietly ignoring it. Full flow: providers.md.

If Claude’s access token comes from an external synchronization service, Iva can wait through its rotation after HTTP 401 and safely repeat the same call once, before any useful output or tool action in the current turn. Set claude.authRotationWaitMs in data/settings.json (for example, {"claude":{"authRotationWaitMs":120000}}); the default window is 120 seconds. Iva watches .credentials.json in CLAUDE_CONFIG_DIR, otherwise ~/.claude, and makes one final call when the access changes or the window ends. Each active attempt retains its usual first-output deadline. A successful repeat stays silent; a final authentication failure with an access-only token asks you to check the external synchronization service. The service that owns the credentials continues to manage refresh.

Don’t inflate the context window. Iva compacts the conversation between turns once a turn’s input reaches 60% of this number (or 110,000 tokens, whichever is smaller), and inside a turn a quarter above that as a safety net. Set it above the model’s real window and the compactor fires too late — the request overflows before the conversation gets trimmed. When you switch models, enter the new model’s actual window, not a rounder bigger one.

Use /compact to compress an idle conversation with at least 30,000 measured input tokens. Iva confirms completion, then reports the before/after size with the next answer using its first measured model input. During an answer, repeat the command after it finishes. After a restart, one completed turn supplies the input measurement.

Telegram

The allowlist is fail-closed: empty means Iva answers nobody. The wizard auto-discovers your ID the moment you message the bot; or ask @userinfobot. Why fail-closed matters: security.md.

At 10:00 in ASSISTANT_TIMEZONE Iva checks Git upstream without using the model. It sends nothing unless a higher stable MAJOR.MINOR.PATCH version exists, and offers each version only once. If TELEGRAM_DIGEST_CHAT_ID is empty, the first trusted ID is used.

Voice

Search

No key for the active provider means web_search returns a clear error — nothing crashes. Free tiers and the comparison table: providers.md.

Memory

The nightly Brain pass builds the hybrid index; to build it now, run node --env-file=.env scripts/memory/embed-index.ts. How search actually works: memory.md.

Notices

What Iva says on her own lives in data/settings.json, not in .env — the 🔔 Notices screen in /menu writes these keys, and the report switch is read at the end of each nightly run, the proactive key on every half-hourly Watch, Brief and Insight tick — so a tap applies without a restart.

Insight: once a day Iva builds and tries one plugin draft for something you keep doing by hand and asks before installing — ADR-0022.

Alerts — problems (memory not backed up, a failed nightly pass) and new versions — always arrive: they cannot be switched off, but each one says what to do and repeats at most once a week per problem — ADR-0007.

System

OpenCode Responses does not forward THINKING_EFFORT: arbitrary Go models have no verified reasoning contract; /think offers no levels in this mode. Existing installations without either protocol variable retain chat/completions, model IDs, keys and data.

Plugin service ownership

Plugin services belong to the canonical data directory. Two code checkouts using the same data directory share one plugin installation, including plugins.json, ports and the existing lock. Reconciliation updates scoped MCP executors to the selected checkout. An active retained legacy keeps its executor during trust/sync; an explicit plugin update may replace its payload only when that plugin source changed. A different canonical data directory gets a different scope in new service names.

A proven legacy service keeps its existing name. Adding ownership metadata alone keeps a running process uninterrupted. Ownership checks include the loaded data directory; foreign content, links and unknown ownership are preserved and reported by iva doctor. Moving the data directory changes the scope: review preserved old services explicitly. Older CLI versions lack these ownership checks, including during a rollback.