## 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.coder` fails to resolve (`No such host`), or
* DNS returns stale `fd60:627a:a42b::/48` addresses that no longer
route, causing `coder ssh`, file sync, and the directory picker to hang.
Related issues:
* coder/coder#26669 — `ExistsViaCoderConnect` false positives when Coder
Desktop has stale DNS
* coder/coder-desktop-windows#171 — Tray reports Coder Connect as
healthy while tunnel/DNS is broken
Until 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`:
1. **New "Recovering from a stale tunnel" section** under
Troubleshooting:
* **macOS:** stop the VPN configuration with `scutil --nc stop`, quit
the app via `osascript`, restart the helper daemon in place with
`launchctl kickstart -k system/com.coder.Coder-Desktop.Helper`, flush
DNS caches, then relaunch.
* Includes a warning to **not** use `launchctl bootout`, which removes
the daemon from launchd's system domain entirely and is not
re-bootstrapped on app relaunch.
* Includes a verification step using the built-in sentinel hostname
`is.coder--connect--enabled--right--now.coder` (defined in
`tailnet/conn.go` as `IsCoderConnectEnabledFmtString`) so users don't
need a workspace name to confirm the tunnel is healthy.
* Uses `dig @fd60:627a:a42b::53` (explicit server) and `dscacheutil -q
host -a name` because plain `dig` does not respect the macOS system
resolver.
* **Windows:** stop the app and `Coder Desktop` service, flush DNS,
restart, then verify the NRPT rule and Wintun adapter. Notes that
`ipconfig /flushdns` does not reset the embedded resolver and that
filtering agents (e.g., Zscaler) may still shadow `.coder` lookups.
2. **macOS log-collection improvements:**
* Switch the predicate from `subsystem == "com.coder.Coder-Desktop"` to
`subsystem BEGINSWITH "com.coder.Coder-Desktop"` so the export captures
the app, helper daemon, and network extension (which all log under
prefixed subsystems).
* Add a `log stream` example for live tailing while reproducing an
issue.
## Verification
* `npx markdownlint-cli2 docs/user-guides/desktop/index.md` — 0 errors.
* macOS recovery steps were validated end-to-end on a real install (the
`kickstart -k` form, in particular, was confirmed to restart the helper
without breaking the install, unlike `bootout`).
---
Created on behalf of @mdanter
---------
Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com>
Co-authored-by: Atif Ali <atif@coder.com>
Co-authored-by: Nick Vigilante <nickvigilante@users.noreply.github.com>
Co-authored-by: Matyas Danter <mdanter@gmail.com>
Normalizes non-standard code-fence language tags across `docs/**` so a
strict highlighter (Shiki, used by Fumadocs) won't fail the build on an
unrecognized language, and unifies redundant synonym tags onto one
canonical form per language. The current renderer (Speed-Highlight)
detects the language from the code content, not the fence label, so this
drift wasn't visible until now.
## Changes
- `hcl` -> `tf` (199 fences, including indented ones nested in
numbered/bulleted lists). Shiki ships `hcl` and `terraform` as two
distinct grammars (not aliases); every `hcl`-tagged fence in `docs/**`
is actually Terraform resource/data/provider syntax, so the more
specific `terraform` grammar is correct for all of them. `tf` is Shiki's
own alias for that grammar, and it's also what GitHub's own markdown
renderer resolves to the same HCL/Terraform highlighting.
- `pwsh`/`powershell` -> `ps1`. Both `ps` and `ps1` are registered
PowerShell aliases in Shiki, but on GitHub's renderer only `.ps1` is a
registered file extension (`.ps` isn't), so `ps1` renders identically to
`powershell` there today while bare `ps` would silently lose
highlighting.
- `env` -> `dotenv` (a dedicated Shiki grammar for `KEY=VALUE` files)
- `text`/`output`/`none`/`url` -> `txt`. Same built-in plain-text
fallback either way, just shorter.
- `Dockerfile` -> `dockerfile` (lowercase)
- `bash`/`shell` -> `sh` (732 fences). Shiki and GitHub both alias all
three to a single shell grammar; this was already the style guide's
stated preference, just not enforced across the existing corpus until
now.
- `markdown` -> `md` (4 fences). Alias of the same grammar in both Shiki
and GitHub.
- `jsonc` -> `json` (1 fence). The block has no comments or trailing
commas, so it doesn't need the comments-capable grammar.
- `ts` -> `tsx` (2 fences, `docs/about/contributing/frontend.md`).
Verified the actual content tokenizes identically under both grammars,
and a sibling block in the same file already needs `tsx` for real JSX,
so unifying to one tag is safe for this file. Documented a caveat: `tsx`
mis-tokenizes the legacy angle-bracket type-assertion syntax
(`<Type>value`), which is invalid in real `.tsx` files anyway, so use
`value as Type` instead.
- `yml` -> `yaml` (1 fence)
- Updated `docs/.style/style-guide/formatting.md` to document all
canonical tags
`promql` (2 fences) and `caddyfile` (2 fences) are left as-is. Shiki
doesn't bundle a grammar for either, so they need a custom grammar
registration when the site adopts Shiki, rather than degrading to `txt`.
Tracked as follow-up work under DOCS-118 and
[DOCS-544](https://linear.app/codercom/issue/DOCS-544/vendor-a-local-promql-grammar-for-shiki-syntax-highlighting)
(promql).
Does not touch `offlinedocs/`.
Linear:
[DOCS-476](https://linear.app/codercom/issue/DOCS-476/normalize-docs-code-fence-languages-de-risk-shikifumadocs)
<details>
<summary>How the fence tags were verified</summary>
Each tag was tested against a real `shiki@latest` highlighter instance
(`codeToHtml`/`codeToTokens`) and cross-checked against GitHub's
`@wooorm/starry-night` grammar sources (the renderer that actually
displays these `.md` files today, in repo browsing and PR diffs), since
that's what determines whether brevity is safe before Shiki adoption:
```text
FAIL env -- Language `env` is not included in this bundle.
FAIL Dockerfile -- Language `Dockerfile` is not included in this bundle.
FAIL promql -- Language `promql` is not included in this bundle.
FAIL caddyfile -- Language `caddyfile` is not included in this bundle.
FAIL pwsh -- Language `pwsh` is not included in this bundle.
FAIL output -- Language `output` is not included in this bundle.
```
`hcl` doesn't error in Shiki, since it's a real grammar, but that's
exactly the trap: it was silently rendering every fence with the generic
HCL grammar instead of the Terraform-specific one. Every `hcl`-tagged
fence in `docs/**` was manually checked against `origin/main` and is
genuinely Terraform content.
For `ts`/`tsx`, tokenizing the actual doc content confirmed identical
output under both grammars; a synthetic test with the legacy
angle-bracket cast syntax confirmed `tsx` degrades on that specific
construct, which the style guide now calls out.
The first normalization pass only matched fence tags at column 0
(`^```tag$`), missing tags indented inside numbered/bulleted lists. A
follow-up pass caught the remaining occurrences at any indentation
level.
</details>
---
*This PR description and the underlying changes were prepared with Coder
Agents assistance.*
## Summary
Adds documentation for the "disable automatic updates" feature in Coder
Desktop.
This adds a new "Administrator Configuration" section to the Coder
Desktop docs that documents:
- **macOS**: Setting the `disableUpdater` UserDefaults key via MDM or
`defaults` command
- **Windows**: Setting the `Updater:Enable` registry value in
`HKLM\SOFTWARE\Coder Desktop\App`
The feature already exists in both platforms but was not documented in
the user-facing docs.
## Changes
- Added new "Administrator Configuration" section before
"Troubleshooting"
- Documented macOS MDM configuration for disabling updates
- Documented Windows registry configuration for disabling updates
- Mentioned the `ForcedChannel` option for locking update channels
---
Created on behalf of @ethanndickson
---------
Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com>
I ended up on the Coder Desktop docs page and thought half of it had disappeared, though it was actually tucked away behind a second page. This PR adds a next steps section to the first page that links there, as it seems very easy to miss right now.
closes#18071
- [x] move `## Accessing web apps in a secure browser context` to the
troubleshooting section
- [x] use a compacted view for troubleshooting topics to prevent them
from occupying a significant space on page
- [x] remove `Issues updating Coder Desktop`
- [x] Update screenshots
---------
Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
It looks like GFM does not respect the `![]` alert syntax (and any other
alert type) when it's enclosed within a div. This is true for both the
coder.com GFM renderer, and GitHub's (though I assume they're the same
internally).
When the section is surrounded by a `<div class="tabs">`:
When it's not:
In our case, we really want the tabs, and the alert block is less
important, so we'll downgrade it to a regular quote.
cc @aqandrew for visibility, in case you're aware of a workaround.
I realised we should advise against installing multiple copies, as I'm sure someone will try and get confused by Apple's obtuse error messaging.
Tailscale also has a similar warning: https://pkgs.tailscale.com/stable/#macos
