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

# Configure Clients

> Configure Olm for connecting to Pangolin clients

<div />

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

To troubleshoot connection or configuration issues, see [Client Logs](/manage/clients/client-logs) for how to view logs on each platform.

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

<Warning>
  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.
</Warning>

#### Primary Upstream DNS

This is the DNS server used to resolve queries that are not bound to a Pangolin alias when Override DNS or DNS Over Tunnel is enabled.

When left blank, **System DNS** is used. This pulls the existing configured system DNS settings and applies them to the tunnel. If Tunnel DNS is enabled and System DNS is used, requests will likely fail if the DNS server is not accessible over the tunnel.

#### Secondary Upstream DNS

This is a fallback DNS server used to resolve queries that are not bound to a Pangolin alias when the primary server is unavailable. Ordering and priority of the server is not guaranteed, but it provides redundancy for DNS resolution. When left blank, **System DNS** is used, same as Primary Upstream DNS.

#### Match Domains

By default, when match domains are not set, all DNS queries are sent to the configured upstream DNS server. Match domains let you whitelist which domains should be sent to the upstream DNS server. When match domains are set, only matching queries go to upstream DNS; all other requests use the system's DNS servers.

**When to use it**: When you have a private or corporate DNS server for specific domains (for example, `*.proxy.internal` or `corp.example.com`) and want everything else resolved by the system DNS as usual.

**How it works**: With no match domains configured, every query is forwarded to your Upstream DNS Server. With match domains set, only queries that match the list are forwarded upstream; the rest use the system's default DNS servers.

#### MTU

You can set the maximum transmission unit (MTU) for the client’s internal WireGuard interface. This value is client-wide: every site the client connects to must use the same MTU on the site (Newt) side, or you can see fragmentation, failed handshakes, or unstable tunnels. See the **mtu** option on [Configure Sites](/manage/sites/configure-site) and set the same value on each of those sites.

<Warning>
  Changing MTU is advanced and not recommended for most users. Only change it when you have a specific, well-understood reason (for example, a constrained network path or a requirement from your infrastructure team). If you do change it, you must update every connected site to the identical value.
</Warning>

## Windows Client (Advanced)

On Windows, the Pangolin GUI reads configuration from two `pangolin.json` files:

* User config: `%LOCALAPPDATA%\Pangolin\pangolin.json` (for example, `C:\Users\USER\AppData\Local\Pangolin\pangolin.json`)
* Global config: `%ProgramData%\Pangolin\pangolin.json`

Most keys in the `Config` object below can be set in either file. If the same key exists in both places, the user config value overrides the global value. This lets administrators define global defaults while still allowing per-user overrides when needed. Keys marked **Global only** must be set in `%ProgramData%\Pangolin\pangolin.json`; restart the Pangolin manager/UI after changing them.

