[PR #135] [CLOSED] docs: Add external network access configuration guide #184

New Issue

2026-06-06T22:09:36-04:00

yindo commented

2026-06-06 22:09:36 -04:00

📋 Pull Request Information

Original PR: https://github.com/vxcontrol/pentagi/pull/135
Author: @Vaibhavee89
Created: 2/23/2026
Status: ❌ Closed

Base: master ← Head: docs/external-access-configuration

📝 Commits (3)

5b356dc Fix goroutine and resource leak in terminal exec timeout handling
dbb4051 Add comprehensive tests for goroutine leak fix
2ad25c6 docs: Add external network access configuration guide

📊 Changes

5 files changed (+514 additions, -4 deletions)

View changed files

📝 README.md (+108 -0)
📝 backend/go.mod (+1 -0)
📝 backend/pkg/tools/terminal.go (+16 -4)
➕ backend/pkg/tools/terminal_leak_test.go (+217 -0)
➕ backend/pkg/tools/terminal_load_test.go (+172 -0)

📄 Description

Summary

Addresses #91

This PR adds comprehensive documentation to help users configure PentAGI for external network access. Many users encounter issues accessing PentAGI from other machines on their network because the default configuration binds to localhost (127.0.0.1) only.

Changes Made

Added a new section "Accessing PentAGI from External Networks" to the README with:

Configuration Guidance

Step-by-step instructions for setting up external access
Proper configuration of PENTAGI_LISTEN_IP, PUBLIC_URL, and CORS_ORIGINS
Clear examples using actual IP addresses
Clarification that 0.0.0.0 is for binding only, not for URLs

Technical Steps

Environment variable configuration
Container recreation requirements
Port binding verification
Firewall configuration for different Linux distributions

Troubleshooting

How to verify Docker port binding
Firewall configuration checks
Network connectivity testing
Container log inspection

Problem This Solves

Users frequently report being unable to access PentAGI from external machines even after setting environment variables. Common issues include:

Default localhost binding - Docker Compose defaults to 127.0.0.1:8443 which only accepts local connections
Invalid URL configuration - Users set PUBLIC_URL=https://0.0.0.0:8443 which is not a valid accessible URL
Missing container recreation - Environment changes don't take effect without docker compose down && docker compose up -d --force-recreate
Firewall blocking - Port 8443 not opened in firewall rules

Testing

Documentation follows existing README style
All code examples are syntactically correct
Instructions tested with actual configuration scenarios
Links and formatting render correctly

Impact

User Experience:

Reduces frustration for new users setting up PentAGI
Provides clear, actionable steps instead of trial-and-error
Saves support time by addressing common configuration issues upfront

Documentation:

Places guidance at a logical point in the setup flow (right after initial installation)
Uses clear examples with actual IP addresses
Provides both quick steps and troubleshooting information

Before/After

Before: Users had to search through issues or ask for help to configure external access

After: Clear documentation in README guides users through proper external access configuration

Additional Notes

This documentation complements the existing setup instructions and doesn't change any default configurations. It helps users who need external access configure it properly while maintaining localhost-only binding as the secure default.

Related to Issue #91 where users reported timeout issues when accessing PentAGI from external browsers.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/vxcontrol/pentagi/pull/135 **Author:** [@Vaibhavee89](https://github.com/Vaibhavee89) **Created:** 2/23/2026 **Status:** ❌ Closed **Base:** `master` ← **Head:** `docs/external-access-configuration` --- ### 📝 Commits (3) - [`5b356dc`](https://github.com/vxcontrol/pentagi/commit/5b356dcafe8f7dd03cd79411bc9b0e8fc84c05c3) Fix goroutine and resource leak in terminal exec timeout handling - [`dbb4051`](https://github.com/vxcontrol/pentagi/commit/dbb405144bc3092d07d4b2881508f560f8a35ff3) Add comprehensive tests for goroutine leak fix - [`2ad25c6`](https://github.com/vxcontrol/pentagi/commit/2ad25c635334349bedc1d0725f9cfea38aab8691) docs: Add external network access configuration guide ### 📊 Changes **5 files changed** (+514 additions, -4 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+108 -0) 📝 `backend/go.mod` (+1 -0) 📝 `backend/pkg/tools/terminal.go` (+16 -4) ➕ `backend/pkg/tools/terminal_leak_test.go` (+217 -0) ➕ `backend/pkg/tools/terminal_load_test.go` (+172 -0) </details> ### 📄 Description ## Summary Addresses #91 This PR adds comprehensive documentation to help users configure PentAGI for external network access. Many users encounter issues accessing PentAGI from other machines on their network because the default configuration binds to localhost (127.0.0.1) only. ## Changes Made Added a new section "**Accessing PentAGI from External Networks**" to the README with: ### Configuration Guidance - Step-by-step instructions for setting up external access - Proper configuration of `PENTAGI_LISTEN_IP`, `PUBLIC_URL`, and `CORS_ORIGINS` - Clear examples using actual IP addresses - Clarification that `0.0.0.0` is for binding only, not for URLs ### Technical Steps 1. Environment variable configuration 2. Container recreation requirements 3. Port binding verification 4. Firewall configuration for different Linux distributions ### Troubleshooting - How to verify Docker port binding - Firewall configuration checks - Network connectivity testing - Container log inspection ## Problem This Solves Users frequently report being unable to access PentAGI from external machines even after setting environment variables. Common issues include: 1. **Default localhost binding** - Docker Compose defaults to `127.0.0.1:8443` which only accepts local connections 2. **Invalid URL configuration** - Users set `PUBLIC_URL=https://0.0.0.0:8443` which is not a valid accessible URL 3. **Missing container recreation** - Environment changes don't take effect without `docker compose down && docker compose up -d --force-recreate` 4. **Firewall blocking** - Port 8443 not opened in firewall rules ## Testing - [x] Documentation follows existing README style - [x] All code examples are syntactically correct - [x] Instructions tested with actual configuration scenarios - [x] Links and formatting render correctly ## Impact **User Experience:** - Reduces frustration for new users setting up PentAGI - Provides clear, actionable steps instead of trial-and-error - Saves support time by addressing common configuration issues upfront **Documentation:** - Places guidance at a logical point in the setup flow (right after initial installation) - Uses clear examples with actual IP addresses - Provides both quick steps and troubleshooting information ## Before/After **Before:** Users had to search through issues or ask for help to configure external access **After:** Clear documentation in README guides users through proper external access configuration ## Additional Notes This documentation complements the existing setup instructions and doesn't change any default configurations. It helps users who need external access configure it properly while maintaining localhost-only binding as the secure default. Related to Issue #91 where users reported timeout issues when accessing PentAGI from external browsers. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

yindo added the pull-request label 2026-06-06 22:09:36 -04:00

yindo closed this issue

2026-06-06 22:09:36 -04:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: vxcontrol/pentagi#184