Skip to content

docs: reorganize remote desktop docs #18716

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 12 commits into
base: main
Choose a base branch
from
+110 −65
Open

docs: reorganize remote desktop docs #18716

Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
e1d87a5
docs: reorganize remote desktop docs
matifali Jul 2, 2025
ae8d1f8
Merge branch 'main' into remote-desktop-module
matifali Jul 2, 2025
0fc85f3
refactor
matifali Jul 2, 2025
da90f1c
remove redundant image
matifali Jul 2, 2025
a42ea7b
remove redundant image
matifali Jul 2, 2025
3a5c9cb
refactor
matifali Jul 2, 2025
c066e68
refactor
matifali Jul 2, 2025
5b94ed1
Update remote-desktops.md
matifali Jul 3, 2025
7621012
Merge branch 'main' into remote-desktop-module
matifali Jul 3, 2025
158abfd
move RDP UDP issue to an alert
matifali Jul 3, 2025
699ca07
Update VNC client installation instructions in docs
matifali Jul 3, 2025
a182082
remove section heading
matifali Jul 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
175 changes: 110 additions & 65 deletions docs/user-guides/workspace-access/remote-desktops.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,70 +1,26 @@
# Remote Desktops

## VNC Desktop
## RDP

The common way to use remote desktops with Coder is through VNC.
The most common way to get a GUI-based connection to a Windows workspace is by using Remote Desktop Protocol (RDP).

![VNC Desktop in Coder](../../images/vnc-desktop.png)

Workspace requirements:

