Skip to main content
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

2

Via env var (crash loops / supervisors)

A direct praisonai gateway restart replays safe mode. To leave safe mode, run a fresh praisonai gateway start without the flag.

​
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.
Safe mode never modifies config files and does not touch built-in gateway features such as forensics, memory-watchdog, scale-to-zero, or config reload — each keeps its own existing toggle.

​
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:
Supervised crash loop — set the env var in the service unit so the next crash-looped restart boots core-only:
Pair with the gateway doctor — confirm which plugins would load, then boot safe mode to compare:
Exit safe mode with a fresh start (not restart):

​
Best Practices

The flag’s intent is explicit in the command line, so a reproduction is unambiguous.
That WARNING line is the single source of truth that safe mode is active and names how many inbound hooks were disabled.
praisonai gateway restart replays the persisted safe-mode posture — exit with a fresh gateway start without the flag.
It is a triage switch, not authorization — use proper channel and token controls to secure the gateway.

Pure Mode

One-shot plugin suppression on run / chat / code

Gateway Inbound Hooks

The inbound HTTP triggers safe mode suppresses

Gateway Troubleshooting

Diagnose a misbehaving gateway

Plugins

Write, load, and configure plugins