Models & providers (BYOK)

Forven's AI layer runs on your own model keys. There's no Forven-hosted inference and no token reselling. Every model call — from the agents, the in-app assistant and deep-dive chat — goes through one routing layer you control, using credentials stored on your machine.

Everything here is set on Agents → Setup, which has three parts: Agent models (who runs on which model), Providers (connections and their health) and Shortlist (models listed first). For a guided first setup, follow Put the agents to work.

Forven is research software. Model output and cost figures are illustrative, not predictive, and nothing here is financial advice. No model can move capital: agents have no order path.

The one rule: connected and selected

Forven only calls a (provider, model) pair that is:

1. connected — on Setup → Providers, and
2. selected — on your Shortlist, or picked for an agent, a fallback, a background task or the backup model on Setup → Agent models.

An API key that only exists in an environment variable does not authorize spend. Its provider tile says a key exists in the environment, but it is not connected here until you connect it in the app. The check sits in the lowest layer of every provider call, so everything is bound by it — agents, the Brain, the assistant, deep-dive, background tasks — in every Forven process that can make a call.

That's what makes spend yours to control: nothing calls a model you didn't pick.

Supported providers

Sixteen providers. Connect only the ones you mean to use.

A model is addressed as provider:model_id, for example anthropic:claude-sonnet-5. Every model picker lists all the models of your connected providers, with your Shortlist first; Refresh model lists on the Shortlist asks each provider for its current list. Catalogs change often, so treat any model id here as an example, not a recommendation.

Connecting a provider

On Setup → Providers, click Connect on a provider's tile.

• API key. Paste it and click Connect. The key is checked with the provider before it's saved, and Test later re-checks it rather than just confirming one is present.
• Sign in. OpenAI and MiniMax offer Sign in instead; your browser opens to finish. From a terminal: python -m forven auth login openai (or minimax), and python -m forven auth status shows what's configured. An expired sign-in stays under Connected with Sign in again.
• Local server. For LM Studio, enter the base URL, such as http://localhost:1234/v1.

Each connected card shows which agents use it, how many models it offers, and its health. Clear status forgets recorded failures; Disconnect removes the saved credentials so nothing can spend on it.

Models and fallbacks

On Setup → Agent models, every agent gets a model and an optional list of Fallbacks, in order.

• No silent vendor-hopping. By default a slot never falls back to a provider you didn't choose for it. If its model is throttled or down, the call fails and you see it; your prompt — which can carry strategy code and P&L — isn't quietly re-sent elsewhere.
• Cross-provider fallback is opt-in, per agent. Add fallbacks and they're tried in order. An empty list means fail closed.
• Fallbacks only before a tool runs. Once an agent has used a tool — registered a strategy, started a backtest — a later model failure ends the run instead of retrying elsewhere, because a retry would repeat those side effects.
• The default model follows the Brain. Calls with no model of their own use the Brain's.
• One model for everyone. Use one model for every agent… → Apply to all sets all six at once, the Brain included.

At call time Forven takes the slot's chain, drops anything you have no credentials for (it never adds a provider you didn't list), and tries each entry in order. On a rate limit (HTTP 429) it backs off before the next attempt, honouring a Retry-After header up to 30 seconds.

The backup model

Under Safety net, one Backup model is tried last, for every agent including the Brain, when a run's own model and fallbacks fail. A run whose model or fallbacks already use the backup's provider skips it, so it only helps on a provider your agents don't otherwise use — the checklist's Survive a provider outage step tells you whether it covers anyone. Leave it Off to keep pure fail-closed behaviour; failed runs then show up in Needs you.

Agents fall back to a provider you connected

Agents are seeded on openai, but you don't need that key. If an agent's provider has no credentials, the runner moves the run to a provider you did connect and logs the switch. The setup wizard re-points agents when you finish it, and Setup → Providers lists any stragglers with Move them to a connected provider. Calls only fail closed when nothing is connected at all.

Background tasks

Not every call deserves your best model. Three background tasks — small jobs the Brain hands off — have their own model and fallbacks under Agent models:

Left on Built-in default, they use OpenRouter models; if OpenRouter isn't connected the call moves to a connected model, or fails. Post-mortems aren't a background task — they run as agent runs on the Quant Researcher's model.

How errors are handled

• Transient (HTTP 408, 425, 429, 5xx, timeouts): back off and retry, moving down the slot's chain if it has one.
• Request too large (HTTP 413) is treated as a capacity problem, not a rate limit.
• Quota exhausted: a long backoff and one actionable alert, not a flood of retries.
• No credentials: skipped, and reported with the provider you actually asked for.
• Empty or truncated replies from reasoning models are detected and recovered where possible.

Every call records health against the provider that actually answered. You see it as the state on each Providers card, in Needs you on the Agents overview, and in each run's transcript.

Cost is tracked per call

Each successful call estimates its cost from a per-provider, per-model price table and stores it on the run. Usage the table can't price is charged a deliberately conservative rate, so an unknown model never reads as free; known-free routes (a local LM Studio server, OpenRouter :free models) are charged nothing. See cost controls.

Good to know

• Costs are estimates from token counts and list prices, not your provider's invoice.
• Free tiers (Gemini, Groq) have tight rate limits; expect 429s under the autonomous loop and lower the throughput preset if you rely on one.
• LM Studio needs a reachable local server; when it's down it's treated like any unavailable provider.
• Changes apply on Save and affect the next call.

Related

• Agents — the Agents page, including Setup
• Cost controls — spend safety, throughput and caps
• CLI reference — auth login, auth status