> ## 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 desktop chat app that runs PraisonAI agents locally

PraisonAI Desktop is a native app for macOS, Windows, and Linux that runs your PraisonAI agents locally with streaming chat, tool calls, approvals, MCP servers, fine-tuning, a Train tab for local fine-tunes, and per-conversation memory — no browser required.

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

## 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`, macOS 10.15+). Shipping installers are DMG (arm64 + Intel), Windows NSIS, and Linux `.deb`.

    ```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 :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

The app ships as a DMG (Apple Silicon and Intel), a Windows NSIS installer, and a Linux `.deb`.

| Platform    | Needs                                                       |
| ----------- | ----------------------------------------------------------- |
| **macOS**   | 10.15+ (DMGs are built on macOS 15)                         |
| **Windows** | WebView2 (installed automatically by the NSIS bootstrapper) |
| **Linux**   | Ubuntu 22.04+ (glibc floor) and the Debian packages below   |

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

| Package                                            | Why                                               |
| -------------------------------------------------- | ------------------------------------------------- |
| `libwebkit2gtk-4.1-0`                              | The webview that renders the chat UI              |
| `libgtk-3-0`                                       | The window toolkit                                |
| `libayatana-appindicator3-1 \| libappindicator3-1` | The system tray icon                              |
| `curl`                                             | Used by the `uv` installer during first-run setup |

<Note>
  On a Wayland host with no appindicator the tray simply doesn't appear — the app still launches. Tray failure is logged, never fatal.
</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 from the app and load the checkpoint back in
  </Card>

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