Models and providers

Naming a model

Everywhere a model is named, the value is a model reference:

package[.Class]:model

package is one of the provider packages agno ships. ivralo keeps no list of its own; it reads agno's. A value without a known package in front is an Ollama tag, so a plain tag keeps working.

The package name is matched without regard to case; the model part keeps its own colons and case.

Two things to know:

• openai means OpenAI's Responses API, because OpenAI's reasoning models refuse function tools on chat completions. Write openai.OpenAIChat: for chat completions.
• mistral:7b is the Mistral API's model 7b, not Ollama's Mistral. Write ollama:mistral:7b for the local one. ivralo doctor flags a reference that reads like this, and one that nearly spells a package, such as antropic:.

The default: Ollama

With nothing set, every role runs on gemma4:26b through Ollama at http://localhost:11434. ivralo init --pull pulls the tags that are missing.

A company endpoint

On a server, the model usually sits on a GPU machine in the same network behind an OpenAI-compatible API: vLLM, a LiteLLM proxy, llama.cpp's server or an internal gateway. Name it with openai-compatible: and the model's name as that server serves it:

IVRALO_MODEL=openai-compatible:qwen3-32b
IVRALO_OPENAI_COMPATIBLE_URL=http://gpu-box:8000/v1
IVRALO_OPENAI_COMPATIBLE_KEY=...        # only if the server wants one

ivralo init --server writes these for you:

ivralo init --server --model-url http://gpu-box:8000/v1 --model qwen3-32b

--model is then a name at that endpoint. A key is never taken as an argument: export IVRALO_OPENAI_COMPATIBLE_KEY before running init and it is copied into .env without being printed.

For an agno package with a server of its own, IVRALO_<PACKAGE>_URL points it there: IVRALO_VLLM_URL (default http://localhost:8000/v1), IVRALO_LMSTUDIO_URL, IVRALO_LLAMA_CPP_URL.

Hosted APIs

A hosted provider reads the key its own SDK reads: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, GROQ_API_KEY, MISTRAL_API_KEY, OPENROUTER_API_KEY and so on. Put it in the home's .env; ivralo keeps no copy under an IVRALO_ name.

Packages that speak OpenAI's protocol (openai, openrouter, deepseek, xai, together, fireworks, the local servers) need nothing extra. Four SDKs ship as optional extras:

The second column goes in the uv tool install line from Install on a server. Any other package needs its SDK installed once; ivralo doctor names it.

ivralo doctor, /model and --model check a model before anything is built and say what is missing in the SDK's own words: the package, the key, a class that does not exist, a server with no URL.

Settings for hosted and compatible models

Claude runs with its system prompt cached, since the team's prompts are long and the same from turn to turn.

A model per role

Every role can run on its own model, and the team can mix local and hosted ones:

IVRALO_MODEL=openai-compatible:qwen3-32b
IVRALO_COORDINATOR_MODEL=openai-compatible:qwen3-235b
IVRALO_MODEL_INVESTIGATOR=openai-compatible:qwen3-235b

The keys are analyst, spreadsheet, visualizer, reporter, scribe, librarian, pdf_operator, courier, secretary, github, coder and investigator, upper-cased in the variable. Roles on the same reference share one instance. ivralo agents lists each role with the model it runs on.

Switching from where you type

In a session:

/model anthropic:claude-sonnet-5

This sets the main model, IVRALO_MODEL, for the rest of the session and rebuilds the team on the same conversation. Roles with a setting of their own keep it. .env is not touched, so the next session starts from it again. /model alone lists the models in use and where each one runs.

From the command line, --model does the same for one run:

ivralo ask --model openai:gpt-5.5 "summarise the open TODOs in src/"

When a model is hosted

A model counts as local when its address is loopback, a private address, or a local name: one without a dot, or one ending in .local, .lan, .home, .internal or .localdomain. Any other address counts as hosted, including a company gateway reached by a public-style name such as llm.example.com. A model whose package is not installed also counts as hosted.

A hosted model receives the prompts, the history and the tool output, which is the text of whatever the agents read. ivralo says so every time: the session header shows a hosted line naming the provider, ivralo ask prints the same note above its text output, and ivralo doctor lists it. Incident evidence is refused on a hosted model unless you allow it with masking. What leaves the machine has the full list.