docs: add Coder Desktop stale-tunnel recovery and improve macOS log capture - #26735
Conversation
Docs previewCheck off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here. |
Documentation CheckUpdates Needed
Automated review via Coder Agents |
|
|
||
| ```shell | ||
| vpn_name=$(scutil --nc list | grep "com.coder.Coder-Desktop" | awk -F'"' '{print $2}' | tail -n1) | ||
| if [ -n "$vpn_name" ]; then scutil --nc stop "$vpn_name"; fi |
There was a problem hiding this comment.
This does the same thing as toggling off Coder Connect in the UI
There was a problem hiding this comment.
@ethanndickson agreed, it's just additional documentation to do the same thing via the CLI.
| 3. Restart the helper daemon in place: | ||
|
|
||
| ```shell | ||
| sudo launchctl kickstart -k system/com.coder.Coder-Desktop.Helper | ||
| ``` | ||
|
|
||
| > [!WARNING] | ||
| > Do not use `launchctl bootout` here. `bootout` removes the daemon from | ||
| > launchd's system domain entirely, and relaunching the app does not | ||
| > re-bootstrap it. Use `kickstart -k` to restart it in place. |
There was a problem hiding this comment.
Restarting the helper shouldn't be necessary, has this been observed to actually resolve the issue, or was this just suggested by blink?
There was a problem hiding this comment.
@ethanndickson This has not been observed to resolve the issue, it's just documenting the restart process and related subprocesses without having to restart a laptop/workstation.
nickvigilante
left a comment
There was a problem hiding this comment.
Approved for style and structure only, with changes.
Co-authored-by: Nick Vigilante <[email protected]>
|
@mdanter and @nickvigilante is it good to merge? |
nickvigilante
left a comment
There was a problem hiding this comment.
Reviewed and approved for style only, and the content looks reasonable. I'd wait for one more review though before merging.
|
@mdanter Can we get your review on this PR? |
Co-authored-by: Nick Vigilante <[email protected]>
Co-authored-by: Nick Vigilante <[email protected]>
Co-authored-by: Nick Vigilante <[email protected]>
Co-authored-by: Nick Vigilante <[email protected]>
Co-authored-by: Nick Vigilante <[email protected]>
Co-authored-by: Nick Vigilante <[email protected]>
Co-authored-by: Nick Vigilante <[email protected]>
Co-authored-by: Nick Vigilante <[email protected]>
|
@nickvigilante looks good from my perspective. Thank you for the stylistic improvements! |
What
Adds a Recovering from a stale tunnel section to the Coder Desktop user guide, with separate macOS and Windows procedures, and tightens the existing macOS log-collection instructions.
Why
Users in the field have hit a state where Coder Desktop's menu bar / tray shows Coder Connect as enabled but the embedded tunnel is no longer working:
workspace.coderfails to resolve (No such host), orfd60:627a:a42b::/48addresses that no longer route, causingcoder ssh, file sync, and the directory picker to hang.Related issues:
ExistsViaCoderConnectfalse positives when Coder Desktop has stale DNS but no working tunnel, causingcoder ssh --stdioto hang #26669 —ExistsViaCoderConnectfalse positives when Coder Desktop has stale DNSUntil the underlying state-management gap is fixed in the apps, the docs should give users (and support) a safe, repeatable way to recover without rebooting.
Changes
docs/user-guides/desktop/index.md:scutil --nc stop, quit the app viaosascript, restart the helper daemon in place withlaunchctl kickstart -k system/com.coder.Coder-Desktop.Helper, flush DNS caches, then relaunch.launchctl bootout, which removes the daemon from launchd's system domain entirely and is not re-bootstrapped on app relaunch.is.coder--connect--enabled--right--now.coder(defined intailnet/conn.goasIsCoderConnectEnabledFmtString) so users don't need a workspace name to confirm the tunnel is healthy.dig @fd60:627a:a42b::53(explicit server) anddscacheutil -q host -a namebecause plaindigdoes not respect the macOS system resolver.Coder Desktopservice, flush DNS, restart, then verify the NRPT rule and Wintun adapter. Notes thatipconfig /flushdnsdoes not reset the embedded resolver and that filtering agents (e.g., Zscaler) may still shadow.coderlookups.subsystem == "com.coder.Coder-Desktop"tosubsystem BEGINSWITH "com.coder.Coder-Desktop"so the export captures the app, helper daemon, and network extension (which all log under prefixed subsystems).log streamexample for live tailing while reproducing an issue.Verification
npx markdownlint-cli2 docs/user-guides/desktop/index.md— 0 errors.kickstart -kform, in particular, was confirmed to restart the helper without breaking the install, unlikebootout).Created on behalf of @mdanter