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

# PraisonAI Desktop

> Native chat app that runs PraisonAI agents locally on macOS, Windows, and Linux

PraisonAI Desktop is a native app that runs your PraisonAI agents locally with streaming chat, tool calls, approvals, MCP servers, per-conversation memory, and fine-tuning — no browser required. Sampling and [reasoning effort](/docs/features/reasoning-effort) are settable from **Settings → Models**, so you can tune how the model responds without touching code. It ships as macOS DMGs (Apple silicon + Intel), a Windows NSIS installer, and a Linux `.deb`.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
)
# Talk to this agent from the PraisonAI Desktop app —
# it picks up your local venv automatically.
agent.start("Summarize this file")
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    User[👤 You] --> Desktop[🖥️ Desktop App]
    Desktop --> Engine[🧠 Local Python Engine<br/>127.0.0.1]
    Engine --> Agent[🤖 PraisonAI Agent]
    Agent --> Tools[🔧 Tools & MCP]

    classDef user fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef app fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef engine fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef agent fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef tool fill:#10B981,stroke:#7C90A0,color:#fff

    class User user
    class Desktop app
    class Engine engine
    class Agent agent
    class Tools tool
```

The app is a Tauri (Rust) shell that supervises a small Python engine on loopback. Chat text streams straight from that engine into the webview over `127.0.0.1` — nothing leaves your machine unless the model itself does.

Prefer a terminal? The Desktop engine ships with `praisonai-desktop` — see [Headless CLI](/docs/features/desktop/cli).

## Quick Start

<Steps>
  <Step title="Install a venv with praisonaiagents">
    The app looks for a local virtual environment inside the checkout. Create one and install the SDK:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    cd src/praisonai-agents
    python3 -m venv .venv
    .venv/bin/pip install praisonaiagents
    ```
  </Step>

  <Step title="Build the app from source">
    The bundle targets are defined in `src-tauri/tauri.conf.json` (`productName: "PraisonAI"`, identifier `ai.praison.desktop`): `app`, `dmg`, `nsis`, and `deb`. macOS builds require 10.15+.

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    cd src/praisonai-desktop
    cargo tauri build
    ```
  </Step>

  <Step title="Launch and watch the startup pill">
    On first launch a status pill reports the engine's state:

    | Pill                | Meaning                                                                                                                                                                                                                                                                                            |
    | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `starting engine`   | The shell is spawning Python                                                                                                                                                                                                                                                                       |
    | `Engine: updating…` | The venv drifted from the shipped requirement — the app is re-running the install step before starting the engine (see [Troubleshooting → Library fixes never reached an existing install (pre-4670)](/docs/features/desktop/troubleshooting#library-fixes-never-reached-an-existing-install-pre-4670)) |
    | `engine :PORT`      | The engine is listening and healthy                                                                                                                                                                                                                                                                |
    | `engine failed`     | Startup failed — the tail of the log is shown                                                                                                                                                                                                                                                      |

    <Note>
      **Silent launch (no window)?** Open `%TEMP%\PraisonAI-startup.log` — the last line tells you whether the launch became the primary shell or was handed off. See [Troubleshooting → Startup Log](/docs/features/desktop/troubleshooting#startup-log-breadcrumb).
    </Note>
  </Step>
</Steps>

***

## How It Works

The Rust shell picks a Python interpreter, proves it owns its own `site-packages`, spawns the engine, then confirms the announced port with a `/health` probe before handing it to the webview.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant Shell as 🖥️ Tauri Shell
    participant Py as 🧠 Python Engine
    participant Web as 🌐 Webview

    Shell->>Py: spawn server.py (unbuffered)
    Py-->>Shell: PRAISONAI_PORT=51234
    Shell->>Py: GET /health (confirm)
    Py-->>Shell: {ok:true, version:2}
    Shell->>Web: engine :51234
    Web->>Py: POST /chat (SSE stream)
```

Where the app looks for the venv, in order (`src-tauri/src/main.rs`):

