> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Start[🖥️ gateway start] --> Flag{🚦 --safe-mode?}
    Flag -->|No| Load[🔌 Load plugins + hooks]
    Flag -->|Yes| Skip[⏭️ Skip plugins + hooks]
    Load --> Core[✅ Core agent + channels serve traffic]
    Skip --> Core

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef check fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef skip fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class Start input
    class Flag check
    class Load,Skip skip
    class Core result
```

## Quick Start

**1. One restart**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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)**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
PRAISONAI_NO_PLUGINS=1 praisonai gateway start --config gateway.yaml
```

> [!WARNING]
>
> 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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant Operator
    participant CLI as gateway start --safe-mode
    participant Handler as GatewayHandler
    participant Server as WebSocketGateway
    participant Manager as PluginManager

    Operator->>CLI: --safe-mode / --pure / --no-plugins
    CLI->>CLI: set PRAISONAI_NO_PLUGINS=1
    CLI->>Handler: start(safe_mode=True)
    Handler->>Server: _apply_hooks_from_config(cfg)
    Server->>Server: SAFE MODE: N inbound hook(s) disabled
    Server->>Manager: discover_entry_points()
    Manager-->>Server: 0 (plugins skipped)
    Server-->>Operator: core agent + channels listening
```

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.

| Component | Normal mode | Safe mode |
| - | - | - |
| Core agent | On | On |
| Configured channels (incl. entry-point channels) | On | On |
| External plugins (entry-point discovery) | Loaded | **Skipped** |
| Inbound YAML `hooks:` block | Registered | **Skipped (logged)** |
| Forensics / scale-to-zero / crash-loop guard / config reload | On | On (own toggles) |
| `.praisonai/config.yaml` | Unchanged | Unchanged |

> [!NOTE]
>
> 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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Q[Gateway misbehaving?] --> A[Not sure: core or extension?]
    Q --> B[One channel acting up]
    Q --> C[Want a plugin inventory first]
    A --> R1["gateway start --safe-mode"]
    B --> R2["pause that channel"]
    C --> R3["gateway doctor, then --safe-mode"]

    classDef decision fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef option fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class Q decision
    class A,B,C option
    class R1,R2,R3 result
```

***

## 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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai gateway doctor --config gateway.yaml
praisonai gateway start --config gateway.yaml --safe-mode
```

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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai gateway start --config gateway.yaml
```

***

## Best Practices

> **Prefer the CLI flag over the env var in bug reports**
>
> The flag's intent is explicit in the command line, so a reproduction is unambiguous.

> **Watch for the SAFE MODE: log line**
>
> That `WARNING` line is the single source of truth that safe mode is active and names how many inbound hooks were disabled.

> **Remember restart stays in safe mode**
>
> `praisonai gateway restart` replays the persisted safe-mode posture — exit with a fresh `gateway start` without the flag.

> **Safe mode is not a security posture**
>
> It is a triage switch, not authorization — use proper channel and token controls to secure the gateway.

***

## Related

> **[Pure Mode](/docs/features/pure-mode.md)**
>
> One-shot plugin suppression on `run` / `chat` / `code`

> **[Gateway Inbound Hooks](/docs/features/gateway-inbound-hooks.md)**
>
> The inbound HTTP triggers safe mode suppresses

> **[Gateway Troubleshooting](/docs/guides/troubleshoot-gateway.md)**
>
> Diagnose a misbehaving gateway

> **[Plugins](/docs/features/plugins.md)**
>
> Write, load, and configure plugins


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.