Gateway Config Reload

Hot-reload gateway.yaml without dropping in-flight turns — SIGHUP, watchdog, drain-coordinated restart

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

sequenceDiagram
    participant Op as Operator
    participant FS as gateway.yaml
    participant GW as Gateway
    participant Ch as Channel (bot)
    Op->>FS: edit gateway.yaml
    FS-->>GW: watchdog event (or mtime poll)
    Op->>GW: kill -HUP pid (equivalent)
    GW->>GW: diff config
    GW->>Ch: drain(reload_drain_timeout)
    Ch-->>GW: in-flight turns finished
    GW->>Ch: restart with new config
    GW-->>Op: log "reload applied: agents; restart[telegram]"

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:

Both paths debounce rapid consecutive writes before applying — a burst of saves from an editor doesn’t cause multiple reloads.

kill -HUP <gateway-pid>
# or via systemd
systemctl reload praisonai-gateway

What Gets Restarted

The WebSocket server itself keeps running throughout — connected clients are not disconnected unless their channel is restarting.

To pre-check what a path will do, call classify_reload(path) — see Programmatic reload-scope classification.

Reloadable Sections › identity:

Editing the top-level identity: block reconciles the cross-platform identity resolver on the next reload, so paired users keep one continuous session across channels (#3020).

Reconciliation runs before channels (re)start, via _reconcile_identity_resolver(), so freshly restarted bots pick up the new resolver rather than a stale one. The gateway records the block’s (enabled, store) signature via _signature_for_identity() — an unchanged signature preserves the live resolver so the link cache and store handle survive reloads that don’t touch identity:.

The gateway also stamps a shared turn-lock onto every channel bot so a user unified across channels cannot scramble their transcript when two channels deliver at once — see Concurrent Turns Across Adapters.

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

YAML Reference

identity:
  enabled: true               # reconciled on reload; false clears the resolver
  store: ~/.praisonai/identity.json  # re-pointing rebuilds the resolver

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.

Optional Dependency

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]

Best Practices

Related