# Port forwarding

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 four ways to forward ports in Coder:

| Method                                 | Details                                                                                                                                                                                  |
| :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Coder Desktop](#coder-desktop)        | Automatic port forwarding via virtual private network (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 Transmission Control Protocol (TCP) or User Datagram Protocol (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.                                                                                                                                                   |

Coder Desktop and `coder port-forward` are generally more performant than:

1. The Dashboard, which proxies traffic through the Coder control plane instead of peer-to-peer like the Coder CLI and Coder Desktop
2. `sshd` which does double encryption of traffic with both Wireguard and SSH

## Coder Desktop

[Coder Desktop](/docs/@main/workspaces/desktop/) 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 `<workspace-name>.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](/docs/@main/workspaces/desktop/) for installation and setup.

## The `coder port-forward` command

This command can be used to forward TCP or UDP ports from the remote workspace so they can be accessed locally.
Both the TCP and UDP command line flags (`--tcp` and `--udp`) can be given once or multiple times.

The supported syntax variations for the `--tcp` and `--udp` flag are:

* Single port with optional remote port: `local_port[:remote_port]`
* Comma separation `local_port1,local_port2`
* Port ranges `start_port-end_port`
* Any combination of the above

### Examples

Forward the remote TCP port `8080` to local port `8000`:

```console
coder port-forward myworkspace --tcp 8000:8080
```

Forward the remote TCP port `3000` and all ports from `9990` to `9999` to their respective local ports.

```console
coder port-forward myworkspace --tcp 3000,9990-9999
```

Forward the remote TCP port `3000` and all ports from `9990` to `9999` to their respective local ports to the `agent` in your Workspace (typically main or dev).
This is needed when you have multiple agents in your workspace.

```console
coder port-forward myworkspace.agent --tcp 3000,9990-9999
```

For more examples, see `coder port-forward --help`.

## Dashboard

To enable port forwarding via the dashboard, Coder must be configured with a [wildcard access URL](/docs/@main/admin/setup/#wildcard-access-url).
If an access URL is not specified, Coder will create [a publicly accessible URL](/docs/@main/admin/setup/#tunnel) to reverse proxy the deployment, and port forwarding will work.

There is a [DNS limitation](https://datatracker.ietf.org/doc/html/rfc1035#section-2.3.1) where each segment of hostnames must not exceed 63 characters.
If your app name, agent name, workspace name and username exceed 63 characters in the hostname, port forwarding via the dashboard will not work.

### From a coder\_app resource

One way to port forward is to configure a `coder_app` resource in the workspace's template.
This approach shows a visual application icon in the dashboard.
See the following `coder_app` example for a Node React app and note the `subdomain` and `share` settings:

```tf
# node app
resource "coder_app" "node-react-app" {
  agent_id  = coder_agent.dev.id
  slug      = "node-react-app"
  icon      = "https://upload.wikimedia.org/wikipedia/commons/a/a7/React-icon.svg"
  url       = "http://localhost:3000"
  subdomain = true
  share     = "authenticated"

  healthcheck {
    url       = "http://localhost:3000/healthz"
    interval  = 10
    threshold = 30
  }

}
```

Valid `share` values include `owner` - private to the user, `authenticated` - accessible by any user authenticated to the Coder deployment, and `public` - accessible by users outside of the Coder deployment.

![Port forwarding from an app in the UI](/docs/@main/images/networking/portforwarddashboard.png)

<a id="accessing-workspace-ports"></a>

## Access workspace ports

Another way to port forward in the dashboard is to use the "Open Ports" button to specify an arbitrary port.
Coder will also detect if apps inside the workspace are listening on ports, and list them below the port input (this is only supported on Windows and Linux workspace agents).

![Port forwarding in the UI](/docs/@main/images/networking/listeningports.png)

<a id="sharing-ports"></a>

### Share ports

We allow developers to share ports as URLs, either with other authenticated coder users or publicly.
Using the open ports interface, developers can assign a sharing level to a port.

* `owner` (Default): The implicit sharing level for all listening ports, only visible to the workspace owner
* `organization`: Accessible by authenticated users in the same organization as the workspace.
* `authenticated`: Accessible by other authenticated Coder users on the same deployment.
* `public`: Accessible by any user with the associated URL.

Once a port is shared at either `authenticated` or `public` levels, it will stay pinned in the open ports UI for better accessibility regardless of whether or not it is still accessible.

![Annotated port controls in the UI](/docs/@main/images/networking/annotatedports.png)

The sharing level is limited by the maximum level enforced in the template settings in premium deployments, and not restricted in open source software (OSS) deployments.

This can also be used to change the sharing level of `coder_app`s by entering their port number in the sharable ports UI.
The `share` attribute on `coder_app` resource uses a different method of authentication and **is not impacted by the template's maximum sharing level**, nor the level of a shared port that points to the app.

### Configure maximum port sharing level

<Callout type="info" title="Note">
  Configuring port sharing level is a Premium feature.
  [Learn more](https://coder.com/pricing#compare-plans).
</Callout>

Premium-licensed template admins can control the maximum port sharing level for workspaces under a given template in the template settings.
By default, the maximum sharing level is set to `Owner`, meaning port sharing is disabled for end-users.
OSS deployments allow all workspaces to share ports at all levels, including `organization`.

![Max port sharing level in the UI](/docs/@main/images/networking/portsharingmax.png)

<a id="configuring-port-protocol"></a>

### Configure port protocol

Both listening and shared ports can be configured to use either `HTTP` or `HTTPS` to connect to the port.
For listening ports the protocol selector applies to any port you input or select from the menu.
Shared ports have protocol configuration for each shared port individually.

You can access any port on the workspace and can configure the port protocol manually by appending a `s` to the port in the URL.

```txt
# Uses HTTP
https://33295--agent--workspace--user--apps.example.com/
# Uses HTTPS
https://33295s--agent--workspace--user--apps.example.com/
```

### Cross-origin resource sharing (CORS)

When forwarding via the dashboard, Coder automatically sets headers that allow requests between separately forwarded applications belonging to the same user.

When forwarding through other methods the application itself will need to set its own cross-origin resource sharing (CORS) headers if they are being forwarded through different origins since Coder does not intercept these cases.
See below for the required headers.

#### Authentication

Since ports forwarded through the dashboard are private, cross-origin requests must include credentials (set `credentials: "include"` if using `fetch`) or the requests cannot be authenticated and you will see an error resembling the following:

```txt
Access to fetch at
'<https://coder.example.com/api/v2/applications/auth-redirect>' from origin
'<https://8000--dev--user--apps.coder.example.com>' has been blocked by CORS
policy: No 'Access-Control-Allow-Origin' header is present on the requested
resource. If an opaque response serves your needs, set the request's mode to
'no-cors' to fetch the resource with CORS disabled.
```

#### Headers

Below is a list of the cross-origin headers Coder sets with example values:

```txt
access-control-allow-credentials: true
access-control-allow-methods: PUT
access-control-allow-headers: X-Custom-Header
access-control-allow-origin: https://8000--dev--user--apps.coder.example.com
vary: Origin
vary: Access-Control-Request-Method
vary: Access-Control-Request-Headers
```

The allowed origin will be set to the origin provided by the browser if the users are identical.
Credentials are allowed and the allowed methods and headers will echo whatever the request sends.

#### Configuration

Template admins set the **CORS Behavior** in the template's **Settings** page.
The setting applies to every app and port in the template's workspaces.
It has two values:

* `Simple` (recommended): Coder applies its built-in CORS handling, as described in this section.
  If an application sets any of the headers above, Coder strips them from the response, except for `Vary` headers that are set to a value other than the ones listed above.
* `Passthru`: Coder bypasses its built-in CORS protection and passes the application's own CORS headers through to the browser.

Passthru reduces protection against cross-origin requests, so only use it for applications that handle CORS correctly.
For more about managing template settings, refer to [Managing templates](/docs/@main/templates/managing-templates/).

#### Allowed by default

<table class="tg">
<caption>
Which requests between forwarded apps the dashboard allows by default.
Columns are the origin: the user, workspace, and app that sends the request.
Rows are the destination: the user, workspace, and app that receives it.
</caption>
<thead>
  <tr>
    <th class="tg-0pky" scope="row" colspan="3">From user</th>
    <th class="tg-0pky" scope="col" colspan="3">Alice</th>
    <th class="tg-0pky" scope="col">Bob</th>
  </tr>
  <tr>
    <th class="tg-0pky" scope="row" colspan="3">From workspace</th>
    <th class="tg-0pky" scope="col">Workspace 1</th>
    <th class="tg-0pky" scope="col" colspan="2">Workspace 2</th>
    <th class="tg-0pky" scope="col">Workspace 3</th>
  </tr>
  <tr>
    <th class="tg-0pky" scope="col">To user</th>
    <th class="tg-0pky" scope="col">To workspace</th>
    <th class="tg-0pky" scope="col">To app</th>
    <th class="tg-0pky" scope="col">App A</th>
    <th class="tg-0pky" scope="col">App B</th>
    <th class="tg-0pky" scope="col">App C</th>
    <th class="tg-0pky" scope="col">App D</th>
  </tr>
</thead>
<tbody>
  <tr>
    <th class="tg-0pky" scope="row" rowspan="3">Alice</th>
    <th class="tg-0pky" scope="row" rowspan="2">Workspace 1</th>
    <th class="tg-0pky" scope="row">App A</th>
    <td class="tg-0pky">✅</td>
    <td class="tg-0pky">✅<span style="font-weight:400;font-style:normal">*</span></td>
    <td class="tg-0pky">✅<span style="font-weight:400;font-style:normal">*</span></td>
    <td class="tg-0pky">❌</td>
  </tr>
  <tr>
    <th class="tg-0pky" scope="row">App B</th>
    <td class="tg-0pky">✅*</td>
    <td class="tg-0pky">✅</td>
    <td class="tg-0pky">✅<span style="font-weight:400;font-style:normal">*</span></td>
    <td class="tg-0pky">❌</td>
  </tr>
  <tr>
    <th class="tg-0pky" scope="row">Workspace 2</th>
    <th class="tg-0pky" scope="row">App C</th>
    <td class="tg-0pky">✅<span style="font-weight:400;font-style:normal">*</span></td>
    <td class="tg-0pky">✅<span style="font-weight:400;font-style:normal">*</span></td>
    <td class="tg-0pky">✅</td>
    <td class="tg-0pky">❌</td>
  </tr>
  <tr>
    <th class="tg-0pky" scope="row">Bob</th>
    <th class="tg-0pky" scope="row">Workspace 3</th>
    <th class="tg-0pky" scope="row">App D</th>
    <td class="tg-0pky">❌</td>
    <td class="tg-0pky">❌</td>
    <td class="tg-0pky">❌</td>
    <td class="tg-0pky">✅</td>
  </tr>
</tbody>
</table>

> '\*' means `credentials: "include"` is required

## SSH

First, [configure SSH](/docs/@main/workspaces/workspace-access/#configure-ssh) on your local machine.
Then, use `ssh` to forward like so:

```console
ssh -L 8080:localhost:8000 coder.myworkspace
```

You can read more on SSH port forwarding [here](https://www.ssh.com/academy/ssh/tunneling/example).
