Skip to content

enhance(clients): Better user and machine seperation #85

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
LaurenceJJones wants to merge 10 commits into
base: main
Choose a base branch
from
Draft

enhance(clients): Better user and machine seperation #85

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
92c10ae
docs: add machine client guides
LaurenceJJones Mar 23, 2026
e344b32
docs: reduce machine client scope
LaurenceJJones Mar 23, 2026
f3edc2c
docs: restore olm guidance on install clients
LaurenceJJones Mar 23, 2026
717b4d3
docs: split client install paths by usage
LaurenceJJones Mar 23, 2026
c7f3230
docs: refine client install navigation and structure
LaurenceJJones Mar 23, 2026
161cec5
docs: restore docker command example
LaurenceJJones Mar 23, 2026
e03a7b7
docs: restore docker configuration notes
LaurenceJJones Mar 23, 2026
7cdec21
docs: merge docker notes and gotchas
LaurenceJJones Mar 23, 2026
5cda811
docs(clients): preserve legacy install anchors
LaurenceJJones Mar 23, 2026
dd724d5
docs(clients): remove redundant install guidance
LaurenceJJones Mar 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 66 additions & 45 deletions manage/clients/install-client.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,12 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";

<PangolinCloudTocCta />

Clients are used in two different ways:

- **User Devices**: A person signs in with a Pangolin account or identity provider and connects from a desktop or mobile client.
- **Automation and Machines**: A server, workload, or script connects with a client ID and secret instead of an interactive login.

## User Devices


## Windows
Expand Down Expand Up @@ -113,14 +119,14 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";

Tap the Connect button to establish a VPN connection. On the first connection, you may be prompted to allow the VPN connection.

<span id="pangolin-cli-linux" />
Copy link
Copy Markdown
Member Author

@LaurenceJJones LaurenceJJones Mar 23, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

currently broken link from application, added a span so link can work again or we update codebase


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


### Quick Install (Recommended) — Linux and macOS

Expand Down Expand Up @@ -167,31 +173,45 @@ Replace `{version}` with the desired version and `{architecture}` with your arch

3. **Start Pangolin**

When logged in as a Pangolin user, connect by running:
Connect Pangolin by running:

```bash
pangolin up
```

To launch a machine client without logging in, use your client credentials:
## Automation and Machines

```bash
pangolin up --id {client_id} --secret {client_secret} --endpoint {endpoint_url} --attach
```
Use this path when the client is a server, CI job, background service, or other non-human workload.

These clients do not log in with a Pangolin account. They connect with:

- `endpoint`
- `id`
- `secret`

You can run automation and machine clients with either Pangolin CLI or Olm.

### Pangolin CLI for Automation and Machines

Install Pangolin CLI:

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

<Tip>
The `--attach` flag runs the client in the foreground instead of spawning it as a background process.
</Tip>
Start the machine client with its generated credentials:

Pangolin CLI can be installed as a systemd service or run in a container. See the sections below for advanced setups.
```bash
pangolin up --id {client_id} --secret {client_secret} --endpoint {endpoint_url} --attach
```

### Systemd Service (Pangolin CLI)
`--attach` keeps the process in the foreground, which is useful for validation and debugging.

Create a basic systemd service for Pangolin CLI:
#### Run as a Service

```ini title="/etc/systemd/system/pangolin-cli.service"
[Unit]
Description=Pangolin CLI
Description=Pangolin machine client
After=network.target

[Service]
Expand All @@ -207,15 +227,12 @@ 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.
</Warning>

### 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):
#### Run in Docker

```yaml
services:
pangolin-cli:
image: fosrl/pangolin-cli:latest
container_name: pangolin-cli
restart: unless-stopped
network_mode: host
cap_add:
Expand All @@ -224,11 +241,11 @@ services:
- /dev/net/tun:/dev/net/tun
environment:
- PANGOLIN_ENDPOINT=https://app.pangolin.net
- CLIENT_ID=5n52gnzfgl3tdox
- CLIENT_SECRET=wyael1dhftekp0ii2ni0ym6xczwjnwmucy2vr6u9kgkp8tw9
- CLIENT_ID=your-client-id
- CLIENT_SECRET=your-client-secret
```

You can also pass the CLI args to the container:
You can also pass the CLI args directly to the container:

```yaml
services:
Expand All @@ -244,19 +261,20 @@ services:
command:
- up
- --id
- "5n52gnzfgl3tdox"
- "your-client-id"
- --secret
- "wyael1dhftekp0ii2ni0ym6xczwjnwmucy2vr6u9kgkp8tw9"
- "your-client-secret"
- --endpoint
- https://app.pangolin.net
- --attach
```

**Docker Configuration Notes:**
#### Docker 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
- `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.
- If connectivity fails, verify the `endpoint`, `id`, and `secret` first.

## Olm (Advanced)

Expand All @@ -280,11 +298,11 @@ 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](https://github.com/fosrl/olm/releases/latest).
If you would like to use Olm on Windows, `wintun.dll` is required. Please use the latest installer from [GitHub releases](https://github.com/fosrl/olm/releases/latest).

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

Expand Down Expand Up @@ -326,12 +344,14 @@ WantedBy=multi-user.target
```

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

<span id="docker-pangolin-cli" />

### 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):
You can also run Olm with Docker Compose:

```yaml
services:
Expand Down Expand Up @@ -371,19 +391,19 @@ services:

**Docker Configuration Notes:**

- `network_mode: host` brings the olm network interface to the host system, allowing the WireGuard tunnel to function properly
- `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.
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

```
```text
# Install the service
olm.exe install

Expand All @@ -399,7 +419,7 @@ olm.exe status
# Remove the service
olm.exe remove

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

# Show help
Expand All @@ -413,15 +433,15 @@ Note running the service requires credentials in `%PROGRAMDATA%\olm\olm-client\c
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!
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`
- 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:

Expand All @@ -431,20 +451,21 @@ Get-EventLog -LogName Application -Source "OlmWireguardService" -Newest 10

### Gotchas

Olm creates a native tun interface. This usually requires sudo / admin permissions. Some notes:
Olm creates a native TUN interface. This usually requires sudo or admin permissions.

- **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. On Proxmox see below.
- **Linux**: May require root privileges or specific capabilities to create tun interfaces.
- **Windows**: Olm runs as a service.
- **LXC containers**: Need to be configured to allow TUN access.
- **Linux**: May require root privileges or specific capabilities to create network 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.
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.
Once `/dev/net/tun` is available, Olm can run within the LXC.

</Accordion>
6 changes: 2 additions & 4 deletions manage/clients/understanding-clients.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,20 +13,18 @@ A client is a way to access resources on sites remotely and privately via a virt

By default a client does not have access to any hosts on the local network of the site. Admins must explicitly define resources on the site and give specific users and roles access to the resources.

Users must log in and connect from a Pangolin client available on [Windows, Mac, Linux, iOS/iPadOS, and Android](/manage/clients/install-client). Machines (automated systems and servers) connect with an ID and secret.

## Client Types

There are two types of clients: user devices and machines.

<CardGroup cols={2}>
<Card title="User Devices">
<Card title="User Devices" href="/manage/clients/install-client#user-devices">
- Associated with a user in your Pangolin organization
- Requires login to connect (password, 2fa, etc)
- Available for download on Mac, Windows, and Linux
</Card>

<Card title="Machines">
<Card title="Machines" href="/manage/clients/install-client#automation-and-machines">
- Represent a server or automated system instead of a user
- Connect with an ID and secret
- Available in CLI form with Pangolin CLI
Expand Down