- VNC server (e.g. [tigervnc](https://tigervnc.org/))
- VNC client (e.g. [novnc](https://novnc.com/info.html))

Installation instructions vary depending on your workspace's operating system,
platform, and build system.

As a starting point, see the
[enterprise-desktop](https://github.com/coder/images/tree/main/images/desktop)
image. It can be used to provision a Dockerized workspace with the
following software:

- Ubuntu 24.04
- XFCE Desktop
- KasmVNC Server and Web Client
<div class="tabs">

## RDP Desktop
### Desktop Client

To use RDP with Coder, you'll need to install an
[RDP client](https://docs.microsoft.com/en-us/windows-server/remote/remote-desktop-services/clients/remote-desktop-clients)
on your local machine, and enable RDP on your workspace.

<div class="tabs">

### CLI

Use the following command to forward the RDP port to your local machine:

```console
coder port-forward <workspace-name> --tcp 3399:3389
```

Then, connect to your workspace via RDP at `localhost:3399`.
![windows-rdp](../../images/ides/windows_rdp_client.png)

### RDP with Coder Desktop

[Coder Desktop](../desktop/index.md)'s Coder Connect feature creates a connection to your workspaces in the background.
There is no need for port forwarding when it is enabled.
#### Coder Desktop

Use your favorite RDP client to connect to `<workspace-name>.coder` instead of `localhost:3399`.
[Coder Desktop](../desktop/index.md)'s **Coder Connect** feature creates a connection to your workspaces in the background. Use your favorite RDP client to connect to `<workspace-name>.coder`.

> [!NOTE]
> Some versions of Windows, including Windows Server 2022, do not communicate correctly over UDP
> when using Coder Connect because they do not respect the maximum transmission unit (MTU) of the link.
> When this happens, the RDP client will appear to connect, but displays a blank screen.
>
> To avoid this error, Coder's [Windows RDP](https://registry.coder.com/modules/windows-rdp) module
> [disables RDP over UDP automatically](https://github.com/coder/registry/blob/b58bfebcf3bcdcde4f06a183f92eb3e01842d270/registry/coder/modules/windows-rdp/powershell-installation-script.tftpl#L22).
>
> To disable RDP over UDP, run the following in PowerShell:
>
> ```powershell
> New-ItemProperty -Path 'HKLM:\SOFTWARE\Policies\Microsoft\Windows NT\Terminal Services' -Name "SelectTransport" -Value 1 -PropertyType DWORD -Force
> Restart-Service -Name "TermService" -Force
> ```
You can use the [RDP Desktop](https://registry.coder.com/modules/coder/local-windows-rdp) module to add a single-click button to open an RDP session in the browser.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest adding a screenshot or GIF here of what it looks like from the desktop client. Would significantly improve the visual identity of the first part of the page and show what the Desktop UX looks like.


You can also use a URI handler to directly launch an RDP session.
You can also use a URI handler to launch an RDP session directly.

The URI format is:

Expand All @@ -88,32 +44,121 @@ locals {
resource "coder_app" "rdp-coder-desktop" {
agent_id = resource.coder_agent.main.id
slug = "rdp-desktop"
display_name = "RDP with Coder Desktop"
display_name = "RDP Desktop"
url = "coder://${local.server_name}/v0/open/ws/${data.coder_workspace.me.name}/agent/main/rdp?username=Administrator&password=coderRDP!"
icon = "/icon/desktop.svg"
external = true
}
```

#### CLI

Use the following command to forward the RDP port to your local machine:

```console
coder port-forward <workspace-name> --tcp 3399:3389
```

Then, connect to your workspace via RDP at `localhost:3399`.
![windows-rdp](../../images/ides/windows_rdp_client.png)

</div>

> [!NOTE]
> Some versions of Windows, including Windows Server 2022, do not communicate correctly over UDP when using Coder Connect because they do not respect the maximum transmission unit (MTU) of the link. When this happens, the RDP client will appear to connect, but displays a blank screen.
>
> To avoid this error, Coder's [Windows RDP](https://registry.coder.com/modules/windows-rdp) module [disables RDP over UDP automatically](https://github.com/coder/registry/blob/b58bfebcf3bcdcde4f06a183f92eb3e01842d270/registry/coder/modules/windows-rdp/powershell-installation-script.tftpl#L22).
>
> To disable RDP over UDP manually, run the following in PowerShell:
>
> ```powershell
> New-ItemProperty -Path 'HKLM:\SOFTWARE\Policies\Microsoft\Windows NT\Terminal Services' -Name "SelectTransport" -Value 1 -PropertyType DWORD -Force
> Restart-Service -Name "TermService" -Force
> ```

### Browser

Our [RDP Web](https://registry.coder.com/modules/windows-rdp) module in the Coder Registry adds a one-click button to open an RDP session in the browser. This requires just a few lines of Terraform in your template, see the documentation on our registry for setup.

![Windows RDP Web](../../images/user-guides/web-rdp-demo.png)

</div>

> [!NOTE]
> The default username is `Administrator` and the password is `coderRDP!`.

## RDP Web
## Amazon DCV

Our [Amazon DCV Windows](https://registry.coder.com/modules/amazon-dcv-windows) installs and configures the Amazon DCV server for seamless remote desktop access. It allows connecting through the both the [Amazon DCV desktop clients](https://docs.aws.amazon.com/dcv/latest/userguide/using-connecting.html) and a [web browser](https://docs.aws.amazon.com/dcv/latest/userguide/using-connecting-browser-connect.html).

<div class="tabs">

### Desktop Client

Connect using the [Amazon DCV Desktop client](https://docs.aws.amazon.com/dcv/latest/userguide/using-connecting.html) by forwarding the DCV port to your local machine:

<div class="tabs">

#### Coder Desktop

[Coder Desktop](../desktop/index.md)'s **Coder Connect** feature creates a connection to your workspaces in the background. Use DCV client to connect to `<workspace-name>.coder:8443`.

#### CLI

Use the following command to forward the DCV port to your local machine:

```console
coder port-forward <workspace-name> --tcp 8443:8443
```

</div>

### Browser

Our [Amazon DCV Windows](https://registry.coder.com/modules/amazon-dcv-windows) module adds a one-click button to open an Amazon DCV session in the browser. This requires just a few lines of Terraform in your template, see the documentation on our registry for setup.

</div>

![Amazon DCV](../../images/user-guides/amazon-dcv-windows-demo.png)

## VNC

The common way to connect to a desktop session of a Linux workspace is to use a VNC client. The VNC client can be installed on your local machine or accessed through a web browser. There is an additional requirement to install the VNC server on the workspace.

Installation instructions vary depending on your workspace's operating system, platform, and build system. Refer to the [enterprise-desktop](https://github.com/coder/images/tree/main/images/desktop) image for a starting point which can be used to provision a Dockerized workspace with the following software:

- Ubuntu 24.04
- XFCE Desktop
- KasmVNC Server and Web Client

<div class="tabs">

### Desktop Client

Our [Windows RDP](https://registry.coder.com/modules/windows-rdp) module in the Coder
Registry adds a one-click button to open an RDP session in the browser. This
requires just a few lines of Terraform in your template, see the documentation
on our registry for setup.
Use a VNC client (e.g., [TigerVNC](https://tigervnc.org/)) by forwarding the VNC port to your local machine.

![Windows RDP Module in a Workspace](../../images/user-guides/web-rdp-demo.png)
<div class="tab">

## Amazon DCV Windows
#### Coder Desktop

Our [Amazon DCV Windows](https://registry.coder.com/modules/amazon-dcv-windows)
module adds a one-click button to open an Amazon DCV session in the browser.
This requires just a few lines of Terraform in your template, see the
documentation on our registry for setup.
[Coder Desktop](../desktop/index.md)'s **Coder Connect** feature allows you to connect to your workspace's VNC server at `<workspace-name>.coder:5900`.

![Amazon DCV Windows Module in a Workspace](../../images/user-guides/amazon-dcv-windows-demo.png)
#### CLI

Use the following command to forward the VNC port to your local machine:

```bash
coder port-forward <workspace-name> --tcp 5900:5900
```

Now you can connect to your workspace's VNC server using a VNC client at `localhost:5900`.

</div>

### Browser

The [KasmVNC module](https://registry.coder.com/modules/coder/kasmvnc) allows browser-based access to your workspace by installing and configuring the [KasmVNC](https://github.com/kasmtech/KasmVNC) server and web client.

</div>

![VNC Desktop in Coder](../../images/vnc-desktop.png)
Loading