Engine API

The loopback HTTP surface the Desktop engine exposes on 127.0.0.1

The Desktop engine is a small HTTP server on 127.0.0.1 — the same surface the app uses, stable enough to wire an alternate UI or an integration against.

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
)
# The Desktop app talks to an engine exactly like this one over 127.0.0.1.
agent.start("Hello")

Every endpoint binds to 127.0.0.1, and requests from a browser origin the engine does not recognise are refused with 403. Nothing leaves your machine unless the model itself does.

Quick Start

1. Find the port

   The app prints engine :PORT when the engine is healthy. That is the loopback port every route below uses.

2. Probe /health

   GET /health confirms the engine is up and returns the true data directory.

   curl http://127.0.0.1:PORT/health

3. Call a route

   Every response is JSON except /chat (SSE) and /train/progress (SSE).

Routes

GET /frameworks response shape

{
  "available": ["praisonai"],
  "known": ["praisonai", "crewai", "autogen", "langgraph", "agno", "google-adk", "openai-agents", "pydantic-ai"],
  "hints": {
    "crewai": "pip install \"praisonai-frameworks[crewai]\"",
    "…": "…"
  },
  "default": "praisonai",
  "error": null
}

available is always at least ["praisonai"]. When the praisonai wrapper is missing from the engine venv the endpoint still answers 200 with an error string explaining why, so the UI can report capability instead of failing the request.

Media routes

The /media/* routes back the Video tab. Generation is a single synchronous POST /media/video — there is no job store or polling. Full walkthrough: Video generation.

GET /media/video/models lists the catalog with a per-model configured flag:

{
  "ok": true,
  "models": [
    { "id": "replicate/minimax/video-01", "display_name": "MiniMax video-01 (Replicate)", "provider": "replicate", "configured": true },
    { "id": "openai/sora-2", "display_name": "OpenAI Sora 2", "provider": "openai", "configured": false }
  ]
}

POST /media/video accepts prompt and an optional model. The Replicate path returns a hosted url; SDK paths (Sora, Veo) return a data_url and a null url:

// Request
{ "prompt": "A cat playing with yarn", "model": "openai/sora-2" }

// SDK response
{ "id": "vid_…", "path": ".../media-output/videos/vid_….mp4",
  "url": null, "data_url": "data:video/mp4;base64,…", "model": "openai/sora-2", "prompt": "…" }

GET /media/capabilities includes video_models and a video_hint alongside the image fields:

{ "ok": true, "video": true,
  "video_models": [ { "id": "replicate/minimax/video-01", "configured": true } ],
  "video_hint": "Set a provider key … (REPLICATE_API_TOKEN for MiniMax, OPENAI_API_KEY for Sora, GEMINI_API_KEY for Veo)." }

Browser Origin Gate

The engine refuses browser origins it does not recognise, because loopback keeps other machines out but not other pages a user has open.

A loopback address keeps other machines out, but any page open in the user’s browser can reach 127.0.0.1 with a two-line fetch. Matching is on the parsed hostname, so lookalike hosts never slip through.

Allowed responses echo the caller’s own Origin (with Vary: Origin) instead of — Access-Control-Allow-Origin: no longer appears anywhere on the surface.

A refusal carries no CORS headers, so the calling page cannot read the reply either. OPTIONS is gated the same way — a refused preflight returns 403, which is what stops the follow-up request in a real browser.

Status Codes

The engine returns a status that matches the cause, so a client shows the right thing instead of a bare drop.

Bounded Responses

The training routes read from bounded buffers, so a long-running engine cannot grow without limit.

The /health Response

/health reports the true data directory, honouring PRAISONAI_DESKTOP_HOME, XDG_DATA_HOME, and APPDATA — so the app can copy the real path rather than reproduce a default.

{
  "ok": true,
  "version": 2,
  "shell_version": "unknown",
  "agents_version": "1.7.2",
  "data_dir": "/Users/you/Library/Application Support/PraisonAI"
}

Best Practices

Related