How to Use Pangolin: The Beginner's Guide (First VPS, the Newt-Tunnel Rule, First Site, First Resource, and the Access-Control Lesson)
CodexFuse Team · 2026-10-31T23:51:03.578Z · 19 min read min read
How to use Pangolin, the self-hosted tunneled reverse proxy: the VPS and domain setup, the installer, the Newt outbound-tunnel rule, your first site and resource, Traefik routing with Let's Encrypt, and the access-control lesson that keeps services safe.
How to Use Pangolin: The Beginner's Guide (First VPS, the Newt-Tunnel Rule, First Site, First Resource, and the Access-Control Lesson)
Learning how to use Pangolin is the step that turns "I wish I could reach my homelab services from anywhere without renting access from a cloud company" into "I own my entire ingress path." Pangolin is a self-hosted, identity-aware tunneled reverse proxy: it sits on a small server you rent, accepts an outbound WireGuard tunnel from your home network, and puts your private services on the internet behind logins you control — with no port forwarding, no ISP permission, and no third-party tunnel in the middle. This pangolin tutorial — the pangolin for beginners guide the field is missing — walks the complete beginner arc in one place: the VPS and domain setup, the installer, the first-run dashboard setup, the Newt-tunnel rule that makes it all work, your first site, your first resource, Traefik routing with Let's Encrypt certificates, and the access-control lesson that keeps your services safe. Everything below was verified against the live Pangolin documentation, the Pangolin GitHub repository, and current release data, because the installer and the edition choices changed in 2026 and half the guides on the internet still describe the old ones.
You will do this in order: get a VPS with a public IP and a domain (this part is non-negotiable — the what is VPS hosting guide covers the sizing if you need it), open the right firewall ports, run the installer, finish the dashboard's first-run setup, create your first organization and site, install the Newt client on the machine you want to expose, publish your first resource, and lock it down with access control. If Docker is new to you, the Docker beginner guide covers the container basics the installer leans on. And if you are wondering how this compares with the mesh-VPN world, the Tailscale beginner guide and the Headscale beginner guide cover that lane — Pangolin is a different tool for a different job, and this guide draws the line between them.
What is Pangolin, exactly?
Pangolin is an open-source, identity-aware tunneled reverse proxy that lets you expose private services to the internet without opening inbound ports on your home network. A server component runs on a VPS you control; a small client called Newt runs on the machine hosting your service and dials OUT to that server over WireGuard; Traefik routes incoming requests to the right service; and every request passes through access control — logins, SSO, PINs, or temporary links — before it reaches anything. The project lives at github.com/fosrl/pangolin, carries roughly 23,300 stars, was created in September 2024, and is under aggressive active development (the latest release, v1.25.3, landed on October 23, 2026). The default license is AGPL-3.0, with a separate Fossorial Commercial License available for commercial tiers — the installer asks you to choose between the Community Edition and the Enterprise Edition up front, so you know which one you are running from the first minute.
- Rent a VPS with a public IP — Ubuntu 20.04+ or Debian 11+, 1GB of RAM minimum (2GB recommended), and SSH access. The outbound-tunnel trick removes your HOME network's ports, not the server: Pangolin still needs one machine on the public internet.
- Point your domain at it — create DNS A records for the dashboard and your future services (a wildcard A record works too), and open firewall ports 80/443 TCP plus 51820/21820 UDP.
- Run the installer —
curl -fsSL https://static.pangolin.net/get-installer.sh | bash, thensudo ./installer; answer the prompts (edition, base domain, dashboard domain, Let's Encrypt email, tunneling: yes) and let it pull the pangolin, gerbil, and traefik Docker images. - Finish the first-run setup — open the dashboard URL, paste the setup token from the Pangolin container logs, create your admin account, and create your first organization.
- Memorize the Newt-tunnel rule — the Newt client on your target machine dials OUT to your VPS over WireGuard, so services behind CGNAT, NAT, or a locked-down ISP router are reachable with zero port forwarding.
- Add your first site — a site is the place where a Newt client runs; the dashboard generates the Newt credentials for it.
- Run Newt on the target machine — as a Docker container, a standalone binary, or a systemd service, it connects out and registers the site.
- Publish your first resource — name the service, attach it to the site, give it a subdomain, and Pangolin routes it through Traefik with an automatic Let's Encrypt certificate.
- Lock it down with access control — choose who gets in: platform SSO, username and password, 2FA, a PIN, or a temporary share link — and keep admin dashboards and private services behind SSO at minimum.
- Check it from the outside — open the subdomain from a phone on mobile data and confirm the login gate appears before the service does.
How does Pangolin work? Meet the four parts
Pangolin is four pieces that each do one job, and understanding the split is what makes the rest of the guide click. The pangolin docker stack pulls all of them as containers, so you install once and get the whole architecture.
| Component | What it is | The one job it does |
|---|---|---|
| Pangolin (server) | The control plane and dashboard on your VPS | Holds your organizations, sites, resources, users, and access rules; serves the dashboard UI |
| Newt | The WireGuard client on the machine you want to expose | Dials OUT from your home network to the VPS — this is the tunnel; no inbound ports needed |
| Gerbil | The WireGuard interface manager on the VPS | Owns the server side of the tunnels — listens on UDP 51820 and holds the interface Newt connects to |
| Traefik | The reverse proxy on the VPS | Routes each subdomain to the right resource through the tunnel and fetches the Let's Encrypt certificates |
The mental model that sticks: think of Newt as a phone calling out from inside your network. Because the call originates from inside, your router's firewall — and even a carrier-grade NAT that gives you no public IP at all — simply lets the conversation happen. Traefik then answers the public doorbell at your VPS and hands each visitor down the right open phone line. That is the whole trick, and it is why the guides keep repeating that Pangolin is CGNAT-proof: nothing about the design requires the ISP to cooperate. Keeping the three moving parts straight is the real beginner skill: the pangolin newt client dials out, the pangolin gerbil manager holds the server-side tunnel interfaces, and the pangolin traefik router answers the public door — together they are what make Pangolin the serious self hosted cloudflare tunnel alternative for people who want to own the whole path.
What do you need before you install Pangolin?
You need three things: a VPS with a public IP address, a domain name you control, and the right ports open on the VPS firewall. Say this once, loudly: Pangolin does NOT run on your home network alone. The outbound tunnel eliminates port forwarding on the client side, but the server side still has to be reachable from the whole internet, and that means a rented server with a public IP. A small VPS costing a few dollars a month is the standard choice; the project's own documentation points you at a VPS guide if you need help choosing one.
On the server side, the official requirements are a Linux machine with root access and a public IP, Ubuntu 20.04+ or Debian 11+ for the smoothest install, and an email address for the Let's Encrypt certificates and the admin login. RamNode's deployment guide recommends at least 1GB of RAM with 2GB preferred — the stack is three containers plus Traefik, so the cheapest 512MB box will struggle. The installer supports both AMD64 and ARM64 architectures, so the popular ARM-based VPS deals work too.
| Port | Protocol | What it carries | Who needs it open |
|---|---|---|---|
| 80 | TCP | HTTP — Let's Encrypt challenges and redirects | The VPS firewall |
| 443 | TCP | HTTPS — everything your visitors see | The VPS firewall |
| 51820 | UDP | WireGuard tunnel — Gerbil's listening port | The VPS firewall |
| 21820 | UDP | WireGuard for tunneled clients | The VPS firewall (client side needs nothing inbound) |
DNS comes before the install, not after: create A records pointing your dashboard subdomain (and any service subdomains, or a wildcard for the whole zone) at the VPS's public IP, and give the records a few minutes to propagate. If your DNS lives behind Cloudflare's proxy, flip those records to DNS-only mode for the install — the orange-cloud proxy intercepts the traffic Pangolin needs to terminate itself, and the deployment guides are unanimous that this breaks the setup.
How do you install Pangolin on your VPS?
The pangolin install is a scripted installer that generates the Docker Compose files and starts three containers — pangolin, gerbil, and traefik — in about two to three minutes. Connect to your VPS over SSH, download the installer, and run it with root privileges:
curl -fsSL https://static.pangolin.net/get-installer.sh | bash
sudo ./installerMove the installer into the directory you want Pangolin to live in before running it — it places all of its files in the current directory. Then it walks you through the configuration prompts in order:
- Edition — choose Community Edition or Enterprise Edition (review the edition differences first; Community is the self-hosted default).
- Base domain — your root domain with no subdomain, e.g.
example.com. - Dashboard domain — press Enter to accept the default
pangolin.example.com, or type your own subdomain. - Let's Encrypt email — used for SSL certificates and the admin login.
- Tunneling — whether to install Gerbil for tunneled connections. The default is yes; say yes unless you specifically want Pangolin to act as a plain reverse proxy for services already on the VPS.
- Email (optional) — SMTP for notifications. The default is no, and the docs recommend leaving it off for the first install; you can add it later.
Confirm the install and the script pulls the Docker images and starts the containers with progress indicators. This is the step where the 2026 freshness matters: older tutorials describe a manual Docker Compose route or the beta-era installer_linux binary pinned to old releases — the static.pangolin.net installer is the current path, and the docs page describing it was updated on October 20, 2026, days before this guide was written.
How do you finish the first-run dashboard setup?
The installer ends by handing you a URL and a one-time setup token; the dashboard setup turns those into your admin account. Visit the URL the installer printed — https://<your-dashboard-domain>/auth/initial-setup — and do not panic if the browser shows a certificate warning on the very first load: the first Let's Encrypt certificate can take a few minutes to validate.
Get the setup token from the Pangolin container logs with sudo docker compose logs pangolin (run it in the install directory), paste the token into the setup page, enter your admin email, and set a strong password — this account has full system access, so treat it like the root password it effectively is. Then create your first organization: give it a name and description (something like "Home" or "Lab" is fine) and click create. The dashboard now shows the four areas you will live in: Sites, Resources, Users & Roles, and the analytics view.
What is the Newt-tunnel rule?
The Newt-tunnel rule is the one sentence that explains Pangolin: Newt always dials OUT, so nothing on your home network ever has to listen for inbound connections. This is what makes Pangolin a genuine self hosted Cloudflare Tunnel alternative rather than just another reverse proxy — Cloudflare Tunnel works the same outbound way, except there the tunnel lands on Cloudflare's servers and your traffic passes through their cloud. With Pangolin, the tunnel lands on YOUR VPS, and the entire ingress path is yours: your server, your certificates, your access rules, your logs.
Three practical consequences fall out of that sentence. First, CGNAT and locked routers stop mattering: if your ISP gives you a private address behind carrier-grade NAT, or your landlord's router has no port-forwarding page, Newt still connects because outbound HTTPS-like UDP traffic is what every NAT is designed to allow. Second, your home IP never appears in any public DNS record — visitors resolve your domain to the VPS, and the VPS alone faces the internet. Third, the attack surface of your home network does not grow: no ports opened, no firewall holes punched, no router admin pages exposed.
How do you add your first site and your first resource?
Sites and pangolin resources are Pangolin's two nouns, and beginners mix them up constantly — so here is the clean split. A site is a place: the machine (or network) where a Newt client runs, like your home server or your office box. A resource is a thing: a service you want to expose, like a media server, a dashboard, or a file browser, attached to a site. One site can carry many resources, and each resource gets its own subdomain and its own access rules.
Create the site first: in the dashboard, add a site under your organization and the dashboard generates the Newt credentials for it — an ID and a secret that identify this tunnel endpoint. Then run the Newt client on the target machine. Newt ships as a Docker container, a standalone binary, and a systemd-friendly native build, and community guides also run it as a Portainer stack; whichever form you pick, it takes the credentials from the dashboard, dials out to your VPS over WireGuard, and registers the site as online. You can confirm with docker ps | grep newt on a Docker install, or by watching the site flip to connected in the dashboard.
Now the resource: add a resource, attach it to the site, name it, point it at the service's internal IP and port (the address Newt can reach, like 192.168.1.50:8096), and give it a subdomain like media.example.com. Traefik picks up the new route automatically and fetches a Let's Encrypt certificate for it. One DNS habit saves headaches here: if you used a wildcard A record for your domain, new subdomains work instantly; if you created records manually, add an A record for each new resource subdomain and wait for propagation before testing.
How does Pangolin compare with Cloudflare Tunnel and Tailscale?
The pangolin vs cloudflare tunnel question and the pangolin vs tailscale question are the two comparisons every beginner asks, and they have clean answers because the three tools sit in different lanes. This guide covers all of them on this one page so you can pick once and commit.
| Question | Pangolin | Cloudflare Tunnel | Tailscale |
|---|---|---|---|
| What is it, in one line? | Self-hosted tunneled reverse proxy with identity-aware access control | Cloudflare's managed outbound tunnel to their edge network | Encrypted mesh VPN connecting your devices to each other |
| Who holds the tunnel endpoint? | Your VPS — you own the whole path | Cloudflare's cloud — your traffic passes through their infrastructure | Your own devices — peer-to-peer WireGuard, coordinated by Tailscale |
| How do visitors reach services? | Public subdomains on your domain, through Traefik, with per-resource login gates | Public hostnames on Cloudflare, with Cloudflare Access policies | Only devices on your tailnet — nothing is public by default |
| Best for… | Publishing homelab services publicly while owning the ingress and the identity layer | Publishing services publicly with zero servers to maintain | Private access between your own devices, no public exposure at all |
| The catch | You operate a VPS and keep Pangolin updated | You depend on Cloudflare's terms, limits, and routing | Sharing with non-technical users means managing their devices too |
Draw the line like this: if the goal is "anyone with the link can reach my service, behind a login I control, and I own the infrastructure," Pangolin is the tool. If the goal is "my services reachable with zero maintenance and I am fine with a cloud provider in the middle," Cloudflare Tunnel is the managed lane. If the goal is "only MY devices can reach my services, nothing public," Tailscale is the mesh-VPN lane — and if you want that mesh lane self-hosted, Headscale is its open-source control plane. The Caddy beginner guide covers the simpler alternative for the narrow case where your services already live ON the VPS itself and you just need a reverse proxy with automatic HTTPS — no tunnel required.
How do you lock down a resource with access control?
Exposing a service is only half the job; the access-control lesson is what keeps a beginner's Pangolin install from becoming a public incident. Pangolin is identity-aware, which means every request to a resource passes through authentication before it reaches the service — this is not an optional add-on, it is the product's core idea. When you create or edit a resource, you choose an authentication method, and the dashboard offers the full menu: platform SSO (the default, wired to your identity provider), username and password, a PIN, two-factor authentication, temporary share links, or disabled auth for genuinely public resources.
Set the policy per resource, not per server: your media library might get a temporary share link for a friend, your home-automation dashboard gets SSO with 2FA for family, and your Pangolin admin dashboard itself gets the strictest option you have. Keep user signups invite-only and disable open registration for private deployments — the installer-era guides all flag this, because an internet-facing dashboard with open signup is an invitation. Organizations and roles let you split access further: one organization for home, one for a side project, each with its own users and resources, so a credential issued for one never wanders into the other.
Two habits close the loop. First, expose only services you own and understand — a resource pointed at a service with its own weak default password is only as strong as that password, login gate or not. Second, check the audit side periodically: the dashboard's analytics and user views show who accessed what, which is how you notice the share link you forgot to expire. The security posture that makes Pangolin worth running is layered — tunnel, TLS, identity, least privilege — and access control is the layer you personally configure, so configure it deliberately.
What mistakes do beginners make with Pangolin?
| Mistake | Why it hurts | The fix |
|---|---|---|
| Installing with no VPS — trying to run it all at home | Nothing public can reach a server with no public IP; the tunnel has nowhere to land | Rent the VPS first — the tunnel removes home ports, not the server |
| Leaving Cloudflare's proxy (orange cloud) on | Cloudflare intercepts the TLS Pangolin must terminate itself; the install and certs break | Set the dashboard and resource records to DNS-only during setup |
| Forgetting UDP 51820/21820 on the VPS firewall | Newt cannot establish the WireGuard tunnel; sites stay offline while the dashboard looks fine | Open both UDP ports on the VPS; the client side needs nothing inbound |
| Skipping DNS before running the installer | Let's Encrypt validation fails and the dashboard loads with certificate warnings | Create the A records first and confirm propagation before installing |
| Pointing a resource at the wrong internal IP | Traefik routes perfectly to a service that is not there — blank page, no useful error | From the Newt machine, verify the service's LAN IP and port first (ping the target, then publish) |
| Leaving a resource on "auth disabled" by accident | A private service becomes a public one with no login gate | Default every resource to an auth method; reserve disabled-auth for intentionally public content |
| Following a 2025-era tutorial's install commands | Old guides pin retired binaries and the pre-Foundry-era compose flow; they break on current releases | Use the current static.pangolin.net installer and the live docs — v1.25.3 is the reference here |
Sources
Every fact in this guide was checked against a source fetched while writing it:
- Pangolin official docs — Quick Install Guide (docs.pangolin.net, updated 2026-10-20): the installer commands, the configuration prompts, the Docker images pulled, the setup-token flow, the port list, and the Community vs Enterprise edition choice.
- GitHub — fosrl/pangolin releases API (fetched this run): v1.25.3 published 2026-10-23, roughly 23,300 stars, repository created September 2024.
- GitHub — fosrl/pangolin LICENSE (fetched this run): AGPL-3.0 by default, with the Fossorial Commercial License available for commercial tiers.
- RamNode — Pangolin Tunneled Reverse Proxy Deployment Guide: VPS sizing (1GB minimum, 2GB recommended), the DNS table, the installer prompts, the auth methods (SSO, username-password, PIN, 2FA, temporary links), and the troubleshooting commands.
- devtoolbox.blog — Pangolin vs Cloudflare Tunnels (101 days old): the full VPS-to-first-resource flow and the own-your-ingress framing.
- XDA Developers — Replaced Cloudflare Tunnel with Pangolin: the weekend-project arc, Newt as a Portainer stack, the CGNAT-proof angle.
- darkwebinformer.com: the four-component explainer — Pangolin server, Newt WireGuard client, Gerbil interface manager, Traefik.
- bendiksens.net: the resource-creation and platform-SSO access-control arc.
- Unraid forums — Pangolin with Plex: VPS cost expectations, the wildcard A record approach, Cloudflare DNS-only mode, and the installer prompt walkthrough.
Frequently Asked Questions
Do I really need a VPS to use Pangolin?
Yes. The Newt tunnel eliminates port forwarding on your home network, but the server side of that tunnel has to live on a machine with a public IP address, and that means a rented VPS. A small one — 1GB of RAM minimum, 2GB recommended, running Ubuntu 20.04+ or Debian 11+ — is enough to start.
How is Pangolin different from just running Nginx or Caddy on my VPS?
A plain reverse proxy like Nginx or Caddy only helps services that already live on the VPS itself. Pangolin adds the tunnel: Newt dials out from machines anywhere — your home, an office, behind CGNAT — and Traefik routes public subdomains down those tunnels. If everything you want to expose already runs on the VPS, a simple reverse proxy is the lighter choice; the moment a service lives somewhere else, you need the tunnel.
Is Pangolin free?
The Community Edition is self-hosted and its code defaults to AGPL-3.0, so you can run it on your own VPS with only the server cost. The installer also offers an Enterprise Edition under the Fossorial Commercial License for commercial tiers. Check the current edition differences in the official docs before committing, since the packaging evolved through 2026.
Can my ISP block Pangolin?
Effectively no, for typical home ISPs. Newt initiates an outbound WireGuard connection (UDP 51820 to your VPS), which is exactly the kind of outbound traffic NAT routers are built to allow. That is why Pangolin works behind carrier-grade NAT and routers with no port-forwarding options. An ISP doing aggressive VPN blocking could interfere in theory, but the deployment guides treat that as an edge case, not the norm.
What happens if my home internet goes down?
Your public subdomains stop reaching the services behind the tunnel — Traefik on the VPS has no live path to route to — but the VPS, the dashboard, and anything running on the VPS itself stay up. When the home connection returns, Newt re-establishes the tunnel on its own and the resources come back without you touching anything.
