Skip to main content

​
Windows

  • Pangolin for Windows Installer - This is the official page to download the latest installer file for Windows.
  • 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 .msi installer from the download button above.
  2. Launch Pangolin Open Pangolin from the Start menu or the shortcut on your Desktop.
  3. 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 task bar’s system tray and select Log in.

​
Mac

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

​
iOS/iPadOS

​
Installation Steps

  1. Download and install the Pangolin app Download and install the Pangolin app from the App Store using the link above.
  2. Launch Pangolin Open the Pangolin app from your home screen.
  3. Install the VPN configuration When prompted, allow Pangolin to add VPN configurations to your device. You may be asked to enter your device passcode or use Face ID/Touch ID to authorize the VPN configuration.
  4. Log in with your Pangolin account Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.
  5. Connect to Pangolin Tap the Connect button to establish a VPN connection.

​
Android

  • Pangolin on Google Play - This is the official page to download the latest Pangolin app for Android devices.
  • 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 app Download and install the Pangolin app from the Google Play Store using the link above.
  2. Launch Pangolin Open the Pangolin app from your app drawer or home screen.
  3. Log in with your Pangolin account Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.
  4. Connect to Pangolin Tap the Connect button to establish a VPN connection. On the first connection, you may be prompted to allow the VPN connection.

​
Pangolin CLI (Linux, macOS, Windows)

Pangolin CLI is the recommended way to run a client using a command line interface on Mac and Linux. Pangolin CLI can run on Windows, but the CLI VPN functionality is not supported. You can still use Pangolin CLI on Windows for SSH alongside the Windows GUI client. Pangolin CLI supports running as user device with authentication or a machine client. Use this command to automatically install Pangolin CLI. It detects your system architecture automatically and always pulls the latest version, adding pangolin to your PATH: 
curl -fsSL https://static.pangolin.net/get-cli.sh | bash

​
Windows

Go to GitHub releases and download the latest MSI installer or EXE for Windows.

​
Manual Download

Binaries for all platforms are available in the GitHub releases for ARM and AMD64 (x86_64) architectures. Download and install manually: 
wget -O pangolin "https://github.com/fosrl/cli/releases/download/{version}/pangolin-cli_{architecture}" && chmod +x ./pangolin
Replace {version} with the desired version and {architecture} with your architecture. Check the release notes for the latest information.

​
Installation Steps

  1. Download and install the Pangolin client Install Pangolin using the installation script: 
    curl -fsSL https://static.pangolin.net/get-cli.sh | bash
  2. Log in with your Pangolin account Log in on your Pangolin Cloud account or your self-hosted Pangolin instance: 
    pangolin login
  3. Start Pangolin When logged in as a Pangolin user, connect by running: 
    pangolin up
    To launch a machine client without logging in, use your client credentials: 
    pangolin up --id {client_id} --secret {client_secret} --endpoint {endpoint_url} --attach
    The --attach flag runs the client in the foreground instead of spawning it as a background process.
Pangolin CLI can be installed as a systemd service or run in a container. See the sections below for advanced setups.

​
Systemd Service (Pangolin CLI)

Create a basic systemd service for Pangolin CLI:
/etc/systemd/system/pangolin-cli.service
[Unit]
Description=Pangolin CLI
After=network.target

[Service]
ExecStart=/usr/local/bin/pangolin up --id {client_id} --secret {client_secret} --endpoint {endpoint_url} --attach
Restart=always
User=root

[Install]
WantedBy=multi-user.target
Make sure to move the binary to /usr/local/bin/pangolin before creating the service. Replace {client_id}, {client_secret}, and {endpoint_url} with your machine client credentials and endpoint.

​
Docker (Pangolin CLI)

You can run Pangolin CLI with Docker Compose. For example, a service in your docker-compose.yml might look like this using environment variables (recommended): 
services:
  pangolin-cli:
    image: fosrl/pangolin-cli:latest
    container_name: pangolin-cli
    restart: unless-stopped
    network_mode: host
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    environment:
      - PANGOLIN_ENDPOINT=https://app.pangolin.net
      - CLIENT_ID=5n52gnzfgl3tdox
      - CLIENT_SECRET=wyael1dhftekp0ii2ni0ym6xczwjnwmucy2vr6u9kgkp8tw9
You can also pass the CLI args to the container: 
services:
  pangolin-cli:
    image: fosrl/pangolin-cli:latest
    container_name: pangolin-cli
    restart: unless-stopped
    network_mode: host
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    command:
      - up
      - --id
      - "5n52gnzfgl3tdox"
      - --secret
      - "wyael1dhftekp0ii2ni0ym6xczwjnwmucy2vr6u9kgkp8tw9"
      - --endpoint
      - https://app.pangolin.net
      - --attach
Docker Configuration Notes:
  • network_mode: host brings the Pangolin CLI network interface to the host system, allowing the WireGuard tunnel to function properly
  • cap_add: - NET_ADMIN is required to grant the container permission to manage network interfaces
  • devices: - /dev/net/tun:/dev/net/tun is required to give the container access to the TUN device for creating WireGuard interfaces

