AI Gateway is now available: identity-aware access to any AI provider, eliminate API keys, and tunnel to self-hosted models. Get started

Log inStart for free
DocumentationDownloadsWebsiteGitHubReleasesTrust Center
ClientsPlatforms

Mac

Install, configure, and update the Pangolin client for Mac

Install

  • Pangolin for macOS Installer - This is the official page to download the latest installer file for macOS.
  • All Versions - The releases section of this repository contains release notes and download artifacts for the latest version and all older versions.

Installation Steps

  1. Download and install the Pangolin client

    Download and install the Pangolin client using the official .dmg installer from the download button above.

    • Open the downloaded .dmg file
    • Drag and drop Pangolin.app into your Applications folder

  2. Launch Pangolin

    Open Pangolin from your Applications folder.

  3. Install the VPN configuration

    Follow the Pangolin onboarding flow, which will guide you to install the Pangolin VPN configuration.

    • Select Open System Settings on startup when it asks to install a network extension.
    • In System Settings, under General > Login Items & Extension > By Category > Network Extensions, ensure that Pangolin.app is toggled on.
    • Select Allow when Pangolin asks to add a VPN configuration.

  4. Log in with your Pangolin account

    Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.

    • Click the Pangolin icon in the menu bar and select Log in.

Configure

DNS, MTU, and other preferences shared across clients are on Platforms.

Start at Login

When enabled, Pangolin opens automatically when you log in to your Mac.

Connect Automatically On

Choose when Pangolin may connect automatically. Connect enables on-demand for that interface; Disconnect disables it.

Ethernet connects automatically while the Mac is on Ethernet.

Wi-Fi connects automatically while the Mac is on Wi-Fi. You can limit which networks that applies to:

  • Any Wi-Fi Network connects on every Wi-Fi network.
  • Only these Wi-Fi Networks connects only on the networks you list.
  • Except these Wi-Fi Networks connects on every network except the ones you list.

Config File

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

Configobject

JSON configuration for the Mac Pangolin client stored in pangolin.json.

Show ConfigHide Config
dnsOverrideEnabledboolean

When true, matches the Enable Aliases (Override DNS) preference and lets the client take over DNS resolution for Pangolin resources.

dnsTunnelEnabledboolean

When true, matches the DNS Over Tunnel preference and sends DNS queries through the Pangolin tunnel.

primaryDNSServerstring

Primary upstream DNS server used when override/tunnel DNS is enabled.

secondaryDNSServerstring

Optional secondary upstream DNS server used as a fallback when the primary is unavailable.

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

exitNodeTakesPrecedenceboolean

When true, matches the Exit Nodes Take Precedence Over Resources preference. While connected through an exit node, routes for other resources are not added and their aliases are not resolved, so all traffic flows through the exit node. If omitted, the default is false.

tunnelMTUinteger

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.

onDemandWiFiEnabledboolean

When true, matches the Wi-Fi option under Connect Automatically On and connects on demand whenever the Mac is on Wi-Fi. Use onDemandSSIDOption and onDemandSSIDs to limit this to specific networks. If omitted, the default is false.

onDemandNonWiFiEnabledboolean

When true, matches the Ethernet option under Connect Automatically On and connects on demand whenever the Mac is on Ethernet. If omitted, the default is false.

onDemandSSIDOptionstring

Which Wi-Fi networks on-demand applies to when onDemandWiFiEnabled is true. Supported values are any (Any Wi-Fi Network), only (Only these Wi-Fi Networks, the names in onDemandSSIDs), and except (Except these Wi-Fi Networks). If omitted, or if onDemandSSIDs is empty, the default is any.

onDemandSSIDsarray of strings

Wi-Fi network names (SSIDs) used by the only and except modes of onDemandSSIDOption.

autoUpdateChecksEnabledboolean

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.

autoDownloadUpdatesEnabledboolean

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.

updateCheckIntervalSecondsinteger

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

sessionCookieNamestring

Overrides the cookie name the session token is sent and read under. Most deployments should leave this unset.

Update

Automatic Updates

The Mac client periodically checks for updates in the background. When an update is available, it requests permission to update. You can also check for updates from the menu bar, or by restarting the application.

Once you accept the update, the client downloads the latest version and replaces itself.

Manual Updates

Find the latest version in the GitHub releases.

You can download the latest installer and run it again to install the latest version. Visit https://pangolin.net/downloads for the official installer.

Windows

Previous Page

iOS/iPadOS

Next Page

Was this page helpful?

⌘I

On this page

InstallInstallation StepsConfigureStart at LoginConnect Automatically OnConfig FileUpdateAutomatic UpdatesManual Updates