<ResponseField name="Config" type="object">
  JSON configuration for the Windows Pangolin client stored in `pangolin.json`.

  <Expandable title="Config">
    <ResponseField name="dnsOverride" type="boolean">
      When true, matches the **Enable Aliases (Override DNS)** preference and lets the client take over DNS resolution for Pangolin resources.
    </ResponseField>

    <ResponseField name="dnsTunnel" type="boolean">
      When true, matches the **DNS Over Tunnel** preference and sends DNS queries through the Pangolin tunnel.
    </ResponseField>

    <ResponseField name="primaryDNS" type="string">
      Primary upstream DNS server used when override/tunnel DNS is enabled.
    </ResponseField>

    <ResponseField name="secondaryDNS" type="string">
      Optional secondary upstream DNS server used as a fallback when the primary is unavailable.
    </ResponseField>

    <ResponseField name="dnsMatchDomains" type="array of strings">
      Optional whitelist of domains sent to the configured upstream DNS server. When unset, all queries go to upstream DNS. When set, only matching queries use your Upstream DNS Server; all other requests use the system's DNS servers. Supports wildcards such as `*.proxy.internal`.
    </ResponseField>

    <ResponseField name="defaultServerURL" type="string">
      When set, skips the deployment option screen during login; all login flows start directly with this server URL.
    </ResponseField>

    <ResponseField name="authPath" type="string">
      Optional path appended to the server URL for authentication, for example `/auth/org/my-org` to always send users to a specific organization or branded login page. Most deployments should leave this unset.
    </ResponseField>

    <ResponseField name="userSettingsDisabled" type="boolean">
      When true, hides and disables the settings form in the GUI so users cannot change these values themselves.
    </ResponseField>

    <ResponseField name="openStatusTabOnConnect" type="boolean">
      When true, opens the Status tab immediately after clicking Connect so users can watch connection feedback while the tunnel is starting.
    </ResponseField>

    <ResponseField name="mtu" type="integer">
      MTU for the internal WireGuard interface. Changing this is advanced and not recommended unless you have a clear reason; if you set a non-default value, configure the same MTU on every site this client connects to—see [Configure Sites](/manage/sites/configure-site).
    </ResponseField>

    <ResponseField name="preferLocalRoutes" type="boolean">
      When true, prioritizes local routes over remote ones by adding an arbitrary metric to the WireGuard routes. This is useful when you want to ensure that local network traffic (for example, to a printer or NAS) is not routed through the Pangolin tunnel.
    </ResponseField>

    <ResponseField name="autoUpdateChecksEnabled" type="boolean">
      **Global only.** When true, periodically check for updates in the background. When false, automatic checks are off; users can still use **Check for Updates** unless that button is also disabled. If omitted, the default is `true`. Enabling checks surfaces the update UI when a new version exists (tray “Pangolin Update Available” and the update prompt). Intended for org admins / MDM so config is the source of truth.
    </ResponseField>

    <ResponseField name="updateCheckIntervalSeconds" type="integer">
      **Global only.** How often automatic checks run, in seconds. Values below `3600` (1 hour) are clamped to `3600`. Only matters when `autoUpdateChecksEnabled` is true. If omitted, the default is `86400` (24 hours). The client applies a small amount of jitter around this interval.
    </ResponseField>

    <ResponseField name="checkForUpdatesButtonEnabled" type="boolean">
      **Global only.** When true, show **Check for Updates** in the system tray More menu. When false, hide that menu item. If omitted, the default is `true`. Manual checks always perform a live network lookup when the button is used. This is independent of `autoUpdateChecksEnabled`.
    </ResponseField>

    <ResponseField name="logLevel" type="string">
      **Global only.** Controls client log verbosity. Supported values include `debug` and `info`. If omitted, the default is `info`.
    </ResponseField>
  </Expandable>
</ResponseField>

