From dfd7ca3b98749d39396d078d8a4d00e3da3b805e Mon Sep 17 00:00:00 2001 From: Atif Ali Date: Tue, 26 May 2026 18:29:10 +0500 Subject: [PATCH] docs: improve discoverability of automatic port forwarding via Coder Desktop (#25675) --- docs/admin/networking/port-forwarding.md | 22 ++++++++++++++----- .../desktop/desktop-connect-sync.md | 8 ++++++- docs/user-guides/desktop/index.md | 7 +++++- docs/user-guides/workspace-access/index.md | 15 ++++++++++++- .../workspace-access/port-forwarding.md | 8 +++++-- 5 files changed, 49 insertions(+), 11 deletions(-) diff --git a/docs/admin/networking/port-forwarding.md b/docs/admin/networking/port-forwarding.md index 3c4e9777d0..f5678403ad 100644 --- a/docs/admin/networking/port-forwarding.md +++ b/docs/admin/networking/port-forwarding.md @@ -4,18 +4,28 @@ Port forwarding lets developers securely access processes on their Coder workspace from a local machine. A common use case is testing web applications in a browser. -There are three ways to forward ports in Coder: +There are four ways to forward ports in Coder: -- The `coder port-forward` command -- Dashboard -- SSH +| Method | Details | +|:---------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Coder Desktop](#coder-desktop) | Automatic port forwarding via VPN tunnel. All workspace ports are available at `workspace.coder:PORT` with no manual setup. Supports peer-to-peer connections. | +| [CLI](#the-coder-port-forward-command) | Forwards specific TCP or UDP ports from the workspace to local ports. Supports peer-to-peer connections. | +| [Dashboard](#dashboard) | Proxies traffic through the Coder control plane. | +| [SSH](#ssh) | Forwards ports over an SSH connection. | -The `coder port-forward` command is generally more performant than: +Coder Desktop and `coder port-forward` are generally more performant than: 1. The Dashboard which proxies traffic through the Coder control plane versus - peer-to-peer which is possible with the Coder CLI + peer-to-peer which is possible with the Coder CLI and Coder Desktop 1. `sshd` which does double encryption of traffic with both Wireguard and SSH +## Coder Desktop + +[Coder Desktop](../../user-guides/desktop/index.md) provides automatic port forwarding to every service running in your workspace. +Once Coder Connect is enabled, any port your application listens on is instantly accessible at `.coder:PORT` from your local machine, with no additional commands or configuration. + +This is the simplest option for most users. See the [Coder Desktop documentation](../../user-guides/desktop/index.md) for installation and setup. + ## The `coder port-forward` command This command can be used to forward TCP or UDP ports from the remote workspace diff --git a/docs/user-guides/desktop/desktop-connect-sync.md b/docs/user-guides/desktop/desktop-connect-sync.md index f6a45a5984..5ea445c672 100644 --- a/docs/user-guides/desktop/desktop-connect-sync.md +++ b/docs/user-guides/desktop/desktop-connect-sync.md @@ -19,7 +19,13 @@ You can also connect to the SSH server in your workspace using any SSH client, s ssh 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. +### Automatic port forwarding + +Any services listening on ports in your workspace are automatically available on the same hostname, with no manual port forwarding required. For example, you can access a web server on port `8080` by visiting `http://your-workspace.coder:8080` in your browser. + +This works for all TCP ports. Start a service in your workspace and access it immediately from your local machine at `http://your-workspace.coder:PORT`. + +For other port forwarding methods (CLI, dashboard, SSH), see [Workspace Ports](../workspace-access/port-forwarding.md). > [!NOTE] > For Coder versions v2.21.3 and earlier: the Coder IDE extensions for VSCode and JetBrains create their own tunnel and do not utilize the Coder Connect tunnel to connect to workspaces. diff --git a/docs/user-guides/desktop/index.md b/docs/user-guides/desktop/index.md index 12bd664f17..bbcb657df6 100644 --- a/docs/user-guides/desktop/index.md +++ b/docs/user-guides/desktop/index.md @@ -1,6 +1,9 @@ # Coder Desktop -Coder Desktop provides seamless access to your remote workspaces through a native application. Connect to workspace services using simple hostnames like `myworkspace.coder`, launch applications with one click, and synchronize files between local and remote environments—all without installing a CLI or configuring manual port forwarding. +Coder Desktop provides seamless access to your remote workspaces through a native application. Connect to workspace services using simple hostnames like `myworkspace.coder`, launch applications with one click, and synchronize files between local and remote environments, all without installing a CLI or configuring manual port forwarding. + +> [!TIP] +> Coder Desktop provides **automatic port forwarding** to every service running in your workspace. Any port your application listens on is instantly accessible at `workspace-name.coder:PORT` with no manual setup required. For a comparison of all port forwarding methods, see [Workspace Ports](../workspace-access/port-forwarding.md). ## What You'll Need @@ -21,6 +24,7 @@ Coder Desktop provides seamless access to your remote workspaces through a nativ **Coder Connect**, the primary component of Coder Desktop, creates a secure tunnel to your Coder deployment, allowing you to: - **Access workspaces directly**: Connect via `workspace-name.coder` hostnames +- **Automatic port forwarding**: All workspace ports are available at `workspace-name.coder:PORT` with no configuration - **Use any application**: SSH clients, browsers, IDEs work seamlessly - **Sync files**: Bidirectional sync between local and remote directories - **Work offline**: Edit files locally, sync when reconnected @@ -196,3 +200,4 @@ If you encounter issues not covered here: ## Next Steps - [Using Coder Connect and File Sync](./desktop-connect-sync.md) +- [Compare port forwarding methods](../workspace-access/port-forwarding.md) diff --git a/docs/user-guides/workspace-access/index.md b/docs/user-guides/workspace-access/index.md index 05dca3beea..da72459cbb 100644 --- a/docs/user-guides/workspace-access/index.md +++ b/docs/user-guides/workspace-access/index.md @@ -155,12 +155,25 @@ of tools for extending the capability of your workspace. If you have a request for a new IDE or tool, please file an issue in our [Modules repo](https://github.com/coder/registry/issues). +## Coder Desktop + +[Coder Desktop](../desktop/index.md) is a native application that provides seamless access to your workspaces via a VPN tunnel. With Coder Desktop, you get: + +- **Automatic port forwarding**: All workspace ports are available at `workspace-name.coder:PORT` with no manual setup +- **SSH access**: Connect with `ssh workspace-name.coder` using any SSH client +- **File sync**: Bidirectional file synchronization between local and remote directories + +Coder Desktop is the recommended way to access workspace services for developers who want a seamless, native experience. + ## Ports and Port forwarding -You can manage listening ports on your workspace page through with the listening +You can manage listening ports on your workspace page through the listening ports window in the dashboard. These ports are often used to run internal services or preview environments. +> [!TIP] +> For automatic access to all ports without manual configuration, use [Coder Desktop](../desktop/index.md). + You can also [share ports](./port-forwarding.md#sharing-ports) with other users, or [port-forward](./port-forwarding.md#the-coder-port-forward-command) through the CLI with `coder port forward`. Read more in the diff --git a/docs/user-guides/workspace-access/port-forwarding.md b/docs/user-guides/workspace-access/port-forwarding.md index 3bcfb1e2b5..26843bcb93 100644 --- a/docs/user-guides/workspace-access/port-forwarding.md +++ b/docs/user-guides/workspace-access/port-forwarding.md @@ -17,8 +17,12 @@ There are multiple ways to forward ports in Coder: ## Coder Desktop -[Coder Desktop](../desktop/index.md) provides seamless access to your remote workspaces, eliminating the need to install a CLI or manually configure port forwarding. -Access all your ports at `.coder:PORT`. +> [!TIP] +> Coder Desktop is the recommended way to access workspace ports. It provides automatic port forwarding with no manual setup. + +[Coder Desktop](../desktop/index.md) creates a VPN tunnel that automatically forwards every port in your workspace. Any service listening on a port is instantly accessible at `.coder:PORT` from your local machine, with no additional commands or configuration. + +This is the simplest option for most developers: install Coder Desktop, enable Coder Connect, and all ports just work. Connections are peer-to-peer for the best performance. ## The `coder port-forward` command