Skip to main content

​
Open Source

Every layer of Pangolin is open source, from the control plane server through site connectors and end-user clients. Each component has its own repository under fosrl on GitHub; the component reference at the bottom of this page lists them. The software that powers Pangolin Cloud is open source as well. The SaaS control plane runs the same codebase as self-hosted Pangolin, and that code lives in the main fosrl/pangolin repository. Nothing described here is proprietary or hidden behind the managed service. Pangolin is split into a control plane (configuration, identity, and orchestration) and a data plane (encrypted tunnels, ingress, and relay). Sites and clients both initiate outbound connections to a Pangolin node, which keeps remote networks behind firewalls reachable without opening inbound ports on those networks. For a product-level walkthrough of sites, resources, and clients, see How Pangolin Works. This page focuses on how those pieces are implemented and how traffic moves through the system.
Pangolin system architecture diagram

High-level Pangolin architecture

​
Control Plane

The control plane is the Pangolin server application. It stores organization state in a database, exposes the dashboard and REST API, handles authentication and authorization, and pushes configuration to every node, site connector, and client in real time over WebSocket. Responsibilities include:
  • Policy and identity — users, roles, clients, machines, and access rules that determine which resources each principal can reach
  • Resource and site definitions — targets, destinations, routing preferences, certificates, and health-check configuration
  • Orchestration — coordinates tunnel peers, DNS records, and ingress routes as you create or change resources
  • Telemetry — connection state, relay status, and operational signals surfaced in the dashboard
You can run the control plane yourself (self-hosted) or use Pangolin Cloud, where the control plane is fully managed. In both cases, the same orchestration model applies: connectors and nodes pull config from the control plane rather than accepting inbound management connections.

​
Nodes

A node is the networking edge of your Pangolin deployment. It terminates inbound traffic from the public internet, manages WireGuard tunnels, and relays client traffic when a direct peer path is unavailable. On a self-hosted deployment, your Pangolin server runs as a single node by default. Enterprise clustering spreads multiple nodes behind a load balancer with shared database state. On Pangolin Cloud, you can add remote nodes: infrastructure you operate that still receives configuration from the cloud control plane. Each node runs several cooperating processes: The control plane writes certificates, Traefik router definitions, and WireGuard peer lists that these processes consume. Nodes do not need direct database access from site connectors; they only need reachability to the control plane and open listener ports on the public side.

DNS and port requirements

Required listener ports, firewall rules, and DNS records for a node.

Clustering for high availability

Multi-node Enterprise deployments with shared state and failover.

Remote nodes on Pangolin Cloud

Run your own node while using the cloud control plane for management.

​
Site Connectors

A site connector runs on a remote network (server, VM, container, or appliance) and maintains persistent outbound connections to a Pangolin node. It is the bridge between your private LAN and the platform. The primary connector implementation is Newt (codename). Newt opens:
  1. A WebSocket to the control plane for configuration, health, and coordination
  2. A WireGuard tunnel to the node’s tunnel manager (Gerbil) for encrypted data traffic
Site connectors are deny-by-default proxies. Deploying one does not expose hosts on the network; traffic is forwarded only for resources you define and grant access to. The connector resolves backend targets on the remote network and delivers packets there. Newt sites support the full feature set: public and private resources, protocol-aware proxies, multi-site routing, health checks, and edge TLS for private HTTP. Other connector types (local and basic WireGuard) exist for specialized self-hosted cases.

Understanding sites

Site types, deployment models, and connector capabilities.

​
Clients

Clients are endpoint agents on user devices or machines. They authenticate to the control plane, receive an access control list, and establish WireGuard tunnels so users can reach private resources. Two client classes share the same tunnel stack:
  • User devices — GUI apps on desktop and mobile; users sign in with their Pangolin identity or SSO
  • Machines — CLI clients for servers and automation; authenticate with an ID and secret

​
Shared client stack (Olm)

Every Pangolin client shares a common networking core called Olm (engineering codename). Olm holds the WireGuard tunnel logic, hole punching and relay negotiation, route installation, and DNS overrides that all clients rely on. Platform apps embed or invoke Olm rather than reimplementing that stack themselves. How Olm is hosted depends on the client:
  • macOS and iOS — Olm runs inside the platform’s network extension
  • Windows and Android — Olm runs as the tunnel service behind the native app
  • Pangolin CLI — spawns Olm as a subprocess and manages it over a local API
  • Olm CLI — exposes Olm directly for minimal machine-client deployments
Olm is an internal building block, not a product surface. Use the native clients built for each operating system for the best experience, support, and integration with OS networking APIs. Direct Olm usage is limited to advanced machine-client and automation scenarios; see Olm (Advanced) if you need that path. Once connected, the client installs routes for each authorized destination. Pangolin selects the correct site connector automatically; users connect to resources, not to sites directly. See multi-site routing for how failover works when a resource spans multiple connectors.

Understanding clients

User devices, machine clients, and how access is granted.

Install clients

Downloads for Mac, Windows, Linux, iOS, iPadOS, and Android.

​
Peer-to-Peer and Relay Paths

Client-to-site traffic does not always traverse your node. Pangolin negotiates the best available path for each tunnel.

​
Direct peer-to-peer (hole punching)

By default, the control plane coordinates NAT hole punching so a client and site connector can form a direct WireGuard peer connection. Traffic then flows client ↔ site without passing through the node’s relay layer. This path typically offers lower latency and less bandwidth use on the node.

​
Relay through the node

When hole punching fails (restrictive NAT, symmetric NAT, or blocked UDP), the client and site fall back to relaying through the node’s tunnel manager (Gerbil). Gerbil listens on UDP port 21820 by default, accepts the client’s WireGuard packets, and forwards them into the site connector’s existing tunnel. The connection stays encrypted end to end; only the network path changes. Site connectors use a separate default port (51820 UDP) for their outbound tunnels to the node. Relay is optional and can be disabled per client if you require direct paths only.

NAT traversal

Hole punching vs relay, how to check isRelay status, and tuning options.

​
Traffic Paths

Two dominant flows cover most deployments.

​
Inbound: public resources

Public resources accept traffic from the internet on your node’s ingress layer.
HTTP, HTTPS, SSH, RDP, and VNC public resources terminate authentication at the node before traffic enters the tunnel. TCP and UDP public resources bind to node ports and proxy raw traffic without an auth layer. Certificate issuance, router config, and access rules are all driven by the control plane.

Public resources

Protocol types, targets, and how ingress maps to backends.

​
Outbound: private resources via client

Private resources are reachable only when a client is connected and authorized.
The client installs routes for IP, CIDR, or FQDN destinations. The site connector resolves and delivers traffic on the remote LAN. For private HTTP, TLS can terminate at the connector so applications stay off the public internet entirely.

Private destinations

How IP, CIDR, FQDN, and alias destinations are resolved and routed.

​
Component Reference

Pangolin’s open-source repositories map to the roles above. Codenames are used throughout the codebase and deployment tooling. For local development setup and how these repositories interact in a dev environment, see Contributing.