Skip to main content
The gateway and chat UI change security behavior based on the interface they bind to — permissive on loopback, strict on external.

​
Quick Start

1

Local development (loopback — permissive)

from praisonaiagents import Agent

agent = Agent(
    name="Local Agent",
    instructions="You are a helpful assistant.",
)

# Serve via gateway on loopback — no token needed
# $ praisonai gateway start --host 127.0.0.1
agent.start("hello")
2

External deployment (strict — token required)

# Option A: Run onboarding (recommended)
praisonai onboard

# Option B: Set a token explicitly
export GATEWAY_AUTH_TOKEN=$(openssl rand -hex 16)
praisonai gateway start --host 0.0.0.0

​
How It Works

ModeMeaningTrigger
localPermissive — no token requiredLoopback bind (default)
tokenToken required (auto-generated if absent on loopback)External bind (default)
passwordUsername/password authChainlit UI
trusted-proxyAuth handled upstreamReverse proxy setups

​
Interface Detection

Hostis_loopback()Resolved mode
127.0.0.1Truelocal
127.255.255.255Truelocal
localhostTruelocal
::1Truelocal
0.0.0.0Falsetoken
192.168.1.xFalsetoken
10.0.0.xFalsetoken
8.8.8.8 (public)Falsetoken

​
User Flows

Flow A — “I want a quick local demo”: Run on 127.0.0.1, no config needed. Token auto-generated, fingerprint logged (gw_****abcd), saved to ~/.praisonai/.env. Flow B — “I want to share on my LAN”: Run praisonai onboard (30s, 3 prompts) OR export GATEWAY_AUTH_TOKEN=$(openssl rand -hex 16) → praisonai gateway start --host 0.0.0.0. Flow C — “I’m deploying to a VPS”: Same as B, but also set CHAINLIT_USERNAME / CHAINLIT_PASSWORD for the UI, and consider TLS. Flow D — “Lab/demo — I accept the risk of admin/admin on external”: export PRAISONAI_ALLOW_DEFAULT_CREDS=1.

​
Environment Variables

VariableScopeEffect
GATEWAY_AUTH_TOKENGatewayAuth token. Required on external bind. Auto-generated + saved to ~/.praisonai/.env (mode 0600) on loopback when unset.
CHAINLIT_HOSTUIHost the UI binds to (default 127.0.0.1). Drives UI auth mode resolution.
CHAINLIT_USERNAMEUIUsername (default admin).
CHAINLIT_PASSWORDUIPassword (default admin).
PRAISONAI_ALLOW_DEFAULT_CREDSUIEscape hatch. Set to 1/true/yes to allow admin/admin on external bind. Unsafe — demo only.
CHAINLIT_AUTH_SECRETUISession secret. Auto-generated if unset (ephemeral per-process).

​
Error Reference

GatewayStartupError — raised by assert_external_bind_safe() when binding externally without a token: 
Cannot bind to 0.0.0.0 without an auth token.
Fix:  praisonai onboard         (30 seconds, 3 prompts)
Or:   export GATEWAY_AUTH_TOKEN=$(openssl rand -hex 16)
UIStartupError — raised by register_password_auth() when admin/admin used on external bind: 
Cannot bind to 0.0.0.0 with default admin/admin credentials.
Fix:  export CHAINLIT_USERNAME=myuser CHAINLIT_PASSWORD=mypass
Lab:  export PRAISONAI_ALLOW_DEFAULT_CREDS=1  (demo only)

​
Token Fingerprinting

Logs now show gw_****XXXX (last 4 chars), never the raw token. This is implemented by get_auth_token_fingerprint() for safe logging. Retrieve the full token from ~/.praisonai/.env if needed.

​
Which Option When

​
Best Practices

Prefer praisonai onboard over manual token creation. It handles all the setup automatically and saves the token securely.
The auto-generated .env file contains sensitive tokens. Add it to your .gitignore and never commit it to version control.
Always set CHAINLIT_USERNAME and CHAINLIT_PASSWORD before binding to external interfaces. Never use admin/admin in production.
The PRAISONAI_ALLOW_DEFAULT_CREDS=1 escape hatch should only be used for ephemeral demos or testing. Never in production.

Gateway Documentation

Core gateway functionality and configuration

Onboarding

Quick setup with automatic token generation

Troubleshooting

Common gateway issues and solutions

Chat Interface

Chainlit UI security and configuration