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.

python
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")
Diagram

โš™๏ธ Settings Registry

๐Ÿ–ฅ๏ธ Rendered Rows

๐Ÿ” Search

โ†บ Per-field Reset

Quick Start

  1. Open settings

    Press โŒ˜, to open the settings window.

  2. 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.

  3. 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.

Diagram

๐Ÿ’พ Save

settings.json

๐Ÿงน clear cached agents

๐Ÿค– Next turn uses new settings


General

FieldTypeDefaultNotes
launch_at_logintogglefalseRequires 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_updatestoggletrueCheck for updates automatically

Models

FieldTypeDefaultNotes
modelcombobox"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.
temperatureslider 0โ€“20.7Higher is more varied
max_tokensnumber 0โ€“12800000 lets the model decide
top_pslider 0โ€“11
reasoning_effortselect"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.
frameworktext"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_urltext""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

FieldTypeDefaultNotes
system_prompttext (multiline)""Prepended to every conversation
auto_titletoggletrueNames chats from the first message
show_reasoningtoggletrueDisplay the model’s thinking
collapse_reasoningtogglefalseVisible only when show_reasoning is on
show_statstoggletrueChars, duration, time to first token
condense_pasteselect4000Off / 2,000 / 4,000 / 8,000 characters

Appearance

FieldTypeDefaultNotes
themesegmented"system"System / Light / Dark
font_sizeselect1513 / 14 / 15 / 16 / 18 / 20 px โ€” scales the whole interface
code_font_sizenumber 10โ€“2012Scales with the UI (rem-based)
reduce_motionsegmented"system"System / On / Off

Safety

FieldTypeDefaultNotes
approval_modeselect"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_timeoutnumber 10โ€“3600300Seconds; visible unless mode is never
confirm_deletetoggletrueConfirm 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:

ActionEffect
Export allExports every transcript as JSON
Show data folderOpens the data directory
Delete allRemoves stored conversations (confirmed)

See Data & Privacy for where data lives.

Integrations

RowEffect
MCP serversStore MCP server entries for a future release. Not launched yet โ€” see MCP Servers.

See MCP Servers for what the panel stores.

About

ItemShows
VersionThe app version
EngineThe engine state (the Python process this window talks to)
Engine logRecent engine activity
Check for updates nowAsks 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:

FieldVisible when
collapse_reasoningshow_reasoning is true
approval_timeoutapproval_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.

ChordmacOSWindows / Linux
SettingsCmd+, shownNo accelerator advertised
QuitCmd+Q shownNo 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.


Related