This feature is only available in self-hosted Pangolin instances.
A client in Pangolin is a way to create a traditional VPN tunnel from your remote computer to your Newt site on your private network. Clients allow you to tunnel your computer back into your whole network and remotely access non-HTTP resources like file shares or use it as a bastion host to manage servers.
Client support in Pangolin is still in beta - things may not perform as expected. If you encounter bugs please report them on GitHub in an issue.

​
How Clients Work

​
The Connection Process

  1. Client Creation: You create a client in Pangolin’s dashboard
  2. Olm Registration: Olm registers with Pangolin using the client credentials
  3. Tunnel Establishment: Olm establishes a WireGuard tunnel to your network
  4. Resource Access: You can access resources on your private network through the tunnel

​
What Clients Are

  • A way to tunnel your computer back into your whole network
  • Remotely access non HTTP resources like file shares
  • A bastion host or “jump box” to manage servers

​
What Pangolin Clients Are Not (Yet)

  • A mesh VPN like Tailscale, Netbird, or Netmaker
  • A slick desktop UI (coming soon)
You can install the Olm client on your computer and run it with the ID and secret values you generate in the dashboard. When it connects, it will create a virtual network adapter on your computer just like a traditional VPN. Take a look at a quick video about clients

​
Prerequisites

Before adding a client, ensure you have:
  1. Updated Components: Make sure you have the required versions:
    • Pangolin ^1.8.0
    • Gerbil ^1.1.0
    • Newt ^1.4.0
  2. Site Configuration: Your Newt site must be configured to accept clients with the --accept-clients flag or ACCEPT_CLIENTS=true environment variable.
  3. Port Configuration: Ensure port 21820 is open on your VPS and added to your docker-compose.yml:
docker-compose.yml
gerbil: 
  ports:
    - 51820:51820/udp
    - 21820:21820/udp
    - 443:443
    - 80:80

​
Adding a Client

1

Navigate to Clients

In the Pangolin dashboard, go to the Clients section and click Add Client.
2

Configure client details

Configure the basic information:
  • Client Name: A descriptive name for your client
3

Generate Olm credentials

Pangolin will generate:
  • Client ID: Unique identifier for the Olm client
  • Secret: Authentication secret for secure connection
  • Endpoint: The Pangolin server endpoint
4

Install Olm

Use the generated credentials to install and configure Olm on your remote computer. See Install Olm for detailed instructions.
5

Configure resources

Create RAW TCP/UDP resources for what you would like to access through the client. For example, to SSH into a server, create a resource like 22:localhost:22.
6

Verify connection

Once Olm is running, the client status should show as “Online” in the dashboard. You can then connect to your network using the site’s IP address.

​
Client Modalities

Clients have two major operation modalities:

​
Relaying (Default)

By default, Olm will relay traffic through your Pangolin VPS - 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 holepunching capabilities of Newt.

​
NAT Hole Punching (Experimental)

Right now NAT hole punching is EXPERIMENTAL. While functional, it does not always connect reliably and can fall back to relaying. We plan to work to improve the reliability over time by implementing more methods for those behind CGNAT or hard nats.Take a look at Tailscale docs for some firewall changes you might be able to make to improve HP performance.
This mode can be activated by using --holepunch in Olm. Instead of immediately relaying through the VPS, this will attempt to connect directly to the Newt site across NAT routers. This should help to:
  • Increase performance (speed/bandwidth)
  • Reduce VPS transit costs

​
Site Modalities

Sites have two operating modalities when accepting clients:

​
Proxy Mode

When you run Newt with --accept-clients it will run fully in user space. This means you do not need to give the container or binary any special permissions. It will NOT create a virtual network interface on the host. Instead you should create raw TCP/UDP resources in Pangolin to configure what ports clients can hit and where they should go. For example, if you wanted to SSH into your server you could add a resource for it:
SSH Resource

Pangolin UI showing example SSH resource.

​
Native Mode

Right now native mode only works on Linux.
In native mode with both --accept-clients and --native, Newt will create a native Linux tunnel interface on the host. This means that all traffic destined for the site can access anything on the host.

​
Remote Subnets

Additionally, you can add remote subnets to the site settings in Pangolin to forward remote networks through Newt. This can let Newt act as a traditional VPN server to route to anything on your local network.
Remote Subnets

Pangolin UI showing remote subnets for clients.

This may require Linux that you have forwarding enabled: 
sysctl -w net.ipv4.ip_forward=1
And make it persistent: 
sudo nano /etc/sysctl.conf

net.ipv4.ip_forward = 1

​
Notes

  • Clients require Olm to be running on the remote computer
  • Each client can access multiple resources on the site
  • Connection status is monitored automatically
  • Olm creates a native tun interface and usually requires sudo/admin permissions
  • On Windows: Olm will run as a service
  • LXC containers need to be configured to allow tun access