Settings Reference
Every field in the Desktop app settings registry
Every setting is one entry in a single registry, so rows, defaults, per-field reset, search, and restart notices all derive from the same list.
from praisonaiagents import Agent
agent = Agent(
name="PraisonAI",
role="Assistant",
goal="Answer the user clearly and concisely.",
)
# Settings you change in the app (model, temperature, system prompt)
# are applied to this agent on the next turn.
agent.start("Hello")Quick Start
- Open settings
Press
โ,to open the settings window. - Search for a field
Use the built-in search box โ it matches labels, descriptions, and keywords, and never returns a row that is currently hidden.
- Reset a single field
Each row has a per-field reset back to its default.
How It Works
On save, the engine clears its cached agents, so the next turn picks up your new settings immediately.
General
| Field | Type | Default | Notes |
|---|---|---|---|
launch_at_login | toggle | false | Requires restart; installed macOS .app only โ the toggle snaps back to off on Windows, Linux, and dev builds with an inline reason. See Launch at Login. |
check_updates | toggle | true | Check for updates automatically |
Models
| Field | Type | Default | Notes |
|---|---|---|---|
model | combobox | "gpt-4o-mini" | Any OpenAI-compatible model id. New chats use this. A provider-prefixed id (anthropic/โฆ, gemini/โฆ, ollama/โฆ) routes through litellm to that provider โ set its API key in the environment, or run Ollama locally. For an OpenAI-compatible endpoint instead, set a Base URL and use that endpoint’s bare model id. See Suggested Models. |
temperature | slider 0โ2 | 0.7 | Higher is more varied |
max_tokens | number 0โ128000 | 0 | 0 lets the model decide |
top_p | slider 0โ1 | 1 | |
reasoning_effort | select | "off" | off leaves the provider default; minimal / low / medium / high map to each backend’s native knob (OpenAI/xAI reasoning_effort, Anthropic/Gemini extended-thinking budget). See Reasoning Effort. |
framework | text | "praisonai" | Requires restart. Which engine runs a turn. praisonai is built in. Installing praisonai-frameworks adds crewai, autogen, langgraph, agno, google-adk, openai-agents, pydantic-ai. An uninstalled name is refused with the exact pip install command โ the setting never silently falls back to the default. See Agent Framework. |
base_url | text | "" | Requires restart. Point at Ollama, LM Studio, vLLM, a proxy or Azure. Sent to whichever provider the model names โ ` |
_API_BASE for a slashed id, OPENAI_API_BASE for a bare id. Blank uses the provider default. | | api_key | text (secret) | “”` | Requires restart; must be โฅ 20 characters; stored in the macOS keychain |
These values are forwarded into agent.start(..., max_tokens=..., top_p=..., reasoning_effort=...) โ but only when you picked a real level. reasoning_effort="off" is not forwarded (same rule as temperature / top_p, which are only sent when changed from their defaults), so the provider’s own default reasoning behaviour is preserved. Since MervinPraison/PraisonAI#4725 the sampling values also take effect on streaming chats โ previously the streaming path ignored them. See Streaming โ Sampling knobs.
Chat
| Field | Type | Default | Notes |
|---|---|---|---|
system_prompt | text (multiline) | "" | Prepended to every conversation |
auto_title | toggle | true | Names chats from the first message |
show_reasoning | toggle | true | Display the model’s thinking |
collapse_reasoning | toggle | false | Visible only when show_reasoning is on |
show_stats | toggle | true | Chars, duration, time to first token |
condense_paste | select | 4000 | Off / 2,000 / 4,000 / 8,000 characters |
Appearance
| Field | Type | Default | Notes |
|---|---|---|---|
theme | segmented | "system" | System / Light / Dark |
font_size | select | 15 | 13 / 14 / 15 / 16 / 18 / 20 px โ scales the whole interface |
code_font_size | number 10โ20 | 12 | Scales with the UI (rem-based) |
reduce_motion | segmented | "system" | System / On / Off |
Safety
| Field | Type | Default | Notes |
|---|---|---|---|
approval_mode | select | "ask" | ask prompts on every gated tool call; smart waives an allowlist of low-risk reads (read_file, list_directory, current_time, web_search) and prompts on everything else; never runs all tools without asking (confirmed once) |
approval_timeout | number 10โ3600 | 300 | Seconds; visible unless mode is never |
confirm_delete | toggle | true | Confirm before deleting a chat |
Since MervinPraison/PraisonAI#4730, smart is meaningful โ previously it fell through to the same prompt as ask. See Approvals & Safety for behaviour.
Data
Action rows, not stored values:
| Action | Effect |
|---|---|
| Export all | Exports every transcript as JSON |
| Show data folder | Opens the data directory |
| Delete all | Removes stored conversations (confirmed) |
See Data & Privacy for where data lives.
Integrations
| Row | Effect |
|---|---|
| MCP servers | Store MCP server entries for a future release. Not launched yet โ see MCP Servers. |
See MCP Servers for what the panel stores.
About
| Item | Shows |
|---|---|
| Version | The app version |
| Engine | The engine state (the Python process this window talks to) |
| Engine log | Recent engine activity |
| Check for updates now | Asks PyPI whether a newer praisonaiagents exists |
See Troubleshooting for the update check behaviour.
Gating Behaviour
Some rows appear only when another setting has the right value:
| Field | Visible when |
|---|---|
collapse_reasoning | show_reasoning is true |
approval_timeout | approval_mode is not never |
Fields marked Requires restart (base_url, api_key, launch_at_login, framework) say so on the row itself.
Tray & Shortcuts
The tray menu shows keyboard accelerators only where the modifier exists.
| Chord | macOS | Windows / Linux |
|---|---|---|
| Settings | Cmd+, shown | No accelerator advertised |
| Quit | Cmd+Q shown | No accelerator advertised |
Off macOS, Tauri maps Cmd to the Super key, which would render as Windows+, and Windows+Q โ and Windows+Q is reserved by the OS. So on Windows and Linux the tray still exists, but no accelerators are shown. The template menubar glyph is macOS-only, and on Linux the menu opens on left click regardless.
Best Practices
Use search instead of scrolling
The search box derives from the registry and respects visibility rules, so it never surfaces a hidden row. Type a keyword like “proxy” or “secret” to jump straight to a field.
Reset one field at a time
Per-field reset restores a single setting to its default without touching the rest โ safer than a full reset.
Restart after changing model credentials
base_url and api_key are marked “requires restart”. Relaunch the app after changing them so the engine picks up the new endpoint or key. If the engine is mid-restart when you change one of these rows, the write can be rejected โ you’ll see Could not save that setting. and the previous value stays on screen, so try again once the pill reads engine :PORT. See Troubleshooting.