Unified Serve - PraisonAI

All PraisonAI servers are accessible through praisonai serve <type> - one command to start any server.

Quick Start

Start Agents Server

praisonai serve agents --port 8000

Start Gateway Server

praisonai serve gateway --port 8765

Start All-in-One Server

praisonai serve unified --port 8765

All Serve Commands

Run praisonai serve to see all available options with descriptions.

Command	Protocol	Port	Description
`praisonai serve agents`	HTTP	8000	Agents as HTTP REST API
`praisonai serve gateway`	WebSocket	8765	Multi-agent real-time coordination
`praisonai serve mcp`	STDIO/SSE	8080	MCP server for Claude/Cursor
`praisonai serve acp`	STDIO	-	Agent Client Protocol for IDEs
`praisonai serve lsp`	STDIO	-	Language Server Protocol
`praisonai serve ui`	HTTP	8082	Chainlit web interface
`praisonai serve rag`	HTTP	9000	RAG query server
`praisonai serve registry`	HTTP	7777	Package registry server
`praisonai serve docs`	HTTP	3000	Documentation preview
`praisonai serve scheduler`	Background	-	Job scheduler daemon
`praisonai serve recipe`	HTTP	8765	Recipe runner server
`praisonai serve a2a`	JSON-RPC	8001	Agent-to-Agent protocol
`praisonai serve a2u`	SSE	8002	Agent-to-User event stream
`praisonai serve unified`	HTTP/SSE	8765	All providers combined
`praisonai serve openai`	HTTP/SSE	8765	OpenAI API compatibility layer

Server Details

Agents
Gateway
MCP
Recipe
Unified

HTTP REST API for agents.

praisonai serve agents --file agents.yaml --port 8000

Options:

Option	Default	Description
`--host`	`127.0.0.1`	Host to bind to
`--port`	`8000`	Port to bind to
`--file`	`agents.yaml`	Agents YAML file
`--reload`	`false`	Enable hot reload
`--api-key`	-	API key for auth

Test with curl:

curl http://localhost:8000/

WebSocket server for multi-agent coordination.

praisonai serve gateway --port 8765 --agents agents.yaml

Options:

Option	Default	Description
`--host`	`127.0.0.1`	Host to bind to
`--port`	`8765`	Port to bind to
`--agents`	-	Agents YAML file

Connect with WebSocket:

const ws = new WebSocket('ws://localhost:8765');

MCP server for Claude Desktop and Cursor.

praisonai serve mcp --transport sse --port 8080

Options:

Option	Default	Description
`--host`	`127.0.0.1`	Host to bind to
`--port`	`8080`	Port to bind to
`--transport`	`stdio`	Transport: stdio, sse
`--name`	-	Server name from config

Recipe runner server.

praisonai serve recipe --port 8765 --reload

Options:

Option	Default	Description
`--host`	`127.0.0.1`	Host to bind to
`--port`	`8765`	Port to bind to
`--config`	-	Config file path
`--reload`	`false`	Enable hot reload

All providers in one server.

praisonai serve unified --port 8765

Options:

Option	Default	Description
`--host`	`127.0.0.1`	Host to bind to
`--port`	`8765`	Port to bind to
`--file`	`agents.yaml`	Agents YAML file
`--reload`	`false`	Enable hot reload

Includes: agents-api, recipe, mcp, a2a, a2u

Authentication

Set --api-key to require a key on every request. Send it with either header.

# Start with a key
praisonai serve agents --api-key $API_KEY --host 0.0.0.0

A public bind requires a key. praisonai serve agents exits with SystemExit if --host is not 127.0.0.1 / localhost / ::1 and neither --api-key nor PRAISONAI_SERVE_API_KEY is set — because POST /agents can execute YAML-defined tools. See Serve Agents Authentication.

# Authorization header
curl -H "Authorization: Bearer $API_KEY" http://localhost:8000/agents

# X-API-Key header
curl -H "X-API-Key: $API_KEY" http://localhost:8000/agents

Both headers are equivalent and use constant-time comparison. Missing or wrong keys return 401 {"error": "Unauthorized"}. These paths stay public even when --api-key is set:

Path	Purpose
`/health`	Health check
`/`	Root info
`/.well-known/agent.json`	A2A agent card
`/__praisonai__/*`	Discovery endpoints

How It Works

Common Patterns

Development with Hot Reload

praisonai serve agents --reload --port 8000

Changes to agents.yaml auto-reload the server.

Production with Auth

praisonai serve agents --api-key $API_KEY --host 0.0.0.0

Bind to all interfaces with API key authentication.

Multiple Servers

# Terminal 1: Agents API
praisonai serve agents --port 8000

# Terminal 2: Gateway
praisonai serve gateway --port 8765

# Terminal 3: MCP
praisonai serve mcp --transport sse --port 8080

Run different server types simultaneously.

All-in-One Development

praisonai serve unified --port 8765 --reload

Single server with all providers for development.

Discovery Endpoint

All HTTP servers expose /__praisonai__/discovery for endpoint discovery.

curl http://localhost:8000/__praisonai__/discovery

{
  "server_name": "praisonai-agents",
  "version": "1.0.0",
  "providers": [...],
  "endpoints": [...]
}

Best Practices

Use Unified for Development

Start with praisonai serve unified during development to access all providers. Split into separate servers for production.

Always Set Host in Production

Use --host 0.0.0.0 to accept external connections. Default 127.0.0.1 only accepts local connections.

Enable Auth for Public Servers

Always use --api-key when exposing servers publicly. Never run unauthenticated servers on public networks.

Agents Server

HTTP REST API details

Gateway Server

WebSocket coordination

MCP Server

Claude Desktop integration

A2A Server

Agent-to-Agent protocol

​Quick Start

​All Serve Commands

​Server Details

​Authentication

​How It Works

​Common Patterns

​Discovery Endpoint

​Best Practices

​Related

Agents Server

Gateway Server

MCP Server

A2A Server

Quick Start

All Serve Commands

Server Details

Authentication

How It Works

Common Patterns

Discovery Endpoint

Best Practices

Related