Providers & cost

Iva runs on your server with your keys. Here is every external service it talks to, with real prices: one paid model subscription, one paid box — everything else fits a free tier. Iva herself is free: the model and the server on the standard stack run about $14–15/mo. A subscription you already pay for (ChatGPT Plus/Pro, Claude Pro/Max) works too — then the model line costs $0 extra.

Model providers

The first three are plain API keys, codex and claude ride subscriptions you already pay for, and custom is an address you supply:

• 🔌 OpenAI-compatible — Go, Ollama and OpenRouter share the same wire format, so switching is one line in .env
• 🌍 Any IP — all answer from any server location, no region blocks
• 💸 No markup — you pay the provider directly; Iva adds nothing on top

MODEL_PROVIDER=opencode   # or ollama / openrouter / codex / claude / custom, then `iva restart`

Those six names, spelled exactly. Anything else — ollmaa, OLLAMA — stops the agent at startup with the list of accepted names, instead of running Ollama under a name nobody configured (troubleshooting.md).

OpenCode Go only serves clients that identify themselves: every request carries Iva’s own User-Agent (iva/<version>) and a stable conversation id in x-opencode-session — the eve session id, or one id per process where there is no session (declared nodes, vision). Without them Go answers MissingSessionID on every turn (Go docs). Other providers get neither header.

Start with Go: half the price, ~23 models to switch between (the wizard pulls the live list, so new ones like kimi-k3 appear on their own). Keys, model pick and context-window settings live in configuration.md.

Two things about the live lists. Both catalogs churn — Ollama Cloud retired gemma3:12b on 2026-07-15 and Go dropped gemini-3-flash, so a hand-written model id in .env can start failing without you touching anything; if the bot goes quiet after weeks of silence on your side, re-run iva config and re-pick from the live list. And on Ollama Cloud the frontier tags (kimi-k3 among them) bill as extra usage on top of the plan: with an empty extra-usage balance the API answers 402, so top it up at ollama.com/settings or stay on deepseek-v4-pro.

OpenCode Go protocols (opencode)

Go’s catalog includes models served over different endpoints. Select the wire explicitly from Go’s endpoint table, without changing provider or adding a key:

MODEL_PROVIDER=opencode
OPENCODE_MODEL=muse-spark-1.3-contributor
OPENCODE_PROTOCOL=responses
iva restart

chat-completions remains the default. Responses models include Muse Spark, Grok 4.6/4.7 and GPT 5.6/6 Luna. iva config asks for the protocol and probes Responses with tools before saving; /model retains the selected protocol and validates Responses selections over that wire. Session headers, usage and night use the same factory. Thinking levels are unavailable for Go Responses until its reasoning contract is verified.

Vision falls back through its own OPENCODE_VISION_PROTOCOL (also chat-completions by default); set it to responses for a compatible image-capable Responses model. The selected text model is tested for image understanding over its actual wire first. Go /messages models are unsupported, including the current documented endpoint for the old qwen3.7-plus vision default. Choose a compatible fallback instead; Iva reports a protocol refusal and continues without a fabricated image description. Existing installs retain their previous defaults.

OpenAI by ChatGPT subscription (codex)

Use the OpenAI subscription you already pay for — no separate API key, no per-token bill. Iva signs in the same way the official codex CLI does (OAuth against auth.openai.com), stores a refreshable token in data/codex-auth.json (chmod 600), and calls the subscription’s Responses backend directly. The access token is refreshed automatically before it expires. If the backend rejects a still-fresh token after the subscription lapses, Iva forces one refresh and retries once; a second rejection tells you to run iva login.

iva login              # device code: opens a link + one-time code (works on a headless VPS)
iva login --browser    # PKCE flow: opens a browser on this machine
iva config             # pick the provider (option 3) and a model from your plan's live list
iva restart

Notes: the model list is pulled from your subscription at setup time, so you always see exactly what your plan allows. Set CODEX_CONTEXT_WINDOW to the real window of the model you picked (compaction derives its threshold from it). Routing a self-hosted assistant through the ChatGPT subscription backend is a grey area under OpenAI’s terms — you are using your own subscription on your own server, but weigh that yourself.

Claude by Pro/Max subscription (claude)

Use the Claude subscription you already pay for — no API key, no per-token bill, nothing to paste into .env. Iva calls the claude CLI (Claude Code) installed and signed in on the same server, so the CLI’s own login is what pays for the requests.

npm install -g --prefix ~/.local @anthropic-ai/claude-code   # as the service user, no root: lands in ~/.local/bin
claude auth login      # one sign-in on the server (a link + code)
iva config             # pick the provider (option 4) and a model from the subscription's live list
iva restart

Notes: the screen offers four models — Fable 5.1, Opus 5.5, Sonnet 5.5 and Haiku 5.5 — and only those the CLI picker actually has; an older CLI that does not know Haiku 5.5 yet shows Haiku 4.5 in its place, without thinking levels. .env stores the canonical id (claude-fable-5-1, claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5), never a picker alias. claude auth status names the plan, and iva doctor prints it next to the model. Requests are billed by the CLI — they count as claude -p (Agent SDK) usage on your plan. CLAUDE_CONTEXT_WINDOW for these four is 1000000 (200000 for Haiku 4.5). The service’s PATH is the node directory, then ~/.local/bin, /usr/local/bin, /usr/bin, /bin; iva doctor looks for claude on that same PATH, not on your shell’s. If the CLI lives elsewhere, point CLAUDE_COMMAND at the binary. /model → Claude checks the CLI and repeats the check after you sign in there.

