Gateway CLI - PraisonAI

The gateway now ships in the praisonai-bot package. praisonai serve gateway still works exactly as documented here; for a standalone install see praisonai-bot Migration.

from praisonaiagents import Agent

agent = Agent(name="gateway-cli-agent", instructions="Manage gateway via CLI commands.")
agent.start("Start the gateway and show its status.")

Gateway CLI provides commands for starting, monitoring, and managing the PraisonAI Gateway server and its daemon service, including channel supervision controls for resilient bot management.

# gateway.yaml
agents:
  assistant:
    instructions: "You are a helpful AI assistant."
    model: gpt-4o-mini

channels:
  telegram:
    token: "${TELEGRAM_BOT_TOKEN}"
    platform: telegram

praisonai gateway start --config gateway.yaml

This page documents the WebSocket multi-agent Gateway daemon. The canonical CLI command is praisonai-bot gateway start (bot-tier package). When the praisonai wrapper is co-installed, praisonai gateway start works as a convenience alias.For the UI-Gateway (Pattern C integration), see praisonai serve ui-gateway.For detailed information about channel resilience and operator controls, see Channel Supervision.

The user runs praisonai gateway start; the CLI launches the daemon, supervises channels, and keeps the WebSocket gateway reachable.

How It Works

Quick Start

The gateway runs in the foreground. The daemon is installed by praisonai-bot gateway install (or automatically by praisonai-bot onboard).

Start Gateway

# Canonical (bot-tier, no wrapper required)
praisonai-bot gateway start

# Wrapper alias (requires pip install praisonai)
praisonai gateway start

