Skip to main content
Swap models from the title bar, tune sampling, and keep your API key in the platform keychain — never in a file.
The same string the desktop combobox passes into llm= can also be a provider-prefixed id, routed through litellm:

​
Quick Start

1

Open the model combobox

Click the model pill in the title bar. It suggests common models and accepts any string.
2

Set your API key

In Settings → Models → API key, paste your key. It is stored in the platform keychain.
3

Tune sampling (optional)

Adjust temperature, max_tokens, or top_p in the Models section.

​
Suggested Models

The combobox suggests eleven ids. Four use the OpenAI API and your api_key; the rest are provider-prefixed and route through litellm to a different provider, which needs that provider’s credentials — in the environment, in the app’s api_key field, or reached by a Base URL. It stays free-text, so you can type any id.

​
Using another provider (Anthropic, Google, Ollama, …)

Three paths reach these providers. The shipped desktop venv now carries litellm — it is a core dependency of the praisonai wrapper package pinned by ENGINE_PACKAGES (see PraisonAI#4721) — so slashed ids run fine out of the box, and PraisonAI#4778 restores them in the picker. The Base URL field is now sent to the variable the selected provider reads — OLLAMA_API_BASE for ollama/…, LM_STUDIO_API_BASE for lm_studio/…, HOSTED_VLLM_API_BASE for hosted_vllm/…, and <PROVIDER>_API_BASE for anything else litellm knows. The API key field follows the same rule (<PROVIDER>_API_KEY), with the OpenAI pair kept in step so switching back to a bare id still works. Pointing the desktop at a remote Ollama, LM Studio, or vLLM host is a two-field task: pick the slashed id, set Base URL. No shell exports needed. Path 1 — Provider-prefixed id (recommended for Anthropic, Gemini, Ollama): Pick a slashed id from the combobox and set that provider’s key in the environment (or run Ollama locally). No Base URL needed. Path 2 — Bare id + Base URL (for any OpenAI-compatible endpoint): Set a Base URL to that endpoint and type its bare model id. Path 3 — Slashed id + provider Base URL (recommended for Ollama / LM Studio / vLLM on your own host): Pick the slashed id and set Base URL to your host. The app routes it to the variable that provider reads. Both base_url and api_key are marked Requires restart — relaunch the app after changing either. See the Setup table below for the exact fields.
Behaviour introduced in PraisonAI #4921 — Base URL and API key are now routed to the environment variable the selected provider actually reads.

​
Sampling & Endpoint

Sampling values — including reasoning_effort — are forwarded only when you change them from their defaults, so a provider default you set elsewhere is never overridden unasked. reasoning_effort="off" is the default and is never sent, leaving each backend’s own reasoning behaviour untouched.
These values are forwarded into agent.start(..., max_tokens=..., top_p=...). Since MervinPraison/PraisonAI#4725 they also take effect on streaming chats — previously the streaming path ignored them. See Streaming → Sampling knobs.

​
Reasoning effort

reasoning_effort grades how hard the model thinks before answering. Off leaves the provider default in place; minimal / low / medium / high map to each backend’s native control (OpenAI/xAI reasoning_effort, Anthropic/Gemini extended-thinking budget). The chosen level is forwarded on every turn — streaming and non-streaming alike (since MervinPraison/PraisonAI#4780 the streaming path honours it too). See Reasoning Effort for what each level means and which model families it affects.

​
Where Keys Live

The api_key is stored in the platform secret store (service ai.praison.desktop, overridable with PRAISONAI_KEYCHAIN_SERVICE) and stripped before settings.json is written — it is the only key in SECRET_KEYS, so it never reaches the file. The store is durable: an unreadable secret raises rather than returning empty, so a transient failure never overwrites a good key, and deleting a key clears both the keychain and the plaintext fallback. See Data & Privacy for the full guarantees.
Your api_key never touches settings.json — it lives only in the platform secret store. Clearing it removes the credential from the environment on the next turn.
The store is durable: an unreadable store raises rather than silently returning empty (so a transient error can’t overwrite a good key), clearing a key wipes both the keychain and the fallback file, and the fallback file is written 0o600. Override the service name with PRAISONAI_KEYCHAIN_SERVICE (default ai.praison.desktop) to isolate keys. See Data & Privacy for the full guarantees.

​
Choosing a Setup

​
Best Practices

If you already export OPENAI_API_KEY, leave the field blank and the engine uses the environment key.
Both are marked “requires restart”. Relaunch so the engine routes to the new credential or endpoint. If you edit api_key or base_url while the engine is still restarting from a previous change, the write can be rejected — as of PraisonAI #4520 the row shows a Could not save that setting. toast and keeps the previous value on screen instead of applying a value the engine did not store. See Troubleshooting.
Base URL no longer always means OpenAI. It is sent to the variable the selected provider reads — OLLAMA_API_BASE for an ollama/… id, LM_STUDIO_API_BASE for lm_studio/…, HOSTED_VLLM_API_BASE for hosted_vllm/…, and <PROVIDER>_API_BASE for any other slashed id. A bare id still targets OPENAI_API_BASE. So to run Ollama, LM Studio, or vLLM on your own host, pick the slashed id and point Base URL at it.

Settings Reference

Every Models field and its default

Data & Privacy

How secrets are kept off disk