docs: explain coder:// link for RDP (#17901)

EdwardAngert · EdwardAngert · commit 030d77eac6ba · 2025-05-21T09:28:31.000+04:00
fixes coder/internal#627 Adds docs for `coder://` URLs for Windows Remote Desktop (RDP). Note that we might want to hold of merging since the URI handling is unreleased in Coder Desktop for Windows.
diff --git a/docs/user-guides/workspace-access/remote-desktops.md b/docs/user-guides/workspace-access/remote-desktops.md
@@ -47,6 +47,38 @@ Or use your favorite RDP client to connect to `localhost:3399`.
 
 The default username is `Administrator` and password is `coderRDP!`.
 
+### Coder Desktop URI Handling (Beta)
+
+[Coder Desktop](../desktop) can use a URI handler to directly launch an RDP session without setting up port-forwarding.
+The URI format is:
+
+```text
+coder://<your Coder server name>/v0/open/ws/<workspace name>/agent/<agent name>/rdp?username=<username>&password=<password>
+```
+
+For example:
+
+```text
+coder://coder.example.com/v0/open/ws/myworkspace/agent/main/rdp?username=Administrator&password=coderRDP!
+```
+
+To include a Coder Desktop button to the workspace dashboard page, add a `coder_app` resource to the template:
+
+```tf
+locals {
+  server_name = regex("https?:\\/\\/([^\\/]+)", data.coder_workspace.me.access_url)[0]
+}
+
+resource "coder_app" "rdp-coder-desktop" {
+  agent_id     = resource.coder_agent.main.id
+  slug         = "rdp-desktop"
+  display_name = "RDP with Coder 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
+}
+```
+
 ## RDP Web
 
 Our [WebRDP](https://registry.coder.com/modules/windows-rdp) module in the Coder
