Skip to main content

​
GUI Clients (Mac, Windows, Android, iOS/iPadOS)

Each respective client has a preferences window with all currently available configuration parameters. In your desktop client, click the menu bar or system tray icon, select “More” in the menu, and click “Preferences”. In the mobile apps, navigate to the “Settings” screen.

​
Preferences

The following preferences control how your client handles DNS resolution and network routing. Understanding these settings helps you configure Pangolin to work best with your network setup.

​
Enable Aliases (Override DNS)

When enabled, the client uses custom DNS servers to resolve internal resources and aliases. This overrides your system’s default DNS settings. Queries that cannot be resolved as a Pangolin resource will be forwarded to your configured Upstream DNS Server. When to use it: This is required if you use aliases on resources in Pangolin. Aliases are friendly domain names assigned to private resources. Pangolin resolves these alias addresses over a private DNS server running in your client. How it works: The client loops back to itself to resolve the alias. This is why you may see your DNS server as an unfamiliar address (often like 100.90.128.x) when this is enabled. When a request doesn’t resolve to a Pangolin resource and is bound for another website (like google.com), it falls back to your configured upstream DNS server.

​
DNS Over Tunnel

When enabled, DNS queries are routed through the tunnel for remote resolution. To ensure queries are tunneled correctly, you must define the DNS server as a Pangolin resource and enter its address as an Upstream DNS Server. When to use it: Tunnel DNS is used when you want to send all DNS queries over the tunnel to a private resource made available in Pangolin. For example, if you host a DNS server like Pi-hole, you could define a private resource for Pi-hole on your remote network. Then in the Pangolin client, you would enable Tunnel DNS and set the host of the Pi-hole private resource as the tunnel DNS server. How it works: When a request needs to be resolved, Pangolin sends it over the tunnel to the site of the private resource with your DNS server. You must enable DNS Over Tunnel and also set the upstream DNS server to your private DNS server. This requires aliases “override DNS” to be enabled as well. This is because the client must take control of your DNS settings to route queries through the tunnel to your private DNS server.
You cannot use an alias name for your DNS server. It must be the IP address of the resource. This is because it’s pointing to the DNS server, so the DNS server can’t resolve itself.

​
Primary Upstream DNS

This is the DNS server that will be used if Override DNS is enabled or DNS Over Tunnel is enabled. It serves as the primary resolver for queries that cannot be resolved as Pangolin resources. Not used when override DNS (aliases) are disabled.

​
Secondary Upstream DNS

This is a fallback DNS server that the system can use if the primary server is unavailable. Ordering and priority of the server is not guaranteed, but it provides redundancy for DNS resolution. Not used when override DNS (aliases) are disabled.

​
Windows Client (Advanced)

On Windows, you can centrally preconfigure the Pangolin GUI client by editing the JSON config at %LOCALAPPDATA%\Pangolin\pangolin.json before the user signs in (for example, C:\Users\USER\AppData\Local\Pangolin\pangolin.json). This is useful for system administrators who want to enforce consistent DNS behavior and login flows across many machines without relying on end users to choose the right options. In particular, defaultServerURL and authPath let you direct users straight to the correct server and, if needed, a specific organization-branded login page on every launch.
​
Config
object
JSON configuration for the Windows Pangolin client stored in pangolin.json.
As a system administrator, you can script placing this file into %LOCALAPPDATA%\Pangolin\pangolin.json to preconfigure user installations and automate rollouts.
For enterprise customers, contact us if you need a custom MSI installer with baked-in configuration; we can maintain custom installers as an add-on to your enterprise license.

​
Windows client log level

To configure the log level for the Windows client system-wide, edit %ProgramData%\Pangolin\pangolin.json. For example: 
{ "logLevel": "debug" }
The default log level is info.

​
Android Battery Optimization

To ensure Pangolin functions correctly in the background on Android devices, it’s recommended to disable battery optimization for the app. This prevents the operating system from restricting its background activities, which could lead to disconnections.
  1. Open the Settings app on your Android device.
  2. Navigate to Apps & notifications (or simply Apps on some devices).
  3. Find and select the Pangolin app from the list of installed apps.
  4. Tap on App battery usage.
  5. Select Allow background usage and enable if disabled.
  6. From the options menu, choose Unrestricted.
Android Battery Optimization Settings

​
Pangolin CLI

Refer to the documentation in the official repository for the available commands, default values, and more.

​
Olm (Advanced)

We recommend using the Pangolin CLI for both user and machine clients if you’re looking for a CLI interface. Olm is the underlying client for the Pangolin CLI.
Olm is a command-line client for connecting machine clients in Pangolin. You can configure it using command-line flags, environment variables, or a configuration file. Expand the section below to view all available configuration options.

​
Flags

