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`

praisonai-bot gateway status is safe to run on any platform. On Windows, if PID-lock inspection can’t complete, the /health probe still runs and shows the authoritative gateway status.

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.

Corporate proxies / SSL-inspecting networks. A preflight failure caused only by SSLCertVerificationError / certificate_verify_failed does not abort the start — the token is usually valid and the runtime adapter’s SSL stack is more permissive. The gateway prints a one-line warning naming the three CA-bundle env vars and continues.If any channel also fails for a non-SSL reason (bad token, unreachable host, timeout), preflight still hard-aborts — fix that channel or pass --no-preflight. See Corporate CA bundle (SSL-inspecting networks).

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        ✗  SSL certificate verify failed (network/proxy?). Token may still be valid. Try SSL_CERT_FILE=/path/to/corp-ca.pem or gateway start --no-preflight
discord      ✓  @MySupport

A non-SSL failure keeps the bare error string:

$ 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

Corporate CA bundle (SSL-inspecting networks)

On networks that intercept TLS with a corporate CA (proxy / MITM), the probe’s HTTP client can reject the certificate chain even though the token is valid and the runtime adapter connects fine. Preflight classifies these SSL cert-verify failures separately and soft-fails when they are the only failures.

$ praisonai gateway start --config gateway.yaml
slack        ✗  SSL certificate verify failed (network/proxy?). Token may still be valid. Try SSL_CERT_FILE=/path/to/corp-ca.pem or gateway start --no-preflight

Pre-flight found SSL certificate-verify failures only (likely a proxy/MITM
network). Tokens may still be valid — continuing start. Set SSL_CERT_FILE /
REQUESTS_CA_BUNDLE / PRAISONAI_SSL_CA_BUNDLE to your corporate CA, or pass
--no-preflight to skip this check.

The probe decides its action from the mix of failures:

Probe outcome (across all channels)	Preflight action
All channels `ok`	Start proceeds silently.
≥1 channel fails with a non-SSL error (token, network, timeout)	Hard-abort, exit `1`.
All failures are SSL cert-verify only	Soft-fail — print the SSL warning, continue to start, exit `0`.
Mixed: ≥1 SSL cert-verify and ≥1 token/network failure	Hard-abort (the non-SSL failure wins), exit `1`.

Only certificate-verify failures soft-fail. Other TLS handshake failures — WRONG_VERSION_NUMBER, NO_SHARED_CIPHER, HANDSHAKE_FAILURE — still hard-abort, because they usually indicate a real bug that also breaks the channel at runtime.

Point the probe at your corporate CA with one of three env vars, highest precedence first:

Variable	Precedence	Behaviour
`PRAISONAI_SSL_CA_BUNDLE`	Highest — explicit PraisonAI override	Overrides pre-existing `SSL_CERT_FILE` and `REQUESTS_CA_BUNDLE` for the probe.
`REQUESTS_CA_BUNDLE`	Middle	Used only if `PRAISONAI_SSL_CA_BUNDLE` is unset. Left alone when the winner came from elsewhere.
`SSL_CERT_FILE`	Lowest — Python default	Read by Python’s default `ssl` context (used by `aiohttp`). Used only if the two above are unset.

export PRAISONAI_SSL_CA_BUNDLE=/path/to/corp-ca.pem
praisonai gateway start --config gateway.yaml

A configured-but-missing path warns and leaves the SSL env vars untouched:

Warning: CA bundle path '<path>' does not exist — SSL_CERT_FILE / REQUESTS_CA_BUNDLE not updated for probe.

The runtime adapter reads the same three env vars, so setting one fixes both the preflight probe and long-lived channel connections.

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.

PID-Lock Status Reference

praisonai gateway status prints one PID-lock line before the /health probe. Look up any line you see:

Line printed	When
`Gateway PID lock: Process <pid> running (<host>:<port>)`	Lock file exists, PID responds to `os.kill(pid, 0)`
`Gateway PID lock: Stale lock (process <pid> not running)`	Lock file exists, PID no longer responds (including Windows `SystemError`/`ValueError` cases)
`Gateway PID lock: No lock file found`	No lock file at `~/.praisonai/gateway-<safe_host>-<port>.pid`
`PID lock status: Utilities not available`	`port_utils` import failed (`ImportError`)
`PID lock status: Unavailable (<error>)`	Any other unexpected exception during PID-lock inspection; the `/health` probe still runs

The port line (Port <host>:<port>: In use / Available) follows the same section unless PID-lock inspection fails, in which case the single PID lock status: Unavailable (<error>) line replaces both.

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

PID Lock Unavailable (Windows)

$ praisonai-bot gateway status --port 18789
PID lock status: Unavailable (kill returned a result with an exception set)
Gateway Status: healthy
  Uptime: 11.4s
  Agents: 1
  Sessions: 0
  Clients: 0

On Windows, os.kill(pid, 0) can raise SystemError. From PraisonAI ≥ v4.6.141 the PID-lock inspection is advisory only — this line replaces Gateway PID lock: … / Port …: … when the check fails, and the /health probe still runs so you still see the real status.

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

​Corporate CA bundle (SSL-inspecting networks)

​Token resolution

​Per-channel timeout

​Exit codes

​When to use which

​Environment Variables

​Single-Instance Enforcement

​PID-Lock Status Reference

​Restart the Daemon

​Status Output Examples

​Healthy Gateway

​PID Lock Unavailable (Windows)

​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

Corporate CA bundle (SSL-inspecting networks)

Token resolution

Per-channel timeout

Exit codes

When to use which

Environment Variables

Single-Instance Enforcement

PID-Lock Status Reference

Restart the Daemon

Status Output Examples

Healthy Gateway

PID Lock Unavailable (Windows)

Daemon Issues

Not Installed

Platform Support

Configuration Files

Best Practices

Related