Only one gateway can run per host:port. Stop the existing one with praisonai-bot 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 doctor`	Validate channel credentials before start (pre-flight)	`praisonai gateway doctor --config gateway.yaml`
`praisonai gateway channels`	List configured channels (add `--probe` to check creds)	`praisonai gateway channels --probe`

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

Channel Control

Command	Description	Example
`praisonai gateway pause`	Pause a channel	`praisonai gateway pause telegram`
`praisonai gateway resume`	Resume a paused channel	`praisonai gateway resume telegram`
`praisonai gateway reconnect`	Force reconnect a channel	`praisonai gateway reconnect telegram`

Inbound Hooks

Command	Description	Example
`praisonai gateway hooks add <path>`	Register an inbound webhook trigger	`praisonai gateway hooks add gmail --agent assistant`
`praisonai gateway hooks list`	List registered hooks	`praisonai gateway hooks list`
`praisonai gateway hooks remove <path>`	Remove an inbound hook	`praisonai gateway hooks remove gmail`

See Gateway Inbound Hooks for full details.

Testing & Debugging

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

Command Reference

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
  --reliability [production|default|off]
                                  Reliability preset — composes drain + admission.
                                  production (15s drain + CPU-scaled admission),
                                  default (5s drain, no admission), off (immediate teardown).
                                  Overrides `reliability:` from YAML but is overridden
                                  by explicit --drain-timeout / --max-concurrent-runs.
  --preflight / --no-preflight    Validate channel credentials before
                                  starting (fail fast on bad tokens)
                                  [default: --preflight]

Examples:
  praisonai gateway start
  praisonai gateway start --config gateway.yaml
  praisonai gateway start --agents agents.yaml --port 9000
  praisonai gateway start --config gateway.yaml --no-preflight
  praisonai gateway start --config gateway.yaml --reliability production
  GATEWAY_PORT=9000 praisonai gateway start

--reliability overrides the reliability: / gateway.reliability: key in YAML. See Gateway Reliability Presets for profile details and precedence rules.

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 stop performs a graceful drain — it waits up to 10 seconds for in-flight agent turns and queued messages before closing. Use --force to skip the drain and terminate immediately.

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 doctor [OPTIONS]

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

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

praisonai gateway channels [OPTIONS]

Options:
  -c, --config TEXT   Path to gateway.yaml [default: gateway.yaml]
  --json              Output JSON format
  --probe             Probe each channel's credentials

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

praisonai gateway pause <channel-name> [OPTIONS]

Options:
  --url TEXT    Gateway WebSocket URL [default: ws://127.0.0.1:8765]

Examples:
  praisonai gateway pause telegram
  praisonai gateway pause discord --url ws://localhost:8000

praisonai gateway resume <channel-name> [OPTIONS]

Options:
  --url TEXT    Gateway WebSocket URL [default: ws://127.0.0.1:8765]

Examples:
  praisonai gateway resume telegram
  praisonai gateway resume discord --url ws://localhost:8000

praisonai gateway reconnect <channel-name> [OPTIONS]

Options:
  --url TEXT    Gateway WebSocket URL [default: ws://127.0.0.1:8765]

Examples:
  praisonai gateway reconnect telegram
  praisonai gateway reconnect discord --url ws://localhost:8000

Pre-flight credential check

praisonai gateway doctor validates every channel’s token before the gateway starts, so a bad or expired credential fails fast with a precise per-channel reason instead of disappearing into the supervisor’s silent reconnect loop.

Examples

Quick health check:

$ praisonai gateway doctor
telegram     ✓  @my_support_bot
slack        ✗  invalid_auth (token expired)
discord      ✓  @MySupport

CI-friendly JSON:

$ praisonai gateway doctor --json
{
  "telegram": {"ok": true,  "platform": "telegram", "bot_username": "my_support_bot"},
  "slack":    {"ok": false, "platform": "slack",    "error": "invalid_auth"},
  "discord":  {"ok": true,  "platform": "discord",  "bot_username": "MySupport"}
}

Same verdict via the listing command:

$ praisonai gateway channels --probe

Pre-flight gate on start

praisonai gateway start runs the same probe automatically before launch when invoked with --config gateway.yaml:

$ praisonai gateway start --config gateway.yaml
slack        ✗  invalid_auth (token expired)

Pre-flight check failed — aborting start. Fix the channel credentials
above or pass --no-preflight to skip.

To bypass during local dev (e.g. flaky probe network):

praisonai gateway start --config gateway.yaml --no-preflight

Token resolution

The probe loads ~/.praisonai/.env first, so ${VAR} placeholders set by praisonai onboard resolve exactly like they do at runtime — doctor, channels --probe, and start --preflight all share the same token-resolution path.

Per-channel timeout

Each probe is bounded by a 15-second deadline; a stuck adapter is reported as "probe timed out after 15s" and does not hang the aggregate.

Exit codes

Outcome	Exit code
All channels probe OK	`0`
Any channel fails	`1`
`gateway doctor` with no channels configured	`0`

When to use which

Programmatic check (Python)

import asyncio
from praisonai.bots import Bot, BotOS

botos = BotOS(
    bots=[
        Bot("telegram", token="..."),
        Bot("slack",    token="..."),
    ],
    enable_supervision=False,
)

results = asyncio.run(botos.probe_all(timeout=15.0))
for platform, r in results.items():
    print(platform, "ok" if r.ok else r.error)

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

​How It Works

​Quick Start

​Commands

​Gateway Management

​Daemon Service

​Channel Control

​Inbound Hooks

​Testing & Debugging

​Command Reference

​Pre-flight credential check

​Examples

​Pre-flight gate on start

​Token resolution

​Per-channel timeout

​Exit codes

​When to use which

​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

How It Works

Quick Start

Commands

Gateway Management

Daemon Service

Channel Control

Inbound Hooks

Testing & Debugging

Command Reference

Pre-flight credential check

Examples

Pre-flight gate on start

Token resolution

Per-channel timeout

Exit codes

When to use which

Environment Variables

Single-Instance Enforcement

Restart the Daemon

Status Output Examples

Healthy Gateway

Daemon Issues

Not Installed

Platform Support

Configuration Files

Best Practices

Related