Skip to main content

Try free on Pangolin Cloud

Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
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. 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.
If you use Pangolin Cloud and want relayed traffic to stay on infrastructure you control, self-host a remote node. Relayed client traffic then traverses your node rather than Pangolin’s shared cloud infrastructure.

​
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): 
{
  "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, run pangolin status. The RELAY column shows whether each site is relayed (true) or directly connected (false): 
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 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 for the full list of Newt flags and environment variables.

​
FAQ

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.
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 for examples.
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.
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.
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 for details.
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 for details.
On self-hosted Pangolin, relayed traffic passes through your own Gerbil instance. On Pangolin Cloud, relayed traffic may traverse Pangolin’s shared infrastructure unless you self-host a remote node, in which case relayed client traffic uses your node instead.
Not always. Many networks hole punch successfully without inbound rules. If punching is unreliable, try firewall tweaks from Tailscale’s firewall guide or pin Newt to a static port with --port / PORT and DNAT that port to Newt on the site host.