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 8 commits into
base: main
Choose a base branch
from
+115 −65
Open

docs: reorganize remote desktop docs #18716

Changes from all commits
Commits
Show all changes
8 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
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
180 changes: 115 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:
#### Coder Desktop

```console
coder port-forward <workspace-name> --tcp 3399:3389
```
[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`.

Then, connect to your workspace via RDP at `localhost:3399`.
![windows-rdp](../../images/ides/windows_rdp_client.png)
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.

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

Use your favorite RDP client to connect to `<workspace-name>.coder` instead of `localhost:3399`.

> [!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 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,126 @@ 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>

### 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 [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.
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).

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

### Desktop Client

## Amazon DCV Windows
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:

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 class="tabs">

![Amazon DCV Windows Module in a Workspace](../../images/user-guides/amazon-dcv-windows-demo.png)
#### 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.

As a starting point, see the enterprise-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">

### Desktop Client

Use a VNC client (e.g., [TigerVNC](https://tigervnc.org/)) by forwarding the VNC port to your local machine.

<div class="tab">

#### Coder Desktop

[Coder Desktop](../desktop/index.md)'s **Coder Connect** feature allows you to connect to your workspace's VNC server at `<workspace-name>.coder:5900`.

#### 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)

## Troubleshooting

### RDP UDP Issues
Copy link
Contributor

Choose a reason for hiding this comment

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

Not sure I agree with putting this at the end instead of in the RDP section. Seems less likely to get read.

Copy link
Member Author

@matifali matifali Jul 3, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

There was a rendering issue with Notes in Tabs, so I moved it to the end. Looks like we are fixing it soon: https://github.com/coder/coder.com/pull/265

I can move it back once that PR gets merged.


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
```
Loading