Engine API

The Desktop engine is a small HTTP server on loopback — document it here if you’re wiring an alternate UI or an integration.

from praisonaiagents import Agent

# The engine wraps this agent. Everything below is how a UI talks to it.
agent = Agent(
    name="PraisonAI",
    instructions="You are a helpful assistant.",
)
agent.start("Hello")

The engine binds to 127.0.0.1 only — nothing leaves your machine unless the model provider does. There is no auth because there is no remote surface: the loopback socket is the boundary.

Quick Start

Find the port

The shell prints PRAISONAI_PORT=<port> on startup and writes it to the lockfile. Every route below is served from http://127.0.0.1:<port>.

Probe health

GET /health returns {ok, version, data_dir} — the version confirms it’s the engine and not something else on the port.

Stream a chat

POST /chat returns a Server-Sent Events stream. See Chat & Streaming for the event vocabulary.

Routes

Route	Purpose
`GET /health`	Liveness. Returns `ok`, `version`, and `data_dir` (the real data folder, honouring overrides).
`POST /chat`	SSE token stream. Covered in Chat & Streaming.
`POST /approve/{approval_id}`	Approve or deny a pending tool call. Body `{choice}`; a missing body means deny.
`POST /mcp`, `GET /mcp`	List and manage MCP servers (`add` / `remove` / `toggle`).
`GET /search?q=`	Full-text search across transcripts.
`POST /fork/{cid}/{idx}`	Copy a transcript up to message `idx` into a new chat.
`DELETE /messages/{cid}/{idx}`	Drop one exchange (a user turn and its reply).
`POST /project/{cid}`	Set a conversation’s project tag.
`DELETE /chats/{cid}`	Delete a conversation. Reports the delete that actually happened: `200 {"ok": true}` on success (a missing file also counts, since `unlink(missing_ok=True)` succeeds), `400 {"ok": false, "error": …}` on an id that reduces to nothing (e.g. `/chats/..`), and `500 {"ok": false, "error": …}` on an `OSError` from `unlink()` (read-only or permission-changed data dir, a directory blocking the file, a synced folder mid-conflict). Answering `200` for every case is how a conversation closed on screen and reappeared in the sidebar on refresh.
`POST /train/start`	Start a fine-tune. `400` on an invalid method or column set. The single-GPU guard survives an engine restart: an adopted live run still counts, so a second start after a restart is refused with `409` rather than silently starting a second trainer beside the live one.
`POST /train/stop/{run_id}`	Stop a run. Stale-tab safe: stopping a run other than the live one is refused. An adopted run from a previous engine process is stopped through its persisted pid — the process group is signalled on POSIX (`killpg`) and the tree walked on Windows (`taskkill /T`). Quitting the engine runs the same kill before it exits, so the GPU is released whether the caller sends Stop or the engine receives SIGTERM (macOS/Linux only; Windows was already correct via `taskkill /T`).
`GET /train/progress?run=…&cursor=N`	SSE replay-then-follow. `400` on a malformed cursor.
`GET /train/status`	The live run plus its recent metrics.
`GET /train/runs`	Finished-run history (bounded — see caps below). Runs from previous engine processes are included: a live run reappears as `running` (its child process is adopted), an interrupted run reads as `failed`, a finished run reads as `done`.

Status Codes

The engine returns real codes so a client can act, rather than dropping the connection.

Code	When
`400`	Bad input — invalid training config, `?cursor=abc` on `/train/progress`, or an id that reduces to nothing on `DELETE /chats/`.
`404`	No such conversation, message, version, or run.
`409`	A conflict — a training run is already live, or a stop named the wrong run.
`500`	A real server error, such as an unwritable runs directory, or an `OSError` from `unlink()` on `DELETE /chats/` (read-only data dir, a directory blocking the file, a synced folder mid-conflict).

A malformed /train/progress?cursor=abc used to drop the connection with no response. It now returns 400 Bad Request with {"error": "cursor must be an integer"}.

DELETE /chats/{cid} used to answer 200 {"ok": true} for every case, including permission errors and malformed ids. It now returns 400 or 500 with {"ok": false, "error": …} so a UI can react instead of blanking the transcript against a delete that never happened.

Bounded Deques

The training routes read from bounded in-memory buffers; the on-disk log is always the full record.

Buffer	Cap	Served by
Run history	`MAX_HISTORY=50`	`GET /train/runs`
Metric series (per run)	`MAX_METRICS=5000`	`GET /train/status` (last 500)

Best Practices

Read the port, don't guess it

The kernel assigns a free port at bind time. Read it from the PRAISONAI_PORT= line or the lockfile — never hardcode one.

Confirm the version on /health

version distinguishes the engine from anything else that answers on the port. Check it before trusting the rest of the surface.

Reconnect training with a cursor

/train/progress replays from cursor then follows. Store the last cursor you saw so a reconnect resumes exactly where it left off.

Fine-Tuning

The training subsystem the /train/* routes drive

Data & Privacy

Why the loopback socket is the whole boundary

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

Routes

Status Codes

Bounded Deques

Best Practices

Fine-Tuning

Data & Privacy

​Quick Start

​Routes

​Status Codes

​Bounded Deques

​Best Practices

​Related

Fine-Tuning

Data & Privacy

Quick Start

Routes

Status Codes

Bounded Deques

Best Practices

Related