OpenRouter (openrouter)

One key for 300+ models (Anthropic, OpenAI, Google, DeepSeek, Meta…), billed pay-as-you-go. Too many to list, so setup takes the model slug from you:

1. Key at openrouter.ai/keys (sk-or-…).
2. Copy a slug from openrouter.ai/models — the vendor/model id under the name (e.g. anthropic/claude-sonnet-5.5). The model must support tool/function calling: Iva sends tools every turn, so chat-only or image models won’t work.
3. iva config → provider 4 → paste the key, then the slug. Setup fires a live test with a tool call and continues only once the model answers — a mistyped slug or a no-tools model is rejected on the spot, not later as a silent bot.

Set OPENROUTER_CONTEXT_WINDOW to the model’s real window. Vision runs through google/gemini-2.5-flash regardless of your text model (billed to your OpenRouter credit); OPENROUTER_VISION_MODEL takes any other image-capable slug.

Your own OpenAI-compatible endpoint (custom)

Anything that speaks OpenAI chat/completions and you can reach: your own proxy, a vendor plan sold as an OpenAI-compatible key, vLLM, LiteLLM, a llama.cpp server on the same box. Before this existed the only way in was patching the provider table, and every iva update threw the patch away — now it is four lines of .env and nothing in the tree.

MODEL_PROVIDER=custom
CUSTOM_BASE_URL=https://api.example.com/v1   # the base IN FULL, /v1 suffix included
CUSTOM_API_KEY=sk-whatever-your-vendor-issues   # optional — leave empty for a keyless endpoint
CUSTOM_MODEL=vendor-model-name
CUSTOM_CONTEXT_WINDOW=131072                 # the real window of that model
iva restart

The address convention is Ollama’s: https://ollama.com/v1, not https://ollama.com. Iva appends /chat/completions and /models to what you wrote, so the /v1-style suffix belongs in the variable. iva config and the /model wizard both take it as text and refuse anything that is not a full http(s) address — a scheme-less api.example.com/v1 would otherwise fail later as a fake network error.

Nothing about this endpoint is guessed. CUSTOM_BASE_URL and CUSTOM_MODEL have no defaults, and a blank one stops the agent at startup naming the variable — Iva will not borrow another provider’s model or invent a host. CUSTOM_API_KEY is the exception: leave it empty and no Authorization header is sent at all, which is what a self-hosted server usually wants; iva doctor does not count it as missing.

Model selection follows whatever the endpoint offers. The wizard asks GET {base}/models first and shows the live list as buttons; endpoints that don’t implement it (the OpenAI-compatible contract doesn’t require it) fall through to typing the model id yourself, and that id is accepted as-is. A 401/403 is still a refusal — a wrong key does not become a “typed id”.

Two deliberate omissions. THINKING_EFFORT is not sent to custom: reasoning_effort is not part of what OpenAI compatibility guarantees, and a blind extra field risks an HTTP 400 on every turn — pick ollama, opencode or codex if you want adjustable thinking. And the outbound security gate has no pattern for CUSTOM_API_KEY’s shape, because an arbitrary vendor’s key has none; it is redacted by its name like every other prefixless key (security.md).

A local example, keyless:

MODEL_PROVIDER=custom
CUSTOM_BASE_URL=http://127.0.0.1:8000/v1
CUSTOM_API_KEY=
CUSTOM_MODEL=Qwen/Qwen3-32B-Instruct
CUSTOM_CONTEXT_WINDOW=32768

Vision

Attachments are never inlined into the model request. A photo lands in the vault, the agent gets its file path, and the provider’s own vision model writes the description — OCR plus visual detail — into the daily transcript. Same key as the text model, no extra subscription. Each provider’s default is a *_VISION_MODEL line in .env and a step in iva config; custom has no default there, so an endpoint whose chat model reads images needs nothing, and one whose model doesn’t needs a CUSTOM_VISION_MODEL and a CUSTOM_API_KEY to call it with. Being on a provider’s model list is not the same as reading images: on Go the default is qwen3.7-plus, and several of the larger models there refuse a picture outright.

VPS sizing

Any Ubuntu/Debian box for $4–5/mo. 512MB RAM works — the installer handles low-memory boxes (install.md). More than 1–2GB buys you little: the model runs in the cloud, not on your box.

Voice — Deepgram

Transcription runs on Deepgram nova-3 with language=multi: Russian, Uzbek and English are detected automatically, even mixed inside one voice note. A new account comes with a free starter credit — no card — that covers months of personal use. The one hard limit is Telegram’s, not Deepgram’s: the Bot API refuses downloads over 20MB, so a long video won’t transcribe.

Web search

Pick one, set SEARCH_PROVIDER and its key. No key means no web search — Iva says so instead of guessing. DuckDuckGo scraping was removed on purpose: server IPs get captchas, and a search tool that randomly hits a wall is worse than none.

Optional hybrid memory search adds one more key (Jina or DeepInfra embeddings) — covered in memory.md.

Total cost

Prefer Ollama Cloud and the same stack lands around $25/mo. Either way the bill is flat, predictable, and paid straight to the providers.