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.
from praisonaiagents import Agent

agent = Agent(name="reload-agent", instructions="Hot-reload gateway configuration without downtime.")
agent.start("Reload the gateway configuration without restarting the service.")
The gateway diffs gateway.yaml against the running config and restarts only affected agents or channels. The WebSocket server keeps running. 
# gateway.yaml
agents:
  assistant:
    instructions: "You are a helpful assistant."

praisonai gateway run gateway.yaml
# Edit agents.assistant.instructions and save — only agents reload (~5s)
The user edits gateway.yaml on disk; the watcher diffs changes and reloads only affected agents or channels while the WebSocket server stays up.

​
How It Works

​
Quick Start

1

Run the gateway

praisonai gateway run gateway.yaml
2

Edit live

Change agent instructions or a single channel token in gateway.yaml and save. The watcher applies a selective reload within ~5 seconds (1s debounce).
3

Trigger reload manually with SIGHUP

Send SIGHUP to reload without editing a file — useful for orchestration scripts and systemd:
# Find the gateway pid, then:
kill -HUP $(pgrep -f "praisonai gateway")

# Or under systemd:
systemctl reload praisonai-gateway

​
Event-driven vs Polling

The watcher prefers event-driven file notifications via the optional watchdog package and falls back gracefully to mtime polling when watchdog is unavailable or an observer cannot start.
ModeHow it worksWhen used
Event-drivenOS file-system events via watchdogwatchdog>=3.0.0 installed
mtime pollingPeriodic stat check every 5swatchdog not installed or observer fails
Both modes apply the same 1s debounce to coalesce rapid saves. Install watchdog for faster reload detection: 
pip install "praisonai[gateway]"
# or
pip install "praisonai[all]"
watchdog is optional — without it, polling continues exactly as before. Install it only when faster reaction times matter.

​
Operator-triggered Reload via SIGHUP

start_with_config installs a SIGHUP handler that runs the same reload_config path as a file-change reload — no shutdown, no dropped connections. Reload via SIGHUP is best-effort — it is silently skipped on platforms without SIGHUP support (e.g. Windows).

​
Drain-coordinated Channel Restart

When a reload triggers a channel restart, the gateway drains in-flight turns before bouncing the channel — no mid-conversation cuts. The drain window for reload-triggered restarts is controlled by a new YAML key: 
gateway:
  reload_drain_timeout: 10   # seconds; falls back to drain_timeout if unset

​
Restart Scope

Changed sectionEffect
agents.*Recreate agents only — channels keep running
channels.<name>.*Restart only that channel
provider.*, guardrails.*Recreate agents
scheduler.*, routes.*, routing.*Full channel restart
Entire channels sectionFull channel restart
Invalid YAML on saveKeep last-known-good config
Full restart stops and starts all channels but does not restart the WebSocket server — connected clients stay connected.

​
Observability

Reloads log a concise summary line on completion: 
reload applied: agents; restart[telegram]
The format is reload applied: <changed-sections>; restart[<channels>]. Grep for reload applied to trace all reloads in your log stream.

​
Tuning

SettingDefaultDescription
Poll interval5.0sHow often the mtime watcher checks the file
Debounce1.0sWait after last write before applying
gateway.reload_drain_timeoutfalls back to gateway.drain_timeoutBounded drain window before a reload-triggered channel restart
Backward compatibility: Leaving reload_drain_timeout unset preserves the prior immediate-restart behaviour. Not installing watchdog keeps polling as before. This is a fully additive change.

​
Best Practices

Changing agents.* avoids dropping live Telegram/Discord sessions.
Edit one channel block to restart only that platform.
Invalid saves are ignored — the previous config keeps running.
Add ExecReload=kill -HUP $MAINPID to your systemd unit so systemctl reload triggers a drain-coordinated reload without stopping the process.

Bot Gateway

Gateway server overview

Gateway Channel Supervision

Self-healing channels

Code-Skew Guard

Detect in-place code updates and refuse hot operations until the process restarts.

Gateway Reliability Preset

One switch to compose drain + admission control