System Architecture

Open SourceCopy Anchor Link

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.

Pangolin is split into a control plane (configuration, identity, and orchestration) and a data plane (encrypted tunnels, ingress, and relay). For public resources, site connectors initiate outbound connections to a Pangolin node so the node can reverse-proxy traffic into the remote network without opening inbound ports there. For private resources, clients connect peer-to-peer to the site; the node is only in the data path as a relay when a direct path cannot be established. See Peer-to-Peer and Relay Paths.

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.

Control PlaneCopy Anchor Link

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.

NodesCopy Anchor Link

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.

Site ConnectorsCopy Anchor Link

A site connector runs on a remote network (server, VM, container, or appliance) and is the bridge between your private LAN and the platform. For public resources it maintains persistent outbound connections to a Pangolin node so ingress can reverse-proxy into the LAN. For private resources, clients form a peer-to-peer path to the connector; the node is only in that data path as a relay when hole punching fails.

The primary connector is a Pangolin Site. The site 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.

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

ClientsCopy Anchor Link

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)Copy Anchor Link

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

Peer-to-Peer and Relay PathsCopy Anchor Link

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)Copy Anchor Link

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 nodeCopy Anchor Link

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.

Traffic PathsCopy Anchor Link

Two dominant flows cover most deployments.

Inbound: public resourcesCopy Anchor Link

Public resources accept traffic from the internet on your node's ingress layer.

Internet → Node ingress (Traefik) → Auth (Badger) → Tunnel (Gerbil) → Site connector (Newt) → Backend target

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.

Outbound: private resources via clientCopy Anchor Link

Private resources are reachable only when a client is connected and authorized.

Client ↔ (direct peer or relay via Gerbil) ↔ Site connector (Newt) → Destination on remote network

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.

Component ReferenceCopy Anchor Link

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.