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

# Desktop App

> Download and run PraisonAI as a native app on Mac, Windows, or Linux — no Python setup

Download the app, run it, and the Python engine sets itself up on first launch. That's it.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
  subgraph "First Launch"
    D[⬇️ Download] --> O[🖱️ Open past the OS warning]
    O --> P[⚙️ App provisions Python]
    P --> R[✅ Ready to use]
  end
  classDef dl fill:#6366F1,stroke:#7C90A0,color:#fff
  classDef act fill:#F59E0B,stroke:#7C90A0,color:#fff
  classDef done fill:#10B981,stroke:#7C90A0,color:#fff
  class D dl
  class O,P act
  class R done
```

## Download

[![](https://img.shields.io/badge/Download_for_macOS-000000?style=for-the-badge\&logo=apple\&logoColor=white)](https://github.com/MervinPraison/PraisonAI/releases/latest)

[![](https://img.shields.io/badge/Download_for_Windows-0078D6?style=for-the-badge\&logo=windows\&logoColor=white)](https://github.com/MervinPraison/PraisonAI/releases/latest)

[![](https://img.shields.io/badge/Download_for_Linux-FCC624?style=for-the-badge\&logo=linux\&logoColor=black)](https://github.com/MervinPraison/PraisonAI/releases/latest)

Grab the latest build from the [Releases page](https://github.com/MervinPraison/PraisonAI/releases/latest), then pick the file for your platform:

| Platform | Download |
| - | - |
| macOS, Apple silicon (M1–M4) | `PraisonAI-<version>-macos-apple-silicon.dmg` |
| macOS, Intel | `PraisonAI-<version>-macos-intel.dmg` |
| Windows 10/11, 64-bit | `PraisonAI-<version>-windows-x64-setup.exe` |
| Linux, 64-bit (Debian/Ubuntu 22.04+) | `PraisonAI-<version>-linux-x64.deb` |

> [!NOTE]
>
> There is no universal build. Each download targets one architecture, and a wrong-arch download fails when you launch it — not when you install it, which is a worse place to find out. Match the file to your machine using the table above.

## Which download do I need?

Follow the branch for your machine.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
  Start[Your machine?] --> OS{OS?}
  OS -->|macOS| Mac{About This Mac says…}
  OS -->|Windows 10/11| Win[windows-x64-setup.exe]
  OS -->|Debian/Ubuntu 22.04+| Lin[linux-x64.deb]
  Mac -->|Chip: Apple M1/M2/M3/M4| MacA[macos-apple-silicon.dmg]
  Mac -->|Processor: Intel …| MacI[macos-intel.dmg]
  classDef q fill:#F59E0B,stroke:#7C90A0,color:#fff
  classDef out fill:#10B981,stroke:#7C90A0,color:#fff
  class Start,OS,Mac q
  class Win,Lin,MacA,MacI out
```

## Open it

The builds are unsigned, so each OS shows a warning the first time. Here's the one-time click for yours.

> [tab] macOS
>
> Not sure which Mac you have? Open the Apple menu → **About This Mac**. "Chip" means Apple silicon; "Processor" means Intel.
>
> **1. Move it to Applications**
>
> Drag **PraisonAI** to Applications.
>
> **2. Open it once**
>
> **Right-click** it → **Open** → **Open**. That once is enough; afterwards it launches normally.
>
> > [!WARNING]
> >
> > Gatekeeper says the app is unverified or that the developer is unidentified — nothing is wrong. The app simply has no trusted signature yet.
>
> If macOS still refuses, clear the quarantine attribute your browser added when it downloaded the file:
>
> ```sh theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> xattr -dr com.apple.quarantine /Applications/PraisonAI.app
> ```
>
> > [!WARNING]
> >
> > If you see *"PraisonAI is damaged and can't be opened"*, right-click → Open will **not** get past it — macOS says "damaged" when a signature is invalid, not merely untrusted. This affected v4.7.2; use v4.7.3 or later.

> [tab] Windows
>
> **1. Run the installer**
>
> Double-click `PraisonAI-<version>-windows-x64-setup.exe`.
>
> **2. Get past SmartScreen**
>
> Click **More info**, then **Run anyway**.
>
> > [!WARNING]
> >
> > SmartScreen shows a full-screen *"Windows protected your PC"* with the Run button hidden until you click **More info**. This is because the installer isn't signed yet, not because it's malicious.
>
> It installs for the current user only, into `%LOCALAPPDATA%`, so it never asks for an administrator password.
>
> > [!NOTE]
> >
> > If the WebView2 runtime is missing, the installer fetches it. Windows 11 and up-to-date Windows 10 already have it.

> [tab] Linux
>
> **1. Install with apt**
>
> ```sh theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> sudo apt install ./PraisonAI-<version>-linux-x64.deb
> ```
>
> Use `apt` rather than `dpkg -i` so the WebKitGTK dependencies are resolved rather than just reported.
>
> > [!NOTE]
> >
> > The `.deb` is built on Ubuntu 22.04, so it runs on 22.04, Debian 12, and anything newer. On an older distribution glibc will refuse it, and no runtime flag fixes that — build from source instead.
>
> > [!NOTE]
> >
> > There is no `.rpm` and no AppImage. AppImage needs `libfuse2`, which Ubuntu 24.04 removed, and renders a blank window on some Wayland and Mesa combinations.

## What happens the first time you open it

