Gateway Safe Mode

Boot the gateway core-only to isolate whether a fault is in the core or an extension

Safe mode boots the gateway with external plugins and inbound YAML hooks disabled so an operator can tell whether a fault is in the core or an extension in one restart.

Quick Start

1. One restart

   praisonai gateway start --config gateway.yaml --safe-mode
   # → logs: SAFE MODE: N inbound hook(s) disabled; external plugins skipped (PRAISONAI_NO_PLUGINS)

2. Via env var (crash loops / supervisors)

   PRAISONAI_NO_PLUGINS=1 praisonai gateway start --config gateway.yaml

How It Works

The CLI flag sets PRAISONAI_NO_PLUGINS=1 for the gateway process and forwards safe_mode=True to the handler; the server then skips inbound hook registration and logs the SAFE MODE: line before it listens.

The flag has three equivalent names — --safe-mode, --pure, --no-plugins — matching the aliases already used by praisonai run / chat / code. The env var PRAISONAI_NO_PLUGINS=1 is equivalent and useful where editing CLI args is awkward.

What Is Suppressed vs. Kept

Safe mode suppresses only extensions — the core agent and your configured channels keep serving traffic.

When To Use It

Reach for safe mode first when you cannot tell whether a fault lives in the gateway core or in an extension.

Common Patterns

Bisect a fault — if a safe-mode boot is green, the problem is a plugin or hook; if it is still red, it is the gateway core:

praisonai gateway start --config gateway.yaml --safe-mode

Supervised crash loop — set the env var in the service unit so the next crash-looped restart boots core-only:

PRAISONAI_NO_PLUGINS=1 praisonai gateway start --config gateway.yaml

Pair with the gateway doctor — confirm which plugins would load, then boot safe mode to compare:

praisonai gateway doctor --config gateway.yaml
praisonai gateway start --config gateway.yaml --safe-mode

Exit safe mode with a fresh start (not restart):

praisonai gateway start --config gateway.yaml

Best Practices

Related