Introduction & Architecture
What Pangolin is, how its components fit together, the four deployment modes, and why a RamNode KVM VPS is the ideal home for it.
Want a condensed, single-page walkthrough? See the Pangolin Quick-Start Guide for a streamlined setup.
If you've ever tried to expose a self-hosted service to the internet — a Nextcloud instance, a home dashboard, a private app — you've probably hit at least one of these walls: your ISP puts you behind CGNAT, your router won't cooperate with port forwarding, or you just don't want your home IP exposed in DNS for the world to see.
Pangolin solves the same problem as Cloudflare Tunnels without giving anything up. It's a fully self-hosted, open-source, identity-aware tunneled reverse proxy built on WireGuard. You run it on a VPS and it becomes the public-facing entry point for all your private services.
The Problem Pangolin Solves
Traditional self-hosting requires either:
- Open ports on your home router — exposing your residential IP, dependent on your ISP allowing inbound connections
- A standard VPS reverse proxy — works if the app is already on the VPS, but doesn't help if your data lives elsewhere
- Traditional VPN — gives you access to your network but requires opening ports and configuring firewall rules on the private side
Pangolin takes a different approach. The VPS runs the control plane and public gateway. Your private server runs Newt, which initiates an outbound WireGuard tunnel. No inbound ports need to be open on your private network.
The Pangolin Stack
Pangolin is made up of several components, all named after burrowing (fossorial) animals:
1Pangolin (Core)
The main application: web dashboard, API, user management, access control, organization and resource configuration. Handles authentication, RBAC, identity provider integration, and routing rules.
2Gerbil
A WireGuard interface management server written in Go. Handles the WireGuard interface lifecycle — creating interfaces, managing peers, and handling the tunneling. Communicates with Pangolin via HTTP API.
3Traefik
The industry-standard reverse proxy that serves traffic. Handles TLS termination, automatic SSL via Let's Encrypt, and HTTP routing. Pangolin dynamically configures Traefik as resources are created and removed.
4Newt
The lightweight site connector installed on your private networks. Initiates the WireGuard tunnel back to Gerbil on your VPS. Runs on anything — a Raspberry Pi, a home server, a Docker host. Requires no inbound firewall rules.
How They Fit Together
Internet
|
v
RamNode VPS (your Pangolin server)
+-- Traefik (port 80/443) - TLS termination, HTTP routing
+-- Pangolin (dashboard, API, access control)
+-- Gerbil (WireGuard endpoint, port 51820 UDP)
|
| WireGuard tunnel (outbound from Newt)
|
Private network (home lab, remote server, etc.)
+-- Newt (tunnel connector, no inbound ports needed)
+-- Your apps (Nextcloud, Jellyfin, Gitea, etc.)Deployment Modes
Mode 1: Standard Tunneled Reverse Proxy
The most common setup. Pangolin + Gerbil + Traefik on your VPS, Newt on your private network(s). All web traffic flows through the VPS and gets tunneled to private services.
Best for: Home lab exposure, bypassing CGNAT, remote access to internal apps.
Mode 2: Standard Reverse Proxy (No Tunneling)
Pangolin runs without Gerbil as a standard reverse proxy with access control. Services must be directly reachable from the VPS.
Best for: Applications already running on your VPS that need identity-aware access control.
Mode 3: Client-Based Private Access
Direct client connections to private resources (SSH, databases, RDP, entire network ranges). Users install the Pangolin client on their device.
Best for: Replacing a traditional VPN for teams, granting developers database access.
Mode 4: Multi-Site Organization
Multiple private networks connected to a single Pangolin server. Each site has its own Newt instance with unified access control.
Best for: MSPs, businesses with distributed offices, homelab sprawl across locations.
Licensing
Pangolin is dual-licensed:
- AGPL-3.0 — the core open-source license
- Fossorial Commercial License — free for personal/hobbyist use and businesses under $100K USD annual revenue
For most RamNode users — homelabbers, indie developers, small teams — the free tier covers everything in this series.
Why RamNode Is a Good Fit
Pangolin's VPS requirements are modest. The control plane runs comfortably on 1 vCPU and 1 GB RAM for personal use. The VPS acts as a gateway and access control layer, not a compute host.
⚠️ KVM vs. OpenVZ
Gerbil uses WireGuard, which requires kernel-level support. RamNode's KVM VPS instances have full kernel support and are the recommended choice for Pangolin deployments that include tunneling. OpenVZ containers depend on the host node's kernel. For pure reverse proxy mode without tunneling, any VPS type works.
Recommended Specs
| Use Case | CPU | RAM | Notes |
|---|---|---|---|
| Personal / small team | 1 vCPU | 1–2 GB | 1–5 sites, under 20 users |
| Team use | 2 vCPU | 2–4 GB | Multiple sites, 20–50 users |
Choose datacenter location based on proximity to your users, not your private servers (traffic routes through the VPS).
What's in This Series
- Part 1 (this article): Architecture overview and VPS planning
- Part 2: VPS provisioning, DNS, firewall, and installation
- Part 3: Connecting private networks with Newt
- Part 4: Exposing web applications with HTTPS resources
- Part 5: Private resource access — SSH, databases, and RDP
- Part 6: Production hardening — SSO, CrowdSec, backups, and updates