Coder's network topology has three types of nodes: workspaces, Coder servers,

and users.

The pages in this section outline Coder's networking stack and how aspects

connect to or interact with each other.

This page is a high-level reference of Coder's network topology, requirements,

and connection types.


Coder's network topology has three general types of nodes or ways of interacting

with Coder:

- Coder servers

- Workspaces

- Users

The Coder server must have an inbound address reachable by users and workspaces,

but otherwise, all topologies_just work_ with Coder.

When NAT traversal fails, connections are relayed through the Coder server. All

user-workspace connections are end-to-end encrypted.

[Tailscale's open source](https://tailscale.com) backs our websocket/HTTPS

networking logic.

[Tailscale](https://tailscale.com)'s implementation of

[Wireguard](https://www.wireguard.com/) backs our websocket/HTTPSnetworking logic.

In order for clients and workspaces to be able to connect:

Coder’s networking is designed to support a wide range of infrastructure targets.

Because of that, there are very few requirements for running Coder in your network:

- The central server (coderd) needs port 443 to be open for HTTPS and websocket traffic

- Workspaces, clients (developer laptops), and provisioners only need to reach the Coder server and establish a websocket connection. No ports need to be open.

In order for clients and workspaces to be able to connect:

- All clients and agents must be able to establish a connection to the Coder

server (`CODER_ACCESS_URL`) over HTTP/HTTPS.

- Any reverse proxy or ingress between the Coder control plane and

clients/agents must support WebSockets.

In order for clients to be able to establish direct connections:

- The client is connecting using the CLI (e.g.`coder ssh` or

`coder port-forward`). Note that the

[VSCode extension](https://marketplace.visualstudio.com/items?itemName=coder.coder-remote)

and[JetBrains Plugin](https://plugins.jetbrains.com/plugin/19620-coder/), and

[`ssh coder.<workspace>`](../../reference/cli/config-ssh.md) all utilize the

CLI to establish a workspace connection.

- Either the client or workspace agent are able to discover a reachable

`ip:port` of their counterpart. If the agent and client are able to

communicate with each other using their locally assigned IP addresses, then a

direct connection can be established immediately. Otherwise, the client and

agent will contact

[the configured STUN servers](../../reference/cli/server.md#--derp-server-stun-addresses)

to try and determine which`ip:port` can be used to communicate with their

counterpart. See[STUN and NAT](./stun.md) for more details on how this

process works.

- All outbound UDP traffic must be allowed for both the client and the agent on

**all ports** to each others' respective networks.

- To establish a direct connection, both agent and client use STUN. This

involves sending UDP packets outbound on`udp/3478` to the configured

[STUN server](../../reference/cli/server.md#--derp-server-stun-addresses).

If either the agent or the client are unable to send and receive UDP packets

to a STUN server, then direct connections will not be possible.

- Both agents and clients will then establish a

[WireGuard](https://www.wireguard.com/)️ tunnel and send UDP traffic on

ephemeral (high) ports. If a firewall between the client and the agent

blocks this UDP traffic, direct connections will not be possible.

Workspaces connect to the Coder server via the server's external address, set

via[`ACCESS_URL`](../../admin/setup/index.md#access-url). There must not be a

NAT between workspaces andcoder server.

NAT between workspaces andthe Coder server.

Users connect to the Coder server's dashboard and API through its`ACCESS_URL`

as well. There must not be a NAT between users and the Coder server.

By default, Coder will attempt to create direct peer-to-peer connections between

the client (developer laptop) and workspace.

If this doesn’t work, the end result will be transparent to the end user because

Coder will fall back to connections relayed to the control plane.

Direct connections are a straight line between the user and workspace, so there

is no special geo-distribution configuration. To speed up direct connections,

move the user and workspace closer together.

Direct connections reduce latency and improve upload and download speeds for developers.

However, there are many scenarios where direct connections cannot be established,

such as when the Coder[administrators disable direct connections](../../reference/cli/server.md#--block-direct-connections).

Consult the[direct connections section](./troubleshooting.md#common-problems-with-direct-connections)

of the troubleshooting guide for more information.

The troubleshooting guide also explains how to identify if a connection is direct

or not via the`coder ping` command.

Ideally, to speed up direct connections, move the user and workspace closer together.

Establishing a direct connection can be an involved process because both the

client and workspace agent will likely be behind at least one level of NAT,

but this can be disabled or changed for

[offline deployments](../../install/offline.md).

In order for clients to be able to establish direct connections:

- The client is connecting using the CLI (e.g.`coder ssh` or

`coder port-forward`). Note that the

[VSCode extension](https://marketplace.visualstudio.com/items?itemName=coder.coder-remote)

and[JetBrains Plugin](https://plugins.jetbrains.com/plugin/19620-coder/), and

[`ssh coder.<workspace>`](../../reference/cli/config-ssh.md) all utilize the

CLI to establish a workspace connection.

- Either the client or workspace agent are able to discover a reachable

`ip:port` of their counterpart. If the agent and client are able to

communicate with each other using their locally assigned IP addresses, then a

direct connection can be established immediately. Otherwise, the client and

agent will contact

[the configured STUN servers](../../reference/cli/server.md#--derp-server-stun-addresses)

to try and determine which`ip:port` can be used to communicate with their

counterpart. See[STUN and NAT](./stun.md) for more details on how this

process works.

- All outbound UDP traffic must be allowed for both the client and the agent on

**all ports** to each others' respective networks.

- To establish a direct connection, both agent and client use STUN. This

involves sending UDP packets outbound on`udp/3478` to the configured

[STUN server](../../reference/cli/server.md#--derp-server-stun-addresses).

If either the agent or the client are unable to send and receive UDP packets

to a STUN server, then direct connections will not be possible.

- Both agents and clients will then establish a

[WireGuard](https://www.wireguard.com/)️ tunnel and send UDP traffic on

ephemeral (high) ports. If a firewall between the client and the agent

blocks this UDP traffic, direct connections will not be possible.

By default, your Coder server also runs a built-in DERP relay which can be used