external/BuddAI
1
0
Fork 0
mirror of https://github.com/JamesTheGiblet/BuddAI.git synced 2026-01-08 21:58:40 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
BuddAI/docs/REMOTE_ACCESS_LOG.md

3.4 KiB
Raw Blame History

Remote Access Implementation Log

This document records the troubleshooting steps, failures, and solutions implemented to enable remote access (Ngrok & Tailscale) for the BuddAI system.

1. Ngrok Execution Failures

Fail: "The term '.\ngrok' is not recognized"

Cause: The script assumed ngrok.exe was in the current folder, but it wasn't, or it wasn't in the system PATH. Fix: Updated run_buddai.ps1 to check both the global PATH (ngrok) and the local folder (.\ngrok.exe).

Fail: "Start-Process : The system cannot find the file specified"

Cause: PowerShell's Start-Process command failed when using a relative path like .\ngrok.exe. Fix: Implemented Resolve-Path to convert the relative path to an absolute path before execution.

2. Tunnel Timing Issues

Fail: Empty URL returned

Cause: The script attempted to fetch the public URL from the Ngrok API immediately after starting the process. The tunnel takes a few seconds to establish. Fix: Added a retry loop in PowerShell that polls http://localhost:4040/api/tunnels every second for up to 15 seconds.

3. Dependency Issues

Fail: "ModuleNotFoundError: No module named 'PIL'"

Cause: The qrcode library was added to generate QR codes, but it relies on pillow (PIL) for image generation, which was missing. Fix: Added pillow to requirements.txt and wrapped the import in main.py with a try/except block to prevent server crashes.

Fail: PowerShell Parsing Errors

Cause: Complex one-liner Python commands inside PowerShell strings caused syntax errors (specifically with parentheses and quoting). Fix: Refactored the Python QR code generation call to be cleaner and safer within the script.

4. Network & Firewall

Fail: "Run as Administrator to enable LAN/VPN access"

Cause: Windows Firewall blocks incoming connections to port 8000 by default, preventing LAN and Tailscale access. Fix: Added automatic detection of the missing firewall rule. The script now prompts the user to press 'A' to restart as Administrator and applies the rule automatically using New-NetFirewallRule.

Fail: Tailscale IP Not Detected

Cause: The script looked specifically for a network interface named "Tailscale", but on some systems, the adapter name differs. Fix: Added a fallback detection method that scans for any active IPv4 address in the 100.x.x.x range (Carrier Grade NAT), which Tailscale uses.

5. User Experience (UX) Friction

Fail: Annoying Ngrok Prompt

Cause: Users with Tailscale (which is always on) were forced to wait 3 seconds or press a key to skip the Ngrok prompt every time. Fix: Added logic to auto-detect Tailscale. If a Tailscale IP is found, the script now automatically skips the Ngrok prompt and defaults to the private VPN URL.

Fail: "How do I view this on mobile?"

Cause: Users had to manually type long IP addresses or URLs into their phone. Fix:

  1. Integrated a QR Code Generator directly into the Python backend (/api/utils/qrcode).
  2. Updated the root dashboard (/) to dynamically display the active IP (LAN, Tailscale, or Ngrok) and a scannable QR code.

Final Status

The system now supports three robust access methods:

  1. Local Network (LAN): Auto-configured via Firewall rules.
  2. Private VPN (Tailscale): Auto-detected with priority handling.
  3. Public Tunnel (Ngrok): Optional fallback with secure/public modes.