docs-v2/manage/clients/install-client.mdx

---
title: "Install Clients"
description: "Install native clients for Mac, Windows, and Linux"
---

## Windows

- [Pangolin for Windows Installer](https://pangolin.net/downloads/windows) - This is the official page to download the latest installer file for Windows.
- [All Versions](https://github.com/fosrl/windows/releases) - The releases section of this repository contains release notes and download artifacts for the latest version and all older versions.

## Mac

- [Pangolin for macOS Installer](https://pangolin.net/downloads/mac) - This is the official page to download the latest installer file for macOS.
- [All Versions](https://github.com/fosrl/apple/releases) - The releases section of this repository contains release notes and download artifacts for the latest version and all older versions.

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

### Quick Install (Recommended)

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:

```bash
curl -fsSL https://static.pangolin.net/get-cli.sh | bash
```

### Manual Download

Binaries for Linux and macOS are available in the [GitHub releases](https://github.com/fosrl/cli/releases) for ARM and AMD64 (x86_64) architectures.

Download and install manually:

```bash
wget -O pangolin "https://github.com/fosrl/cli/releases/download/{version}/pangolin-cli_{architecture}" && chmod +x ./pangolin
```

<Note>
Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/cli/releases) for the latest information.
</Note>

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

#### Quick Install (Recommended)

Use this command to automatically install Olm. It detects your system architecture automatically and always pulls the latest version, adding Olm to your PATH:

```bash
curl -fsSL https://static.pangolin.net/get-olm.sh | bash
```

#### Manual Download

Binaries for Linux, macOS, and Windows are available in the [GitHub releases](https://github.com/fosrl/olm/releases) for ARM and AMD64 (x86_64) architectures.

Download and install manually:

```bash
wget -O olm "https://github.com/fosrl/olm/releases/download/{version}/olm_{architecture}" && chmod +x ./olm
```

<Note>
Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/olm/releases) for the latest information.
</Note>

### Running Olm

Run Olm with the configuration from Pangolin:

```bash
olm \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com
```

### Permanent Installation

Install to your PATH (may need to run as root):

```bash
mv ./olm /usr/local/bin
```

<Note>
The quick installer will do this step for you.
</Note>

### Systemd Service

Create a basic systemd service:

```ini title="/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
```

<Warning>
Make sure to move the binary to `/usr/local/bin/olm` before creating the service!
</Warning>

### 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):

```yaml
services:
    olm:
        image: fosrl/olm
        container_name: olm
        restart: unless-stopped
        network_mode: host
        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:

```yaml
services:
    olm:
        image: fosrl/olm
        container_name: olm
        restart: unless-stopped
        network_mode: host
        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
- `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. You can also run the following:

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

```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](/manage/clients/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. See below.
- **Linux**: May require root privileges or specific capabilities to create tun interfaces.
- **macOS**: May require additional permissions for network interface creation.

#### LXC Container Configuration

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.