docs: Document gateway port collision prevention features by MervinPraison · Pull Request #459 · MervinPraison/PraisonAIDocs

MervinPraison · 2026-05-30T06:27:09Z

Fixes #450

This PR documents the new gateway port collision prevention features added in PraisonAI PR #1756:

Changes Made

docs/features/gateway-cli.mdx

Added praisonai gateway stop command to Gateway Management table
Added new Command Reference tab for stop with --force option
Documented GATEWAY_PORT environment variable in new Environment Variables section
Updated status output examples to show PID lock and port information
Added Single-Instance Enforcement section with mermaid diagram
Added tip about port conflicts in Quick Start

docs/features/gateway.mdx

Added Single-Instance Enforcement section with PID lock explanation
Updated CLI Commands section to include stop and GATEWAY_PORT examples
Added best practice accordion about single instance per bot token

docs/guides/troubleshoot-gateway.mdx

Added Port Already In Use / Two Gateways Running troubleshooting section
Added Telegram Bot Goes Silent After Restart section covering duplicate pollers
Updated Daemon Running But Gateway Unreachable to mention new status output
Added PID lock file path documentation and diagnostic commands

Technical Details Documented

New praisonai gateway stop command with --host, --port, and --force options
GATEWAY_PORT environment variable support for start/stop/status commands
PID lock system at ~/.praisonai/gateway-<safe_host>-.pid
Enhanced status output with lock and port information
User-friendly collision error messages
Single-instance enforcement per host:port combination

Generated with Claude Code

- Add praisonai gateway stop command with --force option - Document GATEWAY_PORT environment variable - Add single-instance enforcement with PID locks - Update status output examples with lock/port info - Add port collision and silent bot troubleshooting 🤖 Generated with [Claude Code](https://claude.ai/code) Co-authored-by: Mervin Praison <MervinPraison@users.noreply.github.com>

qodo-code-review · 2026-05-30T06:27:13Z

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →

coderabbitai · 2026-05-30T06:27:17Z

Warning

Review limit reached

@MervinPraison, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 39 minutes and 16 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7873f21e-c6c9-45dc-ba26-227c20eb4afc

📥 Commits

Reviewing files that changed from the base of the PR and between ad3daba and 51027d8.

📒 Files selected for processing (3)

docs/features/gateway-cli.mdx
docs/features/gateway.mdx
docs/guides/troubleshoot-gateway.mdx

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch claude/issue-450-20260530-0623

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.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

gemini-code-assist

Code Review

This pull request updates the documentation across several files to explain the new single-instance enforcement mechanism for the PraisonAI gateway, which uses PID locks to prevent port conflicts. It introduces documentation for the praisonai gateway stop command, the GATEWAY_PORT environment variable, and provides troubleshooting guides for handling port conflicts and silent Telegram bots. The review feedback suggests correcting the PID lock file placeholders in docs/features/gateway.mdx to use <safe_host> instead of <host> for accuracy, and fixing an incorrectly labeled Windows command (netstat -ano | findstr) that was described as a Linux alternative in the troubleshooting guide.

gemini-code-assist · 2026-05-30T06:27:58Z

+    class Error,Stop error
+```
+
+**PID Lock File:** `~/.praisonai/gateway-<host>-<port>.pid`


The PID lock file name uses safe_host (where dots and colons are replaced with underscores, e.g., 127_0_0_1 instead of 127.0.0.1) as implemented in port_utils.py. Please update the placeholder to <safe_host> to be accurate and consistent with the description in gateway-cli.mdx.

gemini-code-assist · 2026-05-30T06:27:58Z

  </Accordion>
+
+  <Accordion title="Single instance per bot token">
+    Each Telegram/Discord/Slack bot token must be polled by exactly one process. PraisonAI enforces a PID lock at `~/.praisonai/gateway-<host>-<port>.pid` — start a second instance and you'll get a clear error pointing at the running PID. Use `GATEWAY_PORT=<other>` to run a second gateway on another port.


The PID lock file path uses safe_host instead of host to replace dots and colons with underscores. Please update the placeholder here to <safe_host> to maintain consistency and accuracy.

gemini-code-assist · 2026-05-30T06:27:58Z

+# Linux alternative:
+netstat -ano | findstr :8765


The command netstat -ano | findstr :8765 is a Windows command (using findstr and Windows-specific netstat flags), but it is labeled as a 'Linux alternative'. Please update it to a valid Linux command such as netstat -tulpn | grep :8765.

# Linux alternative: netstat -tulpn | grep :8765

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Copilot AI review requested due to automatic review settings May 30, 2026 06:27

Copilot started reviewing on behalf of MervinPraison May 30, 2026 06:27 View session

MervinPraison mentioned this pull request May 30, 2026

[Docs] Document gateway port collision prevention: gateway stop, GATEWAY_PORT, PID lock (PraisonAI PR #1756) #450

Closed

11 tasks

gemini-code-assist Bot reviewed May 30, 2026

View reviewed changes

Copilot AI reviewed May 30, 2026

View reviewed changes

MervinPraison merged commit 1a743f1 into main Jun 3, 2026
22 of 23 checks passed

MervinPraison deleted the claude/issue-450-20260530-0623 branch June 3, 2026 04:50

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Document gateway port collision prevention features#459

docs: Document gateway port collision prevention features#459
MervinPraison merged 1 commit into
mainfrom
claude/issue-450-20260530-0623

MervinPraison commented May 30, 2026

Uh oh!

qodo-code-review Bot commented May 30, 2026

Uh oh!

coderabbitai Bot commented May 30, 2026

Review limit reached

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot May 30, 2026

Uh oh!

gemini-code-assist Bot May 30, 2026

Uh oh!

gemini-code-assist Bot May 30, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

MervinPraison commented May 30, 2026

Changes Made

docs/features/gateway-cli.mdx

docs/features/gateway.mdx

docs/guides/troubleshoot-gateway.mdx

Technical Details Documented

Uh oh!

qodo-code-review Bot commented May 30, 2026

Qodo reviews are paused for this user.

Uh oh!

coderabbitai Bot commented May 30, 2026

Review limit reached

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot May 30, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 30, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants