102.0K
HomeUser GuidesCoder Desktop

Coder Desktop

Coder Desktop provides seamless access to your remote workspaces without the need to install a CLI or configure manual port forwarding. Connect to workspace services using simple hostnames like myworkspace.coder, launch native applications with one click, and synchronize files between local and remote environments.

Coder Desktop requires a Coder deployment running v2.20.0 or later.

Install Coder Desktop

Important

Coder Desktop can't connect through a corporate VPN.

Due to a known issue, if your Coder deployment requires that you connect through a corporate VPN, Desktop will timeout when it tries to connect.

  1. Use Homebrew to install Coder Desktop:

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

    Alternatively, you can manually install Coder Desktop from the releases page.

  2. Open Coder Desktop from the Applications directory.

  3. The application is treated as a system VPN. macOS will prompt you to confirm with:

    "Coder Desktop" would like to use a new network extension

    Select Open System Settings.

  4. In the Network Extensions system settings, enable the Coder Desktop extension.

  5. Continue to the configuration section.

Configure

Before you can use Coder Desktop, you will need to sign in.

  1. Open the Desktop menu and select Sign in:

    Coder Desktop menu before the user signs in

  2. In the Sign In window, enter your Coder deployment's URL and select Next:

    Coder Desktop sign in

  3. macOS: Select the link to your deployment's /cli-auth page to generate a session token.

    Windows: Select Generate a token via the Web UI.

  4. In your web browser, you may be prompted to sign in to Coder with your credentials.

  5. Copy the session token to the clipboard:

    Copy session token

  6. Paste the token in the Session Token field of the Sign In screen, then select Sign In:

    Paste the session token in to sign in

  7. macOS: Allow the VPN configuration for Coder Desktop if you are prompted:

    Copy session token

  8. Select the Coder icon in the menu bar (macOS) or system tray (Windows), and click the Coder Connect toggle to enable the connection.

    Coder Desktop on Windows - enable Coder Connect

    This may take a few moments, because Coder Desktop will download the necessary components from the Coder server if they have been updated.

  9. macOS: You may be prompted to enter your password to allow Coder Connect to start.

  10. Coder Connect is now running!

Troubleshooting

If you encounter an issue with Coder Desktop that is not listed here, file an issue in the GitHub repository for Coder Desktop for macOS or Windows, in the main Coder repository, or consult the community on Discord.

Known Issues

macOS: Do not install more than one copy of Coder Desktop

To avoid system VPN configuration conflicts, only one copy of Coder Desktop.app should exist on your Mac, and it must remain in /Applications.

Coder Desktop can't connect through another VPN

If the logged in Coder deployment requires a corporate VPN to connect, Coder Connect can't establish communication through the VPN, and will time out.

This is due to known issues with macOS and Windows networking. A resolution is in progress.

Next Steps