​
Olm (Advanced)

Olm CLI is the most basic form of a client. All other clients implement Olm under the hood in some form.If you’re looking for a CLI interface for a client, we recommend using Pangolin CLI where possible.Olm CLI is mainly only used for machine clients. Though the Pangolin CLI can also be used for machine clients, use Pangolin CLI if you expect to log in as a user.

​
Binary Installation (Linux)

Use this command to automatically install Olm. It detects your system architecture automatically and always pulls the latest version, adding Olm to your PATH:
curl -fsSL https://static.pangolin.net/get-olm.sh | bash

​
Windows

If you would like to use Olm on Windows, wintun.dll is required. Please use latest installer from GitHub releases.

​
Manual Download

Binaries for Linux, macOS, and Windows are available in the GitHub releases for ARM and AMD64 (x86_64) architectures.Download and install manually:
wget -O olm "https://github.com/fosrl/olm/releases/download/{version}/olm_{architecture}" && chmod +x ./olm
Replace {version} with the desired version and {architecture} with your architecture. Check the release notes for the latest information.

​
Running Olm

Run Olm with the configuration from Pangolin:
olm \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com

​
Systemd Service

Create a basic systemd service:
/etc/systemd/system/olm.service
[Unit]
Description=Olm
After=network.target

[Service]
ExecStart=/usr/local/bin/olm --id 31frd0uzbjvp721 --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 --endpoint https://example.com
Restart=always
User=root

[Install]
WantedBy=multi-user.target
Make sure to move the binary to /usr/local/bin/olm before creating the service!

​
Docker

You can also run it with Docker compose. For example, a service in your docker-compose.yml might look like this using environment vars (recommended):
services:
    olm:
        image: fosrl/olm
        container_name: olm
        restart: unless-stopped
        network_mode: host
        cap_add:
            - NET_ADMIN
        devices:
            - /dev/net/tun:/dev/net/tun
        environment:
            - PANGOLIN_ENDPOINT=https://example.com
            - OLM_ID=31frd0uzbjvp721
            - OLM_SECRET=h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
You can also pass the CLI args to the container:
services:
    olm:
        image: fosrl/olm
        container_name: olm
        restart: unless-stopped
        network_mode: host
        cap_add:
            - NET_ADMIN
        devices:
            - /dev/net/tun:/dev/net/tun
        command:
            - --id 31frd0uzbjvp721
            - --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
            - --endpoint https://example.com
Docker Configuration Notes:
  • network_mode: host brings the olm network interface to the host system, allowing the WireGuard tunnel to function properly
  • cap_add: - NET_ADMIN is required to grant the container permission to manage network interfaces
  • devices: - /dev/net/tun:/dev/net/tun is required to give the container access to the TUN device for creating WireGuard interfaces

​
Windows Service

On Windows, olm has to be installed and run as a Windows service. When running it with the cli args, it will attempt to install and run the service to function like a cli tool.Minimum Windows version: Windows 10

​
Service Management Commands

# Install the service
olm.exe install

# Start the service
olm.exe start

# Stop the service
olm.exe stop

# Check service status
olm.exe status

# Remove the service
olm.exe remove

# Run in debug mode (console output) with our without id & secret
olm.exe debug

# Show help
olm.exe help
Note running the service requires credentials in %PROGRAMDATA%\olm\olm-client\config.json.

​
Service Configuration

When running as a service, Olm will read configuration from environment variables or you can modify the service to include command-line arguments:
  1. Install the service: olm.exe install
  2. Set the credentials in %PROGRAMDATA%\olm\olm-client\config.json. Hint: if you run olm once with —id and —secret this file will be populated!
  3. Start the service: olm.exe start

​
Service Logs

When running as a service, logs are written to:
  • Windows Event Log (Application log, source: “OlmWireguardService”)
  • Log files in: %PROGRAMDATA%\olm\logs\olm.log
You can view the Windows Event Log using Event Viewer or PowerShell:
Get-EventLog -LogName Application -Source "OlmWireguardService" -Newest 10

​
Gotchas

Olm creates a native tun interface. This usually requires sudo / admin permissions. Some notes:
  • Windows: Olm will run as a service. You can use the commands described Configure Client to manage it. You can use this to run it in the background if needed!
  • LXC containers: Need to be configured to allow tun access. On Proxmox see below.
  • Linux: May require root privileges or specific capabilities to create tun interfaces.
  • macOS: May require additional permissions for network interface creation.

​
LXC Proxmox

  1. Create your LXC container.
  2. Go to the Resources tab of the container.
  3. Select Add. Then select Device Passthrough.
  4. On the Add Device prompt, enter dev/net/tun in the Device Path field and select Add.
  5. If the container is running, shut it down and start it up again.
Once /dev/net/tun is available, the olm can run within the LXC.