Skip to main content
The first time you launch PraisonAI Desktop, it installs its own Python runtime and the praisonaiagents package into your user data folder — no terminal, no pip.

​
Quick Start

1

Launch the app

On a clean machine the app opens straight onto the first-run screen instead of the chat.
2

Watch the four stages

Each stage flips from pending to running to done as the runtime is built.
3

Start chatting

When the last stage completes, the window switches to chat — the environment is ready.

​
How It Works

The app locates or fetches uv, has it install a pinned CPython, creates a venv in your data directory, then installs the engine’s dependencies into it. The runtime is pinned, not “latest”: the app installs Python 3.12 and a floor of praisonaiagents>=1.7.2 so a first run cannot land on a bad interpreter or a broken release.
On first launch (or any launch where setup is still needed), the app briefly forces the Chat view while the async engine health check runs. This prevents a saved Train view from hiding the setup wizard behind its CSS (body.training #thread { display: none }). The switch is not persisted — as soon as the engine is up, your deliberate saved view returns on the next launch. Fixed in PraisonAI #4471, closes #4441.

​
Event Stream

The first-run screen renders provision events from the provision_engine command. Each event carries an id, a label, a state, and an optional detail. Each stage moves through four states:
The dependencies stage installs the whole set in one uv pip install invocation, so uv resolves the packages together rather than one at a time.

​
Where Things Go

The environment is built inside your user data folder, never inside the read-only app bundle. The data folder itself is created when the app opens, ahead of provisioning. The venv and engine files land inside it when you click Get started. The <data folder> is the per-platform data directory — see Data & Privacy for each path. Override it with PRAISONAI_DESKTOP_HOME if you want the venv somewhere else.

​
Bring Your Own Runtime

If you already have praisonaiagents, you can skip provisioning entirely.

​
Best Practices

Provisioning downloads an interpreter and resolves packages. Leave the window open until all four stages are done — quitting mid-run leaves a partial venv.
If a stage errors (usually a network drop while fetching uv or Python), the Retry button re-runs provision_engine from the current stage rather than starting over.
Set PRAISONAI_PYTHON to a venv you control when you need a pinned, reproducible environment. The app then runs the engine against your interpreter and never provisions its own.

Window & Lifecycle

Tray, single-instance, and orphan reclamation

Troubleshooting

Read the engine log and fix startup failures