First-Run Provisioning

How the Desktop app installs its own Python runtime on first launch

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.

On later launches, the app compares a record of what it installed against the requirement shipped with the current build. If a fix in praisonaiagents raised the floor, or a new package was added, the app re-runs the install step once — the tray reads Engine: updating… while it runs — and starts the engine against the up-to-date venv. This is why raising the pin in one release actually reaches you on the next launch, instead of only reaching brand-new installs.

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
)
# The Desktop app provisions the environment that runs this agent for you.
agent.start("Hello")

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.

Keeping the venv current

The venv is provisioned once, but its package set is not frozen. Each launch writes a small .praisonai-packages stamp inside the venv recording which requirements are currently installed. When the shipped requirement changes — a raised floor for praisonaiagents, an added dependency — the stamp no longer matches, and the app re-runs the install step exactly once before the engine starts. uv is near-instant when nothing changed, so a no-drift launch is not slowed. On failure the engine still starts and the UI reports whatever version is actually installed, so a bad update never blocks chat; the stamp is only written on install success, so a failed update is retried on the next launch rather than silently recorded as done.

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:

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.

# Point the engine at your own interpreter and skip the managed venv.
export PRAISONAI_PYTHON=/absolute/path/to/venv/bin/python3

Reconciliation only touches the venv the app provisioned itself (<data folder>/venv). If PRAISONAI_PYTHON points the engine at your own interpreter, the app never rewrites its packages — you own that environment and its versions.

Best Practices

Related