coder/docs/user-guides/desktop/index.md

Coder Desktop (Beta)

Use Coder Desktop to work on your workspaces as though they're on your LAN, no port-forwarding required.

Note

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

Install Coder Desktop

You can install Coder Desktop on macOS or Windows.

macOS

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.

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.

Windows

1. Download the latest CoderDesktop installer executable (.exe) from the coder-desktop-windows release page.

   Choose the architecture that fits your Windows system, x64 or arm64.

2. Open the .exe file, acknowledge the license terms and conditions, and select Install.

3. If a suitable .NET runtime is not already installed, the installation might prompt you with the .NET Windows Desktop Runtime installation.

   In that installation window, select Install. Select Close when the runtime installation completes.

4. When the Coder Desktop installation completes, select Close.

5. Find and open Coder Desktop from your Start Menu.

6. Some systems require an additional Windows App Runtime SDK.

   Select Yes if you are prompted to install it. This will open your default browser where you can download and install the latest stable release of the Windows App Runtime SDK.

   Reopen Coder Desktop after you install the runtime.

7. Coder Desktop starts minimized in the Windows System Tray.

   You might need to select the ^ in your system tray to show more icons.

8. 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:

   macOS

   

   Windows

   

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

   

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:

   

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

   

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

   

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

   

   This may take a few moments, as 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!

Coder Connect

While active, Coder Connect will list the workspaces you own and will configure your system to connect to them over private IPv6 addresses and custom hostnames ending in .coder.

To copy the .coder hostname of a workspace agent, you can click the copy icon beside it.

You can also connect to the SSH server in your workspace using any SSH client, such as OpenSSH or PuTTY:

ssh your-workspace.coder

Any services listening on ports in your workspace will be available on the same hostname. For example, you can access a web server on port 8080 by visiting http://your-workspace.coder:8080 in your browser.

Note

Currently, the Coder IDE extensions for VSCode and JetBrains create their own tunnel and do not utilize the Coder Connect tunnel to connect to workspaces.

Ping your workspace

macOS

Use ping6 in your terminal to verify the connection to your workspace:

ping6 -c 5 your-workspace.coder

Windows

Use ping in a Command Prompt or PowerShell terminal to verify the connection to your workspace:

ping -n 5 your-workspace.coder

Sync a local directory with your workspace

Coder Desktop file sync provides bidirectional synchronization between a local directory and your workspace. You can work offline, add screenshots to documentation, or use local development tools while keeping your files in sync with your workspace.

1. Create a new local directory.

   If you select an existing clone of your repository, Desktop will recognize it as conflicting files.

2. In the Coder Desktop app, select File sync.

   

3. Select the + in the corner to select the local path, workspace, and remote path, then select Add:

   

4. File sync clones your workspace directory to your local directory, then watches for changes:

   

   For more information about the current status, hover your mouse over the status.

File sync excludes version control system directories like .git/ from synchronization, so keep your Git-cloned repository wherever you run Git commands. This means that if you use an IDE with a built-in terminal to edit files on your remote workspace, that should be the Git clone and your local directory should be for file syncs.

Note

Coder Desktop uses alpha and beta to distinguish between the:

• Local directory: alpha
• Remote directory: beta

File sync conflicts

File sync shows a Conflicts status when it detects conflicting files.

You can hover your mouse over the status for the list of conflicts:

If you encounter a synchronization conflict, delete the conflicting file that contains changes you don't want to keep.

Accessing web apps in a secure browser context

Some web applications require a secure context to function correctly. A browser typically considers an origin secure if the connection is to localhost, or over HTTPS.

As Coder Connect uses its own hostnames and does not provide TLS to the browser, Google Chrome and Firefox will not allow any web APIs that require a secure context.

Note

Despite the browser showing an insecure connection without HTTPS, the underlying tunnel is encrypted with WireGuard in the same fashion as other Coder workspace connections (e.g. coder port-forward).

If you require secure context web APIs, you will need to mark the workspace hostnames as secure in your browser settings.

We are planning some changes to Coder Desktop that will make accessing secure context web apps easier. Stay tuned for updates.

Chrome

1. Open Chrome and visit chrome://flags/#unsafely-treat-insecure-origin-as-secure.

2. Enter the full workspace hostname, including the http scheme and the port (e.g. http://your-workspace.coder:8080), into the Insecure origins treated as secure text field.

   If you need to enter multiple URLs, use a comma to separate them.

   

3. Ensure that the dropdown to the right of the text field is set to Enabled.

4. You will be prompted to relaunch Google Chrome at the bottom of the page. Select Relaunch to restart Google Chrome.

5. On relaunch and subsequent launches, Google Chrome will show a banner stating "You are using an unsupported command-line flag". This banner can be safely dismissed.

6. Web apps accessed on the configured hostnames and ports will now function correctly in a secure context.

Firefox

1. Open Firefox and visit about:config.

2. Read the warning and select Accept the Risk and Continue to access the Firefox configuration page.

3. Enter dom.securecontext.allowlist into the search bar at the top.

4. Select String on the entry with the same name at the bottom of the list, then select the plus icon on the right.

5. In the text field, enter the full workspace hostname, without the http scheme and port: your-workspace.coder. Then select the tick icon.

   If you need to enter multiple URLs, use a comma to separate them.

   

6. Web apps accessed on the configured hostnames will now function correctly in a secure context without requiring a restart.

Troubleshooting

Mac: Issues updating Coder Desktop

No workspaces!

And

Internal Error: The VPN must be started with the app open during first-time setup.

Due to an issue with the way Coder Desktop works with the macOS interprocess communication mechanism(XPC) system network extension, core Desktop functionality can break when you upgrade the application.

The resolution depends on which version of macOS you use:

macOS <=14

1. Delete the application from /Applications.
2. Restart your device.

macOS 15+

1. Open System Settings
2. Select General
3. Select Login Items & Extensions
4. Scroll down, and select the ⓘ for Network Extensions
5. Select the ... next to Coder Desktop, then Delete Extension, and follow the prompts.
6. Re-open Coder Desktop and follow the prompts to reinstall the network extension.