From cbbbb4492a5a75b4b143e663cd3aaa9c997cea15 Mon Sep 17 00:00:00 2001
From: Spike Curtis <spike@coder.com>
Date: Wed, 21 May 2025 09:28:31 +0400
Subject: [PATCH] docs: explain coder:// link for RDP (#17901)

fixes https://github.com/coder/internal/issues/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.
---
 .../workspace-access/remote-desktops.md       | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/docs/user-guides/workspace-access/remote-desktops.md b/docs/user-guides/workspace-access/remote-desktops.md
index ef8488f588..2fe512b686 100644
--- 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