From b8493fe08def767e7a9ba6b5768c7bf61154c5a0 Mon Sep 17 00:00:00 2001 From: Pedram Amini Date: Sun, 11 Jan 2026 06:01:18 -0600 Subject: [PATCH] MAESTRO: Fix remote-access.md documentation inaccuracies MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix "Global Access" → "Live Sessions" (only live sessions accessible) - Rename "Static Port Configuration" → "Custom Port Configuration" to match UI - Correct port range from 1024-65535 to 1-65535 - Fix "Use Custom Port" → "Custom Port" toggle label - Add UUID clarification for security token - Expand Mobile Web Interface with Core Features, Gestures, Input subsections - Add Connection Handling section (auto-reconnect, offline mode, status) - Add notes, tips, and related links section - Use em-dashes for consistency with other documentation --- docs/remote-access.md | 92 ++++++++++++++++++++++++++++++++----------- 1 file changed, 68 insertions(+), 24 deletions(-) diff --git a/docs/remote-access.md b/docs/remote-access.md index ce3c4264..88631704 100644 --- a/docs/remote-access.md +++ b/docs/remote-access.md @@ -6,66 +6,110 @@ icon: wifi Maestro includes a built-in web server for mobile remote control: -1. **Automatic Security**: Web server runs on a random port with an auto-generated security token embedded in the URL -2. **QR Code Access**: Scan a QR code to connect instantly from your phone -3. **Global Access**: All sessions are accessible when the web interface is enabled - the security token protects access -4. **Remote Tunneling**: Access Maestro from anywhere via Cloudflare tunnel (requires `cloudflared` CLI) +1. **Automatic Security** — Web server runs on a random port with an auto-generated security token (UUID) embedded in the URL +2. **QR Code Access** — Scan a QR code to connect instantly from your phone +3. **Live Sessions** — Sessions marked as "live" become accessible through the web interface (protected by the security token) +4. **Remote Tunneling** — Access Maestro from anywhere via Cloudflare tunnel (requires `cloudflared` CLI) ## Mobile Web Interface -The mobile web interface provides: +The mobile web interface provides a comprehensive remote control experience: + +### Core Features - Real-time session monitoring and command input - Device color scheme preference support (light/dark mode) -- Connection status indicator with automatic reconnection -- Offline queue for commands typed while disconnected -- Swipe gestures for common actions -- Quick actions menu for the send button +- Connection status indicator with automatic reconnection (30-second countdown timer) +- Offline queue for commands typed while disconnected (persisted to localStorage, up to 50 commands) +- Multi-tab support with tab bar and tab search modal + +### Gestures and Navigation +- Swipe gestures (left/right/up/down) for common actions +- Pull-to-refresh functionality +- Long-press menu for mode switching (AI ↔ Terminal) + +### Input Features +- Recent command chips for quick access +- Slash command autocomplete +- Command history drawer ## Local Access (Same Network) -1. Click the "OFFLINE" button in the header to enable the web interface -2. The button changes to "LIVE" and shows a QR code overlay +1. Click the **OFFLINE** button in the Left Bar header to enable the web interface +2. The button changes to **LIVE** (pulsing) and a QR code overlay appears automatically 3. Scan the QR code or copy the secure URL to access from your phone on the same network + +The web interface uses your local IP address (e.g., `192.168.x.x`) for LAN accessibility. Both devices must be on the same network. + + ## Remote Access (Outside Your Network) To access Maestro from outside your local network (e.g., on mobile data or from another location): 1. Install cloudflared: `brew install cloudflared` (macOS) or [download for other platforms](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) -2. Enable the web interface (OFFLINE → LIVE) -3. Toggle "Remote Access" in the Live overlay -4. A secure Cloudflare tunnel URL will be generated -5. Use the Local/Remote pill selector to switch between QR codes -6. The tunnel stays active as long as Maestro is running - no time limits, no account required +2. Enable the web interface (**OFFLINE** → **LIVE**) +3. Toggle **Remote Access** in the Live overlay panel +4. A secure Cloudflare tunnel URL (e.g., `https://abc123.trycloudflare.com`) will be generated within ~30 seconds +5. Use the **Local/Remote** pill selector to switch between QR codes +6. The tunnel stays active as long as Maestro is running — no time limits, no Cloudflare account required -## Static Port Configuration + +The Remote tab automatically activates when the tunnel connects successfully. + + +## Custom Port Configuration By default, Maestro assigns a **random port** each time the web server starts. This is a security-by-obscurity measure — attackers can't easily guess which port to target. -However, if you need a **fixed port** (e.g., for firewall rules, reverse proxies, or persistent tunnel configurations), you can enable static port mode: +However, if you need a **fixed port** (e.g., for firewall rules, reverse proxies, or persistent tunnel configurations), you can enable custom port mode: -1. Click the **OFFLINE** button to open the Live overlay -2. Toggle **Use Custom Port** to enable static port mode -3. Enter your desired port number (1024-65535) +1. Click the **LIVE** button to open the Live overlay panel +2. Toggle **Custom Port** to enable static port mode +3. Enter your desired port number (1–65535) 4. The server restarts automatically on the new port -**Use cases for static ports:** +**Use cases for custom ports:** - Punching a hole through a firewall or NAT - Configuring a reverse proxy (nginx, Caddy) - Setting up persistent SSH tunnels - Integration with home automation systems -**Security Trade-off**: Using a static port removes one layer of security-by-obscurity. The randomized port and auto-generated auth token in the URL work together to protect access. With a static port, you're relying solely on the auth token for security. +**Security Trade-off**: Using a custom port removes one layer of security-by-obscurity. The randomized port and auto-generated auth token in the URL work together to protect access. With a custom port, you're relying solely on the auth token for security. -**Recommendations when using static ports:** +**Recommendations when using custom ports:** - Use Cloudflare tunnel for remote access instead of exposing ports directly - Ensure your network firewall is properly configured - Consider additional authentication at the network level +## Connection Handling + +The mobile interface includes robust connection management: + +### Automatic Reconnection +- When disconnected, a 30-second countdown timer displays before automatic reconnection +- Manual **Retry** button available for immediate reconnection +- Reconnection attempts counter shows progress (e.g., "Attempt 3 of 10") + +### Offline Mode +- Commands typed while offline are queued (up to 50 commands) +- Queued commands are persisted to localStorage and survive page reloads +- Commands automatically send when connection is restored +- An **Offline Queue Banner** shows the number of pending commands + +### Connection Status Indicator +- Displays as a dismissible banner when connection is lost +- Shows different states: **Connecting**, **Authenticating**, **Disconnected**, **No internet** +- Expandable error details for troubleshooting + ## Screenshots ![Mobile chat](./screenshots/mobile-chat.png) ![Mobile groups](./screenshots/mobile-groups.png) ![Mobile history](./screenshots/mobile-history.png) + +## Related + +- [Configuration](/configuration) — General settings including web interface options +- [SSH Remote Execution](/ssh-remote-execution) — Running Maestro on remote servers