The app needs a Python environment to run its engine and offers to build one: it fetches `uv`, installs a pinned CPython, creates a virtual environment, and installs `praisonaiagents` into it. Nothing is installed system-wide, and nothing is written inside the app itself — everything lives in one folder.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
  participant User
  participant App as PraisonAI
  participant FS as Data folder
  User->>App: Launch
  App->>App: Fetch uv
  App->>App: Install pinned CPython
  App->>FS: Create venv
  App->>FS: pip install praisonaiagents
  App-->>User: Ready (≈500 MB, once)
```

| Platform | Data folder |
| - | - |
| macOS | `~/Library/Application Support/PraisonAI` |
| Windows | `%APPDATA%\PraisonAI` |
| Linux | `~/.local/share/PraisonAI` (or `$XDG_DATA_HOME/PraisonAI`) |

The folder appears as soon as you open the app; the ≈500 MB environment lands inside it once you click **Get started**.

On later launches the app also checks the venv against the shipped requirement and re-runs the install once if it drifted (the system tray reads `Engine: updating…` while it runs). This is why a fix in `praisonaiagents` reaches you on the next launch instead of requiring you to delete the venv by hand.

To remove the app completely, uninstall it and delete that folder.

## Video generation

The **Video** tab has a model picker. MiniMax video-01 (Replicate) is a preset, not the only option — SDK-capable providers (OpenAI Sora 2, Google Veo 3.1) become selectable once their key is set. Add the relevant key to the `.env` file inside the data folder above:

| Key | Unlocks |
| - | - |
| `REPLICATE_API_TOKEN` | MiniMax video-01 |
| `OPENAI_API_KEY` | Sora 2 |
| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | Veo 3.1 |

Models without a configured key appear disabled in the dropdown. See [Video generation](https://praison.ai/docs/features/desktop/video.md) for the full walkthrough.

## Which models work in the desktop app

The desktop app runs any **plain OpenAI-compatible model id** (a bare name, no `provider/` prefix); to reach a different endpoint, keep the bare id and set a **Base URL override** in Settings.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
  M[🧩 Model id] --> S{Has a slash?}
  S -->|No, bare id| OK[✅ Accepted]
  S -->|Yes, provider/model| NO[❌ Rejected at save]
  OK --> B[🌐 Optional Base URL → any endpoint]
  classDef q fill:#F59E0B,stroke:#7C90A0,color:#fff
  classDef ok fill:#10B981,stroke:#7C90A0,color:#fff
  classDef no fill:#8B0000,stroke:#7C90A0,color:#fff
  class M,S q
  class OK,B ok
  class NO no
```

| ✅ Works | ❌ Rejected |
| - | - |
| `gpt-4o` | `ollama/llama3.2` |
| `gpt-4o-mini` | `anthropic/claude-3-sonnet` |
| `gpt-5` | `gemini/gemini-2.0-flash` |
| `llama3.2` (with a Base URL pointing at your Ollama server) | any `provider/model` id |

### What the rejection message means

Saving a slashed id in **Settings → Model** returns this:

> The model id "…" needs the LiteLLM provider path, which this build does not include. Use a plain OpenAI-compatible model id without a provider prefix (for example gpt-4o-mini); to reach another endpoint, keep the bare id and set a Base URL override.

This build ships a lean Python engine without the LiteLLM provider extra. Slashed provider ids need that extra. The remedy is a bare id plus an optional Base URL — not a re-install, and not `pip install` in your own Python, since the app manages its own environment.

### Reach Ollama or another local endpoint

**1. Enter the bare model name**

In **Settings → Model**, type `llama3.2` — not `ollama/llama3.2`.

**2. Set the Base URL**

In the **Base URL** field, enter `http://localhost:11434/v1` (Ollama's OpenAI-compatible endpoint).

**3. Save**

The picker accepts it, and turns route to your local server.

To reach Anthropic, Gemini, or others, use the same pattern: a bare model id plus a Base URL for any provider that exposes an OpenAI-compatible endpoint (or a proxy such as LiteLLM Proxy). See [OpenAI-compatible endpoints](https://praison.ai/docs/models/openai-compatible.md) and [LiteLLM Proxy](https://praison.ai/docs/models/litellm-proxy.md).

> [!NOTE]
>
> This constraint applies to the desktop app's lean environment only — the Python SDK reaches Anthropic, Gemini, and others via the `llm` extra. A future desktop build may ship that extra, at which point slashed ids work automatically; the app already reports the capability on `GET /health` (`{ …, "litellm": false }`), so no user action is needed when it changes.

## If it will not start

The window shows the reason and the engine log. Two common ones:

> [accordion] No usable Python
>
> The setup screen offers to build the environment. If it fails, the step that failed is named along with what it printed.

> [accordion] Engine did not report ready in time
>
> The first import of the ML stack is slow on a cold machine. Give it a minute; if it persists, the Engine log in the sidebar has the traceback.

## Signing status

> [!NOTE]
>
> The builds are intentionally unsigned today: signing needs an Apple Developer ID on one side and a hardware-backed certificate or a hosted signing service on the other, and shipping builds you can open past a warning is better than shipping none. Signed builds are a planned improvement.

## Related

> [card] [Install the Python SDK instead](https://praison.ai/docs/install/quickstart.md)
>
> For developers who want the library

> [card] [All install options](https://praison.ai/docs/installation.md)
>
> Top-level installation index


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.