> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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")
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Uv[⬇️ Fetch uv] --> Py[🐍 Install Python 3.12]
    Py --> Venv[📦 Create environment]
    Venv --> Agents[✅ Install PraisonAI]

    classDef fetch fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef py fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef venv fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef done fill:#10B981,stroke:#7C90A0,color:#fff

    class Uv fetch
    class Py py
    class Venv venv
    class Agents done
```

## Quick Start

<Steps>
  <Step title="Launch the app">
    On a clean machine the app opens straight onto the first-run screen instead of the chat.
  </Step>

  <Step title="Watch the four stages">
    Each stage flips from pending to running to done as the runtime is built.
  </Step>

  <Step title="Start chatting">
    When the last stage completes, the window switches to chat — the environment is ready.
  </Step>
</Steps>

***

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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant You as 👤 You
    participant App as 🖥️ App
    participant Uv as ⬇️ uv
    participant Venv as 📦 venv

    You->>App: first launch
    App->>Uv: locate or fetch installer
    App->>Uv: install Python 3.12
    Uv->>Venv: create environment
    App->>Venv: install praisonaiagents
    Venv-->>You: ready to chat
```

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.

<Note>
  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](https://github.com/MervinPraison/PraisonAI/pull/4471), closes [#4441](https://github.com/MervinPraison/PraisonAI/issues/4441).
</Note>

***

## 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`.

| Stage `id` | Label                    |
| ---------- | ------------------------ |
| `uv`       | Fetching the installer   |
| `python`   | Installing Python        |
| `venv`     | Creating the environment |
| `deps`     | Installing PraisonAI     |

Each stage moves through four states:

| `state`   | Meaning                                                     |
| --------- | ----------------------------------------------------------- |
| `pending` | Not started yet                                             |
| `running` | In progress                                                 |
| `done`    | Finished successfully                                       |
| `error`   | Failed — the **Retry** button re-invokes `provision_engine` |

<Note>
  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.
</Note>

***

## 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**.

| Path                                                               | Contents                             |
| ------------------------------------------------------------------ | ------------------------------------ |
| `<data folder>/venv/`                                              | The provisioned Python environment   |
| `<data folder>/venv/bin/python3` (`Scripts\python.exe` on Windows) | The interpreter the engine runs from |

The `<data folder>` is the per-platform data directory — see [Data & Privacy](/docs/features/desktop/data#where-data-lives) 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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Q{Do you already have<br/>praisonaiagents?} -->|Yes| Own[Set PRAISONAI_PYTHON<br/>skip provisioning]
    Q -->|No| Manage[Let first-run finish<br/>app manages the runtime]

    classDef q fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef own fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef manage fill:#10B981,stroke:#7C90A0,color:#fff

    class Q q
    class Own own
    class Manage manage
```

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Point the engine at your own interpreter and skip the managed venv.
export PRAISONAI_PYTHON=/absolute/path/to/venv/bin/python3
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Let the first run finish uninterrupted">
    Provisioning downloads an interpreter and resolves packages. Leave the window open until all four stages are done — quitting mid-run leaves a partial venv.
  </Accordion>

  <Accordion title="Retry from where it stopped">
    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.
  </Accordion>

  <Accordion title="Own the runtime for reproducible installs">
    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.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Window & Lifecycle" icon="window-restore" href="/docs/features/desktop/window-and-lifecycle">
    Tray, single-instance, and orphan reclamation
  </Card>

  <Card title="Troubleshooting" icon="stethoscope" href="/docs/features/desktop/troubleshooting">
    Read the engine log and fix startup failures
  </Card>
</CardGroup>