As a system administrator, you can script placing `pangolin.json` in `%ProgramData%\Pangolin\` to set global defaults, and/or in each user's `%LOCALAPPDATA%\Pangolin\` folder for per-user overrides and targeted rollout behavior.

<Tip>
  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.
</Tip>

## Mac Client (Advanced)

On Mac, the Pangolin GUI reads configuration from `~/Library/Application Support/Pangolin/pangolin.json`. Restart Pangolin after editing for changes to apply.

<ResponseField name="Config" type="object">
  JSON configuration for the Mac Pangolin client stored in `pangolin.json`.

  <Expandable title="Config">
    <ResponseField name="dnsOverrideEnabled" type="boolean">
      When true, matches the **Enable Aliases (Override DNS)** preference and lets the client take over DNS resolution for Pangolin resources.
    </ResponseField>

    <ResponseField name="dnsTunnelEnabled" type="boolean">
      When true, matches the **DNS Over Tunnel** preference and sends DNS queries through the Pangolin tunnel.
    </ResponseField>

    <ResponseField name="primaryDNSServer" type="string">
      Primary upstream DNS server used when override/tunnel DNS is enabled.
    </ResponseField>

    <ResponseField name="secondaryDNSServer" type="string">
      Optional secondary upstream DNS server used as a fallback when the primary is unavailable.
    </ResponseField>

    <ResponseField name="dnsMatchDomains" type="array of strings">
      Optional whitelist of domains sent to the configured upstream DNS server. When unset, all queries go to upstream DNS. When set, only matching queries use your Upstream DNS Server; all other requests use the system's DNS servers. Supports wildcards such as `*.proxy.internal`.
    </ResponseField>

    <ResponseField name="tunnelMTU" type="integer">
      MTU for the internal WireGuard interface. Changing this is advanced and not recommended unless you have a clear reason; if you set a non-default value, configure the same MTU on every site this client connects to. See [Configure Sites](/manage/sites/configure-site).
    </ResponseField>

    <ResponseField name="autoUpdateChecksEnabled" type="boolean">
      When true, periodically check for updates in the background. When false, automatic checks are off; users can still use **Check for Updates**. If omitted, the client default applies (may prompt the user on second launch). Enabling checks without `autoDownloadUpdatesEnabled` still surfaces the update UI when a new version exists. Intended for admin / MDM provisioning so config stays the source of truth over user toggles.
    </ResponseField>

    <ResponseField name="autoDownloadUpdatesEnabled" type="boolean">
      When true, download updates silently when found and stage install for quit/relaunch. When false, show the normal update dialog instead of silent download. Silent download does not replace the running app mid-session; the update installs on quit (and relaunches), so long-running menu bar sessions may keep a staged update until quit. If omitted, the default is `false`.
    </ResponseField>

    <ResponseField name="updateCheckIntervalSeconds" type="integer">
      How often automatic checks run, in seconds. Values below `3600` (1 hour) are clamped to `3600`. Only matters when `autoUpdateChecksEnabled` is true. If omitted, the default is `86400` (24 hours).
    </ResponseField>
  </Expandable>
</ResponseField>

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

<Frame caption="Android Battery Optimization Settings">
  <img src="https://mintcdn.com/fossorial/VqiOoRUR8g1Tf03J/images/android_battery.png?fit=max&auto=format&n=VqiOoRUR8g1Tf03J&q=85&s=100cadbbfa77478600a84cc858f222a0" alt="Android Battery Optimization Settings" style={{width: "250px", height: "auto"}} width="1080" height="2424" data-path="images/android_battery.png" />
</Frame>

## Pangolin CLI

Refer to the [documentation in the official repository](https://github.com/fosrl/cli/blob/main/docs/pangolin.md) for the available commands, default values, and more.

## Olm (Advanced, Deprecated)

<Accordion title="Olm CLI (advanced use only)">
  <Tip>
    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.
  </Tip>

  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.

  <Accordion title="CLI Arguments and Options">
    ### Flags

    <ResponseField name="id" type="string" required>
      Olm ID generated by Pangolin to identify the client.

      **Example**: `31frd0uzbjvp721`
    </ResponseField>

    <ResponseField name="secret" type="string" required>
      A unique secret used to authenticate the client ID with the websocket.

      **Example**: `h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6`

      <Warning>
        Keep this secret private and secure. It's used for authentication.
      </Warning>
    </ResponseField>

    <ResponseField name="endpoint" type="string" required>
      The endpoint where the Pangolin server resides for websocket connections.

      **Example**: `https://pangolin.example.com`
    </ResponseField>

    <ResponseField name="org" type="string">
      Organization ID to connect to.
    </ResponseField>

    <ResponseField name="user-token" type="string">
      User authentication token.
    </ResponseField>

    <ResponseField name="mtu" type="integer">
      MTU for the internal WireGuard interface.

      **Default**: `1280`
    </ResponseField>

    <ResponseField name="dns" type="string">
      DNS server to use to resolve the endpoint.

      **Default**: `8.8.8.8`
    </ResponseField>

    <ResponseField name="upstream-dns" type="string">
      Upstream DNS server(s), comma-separated.

      **Default**: `8.8.8.8:53`
    </ResponseField>

    <ResponseField name="match-domains-dns" type="string">
      FQDN wildcard patterns (using `*` and `?` wildcards, comma-separated, e.g. `*.proxy.internal,*.host-0?.autoco.internal`) to check against local records/upstream DNS. Queries for domains that don't match any pattern are sent directly to the host's own system DNS servers instead of being resolved as Pangolin resources.

      **Default**: (empty, matches every domain)
    </ResponseField>

    <ResponseField name="log-level" type="string">
      The log level to use for Olm output.

      **Options**: `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`

      **Default**: `INFO`
    </ResponseField>

    <ResponseField name="ping-interval" type="string">
      Interval for pinging the server.

      **Default**: `3s`
    </ResponseField>

    <ResponseField name="ping-timeout" type="string">
      Timeout for each ping.

      **Default**: `5s`
    </ResponseField>

    <ResponseField name="interface" type="string">
      Name of the WireGuard interface.

      **Default**: `olm`
    </ResponseField>

    <ResponseField name="enable-api" type="boolean">
      Enable API server for receiving connection requests.

      **Default**: `false`
    </ResponseField>

    <ResponseField name="http-addr" type="string">
      HTTP server address (e.g., ':9452'). When unset, the HTTP API is not started and the socket API (see `socket-path`) is used instead.

      **Default**: (not set)
    </ResponseField>

    <ResponseField name="socket-path" type="string">
      Unix socket path (or named pipe on Windows).

      **Default**: `/var/run/olm.sock` (Linux/macOS) or `olm` (Windows)
    </ResponseField>

    <ResponseField name="disable-holepunch" type="boolean">
      Disable hole punching.

      **Default**: `false`
    </ResponseField>

    <ResponseField name="override-dns" type="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`
    </ResponseField>

    <ResponseField name="tunnel-dns" type="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`
    </ResponseField>

    <ResponseField name="match-domains-dns" type="string">
      Optional comma-separated whitelist of domains sent to the configured upstream DNS server. When unset, all queries go to upstream DNS. When set, only matching queries use your Upstream DNS Server; all other requests use the system's DNS servers. Supports wildcards such as `*.proxy.internal`.
    </ResponseField>

    <ResponseField name="disable-relay" type="boolean">
      Disable relay connections.

      **Default**: `false`
    </ResponseField>

    <ResponseField name="prefer-local-routes" type="boolean">
      When true, prioritizes local routes over remote ones by adding an arbitrary metric to the WireGuard routes. This is useful when you want to ensure that local network traffic (for example, to a printer or NAS) is not routed through the Pangolin tunnel.

      **Default**: `false`
    </ResponseField>

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

    <Note>
      When both environment variables and CLI arguments are provided, CLI arguments take precedence.
    </Note>

    <ResponseField name="PANGOLIN_ENDPOINT" type="string">
      Endpoint of your Pangolin server (equivalent to `--endpoint`)
    </ResponseField>

    <ResponseField name="OLM_ID" type="string">
      Olm ID generated by Pangolin (equivalent to `--id`)
    </ResponseField>

    <ResponseField name="OLM_SECRET" type="string">
      Olm secret for authentication (equivalent to `--secret`)
    </ResponseField>

    <ResponseField name="ORG" type="string">
      Organization ID to connect to (equivalent to `--org`)
    </ResponseField>

    <ResponseField name="USER_TOKEN" type="string">
      User authentication token (equivalent to `--user-token`)
    </ResponseField>

    <ResponseField name="MTU" type="integer">
      MTU for the internal WireGuard interface (equivalent to `--mtu`)

      **Default**: `1280`
    </ResponseField>

    <ResponseField name="DNS" type="string">
      DNS server to use to resolve the endpoint (equivalent to `--dns`)

      **Default**: `8.8.8.8`
    </ResponseField>

    <ResponseField name="UPSTREAM_DNS" type="string">
      Upstream DNS server(s), comma-separated (equivalent to `--upstream-dns`)

      **Default**: `8.8.8.8:53`
    </ResponseField>

    <ResponseField name="MATCH_DOMAINS_DNS" type="string">
      FQDN wildcard patterns, comma-separated (equivalent to `--match-domains-dns`)

      **Default**: (empty, matches every domain)
    </ResponseField>

    <ResponseField name="LOG_LEVEL" type="string">
      Log level (equivalent to `--log-level`)

      **Default**: `INFO`
    </ResponseField>

    <ResponseField name="PING_INTERVAL" type="string">
      Interval for pinging the server (equivalent to `--ping-interval`)

      **Default**: `3s`
    </ResponseField>

    <ResponseField name="PING_TIMEOUT" type="string">
      Timeout for each ping (equivalent to `--ping-timeout`)

      **Default**: `5s`
    </ResponseField>

    <ResponseField name="INTERFACE" type="string">
      Name of the WireGuard interface (equivalent to `--interface`)

      **Default**: `olm`
    </ResponseField>

    <ResponseField name="ENABLE_API" type="boolean">
      Enable API server for receiving connection requests (equivalent to `--enable-api`)

      Set to "true" to enable

      **Default**: `false`
    </ResponseField>

    <ResponseField name="HTTP_ADDR" type="string">
      HTTP server address (equivalent to `--http-addr`)

      **Default**: (not set)
    </ResponseField>

    <ResponseField name="SOCKET_PATH" type="string">
      Unix socket path or Windows named pipe (equivalent to `--socket-path`)

      **Default**: `/var/run/olm.sock` (Linux/macOS) or `olm` (Windows)
    </ResponseField>

    <ResponseField name="DISABLE_HOLEPUNCH" type="boolean">
      Disable hole punching (equivalent to `--disable-holepunch`)

      Set to "true" to disable

      **Default**: `false`
    </ResponseField>

    <ResponseField name="OVERRIDE_DNS" type="boolean">
      Override system DNS settings (equivalent to `--override-dns`)

      Set to "true" to enable

      **Default**: `true`
    </ResponseField>

    <ResponseField name="TUNNEL_DNS" type="boolean">
      Route DNS queries through the tunnel (equivalent to `--tunnel-dns`)

      Set to "true" to enable

      **Default**: `false`
    </ResponseField>

    <ResponseField name="MATCH_DOMAINS_DNS" type="string">
      Optional whitelist of domains sent to the configured upstream DNS server (equivalent to `--match_domains_dns`). When unset, all queries go to upstream DNS.
    </ResponseField>

    <ResponseField name="PREFER_LOCAL_ROUTES" type="boolean">
      When true, prioritizes local routes over remote ones by adding an arbitrary metric to the WireGuard routes. This is useful when you want to ensure that local network traffic (for example, to a printer or NAS) is not routed through the Pangolin tunnel.

      **Default**: `false`
    </ResponseField>

    <ResponseField name="DISABLE_RELAY" type="boolean">
      Disable relay connections (equivalent to `--disable-relay`)

      Set to "true" to disable

      **Default**: `false`
    </ResponseField>

    <ResponseField name="CONFIG_FILE" type="string">
      Set to the location of a JSON file to load secret values
    </ResponseField>

    ### 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"],
      "matchDomainsDNS": [],
      "interface": "olm",
      "logLevel": "INFO",
      "enableApi": false,
      "httpAddr": "",
      "socketPath": "/var/run/olm.sock",
      "pingInterval": "3s",
      "pingTimeout": "5s",
      "disableHolepunch": false,
      "overrideDNS": true,
      "tunnelDNS": false,
      "disableRelay": false,
      "tlsClientCert": "",
      "preferLocalRoutes": false
    }
    ```

    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](https://github.com/fosrl/olm/blob/main/API.md) for more details.
  </Accordion>
</Accordion>