> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
> Use this file to discover all available pages before exploring further.

# NAT Traversal

> How clients connect directly to sites or relay through Pangolin, and how to improve reliability

<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
  <Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
    Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
  </Card>
</div>

When a client connects to a site, Pangolin tries to establish the most direct path possible. Clients have two major operation modalities: NAT hole punching and relaying. A client will first attempt to hole punch before falling back to relaying.

## NAT Hole Punching

NAT hole punching establishes a direct peer-to-peer connection between the client and site, bypassing the need to route traffic through the Pangolin server. The server coordinates the initial connection by helping both peers discover each other's network addresses, allowing them to establish a direct tunnel through their respective NATs and firewalls.

For a deeper look at how Pangolin coordinates hole punching between clients and sites, see [NAT Hole Punching in Pangolin](https://pangolin.net/news/nat-holepunching).

Direct connections typically offer:

* Better performance (speed and bandwidth)
* Lower VPS transit costs when you self-host

## Relaying

If the site and client are unable to hole punch, they fall back to relaying through your Pangolin server.

Clients can relay traffic through a Pangolin server—through Gerbil specifically. Gerbil listens on UDP port 21820 for new WireGuard connections and forwards the packets down the Newt site tunnels to the right peers. This means your connections back to your site do not require firewall config and uses the existing NAT hole punching capabilities of Newt.

Relaying is reliable when direct paths are blocked by NAT or firewall rules, but traffic passes through your Pangolin node instead of traveling directly between the client and site.

<Note>
  If you use [Pangolin Cloud](https://app.pangolin.net/auth/signup) and want relayed traffic to stay on infrastructure you control, [self-host a remote node](/manage/remote-node/understanding-nodes). Relayed client traffic then traverses your node rather than Pangolin's shared cloud infrastructure.
</Note>

## Check Whether a Site Is Relayed

You can confirm whether a connection is direct or relayed from the client.

### GUI clients

In a GUI client (Mac, Windows, Android, or iOS/iPadOS), open **Preferences**, go to the **Status** tab, and switch to the **JSON** view. Under each connected site in the `peers` object, check `isRelay`:

* `isRelay: false` — direct hole-punched connection to the site
* `isRelay: true` — traffic is relayed through your Pangolin server

Example (values obfuscated):

```json theme={"theme":"gruvbox-light-hard"}
{
  "agent": "Pangolin macOS",
  "connected": true,
  "orgId": "org_example123",
  "peers": {
    "1001": {
      "connected": true,
      "endpoint": "203.0.113.10:51820",
      "isRelay": false,
      "name": "Office Network",
      "siteId": 1001
    },
    "1002": {
      "connected": true,
      "endpoint": "198.51.100.5:21820",
      "isRelay": true,
      "name": "Remote Lab",
      "siteId": 1002
    }
  },
  "registered": true,
  "version": "0.8.4"
}
```

In this example, **Office Network** is connected directly (`isRelay: false`) and **Remote Lab** is relayed (`isRelay: true`).

### CLI

On Linux or when using [Pangolin CLI](/manage/clients/install-client), run `pangolin status`. The **RELAY** column shows whether each site is relayed (`true`) or directly connected (`false`):

```bash theme={"theme":"gruvbox-light-hard"}
pangolin status
AGENT         VERSION  STATUS     ORG
Pangolin CLI  0.10.1   Connected  org_example123

SITE            ENDPOINT               STATUS     LAST SEEN  RELAY
Office Network  203.0.113.10:51820     Connected  1s ago     false
Remote Lab      198.51.100.5:21820     Connected  1s ago     true
```

Use either view when troubleshooting hole punching or verifying that configuration changes took effect.

## Improve Hole Punching Reliability

Newt supports NAT traversal to allow clients to connect directly to Newt sites without relaying through the Pangolin server, improving performance and reducing latency.

In some environments, depending on the NAT type and firewall, you may need to tweak settings to get optimal connectivity in the firewall itself. Take a look at [these docs](https://tailscale.com/kb/1361/firewall) for some firewall changes you might be able to make.

Another option is to keep Newt listening for client connections on a static port. This allows you to open a specific port in your firewall for Newt client connections instead of random high ports. You can do this by setting the `--port` flag or `PORT` environment variable and then opening this port in your firewall to DNAT to Newt. See [Configure Sites](/manage/sites/configure-site) for the full list of Newt flags and environment variables.

## FAQ

<AccordionGroup>
  <Accordion title="Why is my connection relayed instead of direct?">
    Hole punching can fail when either side sits behind a restrictive NAT, symmetric NAT, or a firewall that blocks the UDP ports needed for peer discovery. When that happens, the client and site fall back to relaying through your Pangolin server so the tunnel still comes up reliably.
  </Accordion>

  <Accordion title="How do I check whether a site is relayed?">
    **GUI clients:** Open **Preferences**, go to the **Status** tab, and switch to the **JSON** view. Each entry under `peers` includes an `isRelay` field—`false` for direct, `true` when relayed.

    **CLI:** Run `pangolin status` and check the **RELAY** column for each site.

    See [Check Whether a Site Is Relayed](#check-whether-a-site-is-relayed) for examples.
  </Accordion>

  <Accordion title="Is relayed traffic still encrypted?">
    Yes. Whether the path is direct or relayed, client-to-site traffic is encrypted over WireGuard. Relaying changes the network path, not the encryption of the tunnel itself.
  </Accordion>

  <Accordion title="Will relaying affect performance?">
    Direct hole-punched connections usually offer lower latency and higher throughput because traffic does not pass through your Pangolin node. Relayed connections add an extra hop through Gerbil, which can increase latency and bandwidth use on the node—especially relevant if you self-host and pay for transit.
  </Accordion>

  <Accordion title="Can I force direct connections only?">
    You can disable relaying with `disable-relay` in the client config or `--disable-relay` / `DISABLE_RELAY=true` on CLI clients. If hole punching fails, the client will not fall back to a relay and the site may not connect. See [Configure Clients](/manage/clients/configure-client) for details.
  </Accordion>

  <Accordion title="Can I always relay and skip hole punching?">
    Yes. Set `disable-holepunch` in the client config or use `--disable-holepunch` / `DISABLE_HOLEPUNCH=true` on CLI clients to skip hole punching and connect through the relay path. See [Configure Clients](/manage/clients/configure-client) for details.
  </Accordion>

  <Accordion title="Does relayed traffic go through Pangolin Cloud?">
    On self-hosted Pangolin, relayed traffic passes through your own Gerbil instance. On [Pangolin Cloud](https://app.pangolin.net/auth/signup), relayed traffic may traverse Pangolin's shared infrastructure unless you [self-host a remote node](/manage/remote-node/understanding-nodes), in which case relayed client traffic uses your node instead.
  </Accordion>

  <Accordion title="Do I need to open firewall ports for hole punching?">
    Not always. Many networks hole punch successfully without inbound rules. If punching is unreliable, try firewall tweaks from [Tailscale's firewall guide](https://tailscale.com/kb/1361/firewall) or pin Newt to a static port with `--port` / `PORT` and DNAT that port to Newt on the site host.
  </Accordion>
</AccordionGroup>