Files
coder/docs/admin/networking/stun.md
T
Nick Vigilante 5e41baf73c docs: normalize control plane, coderd, and coder server terminology (#28960)
Normalizes the three overlapping names for the thing that serves the
Coder API and dashboard. This is step 1 of the Install/Deploy and
Administration refactor
([DOCS-685](https://linear.app/codercom/issue/DOCS-685),
[DOCS-738](https://linear.app/codercom/issue/DOCS-738)) and lands first
because every later page depends on settled terminology.

Resolves [DOCS-871](https://linear.app/codercom/issue/DOCS-871).

## The rule

| Term | Means | Use when |
|---|---|---|
| control plane | The component that serves the Coder API and dashboard,
brokers connections, and coordinates provisioners | Default in prose,
diagrams, planning, sizing, security |
| `coderd` | The process that implements it | Architecture internals,
metrics, logs, flags, troubleshooting |
| `coder server` | The literal CLI command | Only when the reader will
type it |

Retired: "the Coder server" as a name for the component, and "a service"
as a standalone description of it.

## What changed

- **`docs/.style/style-guide/word-choice.md`**: new "Naming Coder's
components" rule, with do/don't examples. Also fixes a "Do" example on
that page that itself used "the Coder server".
- **`docs/reference/glossary.md`**: rewrote `coderd` and Control plane,
added a `coder server` entry. The existing Control plane entry defined
it as "the collective term for `coderd`, its provisioners, and its
database", which made it indistinguishable from the Deployment entry two
sections later. Control plane is now the component; Deployment remains
the whole installation.
- **65 pages** across `docs/admin`, `docs/install`, `docs/get-started`,
`docs/tutorials`, `docs/user-guides`, `docs/ai-coder`, and `docs/about`:
roughly 154 component-sense "Coder server" usages, 21 bare "the server"
usages meaning the control plane, 3 "a service" descriptions, and 43
unbackticked `coderd` mentions in prose.
- One real bug caught in passing:
`docs/tutorials/best-practices/security-best-practices.md` documented
`coderd server --disable-path-apps`, which is not a command. Now `coder
server`.

Generated files were not touched: `configuration-reference.md`,
`prometheus.md`, `audit-logs.md`, `reference/cli/*`, `reference/api/*`,
and the generated blocks inside `feature-stages.md`. Those still contain
the retired term and need generator-side changes; see the deferred list
below.

## Reviewer attention, please

**Anchor changes.** 11 headings were renamed, so their fragments change.
No in-repo link targets any of them (the one internal link that did was
updated), but external deep links from tickets or blog posts would
break, and fragments cannot be fixed with a redirect. Happy to revert
any of these if you would rather they ride along with the page moves in
[DOCS-869](https://linear.app/codercom/issue/DOCS-869), which changes
those URLs anyway.

<details>
<summary>Renamed headings and their old fragments</summary>

| File | Old fragment | New heading |
|---|---|---|
| `admin/networking/index.md` | `#coder-server` | `## Control plane` |
| `install/index.md` | `#starting-the-coder-server` | `## Starting the
control plane` |
| `install/uninstall.md` | `#the-coder-server-binary-and-cli` | `## The
Coder binary and CLI` |
| `install/registry-mirror-artifactory.md` |
`#step-5-configure-coder-server-or-provisioners` | `## Step 5: Configure
the control plane or provisioners` |
| `install/cloud/compute-engine.md` | `#configuring-coder-server` | `##
Configuring the control plane` |
| `get-started/index.md` |
`#cant-start-coder-server-address-already-in-use` | ``### Can't start
`coder server`: Address already in use`` |
| `tutorials/external-database.md` |
`#coder-server-fails-startup-with-...` | ``### `coder server` fails
startup with ...`` |
| `tutorials/faqs.md` |
`#how-do-i-change-the-access-url-for-my-coder-server` | `## How do I
change the access URL for my control plane?` |
| `tutorials/best-practices/security-best-practices.md` |
`#coder-server` | `## Control plane` |
| `tutorials/best-practices/security-best-practices.md` |
`#server-logs-and-audit-logs` | `### Control plane logs and audit logs`
|
| `tutorials/best-practices/scale-coder.md` | `#coder-server`,
`#how-to-capture-coder-server-metrics-with-prometheus` | `## Control
plane`, `### How to capture control plane metrics with Prometheus` |

</details>

**One deliberate deviation from the issue.** DOCS-871 proposed reserving
"sub-agent" for the Coder Agents sense and using "devcontainer agent"
for the workspace sense. I did not make that change. The glossary
already disambiguates with "Sub-agent (Coder Agents)" and "Sub-agent
(dev containers)", and "devcontainer agent" would violate the existing
dev container spelling rule in the same style guide, which requires "dev
container" as two lowercase words. The current split reads correctly and
costs no churn. Happy to revisit if you disagree.

<details>
<summary>Deferred, with reasons</summary>

- **Generated content still says "Coder server".** `reference/cli/*`
comes from Go command help text, `configuration-reference.md` from
`configdocgen`, and `reference/api/*` from Swagger annotations. Fixing
those means changing Go source, which belongs in its own PR so a docs
review does not turn into a backend review.
- **`validated-architectures/index.md` "also known as `coderd`"** is
fixed here, but the page's larger problem is that it holds four
documents in one file. That split is
[DOCS-868](https://linear.app/codercom/issue/DOCS-868).
- **"server flag" phrasing** in `admin/users/idp-sync.md` and
`admin/users/oidc-auth/index.md` means `coder server` flags. Left alone;
rewording those sentences is a copy edit, not a substitution.
- **Metric and UI labels** such as "Dashboard-to-server latency" in
`admin/networking/index.md`. Renaming risks diverging from what the
dashboard shows.
- **Pre-existing `Coder.GerundHeading` warnings** on headings this PR
touches, and a "from from" typo in `scale-coder.md`. Out of scope for a
terminology pass.
- **Peer-sense "server"** in NAT traversal prose, where "client or
server" describes the connection roles rather than the control plane.
Needs restructuring, not substitution.

</details>

## Verification

| Check | Result |
|---|---|
| `make lint/emdash` | pass |
| `make lint/markdown` | pass, 504 files, 0 errors |
| `make lint/docs-html` | pass |
| `make lint/prose` | pass, findings identical to the `main` baseline (1
intentional demo error, 145 warnings, 1 suggestion; only Vale's file
ordering and one line-number shift in `glossary.md` differ) |
| `make gen` | clean, no drift |
| `make fmt/markdown` | applied |

No redirects needed: no page moved or was renamed in this PR.

<details>
<summary>Merged main, 2026-09-14</summary>

One conflict, in `docs/ai-coder/ai-gateway/providers.md`. Both hunks
were text this PR had edited and `main` had since deleted in #29053,
which removed env-based AI provider configuration:

- The deprecated provider seeding note, which held a `coderd` backtick
fix, is gone. Took `main`.
- The failure-mode table lost its env-drift row. Took `main`'s two rows
and reapplied the `coderd` logs wording.

`main` also landed new prose carrying the retired terms, so the pass was
extended to cover it:

- `docs/admin/integrations/oauth2-provider.md`: two "the server log(s)"
in the scope-enforcement sections added by #29144 are now "the `coderd`
log(s)"; "a `scope` the server will not grant" is now "the control
plane".
- `docs/reference/cli/index.md` gained "the server" from #29104, and
stays deferred as generated content.

The new `docs/ai-coder/agent-relay/claude-code.md` needed no change, and
no page `main` added links to a heading this PR renamed.

</details>

<details>
<summary>Decision log for the wider refactor</summary>

Agreed with @nickvigilante before implementation, recorded on DOCS-685
and in the Notion outline:

1. Feature stages and release channels move to Reference; ESR upgrade
guides move under Operate. No new top-level Releases section.
2. `data-retention.md` moves to Administration > Security;
`chat-lifecycle-hooks.md` moves into the Coder Agents docs.
`admin/setup/` therefore survives as "Deployment configuration" and
`configdocgen` is not touched.
3. Prepare is advisory, not a gate, framed as "don't know where to
start? Start here", with lead times and owners per item.
4. One actor table, on the Install overview, spanning all five phases,
noting that one person can be several actors and several people can be
one actor.
5. The quickstart stays independent and is mentioned once, on the
Install overview. The proposed `server/single-machine` page is dropped.
6. Coder Validated Architecture keeps its name in nav, defined in-page,
with a glossary entry.
7. PR 3 is split: moves only, then prose, so the riskiest change reads
as a pure rename diff.
8. For every PR that moves a page, the coder.com `redirects.json` change
merges first.
9. There is no Download section and no CLI page in docs. Per-OS CLI
steps live on coder.com/download and the Install overview links to it.

</details>

Generated with Coder Agents on behalf of @nickvigilante.
2026-09-22 15:18:40 -04:00

8.7 KiB

title
title
STUN and NAT

Session Traversal Utilities for NAT (STUN) is a protocol used to assist applications in establishing peer-to-peer communications across Network Address Translations (NATs) or firewalls.

Network Address Translation (NAT) is commonly used in private networks to allow multiple devices to share a single public IP address. The vast majority of home and corporate internet connections use at least one level of NAT.

Overview

In order for one application to connect to another across a network, the connecting application needs to know the IP address and port under which the target application is reachable. If both applications reside on the same network, then they can most likely connect directly to each other. In the context of a Coder workspace agent and client, this is generally not the case, as both agent and client will most likely be running in different private networks (e.g. 192.168.1.0/24). In this case, at least one of the two will need to know an IP address and port under which they can reach their counterpart.

This problem is often referred to as NAT traversal, and Coder uses a standard protocol named STUN to address this.

Inside of that network, packets from the agent or client will show up as having source address 192.168.1.X:12345. However, outside of this private network, the source address will show up differently (for example, 12.3.4.56:54321). In order for the Coder client and agent to establish a direct connection with each other, one of them needs to know the ip:port pair under which their counterpart can be reached. Once communication succeeds in one direction, we can inspect the source address of the received packet to determine the return address.

Tip

The below glosses over a lot of the complexity of traversing NATs. For a more in-depth technical explanation, see How NAT traversal works (tailscale.com).

At a high level, STUN works like this:

  • Discovery: Both the client and agent will send UDP traffic to one or more configured STUN servers. These STUN servers are generally located on the public internet, and respond with the public IP address and port from which the request came.
  • Coordination: The client and agent then exchange this information through the control plane. They will then construct packets that should be able to successfully traverse their counterpart's NATs successfully.
  • NAT Traversal: The client and agent then send these crafted packets to their counterpart's public addresses. If all goes well, the NATs on the other end should route these packets to the correct internal address.
  • Connection: Once the packets reach the other side, they send a response back to the source ip:port from the packet. Again, the NATs should recognize these responses as belonging to an ongoing communication, and forward them accordingly.

At this point, both the client and agent should be able to send traffic directly to each other.

Examples

1. Direct connections without NAT or STUN

In this example, both the client and agent are located on the network 192.168.21.0/24. Assuming no firewalls are blocking packets in either direction, both client and agent are able to communicate directly with each other's locally assigned IP address.

Diagram of a workspace agent and client in the same network

2. Direct connections with one layer of NAT

In this example, client and agent are located on different networks and connect to each other over the public Internet. Both client and agent connect to a configured STUN server located on the public Internet to determine the public IP address and port on which they can be reached.

Diagram of a workspace agent and client in separate networks

They then exchange this information through the control plane, and can then communicate directly with each other through their respective NATs.

Diagram of a workspace agent and client in separate networks

3. Direct connections with VPN and NAT hairpinning

In this example, the client workstation must use a VPN to connect to the corporate network. All traffic from the client will enter through the VPN entry node and exit at the VPN exit node inside the corporate network. Traffic from the client inside the corporate network will appear to be coming from the IP address of the VPN exit node 172.16.1.2. Traffic from the client to the public internet will appear to have the public IP address of the corporate router 12.34.56.7.

The workspace agent is running on a Kubernetes cluster inside the corporate network, which is behind its own layer of NAT. To anyone inside the corporate network but outside the cluster network, its traffic will appear to be coming from 172.16.1.254. However, traffic from the agent to services on the public Internet will also see traffic originating from the public IP address assigned to the corporate router. Additionally, the corporate router will most likely have a firewall configured to block traffic from the internet to the corporate network.

If the client and agent both use the public STUN server, the addresses discovered by STUN will both be the public IP address of the corporate router. To correctly route the traffic backwards, the corporate router must correctly route both:

  • Traffic sent from the client to the external IP of the corporate router back to the cluster router, and
  • Traffic sent from the agent to the external IP of the corporate router to the VPN exit node.

This behaviour is known as "hairpinning", and may not be supported in all network configurations.

If hairpinning is not supported, deploying an internal STUN server can aid establishing direct connections between client and agent. When the agent and client query this internal STUN server, they will be able to determine the addresses on the corporate network from which their traffic appears to originate. Using these internal addresses is much more likely to result in a successful direct connection.

Diagram of a workspace agent and client over VPN

Hard NAT

Some NATs are known to use a different port when forwarding requests to the STUN server and when forwarding probe packets to peers. In that case, the address a peer discovers over the STUN protocol will have the correct IP address, but the wrong port. Tailscale refers to this as "hard" NAT in How NAT traversal works (tailscale.com).

If both peers are behind a "hard" NAT, direct connections may take longer to establish or will not be established at all. If one peer is behind a "hard" NAT and the other is running a firewall (including Windows Defender Firewall), the firewall may block direct connections.

In both cases, peers fallback to DERP connections if they cannot establish a direct connection.

If your workspaces are behind a "hard" NAT, you can:

  1. Ensure clients are not also behind a "hard" NAT. You may have limited ability to control this if end users connect from their homes.
  2. Ensure firewalls on client devices (e.g. Windows Defender Firewall) have an inbound policy allowing all UDP ports either to the coder or coder.exe CLI binary, or from the IP addresses of your workspace NATs.
  3. Reconfigure your workspace network's NAT connection to the public internet to be an "easy" NAT. See below for specific examples.

AWS NAT Gateway

The AWS NAT Gateway is a known "hard" NAT. You can use a NAT Instance instead of a NAT Gateway, and configure it to use the same port assignment for all UDP traffic from a particular source IP:port combination (Tailscale calls this "easy" NAT). Linux MASQUERADE rules work well for this.

AWS Elastic Kubernetes Service (EKS)

The default configuration of AWS Elastic Kubernetes Service (EKS) includes the Amazon VPC CNI Driver, which by default randomizes the public port for different outgoing UDP connections. This makes it act as a "hard" NAT, even if the EKS nodes are on a public subnet (and thus do not need to use the AWS NAT Gateway to reach the Internet).

This behavior can be disabled by setting the environment variable AWS_VPC_K8S_CNI_RANDOMIZESNAT=none in the aws-node DaemonSet. Note, however, if your nodes are on a private subnet, they will still need NAT to reach the public Internet, meaning that issues with the AWS NAT Gateway might affect you.