Home
Install
User Guides
Access Workspaces
Coder Desktop
Workspace Management
Workspace Scheduling
Workspace Lifecycle
Dotfiles
Administration
Contributing
Tutorials
Reference
Home
/
User Guides
/
Coder Desktop

Coder Desktop

Early Access

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

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:

    Sign in to your Coder deployment

  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 CoderVPN toggle to start the VPN.

    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 CoderVPN to start.

  10. CoderVPN is now running!

CoderVPN

While active, CoderVPN will list your owned workspaces and configure your system to be able to connect to them over private IPv6 addresses and custom hostnames ending in .coder.

Coder Desktop list of workspaces

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

On macOS you can use ping6 in your terminal to verify the connection to your workspace:

ping6 -c 5 your-workspace.coder

On Windows, you can use ping in a Command Prompt or PowerShell terminal to verify the connection to your workspace:

ping -n 5 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.

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

ssh your-workspace.coder

⚠️ Note: Currently, the Coder IDE extensions for VSCode and JetBrains create their own tunnel and do not utilize the CoderVPN tunnel to connect to workspaces.

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 CoderVPN 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.

See an opportunity to improve our docs? Make an edit.
On this page