---
title: "Add Client"
description: "Create a client to connect to your Pangolin network from a remote computer"
---

<Note>
This feature is only available in self-hosted Pangolin instances.
</Note>

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.

<Note>
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](https://github.com/fosrl/pangolin).
</Note>

## 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](https://github.com/fosrl/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](https://youtu.be/jg8Bb05hlnI)

## 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`:

```yml title="docker-compose.yml" highlight={4}
gerbil: 
  ports:
    - 51820:51820/udp
    - 21820:21820/udp
    - 443:443
    - 80:80
```

## Adding a Client

<Steps>
<Step title="Navigate to Clients">
  In the Pangolin dashboard, go to the **Clients** section and click **Add Client**.
</Step>

<Step title="Configure client details">
  Configure the basic information:
  - **Client Name**: A descriptive name for your client
</Step>

<Step title="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
</Step>

<Step title="Install Olm">
  Use the generated credentials to install and configure Olm on your remote computer. See [Install Olm](/manage/clients/install-olm) for detailed instructions.
</Step>

<Step title="Configure resources">
  Create [client resources](../resources/site-resources.mdx) for what you would like to access through the client. For example, to SSH into a server, create a resource like `22:localhost:22`.
</Step>

<Step title="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.
</Step>
</Steps>

## 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)

<Note>
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](https://tailscale.com/kb/1361/firewall) for some firewall changes you might be able to make to improve HP performance.
</Note>

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 [client resources](../resources/client-resources.mdx) in Pangolin to configure what ports clients can hit and where they should go.

### Native Mode

<Note>
Right now native mode only works on Linux.
</Note>

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

In native mode, 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.

<Frame caption="Pangolin UI showing remote subnets for clients.">
  <img src="/images/remote_subnets.png" alt="Remote Subnets"/>
</Frame>

This will configure a route on the Olm side of the tunnel to route this subnet down the tunnel. When it reaches the other end, can be routed to the appropriate destination by the host.

This may require Linux that you have forwarding enabled:

```bash
sudo nano /etc/sysctl.conf

net.ipv4.ip_forward = 1
```

...and [setup NAT](https://www.geeksforgeeks.org/linux-unix/using-masquerading-with-iptables-for-network-address-translation-nat/) or other routing so that destination networks can route back to the Olm client. Remember the source address of the packets will be the IP address of the Olm client in this situation and the destination will be an IP on the remote subnet network.

## 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
