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

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")

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.

Quick Start

1. Install a venv with praisonaiagents

   The app looks for a local virtual environment inside the checkout. Create one and install the SDK:

   cd src/praisonai-agents
   python3 -m venv .venv
   .venv/bin/pip install praisonaiagents
   
2. 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+.

   cd src/praisonai-desktop
   cargo tauri build
   
3. 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))
   engine :PORT	The engine is listening and healthy
   engine failed	Startup failed — the tail of the log is shown

   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.

---

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.

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.

Install with apt rather than dpkg -i so the WebKitGTK dependencies are resolved:

sudo apt install ./PraisonAI-<version>-linux-x64.deb

---

When To Use It

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

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.

Install praisonaiagents into that venv

A missing dependency surfaces as engine failed: missing dependency. Install praisonaiagents into the same venv the app resolves.

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.

---

Related

Chat & Streaming

Messages, streaming events, tool cards, and keyboard shortcuts

Training

Fine-tune a local model with live loss and reconnect-safe progress

Approvals & Safety

ask / smart / never modes and the per-call approval flow

Fine-Tuning

Train a model in the app and load the checkpoint

Settings Reference

Every field in the settings registry

Agent Framework

Run a turn through CrewAI, AutoGen, LangGraph and other adapters

Engine & Diagnostics

Startup states, the log viewer, and common failure modes