| Order | Path (relative to checkout)  |
| ----- | ---------------------------- |
| 1     | `src/praisonai-agents/.venv` |
| 2     | `src/praisonai-agents/venv`  |
| 3     | `venv`                       |

The first interpreter whose venv owns its own `site-packages` wins. A system Python or a mismatched venv is refused rather than guessed at.

***

## System Requirements

Each release ships one file per platform — there is no universal build.

| Platform                      | File                          |
| ----------------------------- | ----------------------------- |
| macOS, Apple silicon          | `...-macos-apple-silicon.dmg` |
| macOS, Intel                  | `...-macos-intel.dmg`         |
| Windows 10/11, 64-bit         | `...-windows-x64-setup.exe`   |
| Linux, 64-bit (Debian/Ubuntu) | `...-linux-x64.deb`           |

On Debian/Ubuntu the `.deb` declares its own dependencies, so `apt` resolves them:

| Dependency                                         | Provides                          |
| -------------------------------------------------- | --------------------------------- |
| `libwebkit2gtk-4.1-0`                              | The WebView                       |
| `libgtk-3-0`                                       | The window toolkit                |
| `libayatana-appindicator3-1 \| libappindicator3-1` | The tray icon                     |
| `curl`                                             | Fetching `uv` for first-run setup |

The package is built on Ubuntu 22.04, so it runs on Ubuntu 22.04+, Debian 12, and anything newer. On an older distribution, build from source.

<Note>
  Install with `apt` rather than `dpkg -i` so the WebKitGTK dependencies are resolved:

  ```sh theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  sudo apt install ./PraisonAI-<version>-linux-x64.deb
  ```
</Note>

***

## When To Use It

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start{How do you want<br/>to run agents?} -->|Point, click, chat| Desktop[🖥️ Desktop App]
    Start -->|Shareable browser UI| Web[🌐 Web UI]
    Start -->|Automate / script| Script[🐍 Python Script]

    classDef q fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef opt fill:#10B981,stroke:#7C90A0,color:#fff

    class Start q
    class Desktop,Web,Script opt
```

| Choose            | When                                                                             |
| ----------------- | -------------------------------------------------------------------------------- |
| **Desktop App**   | You want a local, native chat window with approvals and per-conversation history |
| **Web UI**        | You need a shareable browser experience                                          |
| **Python script** | You are automating agents or embedding them in code                              |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Keep the venv beside the checkout">
    The shell resolves the interpreter from fixed paths inside the checkout. Put your `.venv` at `src/praisonai-agents/.venv` so the app finds it without configuration.
  </Accordion>

  <Accordion title="Install praisonaiagents into that venv">
    A missing dependency surfaces as `engine failed: missing dependency`. Install `praisonaiagents` into the same venv the app resolves.
  </Accordion>

  <Accordion title="Read the pill, not the exit code">
    Every failure attaches the tail of the engine's own output. Read the pill and the log viewer instead of guessing from a bare exit code.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Chat & Streaming" icon="comments" href="/docs/features/desktop/chat">
    Messages, streaming events, tool cards, and keyboard shortcuts
  </Card>

  <Card title="Training" icon="graduation-cap" href="/docs/features/desktop/training">
    Fine-tune a local model with live loss and reconnect-safe progress
  </Card>

  <Card title="Approvals & Safety" icon="shield-check" href="/docs/features/desktop/approvals">
    `ask` / `smart` / `never` modes and the per-call approval flow
  </Card>

  <Card title="Fine-Tuning" icon="list-check" href="/docs/features/desktop/fine-tune">
    Train a model in the app and load the checkpoint
  </Card>

  <Card title="Settings Reference" icon="sliders" href="/docs/features/desktop/settings">
    Every field in the settings registry
  </Card>

  <Card title="Agent Framework" icon="layer-group" href="/docs/features/desktop/frameworks">
    Run a turn through CrewAI, AutoGen, LangGraph and other adapters
  </Card>

  <Card title="Engine & Diagnostics" icon="stethoscope" href="/docs/features/desktop/troubleshooting">
    Startup states, the log viewer, and common failure modes
  </Card>
</CardGroup>