Gateway CLI - PraisonAI

Gateway CLI provides commands for starting, monitoring, and managing the PraisonAI Gateway server and its daemon service.

This page documents the WebSocket multi-agent Gateway daemon (praisonai gateway start). For the UI-Gateway (Pattern C integration), see praisonai serve ui-gateway.

Quick Start

Important: praisonai gateway start runs in the foreground. The daemon is installed by praisonai gateway install (or automatically by praisonai onboard).

Start Gateway

praisonai gateway start

Only one gateway can run per host:port. Stop the existing one with praisonai gateway stop first, or use a different port.

Check Status

praisonai gateway status

Test Health Endpoint

curl http://127.0.0.1:8765/health

Commands

Gateway Management

Command	Description	Example
`praisonai gateway start`	Start the gateway server (foreground)	`praisonai gateway start --port 9000`
`praisonai gateway stop`	Stop a running gateway instance	`praisonai gateway stop --force`
`praisonai gateway status`	Check gateway and daemon status	`praisonai gateway status --daemon-only`
`praisonai gateway channels`	List configured channels	`praisonai gateway channels --json`

Daemon Service

Command	Description	Example
`praisonai gateway install`	Install as OS daemon	`praisonai gateway install --no-start`
`praisonai gateway uninstall`	Remove daemon service	`praisonai gateway uninstall`
`praisonai gateway logs`	Show daemon logs	`praisonai gateway logs -n 100`
`praisonai gateway restart`	Restart the daemon	See restart commands below

Testing & Debugging

Command	Description	Example
`praisonai gateway send`	Send test message	`praisonai gateway send --channel telegram --channel-id 12345 -m "test"`

Command Reference

start
stop
status
channels

praisonai gateway start [OPTIONS]

Options:
  --host TEXT         Host to bind to [default: 127.0.0.1]
  --port INTEGER      Port to listen on [default: 8765 or $GATEWAY_PORT]
  --agents TEXT       Path to agent configuration file
  --config TEXT       Path to gateway.yaml for multi-bot mode

Examples:
  praisonai gateway start
  praisonai gateway start --config gateway.yaml
  praisonai gateway start --agents agents.yaml --port 9000
  GATEWAY_PORT=9000 praisonai gateway start

praisonai gateway stop [OPTIONS]

Options:
  --host TEXT         Gateway host [default: 127.0.0.1]
  --port INTEGER      Gateway port [default: 8765 or $GATEWAY_PORT]
  --force             Force stop (kill process)

Examples:
  praisonai gateway stop
  praisonai gateway stop --port 9000
  praisonai gateway stop --force

praisonai gateway status [OPTIONS]

Options:
  --host TEXT         Gateway host [default: 127.0.0.1]
  --port INTEGER      Gateway port [default: 8765 or $GATEWAY_PORT]
  --daemon-only       Show only daemon status

Examples:
  praisonai gateway status
  praisonai gateway status --port 9000
  praisonai gateway status --daemon-only

praisonai gateway channels [OPTIONS]

Options:
  -c, --config TEXT   Path to gateway.yaml [default: gateway.yaml]
  --json              Output JSON format

Examples:
  praisonai gateway channels
  praisonai gateway channels --config my-gateway.yaml --json

Environment Variables

Variable	Description	Default
`GATEWAY_PORT`	Port for start/stop/status when —port is not passed	`8765`

The GATEWAY_PORT environment variable is used by start, stop, and status commands when the --port option is not explicitly provided. Invalid values silently fall back to 8765.

Single-Instance Enforcement

PraisonAI enforces a single gateway instance per host:port combination using PID locks. Lock File Location: ~/.praisonai/gateway-<safe_host>-<port>.pid The safe_host replaces : and . with _ (so 127.0.0.1 becomes 127_0_0_1). Each host:port combination gets its own lock file, allowing multiple gateways on different ports.

Restart the Daemon

Use these OS-specific commands to restart the daemon service (same commands shown in the onboard Done panel):

macOS
Linux
Windows

launchctl kickstart -k gui/$(id -u)/ai.praison.bot

systemctl --user restart praisonai-bot

schtasks /End /TN PraisonAIGateway && schtasks /Run /TN PraisonAIGateway

Status Output Examples

Healthy Gateway

$ praisonai gateway status
Gateway PID lock: Process 12345 running (127.0.0.1:8765)
Port 127.0.0.1:8765: In use
Daemon service: Running (launchd)
Process ID: 12345
Gateway server: Reachable at http://127.0.0.1:8765/health
  Status: healthy
  Uptime: 3600.5 seconds
  Agents: 2
  Sessions: 1
  Clients: 3
  Channels: 2 configured

Daemon Issues

$ praisonai gateway status
Daemon service: Installed but not running (launchd)
Gateway not reachable at http://127.0.0.1:8765/health

Not Installed

$ praisonai gateway status --daemon-only
Daemon service: Not installed (systemd)

Platform Support

Gateway CLI works across platforms with native daemon integration:

Platform	Service Type	Log Location	Management
macOS	LaunchAgent (`ai.praison.bot`)	`~/.praisonai/logs/bot-stderr.log`	`launchctl kickstart -k gui/$(id -u)/ai.praison.bot`
Linux	systemd user service (`praisonai-bot`)	`journalctl --user -u praisonai-bot`	`systemctl --user restart praisonai-bot`
Windows	Scheduled Task (`PraisonAIGateway`)	Windows Event Log	`schtasks /End /TN PraisonAIGateway && schtasks /Run /TN PraisonAIGateway`

Configuration Files

agents.yaml
gateway.yaml

# Simple agent configuration
agent:
  name: "support"
  instructions: "You are a helpful support agent"
  model: "gpt-4o-mini"
  tools:
    - search_web
  memory: true

# Multi-bot configuration
agents:
  support:
    instructions: "You are a support agent"
    model: "gpt-4o-mini"
  sales:
    instructions: "You are a sales agent"
    model: "claude-3-5-sonnet-20241022"

channels:
  telegram:
    token: "${TELEGRAM_BOT_TOKEN}"
    routing:
      default: support
  discord:
    token: "${DISCORD_BOT_TOKEN}"
    routing:
      default: sales

Best Practices

Use daemon-only for health checks

Use --daemon-only flag when monitoring daemon status in scripts or CI/CD pipelines to avoid gateway connection attempts.

Check logs for troubleshooting

Always check praisonai gateway logs when the daemon is running but gateway is unreachable - this reveals startup errors.

Test channel configuration

Use praisonai gateway send to test channel bot configuration before deploying to production environments.

Monitor daemon status regularly

Set up monitoring that runs praisonai gateway status --daemon-only to detect service failures quickly.

Gateway Server

Gateway architecture and configuration

Troubleshooting

Common gateway issues and solutions

​Quick Start

​Commands

​Gateway Management

​Daemon Service

​Testing & Debugging

​Command Reference

​Environment Variables

​Single-Instance Enforcement

​Restart the Daemon

​Status Output Examples

​Healthy Gateway

​Daemon Issues

​Not Installed

​Platform Support

​Configuration Files

​Best Practices

​Related

Gateway Server

Troubleshooting

Quick Start

Commands

Gateway Management

Daemon Service

Testing & Debugging

Command Reference

Environment Variables

Single-Instance Enforcement

Restart the Daemon

Status Output Examples

Healthy Gateway

Daemon Issues

Not Installed

Platform Support

Configuration Files

Best Practices

Related