From 2bdc19821ce848a7e2f939d059b46e490ae09e16 Mon Sep 17 00:00:00 2001 From: Aura1122 Date: Mon, 17 Aug 2026 23:57:41 -0400 Subject: [PATCH 1/2] docs(remote): explain local gateway toggle prerequisite --- docs/guides/remote-and-mobile.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/guides/remote-and-mobile.md b/docs/guides/remote-and-mobile.md index aa914fb64bc..5f0f635d30a 100644 --- a/docs/guides/remote-and-mobile.md +++ b/docs/guides/remote-and-mobile.md @@ -675,6 +675,14 @@ A terminal-held tunnel dies with the terminal. A LaunchAgent survives reboots and reconnects after sleep. A ready-made plist is at [`assets/com.kirocrew.tunnel.plist`](assets/com.kirocrew.tunnel.plist): +If the desktop app should act only as a client for this remote gateway, first +bring up the tunnel and verify that it answers on the app's local port. Then turn +off **Settings → Developer → Gateway → Run a local gateway**. Turning that switch +off does not create or supervise a tunnel; on the next launch the app expects a +gateway to already answer on port 5476. A connected entry on the Instances page +does not satisfy this requirement because those tunnels are supervised by the +local gateway itself and use separate loopback ports. + ```bash cp docs/guides/assets/com.kirocrew.tunnel.plist ~/Library/LaunchAgents/ sed -i '' 's|ALIAS@DEV_DESKTOP_HOSTNAME|user@your-host.example.com|g' \ From 161b7ee2403418a8131791c6b6e219fd044fca9b Mon Sep 17 00:00:00 2001 From: Aura1122 Date: Mon, 7 Sep 2026 22:05:33 -0400 Subject: [PATCH 2/2] docs(remote): correct client-only tunnel launch order --- docs/guides/remote-and-mobile.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/docs/guides/remote-and-mobile.md b/docs/guides/remote-and-mobile.md index 5f0f635d30a..f7d93c680df 100644 --- a/docs/guides/remote-and-mobile.md +++ b/docs/guides/remote-and-mobile.md @@ -672,17 +672,20 @@ the browser holds, on the same clocks as [Session duration](#session-duration). ### Persistent SSH tunnel on macOS (LaunchAgent) A terminal-held tunnel dies with the terminal. A LaunchAgent survives reboots -and reconnects after sleep. A ready-made plist is at +and reconnects after sleep. + +If the desktop app should act only as a client for this remote gateway, turn off +**Settings → Developer → Gateway → Run a local gateway**, then quit the app so +its supervised gateway releases port 5476. Start the tunnel, verify the health +probe below, and only then reopen the app. Turning the switch off does not create +or supervise a tunnel; on the next launch the app expects a gateway to already +answer on port 5476. A connected entry on the Instances page does not satisfy +this requirement because those tunnels are supervised by the local gateway +itself and use separate loopback ports. + +A ready-made plist is at [`assets/com.kirocrew.tunnel.plist`](assets/com.kirocrew.tunnel.plist): -If the desktop app should act only as a client for this remote gateway, first -bring up the tunnel and verify that it answers on the app's local port. Then turn -off **Settings → Developer → Gateway → Run a local gateway**. Turning that switch -off does not create or supervise a tunnel; on the next launch the app expects a -gateway to already answer on port 5476. A connected entry on the Instances page -does not satisfy this requirement because those tunnels are supervised by the -local gateway itself and use separate loopback ports. - ```bash cp docs/guides/assets/com.kirocrew.tunnel.plist ~/Library/LaunchAgents/ sed -i '' 's|ALIAS@DEV_DESKTOP_HOSTNAME|user@your-host.example.com|g' \