Skip to main content
Self-lifecycle guard blocks a running gateway’s agent from shutting itself down. An agent with a shell tool can be tricked into running praisonai gateway stop or pkill -f praisonai, taking down the very process it runs in (self-DoS). The guard inspects the command structurally and refuses self-destructive commands before they run — while leaving ordinary commands, and ordinary English, untouched.

​
Quick Start

1

Simple Usage

The guard is on by default. Benign commands pass; a self-stop is refused.
from praisonaiagents.gateway import LifecycleCommandGuardPolicy

guard = LifecycleCommandGuardPolicy()

print(guard.evaluate("ls -la").allow)                 # True
print(guard.evaluate("praisonai gateway stop").allow) # False
2

With Configuration

Name a renamed CLI with process_names and fail closed with default_allow=False.
from praisonaiagents.gateway import LifecycleCommandGuardPolicy

guard = LifecycleCommandGuardPolicy(process_names=["mybot"], default_allow=False)

print(guard.evaluate("ls -la").allow)             # True
print(guard.evaluate("mybot gateway stop").allow) # False

​
How It Works

The guard is consulted before a shell/CLI tool executes and before a scheduled job is registered. A denied command returns a LifecycleCommandDecision instead of running. Matching is command-anchored — structural token inspection over every ; / && / || / pipe / newline segment, not prose. Three rules trip a deny:
RuleFormExample denied
CLI self-control<cli> gateway <verb> (adjacent)praisonai gateway stop
Process killpkill / kill / killall naming the gatewaypkill -f praisonai
Service managersystemctl / launchctl / service / sc stop/restart/… on our unitsystemctl stop praisonai-gateway
Whole-component matching means praisonai-gateway (real unit) matches, but api-gateway, kong-gateway, and my-praisonaibot do not. Rule 1 requires adjacency: the CLI token must sit immediately before gateway, followed by a lifecycle verb — so praisonai gateway status --stop-on-idle is allowed. Leading sudo / env / nohup / exec prefixes are stripped and path-qualified executables (/usr/bin/pkill) are normalised to their base before matching.

​
Configuration Options

LifecycleCommandGuardPolicy is the config-driven default, referenced by gateway.lifecycle_guard in gateway.yaml and by BotOS(..., lifecycle_policy=...).
ParameterTypeDefaultDescription
enabledboolTrueGuard is on by default; False disables it entirely.
process_namesOptional[List[str]]None (→ ["praisonai"])Whole-component identity tokens that name this gateway.
default_allowboolTrueFail posture. True = fail-open on parse error; False = fail-closed for strict hosted gateways.
evaluate() returns a LifecycleCommandDecision — a frozen dataclass with allow (bool), reason (str, populated on denial), and matched (str, the offending fragment for the audit log). The pure decision contract is LifecycleCommandPolicyProtocol (runtime-checkable); LifecycleCommandPolicy is a backward-compat alias for it.

Gateway API Reference

Full SDK reference for the gateway policy family

​
Common Patterns

​
Default guard — benign commands pass

The on-by-default case: ordinary commands run untouched, and prose mentioning “stop the gateway” is never tripped. 
from praisonaiagents.gateway import LifecycleCommandGuardPolicy

guard = LifecycleCommandGuardPolicy()

print(guard.evaluate("systemctl stop nginx").allow)                        # True
print(guard.evaluate("echo 'please stop the gateway from spamming'").allow) # True

​
Opt out

Disable the guard for an operator who legitimately wants an agent to manage the process. 
from praisonaiagents.gateway import LifecycleCommandGuardPolicy

guard = LifecycleCommandGuardPolicy(enabled=False)

print(guard.evaluate("praisonai gateway stop").allow)  # True

​
Strict / fail-closed

For hosted gateways where a parse error must not default to allow. 
from praisonaiagents.gateway import LifecycleCommandGuardPolicy

guard = LifecycleCommandGuardPolicy(default_allow=False)

print(guard.evaluate("pkill -f praisonai").allow)  # False

​
Best Practices

The default enabled=True protects the process from self-DoS. Leave it on for any gateway that must stay up, especially under an external supervisor where a self-stop can become a respawn flap.
The default identity token is praisonai. If you fork the CLI (mybot gateway stop) or run multiple project gateways side by side, pass process_names=["mybot"] so kill, service, and CLI rules all cover the right process.
Fail-open is the safe default for local use. In a hosted gateway, set default_allow=False so an internal parse error refuses the command rather than letting it through.
Approval decides whether an agent may run a tool; the lifecycle guard is a lower-level structural check on the command string. Pair it with approval and tool policy for defence in depth.

Gateway Code-Skew Guard

Refuse hot operations after an in-place code update

Gateway Tool Policy

Control which tools an agent may run through the gateway

Guardrails

Validate and constrain agent inputs and outputs

Gateway Scoped Approvals

Require approval for sensitive gateway operations