docs: Document bind-aware gateway/UI authentication posture#222
docs: Document bind-aware gateway/UI authentication posture#222MervinPraison wants to merge 1 commit intomainfrom
Conversation
- Add comprehensive bind-aware authentication documentation - Create docs/features/gateway-bind-aware-auth.mdx with: * Hero Mermaid diagram with standard color scheme * Quick Start examples for local and external deployment * Interface detection table and auth mode explanations * Environment variables reference * Error handling for GatewayStartupError and UIStartupError * Token fingerprinting documentation * User flow examples and decision diagram * Best practices and security guidance - Update docs/gateway.mdx with Authentication section - Update docs/guides/troubleshoot-gateway.mdx with auth error troubleshooting - Update docs/features/chat.mdx with security and bind-aware behavior - Update docs/features/onboard.mdx with token persistence info - Update docs.json navigation to include new page Co-authored-by: Mervin Praison <MervinPraison@users.noreply.github.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces comprehensive documentation for 'Bind-Aware Authentication,' a security feature that automatically adjusts authentication requirements based on the network interface. The changes include a new dedicated feature guide, updated security sections for the chat UI and gateway, and new troubleshooting steps for authentication errors. Feedback focuses on clarifying the description of token auto-generation logic in the documentation tables and optimizing a shell command in the troubleshooting guide for better idiomatic usage.
| | `local` | Permissive — no token required | Loopback bind (default) | | ||
| | `token` | Token required (auto-generated if absent on loopback) | External bind (default) | |
There was a problem hiding this comment.
The description for token mode is slightly misleading. Auto-generation of the token occurs during loopback binds (to facilitate future external access), but token mode itself (triggered by external binds) strictly requires an existing token and will fail if one is not found. It is clearer to associate the auto-generation behavior with local mode.
| `local` | Permissive — no token required (auto-generated for future use) | Loopback bind (default) |
| `token` | Strict — token required | External bind (default) |
| <Steps> | ||
| <Step title="Retrieve full token from environment file"> | ||
| ```bash | ||
| cat ~/.praisonai/.env | grep GATEWAY_AUTH_TOKEN |
There was a problem hiding this comment.
This is a "useless use of cat". grep can read the file directly, which is more idiomatic and slightly more efficient.
grep "GATEWAY_AUTH_TOKEN" ~/.praisonai/.env
📝 WalkthroughWalkthroughThis PR adds comprehensive documentation for bind-aware authentication, introducing a new feature page and updating existing documentation files to describe how gateway and chat UI security behavior changes depending on the network interface binding (permissive for loopback, strict for external). All changes are documentation-only, with no code modifications. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related issues
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (3)
docs/features/gateway-bind-aware-auth.mdx (2)
1-218: Page is missingConfiguration OptionsandCommon Patternssections from the standard template.The coding guidelines require documentation pages to follow the structure: frontmatter, hero diagram, Quick Start, How It Works, Configuration Options, Common Patterns, Best Practices, Related. This page jumps from How It Works → Interface Detection → User Flows → Environment Variables → Error Reference → Best Practices → Related. The
Environment Variablestable is close to Configuration Options but doesn't use the requiredOption | Type | Default | Descriptioncolumns, and there is noCommon Patternssection at all.Consider either renaming/expanding
Environment Variablesinto aConfiguration Optionssection with the required table schema, and adding a shortCommon Patternssection (e.g., LAN share, VPS with TLS, reverse proxy withtrusted-proxy).As per coding guidelines: "All documentation pages must follow the standard page structure template with frontmatter, hero diagram, Quick Start, How It Works, Configuration Options, Common Patterns, Best Practices, and Related sections" and "Configuration documentation must include a table with columns: Option, Type, Default, Description for all SDK config options".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/features/gateway-bind-aware-auth.mdx` around lines 1 - 218, The page is missing the required "Configuration Options" and "Common Patterns" sections; update the doc by renaming or expanding the existing "Environment Variables" block into a new "Configuration Options" section that contains the required table with columns Option | Type | Default | Description and include entries for GATEWAY_AUTH_TOKEN, CHAINLIT_HOST, CHAINLIT_USERNAME, CHAINLIT_PASSWORD, PRAISONAI_ALLOW_DEFAULT_CREDS, CHAINLIT_AUTH_SECRET (use the current descriptions as the Description column and populate Type/Default); then add a short "Common Patterns" section (3–4 bullets) illustrating LAN share (onboard/export token), VPS deployment (token + TLS + custom creds) and reverse-proxy/trusted-proxy setups referencing the `trusted-proxy` mode; keep the existing Best Practices and Related sections intact.
109-117: Consider promoting User Flows to<Steps>or a table for scannability.Flows A–D are rendered as four consecutive bold-lead paragraphs, which is harder to scan than the rest of the page (which uses Steps/tables/accordions consistently). A small table (
Scenario | Command | Notes) or an<AccordionGroup>would match the page's style and the Mintlify-component guideline.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/features/gateway-bind-aware-auth.mdx` around lines 109 - 117, Convert the four bold-paragraph flows under the "User Flows" heading into a scannable component (use the existing page pattern): replace the consecutive bold-led paragraphs "Flow A", "Flow B", "Flow C", "Flow D" with either a <Steps> component or a small table with columns "Scenario | Command | Notes" (or an <AccordionGroup> if you prefer collapsible sections); ensure each flow keeps its current content (e.g., token generation details, exact commands like `praisonai onboard` / `export GATEWAY_AUTH_TOKEN...` and env hints like `CHAINLIT_USERNAME`/`PRAISONAI_ALLOW_DEFAULT_CREDS`) mapped into the corresponding step/table row/accordion panel for easier scanning.docs/features/onboard.mdx (1)
363-366: Move the bind-aware auth Card into theRelatedCardGroup.The new
<Card>is emitted as a bare element between Best Practices and the## Relatedheading, which breaks the page's structural template (Related is the canonical place for cross-links, and it already uses a<CardGroup cols={2}>). Placing a lone Card outside any CardGroup also renders inconsistently with the four cards below.♻️ Suggested fix
-<Card title="Bind-Aware Authentication" icon="shield" href="/docs/features/gateway-bind-aware-auth"> - Gateway and UI security behavior based on bind interface -</Card> - --- ## Related <CardGroup cols={2}> + <Card title="Bind-Aware Authentication" icon="shield" href="/docs/features/gateway-bind-aware-auth"> + Gateway and UI security behavior based on bind interface + </Card> <Card title="Installation Guide" icon="download" href="/docs/install/installer"> Complete installer documentation including onboarding flow </Card>As per coding guidelines: "Use Mintlify CardGroup component for Related section with
<CardGroup cols={2}>and<Card>children".🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/features/onboard.mdx` around lines 363 - 366, The new standalone <Card title="Bind-Aware Authentication" icon="shield" href="/docs/features/gateway-bind-aware-auth"> is placed outside the Related section and must be moved into the existing <CardGroup cols={2}> that renders the "Related" cards; edit the markup so this <Card> becomes one of the children inside the Related <CardGroup cols={2}> (remove the bare Card from between Best Practices and the "## Related" heading) to restore consistent layout and use the canonical Related CardGroup.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/features/chat.mdx`:
- Around line 115-119: The docs list PRAISONAI_CHAT_HOST and CHAINLIT_HOST as
independently configurable via environment, but the code sets CHAINLIT_HOST
programmatically (overriding env) and never reads PRAISONAI_CHAT_HOST; update
either docs or code: either change docs to state that chat host must be
configured via the API (start_chat_server(host=...)) and remove the env var
rows, or implement env-var support by reading PRAISONAI_CHAT_HOST /
CHAINLIT_HOST at startup and falling back to start_chat_server host parameter
(or vice versa) so environment values are respected; check the logic around
CHAINLIT_HOST assignment in praisonai.chat.__init__ (the code that sets
CHAINLIT_HOST) and ensure consistent precedence and documentation.
In `@docs/features/gateway-bind-aware-auth.mdx`:
- Around line 32-45: Replace the example's bare Agent instantiation with one
that configures the gateway so the snippet demonstrates bind-aware auth:
construct a GatewayConfig(host="127.0.0.1") and pass it to Agent via the gateway
parameter (e.g., Agent(..., gateway=GatewayConfig(...))) before calling
agent.start("hello"), ensuring the code shows the agent using the gateway bind
rather than running purely locally.
---
Nitpick comments:
In `@docs/features/gateway-bind-aware-auth.mdx`:
- Around line 1-218: The page is missing the required "Configuration Options"
and "Common Patterns" sections; update the doc by renaming or expanding the
existing "Environment Variables" block into a new "Configuration Options"
section that contains the required table with columns Option | Type | Default |
Description and include entries for GATEWAY_AUTH_TOKEN, CHAINLIT_HOST,
CHAINLIT_USERNAME, CHAINLIT_PASSWORD, PRAISONAI_ALLOW_DEFAULT_CREDS,
CHAINLIT_AUTH_SECRET (use the current descriptions as the Description column and
populate Type/Default); then add a short "Common Patterns" section (3–4 bullets)
illustrating LAN share (onboard/export token), VPS deployment (token + TLS +
custom creds) and reverse-proxy/trusted-proxy setups referencing the
`trusted-proxy` mode; keep the existing Best Practices and Related sections
intact.
- Around line 109-117: Convert the four bold-paragraph flows under the "User
Flows" heading into a scannable component (use the existing page pattern):
replace the consecutive bold-led paragraphs "Flow A", "Flow B", "Flow C", "Flow
D" with either a <Steps> component or a small table with columns "Scenario |
Command | Notes" (or an <AccordionGroup> if you prefer collapsible sections);
ensure each flow keeps its current content (e.g., token generation details,
exact commands like `praisonai onboard` / `export GATEWAY_AUTH_TOKEN...` and env
hints like `CHAINLIT_USERNAME`/`PRAISONAI_ALLOW_DEFAULT_CREDS`) mapped into the
corresponding step/table row/accordion panel for easier scanning.
In `@docs/features/onboard.mdx`:
- Around line 363-366: The new standalone <Card title="Bind-Aware
Authentication" icon="shield" href="/docs/features/gateway-bind-aware-auth"> is
placed outside the Related section and must be moved into the existing
<CardGroup cols={2}> that renders the "Related" cards; edit the markup so this
<Card> becomes one of the children inside the Related <CardGroup cols={2}>
(remove the bare Card from between Best Practices and the "## Related" heading)
to restore consistent layout and use the canonical Related CardGroup.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: df687263-84c3-4d7e-a16f-c754c0c22a27
📒 Files selected for processing (6)
docs.jsondocs/features/chat.mdxdocs/features/gateway-bind-aware-auth.mdxdocs/features/onboard.mdxdocs/gateway.mdxdocs/guides/troubleshoot-gateway.mdx
| | `CHAINLIT_HOST` | Host the UI binds to (drives auth mode) | `127.0.0.1` | | ||
| | `CHAINLIT_USERNAME` | Username for authentication | `admin` | | ||
| | `CHAINLIT_PASSWORD` | Password for authentication | `admin` | | ||
| | `PRAISONAI_ALLOW_DEFAULT_CREDS` | Allow admin/admin on external bind (unsafe) | `false` | | ||
| | `CHAINLIT_AUTH_SECRET` | Auth secret for sessions | Auto-generated | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Confirm how PRAISONAI_CHAT_HOST and CHAINLIT_HOST are actually resolved in code.
rg -nP -C3 '\b(PRAISONAI_CHAT_HOST|CHAINLIT_HOST)\b'Repository: MervinPraison/PraisonAIDocs
Length of output: 2517
🏁 Script executed:
#!/bin/bash
# Find the ChatConfig or configuration class to understand how config.host is set
fd -e py . praisonai/chat | head -20 | xargs grep -l "class.*Config\|config.host" 2>/dev/null
# Also search for where config is instantiated in chat/__init__.py
rg -A 10 "def run_chat" praisonai/chat/__init__.py | head -40Repository: MervinPraison/PraisonAIDocs
Length of output: 97
🏁 Script executed:
#!/bin/bash
# Read the chat/__init__.py file to understand config initialization
wc -l praisonai/chat/__init__.pyRepository: MervinPraison/PraisonAIDocs
Length of output: 101
🏁 Script executed:
#!/bin/bash
# Read the entire chat/__init__.py file
cat -n praisonai/chat/__init__.pyRepository: MervinPraison/PraisonAIDocs
Length of output: 3825
🏁 Script executed:
#!/bin/bash
# Check if PRAISONAI_CHAT_HOST environment variable is actually read anywhere in the codebase
rg "PRAISONAI_CHAT_HOST" --type pyRepository: MervinPraison/PraisonAIDocs
Length of output: 53
🏁 Script executed:
#!/bin/bash
# Search for any CLI entry point or __main__ that might read PRAISONAI_CHAT_HOST
fd -e py . praisonai/chat | xargs grep -l "argparse\|click\|PRAISONAI_CHAT" 2>/dev/null
# Also search in other locations for CLI definitions
rg "PRAISONAI_CHAT" --type-list all | head -20Repository: MervinPraison/PraisonAIDocs
Length of output: 526
🏁 Script executed:
#!/bin/bash
# Check the size and read app.py
wc -l praisonai/chat/app.pyRepository: MervinPraison/PraisonAIDocs
Length of output: 96
🏁 Script executed:
#!/bin/bash
# Read app.py to check for environment variable usage
cat -n praisonai/chat/app.pyRepository: MervinPraison/PraisonAIDocs
Length of output: 5325
The documentation incorrectly lists environment variables that don't match implementation behavior.
The table describes PRAISONAI_CHAT_HOST and CHAINLIT_HOST as independent environment variables, but the code reveals:
PRAISONAI_CHAT_HOST(default0.0.0.0in the table) is never read from the environmentCHAINLIT_HOST(default127.0.0.1in the table) is always programmatically set to the value ofconfig.hostat runtime, overriding any environment variable
The code in praisonai/chat/__init__.py line 88 shows CHAINLIT_HOST is set by the application, not independently configurable via environment. Users cannot rely on these environment variables; configuration is only available through the start_chat_server(host=...) function parameter.
Fix: Either document that configuration is only available programmatically via the function API, or if environment variable support is intended, implement environment variable reading in the code.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/features/chat.mdx` around lines 115 - 119, The docs list
PRAISONAI_CHAT_HOST and CHAINLIT_HOST as independently configurable via
environment, but the code sets CHAINLIT_HOST programmatically (overriding env)
and never reads PRAISONAI_CHAT_HOST; update either docs or code: either change
docs to state that chat host must be configured via the API
(start_chat_server(host=...)) and remove the env var rows, or implement env-var
support by reading PRAISONAI_CHAT_HOST / CHAINLIT_HOST at startup and falling
back to start_chat_server host parameter (or vice versa) so environment values
are respected; check the logic around CHAINLIT_HOST assignment in
praisonai.chat.__init__ (the code that sets CHAINLIT_HOST) and ensure consistent
precedence and documentation.
| <Step title="Local development (loopback — permissive)"> | ||
| ```python | ||
| 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") | ||
| ``` | ||
| </Step> |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify whether GatewayConfig supports bind_host as the PR objective suggests,
# and how agents are actually served through the gateway.
rg -nP -C3 '\bbind_host\b'
rg -nP -C3 'class\s+GatewayConfig\b'Repository: MervinPraison/PraisonAIDocs
Length of output: 436
🏁 Script executed:
cat -n praisonaiagents/gateway/config.py | head -250 | tail -80Repository: MervinPraison/PraisonAIDocs
Length of output: 3656
🏁 Script executed:
# Search for how Agent uses GatewayConfig
rg -n 'Agent.*GatewayConfig|GatewayConfig.*Agent' -A5 -B5Repository: MervinPraison/PraisonAIDocs
Length of output: 2379
🏁 Script executed:
# Look for gateway start or serve methods in Agent
rg -n 'def start\b' praisonaiagents/agent.py -A10Repository: MervinPraison/PraisonAIDocs
Length of output: 135
🏁 Script executed:
# Find where Agent class is defined
fd 'agent\.py$|agents\.py$' praisonaiagents --type fRepository: MervinPraison/PraisonAIDocs
Length of output: 812
🏁 Script executed:
# Look at the specific file being reviewed
cat -n docs/features/gateway-bind-aware-auth.mdxRepository: MervinPraison/PraisonAIDocs
Length of output: 8842
Replace the Python snippet with Agent passing GatewayConfig(host="127.0.0.1") to actually exercise the gateway bind behavior.
The Step title says "Local development (loopback — permissive)" but the Python code creates a bare Agent without any gateway configuration and calls agent.start("hello"), which runs the agent locally rather than through the gateway's bind-aware auth. The bash comment alone doesn't demonstrate the feature. Show the gateway being configured on the agent itself using gateway=GatewayConfig(host="127.0.0.1") so the snippet matches the documentation's purpose.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/features/gateway-bind-aware-auth.mdx` around lines 32 - 45, Replace the
example's bare Agent instantiation with one that configures the gateway so the
snippet demonstrates bind-aware auth: construct a
GatewayConfig(host="127.0.0.1") and pass it to Agent via the gateway parameter
(e.g., Agent(..., gateway=GatewayConfig(...))) before calling
agent.start("hello"), ensuring the code shows the agent using the gateway bind
rather than running purely locally.
Fixes #221
Summary
This PR implements comprehensive documentation for the bind-aware authentication posture feature introduced in PraisonAI PR #1517. The feature automatically changes security behavior based on the interface the gateway and UI bind to — permissive on loopback, strict on external.
Changes
New Documentation
Updated Documentation
Documentation Standards
Generated with Claude Code
Summary by CodeRabbit