124.8K
Skip to main content
HomeUser GuidesCoder Desktop

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.

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.

What You'll Need

  • A Coder deployment running v2.20.0 or later
  • Administrator privileges on your local machine (for VPN extension installation)
  • Access to your Coder deployment URL

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

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

brew install --cask coder/coder/coder-desktop

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

Testing Your Connection

Once connected, test access to your workspaces:

ssh your-workspace.coder

Administrator Configuration

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

Disable Automatic Updates

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

Set the disableUpdater preference to true using the defaults command:

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.

Troubleshooting

Connection Issues

Can't 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

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

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.

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:

    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:

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

  3. Restart the helper daemon in place:

    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.

  4. Flush DNS caches:

    sudo dscacheutil -flushcache sudo killall -HUP mDNSResponder

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

    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:

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 and file an issue.

Collect logs

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

Coder Desktop and its network extension write to the Apple unified logging system. The file sync (Mutagen) daemon writes to a separate log file.

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

    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:

    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:

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

    Coder Desktop also opens this file in Console automatically when the file sync daemon fails.

Tip

Before attaching logs to a public issue, review them for any sensitive information (deployment URLs, usernames, hostnames) and redact as needed.

Getting Help

If you encounter issues not covered here:

Uninstalling

  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

Next Steps