# Coder Desktop

Coder Desktop provides seamless access to your remote workspaces through a native application. Connect to workspace services using simple hostnames like `myworkspace.coder`, launch applications with one click, and synchronize files between local and remote environments, all without installing a CLI or configuring manual port forwarding.

<Callout type="success" title="Tip">
  Coder Desktop provides **automatic port forwarding** to every service running in your workspace. Any port your application listens on is instantly accessible at `workspace-name.coder:PORT` with no manual setup required. For a comparison of all port forwarding methods, see [Workspace Ports](/beta-docs/user-guides/workspace-access/port-forwarding/).
</Callout>

## What You'll Need [#what-youll-need]

* A Coder deployment running `v2.20.0` or [later](https://github.com/coder/coder/releases/latest)
* Administrator privileges on your local machine (for VPN extension installation)
* Access to your Coder deployment URL

## Quick Start [#quick-start]

1. Install: `brew install --cask coder/coder/coder-desktop` (macOS) or `winget install Coder.CoderDesktop` (Windows)
2. Open Coder Desktop and approve any system prompts to complete the installation.
3. Sign in with your deployment URL and session token
4. Enable "Coder Connect" toggle
5. Access workspaces at `workspace-name.coder`

## How It Works [#how-it-works]

**Coder Connect**, the primary component of Coder Desktop, creates a secure tunnel to your Coder deployment, allowing you to:

* **Access workspaces directly**: Connect via `workspace-name.coder` hostnames
* **Automatic port forwarding**: All workspace ports are available at `workspace-name.coder:PORT` with no configuration
* **Use any application**: SSH clients, browsers, IDEs work seamlessly
* **Sync files**: Bidirectional sync between local and remote directories
* **Work offline**: Edit files locally, sync when reconnected

The VPN extension routes only Coder traffic—your other internet activity remains unchanged.

## Installation [#installation]

<OSTab items="[&#x22;macOS&#x22;, &#x22;Windows&#x22;]">
  <Tab value="macOS">
    <Tabs items="[&#x22;Homebrew (Recommended)&#x22;, &#x22;Manual Installation&#x22;]" groupId="coder-docs-tab:homebrew-recommended-manual-installation" persist="true">
      <Tab value="Homebrew (Recommended)">
        ```sh
        brew install --cask coder/coder/coder-desktop
        ```
      </Tab>

      <Tab value="Manual Installation">
        1. Download the latest release from [coder-desktop-macos releases](https://github.com/coder/coder-desktop-macos/releases)
        2. Run `Coder-Desktop.pkg` and follow the prompts to install
        3. `Coder Desktop.app` will be installed to your Applications folder
      </Tab>
    </Tabs>

    Coder Desktop requires VPN extension permissions:

    1. When prompted with **"Coder Desktop" would like to use a new network extension**, select **Open System Settings**
    2. In **Network Extensions** settings, enable the Coder Desktop extension
    3. You may need to enter your password to authorize the extension

    ✅ **Verify Installation**: Coder Desktop should appear in your menu bar
  </Tab>

  <Tab value="Windows">
    <Tabs items="[&#x22;WinGet (Recommended)&#x22;, &#x22;Manual Installation&#x22;]" groupId="coder-docs-tab:manual-installation-winget-recommended" persist="true">
      <Tab value="WinGet (Recommended)">
        ```sh
        winget install Coder.CoderDesktop
        ```
      </Tab>

      <Tab value="Manual Installation">
        1. Download the latest `CoderDesktop` installer (`.exe`) from [coder-desktop-windows releases](https://github.com/coder/coder-desktop-windows/releases)
        2. Choose the correct architecture (`x64` or `arm64`) for your system
        3. Run the installer and accept the license terms
        4. If prompted, install the .NET Windows Desktop Runtime
        5. Install Windows App Runtime SDK if prompted
      </Tab>
    </Tabs>

    * [.NET Windows Desktop Runtime](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) (installed automatically if not present)
    * Windows App Runtime SDK (may require manual installation)

    ✅ **Verify Installation*&#x2A;: Coder Desktop should appear in your system tray (you may need to click &#x2A;*^** to show hidden icons)
  </Tab>
</OSTab>

## Testing Your Connection [#testing-your-connection]

Once connected, test access to your workspaces:

<Tabs items="[&#x22;SSH Connection&#x22;, &#x22;Ping Test&#x22;, &#x22;Web Services&#x22;]" groupId="coder-docs-tab:ping-test-ssh-connection-web-services" persist="true">
  <Tab value="SSH Connection">
    ```sh
    ssh your-workspace.coder
    ```
  </Tab>

  <Tab value="Ping Test">
    ```sh
    # macOS
    ping6 -c 3 your-workspace.coder

    # Windows
    ping -n 3 your-workspace.coder
    ```
  </Tab>

  <Tab value="Web Services">
    Open `http://your-workspace.coder:PORT` in your browser, replacing `PORT` with the specific service port you want to access (e.g. 3000 for frontend, 8080 for API)
  </Tab>
</Tabs>

## Administrator Configuration [#administrator-configuration]

Organizations that manage Coder Desktop deployments can configure the application using MDM (Mobile Device Management) or group policy.

### Disable Automatic Updates [#disable-automatic-updates]

Administrators can disable the built-in auto-updater to manage updates through their own software distribution system.

<OSTab items="[&#x22;macOS&#x22;, &#x22;Windows&#x22;]">
  <Tab value="macOS">
    Set the `disableUpdater` preference to `true` using the `defaults` command:

    ```sh
    defaults write com.coder.Coder-Desktop disableUpdater -bool true
    ```

    Organization administrators can also enforce this setting across managed devices using MDM (Mobile Device Management) software by deploying a configuration profile that sets this preference.
  </Tab>

  <Tab value="Windows">
    Set the `Updater:Enable` registry value to `0` under `HKEY_LOCAL_MACHINE\SOFTWARE\Coder Desktop\App`:

    ```ps1
    New-Item -Path "HKLM:\SOFTWARE\Coder Desktop\App" -Force
    New-ItemProperty -Path "HKLM:\SOFTWARE\Coder Desktop\App" -Name "Updater:Enable" -Value 0 -PropertyType DWord -Force
    ```

    You can also configure a `Updater:ForcedChannel` string value to lock users to a specific update channel (e.g. `stable`).

    <Callout type="info" title="Note">
      For security, updater settings can only be configured at the machine level (`HKLM`), not per-user (`HKCU`).
    </Callout>
  </Tab>
</OSTab>

## Troubleshooting [#troubleshooting]

### Connection Issues [#connection-issues]

#### Can't connect to workspace [#cant-connect-to-workspace]

* Verify Coder Connect is enabled (toggle should be ON)
* Check that your deployment URL is correct
* Ensure your session token hasn't expired
* Try disconnecting and reconnecting Coder Connect

#### VPN extension not working [#vpn-extension-not-working]

* Restart Coder Desktop
* Check system permissions for network extensions
* Ensure only one copy of Coder Desktop is installed

### Recover from a stale tunnel [#recover-from-a-stale-tunnel]

If the menu bar or tray shows **Coder Connect** as enabled but workspaces are
unreachable (SSH hangs, `workspace.coder` fails to resolve, or file sync cannot
list the workspace directory), the embedded tunnel may be in a stale state.
Restart the helper components first.
If that doesn't resolve the issue, reboot your computer.

<OSTab items="[&#x22;macOS&#x22;, &#x22;Windows&#x22;]">
  <Tab value="macOS">
    Run the following commands in a terminal.
    These steps leave the app and helper daemon installed.
    They only restart the running tunnel and flush DNS caches.

    1. Stop the Coder VPN configuration:

       ```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
       ```

    2. Quit the Coder Desktop app:

       ```shell
       osascript -e 'tell application id "com.coder.Coder-Desktop" to quit'
       ```

    3. Restart the helper daemon in place:

       ```shell
       sudo launchctl kickstart -k system/com.coder.Coder-Desktop.Helper
       ```

       <Callout type="warn" title="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.
       </Callout>

    4. Flush DNS caches:

       ```shell
       sudo dscacheutil -flushcache
       sudo killall -HUP mDNSResponder
       ```

    5. Confirm the stale tunnel is gone (the command should print nothing):

       ```shell
       scutil --nc list | grep "com.coder.Coder-Desktop"
       ```

    6. Relaunch **Coder Desktop** from your `/Applications` folder and toggle **Coder Connect** back on.

    To verify the tunnel is healthy after relaunching, query the built-in sentinel
    hostname against Coder Desktop's embedded DNS server:

    ```shell
    dig @fd60:627a:a42b::53 AAAA is.coder--connect--enabled--right--now.coder +short
    dscacheutil -q host -a name is.coder--connect--enabled--right--now.coder
    ```

    Both commands should return an `fd60:627a:a42b::/48` address.
    If `dig` returns nothing or `dscacheutil` reports no entries, Coder Connect is not publishing DNS.
    [Collect logs](#collect-logs) and file an issue.
  </Tab>

  <Tab value="Windows">
    Run the following in an **elevated PowerShell** session.
    The service restart clears the embedded DNS state.
    The NRPT and adapter checks confirm the system routing policy is intact.

    1. Stop the app and the VPN service:

       ```ps1
       Get-Process -Name "Coder Desktop" -ErrorAction SilentlyContinue | Stop-Process -Force
       Stop-Service -Name "Coder Desktop" -Force
       ```

    2. Flush DNS caches:

       ```ps1
       ipconfig /flushdns
       Clear-DnsClientCache
       ```

    3. Start the service again and relaunch the app:

       ```ps1
       Start-Service -Name "Coder Desktop"
       Start-Process "C:\Program Files\Coder Desktop\CoderDesktop.exe"
       ```

    4. After re-enabling Coder Connect in the tray, verify the NRPT rule and the Wintun adapter exist:

       ```ps1
       Get-DnsClientNrptRule | Where-Object { $_.Namespace -like "*.coder" }
       Get-NetAdapter | Where-Object { $_.InterfaceDescription -like "*Wintun*" }
       ```

       If either command returns nothing while Coder Connect shows as enabled,
       the tunnel did not finish coming up. Disable and re-enable the toggle, or
       repeat the steps above.

    <Callout type="info" title="Note">
      `ipconfig /flushdns` does not reset Coder Desktop's embedded DNS resolver;
      restarting the service is what clears its internal cache. If you are running
      a network filtering agent (for example, Zscaler), it may shadow `.coder`
      lookups even after the tunnel comes back. Check with your IT team if DNS
      still fails after a clean restart.
    </Callout>
  </Tab>
</OSTab>

### Collect logs [#collect-logs]

When reporting an issue, attach the relevant log files so we can diagnose it faster.

<OSTab items="[&#x22;macOS&#x22;, &#x22;Windows&#x22;]">
  <Tab value="macOS">
    Coder Desktop and its network extension write to the Apple [unified logging system](https://developer.apple.com/documentation/os/logging). The file sync (Mutagen) daemon writes to a separate log file.

    1. Export the unified logs for the last hour with the `log` command:

       ```sh
       log show --predicate 'subsystem BEGINSWITH "com.coder.Coder-Desktop"' \
         --info --debug --last 1h > ~/Desktop/coder-desktop.log
       ```

       The `BEGINSWITH` predicate captures the app, the helper daemon, and the
       network extension, which all log under subsystems prefixed with
       `com.coder.Coder-Desktop`. Adjust `--last` (e.g. `30m`, `2h`, `1d`) to
       cover the time the issue occurred.

       You can stream the logs live while reproducing an issue:

       ```shell
       log stream --predicate 'subsystem BEGINSWITH "com.coder.Coder-Desktop"' --info --debug
       ```

       You can also view the same logs interactively in **Console.app** by
       filtering on `subsystem:com.coder.Coder-Desktop` with Info and Debug
       messages enabled.

    2. If you're using file sync, also collect the Mutagen daemon log:

       ```sh
       ~/Library/Application\ Support/Coder\ Desktop/Mutagen/daemon.log
       ```

       Coder Desktop also opens this file in Console automatically when the file sync daemon fails.
  </Tab>

  <Tab value="Windows">
    Coder Desktop has three components that write logs: the app (UI), the VPN service, and the file sync (Mutagen) daemon.

    1. App log (daily rolling):

       ```ps1
       %LOCALAPPDATA%\CoderDesktop\app.log
       ```

    2. VPN service log (default install path):

       ```ps1
       C:\Program Files\Coder Desktop\coder-desktop-service.log
       ```

    3. File sync (Mutagen) daemon log, if you use file sync:

       ```ps1
       %LOCALAPPDATA%\CoderDesktop\mutagen\daemon.log
       ```

    You can quickly open the app log directory by pasting `%LOCALAPPDATA%\CoderDesktop` into File Explorer.
  </Tab>
</OSTab>

<Callout type="success" title="Tip">
  Before attaching logs to a public issue, review them for any sensitive information (deployment URLs, usernames, hostnames) and redact as needed.
</Callout>

### Getting Help [#getting-help]

If you encounter issues not covered here:

* **File an issue**: [macOS](https://github.com/coder/coder-desktop-macos/issues) | [Windows](https://github.com/coder/coder-desktop-windows/issues) | [General](https://github.com/coder/coder/issues)
* **Community support**: [Discord](https://coder.com/chat)

## Uninstalling [#uninstalling]

<OSTab items="[&#x22;macOS&#x22;, &#x22;Windows&#x22;]">
  <Tab value="macOS">
    1. **Disable Coder Connect** in the app menu
    2. **Quit Coder Desktop** completely
    3. **Remove VPN extension** from System Settings > Network Extensions
    4. **Delete the app** from Applications folder
    5. **Remove configuration** (optional): `rm -rf ~/Library/Application\ Support/Coder\ Desktop`
  </Tab>

  <Tab value="Windows">
    1. **Disable Coder Connect** in the app menu
    2. **Quit Coder Desktop** from system tray
    3. **Uninstall** via Settings > Apps or Control Panel
    4. **Remove configuration** (optional): Delete `%APPDATA%\Coder Desktop`
  </Tab>
</OSTab>

## Next Steps [#next-steps]

* [Using Coder Connect and File Sync](/beta-docs/user-guides/desktop/desktop-connect-sync/)
* [Compare port forwarding methods](/beta-docs/user-guides/workspace-access/port-forwarding/)