​
id
string
required
Olm ID generated by Pangolin to identify the client.Example: 31frd0uzbjvp721
​
secret
string
required
A unique secret used to authenticate the client ID with the websocket.Example: h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
Keep this secret private and secure. It’s used for authentication.
​
endpoint
string
required
The endpoint where both Gerbil and Pangolin reside for websocket connections.Example: https://pangolin.example.com
​
org
string
Organization ID to connect to.
​
user-token
string
User authentication token.
​
mtu
integer
MTU for the internal WireGuard interface.Default: 1280
​
dns
string
DNS server to use to resolve the endpoint.Default: 8.8.8.8
​
upstream-dns
string
Upstream DNS server(s), comma-separated.Default: 8.8.8.8:53
​
log-level
string
The log level to use for Olm output.Options: DEBUG, INFO, WARN, ERROR, FATALDefault: INFO
​
ping-interval
string
Interval for pinging the server.Default: 3s
​
ping-timeout
string
Timeout for each ping.Default: 5s
​
interface
string
Name of the WireGuard interface.Default: olm
​
enable-api
boolean
Enable API server for receiving connection requests.Default: false
​
http-addr
string
HTTP server address (e.g., ‘:9452’).Default: :9452
​
socket-path
string
Unix socket path (or named pipe on Windows).Default: /var/run/olm.sock (Linux/macOS) or olm (Windows)
​
disable-holepunch
boolean
Disable hole punching.Default: false
​
override-dns
boolean
When enabled, the client uses custom DNS servers to resolve internal resources and aliases. This overrides your system’s default DNS settings. Queries that cannot be resolved as a Pangolin resource will be forwarded to your configured Upstream DNS Server. (default true)Default: false
​
tunnel-dns
boolean
When enabled, DNS queries are routed through the tunnel for remote resolution. To ensure queries are tunneled correctly, you must define the DNS server as a Pangolin resource and enter its address as an Upstream DNS Server.Default: false
​
disable-relay
boolean
Disable relay connections.Default: false

​
Environment Variables

All CLI arguments can be set using environment variables as an alternative to command line flags. Environment variables are particularly useful when running Olm in containerized environments.
When both environment variables and CLI arguments are provided, CLI arguments take precedence.
​
PANGOLIN_ENDPOINT
string
Endpoint of your Pangolin server (equivalent to --endpoint)
​
OLM_ID
string
Olm ID generated by Pangolin (equivalent to --id)
​
OLM_SECRET
string
Olm secret for authentication (equivalent to --secret)
​
ORG
string
Organization ID to connect to (equivalent to --org)
​
USER_TOKEN
string
User authentication token (equivalent to --user-token)
​
MTU
integer
MTU for the internal WireGuard interface (equivalent to --mtu)Default: 1280
​
DNS
string
DNS server to use to resolve the endpoint (equivalent to --dns)Default: 8.8.8.8
​
UPSTREAM_DNS
string
Upstream DNS server(s), comma-separated (equivalent to --upstream-dns)Default: 8.8.8.8:53
​
LOG_LEVEL
string
Log level (equivalent to --log-level)Default: INFO
​
PING_INTERVAL
string
Interval for pinging the server (equivalent to --ping-interval)Default: 3s
​
PING_TIMEOUT
string
Timeout for each ping (equivalent to --ping-timeout)Default: 5s
​
INTERFACE
string
Name of the WireGuard interface (equivalent to --interface)Default: olm
​
ENABLE_API
boolean
Enable API server for receiving connection requests (equivalent to --enable-api)Set to “true” to enableDefault: false
​
HTTP_ADDR
string
HTTP server address (equivalent to --http-addr)Default: :9452
​
SOCKET_PATH
string
Unix socket path or Windows named pipe (equivalent to --socket-path)Default: /var/run/olm.sock (Linux/macOS) or olm (Windows)
​
DISABLE_HOLEPUNCH
boolean
Disable hole punching (equivalent to --disable-holepunch)Set to “true” to disableDefault: false
​
OVERRIDE_DNS
boolean
Override system DNS settings (equivalent to --override-dns)Set to “true” to enableDefault: false
​
DISABLE_RELAY
boolean
Disable relay connections (equivalent to --disable-relay)Set to “true” to disableDefault: false
​
CONFIG_FILE
string
Set to the location of a JSON file to load secret values

​
Loading secrets from files

You can use CONFIG_FILE to define a location of a config file to store the credentials between runs.
$ cat ~/.config/olm-client/config.json
{
  "id": "spmzu8rbpzj1qq6",
  "secret": "f6v61mjutwme2kkydbw3fjo227zl60a2tsf5psw9r25hgae3",
  "endpoint": "https://app.pangolin.net",
  "org": "",
  "userToken": "",
  "mtu": 1280,
  "dns": "8.8.8.8",
  "upstreamDNS": ["8.8.8.8:53"],
  "interface": "olm",
  "logLevel": "INFO",
  "enableApi": false,
  "httpAddr": "",
  "socketPath": "/var/run/olm.sock",
  "pingInterval": "3s",
  "pingTimeout": "5s",
  "disableHolepunch": false,
  "overrideDNS": false,
  "disableRelay": false,
  "tlsClientCert": ""
}
This file is also written to when olm first starts up. So you do not need to run every time with —id and secret if you have run it once!Default locations:
  • macOS: ~/Library/Application Support/olm-client/config.json
  • Windows: %PROGRAMDATA%\olm\olm-client\config.json
  • Linux/Others: ~/.config/olm-client/config.json

​
API

Olm can be started with a HTTP or socket API to configure and manage it. See the API documentation for more details.