How PraisonAIUI (aiui) connects to praisonai-package — the agent runtime, gateway, and CLI. For generic UI hosting see Agent UI host.
aiui
praisonai-package
| Layer | Repo | Role |
|-------|------|------|
| Agent runtime | praisonai-agents | Agent, tools, memory, streaming |
praisonai-agents
Agent
| Gateway, jobs, CLI | praisonai | WebSocket /ws, /api/v1/runs, praisonai claw |
praisonai
/ws
/api/v1/runs
praisonai claw
| Dashboard UI | PraisonAIUI | dashboard.js, @aiui.page, layout protocol |
dashboard.js
@aiui.page
| Work tracking | praisonai-platform | Issues API (optional board data source) |
praisonai-platform
Canonical app: praisonai-package → src/praisonai/praisonai/claw/default_app.py.
src/praisonai/praisonai/claw/default_app.py
Use when: local dev, full dashboard, agents registered in Python.
Use when: you need WebSocket gateway protocol and dashboard on one port.
| Service | Default port | Endpoints |
|---------|--------------|-----------|
| praisonai gateway start | 8765 | ws://…/ws, /health, /info |
praisonai gateway start
ws://…/ws
/health
/info
| praisonai claw or aiui run | 8082 | Dashboard, /run SSE, /api/* |
aiui run
/run
/api/*
Use when: gateway runs headless; UI is a separate process. Point chat at gateway via provider config or run AIUIGateway instead.
AIUIGateway
Or via host bootstrap:
| Endpoint | Purpose |
|----------|---------|
| POST /run | Stream agent run (SSE) |
POST /run
| GET /sessions, POST /sessions | Session CRUD |
GET /sessions
POST /sessions
| GET /agents, /api/agents/definitions | Agent list / CRUD |
GET /agents
/api/agents/definitions
| GET /api/health | Sidebar health slot |
GET /api/health
| Backend | Base path | When |
|---------|-----------|------|
| aiui JobsFeature | /api/jobs | Default; in-process job store |
JobsFeature
/api/jobs
| praisonai jobs server | /api/v1/runs | Standalone praisonai jobs / FastAPI router |
praisonai jobs
Configure the dashboard jobs view:
/ui-config.json exposes jobs: { apiBase, backend } for jobs.js.
/ui-config.json
jobs: { apiBase, backend }
jobs.js
Response shapes: both return { jobs, total }. Praison uses job_id; aiui uses id. The jobs view normalises either field.
{ jobs, total }
job_id
id
| Action | aiui | praisonai |
|--------|------|-----------|
| List | GET /api/jobs | GET /api/v1/runs |
GET /api/jobs
GET /api/v1/runs
| Detail | GET /api/jobs/{id} | GET /api/v1/runs/{id} |
GET /api/jobs/{id}
GET /api/v1/runs/{id}
| Cancel | POST /api/jobs/{id}/cancel | POST /api/v1/runs/{id}/cancel |
POST /api/jobs/{id}/cancel
POST /api/v1/runs/{id}/cancel
| Stream | GET /api/jobs/{id}/stream | GET /api/v1/runs/{id}/stream |
GET /api/jobs/{id}/stream
GET /api/v1/runs/{id}/stream
| Delete | DELETE /api/jobs/{id} | Not on package router |
DELETE /api/jobs/{id}
Split jobs server (optional): proxy aiui /api/jobs/* to an external jobs host:
/api/jobs/*
Use when the dashboard and jobs server run on different ports. Prefer set_jobs_backend("praisonai") when the browser can call /api/v1/runs on the same origin.
set_jobs_backend("praisonai")
| Path | Use |
|------|-----|
| POST /api/v1/agents/{id}/invoke | Sync invoke (n8n, scripts) — package agent_invoke.py |
POST /api/v1/agents/{id}/invoke
agent_invoke.py
| POST /run | Streaming chat — dashboard chat page |
Same agents if registered on both surfaces; different protocols.
| GET /__praisonai__/discovery | Serve-mode capability discovery |
GET /__praisonai__/discovery
| GET /health, GET /info | Gateway liveness and metadata |
GET /health
GET /info
| GET /api/gateway/status | aiui gateway feature status |
GET /api/gateway/status
See Feature Explorer page in dashboard for live probes.
Under praisonaiagents/ui/:
praisonaiagents/ui/
| Protocol | Purpose |
| A2A | Agent cards, /.well-known/agent.json, external agent hosts |
/.well-known/agent.json
| AG-UI | CopilotKit-style event stream (POST /agui) |
POST /agui
| A2UI | Declarative surfaces in chat/canvas |
Dashboard shell remains the ops console for praisonai claw. Use A2A/AG-UI/A2UI when embedding in other products.
| System | Location | Purpose |
|--------|----------|---------|
| Agent plugins | ~/.praisonai/plugins/ | Python agent extensions (praisonaiagents.plugins) |
~/.praisonai/plugins/
praisonaiagents.plugins
| Dashboard plugins | ~/.praisonai/dashboard-plugins/ | JS tabs + manifest.json for aiui shell |
~/.praisonai/dashboard-plugins/
manifest.json
Do not mix folders. Agent plugins extend runtime; dashboard plugins extend UI tabs only.
Loads jobs.js, auth.js, api.js into the plugin chain and maps them in BUILTIN_VIEWS. Enable only what your deployment exposes.
auth.js
api.js
BUILTIN_VIEWS
Neither repo ships Hermes-style Kanban. Options:
1. aiui.board() — columns from @aiui.page handler (jobs by status, custom data).
aiui.board()
2. praisonai-platform issues — map issue status → board columns (see examples/python/platform-board/). Set PRAISONAI_PLATFORM_URL and PRAISONAI_PLATFORM_WORKSPACE_ID (default workspace default); issues are fetched from GET /api/v1/workspaces/{workspace_id}/issues.
status
examples/python/platform-board/
PRAISONAI_PLATFORM_URL
PRAISONAI_PLATFORM_WORKSPACE_ID
default
GET /api/v1/workspaces/{workspace_id}/issues
3. dashboard-plugins — rich JS via registerView + sdk.createBoard.
dashboard-plugins
registerView
sdk.createBoard
Advanced board UX (drag-drop, WebSocket sync) is deferred — use polling via sdk.createBoard({ pollMs }) or a custom plugin.
sdk.createBoard({ pollMs })
After praisonai claw or aiui run with package bridges:
~/.praisonai/sessions/
modules
jobs
/api/dashboard/plugins
auth
api
integration.py
examples/python/praisonai-claw-board/