Skip to main content
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.
Edit gateway.yaml while the gateway is running and the change applies automatically — no restart, no dropped connections. 
pip install "praisonai[gateway]"
praisonai gateway start --config gateway.yaml
# Edit gateway.yaml and save — reload applies within seconds
The operator edits gateway.yaml; the gateway diffs and hot-reloads without dropping in-flight turns.

​
How It Works

​
Quick Start

1

Install the gateway extra

pip install "praisonai[gateway]"
This installs watchdog>=3.0.0 for event-driven file watching. The gateway falls back to mtime polling when watchdog is not installed.
2

Edit gateway.yaml — auto-detected

# gateway.yaml
agents:
  assistant:
    instructions: "You are a helpful assistant."

gateway:
  reload_drain_timeout: 10.0   # seconds to drain a channel on reload
Save the file. The running gateway detects the change within the watchdog debounce window and reloads automatically.
3

Trigger a reload manually via SIGHUP

systemctl reload praisonai-gateway
# or
kill -HUP $(pgrep -f 'praisonai gateway start')
SIGHUP runs the same reload_config path as a file change — no shutdown. Best-effort on Windows (SIGHUP unavailable, see fallback below).
4

Tune the drain window

gateway:
  reload_drain_timeout: 10.0   # seconds to drain a channel on reload
  # If unset, falls back to gateway.drain_timeout
  drain_timeout: 5.0
reload_drain_timeout controls how long a channel restart waits for in-flight turns to finish. If unset, it falls back to drain_timeout.
5

Watch the audit log

reload applied: agents; restart[telegram]
Each line tells you exactly what changed and which channels were restarted.

​
What Triggers a Reload

Two paths trigger the same reload_config routine:
TriggerMechanism
File editwatchdog filesystem event (if installed) or mtime polling every 5 s
Manualkill -HUP <pid> or systemctl reload praisonai-gateway
Both paths debounce rapid consecutive writes before applying — a burst of saves from an editor doesn’t cause multiple reloads.
With watchdog installed, filesystem events (inotify on Linux, FSEvents on macOS, ReadDirectoryChangesW on Windows) trigger a reload within the debounce window (default 1 s) automatically — no signal required.

​
What Gets Restarted

Config changeAction
Agent instructions / model / toolsRecreate affected agents in-place
Channel token or platform argsDrain + restart that single channel
Gateway host / portFull restart (WebSocket server stays up)
Scheduler / routes / guardrailsFull channel restart
The WebSocket server itself keeps running throughout — connected clients are not disconnected unless their channel is restarting.

​
Drain-Coordinated Restart

Channel restarts drain in-flight turns before bouncing, using the same drain_timeout coroutine as shutdown. 
# gateway.yaml
gateway:
  drain_timeout: 30         # shutdown drain budget
  reload_drain_timeout: 10  # reload-specific budget (wins over drain_timeout for reloads)

​
Windows / No-Watchdog Fallback

EnvironmentFile watchingSIGHUP
Linux / macOS + watchdog installedEvent-driven (instant)Supported
Linux / macOS without watchdogmtime polling (5 s interval)Supported
Windows + watchdog installedEvent-driven (instant)Not available
Windows without watchdogmtime polling (5 s interval)Not available

​
YAML Reference

gateway:
  drain_timeout: 30           # shutdown drain window (seconds)
  reload_drain_timeout: 10    # reload drain window; falls back to drain_timeout if unset

​
Rotating the shared secret during reload

The reload path also picks up changes to gateway.auth_token. When the reloaded config carries a new secret, the gateway adopts it inline and — by default — revokes every live session still on the old secret. Adopting a new secret has three side effects:
  1. self.config.auth_token is updated to the new value.
  2. GATEWAY_AUTH_TOKEN in the environment is updated so all auth paths (HTTP, magic-link, WS) read the same value.
  3. Stale live sessions are force-closed with WebSocket close code 4001 and reason credentials_rotated — unless revoke_on_secret_rotation: false.
Situation in reloaded gateway.yamlOutcome
auth_token absentFull no-op. Running secret + live sessions untouched.
auth_token present, resolves to empty ("" or unset ${VAR})Running secret kept. A warning is logged.
auth_token present, same as running secretNo-op (0 revoked).
auth_token present, differsAdopt new secret, export to env, revoke stale sessions (unless opted out).
auth_token not a string (e.g. 12345)Coerced to str, avoiding a mid-reload TypeError.
revoke_on_secret_rotation: falseSecret adopted for new connections only; live sessions stay on the old secret.
revoke_on_secret_rotation: "false" / "0" / "no" / "off"Also disables revocation.
revoke_on_secret_rotation truthy (default)Every session on the old secret is force-closed with (4001, "credentials_rotated").

Gateway Credential Rotation

Client-side recovery, the rotation mermaid, and the full behaviour matrix

​
Optional Dependency

pip install "praisonai[gateway]" adds watchdog>=3.0.0 for event-driven watching. Without it the gateway uses mtime polling (5 s interval). Both modes apply the same reload logic — the only difference is detection latency.
On Windows, use the file-watch path only. kill -HUP is not available; trigger reloads by saving the config file.

​
Reading the Log Line

A concise summary is logged after each reload: 
reload applied: agents; restart[telegram]
PartMeaning
agentsAgent definitions were updated (no channel restart)
restart[telegram]The telegram channel was restarted with drain
restart[telegram,discord]Multiple channels were restarted
(empty)Config was identical; no changes applied

​
Best Practices

Without watchdog, the gateway polls every 5 seconds. With watchdog installed (pip install "praisonai[gateway]"), changes are detected within milliseconds via filesystem events.
Apply config changes to one channel (e.g. a staging Telegram bot) before rolling to all channels. The per-channel restart scope makes this safe — the reload touches only what changed.
A short reload drain (5s–10s) keeps channel restarts fast. A longer shutdown drain (15s–30s) gives in-flight conversations more time to complete. Keep them separate.
A bad config (YAML syntax error, missing required field) is rejected at reload time — the gateway keeps the last-known-good config and logs an error. Test with praisonai gateway validate gateway.yaml before saving to the watched path.
Log lines like reload applied: agents; restart[telegram] are your audit trail. Ship them to your log aggregator and alert on unexpected full restarts.
After updating gateway.yaml in a deploy pipeline, send kill -HUP $(cat /var/run/praisonai.pid) to trigger reload without downtime. No restart, no new process.

Gateway

WebSocket control plane overview and full YAML reference

Gateway CLI

CLI commands for starting, stopping, and managing the gateway

Gateway Reliability

Graceful drain and admission control presets

Gateway Graceful Drain

Drain-only knob — full reference and sequence diagram

Credential Rotation

Revoke live sessions when the shared secret rotates