Skip to content

providers.md

Latest commit

 

History

History
86 lines (57 loc) · 7.14 KB

providers.md

File metadata and controls

86 lines (57 loc) · 7.14 KB
Raw

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. Total: about $9/mo.

Model providers

Provider Price Text models Vision
OpenCode Go (ex-Zen) ~$5/mo ~23 models fetched live at setup — deepseek-v4-pro (default), kimi-k3, kimi-k2.7-code, glm-5.2, minimax-m3, qwen3.7-max, grok-4.5… qwen3.7-plus
Ollama Cloud ~$20/mo ~19 models fetched live — deepseek-v4-pro (default), kimi-k3, glm-5.2, minimax-m3, gpt-oss:120b… gemma4:31b
OpenRouter pay-as-you-go 300+ models across vendors — pick any slug (vendor/model) google/gemini-2.5-flash
OpenAI (ChatGPT subscription) your existing Plus/Pro/Team the models your plan exposes (gpt-5.x, -codex), fetched live same subscription (multimodal)

The first three are plain API keys; the last rides your personal OpenAI subscription:

  • 🔌 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, then `iva restart`

Start with Go: a quarter of 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.

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.

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.

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-4.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).

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.

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

Provider Free tier Card
tavily (recommended) ~1,000 searches/mo not required
exa ~20,000/mo not required
parallel starter credits not required
brave ~$5/mo credit required

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

Service Monthly
VPS $4–5
OpenCode Go ~$5
Deepgram voice $0 — starter credit
Web search (tavily) $0 — free tier
Total ~$9/mo

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