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.

​
Pangolin CLI (Linux)

Pangolin CLI is the recommended way to run a client using a command line interface on Mac or Linux. Support for Windows is coming soon. 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

​
Manual Download

Binaries for Linux and macOS 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 Connect Pangolin by running: 
    pangolin up

​
Olm CLI

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.